WarpX uses the PICMI standard for its Python input files. Python version 3.7 or newer is required.
Example input files can be found in the examples section <usage-examples>. In the input file, instances of classes are created defining the various aspects of the simulation. The Simulation object is the central object, where the instances are passed, defining the simulation time, field solver, registered species, etc.
pywarpx.picmi.Simulation
For convenience, the PICMI interface defines the following constants, which can be used directly inside any PICMI script. The values are in SI units.
picmi.constants.c: The speed of light in vacuum.picmi.constants.ep0: The vacuum permittivity ϵ0picmi.constants.mu0: The vacuum permeability μ0picmi.constants.q_e: The elementary charge (absolute value of the charge of an electron).picmi.constants.m_e: The electron masspicmi.constants.m_p: The proton mass
Field solvers define the updates of electric and magnetic fields.
pywarpx.picmi.ElectromagneticSolver
pywarpx.picmi.ElectrostaticSolver
pywarpx.picmi.Cartesian3DGrid
pywarpx.picmi.Cartesian2DGrid
pywarpx.picmi.Cartesian1DGrid
pywarpx.picmi.CylindricalGrid
pywarpx.picmi.EmbeddedBoundary
pywarpx.picmi.ConstantAppliedField
pywarpx.picmi.AnalyticAppliedField
pywarpx.picmi.PlasmaLens
pywarpx.picmi.Mirror
pywarpx.picmi.ParticleDiagnostic
pywarpx.picmi.FieldDiagnostic
pywarpx.picmi.ElectrostaticFieldDiagnostic
Lab-frame diagnostics diagnostics are used when running boosted-frame simulations.
pywarpx.picmi.LabFrameFieldDiagnostic
pywarpx.picmi.Checkpoint
Species objects are a collection of particles with similar properties. For instance, background plasma electrons, background plasma ions and an externally injected beam could each be their own particle species.
pywarpx.picmi.Species
pywarpx.picmi.MultiSpecies
Particle distributions can be used for to initialize particles in a particle species.
pywarpx.picmi.GaussianBunchDistribution
pywarpx.picmi.UniformDistribution
pywarpx.picmi.AnalyticDistribution
pywarpx.picmi.ParticleListDistribution
Particle layouts determine how to microscopically place macro particles in a grid cell.
pywarpx.picmi.GriddedLayout
pywarpx.picmi.PseudoRandomLayout
Other operations related to particles
pywarpx.picmi.CoulombCollisions
pywarpx.picmi.MCCCollisions
pywarpx.picmi.FieldIonization
Laser profiles can be used to initialize laser pulses in the simulation.
pywarpx.picmi.GaussianLaser
pywarpx.picmi.AnalyticLaser
Laser injectors control where to initialize laser pulses on the simulation grid.
pywarpx.picmi.LaserAntenna
WarpX can be run in one of two modes. It can run as a preprocessor, using the Python input file to generate an input file to be used by the C++ version, or it can be run directly from Python. The examples support running in both modes by commenting and uncommenting the appropriate lines.
In either mode, if using a virtual environment, be sure to activate it before compiling and running WarpX.
For this, a full Python installation of WarpX is required, as described in the install documentation <install-users> (developers <install-developers>).
In order to run a new simulation:
- Create a new directory, where the simulation will be run.
- Add a Python script in the directory.
The input file should have the line sim.step() which runs the simulation.
- Run the script with Python:
mpirun -np <n_ranks> python <python_script>where <n_ranks> is the number of MPI ranks used, and <python_script> is the name of the script.
When running WarpX directly from Python it is possible to interact with the simulation by installing CallbackFunctions, which will execute a given Python function at a specific location in the WarpX simulation loop.
pywarpx.callbacks.CallbackFunctions
Places in the WarpX loop where callbacks are available include: afterinit, beforecollisions, aftercollisions, beforeEsolve, afterEsolve, beforeInitEsolve, afterInitEsolve, beforedeposition, afterdeposition, beforestep, afterstep, afterdiagnostics,afterrestart and oncheckpointsignal. See the examples in Examples/Tests/ParticleDataPython for references on how to use callbacks.
There are several "hooks" available via the libwarpx shared library to access and manipulate simulation objects (particles, fields and memory buffers) as well as general properties (such as processor number). These "hooks" are accessible through the Simulation.extension object.
pywarpx.picmi.Simulation.extension.getNProcs
pywarpx.picmi.Simulation.extension.getMyProc
pywarpx.picmi.Simulation.extension.get_nattr
pywarpx.picmi.Simulation.extension.get_nattr_species
pywarpx.picmi.Simulation.extension.getistep
pywarpx.picmi.Simulation.extension.gett_new
pywarpx.picmi.Simulation.extension.evolve
pywarpx.picmi.Simulation.extension.finalize
pywarpx.picmi.Simulation.extension.getProbLo
pywarpx.picmi.Simulation.extension.getProbHi
pywarpx.picmi.Simulation.extension.getCellSize
Particles can be added to the simulation at specific positions and with specific attribute values:
pywarpx.picmi.Simulation.extension.add_particles
Properties of the particles already in the simulation can be obtained with various functions.
pywarpx.picmi.Simulation.extension.get_particle_count
pywarpx.picmi.Simulation.extension.get_particle_structs
pywarpx.picmi.Simulation.extension.get_particle_arrays
The get_particle_structs() and get_particle_arrays() functions are called by several utility functions of the form get_particle_{comp_name} where comp_name is one of x, y, z, r, theta, id, cpu, weight, ux, uy or uz.
The index of some specific component of the particle data can be obtained.
pywarpx.picmi.Simulation.extension.get_particle_comp_index
New components can be added via Python.
pywarpx.picmi.Simulation.extension.add_real_comp
Various diagnostics are also accessible from Python. This includes getting the deposited or total charge density from a given species as well as accessing the scraped particle buffer. See the example in Examples/Tests/ParticleBoudaryScrape for a reference on how to interact with scraped particle data.
pywarpx.picmi.Simulation.extension.get_species_charge_sum
pywarpx.picmi.Simulation.extension.depositChargeDensity
pywarpx.picmi.Simulation.extension.get_particle_boundary_buffer_size
pywarpx.picmi.Simulation.extension.get_particle_boundary_buffer_structs
pywarpx.picmi.Simulation.extension.get_particle_boundary_buffer
pywarpx.picmi.Simulation.extension.clearParticleBoundaryBuffer
The embedded boundary conditions can be modified when using the electrostatic solver.
pywarpx.picmi.Simulation.extension.set_potential_EB
In this case, only the pure Python version needs to be installed, as described here <developers-gnumake-python>.
In order to run a new simulation:
- Create a new directory, where the simulation will be run.
- Add a Python script in the directory.
The input file should have the line like sim.write_input_file(file_name = 'inputs_from_PICMI') which runs the preprocessor, generating the AMReX inputs file.
- Run the script with Python:
python <python_script>where <python_script> is the name of the script. This creates the WarpX input file that you can run as normal with the WarpX executable.