Add new options to genesis4_par_to_data: wrap, z0, equal_weights, cut…

docs/examples/data/genesis4/genesis4.in

@@ -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

docs/examples/data/genesis4/genesis4.lat

@@ -0,0 +1,2 @@
+D1: drift = {l=1.0};
+LAT: LINE = {D1};

docs/examples/data/genesis4/run.sh

@@ -0,0 +1 @@
+genesis4 genesis4.in

docs/examples/read_examples.ipynb

@@ -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:"
+   ]
+  },
+  {
+   "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."
+   ]
+  },
+  {
+   "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"
    ]
   }
  ],
@@ -190,7 +211,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.13.3"
   }
  },
  "nbformat": 4,