Improve nomenclature and docstrings

include/cantera/oneD/Domain1D.h

@@ -562,7 +562,7 @@ class Domain1D
 
     //! Set shared data pointer
     void setData(shared_ptr<vector<double>>& data) {
-        m_data = data;
+        m_state = data;
     }
 
 protected:
@@ -572,7 +572,7 @@ class Domain1D
     //! Retrieve meta data
     virtual void setMeta(const AnyMap& meta);
 
-    shared_ptr<vector<double>> m_data; //!< data pointer shared from OneDim
+    shared_ptr<vector<double>> m_state; //!< data pointer shared from OneDim
 
     double m_rdt = 0.0;
     size_t m_nv = 0;

include/cantera/oneD/OneDim.h

@@ -340,7 +340,7 @@ class OneDim
     //! factor time step is multiplied by  if time stepping fails ( < 1 )
     double m_tfactor = 0.5;
 
-    shared_ptr<vector<double>> m_data; //!< Solution vector
+    shared_ptr<vector<double>> m_state; //!< Solution vector
 
     std::unique_ptr<MultiJac> m_jac; //!< Jacobian evaluator
     std::unique_ptr<MultiNewton> m_newt; //!< Newton iterator

include/cantera/oneD/Sim1D.h

@@ -198,20 +198,20 @@ class Sim1D : public OneDim
     const doublereal* solution() {
         warn_deprecated("Sim1D::solution",
             "This method is unused and will be removed after Cantera 3.0.");
-        return m_data->data();
+        return m_state->data();
     }
 
     void setTimeStep(double stepsize, size_t n, const int* tsteps);
 
     void solve(int loglevel = 0, bool refine_grid = true);
 
     void eval(doublereal rdt=-1.0, int count = 1) {
-        OneDim::eval(npos, m_data->data(), m_xnew.data(), rdt, count);
+        OneDim::eval(npos, m_state->data(), m_xnew.data(), rdt, count);
     }
 
     // Evaluate the governing equations and return the vector of residuals
     void getResidual(double rdt, double* resid) {
-        OneDim::eval(npos, m_data->data(), resid, rdt, 0);
+        OneDim::eval(npos, m_state->data(), resid, rdt, 0);
     }
 
     //! Refine the grid in all domains.
@@ -280,14 +280,14 @@ class Sim1D : public OneDim
     void setSolution(const doublereal* soln) {
         warn_deprecated("Sim1D::setSolution",
             "This method is unused and will be removed after Cantera 3.0.");
-        std::copy(soln, soln + m_data->size(), m_data->data());
+        std::copy(soln, soln + m_state->size(), m_state->data());
     }
 
     // @deprecated  To be removed after Cantera 3.0 (unused)
     const doublereal* solution() const {
         warn_deprecated("Sim1D::solution",
             "This method is unused and will be removed after Cantera 3.0.");
-        return m_data->data();
+        return m_state->data();
     }
 
     doublereal jacobian(int i, int j);

include/cantera/thermo/Phase.h

@@ -291,7 +291,8 @@ class Phase
     //! and restoreState().
     virtual std::map<std::string, size_t> nativeState() const;
 
-    //! Return string acronym representing native state
+    //! Return string acronym representing the native state of a Phase.
+    //! Examples: "TP", "TDY", "TPY".
     //! @see nativeState
     //! @since  New in Cantera 3.0
     string nativeMode() const;

src/oneD/Domain1D.cpp

