options

Simulation options input.

a5py.ascot5io.options.Opt

Simulation options.
class a5py.ascot5io.options.Opt(*args, **kwargs)

Bases: DataGroup

Simulation options.

Option parameters and default values are defined with properties and getters. These should not be accessed directly or altered in any way. Use read() to obtain options from the HDF5 file.

property _SIM_MODE

Simulation mode (1, 2, 3, 4)

  • 1 Gyro-orbit

  • 2 Guiding center

  • 3 Hybrid

  • 4 Magnetic field lines

property _ENABLE_ADAPTIVE

Use adaptive time-step (0, 1)

This option is used only if SIM_MODE = 2 or 3. Gyro-orbit simulations are always done with fixed time-step and magnetic field line simulations with adaptive time-step.

  • 0 Use fixed time-step

  • 1 Use adaptive time-step

property _RECORD_MODE

Record GOs as GCs in diagnostics (0, 1)

  • 0 Record GOs as GOs

  • 1 Record GOs as GCs

property _FIXEDSTEP_USE_USERDEFINED

Define fixed time-step value explicitly (0,1)

Note: The adaptive scheme uses fixed time-step value as an initial step.

  • 0 Calculate time-step from FIXEDSTEP_NSTEPS_PER_GYROTIME

  • 1 Use opt.opt.FIXEDSTEP_USERDEFINED as a time-step

property _FIXEDSTEP_USERDEFINED

User-defined time-step [s]

property _FIXEDSTEP_GYRODEFINED

Time-step is 2pi / ( gyrofrequency * N ) where N is this parameter

property _ADAPTIVE_TOL_ORBIT

Relative error tolerance for orbit following in adaptive scheme

property _ADAPTIVE_TOL_CCOL

Relative error tolerance for Coulomb collisions in adaptive scheme

property _ADAPTIVE_MAX_DRHO

Maximum allowed change in rho during one time-step in adaptive scheme

property _ADAPTIVE_MAX_DPHI

Maximum allowed change in phi during one time-step in adaptive scheme

property _ENDCOND_SIMTIMELIM

Terminate when marker time passes ENDCOND_LIM_SIMTIME or when marker time has advanced ENDCOND_MAX_MILEAGE in a simulation

Marker is terminated if t > ENDCOND_MAX_MILEAGE or t0 + t > ENDCOND_LIM_SIMTIME where t0 is marker’s initial time and t the time it has been simulated. Note that if time is reversed, the simulation is instead terminated when t0 + t < ENDCOND_LIM_SIMTIME. See also ENDCOND_CPUTIMELIM.

property _ENDCOND_CPUTIMELIM

Terminate marker when the computer has spent ENDCOND_MAX_CPUTIME amount of real time to simulate it

This limit should be rarely used as its intended use is in debugging to stop markers stuck in a loop.

property _ENDCOND_RHOLIM

Terminate if marker goes outside given rho boundaries

The boundaries are defined by ENDCOND_MIN_RHO and ENDCOND_MAX_RHO.

property _ENDCOND_ENERGYLIM

Terminate when marker energy is below a user-specified value

The user specified values are ENDCOND_MIN_ENERGY and ENDCOND_MIN_ENERGY_TIMES_THERMAL. Marker is terminated when either of these limits is reached.

property _ENDCOND_WALLHIT

Terminate when marker intersects a wall element

property _ENDCOND_MAXORBS

Terminate when marker has completed user-specified number of orbits

Limit ENDCOND_MAX_TOROIDALORBS is used for a number of toroidal and ENDCOND_MAX_POLOIDALORBS for poloidal orbits.

  • 0 The end condition is not active.

  • 1 Marker is terminated when either of these limits is reached.

  • 2 Marker is terminated when both limits are reached.

property _ENDCOND_NEUTRALIZED

Terminate when the marker becomes neutral

property _ENDCOND_IONIZED

Terminate when the marker becomes ionized

property _ENDCOND_LIM_SIMTIME

Time when the simulation stops [s]

property _ENDCOND_MAX_MILEAGE

The maximum amount of time this marker is simulated [s]

property _ENDCOND_MAX_CPUTIME

Maximum cpu time per marker [s]

property _ENDCOND_MAX_RHO

Maximum rho value

property _ENDCOND_MIN_RHO

