Simulations

The simulation is started with:

./ascot5_main --in=in --out=out

or when using mpirun (or srun):

mpirun ./ascot5_main

The default file for reading inputs and storing outputs is ascot.h5 but these can be given explicitly (storing output in the same file with the inputs is recommended):

mpirun ./ascot5_main --in=in --out=out

The simulation can be given a description but this can be done in post-processing as well:

ascot5_main --d="TEST This is a test run"

The default behavior is to use inputs that are marked as active in the file, but this can be overridden by providing the input QID explicitly:

ascot5_main --bfield=0123456789

When not using MPI, it is possible to divide the simulation into separate processes manually with:

ascot5_main --mpi_size=size --mpi_rank=rank

Options

Simulation options are listed below. Click on the parameter name for more details. Note that the first underscore does not belong in a parameter name and only appear here for technical reasons.

Simulation mode and time step

_SIM_MODE	Simulation mode (1, 2, 3, 4)
_ENABLE_ADAPTIVE	Use adaptive time-step (0, 1)
_RECORD_MODE	Record GOs as GCs in diagnostics (0, 1)
_FIXEDSTEP_USE_USERDEFINED	Define fixed time-step value explicitly (0,1)
_FIXEDSTEP_USERDEFINED	User-defined time-step [s]
_FIXEDSTEP_GYRODEFINED	Time-step is 2pi / ( gyrofrequency * N ) where N is this parameter
_ADAPTIVE_TOL_ORBIT	Relative error tolerance for orbit following in adaptive scheme
_ADAPTIVE_TOL_CCOL	Relative error tolerance for Coulomb collisions in adaptive scheme
_ADAPTIVE_MAX_DRHO	Maximum allowed change in rho during one time-step in adaptive scheme
_ADAPTIVE_MAX_DPHI	Maximum allowed change in phi during one time-step in adaptive scheme

Simulation end conditions

_ENDCOND_SIMTIMELIM	Terminate when marker time passes ENDCOND_LIM_SIMTIME or when marker time has advanced ENDCOND_MAX_MILEAGE in a simulation
_ENDCOND_CPUTIMELIM	Terminate marker when the computer has spent ENDCOND_MAX_CPUTIME amount of real time to simulate it
_ENDCOND_RHOLIM	Terminate if marker goes outside given rho boundaries
_ENDCOND_ENERGYLIM	Terminate when marker energy is below a user-specified value
_ENDCOND_WALLHIT	Terminate when marker intersects a wall element
_ENDCOND_MAXORBS	Terminate when marker has completed user-specified number of orbits
_ENDCOND_NEUTRALIZED	Terminate when the marker becomes neutral
_ENDCOND_IONIZED	Terminate when the marker becomes ionized.
_ENDCOND_LIM_SIMTIME	Time when the simulation stops [s]
_ENDCOND_MAX_MILEAGE	The maximum amount of time this marker is simulated [s]
_ENDCOND_MAX_CPUTIME	Maximum cpu time per marker [s]
_ENDCOND_MAX_RHO	Maximum rho value
_ENDCOND_MIN_RHO	Minimum rho value
_ENDCOND_MIN_ENERGY	Minimum energy [eV]
_ENDCOND_MIN_THERMAL	Minimum energy limit is local ion thermal energy times this value
_ENDCOND_MAX_TOROIDALORBS	Maximum number of toroidal orbits
_ENDCOND_MAX_POLOIDALORBS	Maximum number of poloidal orbits

Active physics

_ENABLE_ORBIT_FOLLOWING	Trace markers in an electromagnetic field
_ENABLE_COULOMB_COLLISIONS	Markers experience Coulomb collisions with background plasma
_ENABLE_MHD	Include MHD perturbations to orbit-following
_ENABLE_ATOMIC	Markers can undergo atomic reactions with background plasma or neutrals
_DISABLE_FIRSTORDER_GCTRANS	Disable first order guiding center transformation in velocity space
_DISABLE_ENERGY_CCOLL	Disable guiding center energy collisions
_DISABLE_PITCH_CCOLL	Disable guiding center pitch collisions
_DISABLE_GCDIFF_CCOLL	Disable guiding center spatial diffusion

Distributions

