GreenPolyProducts/cantera
5
0
Fork 0
mirror of https://github.com/Cantera/cantera.git synced 2025-02-25 18:55:29 -06:00
Code Issues Packages Projects Releases Wiki Activity

Additional documentation updates for Sim1D file IO

Browse Source
This commit is contained in:
Ingmar Schoegl 2023-06-21 12:14:50 -06:00
parent 0d58bac3b5
commit 3e9a908021
3 changed files with 63 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
include/cantera/oneD/Sim1D.h
View File

@ -142,18 +142,31 @@ public:
const std::string& desc, int loglevel);
/**
* Save the current solution to a container or CSV file.
* Save current simulation data to a container file or CSV format.
*
* For HDF and YAML, the entire content of the object is saved; for CSV, only the
* main 1D domain is saved.
* In order to save the content of a Sim1D object, individual domains are
* converted to SolutionArray objects and saved using the SolutionArray::save()
* method. For HDF and YAML output, all domains are written to a single container
* file with shared header information. Simulation settings of individual domains
* are preserved as meta data of the corresponding SolutionArray objects.
* For CSV files, only state and auxiliary data of the main 1D domain are saved.
*
* @param fname Name of output container file
* @param name Identifier of solution within the container file
* @param desc Description of the solution
* @param overwrite Force overwrite if name exists; optional (default=false)
* @param compression Compression level (optional; HDF only)
* @param basis Output mass ("Y"/"mass") or mole ("X"/"mole") fractions (CSV only);
* if omitted (default=""), the native storage mode is used
* The complete state of the current object can be restored from HDF and YAML
* container files using the restore() method, while individual domains can be
* loaded using SolutionArray::restore() for further analysis. While CSV do not
* contain complete information, they can still be used for setting initial states
* of individual simulation objects for some Cantera API's.
*
* @param fname Name of output file (CSV, YAML or HDF)
* @param name Identifier of storage location within the container file; this
* node/group contains header information and multiple subgroups holding
* domain-specific SolutionArray data (YAML/HDF only)
* @param desc Custom comment describing the dataset to be stored (YAML/HDF only)
* @param overwrite Force overwrite if file/name exists; optional (default=false)
* @param compression Compression level (0-9); optional (default=0; HDF only)
* @param basis Output mass ("Y"/"mass") or mole ("X"/"mole") fractions;
* if not specified (default=""), the native basis of the underlying
* ThermoPhase manager is used - @see nativeState (CSV only)
*/
void save(const std::string& fname, const std::string& name,
const std::string& desc, bool overwrite=false, int compression=0,
@ -192,9 +205,15 @@ public:
AnyMap restore(const std::string& fname, const std::string& id, int loglevel);
/**
* Initialize the solution with a previously-saved solution.
* @param fname Name of container file
* @param name Identifier of solution within the container file
* Retrieve data and settings from a previously saved simulation.
*
* This method restores a simulation object from YAML or HDF data previously saved
* using the save() method.
*
* @param fname Name of container file (YAML or HDF)
* @param name Identifier of location within the container file; this node/group
* contains header information and subgroups with domain-specific SolutionArray
* data
* @return AnyMap containing header information
*/
AnyMap restore(const std::string& fname, const std::string& name);

41
interfaces/cython/cantera/_onedim.pyx
View File

@ -1539,28 +1539,37 @@ cdef class Sim1D:
def save(self, filename='soln.yaml', name='solution', description=None,
loglevel=None, *, overwrite=False, compression=0, basis=None):
"""
Save the solution to a container or CSV format.
Save current simulation data to a data file (CSV, YAML or HDF).
In order to save the content of a `Sim1D` object, individual domains are
converted to `SolutionArray` objects and saved using the `SolutionArray.save`
In order to save the content of the current object, individual domains are
converted to `SolutionArray` objects and saved using the `~SolutionArray.save`
method. For HDF and YAML output, all domains are written to a single container
file with shared header information. Simulation settings of individual domains
are preserved as meta data of the corresponding `SolutionArray` objects.
For CSV files, only state and auxiliary data of the main 1D domain are saved.
The complete state of the current object can be restored from HDF and YAML
container files using the `restore` method, while individual domains can be
loaded using `SolutionArray.restore` for further analysis. While CSV files do
not contain complete information, they can be used for setting initial states
of individual simulation objects (example: `~FreeFlame.set_initial_guess`).
:param filename:
solution file
Name of output file (CSV, YAML or HDF)
:param name:
solution name within the file (HDF/YAML only)
Identifier of storage location within the container file; this node/group
contains header information and multiple subgroups holding domain-specific
`SolutionArray` data (YAML/HDF only).
:param description:
custom description text (HDF/YAML only)
Custom comment describing the dataset to be stored (YAML/HDF only).
:param overwrite:
Force overwrite if name exists; optional (default=`False`)
Force overwrite if file and/or data entry exists; optional (default=`False`)
:param compression:
compression level 0..9; optional (HDF only)
Compression level (0-9); optional (default=0; HDF only)
:param basis:
Output mass (``Y``/``mass``) or mole (``X``/``mole``) fractions (CSV only);
if not specified (`None`), the native storage mode is used
Output mass (``Y``/``mass``) or mole (``Y``/``mass``) fractions;
if not specified (`None`), the native basis of the underlying `ThermoPhase`
manager is used.
>>> s.save(filename='save.yaml', name='energy_off',
... description='solution with energy eqn. disabled')
@ -1575,17 +1584,21 @@ cdef class Sim1D:
stringify(description), overwrite, compression, stringify(basis))
def restore(self, filename='soln.yaml', name='solution', loglevel=None):
"""Set the solution vector to a previously-saved solution.
"""Retrieve data and settings from a previously saved simulation.
This method restores a simulation object from YAML or HDF data previously saved
using the `save` method.
:param filename:
solution file
Name of container file (YAML or HDF)
:param name:
solution name within the file
Identifier of location within the container file; this node/group contains
header information and subgroups with domain-specific `SolutionArray` data
:param loglevel:
Amount of logging information to display while restoring,
from 0 (disabled) to 2 (most verbose).
:return:
dictionary containing meta data
Dictionary containing header information
>>> s.restore(filename='save.yaml', name='energy_off')

8
interfaces/cython/cantera/composite.py
View File

@ -1275,9 +1275,9 @@ class SolutionArray(SolutionArrayBase):
:param fname:
Name of output file (CSV, YAML or HDF)
:param name:
Identifier of location within the container file; this node/group contains
header information and a subgroup holding actual `SolutionArray` data
(YAML/HDF only).
Identifier of storage location within the container file; this node/group
contains header information and a subgroup holding actual `SolutionArray`
data (YAML/HDF only).
:param sub:
Name identifier for the subgroup holding the `SolutionArray` data and
metadata objects. If `None`, the subgroup name defaults to ``data``
@ -1285,7 +1285,7 @@ class SolutionArray(SolutionArrayBase):
:param description:
Custom comment describing the dataset to be stored (YAML/HDF only).
:param overwrite:
Force overwrite if name exists; optional (default=`False`)
Force overwrite if file/name exists; optional (default=`False`)
:param compression:
Compression level (0-9); optional (default=0; HDF only)
:param basis: