`CoreIO`

Low level API for HDF5 data access and building the treeview.

Module for building the treeview that shows ASCOT5 HDF5 file contents.

Treeview consists of nodes acting as containers for other nodes and data. The tree is spanned by the RootNode.

class a5py.ascot5io.coreio.treeview.InputNode(root, path, h5, **kwargs)

Bases: _ParentNode

Node that represents an input parent group.

Input parent groups are “bfield”, “efield”, etc. in the HDF5 file that can contain several input data groups.

destroy(repack=True)

Remove this group from the HDF5 file.

Parameters:

repackbool, optional

If True, repack the HDF5 file.

Removing data from the HDF5 file only removes references to it and repacking is required to free the disk space. Repacking makes a copy of the HDF5 file and destroys the original, and it also requires 3rd party tool h5repack which is why it’s use is optional here.

get_contents()

Return metadata for all childs sorted by date.

Returns:

qidsarray_like, str: QIDs.
datesarray_like, str: Dates.
descsarray_like, str: Descriptions.
typesarray_like, str: Data types.

ls(show=True)

Get a string representation of the contents.

Parameters:

showstr, optional: If True, the contents are also printed on screen.

Returns:

contentsstr: Multiline string decorated with ANSI escape sequences that list all data groups within this node.

class a5py.ascot5io.coreio.treeview.ResultNode(root, path, h5, inputqids, **kwargs)

Bases: _Node, DataGroup

Node that represents a results group.

Result groups contain the data groups containing simulation results. Result node has its own meta data (QID, etc.) and its children can only be referenced by name e.g. resultnode.inistate. Result node also stores QIDs of the input groups used to obtain that result.

activate()

Set this group as active.

Active inputs are used when the simulation is run. Active groups are also used during post-processing.

destroy(repack=True)

Remove this group from the HDF5 file.

Parameters:

repackbool, optional

If True, repack the HDF5 file.

Removing data from the HDF5 file only removes references to it and repacking is required to free the disk space. Repacking makes a copy of the HDF5 file and destroys the original, and it also requires 3rd party tool h5repack which is why it’s use is optional here.

export(target_file, newgroup=False)

Copy this group with its contents to another HDF5 file.

Parameters:

target_filestr: Path to the file where the data is copied to.
newgroupbool, optional: If True, a new QID and date is generated for the copied group.

get_contents()

Return names of all childs.

Returns:

nameslist [str]: List of names.

get_date()

Get the date when this group was created.

Returns:

datestr: The date in YYYY-MM-DD hh:mm:ss format.

get_desc()

Get this group’s description.

Returns:

descstr: Documentation the user has used to describe this group.

get_name()

Return name of this group.

Returns:

namestr: The name of the group as “<group type>_<group qid>”.

get_qid()

Get QID of this group.

Returns:

qidstr: String with 10 characters containing numbers from 0-9 which is an unique identifier for this group.

get_type()

Return type of this group.

Returns:

gtypestr: Group type.

ls(show=True)

Get a string representation of the contents.

Parameters:

showstr, optional: If True, the contents are also printed on screen.

Returns:

contentsstr: Multiline string decorated with ANSI escape sequences that list this node’s meta data, all output data within this node, and inputs that were used.

set_desc(desc)

Set description for this group.

Note that the first word in the description is this group’s tag which can be used to refer to this group.

Parameters:

descstr: Short description for the user to document this group.

class a5py.ascot5io.coreio.treeview.RootNode(ascot, **kwargs)

Bases: _ParentNode

The entry node for accessing data in the HDF5 file.

The root node spawns the treeview creating all other nodes and data groups.

Attributes:

_ascotAscot: The Ascot object whose HDF5 file is what this tree structure represents.

destroy(repack=True)

Remove all results from the HDF5 file.

Parameters:

repackbool, optional

If True, repack the HDF5 file.

Removing data from the HDF5 file only removes references to it and repacking is required to free the disk space. Repacking makes a copy of the HDF5 file and destroys the original, and it also requires 3rd party tool h5repack which is why it’s use is optional here.

get_contents()

Return metadata for all childs sorted by date.

Returns:

qidsarray_like, str: QIDs.
datesarray_like, str: Dates.
descsarray_like, str: Descriptions.
typesarray_like, str: Data types.

get_runs(inputqid)

Fetch QIDs of runs using given input.

Parameters:

inputqidqid: QID of the input.

Returns:

qidslist [str]: List of run QIDs.

ls(show=True)

Get a string representation of the contents.

Parameters:

showstr, optional: If True, the contents are also printed on screen.

Returns:

contentsstr: Multiline string decorated with ANSI escape sequences that list all results and their meta data and currently active inputs.

Abstract classes for objects containing data.

class a5py.ascot5io.coreio.treedata.DataContainer(root, path, **kwargs)

Bases: object

Interface for providing access to underlying HDF5 data.

This class provides methods to change and access the raw data. The raw data is accessed (via h5py) as

with datacontainer as d:
    d["data"][:]

where d is the h5py.Group corresponding to this container.

Attributes:

_rootRootNode

The rootnode this object belongs to.

