How to run SOFT

All configuration of a SOFT run is done in a separate configuration file, commonly referred to as a pi file. In this section the basic structure of a pi file will be explained in detail. For detailed information about which options can be set, pleaes consult the SOFT manual.

Examples

The best way to learn how to set up run scripts for SOFT is to see examples of such run scripts. A basic pi file can look like the following:

# Basic SOFT pi file
useequation=guiding-center-relativistic
usetool=sycamera

# Specify magnetic field
magnetic_field=circular   # Use analytic magnetic field
magnetic circular { B0=5; major_radius=0.68; minor_radius=0.22; safety_factor=1; }
domain_has_outer_wall=no  # Remove outer device walls to prevent from blocking radiation

# Set phase-space
particles {
    t=0,-1
    rdyn=0.84,1000
    p=3e7,3e7,1
    pitch=0.15,0.15,1
}

# Specify properties for the sycamera tool
tool sycamera {
    aperture=0.006                 # Side length (in m) of (square) detector
    cone=delta                     # Use the cone model (not full angular distribution)
    direction=0,1,0                # Normal vector of detector surface (not necessarily normalized)
    position=0,-1.069,0            # Position vector of detector, relative tokamak point of symmtetry
    product=image                  # Output a synchrotron image when done
    radiation=synchrotron_spectrum # Take spectrum of radiation into account
    spectrum=5e-7,1e-6             # Detector spectral range
    toroidal_resolution=3500       # Number of steps in toroidal integral
    vision_angle=2.0               # Size of field-of-view
}

# Specify properties for the 'image' sycout
sycout image {
    pixels=1000
    name=image.dat
}

The settings available for SOFT are many more, and for a detailed list of which settings are available, please consult the SOFT manual. Further examples of pi files for different purposes are:

  • distpi – Illustrates how SOFT can be run together with a runaway distribution function.
  • hollowpi – An example of simulating a hollow electron beam.
  • simplepi – The basic example shown above, setting just the most important options.
  • orbitpi – Shows how to use the orbit following part of SOFT to simulate particle orbits.

Basic syntax

Options in a pi file are specified by first giving the name of the option, followed by an equal sign, followed by the value to assign to the option. White-space around the equal sign is ignored. Typically, everything between the equal sign and the end-of-line marker is considered part of the assigned value, except for any white-space coming either directly after the equal sign, or directly before the end-of-line-marker. It is however possible to put several settings on the same line by separating them with semi-colons (;).

Comments can be given by preceding the comment text with a hashtag symbol (#). Any text following the hashtag on the same line will be ignored. Note that comments cannot be ended with a semi-colon.

Some options should be assigned vectors of data, such as the direction and rdyn options (among others) in the above example. Each component of the vector must be separated by a comma, and any white-space surrounding commas is ignored. Note that all floating-point numbers can be specified using either decimal form (i.e. 1000 or 0.68) or C scientific notation (i.e. 5e-7).

Environments

Some options in SOFT are considered global and are specified directly in the file, such as for example useequation and usetool in the example above. Many options are however specific to certain modules of SOFT, and they are instead specified inside the appropriate option environment.

There are four different environments in SOFT, all of which are syntactically similar. With the exception of the particles environment (which really just sets what could be considered global options), they are also conceptually similar.

The magnetic, tool and sycout environments specify options for a particular SOFT module, and the name of the module must be specified in the environment header. The settings are then wrapped within curly brackets ({ and }) and given to the specified module. Note that even if an environment for a module is present in the configuration file, it does not mean that the module will automatically used. Other options must be set to enable modules.

The basic syntax for an environment environment configuring the module named module is:

environment module {
    ...
}

The particles environment does not require any module name to specified.

magnetic

The magnetic environment specifies settings for the magnetic equilibrium to use, as well as the surrounding walls. Currently, there are two different so called magnetic handler modules that can be used. The first and simplest is the circular magnetic handler which implements simple analytic circular magnetic field with a constant safety factor. The second magnetic handler, named numeric, allows the specification of a magnetic field numerically from for example an HDF5 or MATLAB *.mat file.

particles

The particles environment sets a number of options relating to the phase-space of the run. Since it is necessarily tied to the particles module of SOFT, the module name part of the environment specification given above should be omitted.

In addition to specifying the bounds of and number of points in phase-space, the particles environment can also be used to specify a different mass or charge of the simulated particle species.

Note

The orbit tool for tracing particle orbits only allows simulating a single point of phase-space at a time, and can otherwise give rise to some very anonymous errors.

tool

The tool environment sets the options for particular tool. A tool, in SOFT, is a module which receives information about a computed orbit and processes it. Currently, there are two tools in SOFT, and these are the orbit and sycamera tools. The orbit tool simply traces a particle or guiding-center orbit, keeps track of a few addiational parameters, and outputs it all to a CSV file.

The sycamera tool is the synchrotron camera (or rather detector) tool which gives SOFT its name. A large part of the SOFT code is dedicated to this module, and the options set by this tool include for example the type of synchrotron radiation model to use, the number of toroidal steps to take, various detector properties among many other things.

sycout

Due to the great versatility of the sycamera tool, the types of output that could be obtained it are numerous. Since each of the output types requires its own set of settings, a separate environment for specifying settings to the output handler of the sycamera tool was created.

The sycout environment thus specifies settings of a sycamera output handler module. To date there are five different sycout modules, namely

Module name Description
green Generates a Green’s function which relates the distribution of runaways to the resulting spectrum or image. (Can) allow fast computation of image/spectrum.
image Generates a synthetic synchrotron image.
space3d Stores 3D information about all particles contributing to a synchrotron image allows visualizing the corresponding surface-of-visibility.
spectrometer Generates a spectrum curve.
topview Stores information about where particles where located in the xy-plane when when they emitted towards the detector. Allows visualizing the toroidal distribution of particles that are visible to the detector.