14.4. steps.API_2.saving

The saving module contains classes related to data saving during simulation.

14.4.1. Detailed documentation

Result selectors
- steps.API_2.saving.ResultSelector
- steps.API_2.saving.CustomResults
Saving to database
- steps.API_2.saving.DatabaseHandler
  steps.API_2.saving.SQLiteDBHandler
  
  steps.API_2.saving.HDF5Handler
  
  steps.API_2.saving.XDMFHandler
- steps.API_2.saving.DatabaseGroup
  steps.API_2.saving.HDF5Group
  
  steps.API_2.saving.SQLiteGroup

class ResultSelector(sim, *args, **kwargs)[source]

Bases:

Class to describe which data should be saved during simulation

Parameters: sim (steps.API_2.sim.Simulation) – The simulation for which we want to select data

This class works in a way that is very similar to steps.API_2.sim.SimPath, paths to the data that should be saved are built in the same way, using dot syntax. For steps.API_2.sim.SimPath, the root of the path is the simulation itself and when a path is completed with a property (e.g. Count), it returns the actual value in the simulation. Since ResultSelector aims at describing the data to be saved, we have to use a different root for our paths:

>>> sim.comp1.S1.Count
13
>>> rs = ResultSelector(sim)
>>> rs.comp1.S1.Count
comp1.S1.Count

While the path whose root is the actual simulation returns a number, the path whose root is the result selector object does not.

Any methods defined in steps.API_2.sim.SimPath can be used to build result selector paths. In addition, result selectors can be combined using standard arithmetic operators (see ResultSelector.__add__(), etc.) and can be concatenated with << (see ResultSelector.__lshift__()):

rs1 = rs.comp1.S1.Count + rs.comp1.S2.Count  # This result selector will save a single
                                             # value that corresponds to the sum of S1
                                             # and S2 counts in comp1.

rs2 = rs.comp1.S1.Count << rs.comp1.S2.Count # This one will save 2 values, the count of
                                             # S1 in comp1 and the count of S2 in comp1.

Result selectors can also transform data and only save the result of the transformation:

rs3 = rs.SUM(rs.TETS(tetlst).S1.Count) # This will save only one value: the total number
                                       # of S1 in all the tetrahedrons in tetlst.

Once we defined all our result selectors, we need to add them to the steps.API_2.sim.Simulation so that the corresponding data gets saved during simulation runs. This is done with e.g.:

sim.toSave(rs1, rs2, rs3, dt=0.01) # Save the three result selectors every 0.01 seconds.

After simulations have been run, results can be accessed with the same result selector objects:

rs1.data[0] # Accessing the data saved during run 0
rs1.time[0] # The time points associated to each saving for run 0

Usage of result selectors is presented in more details in the user guide.

classmethod FromFile(path)[source]

Load data that has been saved to a file

Parameters: path (str) – Path to the file

Result selectors that have been saved to file (with the toFile() method), can then be loaded in a different python process and be used in the same way as in the simulaiton process.

Usage:

rs1 = ResultSelector.FromFile('path/to/file')

plt.plot(rs1.time[0], rs1.data[0])
plt.legend(rs1.labels)
...

property time

Get the time points at which data saving was done for this result selector

An accessor to the timepoints data that should then be indexed with square brackets notation. The underlying data it two dimensional; the first dimension corresponds to runs and the second to time.

Type: Data accessor, read-only

Usage assuming 5 runs of 1s with data saving every 10ms:

>>> rs1.time[0]      # Time points of first run
array([0., 0.01, 0.02, ..., 0.98, 0.99, 1.])
>>> rs1.time[0, -1]  # Last time point of first run
array(1.)
>>> rs1.time[0][-1]  # Same as above
array(1.)
>>> rs1.time[:, -1]  # Last time point of all 5 runs
array([1., 1., 1., 1., 1.])
>>> rs1.time[1:3, 0] # First time point of 2nd and 3rd runs
array([0, 0])
>>> rs1.time[...]    # All time points of all runs
array([[0., 0.01, 0.02, ..., 0.98, 0.99, 1.],
       [0., 0.01, 0.02, ..., 0.98, 0.99, 1.],
       [0., 0.01, 0.02, ..., 0.98, 0.99, 1.],
       [0., 0.01, 0.02, ..., 0.98, 0.99, 1.],
       [0., 0.01, 0.02, ..., 0.98, 0.99, 1.]])

