Use cases for math

[nickerso]

It would be useful to add use-cases for math to the current list (i.e., 1.xii and 1.xiii in the current list at http://libcellml.readthedocs.org/en/latest/usecases.html)

[jonc125]

Where you have just maths & variables, I guess things like:

• a = 1 ms
• a = b
• For each (CellML subset) MathML operator, a separate test case of the simplest possible equation involving it
• A few more complex cases with several operators and levels of nesting
• A simple ODE, e.g. dV/dt = 1 mV/ms
• A simple system of equations, e.g. a=1, a=b+c, b=2

Since we're just checking construction and serialisation at this stage this is perhaps slightly overkill (the last in particular) but they're the sort of thing we'll need when considering units conversions, math evaluation, etc.

With connections, a few of the simple multi-variable cases above, but where the variables come from different components. Again, since we're not yet evaluating, handling source variables several connections away is probably overkill.

[dladd]

From the discussion on pull #66 and resulting changes to the current thinking doc, the consensus was to move forward with treating MathML as a string.

Some possible testing permutations would then be:

• A model with valid/invalid maths in a component
  • with no/one/multiple connections
    • with valid/invalid/no variable(s)
      • with valid/invalid/dimensionless/no units

I propose modifying the use-cases document to explicitly capture a few of these (more permutations will also be tested).

• 1.xiii. a model with maths and variables
  • a. model from 1.xi.d.1 and define invalid maths
  • b. model from 1.xi.d.1 and define valid maths using the two variables with units dimensionless
• 1.xiv. a model with maths, variables and connections
  • a. model with two components, each containing two variables, maths, and one connection
  • b. model from 1.vi.a and define valid maths on variables in child and parent components with one connection

[nickerso]

seems like a good idea to me.

[jonc125]

If we're just treating maths as opaque strings and not resolving variables or units references, those cases seem... difficult to distinguish? And we're not doing validation at all yet. Although I agree they're the sort of thing that would be useful longer term!

[dladd]

True, this may be overkill for the current "Create" step with maths strings- we can cull some (or all but one) of my proposed cases if you think that is more appropriate. But, as you say, these use-cases are recycled in the subsequent "Modify/Load/Validate" steps and could be tests for more complete MathML handling downstream. So it might not hurt to flesh them out now.

[agarny]

If I recall correctly (from a previous issue/PR), we only want to have tests that refer to what we are currently working on. If, down the line, we realise that we need more tests (as we will clearly need here at some point), then we add those tests. (@hsorby, I believe I remember this from one of your comments, so please feel free to correct me if I got/remember it wrong.)

[hsorby]

Yes @agarny you are right, we only want to write tests for what we are currently doing and not what we think we will do.

[dladd]

OK that sounds reasonable. Should we pare the use-cases back to just the "a"s on each item above? I.e.,

• 1.xiii. a model with maths and variables
  • a. model from 1.xi.d.1 and define invalid maths
• 1.xiv. a model with maths, variables and connections
  • a. model with two components, each containing two variables, maths, and one connection