diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst index 4edfe0d64..3a31c7da5 100644 --- a/docs/source/usage/parameters.rst +++ b/docs/source/usage/parameters.rst @@ -146,6 +146,82 @@ Lattice Elements Indicates the element type for this lattice element. This should be one of: +``aperture`` +^^^^^^^^^^^^ + +``aperture`` for a thin collimator element applying a transverse aperture boundary. +This requires these additional parameters: + +* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical or rectangular) +* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical or rectangular) +* ``.repeat_x`` (``float``, in meters) horizontal period for repeated aperture masking (inactive by default) +* ``.repeat_y`` (``float``, in meters) vertical period for repeated aperture masking (inactive by default) +* ``.shape`` (``string``) shape of the aperture boundary: ``rectangular`` (default) or ``elliptical`` +* ``.action`` (``string``) action of the aperture domain: ``transmit`` (default) or ``absorb`` +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``beam_monitor`` +^^^^^^^^^^^^^^^^ + +``beam_monitor`` a beam monitor, writing all beam particles at fixed ``s`` to openPMD files. +If the same element name is used multiple times, then an output series is created with multiple outputs. + +* ``.name`` (``string``, default value: ````) + + The output series name to use. + By default, output is created under ``diags/openPMD/.``. + +* ``.backend`` (``string``, default value: ``default``) + + `I/O backend `_ for `openPMD `_ data dumps. + ``bp`` is the `ADIOS2 I/O library `_, ``h5`` is the `HDF5 format `_, and ``json`` is a `simple text format `_. + ``json`` only works with serial/single-rank jobs. + By default, the first available backend in the order given above is taken. + +* ``.encoding`` (``string``, default value: ``g``) + + openPMD `iteration encoding `__: (v)ariable based, (f)ile based, (g)roup based (default) + variable based is an `experimental feature with ADIOS2 `__. + +* ``.period_sample_intervals`` (``int``, default value: ``1``) + + for periodic lattice, only output every Nth period (turn). + By default, diagnostics are returned every cycle. + +* ``.nonlinear_lens_invariants`` (``boolean``, default value: ``false``) + + Compute and output the invariants H and I within the nonlinear magnetic insert element (see: ``nonlinear_lens``). + Invariants associated with the nonlinear magnetic insert described by V. Danilov and S. Nagaitsev, PRSTAB 13, 084002 (2010), Sect. V.A. + + * ``.alpha`` (``float``, unitless) Twiss alpha of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. + Horizontal and vertical values must be equal. + + * ``.beta`` (``float``, meters) Twiss beta of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. + Horizontal and vertical values must be equal. + + * ``.tn`` (``float``, unitless) dimensionless strength of the IOTA nonlinear magnetic insert element used for computing H and I. + + * ``.cn`` (``float``, meters^(1/2)) scale factor of the IOTA nonlinear magnetic insert element used for computing H and I. + + +``buncher`` +^^^^^^^^^^^ + +``buncher`` for a short RF cavity (linear) bunching element. +This requires these additional parameters: + +* ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity + = (maximum voltage drop in Volts) / (speed of light in m/s * magnetic rigidity in T-m) +* ``.k`` (``float``, in 1/meters) the RF wavenumber + = 2*pi/(RF wavelength in m) +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + ``cfbend`` ^^^^^^^^^^ @@ -167,6 +243,37 @@ Lattice Elements * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) +``constf`` +^^^^^^^^^^ + +``constf`` for a constant focusing element. This requires these additional parameters: + +* ``.ds`` (``float``, in meters) the segment length +* ``.kx`` (``float``, in 1/meters) the horizontal focusing strength +* ``.ky`` (``float``, in 1/meters) the vertical focusing strength +* ``.kt`` (``float``, in 1/meters) the longitudinal focusing strength +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane +* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical) +* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical) +* ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) + + +``dipedge`` +^^^^^^^^^^^ + +``dipedge`` for dipole edge focusing. This requires these additional parameters: + +* ``.psi`` (``float``, in radians) the pole face rotation angle +* ``.rc`` (``float``, in meters) the bend radius +* ``.g`` (``float``, in meters) the gap size +* ``.K2`` (``float``, dimensionless) normalized field integral for fringe field +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + ``drift`` ^^^^^^^^^ @@ -211,6 +318,132 @@ This requires these additional parameters: * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) +``kicker`` +^^^^^^^^^^ + +``kicker`` for a thin transverse kicker. This requires these additional parameters: + +* ``.xkick`` (``float``, dimensionless OR in T-m) the horizontal kick strength +* ``.ykick`` (``float``, dimensionless OR in T-m) the vertical kick strength +* ``.unit`` (``string``) specification of units: ``dimensionless`` (default, in units of the magnetic rigidity of the reference particle) or ``T-m`` +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``line`` +^^^^^^^^ + +``line`` a sub-lattice (line) of elements to append to the lattice. + +* ``.elements`` (``list of strings``) optional (default: no elements) + A list of names (one name per lattice element), in the order that they appear in the lattice. + +* ``.reverse`` (``boolean``) optional (default: ``false``) + Reverse the list of elements in the line before appending to the lattice. + +* ``.repeat`` (``integer``) optional (default: ``1``) + Repeat the line multiple times before appending to the lattice. + Note: If ``reverse`` and ``repeat`` both appear, then ``reverse`` is applied before ``repeat``. + + +``linear_map`` +^^^^^^^^^^^^^^ + +``linear_map`` for a custom, linear transport matrix. + +The matrix elements :math:`R(i,j)` are indexed beginning with 1, so that :math:`i,j=1,2,3,4,5,6`. +The transport matrix :math:`R` is defaulted to the identity matrix, so only matrix entries that differ from that need to be specified. + +The matrix :math:`R` multiplies the phase space vector :math:`(x,px,y,py,t,pt)`, where coordinates :math:`(x,y,t)` have units of m +and momenta :math:`(px,py,pt)` are dimensionless. So, for example, :math:`R(1,1)` is dimensionless, and :math:`R(1,2)` has units of m. + +The internal tracking methods used by ImpactX are symplectic. However, if a user-defined linear map :math:`R` is provided, it is up to the user to ensure that the matrix :math:`R` is symplectic. Otherwise, this condition may be violated. + +This element requires these additional parameters: + +* ``.R(i,j)`` (``float``, ...) matrix entries + a 1-indexed, 6x6, linear transport map to multiply with the the phase space vector :math:`(x,p_x,y,p_y,t,p_t)`. +* ``.ds`` (``float``, in meters) length associated with a user-defined linear element (defaults to 0) +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``multipole`` +^^^^^^^^^^^^^ + +``multipole`` for a thin multipole element. +This requires these additional parameters: + +* ``.multipole`` (``integer``, dimensionless) order of multipole + (m = 1) dipole, (m = 2) quadrupole, (m = 3) sextupole, etc. + +* ``.k_normal`` (``float``, in 1/meters^m) integrated normal multipole coefficient (MAD-X convention) + = 1/(magnetic rigidity in T-m) * (derivative of order :math:`m-1` of :math:`B_y` with respect to :math:`x`) +* ``.k_skew`` (``float``, in 1/meters^m) integrated skew multipole strength (MAD-X convention) +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``nonlinear_lens`` +^^^^^^^^^^^^^^^^^^ + +``nonlinear_lens`` for a thin IOTA nonlinear lens element. +This requires these additional parameters: + +* ``.knll`` (``float``, in meters) integrated strength of the lens segment (MAD-X convention) + = dimensionless lens strength * c parameter**2 * length / Twiss beta +* ``.cnll`` (``float``, in meters) distance of the singularities from the origin (MAD-X convention) + = c parameter * sqrt(Twiss beta) +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``plane_xyrotation`` +^^^^^^^^^^^^^^^^^^^^ + +``plane_xyrotation`` for a rotation in the x-y plane (i.e., about the reference velocity vector). This requires these additional parameters: + +* ``.angle`` (``float``, in degrees) nominal angle of rotation +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``plasma_lens_chromatic`` +^^^^^^^^^^^^^^^^^^^^^^^^^ + +``plasma_lens_chromatic`` for an active cylindrically-symmetric plasma lens, with chromatic effects included. +The Hamiltonian is expanded through second order in the transverse variables :math:`(x,p_x,y,p_y)`, with the exact :math:`p_t` dependence retained. +This requires these additional parameters: + +* ``.ds`` (``float``, in meters) the segment length +* ``.k`` (``float``, in inverse meters squared OR in T/m) the plasma lens focusing strength + = (azimuthal magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if ``unit = 0`` + + OR = azimuthal magnetic field gradient in T/m - if ``unit = 1`` + +* ``.unit`` (``integer``) specification of units (default: ``0``) +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane +* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical) +* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical) +* ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) + + +``prot`` +^^^^^^^^ + +``prot`` for an exact pole-face rotation in the x-z plane. This requires these additional parameters: + +* ``.phi_in`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the original frame +* ``.phi_out`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame + + ``quad`` ^^^^^^^^ @@ -276,25 +509,25 @@ This requires these additional parameters: * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) -``plasma_lens_chromatic`` -^^^^^^^^^^^^^^^^^^^^^^^^^ +``rfcavity`` +^^^^^^^^^^^^ -``plasma_lens_chromatic`` for an active cylindrically-symmetric plasma lens, with chromatic effects included. -The Hamiltonian is expanded through second order in the transverse variables :math:`(x,p_x,y,p_y)`, with the exact :math:`p_t` dependence retained. +``rfcavity`` a radiofrequency cavity. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length -* ``.k`` (``float``, in inverse meters squared OR in T/m) the plasma lens focusing strength - = (azimuthal magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if ``unit = 0`` - - OR = azimuthal magnetic field gradient in T/m - if ``unit = 1`` - -* ``.unit`` (``integer``) specification of units (default: ``0``) +* ``.escale`` (``float``, in 1/m) scaling factor for on-axis RF electric field + = (peak on-axis electric field Ez in MV/m) / (particle rest energy in MeV) +* ``.freq`` (``float``, in Hz) RF frequency +* ``.phase`` (``float``, in degrees) RF driven phase +* ``.cos_coefficients`` (array of ``float``) cosine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ +* ``.cos_coefficients`` (array of ``float``) sine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ * ``.dx`` (``float``, in meters) horizontal translation error * ``.dy`` (``float``, in meters) vertical translation error * ``.rotation`` (``float``, in degrees) rotation error in the transverse plane * ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical) * ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical) +* ``.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) @@ -332,9 +565,30 @@ particle. This requires these additional parameters: * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) -``solenoid`` -^^^^^^^^^^^^ - +``shortrf`` +^^^^^^^^^^^ + +``shortrf`` for a short RF cavity element. +This requires these additional parameters: + +* ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity + = (maximum energy gain in MeV) / (particle rest energy in MeV) +* ``.freq`` (``float``, in Hz) the RF frequency +* ``.phase`` (``float``, in degrees) the synchronous RF phase + + ``phase = 0``: maximum energy gain (on-crest) + + ``phase = -90 deg``: zero energy gain for bunching + + ``phase = 90 deg``: zero energy gain for debunching +* ``.dx`` (``float``, in meters) horizontal translation error +* ``.dy`` (``float``, in meters) vertical translation error +* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane + + +``solenoid`` +^^^^^^^^^^^^ + ``solenoid`` for an ideal hard-edge solenoid magnet. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length @@ -373,90 +627,41 @@ particle. This requires these additional parameters: * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) -``dipedge`` -^^^^^^^^^^^ - -``dipedge`` for dipole edge focusing. This requires these additional parameters: - -* ``.psi`` (``float``, in radians) the pole face rotation angle -* ``.rc`` (``float``, in meters) the bend radius -* ``.g`` (``float``, in meters) the gap size -* ``.K2`` (``float``, dimensionless) normalized field integral for fringe field -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``constf`` -^^^^^^^^^^ +``tapered_pl`` +^^^^^^^^^^^^^^ -``constf`` for a constant focusing element. This requires these additional parameters: +``tapered_pl`` for a thin nonlinear plasma lens with transverse (horizontal) taper. -* ``.ds`` (``float``, in meters) the segment length -* ``.kx`` (``float``, in 1/meters) the horizontal focusing strength -* ``.ky`` (``float``, in 1/meters) the vertical focusing strength -* ``.kt`` (``float``, in 1/meters) the longitudinal focusing strength -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane -* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical) -* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical) -* ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) +.. math:: + B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right) -``rfcavity`` -^^^^^^^^^^^^ +where :math:`g` is the (linear) field gradient in T/m and :math:`D_x` is the targeted horizontal dispersion in m. -``rfcavity`` a radiofrequency cavity. This requires these additional parameters: -* ``.ds`` (``float``, in meters) the segment length -* ``.escale`` (``float``, in 1/m) scaling factor for on-axis RF electric field - = (peak on-axis electric field Ez in MV/m) / (particle rest energy in MeV) -* ``.freq`` (``float``, in Hz) RF frequency -* ``.phase`` (``float``, in degrees) RF driven phase -* ``.cos_coefficients`` (array of ``float``) cosine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ -* ``.cos_coefficients`` (array of ``float``) sine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane -* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical) -* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical) -* ``.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``) -* ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) - +* ``.k`` (``float``, in inverse meters OR in T) the integrated plasma lens focusing strength + = (length in m) * (magnetic field gradient :math:`g` in T/m) / (magnetic rigidity in T-m) - if ``unit = 0`` -``buncher`` -^^^^^^^^^^^ + OR = (length in m) * (magnetic field gradient :math:`g` in T/m) - if ``unit = 1`` -``buncher`` for a short RF cavity (linear) bunching element. -This requires these additional parameters: +* ``.unit`` (``integer``) specification of units (default: ``0``) +* ``.taper`` (``float``, in 1/meters) horizontal taper parameter + = 1 / (target horizontal dispersion :math:`D_x` in m) -* ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity - = (maximum voltage drop in Volts) / (speed of light in m/s * magnetic rigidity in T-m) -* ``.k`` (``float``, in 1/meters) the RF wavenumber - = 2*pi/(RF wavelength in m) * ``.dx`` (``float``, in meters) horizontal translation error * ``.dy`` (``float``, in meters) vertical translation error * ``.rotation`` (``float``, in degrees) rotation error in the transverse plane -``shortrf`` -^^^^^^^^^^^ +``thin_dipole`` +^^^^^^^^^^^^^^^ -``shortrf`` for a short RF cavity element. +``thin_dipole`` for a thin dipole element. This requires these additional parameters: -* ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity - = (maximum energy gain in MeV) / (particle rest energy in MeV) -* ``.freq`` (``float``, in Hz) the RF frequency -* ``.phase`` (``float``, in degrees) the synchronous RF phase - - ``phase = 0``: maximum energy gain (on-crest) - - ``phase = -90 deg``: zero energy gain for bunching - - ``phase = 90 deg``: zero energy gain for debunching +* ``.theta`` (``float``, in degrees) dipole bend angle +* ``.rc`` (``float``, in meters) effective radius of curvature * ``.dx`` (``float``, in meters) horizontal translation error * ``.dy`` (``float``, in meters) vertical translation error * ``.rotation`` (``float``, in degrees) rotation error in the transverse plane @@ -482,210 +687,6 @@ This requires these additional parameters: * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) -``linear_map`` -^^^^^^^^^^^^^^ - -``linear_map`` for a custom, linear transport matrix. - -The matrix elements :math:`R(i,j)` are indexed beginning with 1, so that :math:`i,j=1,2,3,4,5,6`. -The transport matrix :math:`R` is defaulted to the identity matrix, so only matrix entries that differ from that need to be specified. - -The matrix :math:`R` multiplies the phase space vector :math:`(x,px,y,py,t,pt)`, where coordinates :math:`(x,y,t)` have units of m -and momenta :math:`(px,py,pt)` are dimensionless. So, for example, :math:`R(1,1)` is dimensionless, and :math:`R(1,2)` has units of m. - -The internal tracking methods used by ImpactX are symplectic. However, if a user-defined linear map :math:`R` is provided, it is up to the user to ensure that the matrix :math:`R` is symplectic. Otherwise, this condition may be violated. - -This element requires these additional parameters: - -* ``.R(i,j)`` (``float``, ...) matrix entries - a 1-indexed, 6x6, linear transport map to multiply with the the phase space vector :math:`(x,p_x,y,p_y,t,p_t)`. -* ``.ds`` (``float``, in meters) length associated with a user-defined linear element (defaults to 0) -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``multipole`` -^^^^^^^^^^^^^ - -``multipole`` for a thin multipole element. -This requires these additional parameters: - -* ``.multipole`` (``integer``, dimensionless) order of multipole - (m = 1) dipole, (m = 2) quadrupole, (m = 3) sextupole, etc. - -* ``.k_normal`` (``float``, in 1/meters^m) integrated normal multipole coefficient (MAD-X convention) - = 1/(magnetic rigidity in T-m) * (derivative of order :math:`m-1` of :math:`B_y` with respect to :math:`x`) -* ``.k_skew`` (``float``, in 1/meters^m) integrated skew multipole strength (MAD-X convention) -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``nonlinear_lens`` -^^^^^^^^^^^^^^^^^^ - -``nonlinear_lens`` for a thin IOTA nonlinear lens element. -This requires these additional parameters: - -* ``.knll`` (``float``, in meters) integrated strength of the lens segment (MAD-X convention) - = dimensionless lens strength * c parameter**2 * length / Twiss beta -* ``.cnll`` (``float``, in meters) distance of the singularities from the origin (MAD-X convention) - = c parameter * sqrt(Twiss beta) -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``prot`` -^^^^^^^^ - -``prot`` for an exact pole-face rotation in the x-z plane. This requires these additional parameters: - -* ``.phi_in`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the original frame -* ``.phi_out`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame - - -``plane_xyrotation`` -^^^^^^^^^^^^^^^^^^^^ - -``plane_xyrotation`` for a rotation in the x-y plane (i.e., about the reference velocity vector). This requires these additional parameters: - -* ``.angle`` (``float``, in degrees) nominal angle of rotation -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - -``kicker`` -^^^^^^^^^^ - -``kicker`` for a thin transverse kicker. This requires these additional parameters: - -* ``.xkick`` (``float``, dimensionless OR in T-m) the horizontal kick strength -* ``.ykick`` (``float``, dimensionless OR in T-m) the vertical kick strength -* ``.unit`` (``string``) specification of units: ``dimensionless`` (default, in units of the magnetic rigidity of the reference particle) or ``T-m`` -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``thin_dipole`` -^^^^^^^^^^^^^^^ - -``thin_dipole`` for a thin dipole element. -This requires these additional parameters: - -* ``.theta`` (``float``, in degrees) dipole bend angle -* ``.rc`` (``float``, in meters) effective radius of curvature -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``aperture`` -^^^^^^^^^^^^ - -``aperture`` for a thin collimator element applying a transverse aperture boundary. -This requires these additional parameters: - -* ``.aperture_x`` (``float``, in meters) horizontal half-aperture (elliptical or rectangular) -* ``.aperture_y`` (``float``, in meters) vertical half-aperture (elliptical or rectangular) -* ``.repeat_x`` (``float``, in meters) horizontal period for repeated aperture masking (inactive by default) -* ``.repeat_y`` (``float``, in meters) vertical period for repeated aperture masking (inactive by default) -* ``.shape`` (``string``) shape of the aperture boundary: ``rectangular`` (default) or ``elliptical`` -* ``.action`` (``string``) action of the aperture domain: ``transmit`` (default) or ``absorb`` -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``tapered_pl`` -^^^^^^^^^^^^^^ - -``tapered_pl`` for a thin nonlinear plasma lens with transverse (horizontal) taper. - -.. math:: - - B_x = g \left( y + \frac{xy}{D_x} \right), \quad \quad B_y = -g \left(x + \frac{x^2 + y^2}{2 D_x} \right) - -where :math:`g` is the (linear) field gradient in T/m and :math:`D_x` is the targeted horizontal dispersion in m. - -This requires these additional parameters: - -* ``.k`` (``float``, in inverse meters OR in T) the integrated plasma lens focusing strength - = (length in m) * (magnetic field gradient :math:`g` in T/m) / (magnetic rigidity in T-m) - if ``unit = 0`` - - OR = (length in m) * (magnetic field gradient :math:`g` in T/m) - if ``unit = 1`` - -* ``.unit`` (``integer``) specification of units (default: ``0``) -* ``.taper`` (``float``, in 1/meters) horizontal taper parameter - = 1 / (target horizontal dispersion :math:`D_x` in m) - -* ``.dx`` (``float``, in meters) horizontal translation error -* ``.dy`` (``float``, in meters) vertical translation error -* ``.rotation`` (``float``, in degrees) rotation error in the transverse plane - - -``beam_monitor`` -^^^^^^^^^^^^^^^^ - -``beam_monitor`` a beam monitor, writing all beam particles at fixed ``s`` to openPMD files. -If the same element name is used multiple times, then an output series is created with multiple outputs. - -* ``.name`` (``string``, default value: ````) - - The output series name to use. - By default, output is created under ``diags/openPMD/.``. - -* ``.backend`` (``string``, default value: ``default``) - - `I/O backend `_ for `openPMD `_ data dumps. - ``bp`` is the `ADIOS2 I/O library `_, ``h5`` is the `HDF5 format `_, and ``json`` is a `simple text format `_. - ``json`` only works with serial/single-rank jobs. - By default, the first available backend in the order given above is taken. - -* ``.encoding`` (``string``, default value: ``g``) - - openPMD `iteration encoding `__: (v)ariable based, (f)ile based, (g)roup based (default) - variable based is an `experimental feature with ADIOS2 `__. - -* ``.period_sample_intervals`` (``int``, default value: ``1``) - - for periodic lattice, only output every Nth period (turn). - By default, diagnostics are returned every cycle. - -* ``.nonlinear_lens_invariants`` (``boolean``, default value: ``false``) - - Compute and output the invariants H and I within the nonlinear magnetic insert element (see: ``nonlinear_lens``). - Invariants associated with the nonlinear magnetic insert described by V. Danilov and S. Nagaitsev, PRSTAB 13, 084002 (2010), Sect. V.A. - - * ``.alpha`` (``float``, unitless) Twiss alpha of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. - Horizontal and vertical values must be equal. - - * ``.beta`` (``float``, meters) Twiss beta of the bare linear lattice at the location of output for the nonlinear IOTA invariants H and I. - Horizontal and vertical values must be equal. - - * ``.tn`` (``float``, unitless) dimensionless strength of the IOTA nonlinear magnetic insert element used for computing H and I. - - * ``.cn`` (``float``, meters^(1/2)) scale factor of the IOTA nonlinear magnetic insert element used for computing H and I. - - -``line`` -^^^^^^^^ - -``line`` a sub-lattice (line) of elements to append to the lattice. - -* ``.elements`` (``list of strings``) optional (default: no elements) - A list of names (one name per lattice element), in the order that they appear in the lattice. - -* ``.reverse`` (``boolean``) optional (default: ``false``) - Reverse the list of elements in the line before appending to the lattice. - -* ``.repeat`` (``integer``) optional (default: ``1``) - Repeat the line multiple times before appending to the lattice. - Note: If ``reverse`` and ``repeat`` both appear, then ``reverse`` is applied before ``repeat``. - - .. _running-cpp-parameters-collective: Collective Effects