Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed docs/examples/data/genesis4.par.h5
Binary file not shown.
Binary file added docs/examples/data/genesis4/end.par.h5
Binary file not shown.
37 changes: 37 additions & 0 deletions docs/examples/data/genesis4/genesis4.in
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
&setup
rootname = genesis4
lattice = genesis4.lat
beamline = LAT
gamma0 = 1000.0
lambda0 = 1e-07
delz = 0.026
seed = 123456
npart = 128
&end

&time
slen = 7.175993210500245e-05
sample = 10
&end

# 100 pC
&profile_gauss
label = beamcurrent
c0 = 1000.0
s0 = 3.5879966052501225e-05
sig = 1.1959988684167075e-05
&end

&beam
gamma = 1000.0
delgam = 1.0
current = @beamcurrent
&end

&track
zstop = 1.0
&end

&write
beam=end
&end
2 changes: 2 additions & 0 deletions docs/examples/data/genesis4/genesis4.lat
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
D1: drift = {l=1.0};
LAT: LINE = {D1};
Binary file added docs/examples/data/genesis4/genesis4.out.h5
Binary file not shown.
1 change: 1 addition & 0 deletions docs/examples/data/genesis4/run.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
genesis4 genesis4.in
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

run.sh is missing a shebang and will rely on the caller invoking it with bash. Add #!/usr/bin/env bash (and optionally set -euo pipefail) to make it executable and less error-prone when used as a standalone script.

