Skip to main content

Driving a case from Python

Status: beta. The interface ships with release 26 and covers setting up a case, stepping the simulation, sampling histograms on borders, computing or reading a magnetic field, and DSMC cases (WORKMODE = 0) including particle sources with an imported emission profile (see Sputter transport). It is still being extended, so keywords and behaviour can change within the 2.x series. The two example scripts in the repository root (energy_conservation.py, pytest_picmc.py) are marked as provisional by their authors and partly use older keywords - do not copy them unchecked.

Instead of a parameter file, a case can be described by a Python script. import PICMC provides the classes Geometry, Border, BorderReaction, Component, Species, ParticleReaction, Controller and Sim, plus BEM_Solver and BEM_Boundary for the field solver. The script builds the geometry, the species and the boundary conditions, then starts the simulation and advances it step by step. A case started this way does not read a .par file.

The price for the flexibility is that the script has to be written and maintained by hand: the parameter reference on this site documents the RVM keys, not the Python keywords, although both describe the same settings (see mapping).

How the two processes cooperate​

The Python script does not simulate anything. A run is a single MPI job with two programs:

  • exactly one Python process that executes the case script,
  • the picmc workers, which hold the mesh and the particles.

Both are started together with MPI's multiple program support:

export PICMCPATH=/path/to/picmc-26
export PYTHONPATH=$PICMCPATH/lib
export LD_LIBRARY_PATH=$PICMCPATH/lib:/lib64:$LD_LIBRARY_PATH

mpiexec --bind-to none -np 1 python3 case.py \
: -np 8 $PICMCPATH/bin/picmc

The part after the colon is the worker side. This has three consequences:

  • The job has to allocate one task more than the number of workers, because the Python process occupies one slot.
  • The Python side must run with -np 1. Several Python ranks would each initialize the simulation and fight over the workers.
  • picmc is called without a parameter file - it receives its configuration from the Python process. Running picmc case.par and python3 case.py side by side is not possible; a case is either RVM based or Python based.

PYTHONPATH has to contain <prefix>/lib, because that is where the module (PICMC.so) and the species database (pydatabase.py) are installed. PICMC_SEED works as with an RVM case.

Building and installing​

lib/PICMC.so is part of the default All target, so a normal build produces it. The build needs the Python development files; the interpreter is taken from the PYCONFIGPATH_<goal> entry in makefile.inc (for example /usr/bin/python3.11-config). The interpreter that runs a case should be the same version that was used at build time.

The installation receives:

lib/PICMC.so the module itself
lib/pydatabase.py species and reaction database
py/pysubmit.py job submission helper
py/<cluster>.json cluster configurations for pysubmit
sh/pysubmit shell submit script (builds its own SLURM file)

Submitting a run​

py/pysubmit.py is the counterpart of rvmslurm/rvmmpi: it builds a SLURM batch file and submits it. The shell script of the parameter-file route and the chaining of several runs are described in Submitting a run.

python3 $PICMCPATH/py/pysubmit.py case.py -n 8 -c IST_EPYC -t 48:00:00 -s 4711

-n/--ntasks is the number of workers - the job gets one task more, the driving Python rank. -c/--config selects the cluster configuration, -t/--time the wall time and -s/--seed the seed; -e/--exclusive, -N/--nodes, -m/--memory, -p/--partition and -l/--nodelist cover the remaining SLURM options. The generated <case>.slurm launches python3 <case>.py as one task and the worker program with -n tasks, writes <case>-out.txt and <case>-err.txt and appends the error file to the output file at the end.

One option decides which program the workers are: -b (--bem) starts bem instead of picmc. Every script that drives the field solver needs it - without it the workers are the wrong program, they ignore the solver's messages, and the run waits forever without writing output (see Computing a magnetic field with the BEM solver).

The wrapper only fills in cluster defaults; the paths come from py/<cluster>.json, installed next to pysubmit.py:

{
"default_partition": "epyc",
"allowed_partitions": ["epyc"],
"picmc_path": "~/picmc-26-EPYC",
"memory": 16000,
"mpi_path": "/opt/openmpi-5",
"mpi_exec": "mpiexec"
}

picmc_path is the only entry that usually has to be adapted to the local installation.

On a workstation without SLURM, use the mpiexec line from above directly.

Progress while the run is going​

pythonscripts/picmc_progress.py (installed to <PICMCPATH>/lib by make) prints one line per 0.01 % of the run in the style of feedback.r - percent, plot counter, time to the next plot and to the end of the run - plus a tqdm bar on a terminal:

import picmc_progress

bar = picmc_progress.create(sim, TSIM, NPLOTS)
while sim.running():
sim.step()
bar.update()
bar.close()

PICMC_PROGRESS=0 switches it off, PICMC_PROGRESS=log drops the bar, PICMC_PROGRESS_PLAIN=1 leaves every record in the log instead of updating one line for tail -f.

A minimal case script​

import PICMC
import pydatabase

