Proposed backward-incompatible changes to the CCGS.

Hi,

I am planning on completely updating the CCGS to make use of CeVAS, 
MaLaES, and CUSES. Due to the large scale of the changes, I am taking 
this opportunity to fix some design issues which currently limit what 
CCGS can do. This inevitably means breaking the existing interface, and 
any code that uses it (I could have tried to make the interfaces look 
the same, but the code generated would still be different, due to the 
changes discussed below).

Major changes proposed:
* The concept of variables and rates in CCGS is being replaced by a 
concept of a computation target. A computation target is anything which 
can be computed by CCGS, and includes variables and  rates (possibly 
multiple times).
* There will no longer be separate blocks of code which explicitly 
compute rates and blocks which explicitly compute variables. Instead, 
computation targets are computed, and as a side effect of this, any 
other algebraic or rate variable may be computed as a pre-requisite. One 
positive result of this is that it will be possible to use derivatives 
like any other variable, so the same derivative can appear more than 
once, and derivatives can even be solved by Newton-Raphson steps if 
required. It means that it is possible to efficient code which evolves 
the model without computing unnecessary variables until they are needed 
for presentation purposes. This completely changes the structure of the 
strings produced, causing backward-incompatibility.
* The idea that a rate is a constant is contemplated, allowing for more 
efficient computation.

I haven't implemented this, so I would welcome any feedback, especially 
from people using the CCGS in their own applications, such as Andre.

Best regards,
Andrew Miller

#include "CellML_APISPEC.idl"
#include "MathML_content_APISPEC.idl"
#include "MaLaES.idl"

module cellml_services
{
  enum VariableEvaluationType
  {
    /**
     * The target appears in the MathML as a bvar for a derivative,
     * (i.e. is the variable of integration).
     */
    VARIABLE_OF_INTEGRATION,

    /**
     * The target has a specific, immediate value, taken from an
     * initial_value attribute, or computed from other constants. It is
     * possible for both derivatives and non-state variables to be constant.
     */
    CONSTANT,
   
    /**
     * The target is a state variable, that is, it starts at an initial
     * value and evolves according to rates defined in the model.
     * Note that derivatives can be state variables too, for example if you
     * define d^3x/dt^3 = t (where t is the variable of integration),
     * then d^3x/dt^3 is COMPUTED, while d^2x/dt^2, dx/dt, and x are
     * of type STATE_VARIABLE.
     */
    STATE_VARIABLE,

    /**
     * The target is not a state variable, but can be computed from 
constants,
     * state variables, variable(s) of integration and other 'algebraic'
     * variables.
     */
    ALGEBRAIC,

    /**
     * No way to compute the variable has yet been determined. This can 
happen
     * if the model is under-constrained or unsuitably constrained, and no
     * constraint would allow the variable to be computed, or if the 
model is
     * overconstrained and the algorithm stopped before it worked out how to
     * compute this variable.
     */
    FLOATING
  };

  enum ModelConstraintLevel
  {
    /**
     * The model is underconstrained. In this case, all code fragments 
will be
     * empty strings. The set of targets which cannot be computed can be 
found
     * because their VariableEvaluationType will be FLOATING. In order 
to make
     * the model work, it is necessary to add equations or initial 
conditions
     * which define some of these variables in terms of variables which 
can be
     * computed.
     */
    UNDERCONSTRAINED,

    /**
     * There were variables which couldn't be found, but there were also
     * equations which could not be used. This normally means that there is
     * a system of equations which would need to be solved. However, in some
     * cases, adding more constraints may allow the model to get past the
     * this and be solved.
     */
    UNSUITABLY_CONSTRAINED,

    /**
     * The model is overconstrained. The code generator will stop at the 
point
     * where a redundant equation was found. The redundant equation will be
     * present in flaggedEquations. The evaluation type will show the 
variables
     * that have already been assigned.
     */
    OVERCONSTRAINED,

    /**
     * The model is correctly constrained. flaggedEquations contains all
     * equations which are evaluated using the Newton-Raphson solver.
     */
    CORRECTLY_CONSTRAINED
  };