Warning

Although the type of this property implements square bracket element access, it is not a list or an array itself and does not directly contain the data. The data is only really accessed upon using the square bracket notation. To force the retrieval of all the data, it is possible to use the ellipsis notation in square brackets: rs.time[...].

property data

Get the data that was saved by this result selector

An accessor to the data that should then be indexed with square brackets notation The underlying data it three dimensional; the first dimension corresponds to runs, the second to time, and the third to saved paths.

Type: Data accessor, read-only

Usage assuming 5 runs of 3s, saving 3 values every 1 ms:

>>> rs1.data[0]      # Data from the first run
array([[312., 221.,   0.],
       [310., 219.,   2.],
       [308., 217.,   4.],
       ...
       [206., 115., 106.],
       [205., 114., 107.],
       [205., 114., 107.]])
>>> rs1.data[0, -1]  # Data corresponding to the last time point of first run
array([205., 114., 107.])
>>> rs1.data[0][-1]  # Same as above
array([205., 114., 107.])
>>> rs1.data[:, -1]  # Data corresponding to the last time point of all 5 runs
array([[205., 114., 107.],
       [189.,  98., 123.],
       [188.,  97., 124.],
       [185.,  95., 127.],
       [198., 107., 114.]])
>>> rs1.data[0, :, 0] # First saved value for all time points of first run
array([312., 310, 308, ..., 206, 205, 205])
>>> rs1.data[...]    # All data from all runs
array([[[312., 221.,   0.],
        [310., 219.,   2.],
        [308., 217.,   4.],
        ...,
        [206., 115., 106.],
        [205., 114., 107.],
        [205., 114., 107.]],
...
       [[312., 221.,   0.],
        [309., 218.,   3.],
        [305., 214.,   7.],
        ...,
        [199., 108., 113.],
        [199., 108., 113.],
        [198., 107., 114.]]])

Warning

Although the type of this property implements square bracket element access, it is not a list or an array itself and does not directly contain the data. The data is only really accessed upon using the square bracket notation. To force the retrieval of all the data, it is possible to use the ellipsis notation in square brackets: rs.data[...].

property labels

A list of descriptions of the values saved by the result selector

Type: List[str]

By default labels are automatically generated from the result selector. Assuming 3 saved values, one can access their values with:

>>> rs1.labels # Default values, built from the simulation paths used for saving
['comp.molA.Count', 'comp.molB.Count', 'comp.molC.Count']

The labels can also be set by the user but it needs to be done before steps.API_2.sim.Simulation.newRun() has been called. Assuming 3 saved value, one would write:

>>> rs1.labels = ['custom1', 'custom2', 'custom3']

Labels be saved to whichever support the result selector is being saved to (memory, file, database, etc.).

property metaData

Meta data relative to the values saved by the result selector

Type: Mapping[str, List[Union[str, int, float, None]]]

This property allows the user to save additional static (i.e. not time-dependent) data about the values being saved by the result selector. It works as a mapping between arbitrary string keys and lists of values that have the same length as the number of values saved by the result selector.

The meta data needs to be set before steps.API_2.sim.Simulation.newRun() has been called. Assuming 3 values saved, one could write:

>>> rs1.metaData['key1'] = ['str1', 'str2', 'str3']
>>> rs1.metaData['key2'] = [1, 2, 3]
>>> rs1.metaData['key1']
array(['str1', 'str2', 'str3'], dtype='<U4')
>>> 'key2' in rs1.metaData
True
>>> 'key3' in rs1.metaData
False

Like labels, meta data will be saved to whichever support the result selector is being saved to (memory, file, database, etc.).

