Analyser: account for an underconstrained NLA system

.gitignore

@@ -1,9 +1,12 @@
-# OS X hidden system files
+# macOS hidden system files
 .DS_Store
 
 # Ignore the build directory
 build/
 
+# Debugging files
+*.profraw
+
 # Eclipse project files
 .project
 .pydevproject

src/analyser_p.h

@@ -51,6 +51,7 @@ struct AnalyserInternalVariable
         COMPUTED_VARIABLE_BASED_CONSTANT,
         INITIALISED_ALGEBRAIC_VARIABLE,
         ALGEBRAIC_VARIABLE,
+        UNDERCONSTRAINED,
         OVERCONSTRAINED
     };
 
@@ -77,8 +78,8 @@ struct AnalyserInternalEquation
     enum struct Type
     {
         UNKNOWN,
-        TRUE_CONSTANT,
-        VARIABLE_BASED_CONSTANT,
+        CONSTANT,
+        COMPUTED_CONSTANT,
         ODE,
         NLA,
         ALGEBRAIC
@@ -125,7 +126,7 @@ struct AnalyserInternalEquation
     bool variableOnRhs(const AnalyserInternalVariablePtr &variable);
     bool variableOnLhsOrRhs(const AnalyserInternalVariablePtr &variable);
 
-    bool check(const AnalyserModelPtr &model, bool checkNlaSystems);
+    bool check(const AnalyserModelPtr &analyserModel, bool checkNlaSystems);
 };
 
 /**
@@ -152,7 +153,7 @@ class Analyser::AnalyserImpl: public Logger::LoggerImpl
 
     Analyser *mAnalyser = nullptr;
 
-    AnalyserModelPtr mModel = AnalyserModel::AnalyserModelImpl::create();
+    AnalyserModelPtr mAnalyserModel = AnalyserModel::AnalyserModelImpl::create();
 
     AnalyserExternalVariablePtrs mExternalVariables;
 
@@ -178,8 +179,8 @@ class Analyser::AnalyserImpl: public Logger::LoggerImpl
     void analyseComponent(const ComponentPtr &component);
     void analyseComponentVariables(const ComponentPtr &component);
 
-    void doEquivalentVariables(const VariablePtr &variable,
-                               VariablePtrs &equivalentVariables) const;
+    void equivalentVariables(const VariablePtr &variable,
+                             VariablePtrs &equivalentVariables) const;
     VariablePtrs equivalentVariables(const VariablePtr &variable) const;
 
     void analyseEquationAst(const AnalyserEquationAstPtr &ast);
@@ -247,7 +248,7 @@ class Analyser::AnalyserImpl: public Logger::LoggerImpl
 
     static bool isExternalVariable(const AnalyserInternalVariablePtr &variable);
 
-    bool isStateRateBased(const AnalyserEquationPtr &equation,
+    bool isStateRateBased(const AnalyserEquationPtr &analyserEquation,
                           AnalyserEquationPtrs &checkedEquations);
 
     void addInvalidVariableIssue(const AnalyserInternalVariablePtr &variable,

src/analyserequation.cpp

@@ -29,20 +29,26 @@ AnalyserEquationPtr AnalyserEquation::AnalyserEquationImpl::create()
     return std::shared_ptr<AnalyserEquation> {new AnalyserEquation {}};
 }
 
-bool AnalyserEquation::AnalyserEquationImpl::isEmptyDependency(const AnalyserEquationWeakPtr &dependency)
+bool AnalyserEquation::AnalyserEquationImpl::isStagingDependency(const AnalyserEquationWeakPtr &dependency)
 {
-    auto analyserVariables = libcellml::analyserVariables(dependency.lock());
+    return libcellml::analyserVariables(dependency.lock()).empty();
+}
+
+void AnalyserEquation::AnalyserEquationImpl::removeStagingDependencies()
+{
+    // Keep track of our constant dependencies, so that we can generate some code for them, should they be untracked.
 
-    if (std::any_of(analyserVariables.begin(), analyserVariables.end(), [](const auto &av) { return av != nullptr; })) {
-        return false;
+    for (const auto &dependency : mDependencies) {
+        auto constantDependency = dependency.lock()->mPimpl->mConstant;
+
+        if (isStagingDependency(dependency)) {
+            mConstantDependencies.push_back(constantDependency);
+        }
     }
 
-    return true;
-}
+    // Effectively remove our staging dependencies.
 
-void AnalyserEquation::AnalyserEquationImpl::cleanUpDependencies()
-{
-    mDependencies.erase(std::remove_if(mDependencies.begin(), mDependencies.end(), isEmptyDependency), mDependencies.end());
+    mDependencies.erase(std::remove_if(mDependencies.begin(), mDependencies.end(), isStagingDependency), mDependencies.end());
 }
 
 AnalyserEquation::AnalyserEquation()
@@ -61,8 +67,8 @@ AnalyserEquation::Type AnalyserEquation::type() const
 }
 
 static const std::map<AnalyserEquation::Type, std::string> typeToString = {
-    {AnalyserEquation::Type::TRUE_CONSTANT, "true_constant"},
-    {AnalyserEquation::Type::VARIABLE_BASED_CONSTANT, "variable_based_constant"},
+    {AnalyserEquation::Type::CONSTANT, "constant"},
+    {AnalyserEquation::Type::COMPUTED_CONSTANT, "computed_constant"},
     {AnalyserEquation::Type::ODE, "ode"},
     {AnalyserEquation::Type::NLA, "nla"},
     {AnalyserEquation::Type::ALGEBRAIC, "algebraic"},

src/analyserequation_p.h

@@ -34,19 +34,22 @@ struct AnalyserEquation::AnalyserEquationImpl
     size_t mNlaSystemIndex;
     bool mIsStateRateBased = false;
 
+    AnalyserVariablePtr mConstant;
+
     std::vector<AnalyserVariablePtr> mStates;
     std::vector<AnalyserVariablePtr> mComputedConstants;
     std::vector<AnalyserVariablePtr> mAlgebraicVariables;
     std::vector<AnalyserVariablePtr> mExternalVariables;
 
+    std::vector<AnalyserVariablePtr> mConstantDependencies;
     std::vector<AnalyserEquationWeakPtr> mDependencies;
     std::vector<AnalyserEquationWeakPtr> mNlaSiblings;
 
     static AnalyserEquationPtr create();
 
-    static bool isEmptyDependency(const AnalyserEquationWeakPtr &dependency);
+    static bool isStagingDependency(const AnalyserEquationWeakPtr &dependency);
 
-    void cleanUpDependencies();
+    void removeStagingDependencies();
 };
 
 } // namespace libcellml

src/analysermodel.cpp

@@ -16,6 +16,8 @@ limitations under the License.
 
 #include "libcellml/analysermodel.h"
 
+#include "libcellml/analyservariable.h"
+
 #include "analysermodel_p.h"
 #include "utilities.h"
 
@@ -229,31 +231,46 @@ AnalyserVariablePtr AnalyserModel::externalVariable(size_t index) const
     return mPimpl->mExternalVariables[index];
 }
 
-size_t AnalyserModel::equationCount() const
+AnalyserVariablePtr AnalyserModel::analyserVariable(const VariablePtr &variable)
+{
+    if (!isValid() || (variable == nullptr)) {
+        return {};
+    }
+
+    for (const auto &analyserVariable : analyserVariables(shared_from_this())) {
+        if (areEquivalentVariables(variable, analyserVariable->variable())) {
+            return analyserVariable;
+        }
+    }
+
+    return {};
+}
+
+size_t AnalyserModel::analyserEquationCount() const
 {
     if (!isValid()) {
         return 0;
     }
 
-    return mPimpl->mEquations.size();
+    return mPimpl->mAnalyserEquations.size();
 }
 
-std::vector<AnalyserEquationPtr> AnalyserModel::equations() const
+std::vector<AnalyserEquationPtr> AnalyserModel::analyserEquations() const
 {
     if (!isValid()) {
         return {};
     }
 
-    return mPimpl->mEquations;
+    return mPimpl->mAnalyserEquations;
 }
 
-AnalyserEquationPtr AnalyserModel::equation(size_t index) const
+AnalyserEquationPtr AnalyserModel::analyserEquation(size_t index) const
 {
-    if (!isValid() || (index >= mPimpl->mEquations.size())) {
+    if (!isValid() || (index >= mPimpl->mAnalyserEquations.size())) {
         return {};
     }
 
-    return mPimpl->mEquations[index];
+    return mPimpl->mAnalyserEquations[index];
 }
 
 bool AnalyserModel::needEqFunction() const

src/analysermodel_p.h

@@ -41,7 +41,7 @@ struct AnalyserModel::AnalyserModelImpl
     std::vector<AnalyserVariablePtr> mAlgebraicVariables;
     std::vector<AnalyserVariablePtr> mExternalVariables;
 
-    std::vector<AnalyserEquationPtr> mEquations;
+    std::vector<AnalyserEquationPtr> mAnalyserEquations;
 
     bool mNeedEqFunction = false;
     bool mNeedNeqFunction = false;

src/analyservariable.cpp

@@ -34,15 +34,21 @@ void AnalyserVariable::AnalyserVariableImpl::populate(AnalyserVariable::Type typ
                                                       size_t index,
                                                       const VariablePtr &initialisingVariable,
                                                       const VariablePtr &variable,
-                                                      const std::vector<AnalyserEquationPtr> &equations)
+                                                      const AnalyserModelPtr &analyserModel,
+                                                      const std::vector<AnalyserEquationPtr> &analyserEquations)
 {
     mType = type;
     mIndex = index;
     mInitialisingVariable = initialisingVariable;
     mVariable = variable;
-    mComponent = owningComponent(mVariable);
+    mAnalyserModel = analyserModel;
 
-    std::copy(equations.begin(), equations.end(), back_inserter(mEquations));
+    std::copy(analyserEquations.begin(), analyserEquations.end(), back_inserter(mAnalyserEquations));
+}
+
+bool AnalyserVariable::AnalyserVariableImpl::constantWithDummyEquation() const
+{
+    return (mType == Type::CONSTANT) && (mAnalyserEquations.front().lock() == nullptr);
 }
 
 AnalyserVariable::AnalyserVariable()
@@ -88,29 +94,46 @@ VariablePtr AnalyserVariable::variable() const
     return mPimpl->mVariable;
 }
 
-size_t AnalyserVariable::equationCount() const
+AnalyserModelPtr AnalyserVariable::analyserModel() const
+{
+    return mPimpl->mAnalyserModel.lock();
+}
+
+// Note: our equation-related methods must account for the fact that a constant initialised using the `initial_value`
+//       attribute (rather than through an equation; e.g., x = 3) will have a dummy equation associated with it which
+//       we don't want to be accessible, hence the calls to constantWithDummyEquation() in the following methods.
+
+size_t AnalyserVariable::analyserEquationCount() const
 {
-    return mPimpl->mEquations.size();
+    if (mPimpl->constantWithDummyEquation()) {
+        return 0;
+    }
+
+    return mPimpl->mAnalyserEquations.size();
 }
 
-std::vector<AnalyserEquationPtr> AnalyserVariable::equations() const
+std::vector<AnalyserEquationPtr> AnalyserVariable::analyserEquations() const
 {
+    if (mPimpl->constantWithDummyEquation()) {
+        return {};
+    }
+
     std::vector<AnalyserEquationPtr> res;
 
-    for (const auto &equation : mPimpl->mEquations) {
-        res.push_back(equation.lock());
+    for (const auto &analyserEquation : mPimpl->mAnalyserEquations) {
+        res.push_back(analyserEquation.lock());
     }
 
     return res;
 }
 
-AnalyserEquationPtr AnalyserVariable::equation(size_t index) const
+AnalyserEquationPtr AnalyserVariable::analyserEquation(size_t index) const
 {
-    if (index >= mPimpl->mEquations.size()) {
+    if (mPimpl->constantWithDummyEquation() || (index >= mPimpl->mAnalyserEquations.size())) {
         return {};
     }
 
-    return mPimpl->mEquations[index].lock();
+    return mPimpl->mAnalyserEquations[index].lock();
 }
 
 } // namespace libcellml

src/analyservariable_p.h

@@ -22,6 +22,8 @@ limitations under the License.
 
 namespace libcellml {
 
+using AnalyserModelWeakPtr = std::weak_ptr<AnalyserModel>;
+
 /**
  * @brief The AnalyserVariable::AnalyserVariableImpl struct.
  *
@@ -33,15 +35,16 @@ struct AnalyserVariable::AnalyserVariableImpl
     size_t mIndex = 0;
     VariablePtr mInitialisingVariable;
     VariablePtr mVariable;
-    ComponentPtr mComponent;
-    std::vector<AnalyserEquationWeakPtr> mEquations;
+    AnalyserModelWeakPtr mAnalyserModel;
+    std::vector<AnalyserEquationWeakPtr> mAnalyserEquations;
 
     static AnalyserVariablePtr create();
 
-    void populate(AnalyserVariable::Type type, size_t index,
-                  const VariablePtr &initialisingVariable,
-                  const VariablePtr &variable,
-                  const std::vector<AnalyserEquationPtr> &equations);
+    void populate(AnalyserVariable::Type type, size_t index, const VariablePtr &initialisingVariable,
+                  const VariablePtr &variable, const AnalyserModelPtr &analyserModel,
+                  const std::vector<AnalyserEquationPtr> &analyserEquations);
+
+    bool constantWithDummyEquation() const;
 };
 
 } // namespace libcellml

src/api/libcellml/analyser.h

@@ -202,7 +202,7 @@ class LIBCELLML_EXPORT Analyser: public Logger
      *
      * @return The analysed model for the @ref Model analysed by this @ref Analyser.
      */