  interface ComputationTarget
    : XPCOM::IObject
  {
    /**
     * The variable associated with this computable. Note that there can be
     * more than one computable for a single variable.
     */
    readonly attribute cellml_api::CellMLVariable variable;

    /**
     * The degree associated with the variable. This is zero if the 
value isn't
     * a derivative, one for a first order derivative, two for a second 
order
     * derivative, and so on.
     */
    readonly attribute unsigned long degree;

    /**
     * The type of variable.
     */
    readonly attribute VariableEvaluationType type;

    /**
     * The expression for the variable in the procedural language. This is
     * taken from the expression or expression_d<derivative> annotations
     * associated with the variable, which will usually have been expanded
     * based on the patterns provided to the CodeGenerator.
     */
    readonly attribute wstring name;

    /**
     * Fetches the index assigned to this variable. Raises 
CellMLException if
     * no index was assigned to the variable.
     */
    readonly attribute unsigned long assignedIndex;
  };
#pragma terminal-interface

  interface ComputationTargetIterator
    : XPCOM::IObject
  {
    /**
     * Fetches the next computation target.
     */
    ComputationTarget nextComputationTarget();
  };
#pragma terminal-interface

  interface CodeInformation
    : XPCOM::IObject
  {
    /**
     * The error message, in the event that something is wrong with the 
model.
     * If this is set, code should not use further operations or 
attributes on
     * this object.
     */
    readonly attribute wstring errorMessage;

    /**
     * The constraint level, describing whether or not the model is 
correctly
     * constrained. Note that improperly constrained models result in
     * constraintLevel being set, rather than setting an errorMessage.
     */
    readonly attribute ModelConstraintLevel constraintLevel;

    /**
     * The number of variables which were assigned indices in the variables
     * array. This counts a single CellML variable multiple times if extra
     * variables are inserted due to higher order derivatives.
     */
    readonly attribute unsigned long variableIndexCount;

    /**
     * The number of variables which were assigned indices into the rates
     * array. This counts a single CellML variable multiple times if extra
     * rates are inserted due to higher order derivatives.
     */
    readonly attribute unsigned long rateIndexCount;

    /**
     * The number of variables which were assigned indices into the 
constants
     * array.
     */
    readonly unsigned long constantIndexCount;

    /**
     * There are three types of code strings that can be obtained, each 
for a
     * different purpose. Note that as variables are computed, they are 
added
     * into 'Known variables'.
     * Definitions:
     *   State variable: A variable of which the first or higher derivative
     *     is taken.
     *   VOI or Variable of Integration: A variable with respect to 
which the
     *     model is being integrated.
     *  
     * 
+----------+--------------------+-----------------+--------------+------------------+
     * |  String  | Targeted Variables |Possibly computed|    Known     
|     Purpose      |
     * |          |                    |    variables    |  Variables   
|                  |
     * 
+----------+--------------------+-----------------+--------------+------------------+
     * |initConsts|All variables which |   Any variable  |   None       
|Setting up        |
     * |          |aren't state        |    or rate      |              
|constants and     |
     * |          |variables but have  | except VOIs &   |              
|values computed   |
     * |          |an initial_value    |  state variables|              
|from them.        |
     * |          |attribute, and any  |                 |              
|                  |
     * |          |variables & rates   |                 |              
|                  |
     * |          |which follow.       |                 |              
|                  |
     * 
+----------+--------------------+-----------------+--------------+------------------+
     * |  rates   |All rates which are |Any variable or  |Everything 
set|Efficiently       |
     * |          |not static.         |rate             |above, VOIs,  
|computing rates   |
     * |          |                    |                 |& state       
|for the ODE solver|
     * |          |                    |                 |variables     
|                  |
     * 
+----------+--------------------+-----------------+--------------+------------------+
     * |variables |All variables not   |Any variable     |Everything 
set|Computing the     |
     * |          |computed above      |                 |above, VOIs,  
|remaining         |
     * |          |                    |                 |and state     
|variables.        |
     * |          |                    |                 |variables     
|                  |
     * 
+----------+--------------------+-----------------+--------------+------------------+
     *
     * Note that some rates also have corresponding higher order entries 
in the state
     * variables array. These rates are copied from the state variables 
array into the
     * rates array at the beginning of the rates string, and may be 
relied upon in the
     * rates string.
     * e.g.
     *  INDEX     |    0   |     1     |     2     |
     *  VARIABLES |    x   |   dx/dt   | d^2x/dt^2 |
     *  RATES     |  dx/dt | d^2x/dt^2 | d^3x/dt^3 |
     * RATES[1] is copied from VARIABLES[2], and RATES[0] is copied from 
VARIABLES[1].
     */

    /**
     * The initConsts string, as described in the table above.
     */
    readonly attribute wstring initConstsString;

    /**
     * The rates string, as described in the table above.
     */
    readonly attribute wstring ratesString;

    /**
     * The variables string, as described in the table above.
     */
    readonly attribute wstring variablesString;

    /**
     * A string containing any supplementary code which is needed to be used
     * out-of-line by the above strings. Whether or not supplementary code
     * is used, and exactly what it means depends on the MAL file used with
     * MaLaES, and the options set on the CodeGenerator. Typically, for 
C, it
     * is used to define extra functions that are passed as arguments to
     * functions being called from expressions.
     */
    readonly attribute wstring functionsString;

    /**
     * Iterates through all computation targets.
     */
    ComputationTargetIterator iterateTargets();

    /**
     * The list of flagged equations. Which equations are flagged depends on
     * the outcome in constraintLevel. See the documentation on
     * ModelConstraintLevel for more information.
     */
    readonly attribute mathml_dom::MathMLNodeList flaggedEquations;
  };
#pragma terminal-interface
#pragma cross-module-argument

