CONTENT
- Introduction
- DYON output
- Files provided
- Running the scripts
- The main files (functions 'put_to_IMAS', 'get_from_IMAS' and test scripts)
- IDS core_profiles
- IDS core_sources
- IDS equilibrium
- IDS gas_injection
- IDS magnetics
- IDS radiation
- IDS wall
- Service functions
- DYON inputquit
- To be done
Introduction
This page contains a description of MATLAB scripts supporting the storage of DYON input and output data files in IMAS.
The repository folder of the DYON output wrapper is ~g2yyakov/public/dyon/stable.
This document can be found on the ACH-PSNC Confluence page (DYON IMASification - Scientific Worfklows - PCSS Confluence (psnc.pl), https://docs.psnc.pl/display/WFMS/DYON+IMASification).
DYON output
The storage of the DYON output in IMAS is supported by two MATLAB functions, put_to_IMAS and get_from_IMAS. Depending on the situation, they can be integrated to the code or used separately as wrappers providing the connection between DYON and IMAS. The scripts test_put_to_IMAS and test_get_from_IMAS are provided, which illustrate how the functions can be called as wrappers.
The available IMAS Data Dictionary (DD) does not satisfy all requirements of DYON. Therefore, the functions put_to_IMAS and get_from_IMAS are to be extended after the planned extension of the DD.
Now the output data are placed into 7 IMAS IDS's (Interface Data Structures - sections of the IMAS DD describing tokamak subsystems or tokamak physics chapters): 'core_profiles', 'core_sources', 'equilibrium', 'gas_injection', 'magnetics', 'radiation', and 'wall' (this list is to be extended). The allocation of the data in the IDS's and the functions supporting it are described below.
Files provided
File name | Content |
---|---|
put_to_IMAS.m | Function saving IMAS output data to IMAS |
get_from_IMAS.m | Function reading IMAS output data from IMAS |
test_put_to_IMAS.m | Sample script invoking the function put_to_IMAS |
test_get_from_IMAS.m | Sample script that invokes the function get_from_IMAS and compares the recovered data with the initial ones |
put_core_profiles.m | Function saving data to the 'core_profiles' IDS |
put_core_sources.m | Function saving data to the 'core_sources' IDS |
put_equilibrium.m | Function saving data to the 'equilibrium' IDS |
put_gas_injection.m | Function saving data to the 'gas_injection' IDS |
put_magnetics.m | Function saving data to the 'magnetics' IDS |
put_radiation.m | Function saving data to the 'radiation' IDS |
put_wall.m | Function saving data to the 'wall' IDS |
get_core_profiles.m | Function recovering the saved data from the 'core_profiles' IDS |
get_core_sources.m | Function recovering the saved data from the 'core_sources' IDS |
get_equilibrium.m | Function recovering the saved data from the 'equilibrium' IDS |
get_gas_injection.m | Function recovering the saved data from the 'gas_injection' IDS |
get_magnetics.m | Function recovering the saved data from the 'magnetics' IDS |
get_radiation.m | Function recovering the saved data from the 'radiation' IDS |
get_wall.m | Function recovering the saved data from the 'wall' IDS |
arrange_ion_densities.m | Function putting the densities of all charge states and the properties of an ion to 'core_profiles' |
arrange_neutral_density.m | Function putting the density and the properties of a neutral atom to 'core_profiles' |
arrange_radiation.m | Function arranging the radiation power density (together with all atom attributes) for given radiation type and neutral/ion kind |
extract_ion_densities.m | Function extracting the densities of all charge states from the 'core_profiles' IDS |
find_source.m | Function finding the location of the source with a given data dictionary index in an AoS |
find_species.m | Function finding the location of the species with a given label in AoS |
compare_core_profiles.m | Function comparing the data restored from the 'core_profiles' IDS with the initial content |
compare_core_sources.m | Function comparing the data restored from the 'core_sources' IDS with the initial content |
compare_equilibrium.m | Function comparing the data restored from the 'equilibrium' IDS with the initial content |
compare_magnetics.m | Function comparing the data restored from the 'magnetics' IDS with the initial content |
compare_radiation.m | Function comparing the data restored from the 'radiation' IDS with the initial content |
compare_wall.m | Function comparing the data restored from the 'wall' IDS with the initial content |
STEP_10003_N_O_impurities_Cwall_2022_11_12_17_53_27.mat | Example of MAT-file with DYON results (received from Kim Hyun-Tae) |
STEP_10003_v4_600kW_EBWCD_2022_6_20_21_24_29.mat | Example of MAT-file with DYON results (received from Kim Hyun-Tae) |
README.txt | Brief user guide |
DYON-IMAS_wrappers_user_guide.pdf | This documentation in PDF-format |
Running the scripts
To launch the test scripts, do the following:
1. Enter:
module load imasenv/<IMASversion>
Here <IMASversion> is 3.37.0 or higher.
2. The scripts in its present form use the IMAS database 'step'. If you are planning to use it and this database is non-existent, enter the following command to create the database:
imasdb step
You can replace 'step' with another IMAS database name, but do not forget to create it and change the variable 'machine' in test_put_to_IMAS.m and test_get_from_IMAS.m.
3. Enter either
matlab
or
matlab -nodesktop -nosplash
In the nodesktop mode, MATLAB should work faster (I did not notice a significant difference - YY). When using the nodesktop mode, do not forget to run the command 'quit()' to end the session (otherwise, a dangling MATLAB session may remain).
4. Run test_put_to_IMAS.m in order to save in IMAS the data from an available DYON output MAT-file (you can change shot, run, IDS comments etc. by changing the parameters in this script).
5. Type 'viz' (on a console with imasenv loaded) to see the content of the IMAS database.
6. To get back the DYON output data, run test_get_from_IMAS.m.
The main files (functions 'put_to_IMAS', 'get_from_IMAS' and test scripts)
The script test_put_to_IMAS.m loads a MAT-file containing the DYON results (the name of the file is defined in the script). It is assumed that there is a structure with the name 'output' among the variables loaded from the MAT-file and that this structure holds all the data that must be saved.
The script then defines the rest of arguments of the function 'put_to_IMAS' and invokes it. The dummy arguments of this function are as follows:
Name | Type | Description |
---|---|---|
output | struct | structure containing the DYON output to be saved |
H_mass | float | mass of the H isotope (in units of the proton mass) |
machine | symbol array | name of the IMAS database (usually a tokamak name) |
shot | int | shot number |
run | int | run number |
comment | symbol array | comment characterizing the data to be saved (put into each IDS) |
data_source | symbol array | text describing the origin of the data (put into each IDS) |
The function creates an IMAS data entry for the given 'shot' and 'run' parameters (note that the database with the required name must exist; otherwise, an error is raised). Then it invokes several functions that put data to separate IDS's ('put_core_profiles', 'put_core_sources', 'put_equilibrium', 'put_gas_injection', 'put_magnetics', 'put_wall', and 'put_radiation') and closes the database. After that, the content of the 'output' structure is put to IMAS. The DD fields to which the data are placed can be found in the table IMAS interface with DYON - Google Documents. Some more comments will be given in next sections of this document for each IDS separately.
The script test_get_from_IMAS.m defines the input parameters of the function get_from_IMAS and invokes it. The dummy arguments of this function are as follows:
Name | Type | Description |
---|---|---|
machine | symbol array | name of the IMAS database (usually a tokamak name) |
shot | int | shot number |
run | int | run number |
The function calls several functions that extract data from separate IDS's ('get_core_profiles', 'get_core_sources', 'get_equilibrium', 'get_gas_injection', 'get_magnetics', 'get_wall', and 'get_radiation') and closes the database. The function returns the 'output' structure, which is to be equivalent (after the script is complete) to the 'output' structure that was initially put to IMAS. In addition, the function prints to the screen the comments extracted from all IDS's.
The script in its current form contains some parts that are used for verification and debugging. It imports the original DYON output and compares it with the one recovered from IMAS. These part should be removed in the future when such comparison is not required.
IDS core_profiles
The quantities stored in this IDS include electron and ion temperatures, densities of electrons, several ion species and several neutral species, loop voltage, and plasma current. Although all these quantities are represented by single values, most of them are stored as 1D-profiles on the formal grid consisting of a single point. When the ion and neutral densities are recovered from the IDS, the ion species are selected in the array of structures by their charge numbers (not by their places in the array). This is done to permit more flexibility if the set of the ions simulated by the code changes. At present, the storage of ion quantities in the IDS is organized as follows:
Element | Ion label | Ion index | Neutral label | Neutral index |
---|---|---|---|---|
H | H | 1 | - | - |
Be | Be | 2 | Be0 | 1 |
C | C | 3 | C0 | 2 |
N | N | 4 | N0 | 3 |
O | O | 5 | O0 | 4 |
He | He | 6 | He0 | 5 |
Ne | Ne | 7 | Ne0 | 6 |
Here 'ion label' and 'ion index' are the label and the index of the species in the core_profiles.profiles1d.ion AoS (array of structures), respectively; 'neutral label' and 'neutral index' are the label and the index of the species in the core_profiles.profiles1d.neutral AoS (array of structures), respectively.
For all ions except for H, several ion states (charge states) are defined, the index of the 'state' array element being equal to the ion charge number.
The following functions support I/O with the 'core_profiles' IDS:
function put_core_profiles (output, H_mass, idx, comment, data_source, imas_version, access_layer)
Write a suitable part of the 'output' structure to the 'core_profiles' IDS.
This function invokes the functions 'arrange_ion_densities' and 'arrange_neutral_density'.
Name | Type | Description |
---|---|---|
output | struct | structure containing the DYON output to be saved |
H_mass | float | mass of the H isotope (in units of the proton mass) |
idx | int | the data entry identifies |
comment | symbol array | comment characterizing the data to be saved |
data_source | symbol array | text describing the origin of the data |
imas_version | symbol array | IMAS major version (prepared in the 'put_to_IMAS' function) |
access_layer | symbol array | IMAS access layer version used when writing the IDS (prepared in the 'put_to_IMAS' function) |
function [output, comment, data_source, imas_version, access_layer] = get_core_profiles (output, idx, get_time)
Add the data from the 'core_profiles' IDS to the 'output' structure.
This function invokes the functi on ' extract_ion_densities '.
Name | Type | Description |
---|---|---|
output | struct | structure containing the DYON output recovered from IMAS |
idx | int | the data entry identifies |
get_time | boolean | switch on transferring the IDS time to the output time |
comment | symbol array | comment characterizing the recovered data |
data_source | symbol array | text describing the origin of the data |
imas_version | symbol array | IMAS major version |
access_layer | symbol array | IMAS access layer version used when writing the IDS |
IDS core_sources
The source densities are stored as 1D-profiles on the formal grid consisting of a single point although they are represented by single values.
When the data are recovered from the IDS, the sources are sought in the array of structures by their DD indices (not by their places in the array). This is done to permit more flexibility if the set of the sources calculated by the code changes. At present, the storage of sources in the IDS is organized as follows:
Source | DD index | IDS name | IDS index |
---|---|---|---|
Ohmic heating to electrons | 7 | Ohmic | 1 |
Electron energy loss for ionization | 601 | ionization | 2 |
Energy loss due to radiation including excitation, recombination, and bremsstrahlung | 200 | radiation | 3 |
Electron energy loss due to equilibration with ions | 402 | equipartition | 4 |
Electron energy loss due to particle transport | 400 | transport | 5 |
Ion energy loss due to particle transport | 400 | transport | 5 |
ECH power absorbed to electrons | 3 | ECH | 6 |
ECH + EBW power absorbed to electrons | 901 | ECH&EBW | 7 |
Ion energy loss due to charge exchange | 305 | CX | 8 |
Net electron heating power in a unit volume | 1 | net_power | 9 |
Net ion heating power in a unit volume | 1 | net_power | 9 |
Here 'IDS index' is the location of the source in the core_sources.source AoS (which can be changed if required). The 'IDS name' is the label of the source (a part of the source identifier), which is not used when the data are extracted from the IDS. The source 901 (ECH + EBW power absorbed to electrons) is a custom source missing in the DD.
The data are put to the 'core_sources' IDS by the function 'put_core_sources'. Its interface is as follows:
function put_core_sources (output, idx, comment, data_source, imas_version, access_layer)
Name | Type | Description |
---|---|---|
output | struct | structure containing the DYON output to be saved |
idx | int | the data entry identifies |
comment | symbol array | comment characterizing the data to be saved |
data_source | symbol array | text describing the origin of the data |
imas_version | symbol array | IMAS major version (prepared in the 'put_to_IMAS' function) |
access_layer | symbol array | IMAS access layer version used when writing the IDS (prepared in the 'put_to_IMAS' function) |
The data are extracted from the 'core_sources' IDS by the function 'get_core_sources'. Its interface is identical to that of 'get_core_profiles' (Section 2.4).
IDS equilibrium
Data exchange with the 'equilibrium' IDS is carried out by the functions 'put_equilibrium' and 'get_equilibrium'. The interface of 'get_equilibrium' is identical to that of 'get_core_profiles' (Section 2.4). The interface of 'put_equilibrium' is identical to that of 'put_core_sources' (Section 2.5).
IDS gas_injection
Data exchange with the 'gas_injection' IDS is carried out by the functions 'put_gas_injection' and 'get_gas_injection'. The interface of 'get_gas_injection' is identical to that of 'get_core_profiles' (Section 2.4). The interface of 'put_gas_injection' is identical to that of 'put_core_sources' (Section 2.5).
The gas puffing units are electron/s in DYON and Pa*m^3/s in IMAS. The unit conversion is made on the assumption that the gas is H2 (D2) molecules with the temperature of 300 K:
PIMAS = PDYON k T / 2,
with P the gas puffing, T = 300 K, k = 1.3807*10-23 J/K.
IDS magnetics
Data exchange with the 'magnetics' IDS is carried out by the functions 'put_magnetics' and 'get_magnetics'. The interface of 'get_magnetics' is identical to that of 'get_core_profiles' (Section 2.4). The interface of 'put_magnetics' is identical to that of 'put_core_sources' (Section 2.5).
IDS radiation
The emission densities are stored as 1D-profiles on the formal grid consisting of a single point although they are represented by single values.
When the data are recovered from the IDS, the emission processes are sought in the array of structures by their DD indices. At present, the storage of process in the IDS is organized as follows:
Process | DD index | IDS name | IDS index |
---|---|---|---|
Total emission from line radiation | 10 | Line_radiation | 1 |
Recombination and bremsstrahlung emission from ions | 901 | Recombination_and_bremsstrahlung | 2 |
Radiation from charge exchange reactions between H isotope atoms and various ions | 902 | Charge_exchange | 3 |
Here 'IDS index' is the location of the source in the 'radiation.process' AoS (which can be changed if required). The 'IDS name' is the label of the process (a part of the process identifier), which is not used when the data are extracted from the IDS. The processes with DD indices 901 and 902 are custom processes missing in the DD.
The radiating species are sought in the AoS's 'radiation.process(:).profiles1d(1).ion' and 'radiation.process(:).profiles1d(1).neutral' by their labels, which are the standard chemical element notations.
Data exchange with the 'radiation' IDS is carried out by the functions 'put_radiation' and 'get_radiation'. The interface of 'get_radiation' is identical to that of 'get_core_profiles' (Section 2.4). The interface of 'put_radiation' is identical to that of 'put_core_sources' (Section 2.5).
IDS wall
The 'wall' IDS is used to store sputtering coefficients. When the data are extracted from the IDS, each coefficient is found in the AoS by the labels of the sputtered and incident species, which are the standard chemical element notations.
Data exchange with the 'wall' IDS is carried out by the functions 'put_wall' and 'get_wall'. The interface of 'get_wall' is identical to that of 'get_core_profiles' (Section 2.4). The interface of 'put_wall' is identical to that of 'put_core_sources' (Section 2.5).
Service functions
function [ion] = arrange_ion_densities (mass, Z_n, label, neutral_index, densities)
Prepare a structure containing the densities of all ion charge states of an element for the core_profiles IDS and other element characteristics.
Name | Type | Description |
---|---|---|
ion | struct | structure containing the properties of the ion species |
mass | float | ion mass number |
Z_n | float | charge number of the nucleus |
label | symbol array | label of the ion chemical element |
neutral_index | int | index of the respective neutral in the AoS |
densities | 1d float array | array of densities, densities(Z) being the density of the charge state Z |
function [neutral] = arrange_neutral_density (mass, Z_n, label, ion_index, density)
Prepare a structure containing the density of neutral atoms of an element for the core_profiles IDS.
Name | Type | Description |
---|---|---|
neutral | struct | structure containing the properties of the neutral species |
mass | float | ion mass number |
Z_n | float | charge number of the nucleus |
label | symbol array | label of the chemical element |
ion_index | int | index of the respective ion in the AoS |
density | float | neutral density |
function [neutral_sort] = arrange_radiation (label, mass, Z, power_density)
Arrange the structure holding the data about emissivity and other characteristics of a neutral species.
Name | Type | Description |
---|---|---|
neutral_sort | struct | structure containing the emissivity and properties of the neutral species |
label | symbol array | label of the chemical element |
mass | float | ion mass number |
Z | float | charge number of the nucleus |
power_density | float | neutral density |
function [density, ion_found] = extract_ion_densities (profiles, Z)
Extract densities of all charge states of an ion species from the core_profiles IDS.
Name | Type | Description |
---|---|---|
density | 1D float array | the array elements with the numbers 1, ..., Z hold the densities of the corresponding charge states; the element Z+1 hold the neutral density |
ion_found | boolean | equals to false if the ion with the given Z is missing |
profiles | struct | time slice of the AoS core_profiles.profiles_1d |
Z | float | charge number of the nucleus |
function [AOS_index] = find_source (sources, dictionary_index)
Find location of the element with a given data dictionary index in an AOS (in particular, the source in core_sources.source and the process in radiation.process).
Name | Type | Description |
---|---|---|
AOS_index | int | index of the required element in the array |
sources | struct | AoS where the search is performed |
dictionary_index | int | DD index of the required element |
function index = find_species (species_list, label)
Find location of the element with a given label in AoS. The function is used to find the required spruttering coefficient in the 'wall' IDS. The label is the chemical element label; it is hold in the 'label' leaf of each AoS element.
Name | Type | Description |
---|---|---|
index | int | index of the required element in the array |
species_list | struct | AoS where the search is performed |
label | symbol array | label of the required element |
DYON input
Description of the scripts processing the DYON input (to be done).
To be done
- Extending the input script (pending the planned DD extension)
- Adding code descriptions to all IDS's.
- Switching to the HDF5 IMAS backend (pending HDF5 debugging on Gateway).
The scientific work is published for the realization of the international project co-financed by Polish Ministry of Science and Higher Education in 2019 from financial resources of the program entitled "PMW"; Agreement No. 5040/H2020/Euratom/2019/2
This work has been carried out within the framework of the EUROfusion Consortium and has received funding from the Euratom research and training programme 2014–2020 under grant agreement No 633053. The views and opinions expressed herein do not necessarily reflect those of the European Commission or ITER