Particle distributions

Warning

This section is currently in development.

class picmistandard.PICMI_GaussianBunchDistribution(*, n_physical_particles: int, rms_bunch_size: ~collections.abc.Sequence[float], rms_velocity: ~collections.abc.Sequence[float] = <factory>, centroid_position: ~collections.abc.Sequence[float] = <factory>, centroid_velocity: ~collections.abc.Sequence[float] = <factory>, velocity_divergence: ~collections.abc.Sequence[float] = <factory>, **extra_data: ~typing.Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Describes a Gaussian distribution of particles

field n_physical_particles: int [Required]

Integer. Number of physical particles in the bunch

field rms_bunch_size: Sequence[float] [Required]

Vector of length 3 of floats. RMS bunch size at t=0 [m]

field rms_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. RMS velocity spread at t=0 [m/s]

field centroid_position: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Position of the bunch centroid at t=0 [m]

field centroid_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Velocity (gamma*V) of the bunch centroid at t=0 [m/s]

field velocity_divergence: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Expansion rate of the bunch at t=0 [m/s/m]

class picmistandard.PICMI_UniformDistribution(*, density: float, lower_bound: ~collections.abc.Sequence[float | None] = <factory>, upper_bound: ~collections.abc.Sequence[float | None] = <factory>, rms_velocity: ~collections.abc.Sequence[float] = <factory>, directed_velocity: ~collections.abc.Sequence[float] = <factory>, fill_in: bool | None = None, **extra_data: ~typing.Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Describes a uniform density distribution of particles

field density: float [Required]

Float. Physical number density [m^-3]

field lower_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Lower bound of the distribution [m]

field upper_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Upper bound of the distribution [m]

field rms_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Thermal velocity spread [m/s]

field directed_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Directed, average, proper velocity [m/s]

field fill_in: bool | None = None

Bool, optional. Flags whether to fill in the empty spaced opened up when the grid moves

class picmistandard.PICMI_FoilDistribution(*, density: float, front: float, thickness: float, exponential_pre_plasma_length: float | None = None, exponential_pre_plasma_cutoff: float | None = None, exponential_post_plasma_length: float | None = None, exponential_post_plasma_cutoff: float | None = None, lower_bound: ~collections.abc.Sequence[float | None] = <factory>, upper_bound: ~collections.abc.Sequence[float | None] = <factory>, rms_velocity: ~collections.abc.Sequence[float] = <factory>, directed_velocity: ~collections.abc.Sequence[float] = <factory>, fill_in: bool | None = None, **extra_data: ~typing.Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Describes a foil with optional exponential pre- and post-plasma ramps along the propagation direction.

field density: float [Required]

Float. Physical number density [m^-3]

field front: float [Required]

Float. Position of front surface of foil [m]

field thickness: float [Required]

Float >= 0. Thickness of the foil [m]

field exponential_pre_plasma_length: float | None = None

Float > 0, optional. Length scale of exponential decay of pre-foil plasma density [m]

field exponential_pre_plasma_cutoff: float | None = None

Float >= 0, optional. Cutoff length for exponential decay of pre-foil density [m]

field exponential_post_plasma_length: float | None = None

Float > 0, optional. Length scale of exponential decay of post-foil plasma density [m]

field exponential_post_plasma_cutoff: float | None = None

Float >= 0, optional. Cutoff length for exponential decay of post-foil density [m]

field lower_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Lower bound of the distribution [m]

field upper_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Upper bound of the distribution [m]

field rms_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Thermal velocity spread [m/s]

field directed_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Directed, average, proper velocity [m/s]

field fill_in: bool | None = None

Bool, optional. Flags whether to fill in the empty spaced opened up when the grid moves

picmistandard.PICMI_UniformFluxDistribution

alias of PICMI_AnalyticFluxDistribution

class picmistandard.PICMI_AnalyticDistribution(*, density_expression: str, momentum_expressions: ~collections.abc.Sequence[str | None] = <factory>, momentum_spread_expressions: ~collections.abc.Sequence[str | None] = <factory>, lower_bound: ~collections.abc.Sequence[float | None] = <factory>, upper_bound: ~collections.abc.Sequence[float | None] = <factory>, rms_velocity: ~collections.abc.Sequence[float] = <factory>, directed_velocity: ~collections.abc.Sequence[float] = <factory>, fill_in: bool | None = None, user_defined_kw: dict[str, ~typing.Any] = <factory>, **extra_data: ~typing.Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Describes a plasma with density following a provided analytic expression.

Expressions should be in terms of the position, written as ‘x’, ‘y’, and ‘z’. Parameters can be used in the expression with the values given as keyword arguments.

This example will create a distribution where the density is n0 below rmax and zero elsewhere:

.. code-block:: python

dist = AnalyticDistribution(density_expression=’((x**2+y**2)<rmax**2)*n0’,

rmax = 1., n0 = 1.e20, …)

field density_expression: str [Required]

String. Analytic expression describing physical number density [m^-3]. Expression should be in terms of the position, written as ‘x’, ‘y’, and ‘z’. Parameters can be used in the expression with the values given as keyword arguments.

field momentum_expressions: Sequence[str | None] [Optional]

List of strings. Analytic expressions describing the gamma*velocity for each axis [m/s]. Expressions should be in terms of the position, written as ‘x’, ‘y’, and ‘z’. Parameters can be used in the expression with the values given as keyword arguments. For any axis not supplied (set to None), directed_velocity will be used.

field momentum_spread_expressions: Sequence[str | None] [Optional]

List of strings. Analytic expressions describing the gamma*velocity Gaussian thermal spread sigma for each axis [m/s]. Expressions should be in terms of the position, written as ‘x’, ‘y’, and ‘z’. Parameters can be used in the expression with the values given as keyword arguments. For any axis not supplied (set to None), zero will be used.

field lower_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Lower bound of the distribution [m]

field upper_bound: Sequence[float | None] [Optional]

Vector of length 3 of floats, optional. Upper bound of the distribution [m]

field rms_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Thermal velocity spread [m/s]

field directed_velocity: Sequence[float] [Optional]

Vector of length 3 of floats, default=[0.,0.,0.]. Directed, average, proper velocity [m/s]

field fill_in: bool | None = None

Bool, optional. Flags whether to fill in the empty spaced opened up when the grid moves

field user_defined_kw: dict[str, Any] [Optional]

Dictionary of user-defined keyword arguments extracted from extra fields

class picmistandard.PICMI_AnalyticFluxDistribution(*, flux: str, flux_normal_axis: str, surface_flux_position: float, flux_direction: int, lower_bound: ~collections.abc.Sequence[float | None] = <factory>, upper_bound: ~collections.abc.Sequence[float | None] = <factory>, rms_velocity: ~collections.abc.Sequence[float] = <factory>, directed_velocity: ~collections.abc.Sequence[float] = <factory>, flux_tmin: float | None = None, flux_tmax: float | None = None, gaussian_flux_momentum_distribution: bool | None = None, user_defined_kw: dict[str, ~typing.Any] = <factory>, **extra_data: ~typing.Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Describes a flux of particles emitted from a plane.

The flux expression should be in terms of the position and time, written as ‘x’, ‘y’, ‘z’, and ‘t’. Parameters can be used in the expression with the values given as keyword arguments.

field flux: str [Required]

String. Analytic expression describing flux of particles [m^-2.s^-1]. Expression should be in terms of the position and time, written as ‘x’, ‘y’, ‘z’, and ‘t’.

field flux_normal_axis: str [Required]

String. x, y, or z for 3D, x or z for 2D, or r, t, or z in RZ geometry

field surface_flux_position: float [Required]

Float. Location of the injection plane [m] along the direction specified by flux_normal_axis

field flux_direction: int [Required]

Integer. Direction of the flux relative to the plane: -1 or +1

field lower_bound: Sequence[float | None] [Optional]

Vector of floats, optional. Lower bound of the distribution [m]

field upper_bound: Sequence[float | None] [Optional]

Vector of floats, optional. Upper bound of the distribution [m]

field rms_velocity: Sequence[float] [Optional]

Vector of floats, default=[0.,0.,0.]. Thermal velocity spread [m/s]

field directed_velocity: Sequence[float] [Optional]

Vector of floats, default=[0.,0.,0.]. Directed, average, proper velocity [m/s]

field flux_tmin: float | None = None

Float, optional. Time at which the flux injection will be turned on

field flux_tmax: float | None = None

Float, optional. Time at which the flux injection will be turned off

field gaussian_flux_momentum_distribution: bool | None = None

Bool, optional. If True, the momentum distribution is v*Gaussian, in the direction normal to the plane. Otherwise, the momentum distribution is simply Gaussian.

field user_defined_kw: dict[str, Any] [Optional]

Dictionary of user-defined keyword arguments extracted from extra fields

class picmistandard.PICMI_ParticleListDistribution(*, x: float | Sequence[float] = 0.0, y: float | Sequence[float] = 0.0, z: float | Sequence[float] = 0.0, ux: float | Sequence[float] = 0.0, uy: float | Sequence[float] = 0.0, uz: float | Sequence[float] = 0.0, weight: float | Sequence[float] = 0.0, **extra_data: Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Load particles at the specified positions and velocities

field x: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of x positions of the particles [m]

field y: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of y positions of the particles [m]

field z: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of z positions of the particles [m]

field ux: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of ux positions of the particles (ux = gamma*vx) [m/s]

field uy: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of uy positions of the particles (uy = gamma*vy) [m/s]

field uz: float | Sequence[float] = 0.0

Float or list of floats, default=0. List of uz positions of the particles (uz = gamma*vz) [m/s]

field weight: float | Sequence[float] = 0.0

Float or list of floats, default=0. Particle weight or list of weights, number of real particles per simulation particle

class picmistandard.PICMI_FromFileDistribution(*, file_path: str, **extra_data: Any)

Base class for all PICMI classes using Pydantic for validation and extensibility.

This class allows code-specific extensions (e.g., warpx_* kwargs) via Pydantic’s extra fields mechanism while maintaining type safety for standard attributes.

Implementation specific documentation

Load particles from an openPMD file.

The openPMD file must contain the attributes position, momentum, weighting.

field file_path: str [Required]

String. Path to the openPMD file