_pathstr

Path to this data within the HDF5 file.

_openedlist [obj]

List containing a single object, which is this data’s HDF5 group if the data is being accessed and None otherwise.

We are storing single item list, instead of storing the item directly, since this class is inherited by Note objects whose attributes cannot be changed directly. However, if the attribute is a list, the contents of that list can be changed ;).

class a5py.ascot5io.coreio.treedata.DataGroup(root, path, **kwargs)

Bases: DataContainer

Data container that also has meta data (QID, date, description).

activate()

Set this group as active.

Active inputs are used when the simulation is run. Active groups are also used during post-processing.

destroy(repack=True)

Remove this group from the HDF5 file.

Parameters:

repackbool, optional

If True, repack the HDF5 file.

Removing data from the HDF5 file only removes references to it and repacking is required to free the disk space. Repacking makes a copy of the HDF5 file and destroys the original, and it also requires 3rd party tool h5repack which is why it’s use is optional here.

export(target_file, newgroup=False)

Copy this group with its contents to another HDF5 file.

Parameters:

target_filestr: Path to the file where the data is copied to.
newgroupbool, optional: If True, a new QID and date is generated for the copied group.

get_date()

Get the date when this group was created.

Returns:

datestr: The date in YYYY-MM-DD hh:mm:ss format.

get_desc()

Get this group’s description.

Returns:

descstr: Documentation the user has used to describe this group.

get_name()

Return name of this group.

Returns:

namestr: The name of the group as “<group type>_<group qid>”.

get_qid()

Get QID of this group.

Returns:

qidstr: String with 10 characters containing numbers from 0-9 which is an unique identifier for this group.

get_type()

Return type of this group.

Returns:

gtypestr: Group type.

set_desc(desc)

Set description for this group.

Note that the first word in the description is this group’s tag which can be used to refer to this group.

Parameters:

descstr: Short description for the user to document this group.

Module for creating and modifying the HDF5 file and for accessing meta data.

ASCOT5 HDF5 file is built as follows. At top level are parent groups, one (and only one) for each type of input (e.g. bfield for magnetic field input) and one parent group that contains all the results.

Parent groups contain groups that hold the actual datasets. Single parent can have multiple groups e.g. bfield can store multiple magnetic field inputs. The result group is a different in a sense that it contains run groups, one for each simulation, which then contain the groups that store inistate, endstate, and whatever diagnostics were used. However, here we refer to the top level groups as parents, and the groups that are directly below them as data containers.

A typical structure of a file can be like this:

> / > /bfield > /bfield/B_2DS_1234567890 > /bfield/B_2DS_2345678901 > /bfield/B_3DS_3456789012 > … > <other input groups> > … > /results > /results/run_4567890123 > /results/run_5678901234

The number in group name is unique identifier (QID) which is generated when a group is created. It is generated from a 32 bit random integer and as such it is almost quaranteed to be unique.

QID is used to determine which input group is active, i.e., to be used in a simulation, and to which run group the simulation results are written. QID of the active group is stored as an attribute (in a string format) in the parent. For the results parent this is the QID of the most recent run (unless manually changed). Run groups also store QIDs of all input fields used in that particular run.

All groups also store date and time at which they where created and also a description field that user can modify at will.

The groups should be created, removed, and their metadata accessed via this module. The actual datasets are accessed via corresponding modules. This module assumes the HDF5 file is open when these routines are called, and closed afterwards.

a5py.ascot5io.coreio.fileapi.INPUTGROUPS = ['options', 'bfield', 'efield', 'marker', 'plasma', 'neutral', 'wall', 'boozer', 'mhd', 'asigma', 'nbi']: Names of the input parent groups.

a5py.ascot5io.coreio.fileapi.OUTPUTGROUPS = ['inistate', 'endstate', 'dist5d', 'distrho5d', 'dist6d', 'distrho6d', 'orbit', 'transcoef']: Names of the output data containers in runs.

a5py.ascot5io.coreio.fileapi.VERSION = '5.5.6': Current version of the code.

a5py.ascot5io.coreio.fileapi.add_group(f, parent, group, desc=None)

Create a new group. A parent is created if need be.

If parent is created, then this new group is set as active.

Parameters:

fh5py.File: Open HDF5 file.
parentstr or h5py.Group: Parent of the created group.
groupstr: The group name.
descstr, optional: Description for the group.

Returns:

newgrouph5py.Group: The new group.

a5py.ascot5io.coreio.fileapi.copy_group(fs, ft, group, newgroup=False)

Copy group from one file to another. A parent is also created if need be.

The new group is set as active if the parent on the target file has no other groups. The copied group retains its original QID and date of creation.

Parameters:

fsh5py.File: File from which the group is copied.
fth5py.File: File to which the group is copied.
groupstr pr h5py.Group: The group to be copied.
newgroupbool, optional: Flag indicating if copied group should be given new QID and date.

Returns:

groupth5py.Group: The new group which is a copy of group at ft.

Raises:

AscotNoDataException: Raised if the copied group cannot be found.
AscotIOException: Raised if the group already exists on the target file.

