Getting started running Synergia

Synergia contains a set of Python utilities for defining and, optionally, running synergia jobs. The best way to start is by running some of the example scripts provided in the examples directory.

Getting help

All Synergia scripts support online help through the --help flag. Here is the help from booster_test1.py:

|abacus>./booster_test1.py --help
Impact parameter options:
    current=  Current per injected turn (A), default = 0.042
    partpercell=  Particles per cell, default = 10
    numparticles=  Total number of particles, supercedes partpercell, default = None
    BC=  Space charge boundary conditions, default = trans finite, long periodic round
    energy=  Kinetic energy (GeV), default = 0.4
    sampleperiod=  Sampling period for saving particles, default = 1
    numproc=  Number of processors, default = 1,1
    disttype=  Input distribution type, default = gaussian covariance
    pipedims=  Pipe dimenions (m), default = 0.04,0.04
    charge=  Charge in units of e, default = 1
    scgrid=  Space charge grid, default = 33,33,33
    scalefreq=  Scaling frequency (Hz), default = 2e+08

Run/Batch options:
    block=  Whether to block until job has finished, default = 0
    submit=  Whether to immediately run/submit job, default = 0
    overwrite=  Whether to overwrite existing job directory, default = 0

booster_test1 options:
    dpop=  (delta p)/p, default = 0.0003
    
|abacus>

Notice that the options come in three groups:

Impact parameter options: control the options to the Impact routines
Run/Batch options: control the way the job is created and, optionally, run or submitted to the batch system.
script-specific options: are options defined by the user script. booster_test1 defines one optionn, (delta p)/p.

Running a simple job

To start, try running booster_test1.py with 1000 particles:

|abacus>./booster_test1.py numparticles=1000
  
    Using default local batch system settings. Create a file
    synergia_local.py to avoid this message. synergia_default_local.py
    can be used as a logical starting point.

created directory bst1
|abacus>cd bst1
|abacus>time ./synergia.sh

real    0m2.812s
user    0m2.480s
sys     0m0.094s
|abacus>ls
6dphs_turn00081.h5  description       fort.26  fort.31            pack
6dphs_turn00082.h5  external_ble.mad  fort.27  fort.32            synergia.sh
booster_test1.py    fort.18           fort.28  impact.err         test.in
cleanup             fort.24           fort.29  impact.out         wrappedxmain
command             fort.25           fort.30  mad_mapping.table  xmain
|abacus>

The message about local batch system settings is explained in the following section. Synergia always creates a new directory for job files. Here, the directory is bst1. After the job has run, the job directory will contain the following files:

6dphs_turn00081.h5, etc.: The beam distribution saved at various points in hdf5 format if hdf5 was enabled at configure time. 81 and 82 are always the initial and final distributions, respectively. Other positions are numbered consecutively starting with 83.
fort.81, fort.82, etc.: The beam distribution saved at various points, in plain text format if hdf5 was not enabled at configure time. 81 and 82 are always the initial and final distributions, respectively. Other positions are numbered consecutively starting with 83.
a copy of the original script ( booster_test1.py): Synergia always makes a copy of the script that was run to create the job for reproducibility.
cleanup: cleanup is a shell script that will delete all generated files.
command: The file command contains a copy of the command-line arguments used to create the job.
description: The file description contains a human-readable summary of the job.
fort.18 - fort.32: These files are diagnostics from Impact. See IMPACTlayer.doc for details.
impact.err and impact.out: These files are the standard error and standard out streams from the job, respectively.
pack: pack is a shell script to create a gzipped tarball of the job output. It will produce a tarball named with base name of the current directory and place it in the parent directory.
synergia.sh, etc.: Synergia creates a shell script/job submission file whose name starts with "synergia". The rest of the file name will be appropriate for the batch system in question.
other files: The remaining files in the directory are for Synergia's internal use.

Creating synergia_local.py

The file synergia_local.py allows Synergia to automatically create jobs appropriate for the local batch system. If synergia_local.py is not present, the settings in synergia_local_default.py are used. synergia_local_default.py assumes a single processor machine with no batch system available. Examples for other machines and batch systems are available in cvs. Look at the files synergia_local_*.py.

Job template files

All of the scripts create job scripts based on a template file. Simple and conditional substitutions are supported.

Simple substitutions

Simple substitutions can be made in the template files with the @@ @@ syntax. The value of the variable var will be substituted in place of @@var@@. All of the command-line options are available as variables. The following variables are also available:

procspernode: The number of processors per node.
numproc: The total number of processes in the job.
numnodes: The total number of nodes needed by the job.
rundir: The directory where the job is to be run.

Conditional substitutions

Conditional substitutions can be made in the template file with the __ {{ }}{{ }} __ syntax. If the template file contains the string __var{{val1}{{val2}}__, val1 will substituted if var exists or val2 will be substituted if var does not exist or is empty. val1 and val2 can contain simple substitutions.