_ENABLE_DIST_5D	Collect distribution histogram in [R, phi, z, ppa, ppe, t, q]
_ENABLE_DIST_6D	Collect distribution histogram in [R, phi, z, pR, pphi, pz, t, q]
_ENABLE_DIST_RHO5D	Collect distribution histogram in [rho, pol, phi, ppa, ppe, t, q]
_ENABLE_DIST_RHO6D	Collect distribution histogram in [rho, pol, phi, pR, pphi, pz, t, q]
_DIST_MIN_R	Minimum bin edge for R coordinate [m]
_DIST_MAX_R	Maximum bin edge for R coordinate [m]
_DIST_NBIN_R	Number of bins the interval [MIN_R, MAX_R] is divided to
_DIST_MIN_PHI	Minimum bin edge for phi coordinate [deg]
_DIST_MAX_PHI	Maximum bin edge for phi coordinate [deg]
_DIST_NBIN_PHI	Number of bins the interval [MIN_PHI, MAX_PHI] is divided to
_DIST_MIN_Z	Minimum bin edge for z coordinate [m]
_DIST_MAX_Z	Maximum bin edge for z coordinate [m]
_DIST_NBIN_Z	Number of bins the interval [MIN_Z, MAX_Z] is divided to
_DIST_MIN_RHO	Minimum bin edge for rho coordinate [1]
_DIST_MAX_RHO	Maximum bin edge for rho coordinate [1]
_DIST_NBIN_RHO	Number of bins the interval [MIN_RHO, MAX_RHO] is divided to
_DIST_MIN_THETA	Minimum bin edge for theta coordinate [deg]
_DIST_MAX_THETA	Maximum bin edge for theta coordinate [deg]
_DIST_NBIN_THETA	Number of bins the interval [MIN_THETA, MAX_THETA] is divided to
_DIST_MIN_PPA	Minimum bin edge for ppa coordinate [kg m/s]
_DIST_MAX_PPA	Maximum bin edge for ppa coordinate [kg m/s]
_DIST_NBIN_PPA	Number of bins the interval [MIN_PPA, MAX_PPA] is divided to
_DIST_MIN_PPE	Minimum bin edge for ppe coordinate [kg m/s]
_DIST_MAX_PPE	Maximum bin edge for ppe coordinate [kg m/s]
_DIST_NBIN_PPE	Number of bins the interval [MIN_PPE, MAX_PPE] is divided to
_DIST_MIN_PR	Minimum bin edge for pR coordinate [kg m/s]
_DIST_MAX_PR	Maximum bin edge for pR coordinate [kg m/s]
_DIST_NBIN_PR	Number of bins the interval [MIN_PR, MAX_PR] is divided to
_DIST_MIN_PPHI	Minimum bin edge for pphi coordinate [kg m/s]
_DIST_MAX_PPHI	Maximum bin edge for pphi coordinate [kg m/s]
_DIST_NBIN_PPHI	Number of bins the interval [MIN_PPHI, MAX_PPHI] is divided to
_DIST_MIN_PZ	Minimum bin edge for pz coordinate [kg m/s]
_DIST_MAX_PZ	Maximum bin edge for pz coordinate [kg m/s]
_DIST_NBIN_PZ	Number of bins the interval [MIN_PZ, MAX_PZ] is divided to
_DIST_MIN_TIME	Minimum bin edge for time coordinate [s]
_DIST_MAX_TIME	Maximum bin edge for time coordinate [s]
_DIST_NBIN_TIME	Number of bins the interval [MIN_TIME, MAX_TIME] is divided to
_DIST_MIN_CHARGE	Minimum bin edge for charge coordinate [e]
_DIST_MAX_CHARGE	Maximum bin edge for charge coordinate [e]
_DIST_NBIN_CHARGE	Number of bins the interval [MIN_CHARGE, MAX_CHARGE] is divided to

Constant of motion distribution

