Implement C++ SolutionArray::save for CSV output

include/cantera/base/SolutionArray.h

@@ -22,8 +22,6 @@ class ThermoPhase;
  *  stored, reshaping operations need to be implemented in high-level API's.
  *
  *  @since  New in Cantera 3.0.
- *  @warning This class is an experimental part of the %Cantera API and may be
- *      changed or removed without notice.
  */
 class SolutionArray
 {
@@ -189,105 +187,147 @@ class SolutionArray
     void append(const vector<double>& state, const AnyMap& extra);
 
     /*!
-     *  Write header data to container file.
+     *  Write header data to a HDF container file.
      *
      *  @param fname  Name of HDF container file
-     *  @param id  Identifier of root location within the container file
-     *  @param desc  Description
-     *  @param overwrite  Force overwrite if id exists; optional (default=false)
+     *  @param name  Identifier of group holding header information
+     *  @param desc  Custom comment describing dataset
+     *  @param overwrite  Force overwrite if file/group exists; optional (default=false)
      */
-    static void writeHeader(const string& fname, const string& id, const string& desc,
+    static void writeHeader(const string& fname, const string& name, const string& desc,
                             bool overwrite=false);
 
     /*!
-     *  Write header data to AnyMap.
+     *  Write header data to AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
-     *  @param id  Identifier of root location within the container file
-     *  @param desc  Description
-     *  @param overwrite  Force overwrite if id exists; optional (default=false)
+     *  @param name  Identifier of node holding header information
+     *  @param desc  Custom comment describing dataset
+     *  @param overwrite  Force overwrite if node exists; optional (default=false)
      */
-    static void writeHeader(AnyMap& root, const string& id, const string& desc,
+    static void writeHeader(AnyMap& root, const string& name, const string& desc,
                             bool overwrite=false);
 
     /*!
-     *  Write SolutionArray data to container file.
+     *  Write SolutionArray data to a CSV file.
+     *
+     *  @param fname  Name of CSV file
+     *  @param overwrite  Force overwrite if file exists; optional (default=false)
+     *  @param basis  Output mass ("Y"/"mass") or mole ("X"/"mole") fractions;
+     *      if omitted (default=""), the native basis of the underlying ThermoPhase
+     *      manager is used - @see nativeState
+     */
+    void writeEntry(const string& fname, bool overwrite=false, const string& basis="");
+
+    /*!
+     *  Write SolutionArray data to a HDF container file.
      *
      *  @param fname  Name of HDF container file
-     *  @param id  Identifier of root location within the container file
-     *  @param sub  Name identifier for the subgroup holding actual data
-     *  @param overwrite  Force overwrite if sub exists; optional (default=false)
+     *  @param name  Identifier of group holding header information
+     *  @param sub  Name identifier of subgroup holding SolutionArray data
+     *  @param overwrite  Force overwrite if subgroup exists; optional (default=false)
      *  @param compression  Compression level; optional (default=0; HDF only)
      */
-    void writeEntry(const string& fname, const string& id, const string& sub,
+    void writeEntry(const string& fname, const string& name, const string& sub,
                     bool overwrite=false, int compression=0);
 
     /*!
-     *  Write SolutionArray data to AnyMap.
+     *  Write SolutionArray data to AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
-     *  @param id  Identifier of root location within the container file
-     *  @param sub  Name identifier for the subgroup holding actual data
-     *  @param overwrite  Force overwrite if sub exists; optional (default=false)
+     *  @param name  Identifier of node holding header information and subgroup
+     *  @param sub  Name identifier of subgroup holding SolutionArray data
+     *  @param overwrite  Force overwrite if subgroup exists; optional (default=false)
      */
-    void writeEntry(AnyMap& root, const string& id, const string& sub,
+    void writeEntry(AnyMap& root, const string& name, const string& sub,
                     bool overwrite=false);
 
     /*!
-     *  Save current SolutionArray and header to a container file.
+     *  Save current SolutionArray contents to a data file.
      *
-     *  @param fname  Name of output container file (YAML or HDF)
-     *  @param id  Identifier of root location within the container file
-     *  @param sub  Name identifier for the subgroup holding actual data
-     *  @param desc  Custom comment describing the dataset to be stored
-     *  @param overwrite  Force overwrite if sub exists; optional (default=false)
-     *  @param compression  Compression level; optional (default=0; HDF only)
+     *  Data can be saved either in CSV format (extension '*.csv'), YAML container
+     *  format (extension '*.yaml'/'*.yml') or HDF container format (extension
+     *  '*.h5'/'*.hdf5'/'*.hdf'). The output format is automatically inferred from the
+     *  file extension.
+     *
+     *  CSV files preserve state data and auxiliary data for a single SolutionArray in a
+     *  comma-separated text format, container files may hold multiple SolutionArray
+     *  entries in an internal hierarchical structure. While YAML is a human-readable
+     *  text format, HDF is a binary format that supports compression and is recommended
+     *  for large datasets.
+     *
+     *  For container files (YAML and HDF), header information contains automatically
+     *  generated time stamps, version information and an optional description.
+     *  Container files also preserve SolutionArray metadata (example: SolutionArray
+     *  objects generated by Sim1D hold simulation settings).
+     *
+     *  @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)
+     *  @param sub  Name identifier for the subgroup holding the SolutionArray data and
+     *      metadata objects. If omitted (""), the subgroup name defaults to "data"
+     *      (YAML/HDF only)
+     *  @param desc  Custom comment describing dataset to be stored (YAML/HDF only)
+     *  @param overwrite  Force overwrite if file and/or data entry exists; optional
+     *      (default=false)
+     *  @param compression  Compression level (0-9); (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 string& fname, const string& id, const string& sub,
-              const string& desc, bool overwrite=false, int compression=0);
+    void save(const string& fname, const string& name="", const string& sub="",
+              const string& desc="", bool overwrite=false, int compression=0,
+              const string& basis="");
 
     /*!
-     *  Read header data from container file.
+     *  Read header information from a HDF container file.
      *
      *  @param fname  Name of HDF container file
-     *  @param id  Identifier of root location within the container file
+     *  @param name  Identifier of group holding header information
      */
-    static AnyMap readHeader(const string& fname, const string& id);
+    static AnyMap readHeader(const string& fname, const string& name);
 
     /*!
-     *  Read header data from AnyMap.
+     *  Read header information from AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
-     *  @param id  Identifier of root location within the container file
+     *  @param name  Identifier of node holding header information
      */
-    static AnyMap readHeader(const AnyMap& root, const string& id);
+    static AnyMap readHeader(const AnyMap& root, const string& name);
 
     /*!
-     *  Restore SolutionArray entry from a container file.
+     *  Restore SolutionArray data from a HDF container file.
      *
      *  @param fname  Name of HDF container file
-     *  @param id  Identifier of root location within the container file
-     *  @param sub  Name of the subgroup holding actual data
+     *  @param name  Identifier of group holding header information
+     *  @param sub  Name identifier of subgroup holding SolutionArray data
      */
-    void readEntry(const string& fname, const string& id, const string& sub);
+    void readEntry(const string& fname, const string& name, const string& sub);
 
     /*!
-     *  Restore SolutionArray entry from AnyMap.
+     *  Restore SolutionArray data from AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
-     *  @param id  Identifier of root location within the container file
-     *  @param sub  Name of the subgroup holding actual data
+     *  @param name  Identifier of node holding header information
+     *  @param sub  Name identifier of subgroup holding SolutionArray data
      */
-    void readEntry(const AnyMap& root, const string& id, const string& sub);
+    void readEntry(const AnyMap& root, const string& name, const string& sub);
 
     /*!
-     *  Restore SolutionArray entry and header from a container file.
+     *  Restore SolutionArray data and header information from a container file.
+     *
+     *  This method retrieves data from a YAML or HDF files that were previously saved
+     *  using the @see save method.
      *
      *  @param fname  Name of container file (YAML or HDF)
-     *  @param id  Identifier of SolutionArray within the container file
-     *  @param sub  Name of the subgroup holding actual data
+     *  @param name  Identifier of location within the container file; this node/group
+     *      contains header information and a subgroup holding actual SolutionArray data
+     *  @param sub  Name identifier for the subgroup holding the SolutionArray data and
+     *      metadata objects. If omitted (""), the subgroup name defaults to "data"
+     *  @return  AnyMap containing header information
      */
-    AnyMap restore(const string& fname, const string& id, const string& sub);
+    AnyMap restore(const string& fname, const string& name, const string& sub="");
 
 protected:
     //! Service function used to resize SolutionArray

include/cantera/oneD/Sim1D.h

@@ -142,15 +142,35 @@ class Sim1D : public OneDim
               const std::string& desc, int loglevel);
 
     /**
-     * Save the current solution to a container file.
-     * @param fname  Name of output container file
-     * @param id  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)
+     * Save current simulation data to a container file or CSV format.
+     *
+     * 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.
+     *
+     * 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& id,
-              const std::string& desc, bool overwrite=false, int compression=0);
+    void save(const std::string& fname, const std::string& name,
+              const std::string& desc, bool overwrite=false, int compression=0,
+              const string& basis="");
 
     /**
      * Save the residual of the current solution to a container file.
@@ -166,12 +186,12 @@ class Sim1D : public OneDim
     /**
      * Save the residual of the current solution to a container file.
      * @param fname  Name of output container file
-     * @param id  Identifier of solution within the 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)
      */
-    void saveResidual(const std::string& fname, const std::string& id,
+    void saveResidual(const std::string& fname, const std::string& name,
                       const std::string& desc, bool overwrite=false, int compression=0);
 
     /**
@@ -185,12 +205,18 @@ class Sim1D : public OneDim
     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 id  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& id);
+    AnyMap restore(const std::string& fname, const std::string& name);
 
     //! @}
 

interfaces/cython/cantera/_onedim.pxd

@@ -114,7 +114,7 @@ cdef extern from "cantera/oneD/Sim1D.h":
         void refine(int) except +translate_exception
         void setRefineCriteria(size_t, double, double, double, double) except +translate_exception
         vector[double] getRefineCriteria(int) except +translate_exception
-        void save(string&, string&, string&, cbool, int) except +translate_exception
+        void save(string&, string&, string&, cbool, int, string&) except +translate_exception
         CxxAnyMap restore(string&, string&) except +translate_exception
         void writeStats(int) except +translate_exception
         void clearStats()

interfaces/cython/cantera/_onedim.pyx

@@ -1537,20 +1537,39 @@ cdef class Sim1D:
             return self.sim.fixedTemperatureLocation()
 
     def save(self, filename='soln.yaml', name='solution', description=None,
-             loglevel=None, overwrite=False, compression=0):
+             loglevel=None, *, overwrite=False, compression=0, basis=None):
         """
-        Save the solution in YAML or HDF format.
+        Save current simulation data to a data file (CSV, YAML or HDF).
+
+        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
+            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
+            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 (``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')
@@ -1562,20 +1581,24 @@ cdef class Sim1D:
             warnings.warn("Argument 'loglevel' is deprecated and will be ignored.",
                 DeprecationWarning)
         self.sim.save(stringify(str(filename)), stringify(name),
-                      stringify(description), overwrite, compression)
+                      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')