Minimum rho value

property _ENDCOND_MIN_ENERGY

Minimum energy [eV]

property _ENDCOND_MIN_THERMAL

Minimum energy limit is local ion thermal energy times this value

property _ENDCOND_MAX_TOROIDALORBS

Maximum number of toroidal orbits

property _ENDCOND_MAX_POLOIDALORBS

Maximum number of poloidal orbits

property _ENABLE_ORBIT_FOLLOWING

Trace markers in an electromagnetic field

property _ENABLE_COULOMB_COLLISIONS

Markers experience Coulomb collisions with background plasma

property _ENABLE_MHD

Include MHD perturbations to orbit-following

property _ENABLE_ATOMIC

Markers can undergo atomic reactions with background plasma or neutrals

  • 0 Atomic reactions are turned off.

  • 1 Atomic reactions are on but marker is terminated when outside

    the reaction data domain.

  • 2 Atomic reactions are on but they are ignored when marker is

    outside the reaction data domain.

property _DISABLE_FIRSTORDER_GCTRANS

Disable first order guiding center transformation in velocity space

property _DISABLE_ENERGY_CCOLL

Disable guiding center energy collisions

property _DISABLE_PITCH_CCOLL

Disable guiding center pitch collisions

property _DISABLE_GCDIFF_CCOLL

Disable guiding center spatial diffusion

property _REVERSE_TIME

Trace markers backwards in time.

Collision operator isn’t reversible so disable collisions if this option is used. Also when tracing markers, the simulation stops when marker time is below ENDCOND_LIM_SIMTIME.

property _ENABLE_DIST_5D

Collect distribution histogram in [R, phi, z, ppa, ppe, t, q]

The coordinates are:

  • R major radius

  • phi toroidal angle

  • z z-coordinate

  • ppa momentum component parallel to magnetic field

  • ppe momentum component perpendicular to magnetic field

  • t time

  • q charge

property _ENABLE_DIST_6D

Collect distribution histogram in [R, phi, z, pR, pphi, pz, t, q]

The coordinates are:

  • R major radius

  • phi toroidal angle

  • z z-coordinate

  • pR momentum R-component

  • pphi momentum phi-component

  • pz momentum z-component

  • t time

  • q charge

property _ENABLE_DIST_RHO5D

Collect distribution histogram in [rho, pol, phi, ppa, ppe, t, q]

The coordinates are:

  • rho flux surface

  • pol poloidal angle

  • phi toroidal angle

  • z z-coordinate

  • ppa momentum component parallel to magnetic field

  • ppe momentum component perpendicular to magnetic field

  • t time

  • q charge

property _ENABLE_DIST_RHO6D

Collect distribution histogram in [rho, pol, phi, pR, pphi, pz, t, q]

The coordinates are:

  • rho flux surface

  • pol poloidal angle

  • phi toroidal angle

  • z z-coordinate

  • pR momentum R-component

  • pphi momentum phi-component

  • pz momentum z-component

  • t time

  • q charge

property _DIST_MIN_R

Minimum bin edge for R coordinate [m]

property _DIST_MAX_R

Maximum bin edge for R coordinate [m]

property _DIST_NBIN_R

Number of bins the interval [MIN_R, MAX_R] is divided to

property _DIST_MIN_PHI

Minimum bin edge for phi coordinate [deg]

property _DIST_MAX_PHI

Maximum bin edge for phi coordinate [deg]

property _DIST_NBIN_PHI

Number of bins the interval [MIN_PHI, MAX_PHI] is divided to

property _DIST_MIN_Z

Minimum bin edge for z coordinate [m]

property _DIST_MAX_Z

Maximum bin edge for z coordinate [m]

property _DIST_NBIN_Z

Number of bins the interval [MIN_Z, MAX_Z] is divided to

property _DIST_MIN_RHO

Minimum bin edge for rho coordinate [1]

property _DIST_MAX_RHO

Maximum bin edge for rho coordinate [1]

property _DIST_NBIN_RHO

Number of bins the interval [MIN_RHO, MAX_RHO] is divided to

property _DIST_MIN_THETA

Minimum bin edge for theta coordinate [deg]

property _DIST_MAX_THETA

Maximum bin edge for theta coordinate [deg]

