Simulation

The Simulation object is the central object in a PICMI script. It defines the simulation time, field solver, registered species, etc.

pydantic model picmistandard.PICMI_Simulation

Creates a Simulation object

Parameters

parameter applied_fields: list[PICMI_AnyAppliedField] [Optional]

Applied fields added with add_applied_field

parameter diagnostics: list[PICMI_AnyDiagnostic] [Optional]

Diagnostics added with add_diagnostic

parameter gamma_boost: float | None = None

Lorentz factor of the boosted simulation frame. Note that all input values should be in the lab frame.

parameter initialize_self_fields: list[bool | None] [Optional]

Whether the initial space-charge fields of each species are calculated

parameter injection_plane_normal_vectors: list[list[float] | None] [Optional]

Vector normal to the injection plane of each species

parameter injection_plane_positions: list[float | list[float] | None] [Optional]

Position of one point of the injection plane of each species

parameter interactions: list[PICMI_AnyInteraction] [Optional]

Interactions added with add_interaction

parameter laser_injection_methods: list[PICMI_AnyLaserInjection | None] [Optional]

Injection method of each laser

parameter lasers: list[PICMI_AnyLaser] [Optional]

Lasers added with add_laser

parameter layouts: list[PICMI_AnyLayout | list[PICMI_AnyLayout] | None] [Optional]

Layout (or list of layouts, one per initial distribution) of each species

parameter load_balancing: Any | None = None

Controls load balancing (code dependent).

parameter max_steps: int | None = None

Maximum number of time steps. Specify either this, or max_time, or use the step function directly.

parameter max_time: float | None = None

Maximum physical time to run the simulation [s]. Specify either this, or max_steps, or use the step function directly.

parameter particle_shape: Literal['NGP', 'linear', 'quadratic', 'cubic'] | int | None = 'linear'

Default particle shape for species added to this simulation. One of ‘NGP’, ‘linear’, ‘quadratic’, ‘cubic’, or the equivalent integer interpolation order.

parameter solver: PICMI_AnySolver | None = None

This is the field solver to be used in the simulation. It should be an instance of field solver classes.

parameter species: list[PICMI_AnySpecies] [Optional]

Species added with add_species or add_species_through_plane

parameter time_step_size: float | None = None

Absolute time step size of the simulation [s]. Needed if the CFL is not specified elsewhere.

parameter verbose: int | None = None

Verbosity flag. A larger integer results in more verbose output

Methods

add_applied_field(applied_field)

Add an applied field

Parameters:

applied_field (PICMI_AnyAppliedField) – One of the applied field instances. Specifies the properties of the applied field.

add_diagnostic(diagnostic)

Add a diagnostic

Parameters:

diagnostic (PICMI_AnyDiagnostic) – One of the diagnostic instances.

add_interaction(interaction)

Add an interaction

Parameters:

interaction (PICMI_AnyInteraction) – One of the interaction objects.

add_laser(laser, injection_method)

Add a laser pulse that is injected into the simulation

Parameters:

• laser (PICMI_AnyLaser) – One of the laser profile instances. Specifies the physical properties of the laser pulse (e.g. spatial and temporal profile, wavelength, amplitude, etc.).

• injection_method (PICMI_AnyLaserInjection or None) – Specifies how the laser is injected (numerically) into the simulation (e.g. through a laser antenna, or directly added to the mesh). This argument describes an algorithm, not a physical object. It is up to each code to define the default method of injection, if the user does not provide injection_method.

add_species(species, layout, initialize_self_field=None)

Add species to be used in the simulation

Parameters:

• species (PICMI_AnySpecies) – An instance of one of the PICMI species objects. Defines species to be added from the physical point of view (e.g. charge, mass, initial distribution of particles).

• layout (PICMI_AnyLayout, list of PICMI_AnyLayout, or None) – An instance of one of the PICMI particle layout objects (or a list of them, one per initial distribution). Defines how particles are added into the simulation, from the numerical point of view.

• initialize_self_field (bool, optional) – Whether the initial space-charge fields of this species is calculated and added to the simulation

add_species_through_plane(species, layout, injection_plane_position, injection_plane_normal_vector, initialize_self_field=None)

Add species to be used in the simulation that are injected through a plane during the simulation.

Parameters:

• species (PICMI_AnySpecies) – An instance of one of the PICMI species objects. Defines species to be added from the physical point of view (e.g. charge, mass, initial distribution of particles).

• layout (PICMI_AnyLayout, list of PICMI_AnyLayout, or None) – An instance of one of the PICMI layout objects (or a list of them, one per initial distribution). Defines how particles are added into the simulation, from the numerical point of view.

• initialize_self_field (bool, optional) – Whether the initial space-charge fields of this species is calculated and added to the simulation

• injection_plane_position (float or list of float) – Position of one point of the injection plane

• injection_plane_normal_vector (list of float) – Vector normal to injection plane

extension()

Reserved for code-specific extensions, for example returns a class instance that has further methods for manipulating a PIC simulation.

run()

Run the full simulation (up to max_time or max_step are reached)

set_max_step(max_steps)

Set the default number of steps for the simulation (i.e. the number of steps that gets written when calling write_input_file).

Note: this is equivalent to passing max_steps as an argument, when initializing the Simulation object

Parameters:

max_steps (int) – Maximum number of time steps

step(nsteps=1)

Run the simulation for nsteps timesteps

Parameters:

nsteps (int, default 1) – The number of timesteps

write_input_file(file_name)

Write the parameters of the simulation, as defined in the PICMI input, into a code-specific input file.

This can be used for codes that are not Python-driven (e.g. compiled, pure C++ or Fortran codes) and expect a text input in a given format.

Parameters:

file_name (str) – The path to the file that will be created