Input generation

Summary

• Inputs are modular: to simulate markers in a stellarator magnetic field, provide a stellarator magnetic field input.

• All required inputs must be present even though they would not be actually used: provide dummy atomic data even if you have atomic physics disabled.

  • Information on when input is used can be found at the end of this documentation below each input type’s description.

• Inputs are created via create_input():

  • Dummy input (provide input type but no data): create_input("B_2DS").

  • Creating input explicitly (provide input type and data): create_input("B_2DS", **data).

  • Creating input implicitly via templates (provide template name and arguments if needed): create_input("bfield analytical iter circular", spline=True).

• Input data can be read with read() method: a5.data.bfield.active.read().

• Information on what inputs there are, what data they need and what templates there are can be found at the end of this page.

ASCOT5 is modular in terms of inputs. In the code, inputs are interpolated via interfaces so that the implementation can vary. For example, the magnetic field interface specifies methods to interpolate magnetic field vector at the given coordinates, but the implementation of those methods is different for axisymmetric tokamaks and stellarators.

This modularity is reflected in the format of the HDF5 file, which can look like this for example:

data
├── bfield               # Magnetic field inputs
│   ├── B_2DS_7027705680 # Some axisymmetric tokamak magnetic field data
│   ├── B_STS_0890178582 # Some stellarator magnetic field data
│   └── ...              # Some other possible magnetic field data
│
├── efield               # Electric field inputs
│   └── ...
│
└── ...                  # Other inputs (wall, plasma, etc.)

Here bfield and efield are parent groups for which there are corresponding magnetic and electric field interfaces in the code. The actual data is contained in B_2DS and B_STS and the code recognizes that these are axisymmetric tokamak and stellarator magnetic field data, respectively, and uses the corresponding implementation in the simulation (depending on which of the inputs was active).

Note

To run a simulation, all required parent groups must have an input of some type present even though the input would not actually be used in the simulation. For those cases one can supply dummy data.

Inputs are created with create_input() method which can operate in three ways. To create dummy input, call the method without providing any data.

# By default the created input is not activated if there are other inputs
# already present
a5.data.create_input("E_TC", activate=True)

Here E_TC is the desired input type, which in this case is the trivial Cartesian electric field.

To generate proper input, one must provide all required data which is specified in that input’s write_hdf5 function. In this example, E_TC.write_hdf5() requires that an array with all electric field components is provided.

a5.data.create_input("E_TC", exyz=np.array([0, 0, 0]))

Existing data can be read with read method to a dictionary that has the same format as what was passed to write_hdf5:

data = a5.data.efield.active.read()                   # Read data to a dictionary
data["exyz"] = exyz=np.array([1, 0, 0])               # Modify
a5.data.create_input("E_TC", **data, desc="MODIFIED") # Write back to disk

However, it can be laborous to e.g. extract magnetic field data from EQDSK and convert it to the format required by ASCOT5. For this reason, there are tools called templates that convert common data formats to ASCOT5 inputs. Templates provide a convenient way to import data to ASCOT5 and they also contain some premade inputs, e.g. options and markers for creating Poincaré plots.

Templates are used by providing the name of the template and any required or optional parameters.

a5.data.create_input("options poincare", maxrho=True, simmode=2, tor=[0, 180])

Next we list all available input types followed by available templates. When beginning a new study, look through inputs to see what input types you will need and what data is required, and skim through templates to see if you can make use of them.

Note

ASCOT5 aims to use the user-provided data “as is” as far as possible, so that the user retains control and knowledge what is done with the data. This means that ASCOT5 does not extrapolate inputs, so it is user’s responsibility to ensure e.g. that the plasma profiles covers the whole region and that the magnetic field extends all the way to the wall.

Magnetic field bfield

Magnetic field input is used always in every simulation and it is required to evaluate data via libascot.

A good quality magnetic field is essential for any orbit-following study. Always check the field quality by generating Poincaré plots and plotting the divergence. If you don’t specifically require some other input, use the axisymmetric field since that is fast to interpolate and divergence free. Note that MHD eigenmodes can be included via dedicated input.

bfield	Magnetic field input.
bfield.B_2DS	Axisymmetric tokamak field interpolated with splines.
bfield.B_2DS.write_hdf5	Write input data to the HDF5 file.
bfield.B_3DS	Non-axisymmetric tokamak field.
bfield.B_3DS.write_hdf5	Write input data to the HDF5 file.
bfield.B_STS	Stellarator magnetic field.
bfield.B_STS.write_hdf5	Write input data to the HDF5 file.
bfield.B_GS	Analytical tokamak field.
bfield.B_GS.write_hdf5	Write input data to the HDF5 file.
bfield.B_TC	Magnetic field in Cartesian basis for testing purposes.
bfield.B_TC.write_hdf5	Write input data to the HDF5 file.

Electric field efield

Electric field data is used always in every simulation.

Note that electric field cannot be disabled manually in simulations. If electric field is not relevant for your simulation, use E_TC and set it to zero to effectively disable electric field.

efield	Electric field input.
efield.E_TC	Uniform electric field in Cartesian basis.
efield.E_TC.write_hdf5	Write input data to the HDF5 file.
efield.E_1DS	One-dimensional electric field interpolated with cubic splines.
efield.E_1DS.write_hdf5	Write input data to the HDF5 file.

Plasma plasma

Plasma input is used whenever you have ENABLE_CCOLL=1, ENABLE_ATOMIC=1, ENDCOND_EMIN=1 or when you use AFSI.