@@ -146,28 +146,27 @@ AnyMap Domain1D::serialize(const double* soln) const
 }
 
 shared_ptr<SolutionArray> Domain1D::toArray(bool normalize) const {
-    if (!m_data) {
+    if (!m_state) {
         throw CanteraError("Domain1D::toArray",
             "Domain needs to be installed in a container before calling asArray.");
     }
-    if (!normalize) {
-        return asArray(m_data->data() + m_iloc);
+    auto ret = asArray(m_state->data() + m_iloc);
+    if (normalize) {
+        ret->normalize();
     }
-    auto ret = asArray(m_data->data() + m_iloc);
-    ret->normalize();
     return ret;
 }
 
 void Domain1D::fromArray(const shared_ptr<SolutionArray>& arr)
 {
-    if (!m_data) {
+    if (!m_state) {
         throw CanteraError("Domain1D::fromArray",
             "Domain needs to be installed in a container before calling fromArray.");
     }
     resize(nComponents(), arr->size());
     m_container->resize();
-    fromArray(*arr, m_data->data() + m_iloc);
-    _finalize(m_data->data() + m_iloc);
+    fromArray(*arr, m_state->data() + m_iloc);
+    _finalize(m_state->data() + m_iloc);
 }
 
 void Domain1D::setMeta(const AnyMap& meta)

src/oneD/OneDim.cpp

@@ -25,7 +25,7 @@ OneDim::OneDim(vector<shared_ptr<Domain1D>>& domains)
 {
     // create a Newton iterator, and add each domain.
     m_newt = make_unique<MultiNewton>(1);
-    m_data = make_shared<vector<double>>();
+    m_state = make_shared<vector<double>>();
     for (auto& dom : domains) {
         addDomain(dom);
     }
@@ -41,7 +41,7 @@ OneDim::OneDim(vector<Domain1D*> domains)
 
     // create a Newton iterator, and add each domain.
     m_newt = make_unique<MultiNewton>(1);
-    m_data = make_shared<vector<double>>();
+    m_state = make_shared<vector<double>>();
     for (size_t i = 0; i < domains.size(); i++) {
         addDomain(domains[i]);
     }
@@ -98,7 +98,7 @@ void OneDim::addDomain(shared_ptr<Domain1D> d)
     // add it also to the global domain list, and set its container and position
     m_sharedDom.push_back(d);
     m_dom.push_back(d.get());
-    d->setData(m_data);
+    d->setData(m_state);
     d->setContainer(this, m_dom.size()-1);
     resize();
 }
@@ -125,7 +125,7 @@ void OneDim::addDomain(Domain1D* d)
 
     // add it also to the global domain list, and set its container and position
     m_dom.push_back(d);
-    d->setData(m_data);
+    d->setData(m_state);
     d->setContainer(this, m_dom.size()-1);
     resize();
 }
@@ -241,7 +241,7 @@ void OneDim::resize()
         m_size = d->loc() + d->size();
     }
 
-    m_data->resize(size());
+    m_state->resize(size());
 
     m_newt->resize(size());
     m_mask.resize(size());

src/oneD/Sim1D.cpp

@@ -30,7 +30,7 @@ Sim1D::Sim1D(vector<shared_ptr<Domain1D>>& domains) :
     // domain-specific initialization of the solution vector.
     resize();
     for (size_t n = 0; n < nDomains(); n++) {
-        domain(n)._getInitialSoln(m_data->data() + start(n));
+        domain(n)._getInitialSoln(m_state->data() + start(n));
     }
 
     // set some defaults
@@ -50,7 +50,7 @@ Sim1D::Sim1D(vector<Domain1D*>& domains) :
     // domain-specific initialization of the solution vector.
     resize();
     for (size_t n = 0; n < nDomains(); n++) {
-        domain(n)._getInitialSoln(m_data->data() + start(n));
+        domain(n)._getInitialSoln(m_state->data() + start(n));
     }
 
     // set some defaults
@@ -74,24 +74,24 @@ void Sim1D::setInitialGuess(const std::string& component, vector_fp& locs, vecto
 void Sim1D::setValue(size_t dom, size_t comp, size_t localPoint, doublereal value)
 {
     size_t iloc = domain(dom).loc() + domain(dom).index(comp, localPoint);
-    AssertThrowMsg(iloc < m_data->size(), "Sim1D::setValue",
-                   "Index out of bounds: {} > {}", iloc, m_data->size());
-    (*m_data)[iloc] = value;
+    AssertThrowMsg(iloc < m_state->size(), "Sim1D::setValue",
+                   "Index out of bounds: {} > {}", iloc, m_state->size());
+    (*m_state)[iloc] = value;
 }
 
 doublereal Sim1D::value(size_t dom, size_t comp, size_t localPoint) const
 {
     size_t iloc = domain(dom).loc() + domain(dom).index(comp, localPoint);
-    AssertThrowMsg(iloc < m_data->size(), "Sim1D::value",
-                   "Index out of bounds: {} > {}", iloc, m_data->size());
-    return (*m_data)[iloc];
+    AssertThrowMsg(iloc < m_state->size(), "Sim1D::value",
+                   "Index out of bounds: {} > {}", iloc, m_state->size());
+    return (*m_state)[iloc];
 }
 
 doublereal Sim1D::workValue(size_t dom, size_t comp, size_t localPoint) const
 {
     size_t iloc = domain(dom).loc() + domain(dom).index(comp, localPoint);
-    AssertThrowMsg(iloc < m_data->size(), "Sim1D::workValue",
-                   "Index out of bounds: {} > {}", iloc, m_data->size());
+    AssertThrowMsg(iloc < m_state->size(), "Sim1D::workValue",
+                   "Index out of bounds: {} > {}", iloc, m_state->size());
     return m_xnew[iloc];
 }
 
@@ -133,7 +133,7 @@ void Sim1D::save(const std::string& fname, const std::string& id,
     if (extension == "h5" || extension == "hdf"  || extension == "hdf5") {
         SolutionArray::writeHeader(fname, id, desc, overwrite);
         for (auto dom : m_dom) {
-            auto arr = dom->asArray(m_data->data() + dom->loc());
+            auto arr = dom->asArray(m_state->data() + dom->loc());
             arr->writeEntry(fname, id, dom->id(), overwrite, compression);
         }
         return;
@@ -147,7 +147,7 @@ void Sim1D::save(const std::string& fname, const std::string& id,
         SolutionArray::writeHeader(data, id, desc, overwrite);
 
         for (auto dom : m_dom) {
-            auto arr = dom->asArray(m_data->data() + dom->loc());
+            auto arr = dom->asArray(m_state->data() + dom->loc());
             arr->writeEntry(data, id, dom->id(), overwrite);
         }
 
@@ -174,14 +174,14 @@ void Sim1D::saveResidual(const std::string& fname, const std::string& id,
 void Sim1D::saveResidual(const std::string& fname, const std::string& id,
                          const std::string& desc, bool overwrite, int compression)
 {
-    vector_fp res(m_data->size(), -999);
-    OneDim::eval(npos, m_data->data(), &res[0], 0.0);
-    // Temporarily put the residual into m_data, since this is the vector that the
+    vector_fp res(m_state->size(), -999);
+    OneDim::eval(npos, m_state->data(), &res[0], 0.0);
+    // Temporarily put the residual into m_state, since this is the vector that the
     // save() function reads.
-    vector<double> backup(*m_data);
-    *m_data = res;
+    vector<double> backup(*m_state);
+    *m_state = res;
     save(fname, id, desc, overwrite, compression);
-    *m_data = backup;
+    *m_state = backup;
 }
 
 namespace { // restrict scope of helper function to local translation unit
@@ -303,7 +303,7 @@ AnyMap Sim1D::restore(const std::string& fname, const std::string& id)
         resize();
         m_xlast_ts.clear();
         for (auto dom : m_dom) {
-            dom->fromArray(*arrs[dom->id()], m_data->data() + dom->loc());
+            dom->fromArray(*arrs[dom->id()], m_state->data() + dom->loc());
         }
         finalize();
     } else if (extension == "yaml" || extension == "yml") {
@@ -320,7 +320,7 @@ AnyMap Sim1D::restore(const std::string& fname, const std::string& id)
         resize();
         m_xlast_ts.clear();
         for (auto dom : m_dom) {
-            dom->fromArray(*arrs[dom->id()], m_data->data() + dom->loc());
+            dom->fromArray(*arrs[dom->id()], m_state->data() + dom->loc());
         }
         finalize();
     } else {
@@ -357,7 +357,7 @@ void Sim1D::show(ostream& s)
 {
     for (size_t n = 0; n < nDomains(); n++) {
         if (domain(n).type() != "empty") {
-            domain(n).show(s, m_data->data() + start(n));
+            domain(n).show(s, m_state->data() + start(n));
         }
     }
 }
@@ -368,7 +368,7 @@ void Sim1D::show()
         if (domain(n).type() != "empty") {
             writelog("\n\n>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> "+domain(n).id()
                      +" <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n\n");
-            domain(n).show(m_data->data() + start(n));
+            domain(n).show(m_state->data() + start(n));
         }
     }
 }
@@ -379,7 +379,7 @@ void Sim1D::restoreTimeSteppingSolution()
         throw CanteraError("Sim1D::restoreTimeSteppingSolution",
                            "No successful time steps taken on this grid.");
     }
-    *m_data = m_xlast_ts;
+    *m_state = m_xlast_ts;
 }
 
 void Sim1D::restoreSteadySolution()
@@ -388,7 +388,7 @@ void Sim1D::restoreSteadySolution()
         throw CanteraError("Sim1D::restoreSteadySolution",
                            "No successful steady state solution");
     }
-    *m_data = m_xlast_ss;
+    *m_state = m_xlast_ss;
     for (size_t n = 0; n < nDomains(); n++) {
         vector_fp& z = m_grid_last_ss[n];
         domain(n).setupGrid(z.size(), z.data());
@@ -398,14 +398,14 @@ void Sim1D::restoreSteadySolution()
 void Sim1D::getInitialSoln()
 {
     for (size_t n = 0; n < nDomains(); n++) {
-        domain(n)._getInitialSoln(m_data->data() + start(n));
+        domain(n)._getInitialSoln(m_state->data() + start(n));
     }
 }
 
 void Sim1D::finalize()
 {
     for (size_t n = 0; n < nDomains(); n++) {
-        domain(n)._finalize(m_data->data() + start(n));
+        domain(n)._finalize(m_state->data() + start(n));
     }
 }
 
@@ -420,9 +420,9 @@ void Sim1D::setTimeStep(double stepsize, size_t n, const int* tsteps)
 
 int Sim1D::newtonSolve(int loglevel)
 {
-    int m = OneDim::solve(m_data->data(), m_xnew.data(), loglevel);
+    int m = OneDim::solve(m_state->data(), m_xnew.data(), loglevel);
     if (m >= 0) {
-        *m_data = m_xnew;
+        *m_state = m_xnew;
         return 0;
     } else if (m > -10) {
         return -1;
@@ -494,8 +494,8 @@ void Sim1D::solve(int loglevel, bool refine_grid)
                 if (loglevel > 0) {
                     writelog("Take {} timesteps   ", nsteps);
                 }
-                dt = timeStep(nsteps, dt, m_data->data(), m_xnew.data(), loglevel-1);
-                m_xlast_ts = *m_data;
+                dt = timeStep(nsteps, dt, m_state->data(), m_xnew.data(), loglevel-1);
+                m_xlast_ts = *m_state;
                 if (loglevel > 6) {
                     save("debug_sim1d.yaml", "debug", "After timestepping");
                 }
@@ -506,7 +506,7 @@ void Sim1D::solve(int loglevel, bool refine_grid)
 
                 if (loglevel == 1) {
                     writelog(" {:10.4g} {:10.4g}\n", dt,
-                             log10(ssnorm(m_data->data(), m_xnew.data())));
+                             log10(ssnorm(m_state->data(), m_xnew.data())));
                 }
                 istep++;
                 if (istep >= m_steps.size()) {
@@ -551,7 +551,7 @@ int Sim1D::refine(int loglevel)
     vector_fp znew, xnew;
     std::vector<size_t> dsize;
 
-    m_xlast_ss = *m_data;
+    m_xlast_ss = *m_state;
     m_grid_last_ss.clear();
 
     for (size_t n = 0; n < nDomains(); n++) {
@@ -563,7 +563,7 @@ int Sim1D::refine(int loglevel)
 
         // determine where new points are needed
         ianalyze = r.analyze(d.grid().size(), d.grid().data(),
-                             m_data->data() + start(n));
+                             m_state->data() + start(n));
         if (ianalyze < 0) {
             return ianalyze;
         }
@@ -628,7 +628,7 @@ int Sim1D::refine(int loglevel)
     }
 
     // Replace the current solution vector with the new one
-    *m_data = xnew;
+    *m_state = xnew;
     resize();
     finalize();
     return np;
@@ -717,7 +717,7 @@ int Sim1D::setFixedTemperature(double t)
     }
 
     // Replace the current solution vector with the new one
-    *m_data = xnew;
+    *m_state = xnew;
 
     resize();
     finalize();
@@ -814,7 +814,7 @@ doublereal Sim1D::jacobian(int i, int j)
 
 void Sim1D::evalSSJacobian()
 {
-    OneDim::evalSSJacobian(m_data->data(), m_xnew.data());
+    OneDim::evalSSJacobian(m_state->data(), m_xnew.data());
 }
 
 void Sim1D::solveAdjoint(const double* b, double* lambda)