Note

Some path elements automatically define their own meta data, one can always check which meta data is already declared with e.g. print(rs1.metaData.keys())

Warning

Although the type of this property implements square bracket key access, it is not a dict itself and does not directly contain the data. The data is only really accessed upon using the square bracket notation. However, it does implement keys(), items(), __iter__() and __contains__() so it can be used like a dict to some extent.

property description

String description of the result selector

Type: str

All results selectors have a default string description generated by STEPS. It can be modified by setting this property and the changes will be saved to whichever support the result selector is being saved to (memory, file, database, etc.).

toFile(path, buffering=- 1)[source]

Specify that the data should be saved to a file

Parameters

path (str) – The path to the file
buffering (int) – The buffering parameter passed to the open() function, see https://docs.python.org/3/library/functions.html#open for details

This method should be called before steps.API_2.sim.Simulation.newRun() has been called. The file is written in a custom binary format and can be read in a different python process by creating a result selector from file with ResultSelector.FromFile().

Warning

After all simulations are finished, depending on the buffering policy, it is possible that the file does not contain all the data. The data will be flushed to the file upon destruction of the result selector (when the python process ends for example). This should not create any issues for using the result selector in the process in which it was created (because the data that might not be written to file is kept in memory) but it could create issues when trying to load the file from another python process while the first one is still running.

save()[source]

Trigger saving of the result selector at the current simulation time

Most saving should be done automatically by providing a dt or a timePoints argument to the steps.API_2.sim.Simulation.toSave() method but it is possible to manually decide when to save data by calling save() on a result selector during simulation.

Usage:

for r in range(NBRUNS):
    sim.newRun()
    for t in timePoints:
        sim.run(t)
        rs1.save() # Saving values manually

clear()[source]

Discard all recorded data

This method is only available for ResultSelectors that do not save data to files.

__getattr__(name)[source]

Redirect attribute access to a SimPath

See steps.API_2.sim.SimPath.__getattr__().

Note

This method should not be called explicitely, it is only documented for clarity.

__lshift__(other)[source]

Concatenate two result selectors with the << operator

Parameters: other (ResultSelector) – The other result selector
Returns: The result selector resulting from the concatenation of both operands. Its length is thus the sum of both of the operands’ lengths.
Return type: ResultSelector

Usage:

rs2 = rs.comp1.S1.Count << rs.comp1.S2.Count # rs2 will save 2 values, the count of S1
                                             # in comp1 and the count of S2 in comp1.

__mul__(other)[source]

Multiply result selectors with the * operator

Parameters: other (Union[ResultSelector, float]) – The other result selector or a number
Returns: The result selector resulting from the multiplication of both operands. If both operands are result selectors and have the same size, this corresponds to the element-wise product of values. If one of the operand is a number or a result selector of length 1, all values of the result selector are multiplied with this single value.
Return type: ResultSelector

Usage:

rs3 = 10 * rs.TETS(tetlst).S1.Count                       # rs3 will save the number
                                                          # of S1 in each tetrahedron
                                                          # in tetlst, multiplied by
                                                          # 10.

rs4 = rs.TETS(tetlst).S1.Count * rs.TETS(tetlst).S2.Count # rs4 will save the product
                                                          # of the number of S1 and
                                                          # the number of S2 in each
                                                          # tetrahedron in tetLst.

__truediv__(other)[source]

Divide result selectors with the / operator

Parameters: other (Union[ResultSelector, float]) – The other result selector or a number
Returns: The result selector resulting from the division of both operands. If both operands are result selectors and have the same size, this corresponds to the element-wise division of values. If one of the operand is a number or a result selector of length 1, all values of the result selectors are divided by this single value (or this single value is divided by all values from the result selector, depending on order).
Return type: ResultSelector

Usage:

rs3 = rs.TETS(tetlst).S1.Count / 10                       # rs3 will save the number
                                                          # of S1 in each tetrahedron
                                                          # in tetlst, divided by 10.