plasma	Input data representing plasma background species.
plasma.plasma_1D	Plasma profiles that have only radial dependency.
plasma.plasma_1D.write_hdf5	Write input data to the HDF5 file.
plasma.plasma_1DS	Same input as plasma_1D but interpolated with splines.
plasma.plasma_1DS.write_hdf5	Write input data to the HDF5 file.

Wall mesh wall

Wall input is used when you have ENDCOND_WALLHIT=1.

If losses are of no interest it is advised to use some wall to prevent markers from escaping the computational domain. Alternatively, one can use the RHOMAX end condition to stop markers at the separatrix.

wall	Input representing first wall and other plasma facing components.
wall.wall_2D	Contour in Rz-plane that represents an axisymmetric wall.
wall.wall_2D.write_hdf5	Write input data to the HDF5 file.
wall.wall_3D	Triangle mesh that represents a 3D wall.
wall.wall_3D.write_hdf5	Write input data to the HDF5 file.

Neutral neutral

Neutral particle profiles required when atomic (CX, etc.) reactions are included.

neutral	Input representing plasma neutral bakcground.
neutral.N0_1D	Constant-on-flux-surfaces neutral profile.
neutral.N0_1D.write_hdf5	Write input data to the HDF5 file.
neutral.N0_3D	Non-axisymmetric neutral data.
neutral.N0_3D.write_hdf5	Write input data to the HDF5 file.

Boozer data boozer

Boozer input is used when ENABLE_MHD=1.

Boozer data is required for simulations with MHD eigenfunctions. One can create it automatically from B_2DS or B_3DS with a template InputFactory.boozer_tokamak().

boozer	Input representing mapping from real-space to Boozer coordinates.
boozer.Boozer	Mapping between cylindrical and Boozer coordinates assuming that psi is axisymmetric.
boozer.Boozer.write_hdf5	Write input data to the HDF5 file.

MHD eigenfunctions mhd

MHD input is used when ENABLE_MHD=1.

MHD input is used to model particle response to MHD (feedback from particles to modes is not implemented).

mhd	Input containing MHD eigenmodes.
mhd.MHD_STAT	Stationary MHD eigenfunctions.
mhd.MHD_STAT.write_hdf5	Write input data to the HDF5 file.
mhd.MHD_NONSTAT	Time-dependent MHD eigenfunctions.
mhd.MHD_NONSTAT.write_hdf5	Write input data to the HDF5 file.

Atomic reaction data asigma

Atomic input is used when ENABLE_ATOMIC=1.

Data for interpolating and computing reaction probabilities and cross sections for reactions where the test particle charge state changes. This data, typically sourced from ADAS, is required only for simulations where atomic reactions are enabled.

asigma	Atomic reaction data HDF5 IO.
asigma.Asigma_loc	Local atomic data.
asigma.Asigma_loc.write_hdf5	Write input data to the HDF5 file.

Neutral beam injectors nbi

NBI input is used by BBNBI exclusively. The input consists of a bundle of injectors, which in a5py are represented by Injector.

nbi	Input data representing NBI.
nbi.NBI	Object representing a bundle of injectors used as an input in BBNBI.
nbi.NBI.write_hdf5	Write input data to the HDF5 file.

Markers marker

Simulation markers are always used except for BBNBI.

marker	Markers whose orbits are solved within the ASCOT5 code.
marker.Prt	Marker input representing physical particles.
marker.Prt.write_hdf5	Write input data to the HDF5 file.
marker.GC	Particle input in guiding-center coordinates.
marker.GC.write_hdf5	Write input data to the HDF5 file.
marker.FL	Magnetic-field-line tracer input.
marker.FL.write_hdf5	Write input data to the HDF5 file.

Options opt

Options are used in every simulation.

There is only one type of options Opt and it is treated like any other input. The options are documented in Running Simulations.

options	Simulation options input.
options.Opt	Simulation options.

Templates

Data import

boozer_tokamak	Build mapping from real-space to Boozer coordinates assuming axisymmetric tokamak field.
import_geqdsk	Import axisymmetric magnetic field from EQDSK.
import_plasma_profiles	Import 1D plasma profiles.
import_adas	Import data from ADAS files.
import_wall_vtk	Import 3D wall from VTK file.
import_marsf	Import toroidal harmonics calculated with MARS-F.
mhd_consistent_potentials	Make MHD potentials consistent with E_par = 0 condition.
ascot4_particles	Convert marker input from ASCOT4 to ASCOT5.
ascot4_wall2d	Convert 2D wall data from ASCOT4 to ASCOT5.
ascot4_wall3d	Convert 3D wall data from ASCOT4 to ASCOT5.
ascot4_tokamak	Convert tokamak magnetic field data from ASCOT4 to ASCOT5.
ascot4_stellarator	Convert stellarator magnetic field data from ASCOT4 to ASCOT5.
ascot4_plasma1d	Convert 1D plasma data from ASCOT4 to ASCOT5.
ascot4_erad	Convert 1D electric field data from ASCOT4 to ASCOT5.
ascot4_neutral1d	Convert 1D neutral data from ASCOT4 to ASCOT5.
ascot4_alfven	Convert Alfvén MHD data from ASCOT4 to ASCOT5.

Premade studies

options_poincare	Generate options to generate Poincaré plot data.
marker_poincare	Generate markers at fixed intervals in radius.
options_tutorial	Create fast slowing-down simulation options with orbits and distributions enabled.

Analytic

Note

These are mainly used for testing.

bfield_analytical_iter_circular	Create ITER like but circular magnetic field.
plasma_flat	Create uniform single-species plasma that is flat inside the separatrix but inexistent outside.
neutral_flat	Create uniform single-species constant neutral data.
wall_rectangular	Create wall with a rectangular cross section.