Skip to content

Commit

Permalink
[docs] Improve SolutionArray documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ischoegl
ischoegl committed Aug 3, 2023
1 parent d249b2b commit 82aec96
Showing 1 changed file with 32 additions and 29 deletions.
61 changes: 32 additions & 29 deletions include/cantera/base/SolutionArray.h
View file
Expand Up @@ -70,7 +70,7 @@ class SolutionArray
//! Reset all entries of the SolutionArray to the current Solution state
void reset();

//! Size of SolutionArray (number of entries)
//! Size of SolutionArray (number of entries).
int size() const {
return static_cast<int>(m_size);
}
Expand Down Expand Up @@ -122,8 +122,10 @@ class SolutionArray
//! Retrieve list of component names
vector<string> componentNames() const;

//! Check whether SolutionArray contains a component (property defining state or
//! auxiliary variable)
/**
* Check whether SolutionArray contains a component.
* A component is a property defining state or auxiliary variable.
*/
bool hasComponent(const string& name) const;

/**
Expand Down Expand Up @@ -166,10 +168,10 @@ class SolutionArray

/**
* Add auxiliary component to SolutionArray. Initialization requires a subsequent
* call of setComponent.
* call of setComponent().
*
* @param name Name of component (property defining auxiliary variable)
* @param back If true (default), add name after components representing the
* @param back If `true` (default), add name after components representing the
* state, otherwise add to front of list. Front and back components are
* populated left to right.
*/
Expand Down Expand Up @@ -198,18 +200,19 @@ class SolutionArray
* @param fname Name of HDF container file
* @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)
* @param overwrite Force overwrite if file/group exists;
* optional (default=`false`)
*/
static void writeHeader(const string& fname, const string& name, const string& desc,
bool overwrite=false);

/**
* Write header data to AnyMap; used by YAML serialization.
* Write header data to AnyMap. Used by YAML serialization.
*
* @param root Root node of AnyMap structure
* @param name Identifier of node holding header information
* @param desc Custom comment describing dataset
* @param overwrite Force overwrite if node exists; optional (default=false)
* @param overwrite Force overwrite if node exists; optional (default=`false`)
*/
static void writeHeader(AnyMap& root, const string& name, const string& desc,
bool overwrite=false);
Expand All @@ -218,10 +221,10 @@ class SolutionArray
* 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
* @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 Phase::nativeState
*/
void writeEntry(const string& fname, bool overwrite=false, const string& basis="");

Expand All @@ -231,7 +234,7 @@ class SolutionArray
* @param fname Name of HDF container file
* @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 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& name, const string& sub,
Expand All @@ -243,17 +246,17 @@ class SolutionArray
* @param root Root node of AnyMap structure
* @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)
* @param overwrite Force overwrite if subgroup exists; optional (default=`false`)
*/
void writeEntry(AnyMap& root, const string& name, const string& sub,
bool overwrite=false);

/**
* Save current SolutionArray contents to a data file.
*
* 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
* 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
Expand All @@ -272,15 +275,15 @@ class SolutionArray
* 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"
* 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)
* (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)
* @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 Phase::nativeState (CSV only)
*/
void save(const string& fname, const string& name="", const string& sub="",
const string& desc="", bool overwrite=false, int compression=0,
Expand Down Expand Up @@ -312,7 +315,7 @@ class SolutionArray
void readEntry(const string& fname, const string& name, const string& sub);

/**
* Restore SolutionArray data from AnyMap; used by YAML serialization.
* Restore SolutionArray data from AnyMap. Used by YAML serialization.
*
* @param root Root node of AnyMap structure
* @param name Identifier of node holding header information
Expand All @@ -324,13 +327,13 @@ class SolutionArray
* 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.
* 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 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"
* metadata objects. If omitted (`""`), the subgroup name defaults to "data"
* @return AnyMap containing header information
*/
AnyMap restore(const string& fname, const string& name, const string& sub="");
Expand Down Expand Up @@ -365,9 +368,9 @@ class SolutionArray

/**
* Identify storage mode of state data. The storage mode is a combination of
* properties defining state); valid modes include Phase::nativeState ("native") or
* other property combinations defined by Phase::fullStates (three-letter acronyms,
* for example "TDY", "TPX").
* properties defining state); valid modes include Phase::nativeState (`"native"`)
* or other property combinations defined by Phase::fullStates (three-letter
* acronyms, for example `"TDY"`, `"TPX"`).
*/
string _detectMode(const set<string>& names, bool native=true);

Expand All @@ -393,7 +396,7 @@ class SolutionArray
//! corresponds to the last entry (different from Python index convention).
shared_ptr<map<int, string>> m_order;

bool m_shared = false; //!< True if data are shared from another object
bool m_shared = false; //!< `true` if data are shared from another object
vector<int> m_active; //!< Vector of locations referencing active entries
};

Expand Down

0 comments on commit 82aec96

Please sign in to comment.