rs4 = 1 / rs.TETS(tetlst).S1.Count                        # rs4 will save the inverse
                                                          # of the number of S1 in
                                                          # each tetrahedron in
                                                          # tetlst, divided by 10.

rs5 = rs.TETS(tetlst).S1.Count / rs.TETS(tetlst).S2.Count # rs5 will save the ratio of
                                                          # S1 to S2 in each
                                                          # tetrahedron in tetLst.

__add__(other)[source]

Add result selectors with the + operator

Parameters: other (Union[ResultSelector, float]) – The other result selector or a number
Returns: The result selector resulting from the addition of both operands. If both operands are result selectors and have the same size, this corresponds to the element-wise addition of values. If one of the operand is a number or a result selector of length 1, this single value is added to all values of the result selector.
Return type: ResultSelector

Usage:

rs3 = 10 + rs.TETS(tetlst).S1.Count                       # rs3 will save the number
                                                          # of S1 in each tetrahedron
                                                          # in tetlst, increased by
                                                          # 10.

rs4 = rs.TETS(tetlst).S1.Count + rs.TETS(tetlst).S2.Count # rs4 will save the sum
                                                          # of the number of S1 and
                                                          # the number of S2 in each
                                                          # tetrahedron in tetLst.

__sub__(other)[source]

Subtract result selectors with the - operator

Parameters: other (Union[ResultSelector, float]) – The other result selector or a number
Returns: The result selector resulting from the subtraction of both operands. If both operands are result selectors and have the same size, this corresponds to the element-wise subtraction of values. If one of the operand is a number or a result selector of length 1, this single value is subtracted from all values of the result selectors (or each value from the result selector is subtracted from the single value, depending on order).
Return type: ResultSelector

Usage:

rs3 = rs.TETS(tetlst).S1.Count - 10                       # rs3 will save the number
                                                          # of S1 in each tetrahedron
                                                          # in tetlst, minus 10.

rs4 = 10 - rs.TETS(tetlst).S1.Count                       # rs4 will save 10 minus the
                                                          # number of S1 for each
                                                          # tetrahedron in tetlst.

rs5 = rs.TETS(tetlst).S1.Count - rs.TETS(tetlst).S2.Count # rs5 will save the number
                                                          # of S1 minus the number of
                                                          # S2 in each tetrahedron in
                                                          # tetLst.

__pow__(other)[source]

Exponentiate result selectors with the ** operator

Parameters: other (Union[ResultSelector, float]) – The other result selector or a number
Returns: The result selector resulting from the exponentiation of both operands. If both operands are result selectors and have the same size, this corresponds to the element-wise exponentiation of values. If one of the operand is a number or a result selector of length 1, this single value is exponentiated by each value of the result selector (or each value in the result selector is exponentiated by the single value, depending on order).
Return type: ResultSelector

Usage:

rs3 = rs.TETS(tetlst).S1.Count ** 2                       # rs3 will save the square
                                                          # of the number of S1 in
                                                          # each tetrahedron in
                                                          # tetlst.

classmethod SUM(sel)[source]

Sum of all values from a result selector

Parameters: sel (ResultSelector) – Result selector whose values should be summed
Returns: A result selector with a single value that corresponds to the sum of the values in sel.
Return type: ResultSelector

Usage:

rs3 = rs.SUM(rs.TETS(tetLst).S1.Count) # The total number of S1 in tetLst

classmethod MIN(sel)[source]

Minimum of all values from a result selector

Parameters: sel (ResultSelector) – Result selector whose values should be used
Returns: A result selector with a single value that corresponds to the minimum of the values in sel.
Return type: ResultSelector

Usage:

rs3 = rs.MIN(rs.TETS(tetLst).S1.Count) # The minimum number of S1 in tetLst

classmethod MAX(sel)[source]

Maximum of all values from a result selector

Parameters: sel (ResultSelector) – Result selector whose values should be used
Returns: A result selector with a single value that corresponds to the maximum of the values in sel.
Return type: ResultSelector

Usage:

