Simulation
The Simulation object is the central object in a PICMI script. It defines the simulation time, field solver, registered species, etc.
- class picmistandard.PICMI_Simulation(**extra_data: Any)[source]
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
Creates a Simulation object.
- field solver: PICMI_ElectromagneticSolver | PICMI_ElectrostaticSolver | PICMI_MagnetostaticSolver | None = None
Field solver instance. This is the field solver to be used in the simulation. It should be an instance of field solver classes (PICMI_ElectromagneticSolver, PICMI_ElectrostaticSolver, or PICMI_MagnetostaticSolver).
- field time_step_size: float | None = None
Absolute time step size of the simulation [s]. Needed if the CFL is not specified elsewhere.
- field verbose: int | None = None
Verbosity flag. A larger integer results in more verbose output
- field max_steps: int | None = None
Maximum number of time steps. Specify either this, or max_time, or use the step function directly.
- field 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.
- field particle_shape: Literal['NGP', 'linear', 'quadratic', 'cubic'] = 'linear'
Default particle shape for species added to this simulation
- field gamma_boost: float | None = None
Lorentz factor of the boosted simulation frame. Note that all input values should be in the lab frame.
- field load_balancing: Any = None
Load balancing configuration
- field species: list[PICMI_Species | PICMI_MultiSpecies] [Optional]
- field layouts: list[PICMI_GriddedLayout | PICMI_PseudoRandomLayout | PICMI_ParticleDistributionPlanarInjector] [Optional]
- field initialize_self_fields: list[bool | None] [Optional]
- field injection_plane_positions: list[Sequence[float] | None] [Optional]
- field injection_plane_normal_vectors: list[Sequence[float] | None] [Optional]
- field lasers: list[PICMI_GaussianLaser | PICMI_AnalyticLaser] [Optional]
- field laser_injection_methods: list[PICMI_LaserAntenna] [Optional]
- field applied_fields: list[PICMI_ConstantAppliedField | PICMI_AnalyticAppliedField | PICMI_Mirror | PICMI_LoadAppliedField | PICMI_LoadGriddedField] [Optional]
- field diagnostics: list[PICMI_FieldDiagnostic | PICMI_ElectrostaticFieldDiagnostic | PICMI_ParticleDiagnostic | PICMI_ParticleBoundaryScrapingDiagnostic | PICMI_LabFrameFieldDiagnostic | PICMI_LabFrameParticleDiagnostic] [Optional]
- field interactions: list[PICMI_FieldIonization] [Optional]
List of interaction objects
- add_species(species: PICMI_Species | PICMI_MultiSpecies, layout: PICMI_GriddedLayout | PICMI_PseudoRandomLayout | PICMI_ParticleDistributionPlanarInjector, initialize_self_field: bool | None = None)[source]
Add species to be used in the simulation
- Parameters:
species (species instance) – 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 (layout instance) – An instance of one of the PICMI particle layout objects. 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: PICMI_Species | PICMI_MultiSpecies, layout: PICMI_GriddedLayout | PICMI_PseudoRandomLayout | PICMI_ParticleDistributionPlanarInjector, injection_plane_position: Sequence[float], injection_plane_normal_vector: Sequence[float], initialize_self_field: bool | None = None)[source]
Add species to be used in the simulation that are injected through a plane during the simulation.
- Parameters:
species (species instance) – 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 (layout instance) – An instance of one of the PICMI layout objects. 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 (vector of floats) – Position of one point of the injection plane
injection_plane_normal_vector (vector of floats) – Vector normal to injection plane
- add_laser(laser: PICMI_GaussianLaser | PICMI_AnalyticLaser, injection_method: PICMI_LaserAntenna)[source]
Add a laser pulses that to be injected in the simulation
- Parameters:
laser_profile (laser instance) – One of laser profile instances. Specifies the physical properties of the laser pulse (e.g. spatial and temporal profile, wavelength, amplitude, etc.).
injection_method (laser injection instance, optional) – 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_applied_field(applied_field: PICMI_ConstantAppliedField | PICMI_AnalyticAppliedField | PICMI_Mirror | PICMI_LoadAppliedField | PICMI_LoadGriddedField)[source]
Add an applied field
- Parameters:
applied_field (applied field instance) – One of the applied field instance. Specifies the properties of the applied field.
- add_diagnostic(diagnostic: PICMI_FieldDiagnostic | PICMI_ElectrostaticFieldDiagnostic | PICMI_ParticleDiagnostic | PICMI_ParticleBoundaryScrapingDiagnostic | PICMI_LabFrameFieldDiagnostic | PICMI_LabFrameParticleDiagnostic)[source]
Add a diagnostic
- Parameters:
diagnostic (diagnostic instance) – One of the diagnostic instances.
- add_interaction(interaction: PICMI_FieldIonization)[source]
Add an interaction
- Parameters:
interaction (interaction instance) – One of the interaction objects.
- set_max_step(max_steps: int)[source]
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
Parameter
- max_steps: integer
Maximum number of time steps
- write_input_file(file_name: str)[source]
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 (string) – The path to the file that will be created