-    AnalyserModelPtr model() const;
+    AnalyserModelPtr analyserModel() const;
 
 private:
     Analyser(); /**< Constructor, @private. */

src/api/libcellml/analyserequation.h

@@ -29,23 +29,23 @@ namespace libcellml {
 class LIBCELLML_EXPORT AnalyserEquation
 {
     friend class Analyser;
+    friend class Generator;
 
 public:
     /**
      * @brief The type of an equation.
      *
-     * The type of an equation, i.e. whether it is used to compute a true
-     * constant, a variable-based constant, a rate, an algebraic variable,
-     * or whether it is placeholder for an external variable.
+     * The type of an equation, i.e. whether it is used to compute a (true) constant, a computed constant, a rate, an
+     * algebraic variable, or whether it is a placeholder for an external variable.
      */
     enum class Type
     {
-        TRUE_CONSTANT, /**< An equation that defines a true constant, e.g. x = 3. */
-        VARIABLE_BASED_CONSTANT, /**< An equation that describes a variable-based constant, e.g. x = y+z where y and z are true constants. */
-        ODE, /**< An equation that describes an ordinary differential equation, e.g. d(y)/dt = f(t, x). */
-        NLA, /**< An equation that is used to compute one or several algebraic variables, e.g. x+y = f(z) where x and y are known, but not z. */
-        ALGEBRAIC, /**< An equation that is used to compute an algebraic variable, e.g. y = f(x). */
-        EXTERNAL /**< A placeholder equation to capture the dependency of the model on an external variable. */
+        CONSTANT, /**< An equation that computes a (true) constant (e.g., x = 3). */
+        COMPUTED_CONSTANT, /**< An equation that computes a computed constant (e.g., x = 3+5, x = 3+z, x = y+z where y and z are (true or computed) constants). */
+        ODE, /**< An equation that computes an ordinary differential equation (e.g., d(y)/dt = f(t, x)). */
+        NLA, /**< An equation that computes one or several algebraic variables (e.g., x+y = f(z) where x and y are known, but not z). */
+        ALGEBRAIC, /**< An equation that computes an algebraic variable (e.g., y = f(x)). */
+        EXTERNAL /**< A placeholder equation that captures the dependency of the model on an external variable. */
     };
 
     ~AnalyserEquation(); /**< Destructor, @private. */