property _DIST_NBIN_THETA

Number of bins the interval [MIN_THETA, MAX_THETA] is divided to

property _DIST_MIN_PPA

Minimum bin edge for ppa coordinate [kg m/s]

property _DIST_MAX_PPA

Maximum bin edge for ppa coordinate [kg m/s]

property _DIST_NBIN_PPA

Number of bins the interval [MIN_PPA, MAX_PPA] is divided to

property _DIST_MIN_PPE

Minimum bin edge for ppe coordinate [kg m/s]

property _DIST_MAX_PPE

Maximum bin edge for ppe coordinate [kg m/s]

property _DIST_NBIN_PPE

Number of bins the interval [MIN_PPE, MAX_PPE] is divided to

property _DIST_MIN_PR

Minimum bin edge for pR coordinate [kg m/s]

property _DIST_MAX_PR

Maximum bin edge for pR coordinate [kg m/s]

property _DIST_NBIN_PR

Number of bins the interval [MIN_PR, MAX_PR] is divided to

property _DIST_MIN_PPHI

Minimum bin edge for pphi coordinate [kg m/s]

property _DIST_MAX_PPHI

Maximum bin edge for pphi coordinate [kg m/s]

property _DIST_NBIN_PPHI

Number of bins the interval [MIN_PPHI, MAX_PPHI] is divided to

property _DIST_MIN_PZ

Minimum bin edge for pz coordinate [kg m/s]

property _DIST_MAX_PZ

Maximum bin edge for pz coordinate [kg m/s]

property _DIST_NBIN_PZ

Number of bins the interval [MIN_PZ, MAX_PZ] is divided to

property _DIST_MIN_TIME

Minimum bin edge for time coordinate [s]

property _DIST_MAX_TIME

Maximum bin edge for time coordinate [s]

property _DIST_NBIN_TIME

Number of bins the interval [MIN_TIME, MAX_TIME] is divided to

property _DIST_MIN_CHARGE

Minimum bin edge for charge coordinate [e]

property _DIST_MAX_CHARGE

Maximum bin edge for charge coordinate [e]

property _DIST_NBIN_CHARGE

Number of bins the interval [MIN_CHARGE, MAX_CHARGE] is divided to

property _ENABLE_DIST_COM

Collect constant-of-motion distribution histogram [mu, Ekin, Ptor]

The coordinates are:

  • mu magnetic moment (first adiabatic invariant)

  • Ekin kinetic energy

  • Ptor canonical toroidal angular momentum

property _DIST_MIN_MU

Minimum bin edge for the mu coordinate in COM-dist [J/T]

property _DIST_MAX_MU

Maximum bin edge for the mu coordinate in COM-dist [J/T]

property _DIST_NBIN_MU

Number of bins the interval [MIN_MU, MAX_MU] is divided to

property _DIST_MIN_EKIN

Minimum bin edge for the energy coordinate [J]

property _DIST_MAX_EKIN

Maximum bin edge for the energy coordinate [J]

property _DIST_NBIN_EKIN

Number of bins the interval [MIN_EKIN, MAX_EKIN] is divided to

property _DIST_MIN_PTOR

Minimum bin edge for the Ptor coordinate [kg m^2/s]

property _DIST_MAX_PTOR

Maximum bin edge for the Ptor coordinate [kg m^2/s]

property _DIST_NBIN_PTOR

Number of bins the interval [MIN_PTOR, MAX_PTOR] is divided to

property _ENABLE_ORBITWRITE

Enable diagnostics that store marker orbit

  • 0 Marker orbit diagnostics are not collected

  • 1 Marker orbit diagnostics are collected

property _ORBITWRITE_MODE

What kind of marker orbit diagnostics are collected

These are only used if ENABLE_ORBITWRITE is active.

  • 0 When marker crosses a plane (Poincare-plot)

  • 1 Between given time intervals

property _ORBITWRITE_NPOINT

Maximum number of points (per marker) to be written

If this number is exceeded when marker is being simulated, the oldest points will be replaced as long as the simulation continues. Thus, this parameter is effectively the number of marker’s last positions that are stored.

property _ORBITWRITE_POLOIDALANGLES

Poloidal angles of toroidal planes where toroidal plots are collected

Used when ENABLE_ORBITWRITE = 1 and ORBITWRITE_MODE = 0.