rs3 = rs.MAX(rs.TETS(tetLst).S1.Count) # The maximum number of S1 in tetLst

classmethod JOIN(selectors)[source]

Concatenate values from several result selectors

Parameters: selectors (Iterable[ResultSelector]) – Result selectors whose values should be concatenated
Returns: A result selector that corresponds to the concatenatin of the values in selectors.
Return type: ResultSelector

Usage:

# The total number of species for each tetrahedron in tetLst
rs3 = rs.JOIN(rs.SUM(rs.TET(tet).ALL(Species).Count) for tet in tetLst)

class CustomResults(sim, types, *args, **kwargs)[source]

Bases: ResultSelector

Class to manually save data

This class helps to save data to file or databases in the same format as ResultSelector. This is useful for cases in which the data to be saved is not easily describable with a standard ResultSelector. Instead of describing the data to be saved, CustomResults requires a list of the types of the data to be saved. The user then calls the save method with a list of values to be saved whenever it is needed.

Parameters

sim (steps.API_2.sim.Simulation) – The simulation for which we want to save data
types (List[Union[dict, list, str, float, int]]) – A list of types that describes the types of each data that will be saved upon calls save.

save(values)[source]

Save the provided values at the current simulation time

Unlike other ResultsSelector`s, :py:class:`CustomResults will only save values that are explicitely given to it through this method, along with the simulation time at the time of the call.

Parameters: values (List[Union[Dict, List, str, Number]]) – A list of values that has the same length as the list of types used to create the CustomResults object.

Usage:

cr1 = CustomResults([dict, list, float])

sim.toSave(cr1) # No dt or timepoints parameters

sim.newRun()
for t in timePoints:
    sim.run(t)
    myvalues = [{'key1': 92, 'key2': 6}, ['str1', 'str2'], 42.0] # Compute values
    rs1.save(myvalues) # Saving values manually

class DatabaseHandler(*args, **kwargs)[source]

Bases:

Base class for all database handlers.

property parameters

All parameter values from all run groups

A dictionary whose keys are parameter names and values are sets of possible values

Return type: Mapping[str, Set[Any]], read-only

filter(**kwargs)[source]

Return all run groups that match the given parameter values

Parameters: **kwargs – Keyword arguments specifying the values of parameters that the filtered run groups must match.
Returns: A set of run groups whose parameter values match the parameters supplied by keyword arguments
Return type: Set[DatabaseGroup]

get(**kwargs)[source]

Get the run group that matches the given parameter values

Parameters: **kwargs – Keyword arguments specifying the values of parameters that the run group must match.
Returns: The single run group that matches the given parameter values
Return type: DatabaseGroup

If several or none of the groups match these values, an exception will be raised.

class DatabaseGroup(dbh, *args, **kwargs)[source]

Bases:

Base class for all database run groups

property name

The unique identifier of the group

Type: str, read-only

class SQLiteDBHandler(path, *args, commitFreq=- 1, **kwargs)[source]

Bases: DatabaseHandler

SQLite database handler

Parameters

path (str) – The path to the SQLite database file
*args – Transmitted to sqlite3.connect(), see documentation for details
commitFreq (int) – How frequently the data should be committed to the database. For example, this value is set to 10 by default which means that every 10 saving events, the data will be committed. If a result selector is saved every 10ms, it means the data will be committed to database every 100ms.
**kwargs – Transmitted to sqlite3.connect(), see documentation for details

Handles the connection to a SQLite database and enables the saving of result selectors to that database. In contrast to the regular saving of result selectors (to memory or to file), it is possible to define groups of runs identified by a unique string so that the same database file can be used for several (sequential) runs of scripts.

The database handler should be used as a context manager that wraps all simulation code. Inside this wrapped block, the user should call the steps.API_2.sim.Simulation.toDB() method to indicate that all results selectors associated to the simulation should be saved in the database. In this call, the user should provide the unique simulation group identifier as well as optional parameters that will also be saved to the database.

Usage when saving:

sim.toSave(rs1, rs2, rs3, dt=0.01)                # Add the result selectors to the
                                                  # simulation.