Copilot uses AI. Check for mistakes.
175 changes: 98 additions & 77 deletions docs/examples/read_examples.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -11,166 +11,187 @@
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:26.404727Z",
"iopub.status.busy": "2024-10-17T23:18:26.404338Z",
"iopub.status.idle": "2024-10-17T23:18:26.431800Z",
"shell.execute_reply": "2024-10-17T23:18:26.431113Z"
},
"tags": []
},
"outputs": [],
"source": [
"# Useful for debugging\n",
"%load_ext autoreload\n",
"%autoreload 2"
"from pmd_beamphysics import ParticleGroup\n",
"from pmd_beamphysics.interfaces.elegant import elegant_h5_to_data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# elegant hdf5 format"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This will convert to a data dict"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:26.434439Z",
"iopub.status.busy": "2024-10-17T23:18:26.434222Z",
"iopub.status.idle": "2024-10-17T23:18:27.006225Z",
"shell.execute_reply": "2024-10-17T23:18:27.005886Z"
},
"tags": []
},
"outputs": [],
"source": [
"from pmd_beamphysics import ParticleGroup"
"data = elegant_h5_to_data(\"data/elegant_raw.h5\")\n",
"data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# elegant hdf5 format"
"Create `ParticleGroup` and plot:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.007895Z",
"iopub.status.busy": "2024-10-17T23:18:27.007692Z",
"iopub.status.idle": "2024-10-17T23:18:27.018400Z",
"shell.execute_reply": "2024-10-17T23:18:27.018161Z"
},
"tags": []
},
"outputs": [],
"source": [
"from pmd_beamphysics.interfaces.elegant import elegant_h5_to_data"
"P = ParticleGroup(data=data)\n",
"P.plot(\"delta_t\", \"delta_pz\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This will convert to a data dict"
"# Genesis4 HDF5 format\n",
"\n",
"Genesis4 stores particles in `z` slices in its HDF5 file format. Each slice has a `z` length equal to the reference wavelength `lambda0`. In order to speed up the simulation, Genesis4 also has an integer parameter [`sample`](https://github.com/svenreiche/Genesis-1.3-Version4/blob/master/manual/MAIN_INPUT.md#time) that essentially skips adjacent slices, defined in the input file:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.019838Z",
"iopub.status.busy": "2024-10-17T23:18:27.019749Z",
"iopub.status.idle": "2024-10-17T23:18:27.038539Z",
"shell.execute_reply": "2024-10-17T23:18:27.038287Z"
},
"tags": []
},
"metadata": {},
"outputs": [],
"source": [
"data = elegant_h5_to_data(\"data/elegant_raw.h5\")\n",
"data"
"# Input\n",
"!cat data/genesis4/genesis4.in"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Lattice\n",
"!cat data/genesis4/genesis4.lat"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Create `ParticleGroup` and plot:"
"Running Genesis4 on this input (`genesis4 genesis4.in`) produces the raw particle file `end.par.h5` with slice particle."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.060724Z",
"iopub.status.busy": "2024-10-17T23:18:27.060588Z",
"iopub.status.idle": "2024-10-17T23:18:27.383511Z",
"shell.execute_reply": "2024-10-17T23:18:27.383284Z"
},
"tags": []
},
"metadata": {},
"outputs": [],
"source": [
"P = ParticleGroup(data=data)\n",
"P.plot(\"delta_t\", \"delta_pz\")"
"parfile = \"data/genesis4/end.par.h5\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Genesis4 HDF5 format"
"By default `ParticleGroup.from_genesis4` will load these particles relative to their slice position. Because `sample=10` we see a comb-like distribution:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.385069Z",
"iopub.status.busy": "2024-10-17T23:18:27.384959Z",
"iopub.status.idle": "2024-10-17T23:18:27.395330Z",
"shell.execute_reply": "2024-10-17T23:18:27.395103Z"
}
},
"metadata": {},
"outputs": [],
"source": [
"from pmd_beamphysics.interfaces.genesis import genesis4_par_to_data"
"P_default = ParticleGroup.from_genesis4(parfile)\n",
"P_default.plot(\"z\", \"pz\", bins=200)\n",
"P_default"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.396506Z",
"iopub.status.busy": "2024-10-17T23:18:27.396431Z",
"iopub.status.idle": "2024-10-17T23:18:27.491746Z",
"shell.execute_reply": "2024-10-17T23:18:27.491430Z"
}
},
"metadata": {},
"outputs": [],
"source": [
"P = ParticleGroup(data=genesis4_par_to_data(\"data/genesis4.par.h5\"))\n",
"# ParticleGroup has a `smear` option that shifts particles in each slice by a random integer multiple of the slice spacing, so that the overall distrubution is smoother while preserving the bunching characteristics:"
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo in notebook text: "distrubution" → "distribution".

Suggested change
"# ParticleGroup has a `smear` option that shifts particles in each slice by a random integer multiple of the slice spacing, so that the overall distrubution is smoother while preserving the bunching characteristics:"
"# ParticleGroup has a `smear` option that shifts particles in each slice by a random integer multiple of the slice spacing, so that the overall distribution is smoother while preserving the bunching characteristics:"

Copilot uses AI. Check for mistakes.
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"P_smear = ParticleGroup.from_genesis4(parfile, smear=True)\n",
"P_smear.plot(\"z\", \"pz\", bins=100)\n",
"P_smear"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Looking closer:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"P = P_default\n",
"P[(P.z > 30e-6) & (P.z < 35e-6)].plot(\"z\", \"pz\", bins=100)\n",
"P"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"execution": {
"iopub.execute_input": "2024-10-17T23:18:27.493261Z",
"iopub.status.busy": "2024-10-17T23:18:27.493141Z",
"iopub.status.idle": "2024-10-17T23:18:27.692929Z",
"shell.execute_reply": "2024-10-17T23:18:27.692655Z"
}
},
"metadata": {},
"outputs": [],
"source": [
"P = P_smear\n",
"P[(P.z > 30e-6) & (P.z < 35e-6)].plot(\"z\", \"pz\", bins=100)\n",
"P"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Normally Genesis4 populates the same number of particles in each slice, with each slice having its own weight (internally the `current`). In some cases it's simpler to have particles that have the same weight, so `ParticleGroup` further has an `equal_weights` option that samples particles from the slices according to the relative weights. Notice that there are fewer particles in this case, but that the projected densities are roughtly the same as above."
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo in notebook text: "roughtly" → "roughly".

Suggested change
"Normally Genesis4 populates the same number of particles in each slice, with each slice having its own weight (internally the `current`). In some cases it's simpler to have particles that have the same weight, so `ParticleGroup` further has an `equal_weights` option that samples particles from the slices according to the relative weights. Notice that there are fewer particles in this case, but that the projected densities are roughtly the same as above."
"Normally Genesis4 populates the same number of particles in each slice, with each slice having its own weight (internally the `current`). In some cases it's simpler to have particles that have the same weight, so `ParticleGroup` further has an `equal_weights` option that samples particles from the slices according to the relative weights. Notice that there are fewer particles in this case, but that the projected densities are roughly the same as above."

Copilot uses AI. Check for mistakes.
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"P.plot(\"z\", \"pz\")"
"P_equal = ParticleGroup.from_genesis4(parfile, smear=True, equal_weights=True)\n",
"P_equal.plot(\"z\", \"pz\", bins=100)\n",
"P_equal"
]
}
],
Expand All @@ -190,7 +211,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.7"
"version": "3.13.3"
}
},
"nbformat": 4,
Expand Down
Loading
Loading