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.
Magnetic field input. |
|
Axisymmetric tokamak field interpolated with splines. |
|
Write input data to the HDF5 file. |
|
Non-axisymmetric tokamak field. |
|
Write input data to the HDF5 file. |
|
Stellarator magnetic field. |
|
Write input data to the HDF5 file. |
|
Analytical tokamak field. |
|
Write input data to the HDF5 file. |
|
Magnetic field in Cartesian basis for testing purposes. |
|
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.
Electric field input. |
|
Uniform electric field in Cartesian basis. |
|
Write input data to the HDF5 file. |
|
One-dimensional electric field interpolated with cubic splines. |
|
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.
Input data representing plasma background species. |
|
Plasma profiles that have only radial dependency. |
|
Write input data to the HDF5 file. |
|
Same input as |
|
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.
Input representing first wall and other plasma facing components. |
|
Contour in Rz-plane that represents an axisymmetric wall. |
|
Write input data to the HDF5 file. |
|
Triangle mesh that represents a 3D wall. |
|
Write input data to the HDF5 file. |
Neutral neutral
Neutral particle profiles required when atomic (CX, etc.) reactions are included.
Input representing plasma neutral bakcground. |
|
|
Constant-on-flux-surfaces neutral profile. |
|
Write input data to the HDF5 file. |
Non-axisymmetric neutral data. |
|
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().
Input representing mapping from real-space to Boozer coordinates. |
|
Mapping between cylindrical and Boozer coordinates assuming that psi is axisymmetric. |
|
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).
Input containing MHD eigenmodes. |
|
Stationary MHD eigenfunctions. |
|
Write input data to the HDF5 file. |
|
Time-dependent MHD eigenfunctions. |
|
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.
Atomic reaction data HDF5 IO. |
|
Local atomic data. |
|
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.
Input data representing NBI. |
|
Object representing a bundle of injectors used as an input in BBNBI. |
|
Write input data to the HDF5 file. |
Markers marker
Simulation markers are always used except for BBNBI.
Markers whose orbits are solved within the ASCOT5 code. |
|
Marker input representing physical particles. |
|
Write input data to the HDF5 file. |
|
Particle input in guiding-center coordinates. |
|
Write input data to the HDF5 file. |
|
Magnetic-field-line tracer input. |
|
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.
Simulation options input. |
|
Simulation options. |
Templates
Data import
Premade studies
Analytic
Note
These are mainly used for testing.