Skip to main content

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:

  1. a Parameters object with everything that is fixed for the run,
  2. a pyPALADINServer object built from it,
  3. 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​

KeyMeaning
MESH_FILEGmsh .msh file with the volume mesh and physical groups
UNITLength 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:

KeyMeaning
BBBounding box as (x_min, y_min, z_min, x_max, y_max, z_max) in UNIT
BB_OPTIONSOne entry per direction: BB_SOLID, BB_PERIODIC, BB_OUT_MIN, BB_OUT_MAX or BB_OUT
MESH_DIVISIONResolution 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:

FieldMeaning
icodecPhysical group number in the mesh
typeWALL_TYPE_SPECULAR, WALL_TYPE_DIFFUSE or WALL_TYPE_MEMBRANE
elasticityRestitution of the impact, 1.0 = elastic, 0.0 = fully absorbing in the normal direction
destructionThe particle is removed when it hits this border
trackingThe border records impacts and origins, which is what a backtrace dump needs
ejection_speedSpeed 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:

ArgumentMeaning
scalarConstant scalar value
vectorConstant vector, e.g. (0, 0, -GRAVITATIONAL_ACCELERATION)
fieldPath to a .pos file with the field, scalar or vector
potentialPath to a .pos file with a scalar potential; the field is the negative gradient
unitUnit of the values in the file
default_if_zeroUse the constant instead of a cell whose file value is zero
noneExplicitly 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 what spawn_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:

FieldMeaning
size_distribution_typeDISTRIBUTION_CONSTANT, DISTRIBUTION_UNIFORM, DISTRIBUTION_LOG_NORMAL or DISTRIBUTION_WEIBULL
size_distribution_param_1, ..._2Radius parameters in metres; for the uniform distribution the lower and upper bound
mass_densityDensity of the particle material
dry_mass_densityDensity of the non-volatile core, for droplets
initial_charge_densityCharge per volume at the start, in C/m³
relative_permittivityFor the polarisation force
hamaker_constantFor the van der Waals adhesion
minimum_wall_distanceDistance at which the adhesion is evaluated
vapour propertiessaturation_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_surface distributes particles over the triangles of a border and gives them the border's ejection_speed along the surface normal. This is the usual start for a contamination study: particles are released where they are produced.
  • spawn_particles places particles at one point with one velocity. Useful for a single test particle.
  • inject_test_particle / inject_test_particles add particles during a run, for example from an each_tick callback.

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
OptionMeaning
-n <n>Number of client ranks
-N <n>Number of nodes
-partition <p>, -time <hh:mm:ss>, -mem <MB>, -exclude <list>, -exclusiveSlurm settings
-dummyOnly write the batch file, do not submit
-testWrite 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:

OptionMeaning
file_templateName fragment; the file becomes <NAME>_<file_template>
valuesList of quantities to write, see constants and units
value_unitsOne entry per quantity, in which unit it is written
total_numberNumber of dumps over the whole run
modeDUMP_ALL_IN_ONE (one file, one block per step) or DUMP_SEPARATE (one file per step)
formatFORMAT_GMSH_POS, FORMAT_TXT, FORMAT_GMSH_MSH or FORMAT_EMDI_DMP
additional_pathSubdirectory inside the run directory
particle_speciesRestrict the dump to one species
collision_dumperWrite only on collisions
loss_dumperWrite only particles that left the volume
additional_dump_at_startWrite the initial state as well
add_counterAppend a running number to the file name
file_float_precision, binaryFormatting

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.

CaseWhat it isWhat it teaches
Example_CapacitorTwo walls, a constant electric field, no plasma, ten 1 µm particles, 2.5 sThe minimal case: field plus gravity, one dumper, nothing else
Example_ChargingUniform electron and argon ion density of 10¹⁰ m⁻³ (10⁴ cm⁻³) at 10⁴ K, five test particles, a strong magnetic fieldCharging of a particle in a homogeneous plasma; dumps of charge and potential over time
Example_MagnetronPICMC fields of the EOSS® geometry read from .pos files, 1–2 µm particles, 100 released from each targetThe realistic workflow: fields from files, backtrace dumpers, collision dumpers, a size distribution
Example_TubeGas density, pressure, temperature, velocity and heat flux from a flow solution, mesh in millimetres, walls, inlet and pumpA 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 = METER puts 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_CLIENT makes a run reproducible. Change it deliberately, not accidentally.