with SQLiteDBHandler(dbPath) as dbh:              # Create database handler.

    sim.toDB(dbh, 'MySimulation', val1=1, val2=2) # Create a new group of runs in the
                                                  # database with identifier
                                                  # 'MySimulation' and save additional
                                                  # parameters val1 and val2.

    for i in range(NBRUNS):                       # Run a series of runs, all of them
        sim.newRun()                              # being associated to the
        ...                                       # 'MySimulation' group.
        sim.run(...)

Note that after calling sim.toDB(…) it is still possible to force the saving of some result selectors to files by calling toFile(...) on them. Result selectors that contain a high number of values to save are probably better saved to a file. The name of the file can be added as a keyword parameter to the simtoDB(...) call to simplify loading.

Usage when accessing data from the database:

with SQLiteDBHandler(dbPath) as dbh:              # Create database handler.

    val1 = dbh['MySimulation'].val1               # Querying a parameter value from the
                                                  # 'MySimulation' group.

    rs1, rs2, rs3 = dbh['MySimulation'].results   # Querying the result selectors that
                                                  # were saved for the 'MySimulation'
                                                  # group. They are returned in the same
                                                  # order ad they were added to the
                                                  # simulation.

    plt.plot(rs1.time[0], rs1.data[0])            # The results selectors can be used as
                                                  # if they had been declared in the same
                                                  # process.

__getitem__(key)[source]

Access a SQLite group from its unique identifier

Parameters: key (str) – Unique identifier to the group
Returns: The associated SQLite group
Return type: SQLiteGroup

See SQLiteDBHandler for usage examples.

Raises a KeyError if the key is not in the database. :meta public:

__iter__()[source]

Iterate over SQLite groups in the database

Usage:

with SQLiteDBHandler(dbPath) as dbh:              # Create database handler.

    for group in dbh:                             # Iterate over all groups

        val1 = group.val1                         # Access group data

class SQLiteGroup(dbh, row, *args, **kwargs)[source]

Bases: DatabaseGroup

A class representing a group of runs in a SQLite database

Note

This class should never be instantiated by the user, it is obtained through SQLiteDBHandler instead.

__getattr__(name)[source]

Attribute access for parameters of the group

Parameters: name (str) – Name of the parameter, as defined in the original call to sim.toDB(...)
Returns: The corresponding parameter value

See SQLiteDBHandler for usage examples.

property name

The unique identifier of the group

Type: str, read-only

property results

A list of all result selectors that were saved

Type: List[ResultSelector], read-only

The result selectors are returned in the same order as they were added to the simulation with the steps.API_2.sim.Simulation.toSave() method.

See SQLiteDBHandler for usage examples.

property parameters

A dictionary of all parameters defined for this group

Type: Mapping[str, Any], read-only

Usage:

>>> with SQLiteDBHandler(dbPath) as dbh:
...     dbh['MySimulation'].parameters
{'val1': 1, 'val2': 2}

property staticData

Not supported for SQLite databases.

See HDF5Handler.staticData

class HDF5Handler(pathPrefix, hdf5FileKwArgs={}, hdf5DatasetKwArgs={}, internalKwArgs={}, **kwargs)[source]

Bases: DatabaseHandler

HDF5 File handler

Parameters