_ENABLE_DIST_COM	Collect constant-of-motion distribution histogram [mu, Ekin, Ptor]
_DIST_MIN_MU	Minimum bin edge for the mu coordinate in COM-dist [J/T]
_DIST_MAX_MU	Maximum bin edge for the mu coordinate in COM-dist [J/T]
_DIST_NBIN_MU	Number of bins the interval [MIN_MU, MAX_MU] is divided to
_DIST_MIN_EKIN	Minimum bin edge for the energy coordinate [J]
_DIST_MAX_EKIN	Maximum bin edge for the energy coordinate [J]
_DIST_NBIN_EKIN	Number of bins the interval [MIN_EKIN, MAX_EKIN] is divided to
_DIST_MIN_PTOR	Minimum bin edge for the Ptor coordinate [kg m^2/s]
_DIST_MAX_PTOR	Maximum bin edge for the Ptor coordinate [kg m^2/s]
_DIST_NBIN_PTOR	Number of bins the interval [MIN_PTOR, MAX_PTOR] is divided to

Recording marker trajectories

_ENABLE_ORBITWRITE	Enable diagnostics that store marker orbit
_ORBITWRITE_MODE	What kind of marker orbit diagnostics are collected
_ORBITWRITE_NPOINT	Maximum number of points (per marker) to be written
_ORBITWRITE_POLOIDALANGLES	Poloidal angles of toroidal planes where toroidal plots are collected
_ORBITWRITE_TOROIDALANGLES	Toroidal angles of poloidal planes where poloidal plots are collected
_ORBITWRITE_RADIALDISTANCES	Minor radius coordinate where radial plots are collected
_ORBITWRITE_INTERVAL	Time interval for writing marker state [s]

Transport coefficients

_ENABLE_TRANSCOEF	Enable evaluation of transport coefficients.
_TRANSCOEF_INTERVAL	Time interval for recording data points
_TRANSCOEF_NAVG	Number of subsequent data points that are averaged before calculating coefficients to reduce noise.
_TRANSCOEF_RECORDRHO	Record coefficients in terms of normalized poloidal flux instead of meters.

Batch jobs

Use this script to run ASCOT5 in multiple nodes using MPI (MPI=1 when the code was compiled).

#!/bin/bash

## Set required nodes and CPUs (number of processes == number of nodes)
#SBATCH -N10 -n10 -c48

#SBATCH -t 24:00:00
#SBATCH -J ascot5

#SBATCH -e %x.e%j
#SBATCH -o %x.o%j

export <your exports>
module load <your modules>

echo Job name $SLURM_JOB_NAME
echo Job id $SLURM_JOB_ID

# Some platforms require that the number of threads must be given explicitly
# In those cases use (1-2) x number of CPUs (check which is faster)
export OMP_NUM_THREADS=48

INPUTFILE=ascot

date
export FOR_PRINT=$SLURM_JOB_ID.stdout
mpirun ./ascot5_main --in=$INPUTFILE --d="YOURTAG Your description"
date

Use this script to run ASCOT5 in multiple nodes without MPI (MPI=0 when the code was compiled). This results in multiple output files that you have to combine using the python tool a5combine.

#!/bin/bash

## How many jobs this run is divided into
NJOBS=100

## Name of the input file. Each output file begins with this name followed by
## its "mpi_rank"
INPUTFILE=ascot

for i in $(seq 0 $(($NJOBS-1)))
do
filename=${RANDOM}
cat > $filename << EOF
#!/bin/bash

## Use only single node and single process
#SBATCH -N1 -n1 -c48

#SBATCH -t 24:00:00
#SBATCH -J ascot5

#SBATCH -e ${i}.e%j
#SBATCH -o ${i}.o%j

export <your exports>
module load <your modules>

# Some platforms require that the number of threads must be given explicitly
# In those cases use (1-2) x number of CPUs (check which is faster)
export OMP_NUM_THREADS=96

echo Job name $SLURM_JOB_NAME
echo Job id $SLURM_JOB_ID

date
./ascot5_main --mpi_rank=$i --mpi_size=$NJOBS --in=$INPUTFILE --d="YOURTAG Your description"
date

EOF

sbatch $filename
rm $filename
echo $i
## If multiple jobs are reading from the same file at the same time this can
## cause problems in the system, so give system some time to breathe
sleep 5s
done

Examples

Examples of simulation times and number of markers used

Simulation	Hardware	Number of markers	CPU time
Alpha particle slowing-down in 3D ITER (Not real numbers!)	Xeon-Phi, 10 nodes (MARCONI)	\(1\times10^6\)	24 h