geo = PICMC.Geometry(
mesh_file = "JustABox.msh",
mesh_unit = 0.1,
BB = (
(-1.0, -0.5, -0.5), # -x, -y, -z
(1.5, 0.5, 0.5) # +x, +y, +z
),
NX = [10] * 10,
NY = [10] * 4,
NZ = [10] * 4,
BOUNDARY_CONDITIONS = (
("outlet", "outlet", "outlet"),
("outlet", "outlet", "outlet")
),
BORDER_TYPES = {
"Wall": PICMC.Border(icodec = 1, type = "wall", epsr = 10.0)
}
)

sim = PICMC.Sim(
WORKMODE = 1,
DT = 5e-11,
TSIM = 1e-4,
Batchfile = "case",
Geometry = geo,
SPECIES = {
"Arplus": PICMC.Component(NREAL = 1e5, P0 = 1e13),
"e": PICMC.Component(NREAL = 1e5, P0 = 1e13)
},
Materials = [],
SPECS = pydatabase.SPECIES_LIST,
Reactions = pydatabase.REACTION_LIST,
Plots = {
"density": ["Arplus", "e"],
"energy": ["Arplus", "e"],
"FIELD": ["PHI", "E"]
},
NPLOTS = 1000,
TAVG = True
)

try:
sim.init()
while sim.running():
sim.step()
sim.exit()
except Exception:
import traceback
traceback.print_exc()
sim.exit()

SPECS and Reactions are what the RVM case takes from species_definition.r and the cross-section subroutines: pydatabase.SPECIES_LIST holds the known species with mass and charge, pydatabase.REACTION_LIST the reaction and scattering parameters. Both can be extended or replaced by own entries.

The try/except block is not decoration: an exception in the middle of a run leaves the workers waiting, and sim.exit() in the handler is what ends them. The shipped example script does the same.

JustABox.msh is the small test mesh of the repository example; replace it with a mesh of your own, created as described in the Gmsh page. The physical groups of the mesh have to match the icodec values in BORDER_TYPES.

Methods of Sim​

methodpurpose
init(reload_if_possible = False)reads the mesh, distributes the configuration to the workers, harmonizes the weights if RESAMPLE_SCALE is set; with True it continues an existing checkpoint, see Checkpoints and continuation
full_run()runs until TSIM is reached without returning control
step()advances one time cycle
running()True while the simulation time is below TSIM
get_time() / get_step()current simulation time in s / number of finished cycles
is_species_defined(name)whether a species exists in the case
read_magnetic_field(filename, file_type)reads an external magnetic field (same file formats as in the parameter file)
plot(filename, what, species_name = "")forces a plot of one field or species property
exit()tears the run down on the worker side

The loop while sim.running(): sim.step() is what makes the interface interesting: between two steps, own code can read the state, log it or change parameters. full_run() exists for cases that need none of that.

Keyword arguments of the classes​

classkeywords
Geometryrequired: mesh_file, BB, NX, NY, NZ; optional: mesh_unit, DIV_X, DIV_Y, DIV_Z, BOUNDARY_CONDITIONS, BORDER_TYPES
Borderrequired: icodec, type; optional: T, epsr, vf_coupling, vf, reactions
BorderReactionspecies, reaction_type (plain, transmission, specular, source), probability, absorption, reaction_products, product_weights, source_value, source_unit; methods set_emission_Maxwell, set_emission_Thompson, set_emission_energy, set_profile, set_probability_function, set_temperature_function, set_yield_function, set_yield2D_function, add_energy_histogram, add_angular_histogram, add_histogram and their _array variants (see histograms)
ComponentNREAL, P0, frozen
Speciesmr, charge, is_frozen
ParticleReactionspecies_1, species_2, sigma, message, delete_1, delete_2, threshold_eV, alpha, reaction_products, runtime_modification, unit_correction_factor
ControllerPTARGET, PSAMPLE, RegulationFactor, RegulationScale, IntegrationTime, DifferentiationTime, VPMIN, VPMAX, VPSTART
Simrequired: WORKMODE, DT, TSIM, Batchfile, Geometry, SPECIES, Materials; optional: Reactions, SPECS, Plots, NPLOTS, PowerControl, TAVG, SIGMA_ENERGY, all RESAMPLE_* keys

Border.vf accepts a number or a callable object, so a voltage boundary condition can be a Python function instead of a fixed value or a table. The callable is called without arguments at every solve cycle; read the time inside it with sim.get_time(). Sim.PowerControl takes a Controller object and replaces PSOLL/PSAMPLE plus the power regulation keys of the parameter file; the two input forms differ in their defaults, see power regulation.

Histograms on borders​

A border can record what hits it - energy, angle, or both, per species. This is the sampling the parameter file offers for walls and membranes; file names, columns and the handling of the reference direction are the same, see Energy/angle sampling.

The methods sit on the BorderReaction of the border and return the object, so calls can be chained:

