Building a scenario
A PALADIN case is a Python script. The script describes the geometry, the fields, the species and the output, starts the server object and lets it run. Everything else — moving the particles, charging them, resolving wall collisions — happens in the C++ part, which is distributed over the MPI client ranks.
A script therefore has three parts, always in the same order:
- a
Parametersobject with everything that is fixed for the run, - a
pyPALADINServerobject built from it, - the particle initialisation and
run().
The smallest complete case, a capacitor with a constant field and ten dust particles:
from pyPALADINServer import *
pars = Parameters(
NAME = "Capacitor",
DT = 0.001*SECOND,
TSIM = 2.5*SECOND,
MESH_FILE = "capacitor.msh",
UNIT = METER,
BB = (-1.1, -0.6, -0.05, 1.1, 0.6, 0.0),
BB_OPTIONS = (BB_SOLID, BB_SOLID, BB_PERIODIC),
MESH_DIVISION = (10, 5, 1),
BORDER_TYPES = {
"Inside": pyPALADIN.Border(icodec = 1, type = WALL_TYPE_SPECULAR),
"Outside": pyPALADIN.Border(icodec = 2, type = WALL_TYPE_SPECULAR)
},
GRAVITY = pyPALADIN.Field(vector = (0, -GRAVITATIONAL_ACCELERATION, 0)),
ELECTRIC = pyPALADIN.Field(vector = (1*VOLT*PER(METER), 0, 0)),
PLASMA_SPECIES_LIST = {},
SPECIES_LIST = {
"Dust": pyPALADIN.Species(
size_distribution_type = DISTRIBUTION_CONSTANT,
size_distribution_param_1 = 1*MICRO*METER,
mass_density = 1000*KILOGRAM*PER(CUBIC(METER))
)
},
DUMPER_INSTANCES = {
"Tracer": pyPALADIN.DumperInstance(
file_template = "tracer",
total_number = round(TSIM/DT),
mode = DUMP_ALL_IN_ONE,
values = [DUMP_SCALAR_TIME],
value_units = [SECOND],
format = FORMAT_GMSH_POS,
additional_dump_at_start = True
)
},
SEED_FOR_FIRST_CLIENT = 1234
)
server = pyPALADINServer(pars)
server.spawn_particles_on_surface(10, border_name = "Inside", species_name = "Dust")
server.run()
The Parameters object is checked before anything is started: a wrong type, a missing entry or
a time step larger than the simulated time stops the script with a message instead of a crash
in the middle of a run.
Geometry and mesh
| Key | Meaning |
|---|---|
MESH_FILE | Gmsh .msh file with the volume mesh and physical groups |
UNIT | Length unit of the mesh file, in metres. A mesh in millimetres uses MILLI*METER |
The physical groups of the mesh are what connects the geometry to the physics: each of them is
addressed by its icodec, the number given in the mesh. Which wall is the target, which is the
substrate, which one is an inlet is decided in the script, not in the mesh file.
The mesh has to resolve the geometry, not the particle. Particles are points with a radius; all fields are interpolated from the cell centres of the mesh, so the cell size sets the resolution of the field a particle sees.
Simulation volume
The volume the particles live in is described independently of the mesh:
| Key | Meaning |
|---|---|
BB | Bounding box as (x_min, y_min, z_min, x_max, y_max, z_max) in UNIT |
BB_OPTIONS | One entry per direction: BB_SOLID, BB_PERIODIC, BB_OUT_MIN, BB_OUT_MAX or BB_OUT |
MESH_DIVISION | Resolution of the internal element lookup grid, as (nx, ny, nz) |
BB_SOLID closes the box with a wall, BB_PERIODIC wraps it, and the BB_OUT* variants let a
particle leave.
MESH_DIVISION is not about the parallelisation: it subdivides the bounding box into a lookup
grid in which every mesh triangle is registered, so that a wall collision only tests the
triangles of the neighbourhood instead of all of them. The product nx · ny · nz is the number
of grid cells and therefore the memory the lookup costs; a grid that is too coarse leaves many
triangles per cell and costs collision tests, a grid that is too fine costs memory for the cells.
The tube example uses (100, 100, 100) for a mesh that covers the whole tube.
The clients split the particles, not the volume: each client owns a share of the particles and carries the whole geometry, so the number of clients is a free choice.
Walls
BORDER_TYPES is a dictionary of named borders. Each entry is a Border with the icodec of
a physical group from the mesh:
| Field | Meaning |
|---|---|
icodec | Physical group number in the mesh |
type | WALL_TYPE_SPECULAR, WALL_TYPE_DIFFUSE or WALL_TYPE_MEMBRANE |
elasticity | Restitution of the impact, 1.0 = elastic, 0.0 = fully absorbing in the normal direction |
destruction | The particle is removed when it hits this border |
tracking | The border records impacts and origins, which is what a backtrace dump needs |
ejection_speed | Speed normal to the surface that particles get when they are spawned on this border |
The wall types differ in what happens to the tangential motion: a specular wall mirrors the particle, a diffuse wall re-emits it with a randomised direction at unchanged speed, and a membrane leaves the velocity untouched so the particle passes through the surface. What adheres and what bounces is decided by the particle model — the adhesion section has the details.
Note: WALL_TYPE_SPECULAR is the name in the Python interface. The corresponding type in
the C++ code is called WALL_TYPE_WALL; both mean the same thing.
Fields
A field is always a pyPALADIN.Field. It can be a constant, a file, or a file with a constant
fallback:
| Argument | Meaning |
|---|---|
scalar | Constant scalar value |
vector | Constant vector, e.g. (0, 0, -GRAVITATIONAL_ACCELERATION) |
field | Path to a .pos file with the field, scalar or vector |
potential | Path to a .pos file with a scalar potential; the field is the negative gradient |
unit | Unit of the values in the file |
default_if_zero | Use the constant instead of a cell whose file value is zero |
none | Explicitly no field |
The three fields a case can have are fixed slots:
ELECTRIC— either from a potential (PICMC writes the potential, so this is the normal route) or as a constant vector.MAGNETIC— from a file or constant; only needed if the particles are charged and the field is strong enough to bend their path.GRAVITY— almost always the constant(0, 0, -GRAVITATIONAL_ACCELERATION).
default_if_zero exists for a practical reason: a plasma field from PICMC is zero outside the
plasma region, and without the flag the particle would see a temperature of 0 K there instead
of the neutral gas temperature.
Species
Two lists, and the distinction matters:
PLASMA_SPECIES_LIST— the charged species of the plasma (electrons, ions, sometimes negative ions). They do not move; they provide the currents that charge the particles and the gas properties for drag and thermophoresis.SPECIES_LIST— the particle species that are actually traced. This is whatspawn_particles*refers to.
A PlasmaSpecies in practice needs mass, density and temperature; charge is the charge
number (−1 for electrons, +1 for singly charged ions). Optional entries are velocity,
pressure, temperature_gradient, pressure_gradient, heat_flux, cross_section,
dynamic_viscosity, heat_conductivity and relative_humidity. Each of them is a Field, so
every one can come from a file.
Warning: the defaults of these entries are placeholders — a mass of 1 kg, a viscosity of 1 Pa·s and a relative humidity of 1.0. Set the properties of your gas explicitly; a humidity of 1.0 means saturated vapour, which makes every droplet in the case grow instead of evaporate.
A Species (the traced particle) has:
| Field | Meaning |
|---|---|
size_distribution_type | DISTRIBUTION_CONSTANT, DISTRIBUTION_UNIFORM, DISTRIBUTION_LOG_NORMAL or DISTRIBUTION_WEIBULL |
size_distribution_param_1, ..._2 | Radius parameters in metres; for the uniform distribution the lower and upper bound |
mass_density | Density of the particle material |
dry_mass_density | Density of the non-volatile core, for droplets |
initial_charge_density | Charge per volume at the start, in C/m³ |
relative_permittivity | For the polarisation force |
hamaker_constant | For the van der Waals adhesion |
minimum_wall_distance | Distance at which the adhesion is evaluated |
| vapour properties | saturation_pressure, latent_heat, diffusivity, molar_fraction, specific_heat_p, vapor_gas_constant and their temperature derivatives |
An empty PLASMA_SPECIES_LIST is legitimate: without plasma species no current reaches the
particle, so it keeps the charge it was given and only the neutral-gas forces act on it.
Starting particles
server.spawn_particles_on_surface(100, border_name = "T1", species_name = "Sample")
server.spawn_particles(50, species_name = "Sample",
position = (0.1, 0.0, 0.02),
velocity = (0.0, 0.0, 1.0))
spawn_particles_on_surfacedistributes particles over the triangles of a border and gives them the border'sejection_speedalong the surface normal. This is the usual start for a contamination study: particles are released where they are produced.spawn_particlesplaces particles at one point with one velocity. Useful for a single test particle.inject_test_particle/inject_test_particlesadd particles during a run, for example from aneach_tickcallback.
Both are called before run(); the initial dump is taken after spawning.
Running a case
pyPALADINServer(pars) creates the run directory, initialises the mesh, distributes the volume
over the clients and prepares the dumpers. run() then advances the simulation until TSIM is
reached, writes the dumps at their intervals and prints the progress block.
The run directory is created next to the script and is named after NAME. All dumps and log
files go there, unless DUMP_PATH or LOGFILE_PATH point to a subdirectory.
Two attributes of the server object change the console behaviour:
server.show_interface = True # progress block, False for batch jobs
server.interface_update_interval = 100 # time steps between two updates
Callbacks
The server object can call a function during the run:
def each_tick(server):
if server.get_time() > 0.05:
server.reload_field("ELECTRIC")
server.each_tick = each_tick
each_tick runs once per time step, at_time(value) and every_n_steps(n) are helpers to test
against the current time. This is the hook for time-dependent fields: PICMC fields are written
per time slice, and reload_field reads the next one. reload_field_unit changes the unit of a
field file, reload_trait and reload_trait_unit do the same for the entries of a plasma
species, and push_field_to_cache / reload_field_from_cache keep a loaded field in memory
instead of reading the file again.
Launching
The Python script is one MPI rank; the clients are the others. On a machine without a batch
system, the whole run is one mpiexec line with two MPMD parts:
export PALADINPATH=/path/to/paladin
export PYTHONPATH=$PALADINPATH/libs:$PALADINPATH/python_scripts:$PYTHONPATH
export LD_LIBRARY_PATH=$PALADINPATH/libs:$LD_LIBRARY_PATH
mpiexec -np 1 --bind-to none python3 case.py : -np 8 $PALADINPATH/start_client
The number of clients is free: each of them receives its share of the particles. On a Slurm cluster, submit_py writes the batch script and
submits it:
./submit_py -n 8 -partition epyc -time 24:00:00 case.py
| Option | Meaning |
|---|---|
-n <n> | Number of client ranks |
-N <n> | Number of nodes |
-partition <p>, -time <hh:mm:ss>, -mem <MB>, -exclude <list>, -exclusive | Slurm settings |
-dummy | Only write the batch file, do not submit |
-test | Write the batch file and submit it as a test job |
-valgrind <log>, -callgrind <log>, -massif <log> | Run server and clients under Valgrind |
-dummy is the fastest way to see what the job would look like: it produces
<script>.slurm next to the case.
Output
A dumper instance is one output file family. Its options:
| Option | Meaning |
|---|---|
file_template | Name fragment; the file becomes <NAME>_<file_template> |
values | List of quantities to write, see constants and units |
value_units | One entry per quantity, in which unit it is written |
total_number | Number of dumps over the whole run |
mode | DUMP_ALL_IN_ONE (one file, one block per step) or DUMP_SEPARATE (one file per step) |
format | FORMAT_GMSH_POS, FORMAT_TXT, FORMAT_GMSH_MSH or FORMAT_EMDI_DMP |
additional_path | Subdirectory inside the run directory |
particle_species | Restrict the dump to one species |
collision_dumper | Write only on collisions |
loss_dumper | Write only particles that left the volume |
additional_dump_at_start | Write the initial state as well |
add_counter | Append a running number to the file name |
file_float_precision, binary | Formatting |
Typical set for a contamination study: one dumper with positions over time
(FORMAT_GMSH_POS, small total_number), one collision dumper with velocities and kinetic
energy, one loss dumper, and one final dump with the backtrace quantities
DUMP_SCALAR_STARTING_ELEMENT_ID and DUMP_SCALAR_LAST_SURFACE_TAG — that pair is what makes
"particles came from the target" a checkable statement.
For a backtrace, the relevant borders need tracking = True; without it the origin is not
recorded.
Warning: total_number is spread over the run, not a time interval. A value of
round(TSIM/DT) writes every step and fills the disk quickly with many particles; the magnetron
example deliberately uses round(TSIM/DT/10) for the trajectory dump.
Controlling a running job
signal_helper sends commands to a running job by process name:
$PALADINPATH/signal_helper -s d server # dump now
$PALADINPATH/signal_helper -s p server # pause
$PALADINPATH/signal_helper -s u server # continue
$PALADINPATH/signal_helper -s s server # shut down in an orderly way
$PALADINPATH/signal_helper -s k server # kill
The letters can be combined, and c[...] sends a custom command. -h prints the help.
Shipped example cases
The examples that come with a make full build are small on purpose: each one isolates a
different part of the workflow.
| Case | What it is | What it teaches |
|---|---|---|
Example_Capacitor | Two walls, a constant electric field, no plasma, ten 1 µm particles, 2.5 s | The minimal case: field plus gravity, one dumper, nothing else |
Example_Charging | Uniform electron and argon ion density of 10¹⁰ m⁻³ (10⁴ cm⁻³) at 10⁴ K, five test particles, a strong magnetic field | Charging of a particle in a homogeneous plasma; dumps of charge and potential over time |
Example_Magnetron | PICMC fields of the EOSS® geometry read from .pos files, 1–2 µm particles, 100 released from each target | The realistic workflow: fields from files, backtrace dumpers, collision dumpers, a size distribution |
Example_Tube | Gas density, pressure, temperature, velocity and heat flux from a flow solution, mesh in millimetres, walls, inlet and pump | A gas-flow case without a plasma: aerosol transport in a tube, large MESH_DIVISION |
Warning: the example scripts reference their mesh and field files as ../…, because the
working directory of a run is meant to be a subdirectory of the case. Running the script
directly in the example folder fails to find the files. Copy the script into a subdirectory of
the case, start it there, and the run directory appears next to it.
Before a long run
- Check
MESH_DIVISION: a grid that is too coarse makes wall collisions slow, one that is too fine costs memory before the run even starts. - Check the unit of the mesh. A mesh in millimetres with
UNIT = METERputs every particle outside the volume, and the run ends immediately with everything lost. - Check that every physical group that particles can hit is in
BORDER_TYPES. - Start with a small number of particles and
additional_dump_at_start = True; if the initial state already looks wrong in ParaView, the fields or the geometry are wrong, not the physics. SEED_FOR_FIRST_CLIENTmakes a run reproducible. Change it deliberately, not accidentally.