From 3e9a9080215255f14ced1199b3710b368967ef24 Mon Sep 17 00:00:00 2001 From: Ingmar Schoegl Date: Wed, 21 Jun 2023 12:14:50 -0600 Subject: [PATCH] Additional documentation updates for Sim1D file IO --- include/cantera/oneD/Sim1D.h | 45 ++++++++++++++++++-------- interfaces/cython/cantera/_onedim.pyx | 41 +++++++++++++++-------- interfaces/cython/cantera/composite.py | 8 ++--- 3 files changed, 63 insertions(+), 31 deletions(-) diff --git a/include/cantera/oneD/Sim1D.h b/include/cantera/oneD/Sim1D.h index 12d8eefd6..842128761 100644 --- a/include/cantera/oneD/Sim1D.h +++ b/include/cantera/oneD/Sim1D.h @@ -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); diff --git a/interfaces/cython/cantera/_onedim.pyx b/interfaces/cython/cantera/_onedim.pyx index 5520ebd01..beaf04d6d 100644 --- a/interfaces/cython/cantera/_onedim.pyx +++ b/interfaces/cython/cantera/_onedim.pyx @@ -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') diff --git a/interfaces/cython/cantera/composite.py b/interfaces/cython/cantera/composite.py index cac3b2da2..bcc77c646 100644 --- a/interfaces/cython/cantera/composite.py +++ b/interfaces/cython/cantera/composite.py @@ -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: