.. _parameters-source: Input parameters ================ Parser ------ In HiPACE++ all input parameters are obtained through ``amrex::Parser``, making it possible to specify input parameters with expressions and not just numbers. User constants can be defined in the input script with ``my_constants``. .. code-block:: bash my_constants.ne = 1.25e24 my_constants.kp_inv = "clight / sqrt(ne * q_e^2 / (epsilon0 * m_e))" beam.radius = "kp_inv / 2" Thereby, the following constants are predefined: ============ ========================= ===================== **variable** **name** **Value** q_e elementary charge 1.602176634e-19 m_e electron mass 9.1093837139e-31 m_p proton mass 1.67262192595e-27 epsilon0 vacuum permittivity 8.8541878188e-12 mu0 vacuum permeability 1.2566370612685e-06 clight speed of light 299'792'458. hbar reduced Planck constant 1.0545718176461565e-34 r_e classical electron radius 2.8179403205e-15 ============ ========================= ===================== For a list of supported functions see the `AMReX documentation `__. Sometimes it is necessary to use double-quotes around expressions, especially when providing them as command line parameters. Multi-line expressions are allowed if surrounded by double-quotes. For input parameters of type ``string``, ``my_constants`` can be putinside curly braces ``{...}`` to directly paste them into the input parameter. If what is inside the braces is not a ``my_constants`` it will be evaluated as an expression using the parser. General parameters ------------------ * ``hipace.normalized_units`` (`bool`) optional (default `0`) Whether the simulation uses the normalized unit system commonly used in wakefield acceleration, see e.g. `chapter 2 of this reference `__. Otherwise, the code assumes SI (Système International) unit system. * ``random_seed`` (`integer`) optional (default `1`) Passes a seed to the AMReX random number generator. This allows for reproducibility of random events such as randomly generated beams, ionization, and collisions. Note that on GPU, since the order of operations is not ensured, providing a seed does not guarantee reproducibility to the level of machine precision. * ``use_previous_rng`` (`bool`) optional (default `0`) If set to `1`, the seed of the random number generator is computed as was done previous to `Pull Request 1081 `__. In particular, this seed depends on the number of ranks used for the simulation. If ``random_seed`` is specified, it takes precedence and ``use_previous_rng`` is not used. This option is off by default and should only be used for backward compatibility. * ``hipace.verbose`` (`int`) optional (default `0`) Level of verbosity. * ``hipace.verbose = 1``, prints only the time steps, which are computed. * ``hipace.verbose = 2`` additionally prints the number of iterations in the predictor-corrector loop, as well as the B-Field error at each slice. * ``hipace.verbose = 3`` also prints the number of particles that violate the quasi-static approximation and were neglected at each slice. It prints the number of ionized particles, if ionization occurred. It also adds additional information if beams are read in from file. * ``hipace.do_device_synchronize`` (`int`) optional (default `0`) Level of synchronization on GPU. * ``hipace.do_device_synchronize = 0``, synchronization happens only when necessary. * ``hipace.do_device_synchronize = 1``, synchronizes most functions (all that are profiled via ``HIPACE_PROFILE``) * ``amrex.the_arena_is_managed`` (`bool`) optional (default `0`) Whether managed memory is used. Note that large simulations sometimes only fit on a GPU if managed memory is used, but generally it is recommended to not use it. * ``amrex.omp_threads`` (``system``, ``nosmt`` or positive integer; default is ``nosmt``) An integer number can be set in lieu of the ``OMP_NUM_THREADS`` environment variable to control the number of OpenMP threads to use for the ``OMP`` compute backend on CPUs. By default, we use the ``nosmt`` option, which overwrites the OpenMP default of spawning one thread per logical CPU core, and instead only spawns a number of threads equal to the number of physical CPU cores on the machine. If set, the environment variable ``OMP_NUM_THREADS`` takes precedence over ``system`` and ``nosmt``, but not over integer numbers set in this option. * ``comms_buffer.on_gpu`` (`bool`) optional (default `0`) Whether the buffers that hold the beam and the 3D laser envelope should be allocated on the GPU (device memory). By default they will be allocated on the CPU (pinned memory). Setting this option to `1` is necessary to take advantage of GPU-Enabled MPI, however for this additional enviroment variables need to be set depending on the system. * ``comms_buffer.async_memcpy`` (`bool`) optional (default `1`) When using a GPU and setting ``comms_buffer.on_gpu = 0``, this option will allow the data transfer between the CPU and GPU for communications to be asynchronous instead of blocking. This can improve performance in a typical situation where the CPU-GPU link has relatively low bandwidth at the cost of some GPU memory and a reduced maximum number of MPI ranks. * ``comms_buffer.max_size_GiB`` (`float`) optional (default `inf`) How many Gibibytes of beam particles and laser slices can be stored in the communications buffer on each rank. This setting offers an alternative to ``comms_buffer.max_leading_slices`` and ``comms_buffer.max_trailing_slices``. Note that the amount specified here may be slightly exeeded in practice. If there are more time steps than ranks, this parameter must be chosen such that between all ranks there is enough capacity to store every beam particle and laser slice to avoid a deadlock, i.e. ``comms_buffer.max_size_GiB * nranks > beam_size + laser_size``. * ``comms_buffer.max_open_requests`` (`int`) optional (default `1000`) How many MPI requests may be open at the same time. Note that this is counted separately for each of the four different kinds of requests used. Must be set to at least two. Limiting the number of open requests is useful for simulations with many zeta slices (`>10000`) to reduce work for the MPI implementation. Note that setting the limit too low may result in a deadlock. * ``comms_buffer.max_leading_slices`` (`int`) optional (default `inf`) How many slices of beam particles can be received and stored in advance. * ``comms_buffer.max_trailing_slices`` (`int`) optional (default `inf`) How many slices of beam particles can be stored before being sent. Using ``comms_buffer.max_leading_slices`` and ``comms_buffer.max_trailing_slices`` will in principle limit the amount of asynchronousness in the parallel communication and may thus reduce performance. However it may be necessary to set these parameters to avoid all slices accumulating on a single rank that would run out of memory (out of CPU or GPU memory depending on ``comms_buffer.on_gpu``). If there are more time steps than ranks, these parameters must be chosen such that between all ranks there is enough capacity to store every slice to avoid a deadlock, i.e. ``comms_buffer.max_trailing_slices * nranks > nslices``. * ``comms_buffer.pre_register_memory`` (`bool`) optional (default `false`) On some platforms, such as JUWELS booster, the memory passed into MPI needs to be registered to the network card, which can take a long time. When using this option, all ranks can do this at once in initialization instead of one after another as part of the communication pipeline. * ``hipace.do_shared_depos`` (`bool`) optional (default `false`) Whether to use shared memory current deposition on GPU. * ``hipace.do_tiling`` (`bool`) optional (default `true`) Whether to use tiling, when running on CPU. Currently, this option only affects plasma operations (gather, push and deposition). The tile size can be set with ``hipace.tile_size``. * ``hipace.tile_size`` (`int`) optional (default `32`) Tile size for beam and plasma current deposition, when running on CPU and tiling is activated (``hipace.do_tiling = 1``). * ``hipace.depos_order_xy`` (`int`) optional (default `2`) Transverse particle shape order. Currently, `0,1,2,3` are implemented. * ``hipace.depos_order_z`` (`int`) optional (default `0`) Longitudinal particle shape order. Only affects the gathering of Ez for beam particles. Can be 0 or 2. * ``hipace.depos_derivative_type`` (`int`) optional (default `2`) Type of derivative used in explicit deposition. `0`: analytic, `1`: nodal, `2`: centered * ``hipace.do_beam_jx_jy_deposition`` (`bool`) optional (default `1`) Using the default, the beam deposits all currents ``Jx``, ``Jy``, ``Jz``. Using ``hipace.do_beam_jx_jy_deposition = 0`` disables the transverse current deposition of the beams. * ``hipace.do_beam_jz_minus_rho`` (`bool`) optional (default `0`) Whether the beam contribution to :math:`j_z-c\rho` is calculated and used when solving for Psi (used to caculate the transverse fields Ex-By and Ey+Bx). if 0, this term is assumed to be 0 (a good approximation for an ultra-relativistic beam in the z direction with small transverse momentum). * ``hipace.interpolate_neutralizing_background`` (`bool`) optional (default `0`) Whether the neutralizing background from plasmas should be interpolated from level 0 to higher MR levels instead of depositing it on all levels. * ``hipace.output_input`` (`bool`) optional (default `0`) Print all input parameters before running the simulation. If a parameter is present multiple times then the last occurrence will be used. Note that this will include some default AMReX parameters. * ``hipace.initial_time`` (`float`) optional (default `0.`) Initial time of the simulation. Can be used to start at a chosen location in a custom density profile or to overwrite the initial time set e.g. with the ``from_file`` option of beam initialization. * ``hipace.initial_step`` (`integer`) optional (default `0`) Initial step index of the simulation. Can be used to offset the iteration number of diagnostic output as well as the output period calculation when restarting a simulation. Should be used together with with ``hipace.initial_time``. * ``hipace.grid_external_fields(x,y,z,t)`` (5 `float`) optional (default `0. 0. 0. 0. 0.`) External fields applied to the field grid as a function of x, y, z and t. This will affect both beam and plasma particles, as well as the field diagnostics. The components represent Bx, By, Bz, Psi and Ez respectively. The plasma wake potential :math:`\Psi = \phi - cA_z` must satisfy :math:`\frac{d}{dx} \Psi = - (E_x - c B_y)` and :math:`\frac{d}{dy} \Psi = - (E_y + c B_x)`. Note that z refers to the location of the beam particle inside the moving frame of reference (zeta) and t to the physical time of the current time step. * ``hipace.ignore_noncritical_warnings`` (`bool`) optional (default `0`) Don't crash the simulation from assertions that check for suboptimal input parameters but are not needed for correctness. Geometry -------- * ``amr.n_cell`` (3 `integer`) Number of cells in x, y and z. With the explicit solver (default), the number of cells in the x and y directions must be either :math:`2^n-1` (common values are 511, 1023, 2047, best configuration for performance) or :math:`2^n` where :math:`n` is an integer. Some other values might work, like :math:`3 \times 2^n-1`, but use at your own risk. * ``amr.max_level`` (`integer`) optional (default `0`) Maximum level of mesh refinement. Currently, mesh refinement is supported up to level `2`. Note, that the mesh refinement algorithm is still in active development and should be used with care. * ``geometry.prob_lo`` (3 `float`) Lower end of the simulation box in x, y and z. * ``geometry.prob_hi`` (3 `float`) Higher end of the simulation box in x, y and z. * ``boundary.field`` (`string`) Type of boundary condition used to fill the ghost cells of the fields. Possible values: * ``Dirichlet`` The field value in ghost cells stays zero. * ``Periodic`` The field value in ghost cells is filled using periodic continuation of the domain. This option should usually be selected only in combination with periodic field solvers. * ``Open`` Uses a Taylor approximation of the Greens function to solve the Poisson equations with open boundary conditions. Only available with the predictor-corrector solver. * ``boundary.particle`` (`string`) Type of boundary condition used for particles. Possible values: * ``Reflecting`` Particles are reflected into the domain where they exited. * ``Periodic`` Particles enter the domain on the opposite side where they exit. * ``Absorbing`` Particles exiting the domain are deleted. * ``boundary.particle_lo`` (2 `float`) optional (default ``) The lower location of the domain boundary the particles experience. By default, this is equal to the boundary of the fields however it may be shrunk to reduce noise originating from the boundary, especially when using open boundary conditions. * ``boundary.particle_hi`` (2 `float`) optional (default ``) The upper location of the domain boundary the particles experience. See ``boundary.particle_lo``. * ``mr_lev1.n_cell`` (2 `integer`) Number of cells in x and y for level 1. The number of cells in the zeta direction is calculated from ``patch_lo`` and ``patch_hi``. * ``mr_lev1.patch_lo`` (3 `float`) Lower end of the refined grid in x, y and z. * ``mr_lev1.patch_hi`` (3 `float`) Upper end of the refined grid in x, y and z. * ``mr_lev1.ref_ratio`` (2 `float`) optional (default `0 0`) The refinement ratio of level 1 compared to level 0 in the x and y directions. If specified, ``patch_lo`` and ``patch_hi`` will be adjusted by up to 5% to match the requested refinement ratio. * ``mr_lev1.plasma_fine_patch`` (2 `float`) optional (default `0 0`) Enable a fine patch for all plasmas using the location and refinement ratio of level 1. The two parameters specify how large the diameter of the fine patch should be compared to the length of level 1. It is recommended to use at least ``1.5 1.5`` to include the corners. * ``mr_lev2.n_cell`` (2 `integer`) Number of cells in x and y for level 2. The number of cells in the zeta direction is calculated from ``patch_lo`` and ``patch_hi``. * ``mr_lev2.patch_lo`` (3 `float`) Lower end of the refined grid in x, y and z. * ``mr_lev2.patch_hi`` (3 `float`) Upper end of the refined grid in x, y and z. * ``mr_lev2.ref_ratio`` (2 `float`) optional (default `0 0`) The refinement ratio of level 2 compared to level 0 in the x and y directions. If specified, ``patch_lo`` and ``patch_hi`` will be adjusted by up to 5% to match the requested refinement ratio. * ``mr_lev2.plasma_fine_patch`` (2 `float`) optional (default `0 0`) Enable a fine patch for all plasmas using the location and refinement ratio of level 2. The two parameters specify how large the diameter of the fine patch should be compared to the length of level 2. It is recommended to use at least ``1.5 1.5`` to include the corners. * ``lasers.n_cell`` (2 `integer`) Number of cells in x and y for the laser grid. The number of cells in the zeta direction is calculated from ``patch_lo`` and ``patch_hi``. * ``lasers.patch_lo`` (3 `float`) Lower end of the laser grid in x, y and z. * ``lasers.patch_hi`` (3 `float`) Upper end of the laser grid in x, y and z. Time step --------- * ``max_step`` (`integer`) optional (default `0`) Maximum number of time steps. `0` means that the 0th time step will be calculated, which are the fields of the initial beams. * ``hipace.max_time`` (`float`) optional (default `infinity`) Maximum physical time of the simulation. The ``dt`` of the last time step may be reduced so that ``t + dt = max_time``, both for the adaptive and a fixed time step. * ``hipace.dt`` (`float` or `string`) optional (default `0.`) Time step to advance the particle beam. For adaptive time step, use ``"adaptive"``. * ``hipace.dt_max`` (`float`) optional (default `inf`) Only used if ``hipace.dt = adaptive``. Upper bound of the adaptive time step: if the computed adaptive time step is is larger than ``dt_max``, then ``dt_max`` is used instead. Useful when the plasma profile starts with a very low density (e.g. in the presence of a realistic density ramp), to avoid unreasonably large time steps. * ``hipace.nt_per_betatron`` (`Real`) optional (default `20.`) Only used when using adaptive time step (see ``hipace.dt`` above). Number of time steps per betatron period (of the full blowout regime). The time step is given by :math:`\omega_{\beta}\Delta t = 2 \pi/N` (:math:`N` is ``nt_per_betatron``) where :math:`\omega_{\beta}=\omega_p/\sqrt{2\gamma}` with :math:`\omega_p` the plasma angular frequency and :math:`\gamma` is an average of Lorentz factors of the slowest particles in all beams. * ``hipace.adaptive_predict_step`` (`bool`) optional (default `1`) Only used when using adaptive time step (see ``hipace.dt`` above). If true, the current Lorentz factor and accelerating field on the beams are used to predict the (adaptive) ``dt`` of the next time steps. This prediction is used to better estimate the betatron frequency at the beginning of the next step performed by the current rank. It improves accuracy for parallel simulations (with significant deceleration and/or z-dependent plasma profile). Note: should be on by default once good defaults are determined. * ``hipace.adaptive_control_phase_advance`` (`bool`) optional (default `1`) Only used when using adaptive time step (see ``hipace.dt`` above). If true, a test on the phase advance sets the time step so it matches the phase advance expected for a uniform plasma (to a certain tolerance). This should improve the accuracy in the presence of density gradients. Note: should be on by default once good defaults are determined. * ``hipace.adaptive_phase_tolerance`` (`Real`) optional (default `4.e-4`) Only used when using adaptive time step (see ``hipace.dt`` above) and ``adaptive_control_phase_advance``. Tolerance for the controlled phase advance described above (lower is more accurate, but should result in more time steps). * ``hipace.adaptive_phase_substeps`` (`int`) optional (default `2000`) Only used when using adaptive time step (see ``hipace.dt`` above) and ``adaptive_control_phase_advance``. Number of sub-steps in the controlled phase advance described above (higher is more accurate, but should be slower). * ``hipace.adaptive_threshold_uz`` (`Real`) optional (default `2.`) Only used when using adaptive time step (see ``hipace.dt`` above). Threshold beam momentum, below which the time step is not decreased (to avoid arbitrarily small time steps). Field solver parameters ----------------------- Two different field solvers are available to calculate the transverse magnetic fields `Bx` and `By`: an explicit solver (based on analytic integration) and a predictor-corrector loop (based on an FFT solver). In the explicit solver, the longitudinal derivative of the transverse currents is calculated explicitly, which results in a shielded Poisson equation, solved with either the internal HiPACE++ multigrid solver or the AMReX multigrid solver. The default is to use the explicit solver. **We strongly recommend to use the explicit solver**, because we found it to be more robust, faster to converge, and easier to use. * ``hipace.bxby_solver`` (`string`) optional (default `explicit`) Which solver to use. Possible values: ``explicit`` and ``predictor-corrector``. * ``fields.poisson_solver`` (`string`) optional (default CPU: `FFTDirichletDirectEven` or `FFTDirichletDirectOdd`, GPU: `FFTDirichletQuick` or `FFTDirichletFast`) Which Poisson solver to use for ``Psi``, ``Ez`` and ``Bz``. The ``predictor-corrector`` BxBy solver also uses this poisson solver for ``Bx`` and ``By`` internally. Available solvers are: * ``FFTDirichletDirectEven`` Use the discrete sine transformation that is directly implemented by FFTW to solve the Poisson equation with Dirichlet boundary conditions. This option is only available when compiling for CPUs with FFTW. Preferred resolution: :math:`2^N`. * ``FFTDirichletDirectOdd`` Use the discrete sine transformation that is directly implemented by FFTW to solve the Poisson equation with Dirichlet boundary conditions. This option is only available when compiling for CPUs with FFTW. Preferred resolution: :math:`2^N-1`. * ``FFTDirichletExpanded`` Perform the discrete sine transformation by symmetrically expanding the field to twice its size. Preferred resolution: :math:`2^N-1`. * ``FFTDirichletFast`` Perform the discrete sine transformation using a fast sine transform algorithm that uses FFTs of the same size as the fields. Preferred resolution: :math:`2^N-1`. * ``FFTDirichletQuick`` Similar to ``FFTDirichletFast`` but uses a different type of FFT that works better for even resolutions. Preferred resolution: :math:`2^N`. * ``MGDirichlet`` Use the HiPACE++ multigrid solver to solve the Poisson equation with Dirichlet boundary conditions. Preferred resolution: :math:`2^N` and :math:`2^N-1`. * ``FFTPeriodic`` Use FFTs to solve the Poisson equation with Periodic boundary conditions. Note that this does not work with features that change the boundary values, like mesh refinement or open boundaries. Preferred resolution: :math:`2^N`. * ``fields.do_symmetrize`` (`bool`) optional (default `0`) Symmetrizes current and charge densities transversely before the field solve. Each cell at (`x`, `y`) is averaged with cells at (`-x`, `y`), (`x`, `-y`) and (`-x`, `-y`). Explicit solver parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``hipace.use_amrex_mlmg`` (`bool`) optional (default `0`) Whether to use the AMReX multigrid solver. Note that this requires the compile-time option ``AMReX_LINEAR_SOLVERS`` to be true. Generally not recommended since it is significantly slower than the default HiPACE++ multigrid solver. * ``hipace.MG_tolerance_rel`` (`float`) optional (default `1e-4`) Relative error tolerance of the multigrid solvers. * ``hipace.MG_tolerance_abs`` (`float`) optional (default `0.`) Absolute error tolerance of the multigrid solvers. * ``hipace.MG_verbose`` (`int`) optional (default `0`) Level of verbosity of the the multigrid solvers. Predictor-corrector loop parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``hipace.predcorr_B_error_tolerance`` (`float`) optional (default `4e-2`) The tolerance of the transverse B-field error. Set to a negative value to use a fixed number of iterations. * ``hipace.predcorr_max_iterations`` (`int`) optional (default `30`) The maximum number of iterations in the predictor-corrector loop for single slice. * ``hipace.predcorr_B_mixing_factor`` (`float`) optional (default `0.05`) The mixing factor between the currently calculated B-field and the B-field of the previous iteration (or initial guess, in case of the first iteration). A higher mixing factor leads to a faster convergence, but increases the chance of divergence. .. note:: In general, we recommend two different settings: First, a fixed B-field error tolerance. This ensures the same level of convergence at each grid point. To do so, use e.g. the default settings of ``hipace.predcorr_B_error_tolerance = 4e-2``, ``hipace.predcorr_max_iterations = 30``, ``hipace.predcorr_B_mixing_factor = 0.05``. This should almost always give reasonable results. Second, a fixed (low) number of iterations. This is usually much faster than the fixed B-field error, but can loose significant accuracy in special physical simulation settings. For most settings (e.g. a standard PWFA simulation the blowout regime at a reasonable resolution) it reproduces the same results as the fixed B-field error tolerance setting. It works very well at high longitudinal resolution. A good setting for the fixed number of iterations is usually given by ``hipace.predcorr_B_error_tolerance = -1.``, ``hipace.predcorr_max_iterations = 1``, ``hipace.predcorr_B_mixing_factor = 0.15``. The B-field error tolerance must be negative. Plasma parameters ----------------- The name of all plasma species must be specified with `plasmas.names = ...`. Then, properties can be set per plasma species with ``. = ...``, or sometimes for all plasma species at the same time with ``plasmas. = ...``. When both are specified, the per-species value is used. * ``plasmas.names`` (`string`) optional (default `no_plasma`) The names of the plasmas, separated by a space. To run without plasma, choose the name ``no_plasma``. * `` or plasmas.density(x,y,z)`` (`float`) optional (default `0.`) The plasma density as function of `x`, `y` and `z`. `x` and `y` coordinates are taken from the simulation box and :math:`z = time \cdot c`. The density gets recalculated at the beginning of every timestep. If specified as a command line parameter, quotation marks must be added: ``".density(x,y,z)" = "1."``. * `` or plasmas.min_density`` (`float`) optional (default `0`) Particles with a density less than or equal to the minimal density won't be injected. Useful for parsed functions to avoid redundant plasma particles with close to 0 weight. * ``.density_table_file`` (`string`) optional (default "") Alternative to ``.density(x,y,z)``. Specify the name of a text file containing multiple densities for different positions. File syntax: `` `` for every line. If a line doesn't start with a position it is ignored (comments can be made with `#`). `` is evaluated like ``.density(x,y,z)``. The simulation position :math:`time \cdot c` is rounded up to the nearest `` in the file to get it's `` which is used for that time step. * `` or plasmas.read_density_from_path`` (`string`) optional (default "") Alternative to ``.density(x,y,z)``. Specify the path to an openPMD file that contains the species' number density for each location of the simulation. Both geometries (Cartesian ``xyz`` and Cylindrical ``rz`` + modes) are supported, however not all dimensions need to be included. The mesh in the file can be chosen with `` or plasmas.density_mesh_name`` (default ``density``) and must contain a single ``SCALAR`` component. Examples of scripts to generate such files can be found in ``tools/write_plasma_density.py`` and ``tools/write_plasma_density_rz.py``. * `` or plasmas.ppc`` (2 `integer`) The number of plasma particles per cell in x and y. Since in a quasi-static code, there is only a 2D plasma slice evolving along the longitudinal coordinate, there is no need to specify a number of particles per cell in z. * `` or plasmas.radius`` (`float`) optional (default `infinity`) Radius of the plasma. Set a value to run simulations in a plasma column. * `` or plasmas.hollow_core_radius`` (`float`) optional (default `0.`) Inner radius of a hollow core plasma. The hollow core radius must be smaller than the plasma radius itself. * `` or plasmas.max_qsa_weighting_factor`` (`float`) optional (default `35.`) The maximum allowed weighting factor :math:`\gamma /(\psi+1)` before particles are considered as violating the quasi-static approximation and are removed from the simulation. * ``.mass`` (`float`) optional (default `0.`) The mass of plasma particle in SI units. Use ``plasma_name.mass_Da`` for Dalton. Can also be set with ``.element``. Must be `>0`. * ``.mass_Da`` (`float`) optional (default `0.`) The mass of plasma particle in Dalton. Use ``.mass`` for SI units. Can also be set with ``.element``. Must be `>0`. * ``.charge`` (`float`) optional (default `0.`) The charge of a plasma particle. Can also be set with ``.element``. The charge gets multiplied by the current ionization level. * ``.element`` (`string`) optional (default "") The physical element of the plasma. Sets charge, mass and, if available, the specific ionization energy of each state. Options are: ``electron``, ``positron``, ``H``, ``D``, ``T``, ``He``, ``Li``, ``Be``, ``B``, …. * ``.can_ionize`` (`bool`) optional (default `0`) Whether this plasma can ionize. Can also be set to 1 by specifying ``.ionization_product``. * ``.can_laser_ionize`` (`bool`) optional (default `.can_ionize`) Whether this plasma can be ionized by a laser. * ``.initial_ion_level`` (`int`) optional (default `-1`) The initial ionization state of the plasma. `0` for neutral gasses. If set, the plasma charge gets multiplied by this number. If the plasma species is not ionizable, the initial ionization level is set to 1. * ``.ionization_product`` (`string`) optional (default "") Name of the plasma species that contains the new electrons that are produced when this plasma gets ionized. Only needed if this plasma is ionizable. * `` or plasmas.neutralize_background`` (`bool`) optional (default `1`) Whether to add a neutralizing background of immobile particles of opposite charge. * ``.temperature_in_ev`` (`float`) optional (default `0`) | Initializes the plasma particles with a given temperature :math:`k_B T` in eV. Using a temperature, the plasma particle momentum is normally distributed with a variance of :math:`k_B T /(M c^2)` in each dimension, with :math:`M` the particle mass, :math:`k_B` the Boltzmann constant, and :math:`T` the isotropic temperature in Kelvin. | Note: Using a temperature can affect the performance since the plasma particles loose their order and thus their favorable memory access pattern. The performance can be mostly recovered by reordering the plasma particles (see `` or plasmas.reorder_period``). Furthermore, the noise of the temperature can seed the hosing instability. The amplitude of the seeding is unphysical, because the number of macro-particles is typically orders of magnitude below the number of actual plasma electrons. Since it is often unfeasible to use a sufficient amount of plasma macro-particles per cell to suppress this numerical seed, the plasma can be symmetrized to prevent the onset of the hosing instability (see `` or plasmas.do_symmetrize``). * `` or plasmas.do_symmetrize`` (`bool`) optional (default `0`) Symmetrizes the plasma in the transverse phase space. For each particle with (`x`, `y`, `ux`, `uy`), three additional particles are generated with (`-x`, `y`, `-ux`, `uy`), (`x`, `-y`, `ux`, `-uy`), and (`-x`, `-y`, `-ux`, `-uy`). The total number of plasma particles is multiplied by 4. This option is helpful to prevent a numerical seeding of the hosing instability for a plasma with a temperature. * `` or plasmas.reorder_period`` (`int`) optional (default `0`) Reorder particles periodically to speed-up current deposition on GPU for a high-temperature plasma. A good starting point is a period of 4 to reorder plasma particles on every fourth zeta-slice. To disable reordering set this to 0. * `` or plasmas.n_subcycles`` (`int`) optional (default `1`) Number of sub-cycles within the plasma pusher. Currently only implemented for the leapfrog pusher. Must be larger or equal to 1. Sub-cycling is needed if plasma particles move significantly in the transverse direction during a single longitudinal cell. If they move too many cells such that they do not sample certain small transverse structures in the wakefields, sub-cycling is needed and fixes the issue. * `` or plasmas.reorder_idx_type`` (2 `int`) optional (default `0 0` or `1 1`) Change if plasma particles are binned to cells (0), nodes (1) or both (2) for both x and y direction as part of the reordering. The ideal index type depends on the particle shape factor used for deposition. For shape factors 1 and 3, 2^2 and 4^2 cells are deposited per particle respectively, resulting in node centered reordering giving better performance. For shape factors 0 and 2, 1^2 and 3^2 cells are deposited such that cell centered reordering is better. The default is chosen accordingly. If ``hipace.depos_derivative_type = 1``, the explicit deposition deposits an additional cell in each direction, making the opposite index type ideal. Since the normal deposition still requires the original index type, the compromise option ``2 2`` can be chosen. This will however require more memory in the binning process. * `` or plasmas.fine_patch(x,y)`` (`int`) optional (default `0`) When using mesh refinement it can be helpful to increase the number of particles per cell drastically in a small part of the domain. For this parameter, a function of ``x`` and ``y`` must be specified and returns an integer refinement flag. The function may evaluate to: * ``0`` use the default number of particles per cell (no fine patch), * ``1`` apply the first fine-patch level, * ``2`` apply the second fine-patch level. This allows up to two nested or distinct fine-patch regions with different particle densities. For example, using ``plasmas.fine_patch(x, y) = "sqrt(x^2 + y^2) < 10"`` specifies a circular region of radius ``10`` around ``x = 0, y = 0`` where the function evaluates to ``1`` and the first fine-patch level is applied, while it evaluates to ``0`` elsewhere. More complex expressions may be used to return ``2`` in selected regions to enable the second fine-patch level. Note that the function is evaluated at the cell centers of the level zero grid. * `` or plasmas.fine_ppc`` (2 or 4 `int`) optional (default `0 0 0 0`) The number of plasma particles per cell in x and y inside the fine plasma patch. This must be divisible by the ppc outside the fine patch in both directions. The ppc number is taken relative to the cell size of mesh refinement level 0 so it typically should be much larger than `` or plasmas.ppc``. If two levels of fine patch are used the number of plasma particles per cell are specified as ``x1 y1 x2 y2``. * `` or plasmas.fine_transition_cells`` (`int`) optional (default `5`) Number of cells that are used just outside of the fine plasma patch to smoothly transition between the low and high ppc regions. More transition cells produce less noise but require more particles. * `` or plasmas.prevent_centered_particle`` (`bool`) optional (default `0`) When ``amr.n_cell`` and the plasma ppc are both odd, a plasma particle is initialized in the exact center of the domain. A symmetric beam also initialized at the center of the domain will not be able to push this particle away, causing the plasma particle to pass through the beam and increasing its emittance. Enabling this setting causes all plasma particles to be initialized half a cell to the side so that no plasma particle will be at the exact center of the domain. However, this will also result in a gap at the domain boundary, which can lead to noise. * `` or plasmas.do_push`` (`bool`) optional (default `1`) When set to `0`, disables the plasma particle pusher. Beam parameters --------------- For the beam parameters, first the names of the beams need to be specified. Afterwards, the beam parameters for each beam are specified via ``. = ...`` * ``beams.names`` (`string`) optional (default `no_beam`) The names of the particle beams, separated by a space. To run without beams, choose the name ``no_beam``. General beam parameters ^^^^^^^^^^^^^^^^^^^^^^^ The general beam parameters are applicable to all particle beam types. More specialized beam parameters, which are valid only for certain beam types, are introduced further below under "Option: ````". * ``.injection_type`` (`string`) The injection type for the particle beam. Currently available are ``fixed_weight_pdf``, ``fixed_weight``, ``fixed_ppc``, ``from_file`` and ``from_list``. ``fixed_weight_pdf`` generates a beam with a fixed number of particles with a constant weight where the transverse profile is Gaussian and the longitudinal profile is arbitrary according to a user-specified probability density function. It is more general and faster, and uses less memory than ``fixed_weight``. ``fixed_weight`` generates a Gaussian beam with a fixed number of particles with a constant weight. ``fixed_ppc`` generates a beam with a fixed number of particles per cell and varying weights. It can be either a Gaussian or a flattop beam. ``from_file`` reads a beam from openPMD files. ``from_list`` reads a beam from arrays provided directly in the input script. * ``.element`` (`string`) optional (default `electron`) The Physical Element of the plasma. Sets charge, mass and, if available, the specific Ionization Energy of each state. Currently available options are: ``electron``, ``positron``, and ``proton``. * ``.mass`` (`float`) optional (default `m_e`) The mass of beam particles. Can also be set with ``.element``. Must be `>0`. * ``.charge`` (`float`) optional (default `-q_e`) The charge of a beam particle. Can also be set with ``.element``. * ``.n_subcycles`` (`int`) optional (default `10`) Number of sub-cycles performed in the beam particle pusher. The particles will be pushed ``n_subcycles`` times with a time step of `dt/n_subcycles`. This can be used to improve accuracy in highly non-linear focusing fields. * `` or beams.external_E(x,y,z,t)`` (3 `float`) optional (default `0. 0. 0.`) External electric field applied to beam particles as functions of x, y, z and t. The components represent Ex, Ey and Ez respectively. Note that z refers to the location of the beam particle inside the moving frame of reference (zeta) and t to the physical time of the current timestep. * `` or beams.external_B(x,y,z,t)`` (3 `float`) optional (default `0. 0. 0.`) External magnetic field applied to beam particles as functions of x, y, z and t. The components represent Bx, By and Bz respectively. Note that z refers to the location of the beam particle inside the moving frame of reference (zeta) and t to the physical time of the current timestep. * ``.do_z_push`` (`bool`) optional (default `1`) Whether the beam particles are pushed along the z-axis. The momentum is still fully updated. Note: using ``do_z_push = 0`` results in unphysical behavior. * `` or beams.do_push`` (`bool`) optional (default `1`) When set to `0`, disables the beam particle pusher. * `` or beams.reorder_period`` (`int`) optional (default `0`) Reorder particles periodically to speed-up current deposition and particle push on GPU. A good starting point is a period of 1 to reorder beam particles on every timestep. To disable reordering set this to 0. For very narrow beams the sorting may take longer than the time saved in the beam push and deposition. * `` or beams.reorder_idx_type`` (2 `int`) optional (default `0 0` or `1 1`) Change if beam particles are binned to cells (0), nodes (1) or both (2) for both x and y direction as part of the reordering. The ideal index type is different for beam push and beam deposition so some experimentation may be required to find the overall fastest setting for a specific simulation. * `` or beams.output_ratio`` (`int`) optional (default `1`) Set the fraction of beam particles that should be written to the openPMD output. For example, an output ratio of 100 will output every 100th beam particle. This is implemented using the particle ID, which is set in ascending order at the beginning of a simulation. Option: ``fixed_weight_pdf`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``.num_particles`` (`int`) Number of constant weight particles to generate the beam. * ``.pdf`` (`float`) Longitudinal density profile of the beam, given as a probability density function (the transverse profile is Gaussian). This is a parser function of z, giving the charge density integrated in both transverse directions `x` and `y` (this is proportional to the beam current profile in the limit :math:`v_z \simeq c`). The probability density function is automatically normalized, and combined with ``.total_charge`` or ``.density`` within the code to generate the absolute beam profile. Examples (assuming ``z_center``, ``z_std``, ``z_length``, ``z_slope``, ``z_min`` and ``z_max`` are defined with ``my_constants``): - Gaussian: ``exp(-0.5*((z-z_center)/z_std)^2)`` - Cosine: ``(cos(2*pi*(z-z_center)/z_length)+1)*(2*abs(z-z_center)z_min)*(1+z_slope*z)`` * ``.total_charge`` (`float`) Total charge of the beam (either ``total_charge`` or ``density`` must be specified). Only available when running in SI units. The absolute value of this parameter is used when initializing the beam. Note that in contrast to the ``fixed_weight`` injection type, using ``.radius`` or a special pdf to emulate ``z_min`` and ``z_max`` will result in beam particles being redistributed to other locations rather than being deleted. Therefore, the resulting beam will have exactly the specified total charge, but cutting a significant fraction of the charge is not recommended. * ``.density`` (`float`) Peak density of the beam (either ``total_charge`` or ``density`` must be specified). The absolute value of this parameter is used when initializing the beam. Note that this is the peak density of the analytical profile specified by `pdf`, `position_mean` and `position_std`, within the limits of the resolution of the numerical evaluation of the pdf. The actual resulting beam profile consists of randomly distributed particles and will likely feature density fluctuations exceeding the specified peak density. * ``.position_mean`` (2 `float`) The mean position of the beam in ``x, y``, separated by a space. Both values can be a function of z. To generate a tilted beam use ``.position_mean = "x_center+(z-z_center)*dx_per_dzeta" "y_center+(z-z_center)*dy_per_dzeta"``. * ``.position_std`` (2 `float`) The rms size of the of the beam in ``x, y``, separated by a space. Both values can be a function of z. * ``.u_mean`` (3 `float`) The mean normalized momentum of the beam in ``x, y, z``, separated by a space. All values can be a function of z. Normalized momentum is equal to :math:`= \gamma \beta = \frac{p}{m c}`. An electron beam with a momentum of 1 GeV/c has a u_mean of ``0 0 1956.951198`` while a proton beam with the same momentum has a u_mean of ``0 0 1.065788933``. * ``.u_std`` (3 `float`) The rms normalized momentum of the beam in ``x, y, z``, separated by a space. All values can be a function of z. * ``.do_symmetrize`` (`bool`) optional (default `0`) Symmetrizes the beam in the transverse phase space. For each particle with (`x`, `y`, `ux`, `uy`), three further particles are generated with (`-x`, `y`, `-ux`, `uy`), (`x`, `-y`, `ux`, `-uy`), and (`-x`, `-y`, `-ux`, `-uy`). The total number of particles will still be ``beam_name.num_particles``, therefore this option requires that the beam particle number must be divisible by 4. * ``.z_foc`` (`float`) optional (default `0.`) Distance at which the beam will be focused, calculated from the position at which the beam is initialized. The beam is assumed to propagate ballistically in-between. * ``.radius`` (`float`) optional (default `infinity`) Maximum radius ``.radius`` :math:`= \sqrt{x^2 + y^2}` within that particles are injected. If ``.density`` is specified, beam particles outside of the radius get deleted. If ``.total_charge`` is specified, beam particles outside of the radius get new random transverse positions to conserve the total charge. * ``.pdf_ref_ratio`` (`int`) optional (default `4`) Into how many segments the pdf is divided per zeta slice for its first-order numerical evaluation. Option: ``fixed_weight`` ^^^^^^^^^^^^^^^^^^^^^^^^ * ``.num_particles`` (`int`) Number of constant weight particles to generate the beam. * ``.profile`` (`string`) optional (default `gaussian`) Beam profile. Possible options are ``can`` (uniform longitudinally, Gaussian transversally) and ``gaussian`` (Gaussian in all directions). * ``.total_charge`` (`float`) Total charge of the beam. Note: Either ``total_charge`` or ``density`` must be specified. The absolute value of this parameter is used when initializing the beam. Note that ``.zmin``, ``.zmax`` and ``.radius`` can reduce the total charge. * ``.density`` (`float`) Peak density of the beam. Note: Either ``total_charge`` or ``density`` must be specified. The absolute value of this parameter is used when initializing the beam. * ``.position_mean`` (3 `float`) The mean position of the beam in ``x, y, z``, separated by a space. The x and y directions can be functions of ``z``. To generate a tilted beam use ``.position_mean = "x_center+(z-z_ center)*dx_per_dzeta" "y_center+(z-z_ center)*dy_per_dzeta" "z_center"``. * ``.position_std`` (3 `float`) The rms size of the of the beam in ``x, y, z``, separated by a space. * ``.u_mean`` (3 `float`) The mean normalized momentum of the beam in ``x, y, z``, separated by a space. Normalized momentum is equal to :math:`= \gamma \beta = \frac{p}{m c}`. An electron beam with a momentum of 1 GeV/c has a u_mean of ``0 0 1956.951198`` while a proton beam with the same momentum has a u_mean of ``0 0 1.065788933``. * ``.u_std`` (3 `float`) The rms normalized momentum of the beam in ``x, y, z``, separated by a space. * ``.duz_per_uz0_dzeta`` (`float`) optional (default `0.`) Relative correlated energy spread per :math:`\zeta`. Thereby, `duz_per_uz0_dzeta *` :math:`\zeta` `* uz_mean` is added to `uz` of the each particle. :math:`\zeta` is hereby the particle position relative to the mean longitudinal position of the beam. * ``.do_symmetrize`` (`bool`) optional (default `0`) Symmetrizes the beam in the transverse phase space. For each particle with (`x`, `y`, `ux`, `uy`), three further particles are generated with (`-x`, `y`, `-ux`, `uy`), (`x`, `-y`, `ux`, `-uy`), and (`-x`, `-y`, `-ux`, `-uy`). The total number of particles will still be ``beam_name.num_particles``, therefore this option requires that the beam particle number must be divisible by 4. * ``.z_foc`` (`float`) optional (default `0.`) Distance at which the beam will be focused, calculated from the position at which the beam is initialized. The beam is assumed to propagate ballistically in-between. * ``.zmin`` (`float`) (default `-infinity`) Minimum in `z` at which particles are injected. * ``.zmax`` (`float`) (default `infinity`) Maximum in `z` at which particles are injected. * ``.radius`` (`float`) (default `infinity`) Maximum radius ``.radius`` :math:`= \sqrt{x^2 + y^2}` within that particles are injected. * `` or beams.initialize_on_cpu`` (`bool`) optional (default `0`) Whether to initialize the beam on the CPU instead of the GPU. Initializing the beam on the CPU can be much slower but is necessary if the full beam does not fit into GPU memory. Option: ``fixed_ppc`` ^^^^^^^^^^^^^^^^^^^^^ * ``.ppc`` (3 `int`) (default `1 1 1`) Number of particles per cell in `x`-, `y`-, and `z`-direction to generate the beam. * ``.profile`` (`string`) Beam profile. Possible options are ``flattop`` (flat-top radially and longitudinally), ``gaussian`` (Gaussian in all directions), or ``parsed`` (arbitrary analytic function provided by the user). When ``parsed``, ``.density(x,y,z)`` must be specified. * ``.density`` (`float`) Peak density of the beam. The absolute value of this parameter is used when initializing the beam. * ``.density(x,y,z)`` (`float`) The density profile of the beam, as a function of spatial dimensions `x`, `y` and `z`. This function uses the parser, see above. * ``.min_density`` (`float`) optional (default `0`) Particles with a density less than or equal to the minimal density won't be injected. The absolute value of this parameter is used when initializing the beam. * ``.position_mean`` (3 `float`) The mean position of the beam in ``x, y, z``, separated by a space. * ``.position_std`` (3 `float`) The rms size of the of the beam in ``x, y, z``, separated by a space. * ``.u_mean`` (3 `float`) The mean normalized momentum of the beam in ``x, y, z``, separated by a space. Normalized momentum is equal to :math:`= \gamma \beta = \frac{p}{m c}`. An electron beam with a momentum of 1 GeV/c has a u_mean of ``0 0 1956.951198`` while a proton beam with the same momentum has a u_mean of ``0 0 1.065788933``. * ``.u_std`` (3 `float`) The rms normalized momentum of the beam in ``x, y, z``, separated by a space. * ``.random_ppc`` (3 `bool`) optional (default `0 0 0`) Whether the position in `(x y z)` of the particles is randomized within the cell. * ``.zmin`` (`float`) (default `-infinity`) Minimum in `z` at which particles are injected. * ``.zmax`` (`float`) (default `infinity`) Maximum in `z` at which particles are injected. * ``.radius`` (`float`) (default `infinity`) Maximum radius ``.radius`` :math:`= \sqrt{x^2 + y^2}` within that particles are injected. Option: ``from_file`` ^^^^^^^^^^^^^^^^^^^^^ * `` or beams.input_file`` (`string`) Name of the input file. **Note:** Reading in files with digits in their names (e.g. ``openpmd_002135.h5``) can be problematic, it is advised to read them via ``openpmd_%T.h5`` and then specify the iteration via ``beam_name.iteration = 2135``. * `` or beams.iteration`` (`integer`) optional (default `0`) Iteration of the openPMD file to be read in. If the openPMD file contains multiple iterations, or multiple openPMD files are read in, the iteration can be specified. **Note:** The physical time of the simulation is set to the time of the given iteration (if available). * ``.openPMD_species_name`` (`string`) optional (default ``) Name of the beam to be read in. If an openPMD file contains multiple beams, the name of the beam needs to be specified. * `` or beams.initialize_on_cpu`` (`bool`) optional (default `0`) Whether to initialize the beam on the CPU instead of the GPU. Initializing the beam on the CPU can be much slower but is necessary if the full beam does not fit into GPU memory. Option: ``from_list`` ^^^^^^^^^^^^^^^^^^^^^ * ``.num_particles`` (`int`) Number of particles to generate the beam. If this is equal to zero, then the other parameters can be omitted. * ``.init_pos_x``, ``.init_pos_y`` and ``.init_pos_z`` (`float`) List of initial x-, y- and z-positions for all beam particles. * ``.init_ux``, ``.init_uy`` and ``.init_uz`` (`float`) List of initial normalized momentum (:math:`= \gamma \beta = \frac{p}{m c}`) in x, y and z for all beam particles. * ``.init_weight`` (`float`) List of macro-particle weight for all beam particles. A value of one corresponds to one physical particle. * ``.init_sx``, ``.init_sy`` and ``.init_sz`` (`float`) If spin-tracking is enabled, list of initial x-, y- and z-spin for all beam particles. SALAME algorithm ^^^^^^^^^^^^^^^^ HiPACE++ features the Slicing Advanced Loading Algorithm for Minimizing Energy Spread (SALAME) to generate a beam profile that automatically loads the wake optimally, i.e., so that the initial wakefield is flattened by the charge of the beam. Important note: In the algorithm, the weight of the beam particles is adjusted while the plasma response is computed. Since the beam is written to file **before** the plasma response is calculated, the SALAME beam has incorrect weights in the 0th time step. For more information on the algorithm, see the corresponding publication `S. Diederichs et al., Phys. Rev. Accel. Beams 23, 121301 (2020) `__ * ``.do_salame`` (`bool`) optional (default `0`) If turned on, the per-slice beam weight in the first time-step is adjusted such that the Ez field is uniform in the beam. This ignores the contributions to jx, jy and rho from the beam in the first time-step. It is recommended to use this option with a fixed weight can beam. If a gaussian beam profile is used, then the zmin and zmax parameters should be used. * ``hipace.salame_n_iter`` (`int`) optional (default `5`) The maximum number of iterations the SALAME algorithm should do when it is used. * ``hipace.salame_relative_tolerance`` (`float`) optional (default `1e-4`) Relative error tolerance to finish SALAME iterations early. * ``hipace.salame_do_advance`` (`bool`) optional (default `1`) Whether the SALAME algorithm should calculate the SALAME-beam-only Ez field by advancing plasma (if `1`) particles or by approximating it using the chi field (if `0`). * ``hipace.salame_Ez_target(zeta,zeta_initial,Ez_initial)`` (`string`) optional (default `Ez_initial`) Parser function to specify the target Ez field at the witness beam for SALAME. ``zeta``: position of the Ez field to set. ``zeta_initial``: position where the SALAME algorithm first started. ``Ez_initial``: field value at `zeta_initial`. For `zeta` equal to `zeta_initial`, the function should return `Ez_initial`. The default value of this function corresponds to a flat Ez field at the position of the SALAME beam. Note: `zeta` is always less than or equal to `zeta_initial` and `Ez_initial` is typically below zero for electron beams. Laser parameters ---------------- The model implemented is the one from [C. Benedetti et al. Plasma Phys. Control. Fusion 60.1: 014002 (2017)]. Unlike for ``beams`` and ``plasmas``, all the laser pulses are currently stored on the same array, which you can find in the output openPMD file as a complex array named `laserEnvelope`. Parameters starting with ``lasers.`` apply to all laser pulses, parameters starting with ```` apply to a single laser pulse. * ``lasers.names`` (list of `string`) optional (default `no_laser`) The names of the laser pulses, separated by a space. To run without a laser, choose the name ``no_laser``. * ``lasers.polarization`` (`linear` or `circular`) optional (default `linear`) Polarization of the laser pulse. For the same peak amplitude, the ponderomotive force is 2x larger in circular polarization than in linear polarization. Note that the envelope of the vector potential stored in arrays is independent on the polarization, such that the energy is actually 2x higher in circular polarization than in linear polarization. * ``lasers.use_phase`` (`bool`) optional (default `true`) Whether the phase terms (:math:`\theta` in Eq. (6) of [C. Benedetti et al. Plasma Phys. Control. Fusion 60.1: 014002 (2017)]) are computed and used in the laser envelope advance. Keeping the phase should be more accurate, but can cause numerical issues in the presence of strong depletion/frequency shift. * ``lasers.use_non_centered_push`` (`bool`) optional (default `false`) By default, the laser solver uses the two previous time steps to compute the next one. In some cases this can lead to unphysical fast oscillations. With this setting, only one previous time step is used which, can help to reduce oscillations but is less accurate. * ``lasers.interp_order`` (`int`) optional (default `1`) Transverse shape order for the laser to field interpolation of aabs and the field to laser interpolation of chi. Currently, `0,1,2,3` are implemented. * ``lasers.solver_type`` (`string`) optional (default `multigrid`) Type of solver for the laser envelope solver, either ``multigrid`` or ``off``. Currently, the approximation that the phase is evaluated on-axis only is made. With the multigrid solver, we could drop this assumption. If set ``off``, the laser will not evolve and remain as the initial profile through the simulation. * ``lasers.MG_tolerance_rel`` (`float`) optional (default `1e-4`) Relative error tolerance of the multigrid solver used for the laser pulse. * ``lasers.MG_tolerance_abs`` (`float`) optional (default `0.`) Absolute error tolerance of the multigrid solver used for the laser pulse. * ``lasers.MG_verbose`` (`int`) optional (default `0`) Level of verbosity of the multigrid solver used for the laser pulse. * ``lasers.MG_average_rhs`` (`0` or `1`) optional (default `1`) Whether to use the most stable discretization for the envelope solver. * ``.init_type`` (list of `string`) optional (default `gaussian`) The initialisation method of laser. Possible options are: ``gaussian`` (default): the laser is initialised with an ideal Gaussian pulse: :math:`a(x,y,z) = a_0 e^{-(x^2/w_0^2 + y^2/w_0^2 + z^2/L_0^2)}`. * ``.a0`` (`float`) optional (default `0`) Peak normalized vector potential of the laser pulse. * ``lasers.lambda0`` (`float`) Wavelength of the laser pulses. Currently, all pulses must have the same wavelength. * ``.position_mean`` (3 `float`) optional (default `0 0 0`) The mean position of the laser in `x, y, z`. * ``.w0`` (2 `float`) optional (default `0 0`) The laser waist in `x, y`. * ``.L0`` (`float`) optional (default `0`) The laser pulse length in `z`. Use either the pulse length or the pulse duration ``.tau``. * ``.tau`` (`float`) optional (default `0`) The laser pulse duration. The pulse length is set to `laser.tau`:math:`*c_0`. Use either the pulse length or the pulse duration. * ``.focal_distance`` (`float`) Distance at which the laser pulse is focused (in the z direction, counted from laser initial position). * ``.propagation_angle_yz`` (`float`) optional (default `0`) Propagation angle of the pulse in the yz plane (0 is along the z axis) * ``.STC_theta_xy`` (`float`) optional (default `0`) Direction of the linear spatial and angular chirps in the xy plane (in radians; `0` is along x, `π/2` along y). In what follows, all chirps are given as defined in `S. Akturk et al., Optics Express 12, 4399 (2004) `__. * ``.beta`` (`float`) optional (default `0.`) Angular dispersion (or angular chirp) at focus in :math:`second`. * ``.zeta`` (`float`) optional (default `0.`) Spatial chirp at focus in :math:`second \cdot meter`. * ``.phi2`` (`float`) optional (default `0`) Temporal chirp :math:`\phi^{(2)}` at focus in :math:`second^2`. Namely, a wave packet centered on frequency :math:`(\omega_0 + \delta \omega)` reaches its peak intensity at :math:`z(\delta \omega) = z_0 - c \phi^{(2)} \, \delta \omega`. Thus, a positive :math:`\phi^{(2)}` corresponds to positive chirp, i.e., red part of the spectrum in the front of the pulse and blue part in the back. More specifically, the electric field in the focal plane is of the form: .. math:: E(\boldsymbol{x},t) \propto Re\left[ \exp\left( -\frac{(t-t_{peak})^2}{\tau^2 + 2i\phi^{(2)}} + i\omega_0 (t-t_{peak}) + i\phi_0 \right) \right] where :math:`\tau` is given by ``.tau`` and represents the Fourier-limited duration of the laser pulse. Thus, the actual duration of the chirped laser pulse is: .. math:: \tau' = \sqrt{ \tau^2 + 4 (\phi^{(2)})^2/\tau^2 } ``from_file``: the laser is loaded from an openPMD file. * ``.input_file`` (`string`) optional (default `""`) Path to an openPMD file containing a laser envelope. The file should comply with the `LaserEnvelope extension of the openPMD-standard `__, as generated by `LASY `__. Currently supported geometries: 3D or cylindrical profiles with azimuthal decomposition. The laser pulse is injected in the HiPACE++ simulation so that the beginning of the temporal profile from the file corresponds to the head of the simulation box, and time (in the file) is converted to space (HiPACE++ longitudinal coordinate) with ``z = -c*t + const``. If this parameter is set, then the file is used to initialize all lasers instead of using a gaussian profile. * ``.lambda0`` (`float`) optional (default ``) Wavelength of the laser pulses. Currently, all pulses must have the same wavelength. The wavelength is already read in from the metadata of the openPMD file, however it can be overwritten using this parameter. * ``.openPMD_laser_name`` (`string`) optional (default `laserEnvelope`) Name of the laser envelope field inside the openPMD file to be read in. * ``.iteration`` (`int`) optional (default `0`) Iteration of the openPMD file to be read in. ``parser``: the laser is initialized with the expression of the complex envelope function. * ``.laser_real(x,y,z)`` optional (`string`) (default `""`) Expression for the real part of the laser envelope in `x, y, z`. * ``.laser_imag(x,y,z)`` optional (`string`) (default `""`) Expression for the imaginary part of the laser envelope `x, y, z`. * ``lasers.lambda0`` (`float`) Wavelength of the laser pulses. Currently, all pulses must have the same wavelength. Diagnostic parameters --------------------- There are different types of diagnostics in HiPACE++. The standard diagnostics are compliant with the openPMD standard. The in-situ diagnostics allow for fast analysis of large beams or the plasma particles. Please make sure to always clear or rename the output folder before running a new simulation to avoid mixing data from different runs. * ``diagnostic.output_period`` (`integer` or `string`) optional (default `0`) Output period for standard beam and field diagnostics. Field or beam specific diagnostics can overwrite this parameter. Diagnostic output is written to file when the current time step is a multiple of the output period. For ``diagnostic.output_period = 0`` no output is given, while ``diagnostic.output_period = 1`` always produces output. The output period can also be a function of ``current_step`` and ``current_time`` to have finer control of when output should be written. Examples of how to use this can be found `here `__. * ``hipace.output_folder`` (`string`) optional (default ``"diags"``) Set the output path of diagnostic data. By default all types of diagnostics will output into subfolders of this folder. * ``hipace.file_prefix`` (`string`) optional (default ``"/hdf5/"``) Path of the output. * ``hipace.openpmd_backend`` (`string`) optional (default `h5`) OpenPMD backend. This can either be ``h5``, ``bp``, or ``json``. The default is chosen by what is available. If both Adios2 and HDF5 are available, ``h5`` is used. Note that ``json`` is extremely slow and is not recommended for production runs. Beam diagnostics ^^^^^^^^^^^^^^^^ * ``diagnostic.beam_output_period`` (`integer` or `string`) optional (default `0`) Output period for the beam. No output is given for ``diagnostic.beam_output_period = 0``. If ``diagnostic.output_period`` is defined, that value is used as the default for this. See the documentation of ``diagnostic.output_period`` for more details. * ``diagnostic.beam_data`` (`string`) optional (default `all`) Names of the beams written to file, separated by a space. The beam names need to be ``all``, ``none`` or a subset of ``beams.names``. Field diagnostics ^^^^^^^^^^^^^^^^^ * ``diagnostic.names`` (`string`) optional (default `lev0`) The names of all field diagnostics, separated by a space. Multiple diagnostics can be used to limit the output to only a few relevant regions to save on file size. To run without field diagnostics, choose the name ``no_field_diag``. Depending on whether mesh refinement or a laser is used, the default becomes a subset of ``lev0 lev1 lev2 laser_diag``. * `` or diagnostic.base_geometry`` (`string`) optional (default `level_0`) Which geometry the diagnostics should be based on. Available geometries are `level_0`, `level_1`, `level_2`, `laser` and `histogram`, depending on if MR or a laser is used. If ```` is equal to ``lev0 lev1 lev2 laser_diag``, the default for this parameter becomes ``level_0 level_1 level_2 laser`` respectively. * ``.output_period`` (`integer` or `string`) optional (default `0`) Output period for fields. No output is given for ``.output_period = 0``. If ``diagnostic.output_period`` is defined, that value is used as the default for this. See the documentation of ``diagnostic.output_period`` for more details. * `` or diagnostic.diag_type`` (`string`) Type of field output. Available options are `xyz`, `xz`, `yz` and `xy_integrated`. `xyz` generates a 3D field output. Use 3D output with parsimony, it may increase disk Space usage and simulation time significantly. `xz` and `yz` generate 2D field outputs at the center of the y-axis and x-axis, respectively. In case of an even number of grid points, the value is averaged between the two inner grid points. `xy_integrated` generates 2D field output that has been integrated along the `z` axis, i.e., it is the sum of the 2D field output over all slices multiplied with `dz`. * `` or diagnostic.coarsening`` (3 `int`) optional (default `1 1 1`) Coarsening ratio of field output in x, y and z direction respectively. The coarsened output is obtained through first order interpolation. * `` or diagnostic.include_ghost_cells`` (`bool`) optional (default `0`) Whether the field diagnostics should include ghost cells. * `` or diagnostic.field_data`` (`string`) optional (default `all`) Specifies the fields to be written to file, separated by a space. The field names can be: * ``all``: Includes all available fields. * ``none``: Excludes all fields. * A subset of the following: ``Ex``, ``ExmBy``, ``Ey``, ``EypBx``, ``Ez``, ``Bx``, ``By``, ``Bz``, ``Psi``. * Specific to the Predictor-Corrector solver: ``jx``, ``jy``, ``jz``, and ``rhomjz``, which correspond to the current and charge densities of the plasma and beam (``rhomjz`` is defined as :math:`\rho-j_z/c`). * Specific to the Explicit solver: separate current and charge densities for the beam (``jx_beam``, ``jy_beam``, ``jz_beam``) and plasma (``jx``, ``jy``, and ``rhomjz``). * Plasma diagnostics: ``rho`` (total charge density) is always available. Per-species diagnostics are also available: ``rho_`` (charge density of the species); ``w_`` (particle weights of the species); and momentum components ``ux_``, ``uy_``, ``uz_``, ``ux^2_``, etc. * Laser diagnostics, when a laser pulse is used: ``laserEnvelope`` (the complex envelope of the laser in the ``laser`` base geometry) and ``chi`` (plasma proper density :math:`n/\gamma`). ``laserChi`` can be used to access chi on the laser grid, with the imaginary component containing chi of the initial unperturbed plasma. ``|a^2|`` contains the absolute value squared of the laser envelope in the real component and zero in the imaginary component. * Fields can be added or removed from the list dynamically: to remove a field after including ``all``, use ``remove_``. If a field is added and removed multiple times, the last occurrence takes precedence. * `` or diagnostic.patch_lo`` (3 `float`) optional (default `-infinity -infinity -infinity`) Lower limit for the diagnostic grid. * `` or diagnostic.patch_hi`` (3 `float`) optional (default `infinity infinity infinity`) Upper limit for the diagnostic grid. * ``hipace.deposit_rho`` (`bool`) optional (default `0`) If the charge density ``rho`` of the plasma should be deposited so that it is available as a diagnostic. Otherwise only ``rhomjz`` equal to :math:`\rho-j_z/c` will be available. If ``rho`` is explicitly mentioned in ``diagnostic.field_data``, then the default will become `1`. * ``hipace.deposit_rho_individual`` (`bool`) optional (default `0`) This option works similarly to ``hipace.deposit_rho``, but the charge density from every plasma species will be deposited into individual fields accessible as ``rho_`` in ``diagnostic.field_data``. * ``hipace.deposit_n`` (`bool`) optional (default `0`) Whether the number density of each plasma species should be deposited so that it is available as a diagnostic. If ``n_`` is explicitly mentioned in ``diagnostic.field_data``, then the default will become `1`. * ``hipace.deposit_n_ion_levels`` (`bool`) optional (default `0`) This option works similarly to ``hipace.deposit_rho_individual``, but the number density will be split according to the ionization level. Every plasma species that is ionizable will be deposited into individual fields accessible as ``n__ionlev_`` in ``diagnostic.field_data``. * ``hipace.deposit_temp_individual`` (`bool`) optional (default `0`) The weights, momentum, and their squares from every plasma species will be deposited into individual fields accessible as ``w``, ``ux_`` or ``ux^2_`` (similarly for ``uy`` and ``uz``) in ``diagnostic.field_data``. * ``hipace.temperature_depos_order`` (`int`) optional (default `2`) When ``hipace.deposit_temp_individual`` is turned on, this option specifies the shape order of the deposited fields. Currently, 0,1,2,3 are implemented. Particle Histogram diagnostics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This diagnostic allows the direct computation of histograms of arbitrary particle quantities during the simulation runtime. It supports both plasma and beam particles. It is part of the standard field diagnostic and is enabled by setting ``.base_geometry = histogram``. Histograms may have one or two user-defined axes. Optionally, the simulation z-axis can be included as an additional axis or integrated over. All field diagnostic parameters apply, except ``field_data`` and ``diag_type``. For example, ``patch_lo`` and ``patch_hi`` can be used to restrict the particles included in the histogram in coordinate space, but do not modify the histogram axes. Each particle species produces a separate histogram that is output as ``_``. No unit conversion or normalization by cell volume is applied. Particles outside the histogram bounds are discarded. * ``.hist_species_names`` (`string`) List of species to include. Can be beam and/or plasma species. * ``.hist_num_bins`` (`int` or 2 `int`) Number of bins per histogram axis. * ``.hist_bins_lo`` (`flaot` or 2 `flaot`) Lower bound of each histogram axis. * ``.hist_bins_hi`` (`flaot` or 2 `flaot`) Upper bound of each histogram axis. * ``.hist_function`` (`string`) Parser expression defining the first histogram axis as a function of particle properties: ``x``, ``y``, ``z``, ``ux``, ``uy``, ``uz``, ``ga_psi``, ``w``, ``ion_lev``. Here, ``ga_psi`` is the quasi-static weighting factor for plasma particles, ``ion_lev`` is the ionization level (for ionizable species), and ``w`` is the macro-particle weight. * ``.hist_function2`` (`string`) optional Parser expression defining the second histogram axis. Uses the same variables as ``.hist_function``. * ``.hist_weight`` (`string`) optional (default `w`) Parser expression defining the weight contributed by each particle to the histogram. For plasma particles, this weight is automatically multiplied by ``ga_psi`` to obtain the physical particle weight. Uses the same variables as ``.hist_function``. This can also be used to filter particles. * ``.hist_add_z_axis`` (`bool`) optional (default `false`) Add the zeta axis from the simulation to the histogram output. This is more efficient than adding z as a custom histogram axis using ``hist_function`` or ``hist_function2``. If disabled the histogram contains data from all z slices in the range given by ``patch_lo`` and ``patch_hi``. In-situ diagnostics ^^^^^^^^^^^^^^^^^^^ Besides the standard diagnostics, fast in-situ diagnostics are available. They are most useful when beams with large numbers of particles are used, as the important moments can be calculated in-situ (during the simulation) to largely reduce the simulation's analysis. In-situ diagnostics compute slice quantities (1 number per quantity per longitudinal cell). For particle beams, they can be used to calculate the main characterizing beam parameters (width, energy spread, emittance, etc.), from which most common beam parameters (e.g. slice and projected emittance, etc.) can be computed. Additionally, the plasma particle properties (e.g, the temperature) can be calculated. For particle quantities, "[...]" stands for averaging over all particles in the current slice; for grid quantities, "[...]" stands for integrating over all cells in the current slice. For particle beams, the following quantities are calculated per slice and stored: ``sum(w), [x], [x^2], [y], [y^2], [z], [z^2], [ux], [ux^2], [uy], [uy^2], [uz], [uz^2], [x*ux], [y*uy], [z*uz], [x*uy], [y*ux], [ux/uz], [uy/uz], [ga], [ga^2], np``. For plasma particles, the following quantities are calculated per slice and stored: ``sum(w), [x], [x^2], [y], [y^2], [ux], [ux^2], [uy], [uy^2], [uz], [uz^2], [ga], [ga^2], np``. Thereby, "w" stands for weight, "ux" is the normalized momentum in the x direction, "ga" is the Lorentz factor. Averages and totals over all slices are also provided for convenience under the respective ``average`` and ``total`` subcategories. For the field in-situ diagnostics, the following quantities are calculated per slice and stored: ``[Ex^2], [Ey^2], [Ez^2], [Bx^2], [By^2], [Bz^2], [ExmBy^2], [EypBx^2], [jz_beam], [Ez*jz_beam]``. These quantities can be used to calculate the energy stored in the fields. For the laser in-situ diagnostics, the following quantities are calculated per slice and stored: ``max(|a|^2), [|a|^2], [|a|^2*x], [|a|^2*x*x], [|a|^2*y], [|a|^2*y*y], axis(a), [chi*d_z|a|^2]``. Thereby, ``max(|a|^2)`` is the highest value of ``|a|^2`` in the current slice and ``axis(a)`` gives the complex value of the laser envelope, in the center of every slice. Additionally, some metadata is also available: ``time, step, n_slices, charge, mass, z_lo, z_hi, normalized_density_factor``. ``time`` and ``step`` refers to the physical time of the simulation and step number of the current timestep. ``n_slices`` is the number of slices in the zeta direction. ``charge`` and ``mass`` relate to a single particle and are for example equal to the electron charge and mass. ``z_lo`` and ``z_hi`` are the lower and upper bounds of the z-axis of the simulation domain specified in the input file and can be used to generate a z/zeta-axis for plotting (note that they corresponds to mesh nodes, while the data is cell-centered). ``normalized_density_factor`` is equal to ``dx * dy * dz`` in normalized units and 1 in SI units. It can be used to convert ``sum(w)``, which specifies the particle density in normalized units and particle weight in SI units, to the particle weight in both unit systems. The data is written to a file at ``/reduced_..txt``. The in-situ diagnostics file format consists of a header part in ASCII containing a JSON object. When this is parsed into Python it can be converted to a NumPy structured datatype. The rest of the file, following immediately after the closing ``}``, is in binary format and contains all of the in-situ diagnostics along with some metadata. This part can be read using the structured datatype of the first section. Use ``hipace/tools/read_insitu_diagnostics.py`` to read the files using this format. It can be installed using the command ``pip install -U -e /path_to_hipace/hipace/tools``. Functions to calculate the most useful properties are also provided in that file. Usage example: .. code-block:: python import read_insitu_diagnostics as diag ir = diag.InSituReader("diags/insitu/reduced_beam.*.txt") ir.avail() # print available quantities ir.avg_data("[x]") # get 1D array over time steps ir.slice_data("emittance_x") # get 2D array over time steps and slices ir.time, ir.zeta # get metadata needed for plotting * `` or beams.insitu_period`` (`integer` or `string`) optional (default ``0``) Period of the beam in-situ diagnostics. `0` means no beam in-situ diagnostics. See the documentation of ``diagnostic.output_period`` for more details. * `` or beams.insitu_file_prefix`` (`string`) optional (default ``"/insitu"``) Path of the beam in-situ output. Must not be the same as `hipace.file_prefix`. * `` or beams.insitu_radius`` (`float`) optional (default ``infinity``) Maximum radius ``.insitu_radius`` :math:`= \sqrt{x^2 + y^2}` within which particles are used for the calculation of the insitu diagnostics. * `` or plasmas.insitu_period`` (`integer` or `string`) optional (default ``0``) Period of the plasma in-situ diagnostics. `0` means no plasma in-situ diagnostics. See the documentation of ``diagnostic.output_period`` for more details. * `` or plasmas.insitu_file_prefix`` (`string`) optional (default ``"/insitu"``) Path of the plasma in-situ output. Must not be the same as `hipace.file_prefix`. * `` or plasmas.insitu_radius`` (`float`) optional (default ``infinity``) Maximum radius ``.insitu_radius`` :math:`= \sqrt{x^2 + y^2}` within which particles are used for the calculation of the insitu diagnostics. * ``fields.insitu_period`` (`integer` or `string`) optional (default ``0``) Period of the field in-situ diagnostics. `0` means no field in-situ diagnostics. See the documentation of ``diagnostic.output_period`` for more details. * ``fields.insitu_file_prefix`` (`string`) optional (default ``"/insitu"``) Path of the field in-situ output. Must not be the same as `hipace.file_prefix`. * ``lasers.insitu_period`` (`integer` or `string`) optional (default ``0``) Period of the laser in-situ diagnostics. `0` means no laser in-situ diagnostics. * ``lasers.insitu_file_prefix`` (`string`) optional (default ``"/insitu"``) Path of the laser in-situ output. Must not be the same as `hipace.file_prefix`. See the documentation of ``diagnostic.output_period`` for more details. Additional physics ------------------ Additional physics describe the physics modules implemented in HiPACE++ that go beyond the standard electromagnetic equations. This includes ionization (see plasma parameters), binary collisions, and radiation reactions. Since all of these require the actual plasma density, they need a background density in SI units, if the simulation runs in normalized units. * ``hipace.background_density_SI`` (`float`) optional Background plasma density in SI units. Certain physical modules (collisions, ionization, radiation reactions) depend on the actual background density. Hence, in normalized units, they can only be included, if a background plasma density in SI units is provided using this input parameter. Binary collisions ^^^^^^^^^^^^^^^^^ WARNING: this module is in development. HiPACE++ proposes an implementation of [Perez et al., Phys. Plasmas 19, 083104 (2012)], inherited from WarpX, for collisions between plasma-plasma and beam-plasma. As collisions depend on the physical density, in normalized units `hipace.background_density_SI` must be specified. * ``hipace.collisions`` (list of `strings`) optional List of names of binary Coulomb collisions. Each will represent collisions between 2 species. * ``.species`` (two `strings`) optional The name of the two species for which collisions should be included. This can either be plasma-plasma or beam-plasma collisions. For plasma-plasma collisions, the species can be the same to model collisions within a species. The names must be in `plasmas.names` or `beams.names` (for beam-plasma collisions). * ``.CoulombLog`` (`float`) optional (default `-1.`) Coulomb logarithm used for this collision. If not specified, the Coulomb logarithm is determined from the temperature in each cell. Radiation reaction ^^^^^^^^^^^^^^^^^^ Whether the energy loss due to classical radiation reaction of beam particles is calculated. * `` or beams.do_radiation_reaction`` (`bool`) optional (default `0`) Whether the beam particles undergo energy loss due to classical radiation reaction. The implemented radiation reaction model is based on this publication: `M. Tamburini et al., NJP 12, 123005 `__ In normalized units, `hipace.background_density_SI` must be specified. Spin tracking ^^^^^^^^^^^^^ Track the spin of each beam particle as it is rotated by the electromagnetic fields using the Thomas-Bargmann-Michel-Telegdi (TBMT) model, see [Z. Gong et al., Matter and Radiation at Extremes 8.6 (2023), https://doi.org/10.1063/5.0152382] for the details of the implementation. This will add three extra components to each beam particle to store the spin and output those as part of the beam diagnostic as ``spin/x, spin/y, spin/z`` or beam in-situ diagnostic as ``[sx], [sx^2], [sy], [sy^2], [sz], [sz^2]``. * `` or beams.do_spin_tracking`` (`bool`) optional (default `0`) Enable spin tracking * `` or beams.initial_spin`` (3 `float`) Initial spin ``sx sy sz`` of all particles. The length of the three components is normalized to one. * `` or beams.spin_anom`` (`bool`) optional (default `0.00115965218128`) The anomalous magnetic moment. The default value is the moment for electrons. Grid Ionization ^^^^^^^^^^^^^^^ For weak laser pulses that ionize neutral gas to make a plasma channel but do not form an electron wake, the ionization fraction and resulting electron temperature can be computed directly on the grid without using plasma particles. This results in significantly faster computation and eliminates statistical noise. However, ions and electrons remain stationary with this approach. To use this feature, start with a normal input script that contains all the plasma species with plasma laser ionization fully set up. Then set the particles per cell for all plasmas to zero ``.ppc = 0 0`` and add all the ionizable plasma species to ``grid_ionization.plasma_names``. The ``ionization_product`` species of the plasmas will be ignored and instead generic electrons will be produced by grid ionization. When enabled, the fields ``grid_ionization_w_elec``, ``grid_ionization_ux^2_elec``, ``grid_ionization_uy^2_elec``, ``grid_ionization_uz_elec``, ``grid_ionization_uz^2_elec`` and ``grid_ionization_w__`` will be available in the diagnostic to compute the electron temperature and ionization fraction. Additionally, the refractive index chi is updated by the ionized electrons. * ``grid_ionization.plasma_names`` (list of `strings`) optional (default `no_gridplasma`) Names of existing plasma species that will be modeled by the grid instead of particles. All of these species should be atoms with laser ionization enabled and with zero particles per cell ``ppc = 0 0``. Parser ------ * ``parser.debug_print`` (list of `strings`) optional Print an evaluated parser expression for debugging. The fist `string` from the input is the expression to evaluate and all following `strings` can be used to define constants or variables that are used in the expression. Constants are defined by ``"="`` and variables by ``"=[,,]"``, where the expression will be evaluated at ```` equally spaced points between ```` and ````. These are the same points as ``numpy.linspace(,,)`` gives. Up to four variables are supported. Note that constant and variable definitions have to be enclosed in double-quotes and if provided through command-line parameters in bash, the full list of strings needs to be enclosed in single-quotes. Example: .. code-block:: bash parser.debug_print = "10*x + y" "x=[0,9,10]" "y=2" Output: .. code-block:: bash Parser Debug Print "10*x + y" = [2, 12, 22, 32, 42, 52, 62, 72, 82, 92]