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
picmcworkers, 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. picmcis called without a parameter file - it receives its configuration from the Python process. Runningpicmc case.parandpython3 case.pyside 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
| method | purpose |
|---|---|
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
| class | keywords |
|---|---|
Geometry | required: mesh_file, BB, NX, NY, NZ; optional: mesh_unit, DIV_X, DIV_Y, DIV_Z, BOUNDARY_CONDITIONS, BORDER_TYPES |
Border | required: icodec, type; optional: T, epsr, vf_coupling, vf, reactions |
BorderReaction | species, 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) |
Component | NREAL, P0, frozen |
Species | mr, charge, is_frozen |
ParticleReaction | species_1, species_2, sigma, message, delete_1, delete_2, threshold_eV, alpha, reaction_products, runtime_modification, unit_correction_factor |
Controller | PTARGET, PSAMPLE, RegulationFactor, RegulationScale, IntegrationTime, DifferentiationTime, VPMIN, VPMAX, VPSTART |
Sim | required: 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:
| method | records |
|---|---|
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 file | Python |
|---|---|
WORKMODE, DT, TSIM | Sim(WORKMODE = …, DT = …, TSIM = …) |
Batchfile | Sim(Batchfile = "name") |
BB, NX, NY, NZ, DIV_X/Y/Z | Geometry(…) |
BOUNDARY_CONDITIONS, BORDER_TYPES | Geometry(BOUNDARY_CONDITIONS = …, BORDER_TYPES = {…}) |
SPECIES/NREAL_<sp>/P0_<sp> | Sim(SPECIES = {"<sp>": PICMC.Component(…)}) |
species_definition.r | Sim(SPECS = pydatabase.SPECIES_LIST) |
| cross-section and reaction setup | Sim(Reactions = pydatabase.REACTION_LIST) |
NUMBER/DENSITY/ENERGY/FIELD plots, NPLOTS | Sim(Plots = {...}, NPLOTS = …) |
POLL/PSOLL/PSAMPLE, power regulation keys | Sim(PowerControl = PICMC.Controller(…)) |
RESAMPLE_SCALE and the other RESAMPLE_* keys | Sim(RESAMPLE_…), see Resampling |
add_energy_histogram, add_angular_histogram, add_histogram, add_*_histogram_array | BorderReaction.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/_energy | BorderReaction.set_emission_Thompson/_Maxwell/_energy |
SIGMA_ENERGY | Sim(SIGMA_ENERGY = …) |
TAVG | Sim(TAVG = …) |
What the interface does not cover yet
- The wall models of the wall interaction model are only partly
reachable.
BorderReactioncoversplain,transmission,specularandsourcereactions with absorption, reaction products, the emission profilesset_emission_Maxwell,set_emission_Thompsonandset_emission_energy, the spatialset_profile, and the histograms of energy and angle. What has no Python counterpart yet areset_emission_sputter(Thompson without the ion energy, i.e.Ub/alphaonly), the temperature dependent vapour sourceadd_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_profileandset_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. Materialsis accepted bySimbut 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.posfiles 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.