pathPrefix (str) – Path and prefix for the HDF5 file(s) (e.g. ‘./data/HDF5Data’ would yield one file named ‘./data/HDF5Data.h5’ when the simulation is not distributed and several files named ‘./data/HDF5Data_rank0.h5’, ‘./data/HDF5Data_rank1.h5’, etc. when the simulation is distributed.
hdf5FileKwArgs (dict) – Keyword arguments transmitted to h5py.File(), see documentation for details
hdf5DatasetKwArgs – Keyword arguments transmitted to h5py.Group.create_dataset(), see documentation for details. Most notably, compression-related argument can be set there.
internalKwArgs (dict) – Keyword arguments specific to the handling of HDF5 files by STEPS, currently only supports maxFullLoadSize which improves reading speed of lists or dictionaries saved in result selectors by fully loading some datasets in memory if their size is below maxFullLoadSize.

Handles reading and writing to an HDF5 file and enables the saving of result selectors to that file. In contrast to the regular saving of result selectors (to memory or to file), it is possible to define groups of runs identified by a unique string so that the same HDF5 file can be used for several (sequential) runs of scripts.

The HDF5Handler should be used as a context manager that wraps all simulation code. Inside this wrapped block, the user should call the steps.API_2.sim.Simulation.toDB() method to indicate that all results selectors associated to the simulation should be saved in the HDF5 file. In this call, the user should provide the unique simulation group identifier as well as optional parameters that will also be saved to the file.

Usage when saving:

sim.toSave(rs1, rs2, rs3, dt=0.01)                # Add the result selectors to the
                                                  # simulation.

with HDF5Handler('./path/to/Prefix') as hdf:      # Create database handler.

    sim.toDB(hdf, 'MySimulation', val1=1, val2=2) # Create a new group of runs in the
                                                  # HDF5 file with identifier
                                                  # 'MySimulation' and save additional
                                                  # parameters val1 and val2.

    for i in range(NBRUNS):                       # Run a series of runs, all of them
        sim.newRun()                              # being associated to the
        ...                                       # 'MySimulation' group.
        sim.run(...)

Note that, in contrast with SQLiteDBHandler, there is no use for forcing the saving of some result selectors to files by calling toFile(...) on them. HDF5 files can contain high amounts of data.

Usage when accessing data from the database:

with HDF5Handler('./path/to/Prefix') as hdf:      # Create database handler.

    val1 = hdf['MySimulation'].val1               # Querying a parameter value from the
                                                  # 'MySimulation' group.

    rs1, rs2, rs3 = hdf['MySimulation'].results   # Querying the result selectors that
                                                  # were saved for the 'MySimulation'
                                                  # group. They are returned in the same
                                                  # order as they were added to the
                                                  # simulation.

    plt.plot(rs1.time[0], rs1.data[0])            # The results selectors can be used as
                                                  # if they had been declared in the same
                                                  # process.

Note that XDMFHandler inherits from HDF5Handler and generates .xmf files that point to the HDF5 files and can be read by data visualization software such as Paraview.

__getitem__(key)[source]

Access an HDF5 group from its unique identifier

Parameters: key (str) – Unique identifier to the group
Returns: The associated HDF5 group
Return type: HDF5Group

See HDF5Handler for usage examples.

Raises a KeyError if the key is not in the file.

__iter__()[source]

Iterate over STEPS groups in the file

Usage:

with HDF5Handler(filePath) as hdf:    # Create database handler.

    for group in hdf:                 # Iterate over all groups

        val1 = group.val1             # Access group data

Note that not all HDF5 groups in the file will be iterated on, only the ones that were added by STEPS. Other groups will be ignored by STEPS.

class HDF5MultiFileReader(path, recursive=False, **kwargs)[source]

Bases: DatabaseHandler

An HDF5 reader that aggregates data from several files.

This class can be used to access data from several HDF5 files as if the data was in a single file. It works like HDF5Handler but is read-only.

Parameters

path (Union[List[str], str]) – Can either be a path to a directory or a list of path prefixes for HDF5 files (see HDF5Handler). If a list of path prefixes is given, all of these files will be opened. If a path to a directory is given, all HDF5 files in the directory will be opened.
recursive (bool) – Also search in subdirectories (if path is a path to a directory).

__getitem__(key)[source]

Access an HDF5 group from its unique identifier

Parameters: key (str) – Unique identifier to the group
Returns: The associated HDF5 group, if run groups from different files have the same unique identifier, a list containing the corresponding run groups will be returned
Return type: Union[List[HDF5Group], HDF5Group]

__iter__()[source]

Iterate over run groups in all HDF5 files See HDF5Handler

class HDF5Group(dbh, group, *args, **kwargs)[source]

Bases: DatabaseGroup

A class representing a group of runs in an HDF5 file

Note

This class should never be instantiated by the user, it is obtained through HDF5Handler instead.

__getattr__(name)[source]

Attribute access for parameters of the group

Parameters: name (str) – Name of the parameter, as defined in the original call to sim.toDB(...)
Returns: The corresponding parameter value

See SQLiteDBHandler for usage examples.

property name

The unique identifier of the group

Type: str, read-only

property results

A list of all result selectors that were saved

Type: List[ResultSelector], read-only

The result selectors are returned in the same order as they were added to the simulation with the steps.API_2.sim.Simulation.toSave() method.

See HDF5Handler for usage examples.

property parameters

A dictionary of all parameters defined for this group

Type: Mapping[str, Any], read-only

Usage:

>>> with HDF5Handler(filePath) as hdf:
...     hdf['MySimulation'].parameters
{'val1': 1, 'val2': 2}

property staticData

A mutable mapping which contains static data specific to this run group

Type: Mapping[str, Union[List, Dict, float, int, str]]

Usage when writing data:

>>> with HDF5Handler(filePath) as hdf:
>>>     group = sim.toDB(hdf, 'RunGroup1')
>>>     group.staticData['StimPoints'] = [1, 5, 8]

The static data that is saved must be specific to the whole run group. If the key associated to the data already exists in the static data, STEPS will check that the value given is the same as the one that was already saved. If not, an exception will be raised.

Usage when reading data:

>>> with HDF5Handler(filePath) as hdf:
>>>     group = hdf['RunGroup1']
>>>     group.staticData['StimPoints']
[1, 5, 8]

Note that when using MPI, only rank 0 can access this property.

class XDMFHandler(pathPrefix, hdf5FileKwArgs={}, hdf5DatasetKwArgs={}, xdmfFolder=None, **kwargs)[source]

Bases: HDF5Handler

XDMF / HDF5 File handler

Parameters

pathPrefix (str) – Path and prefix for the HDF5 file(s), see HDF5Handler.
hdf5FileKwArgs (dict) – see HDF5Handler.
hdf5DatasetKwArgs – see HDF5Handler.
xdmfFolder (Union[str, None]) – Path to the folder to which XDMF files should be written. If None, it uses the folder in which HDF5 files will be saved.

The XDMF file format uses XML files with the .xmf extension to describe data saved in an HDF5 file. Scientific visualization tools like Paraview can read .xmf files and access the corresponding data in HDF5 files to display the mesh and the data associated with it.

The XDMFHandler database handler inherits from HDF5Handler and thus behaves like an HDF5 database handler. The main difference is that XDMFHandler also saves mesh information to the HDF5 file and generates .xmf XDMF files that describe all the data that can be visualized on meshes. Since it works in the same way as HDF5Handler, usage examples can be seen there.

Regardless on whether the data saved by a ResulSelector is specific to mesh elements, it will be saved in the same way as if HDF5Handler was used. Data that is specific to mesh elements (e.g. count of species in a tetrahedron, concentration of species in a region of interest, etc.) will be described in the .xmf file.

The following mesh locations (see steps.API_2.sim.SimPath) are supported:

Location	Result selector	XDMF data type
Tetrahedrons	`rs.TETS(tetLst)...`	Cell data
Triangles	`rs.TRIS(triLst)...`	Cell data
Vertices	`rs.VERTS(vertLst)...`	Node data
Regions of Interest	`rs.ROIname...`	Grid data
Compartments	`rs.compName...`	Grid data
Patches	`rs.patchName...`	Grid data

Technical note: the result selectors that involve mesh data (data that will be described in the .xmf file) might be stored in the HDF5 file in a way that is different from how it is normally stored with HDF5Handler. Notably, the order of ResultSelector columns might be changed to allow contiguous data access when loading the data into scientific visualization softwares. These differences do not affect users as long as the data is read using HDF5Handler.__getitem__(), columns will be correctly reordered to match the original ResultSelector order.