methodrecords
add_energy_histogram(species, E0, E1, nE)energy in nE bins over [E0, E1]
add_angular_histogram(species, nTheta, nPhi, v)polar angle θ in [0°, 90°] and azimuth φ in [0°, 360°]
add_histogram(species, nTheta, nPhi, E0, E1, nE, v)both, as a correlated distribution
add_energy_histogram_array(species, nX, nY, x0, x1, x2, E0, E1, nE)the energy histogram resolved over an array on the surface
add_angular_histogram_array(species, nTheta, nPhi, nX, nY, x0, x1, x2)the angular histogram resolved over an array
add_histogram_array(species, nTheta, nPhi, nX, nY, x0, x1, x2, E0, E1, nE)both, resolved over an array

v is the reference direction of the azimuth, given as a tuple (vx, vy, vz). x0, x1 and x2 are three corners of the rectangle that the array covers on the surface, each a tuple (x, y, z); nX and nY are its number of subdivisions. The corners are given in the unit of the mesh file, that is in the unit of Geometry(mesh_unit = …). Wrong units raise no error: the grid then misses the surface and every hit ends up in a single cell. The array only works on a plane surface. In the combined methods E0, E1 and nE are optional and fall back to 0 to 1000 eV in a single bin, which is what the two single-purpose methods use for the dimension they do not sample. Mind the total number of bins nTheta * nPhi * nE - the same caveat as in the parameter file applies.

Arplus_on_membrane = (
PICMC.BorderReaction(species = "Arplus", reaction_type = "transmission", probability = 1.0)
.add_histogram(species = "Arplus", nTheta = 18, nPhi = 36,
v = (1.0, 0.0, 0.0), E0 = 0.0, E1 = 200.0, nE = 40)
)

membrane = PICMC.Border(icodec = 10, type = "membrane", reactions = [Arplus_on_membrane])

The histogram is taken on the physical surface of the border that carries the reaction. Every call creates its own histogram with its own numbered output file, as the file names with the running number suggest - nothing is merged. As in the parameter file, a membrane only samples the side its normal points to.

Mapping of parameter file keys​

parameter filePython
WORKMODE, DT, TSIMSim(WORKMODE = …, DT = …, TSIM = …)
BatchfileSim(Batchfile = "name")
BB, NX, NY, NZ, DIV_X/Y/ZGeometry(…)
BOUNDARY_CONDITIONS, BORDER_TYPESGeometry(BOUNDARY_CONDITIONS = …, BORDER_TYPES = {…})
SPECIES/NREAL_<sp>/P0_<sp>Sim(SPECIES = {"<sp>": PICMC.Component(…)})
species_definition.rSim(SPECS = pydatabase.SPECIES_LIST)
cross-section and reaction setupSim(Reactions = pydatabase.REACTION_LIST)
NUMBER/DENSITY/ENERGY/FIELD plots, NPLOTSSim(Plots = {...}, NPLOTS = …)
POLL/PSOLL/PSAMPLE, power regulation keysSim(PowerControl = PICMC.Controller(…))
RESAMPLE_SCALE and the other RESAMPLE_* keysSim(RESAMPLE_…), see Resampling
add_energy_histogram, add_angular_histogram, add_histogram, add_*_histogram_arrayBorderReaction.add_*_histogram(…), see Histograms on borders
add_absorption("sp", p)BorderReaction(species = "sp", absorption = True, probability = p)
add_source("sp", v, "sccm"/"Pa")BorderReaction(species = "sp", reaction_type = "source", source_value = v, source_unit = "sccm")
set_profile("file.pos")BorderReaction.set_profile("file.pos"), see Sputter transport
set_emission_thompson/_maxwell/_energyBorderReaction.set_emission_Thompson/_Maxwell/_energy
SIGMA_ENERGYSim(SIGMA_ENERGY = …)
TAVGSim(TAVG = …)

What the interface does not cover yet​

  • The wall models of the wall interaction model are only partly reachable. BorderReaction covers plain, transmission, specular and source reactions with absorption, reaction products, the emission profiles set_emission_Maxwell, set_emission_Thompson and set_emission_energy, the spatial set_profile, and the histograms of energy and angle. What has no Python counterpart yet are set_emission_sputter (Thompson without the ion energy, i.e. Ub/alpha only), the temperature dependent vapour source add_vapor_source, the formula-based emitters (set_emission_function_*), the energy loss functions and the surface chemistry of the RVM side, so those pages show RVM examples only.
  • Note the order inside Border.reactions: set_profile and set_emission_* attach to the reaction that was declared last, so a source reaction with an emission profile has to be listed after the reactions of the same border.
  • Materials is accepted by Sim but the code marks it as unfinished.
  • There is no Python counterpart of the ppp post-processing module. Sim.plot() writes single snapshots during the run; the regular evaluation still runs on the .pos files as described in Postprocessing.
  • The interface is one Python rank by design, so analysis that needs the particle data of all workers has to happen after the run, not inside the script.