a5py.ascot5io.coreio.fileapi.get_active(f, parent)

Get active group.

Parameters:

fh5py.File: Open HDF5 file.
parentstr or h5py.Group: Group object or its name.

Returns:

grouph5py.Group: The active group.

Raises:

AscotNoDataException: Raised if the parent or the active group does not exist.

a5py.ascot5io.coreio.fileapi.get_activeqid(f, parent)

Get QID of the currently active group.

Parameters:

fh5py.File: Open HDF5 file.
parentstr or h5py.Group: Parent whose active group is sought.

Returns:

qidstr: QID string.

a5py.ascot5io.coreio.fileapi.get_date(f, group)

Get date.

Parameters:

fh5py.File: Open HDF5 file.
groupstr or h5py.Group: Group object or its name.

Returns:

datestr: Date as a string in format YYYY-MM-DD hh:mm:ss.

Raises:

AscotNoDataException: Raised if the group does not exist.

a5py.ascot5io.coreio.fileapi.get_desc(f, group)

Get group description.

Parameters:

fh5py.File: Open HDF5 file.
groupstr or h5py.Group: Group object or its name.

Returns:

descstr: Description as a string.

Raises:

AscotNoDataException: Raised if group does not exist.

a5py.ascot5io.coreio.fileapi.get_group(f, qid)

Scan the file and return the group the QID corresponds to.

Parameters:

fh5py.File: Open HDF5 file.
qidstr: QID string.

Returns:

grouph5py.Group: Group or None if the group was not present.

a5py.ascot5io.coreio.fileapi.get_inputqids(f, rungroup)

Get all QIDs that tell which input was used in the given run group.

Parameters:

fh5py.File: Open HDF5 file.
rungroupstr or h5py.Group: Either the run group object or its name.

Returns:

qidscollections.OrderedDict [str, str]: Ordered dictionary with “parent name” - “qid” value pairs with the order being same as in INPUTGROUPS.

Raises:

AscotNoDataException: Raised if run group does not exist.

a5py.ascot5io.coreio.fileapi.get_qid(group)

Get QID from a given group.

Parameters:

groupstr or h5py.Group: Group object or its name.

Returns:

qidstr: QID string.

Raises:

AscotNoDataException: Raised if group does not have a valid QID.

a5py.ascot5io.coreio.fileapi.get_qids(f, parent)

Get QIDs of all the groups that a given parent contains.

The QIDs are returned as list of no specific order.

Parameters:

fh5py.File: Open HDF5 file.
parentstr or h5py.Group: Parent object or its name.

Returns:

qidslist [str]: A list of QID strings.

Raises:

AscotNoDataException: Raised if parent group does not exist.

a5py.ascot5io.coreio.fileapi.get_type(group)

Get type from a given group or from its name.

Parameters:

groupstr or h5py.Group: Group object or its name.

Returns:

typestr: Group’s type.

Raises:

AscotNoDataException: Raised if group does not have a valid type.

a5py.ascot5io.coreio.fileapi.read_data(group, name)

Read a dataset including its units if present.

Parameters:

grouph5py.Group: HDF5 group containing the dataset.
namestr: Name of the dataset.

Returns:

datanp.array or unyt.array, (N,)

Dataset with units read from the dataset attribute “unit”.

If dataset has no “unit” attribute, ordinary np.array is returned.

a5py.ascot5io.coreio.fileapi.remove_group(f, group)

Remove a group.

If this was an active group, a most recent group is set as an active instead. If no other groups exist the parent is also removed.

Input groups are not removed if they have been used in an existing run.

Note that to reclaim the disk space which the group occupied, one needs to call h5repack in a terminal.

Parameters:

fh5py.File: Open HDF5 file.
groupstr or h5py.Group: The group to be removed.

Raises:

AscotNoDataException: Raised if group could not be found.
AscotIOException: Raised if the group is input used by a run.

a5py.ascot5io.coreio.fileapi.set_active(f, group)

Set given group as active.

Parameters:

fh5py.File: Open HDF5 file.
groupstr or h5py.Group: Group object or its name.

Raises:

AscotNoDataException: Raised if the group or its parent does not exist.

a5py.ascot5io.coreio.fileapi.set_activeqid(f, qid)

Set a group with the given QID as the active one.

Parameters:

fh5py.File: Open HDF5 file.
qidstr: QID.

a5py.ascot5io.coreio.fileapi.set_desc(f, group, desc)

Set group description.

Parameters:

fh5py.File: Open HDF5 file.
groupstr or h5py.Group: Group object or its name.
descstr: Description as a string.

Raises:

AscotNoDataException: Raised if group does not exist.

a5py.ascot5io.coreio.fileapi.write_data(group, name, data, shape, dtype, unit=None, compress=False)

Write a dataset.

The shape of the written dataset is same as the input array.

Parameters:

grouph5py.Group: HDF5 group where the dataset will be written.
namestr: Name of the new dataset.
datanp.array: Data to be written.
dtypestr: Data type.
unitstr, optional: Unit string if the data has units.
compressbool, optional: Use gzip compression

CoreIO

`CoreIO`