  interface CodeGenerator
    : XPCOM::IObject
  {
    /**
     * The pattern used to generate constant names (if they are not already
     * annotated). The % character is replaced with the array index.
     * Default: CONSTANTS[%]
     */
    attribute wstring constantPattern;

    /**
     * The pattern used to generate variable names (if they are not already
     * annotated). The % character is replaced with the array index.
     * Default: VARIABLES[%]
     */
    attribute wstring variableNamePattern;

    /**
     * The pattern used to generate rate names (if they are not already
     * annotated). The % character is replaced with the array index.
     * Default: RATES[%]
     */
    attribute wstring rateNamePattern;

    /**
     * The offset at which array indices start. This is normally 0 for
     * languages like C and 1 for languages like MATLAB and FORTRAN.
     * Default: 0
     */
    attribute unsigned long arrayOffset;

    /**
     * The pattern which is used to set variables by assignment.
     * <LHS> is replaced by the variable name.
     * <RHS> is replaced by the expression for the right-hand side.
     * Default: <LHS> = <RHS>;\r\n
     */
    attribute wstring assignPattern;

    /**
     * The pattern which is used to compute variables which cannot be set by
     * assignment.
     * <LHS> is replaced by the expression for the first argument to the
     *       equality.
     * <RHS> is replaced by the expression for the second argument to the
     *       equality.
     * <SUP> causes the following text to go into the supplementary function
     *       array instead of the main code list.
     * <VAR> gives the array index of the variable to compute.
     * <ID> is replaced with a numeric ID unique to this equation.
     * Default: NR_MINIMISE(minfunc_<ID>, CONSTANTS, VARIABLES, 
<VAR>);\r\n<SUP>void minfunc_<ID>(double* CONSTANTS, double* 
VARIABLES)\r\n{\r\nreturn fabs(<LHS>-<RHS>);\r\n}\r\n
     */
    attribute wstring solvePattern;

    /**
     * A MaLaES transform to use. If will be null if it has not bee set, and
     * no code has been generated from this generator. If generateCode is
     * called but this is null, a new default MaLaESTransform will be 
created,
     * with a MAL description suitable for use in C programs.
     * Default: null
     */
    attribute cellml_services::MaLaESTransform transform;

    /**
     * The CeVAS association to use. If this is null (the default) a new 
CeVAS
     * will be requested every time you call generateCode. Be careful to 
use a
     * CeVAS which corresponds to the exact model being passed in to
     * generateCode. The model cannot be changed once the CeVAS is created,
     * until the CeVAS is destroyed.
     * Default: null
     */
    attribute cellml_services::CeVAS useCeVAS;

    /**
     * The CUSES object to use. If this is null (the default) a new CUSES
     * will be requested every time you call generateCode. Be careful to 
use a
     * CUSES which corresponds to the exact model being passed in to
     * generateCode. The model cannot be changed once the CUSES is created,
     * until the CUSES is destroyed.
     * Default: null
     */
    attribute cellml_services::CUSES useCUSES;

    /**
     * The annotation set to use. If this is null (the default) a new 
AnnoSet
     * will be requested every time you call generateCode.
     */
    attribute cellml_services::AnnoSet useAnnoSet;

    /**
     * Generates a CodeInformation object for a model.
     * @param sourceModel The model for which to generate the 
CodeInformation.
     */
    CodeInformation generateCode(in cellml_api::Model sourceModel);
  };
#pragma terminal-interface
#pragma cross-module-argument

  interface CodeGeneratorBootstrap
    : XPCOM::IObject
  {
    CodeGenerator createCodeGenerator();
  };
#pragma terminal-interface
#pragma cross-module-argument