property _ORBITWRITE_TOROIDALANGLES

Toroidal angles of poloidal planes where poloidal plots are collected

Used when ENABLE_ORBITWRITE = 1 and ORBITWRITE_MODE = 0.

property _ORBITWRITE_RADIALDISTANCES

Minor radius coordinate where radial plots are collected

Used when ENABLE_ORBITWRITE = 1 and ORBITWRITE_MODE = 0.

property _ORBITWRITE_INTERVAL

Time interval for writing marker state [s]

Used when ENABLE_ORBITWRITE = 1 and ORBITWRITE_MODE = 1.

property _ENABLE_TRANSCOEF

Enable evaluation of transport coefficients.

  • 0 Transport coefficients are not collected

  • 1 Transport coefficients are collected

property _TRANSCOEF_INTERVAL

Time interval for recording data points

The data points are recorded (at the outer mid-plane crossing) if this interval has passed from the previous recording.

property _TRANSCOEF_NAVG

Number of subsequent data points that are averaged before calculating coefficients to reduce noise.

property _TRANSCOEF_RECORDRHO

Record coefficients in terms of normalized poloidal flux instead of meters.

read()

Read data from HDF5 file.

Returns:
datadict

Data read from HDF5 stored in the same format as is passed to write_hdf5().

Raises:
AscotIOException

If stored options were unviable.

tostring(descriptions=True, aslist=False)

Convert options to string representation.

Parameters:
descriptionsbool, optional

If True, section headers and descriptions are added above the parameters to make options more readable.

aslistbool, optional

Instead of line breaks, separate each line as a list item.

Returns:
optstr or list [str]

String where option parameters are written on each line as “<PARAMETER> = <VALUE>”.

new(desc=None, **kwargs)

Write new options with updated parameters.

This method reads the current options, updates the given parameters, and writes the updated options as a new input.

Parameters:
descstr, optional

Input description.

**kwargs

<name> : <value> pairs for each options parameter that are updated.

Returns:
namestr

Name, i.e. “<type>_<qid>”, of the new input that was written.

Raises:
ValueError

If arguments contain unknown parameters.

static write_hdf5(fn, desc=None, **kwargs)

Write input data to the HDF5 file.

Parameters:
fnstr

Full path to HDF5 file.

descstr, optional

Input description.

**kwargs

<name> : <value> pairs for each options parameter

Hint: get_default() generates a default options dictionary from which one can pick parameters to change.

Returns:
namestr

Name, i.e. “<type>_<qid>”, of the new input that was written.

Raises:
ValueError

If arguments contain unknown parameters or if there are parameters missing.

static create_dummy()

Create dummy data that has correct format and is valid, but can be non-sensical.

This method is intended for testing purposes or to provide data whose presence is needed but which is not actually used in simulation.

The default options are created.

Returns:
datadict

Input data that can be passed to write_hdf5 method of a corresponding type.

static get_default()

Get default option parameters.

The default options have all “ENABLE” settings disabled. The default values are not suitable for any proper simulation.

Returns:
optionsdict

Default options in a format that can be passed to write_hdf5().

static validate()

Validate options and return names of faulty parameters.

static convert_string(lines)

Converts a string to Opt input.

Parameters:
linesstr or [str]

String with line breaks or list of strings where each item is a single line.

Options are interpreted from a string assuming that the relevant lines have format “<PARAMETER> = <VALUE>” and nothing else. The parameter name must be in all uppercase. Lines that don’t start with a recognizable parameter are ignored.

Returns:
outdict

String converted as an input for write_hdf5().

static convert_xml(xml)

Convert XML file to Opt input.

Parameters:
xmlstr

Path to XML file or contents of the file as a string.

Returns:
outdict

XML converted to Opt input.

static schema(opt=None, fnxsd=None, fnxml=None)

Produce a schema and an XML file containing ASCOT5 option parameters.

Parameters:
optdict, optional

Options used to fill the XML with parameter values.

If None, the default options are used.

fnxsdstr, optional

None or filename to write XSD data.

fnxmlstr, optional

None or filename to write XML data.

Returns:
schema

Schema that contains parameter descriptions and which can validate XML files containing ASCOT5 options.

xml

XML file containing the options parameters and their values.