cellml / libcellml Goto Github PK

The documentation could do with some minor cleaning up:

• Remove conf.py (it is not used since there is a conf.py.in)
• Update the Read the Docs links
• Update the year in the copyright information
• Fix the path to the rough object model image
• Remove some trailing spaces here and there
• Customise the Alabaster theme for images (so that we don't have the dotted bottom line for the ABI logo)

Now that the documentation links to the doxygen and coverage generated documentation in addition to the sphinx docs, we need some way to link to a version of that matches the current state of the develop branch (which is what "latest" on readthedocs points at). We can do this by having a step in the buildbot setup that syncs the docs when a merge is being performed, rather than a pull-request being updated.

This issue is mostly here as a reminder that this needs to be implemented. When someone has a chance to do so :)

If I create a build directory and run ccmake .. from it, I get the following options (after the initial configuration):

 CMAKE_OSX_ARCHITECTURES         *                                                                                                                                                                     
 CMAKE_OSX_DEPLOYMENT_TARGET     *                                                                                                                                                                     
 CMAKE_OSX_SYSROOT               *                                                                                                                                                                     
 LIBCELLML_BUILD_SHARED          *OFF                                                                                                                                                                  
 LIBCELLML_BUILD_TYPE            *Release                                                                                                                                                              
 LIBCELLML_INSTALL_PREFIX        */usr/local                                                                                                                                                           
 LIBCELLML_TREAT_WARNINGS_AS_ER  *OFF                                                                                                                                                                  
 LIBCELLML_UNIT_TESTS            *OFF                                                                                                                                                                  

If I switch LIBCELLML_UNIT_TESTS and recompile, I get:

 gtest_disable_pthreads          *OFF                                                                                                                                                                  
 gtest_force_shared_crt          *ON                                                                                                                                                                   
 CMAKE_OSX_ARCHITECTURES                                                                                                                                                                               
 CMAKE_OSX_DEPLOYMENT_TARGET                                                                                                                                                                           
 CMAKE_OSX_SYSROOT                                                                                                                                                                                     
 LIBCELLML_BUILD_SHARED           OFF                                                                                                                                                                  
 LIBCELLML_BUILD_TYPE             Release                                                                                                                                                              
 LIBCELLML_INSTALL_PREFIX         /usr/local                                                                                                                                                           
 LIBCELLML_TREAT_WARNINGS_AS_ER   OFF                                                                                                                                                                  
 LIBCELLML_UNIT_TESTS             ON                                                                                                                                                                   

I understand that gtest_disable_pthreads and gtest_force_shared_crt are specific to gtest, but because of that maybe they should be in the advanced mode. The same holds for CMAKE_OSX_*. So, in the end, I would only have LIBCELLML_* in the main mode.

This issue covers adding support for maths, building on the discussion from issue #65 and pull #66.

This includes:

• Updates to the object model
• Tests and implementation that cover expected functionality and specific use-cases:
  • 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

Using CMake 3.5.1 (i.e. the latest version currently available), we get the following message when doing a simple configuration:

 CMake Deprecation Warning at /Applications/CMake.app/Contents/share/cmake-3.5/Modules/GenerateExportHeader.cmake:383 (message):
   The add_compiler_export_flags function is obsolete.  Use the
   CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN target properties
   instead.
 Call Stack (most recent call first):
   src/CMakeLists.txt:68 (add_compiler_export_flags)

Currently, unit prefixes are set by default to the PREFIX_UNIT enumerator as a tidy way to indicate that no prefix has been set.

However, it has been suggested that this may not be strictly correct, since a base unit by definition does not have a prefix and therefore may not belong in the PREFIXES enum. An alternative proposal is to remove PREFIX_UNIT and add a mHasPrefix Boolean attribute to Unit to indicate whether a prefix has been set.

To vote, use a thumbs-up for keeping PREFIX_UNIT, a thumbs-down for mHasPrefix, or leave a comment for other proposals (or general discussion).

This issue adds support for connections, building on the discussion from issue #82 and pull #85.

In addition to tests for expected functionality and full coverage, specific outlined use-cases to test for are:

• a. a model with one component encapsulating two children, each child containing a single variable
  • 1. with a private interface in the parent and public interface in the child components and connect the variable in both children to the parent.
  • 2. with a public interface in all components and connect the variables in the children to the parent

There should be a readme.

gcov is available on OS X so we should make the coverage testing functionality available on this platform

Implement use case 1.ii and 1.iii

As the object model is expanded with new features (for example see the file changes in #85 ), it is becoming somewhat unwieldy to view as an extensive list of all overloaded functions and private members. It has been suggested that this diagram would better serve as a birds-eye overview (hence the "rough" in the title) of the public-facing API.

For explicit details on all available functions and features (public and private) and full class diagrams we would instead refer to the generated Doxygen documentation. This would provide more granularity, be less prone to errors from transcription & unincorporated changes, and generally be a more direct reflection of the code in its current state.

To vote, use a thumbs-up for a simplified diagram, a thumbs-down for an explicit-as-possible diagram, or leave a comment for other proposals (or general discussion).

This issue is for implementing support for use case 1.x, creating a model with imported units.

This covers proposed changes to the rough object model(s) to incorporate use-case 1.xi: creating a model with variables.

See https://github.com/cellml/libcellml/pull/42/files#r36632518 for some background on this 'issue'.

The next feature to build on from the use-cases doc is 1.xii: a model with connections. I thought it would be a good idea to put down some of the current thinking on how things might fit together.

Consider a simple serialised model with a connection:

    <?xml version=\"1.0\" encoding=\"UTF-8\"?>
    <model xmlns=\"http://www.cellml.org/cellml/1.2#\">
      <component name=\"component1\">
        <variable name=\"variable1\"/>
      </component>
      <component name=\"component2\">
        <variable name=\"variable2\"/>
      </component>
      <connection>
        <map_components component_1=\"component1\" component_2=\"component2\"/>
        <map_variables variable_1=\"variable1\" variable_2=\"variable2\"/>
      </connection>
    </model>

To build this up, two options have been discussed so far: (1) allowing direct access to connections through the API and (2) keeping connections "under the hood":

• 1. The connection is built through the API and passed variables to map: e.g.,

    libcellml::Model m;
    // Create connection object.
    libcellml::ConnectionPtr connection1 = std::make_shared<libcellml::Connection>(); 
    libcellml::ComponentPtr comp1 = std::make_shared<libcellml::Component>();
    libcellml::ComponentPtr comp2 = std::make_shared<libcellml::Component>();
    libcellml::VariablePtr v1 = std::make_shared<libcellml::Variable>();
    libcellml::VariablePtr v2 = std::make_shared<libcellml::Variable>();

    comp1->setName("component1");
    comp2->setName("component2");
    v1->setName("variable1");
    v2->setName("variable2");

    comp1->addVariable(v1);
    comp2->addVariable(v2);
    m.addComponent(comp1);
    m.addComponent(comp2);
    // Pass the two variables to the connection object
    connection1.mapVariables(v1,v2); 
    // Add the connection to the model
    m.addConnection(connection1); 

• 2. The connection is instantiated as a part of the model inside the library: e.g., don't create connection1 and replace the last two non-comment lines from (1) with:

    ...
    // Instantiate the connection; pass v1 and v2 to the connection; add the connection to the parent model
    v1.isEquivalentTo(v2); 

In both cases, I am assuming that we get each component for map_components as each variable's respective parent component. In (2) I also assume that we can similarly get the parent model from these components to instantiate a new connection.

In discussions at the ABI on Friday, I believe the team here were more in favour of option (2). It is arguably more user-friendly and specifying the operations associated with connection in the Variable class allows for a cleaner set of overloaded functions. There was also some debate over whether the concept of a connection was relevant to a user.

However, while (1) may be a bit more clunky, it relaxes the requirements on variables passed to the connection. For a valid model, the mapped variables do not need to have parent components or models until serialisation. (1) also allows for invalid definitions of connections (e.g., variables without parent components), which has been standard for testing other features so far (e.g., variables without defined units). Thus (1) is also more conducive to testing. In contrast, (2) requires mapped variables to have both parent components and parent models at execution of isEquivalentTo() in order to instantiate the connection.

I am therefore now more in favour of option (1) personally.

This issue is for implementing support for use case 1.ix, creating a model with units.

To standardise practices in the codebase, a formatting tidy-up has been proposed after pulls #71 and #68 come through.

I'll add to and edit the list of changes to be implemented in this opening comment based on agreed upon features in the discussion below.

Practices to standardise

• Increment should be done in pre-form (++i rather than i++) when the methods are otherwise equivalent.
• Conditional and loop statements should have a space before opening parentheses. E.g., for ( rather than for(.
• Doxygen comments should be in sentence-style: beginning with capitalisation and ending with punctuation.
• Test names should be in camelCase and explicit to help identify which specific features they cover.
• Spaces should be used for indentation- not tabs.

This is a proposal to swap out the Load (currently 2) and Modify (currently 3) tasks in usecases.rst.

The thinking here is that it will be a more logically incremental step for development/testing to extend the models from the Create task (1) than to start dealing with loading/importing models at this stage.

Some of the image file names in the libCellML documentation is causing the PDF generation on readthedocs to fail:

...MLRoughObjectModel-UseCases1.i-1.iii.png}

! LaTeX Error: Unknown graphics extension: .i-1.iii.png.

the HTML version is unaffected. Renaming the files and updating the references should be sufficient to avoid this issue.

It is nice to group the targets created into folders in Visual Studio. This makes the code much more manageable and usable.

Currently there is no determination on whether or not the coverage test/memcheck test can be run, it will just noisily fail if executed and the required software is not accessible. This should be checked by the build system beforehand and make the user aware of the status.

We should decide on what variable naming convention to follow, after some comments on pull request #22 it would appear we have different opinions. This issue is to sort out the naming convention for variables and have the decision added to the libcellml coding standard documentation.

It would be good to document the intended scope of libCellML and this issue is to ensure there is agreement on the scope of the library. Obviously the scope may change over time, but this initial scope will guide the development of the project to address the initial set of use-cases.

The initial proposal is that the purpose of libCellML is to create, manipulate, serialise, deserialise, validate and instantiate CellML models. In the first instance, all serialising and deserialising will be to and from standard strings and using the CellML XML format.

The library should be lightweight and focused purely in dealing with CellML models. In achieving this, some of the convenience methods/objects that we might expect will not be part of libCellML. For example, in our current thoughts, libCellML would not be concerned with the actual mechanics of resolving and retrieving external resources - calling applications would be required to resolve and retrieve import URL's and provide the serialised documents to libCellML in the form of strings for instantiation as part of the CellML 1.1/1.2 hierarchical model description.

Example code would be provided which demonstrates how such tasks can be achieved using standard tools, i.e., libcurl for C/C++ and maybe whatever PMR2 uses in Python to resolve and retrieve imported models.

It would be a good idea to be able to generate the documentation outside of the source directory. This keeps the source directory clean and keeps to the same philosophy that we have when building the library.

It should also be possible to create the documentation through a command in the build directory like make docs. Of course, the documentation you can create will be dependent on the tools available, currently we require:

• Sphinx - For the project documentation
• Doxygen- For the API documentation
• gcov and Python - For the coverage documentation

The project requires some documentation to be written. It would be helpful to have information on how to:

• setup the library
• build the library
• contribute code to the project
• coding standard
• review (for those who have authority)

This issue is for implementing support for use case 1.xi, creating a model with variables.

This includes:

• a. model from 1.iv.a and define a variable with a valid name and units dimensionless
  • 1. with a valid variable initial value of 0.0
• b. model from 1.iv.a and define a variable with an invalid name and units dimensionless
• c. model from 1.iv.a and define a variable with a valid name and invalid units name.
• d. a model with a single component containing two variables.
  • 1. with valid variable initial values of 1.0 and -1.0, respectively
  • 2. one with an initial value of 1.0 and the other with an initial value of the first variable.

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)

Now that we are a little way through the implementation and have had a look at how the API is starting to form, there appears to be a difference of opinion on what should be returned through the API:

• references, or
• pointers.

This issue is to decide which route we should take.

This issue was raised in pull request #36

This issue covers the Modify step as outlined in the use-cases doc. This includes:

• Updates to the object model
• Tests and implementation to modify models from the Create step (1).
  • add {components, units, maths, variables, connections}
  • remove {components, units, maths, variables, connections}
  • update {components, units, maths, model attributes, variables, connections}

Before heading too far down the implementation path of the libCellML object model, we should implement some tests demonstrating the use of libCellML to modify an existing model and component encapsulation hierarchy. See the related discussion thread here: https://groups.google.com/forum/#!msg/libcellml-team/ELvmfQiY7EE/uXwpNayqw_MJ

(current use-case list available at: http://libcellml.readthedocs.org/en/latest/usecases.html)

There are a few occurrences such as IF( XXX ) and SET( XXX ) while in most cases we use IF(XXX) and SET(XXX).

@agarny possibly considers the currently accepted rough object model to be too rough. This issue is to tidy up the diagram and reduce it's roughness.

The object model for use cases 1.i - 1.iii will not be sufficient for use cases up to 1.vi. So the object model needs to be updated.

This issue picks up general items for clean-up before we move on to Modify use-cases. Feel free to comment with anything else you would like to see addressed.

• Change variable interface type handling to be consistent with unit prefixes from #103
  • Would allow us to get rid of the remaining EXPORT_FOR_TESTING instance
  • If we store the interface type as a string internally, we could:
    • allow the user to specify the interface type by string.
    • allow the user to serialise out interface_type=none if they choose to do so.
• Swap out plain enums for enum classes where possible
  • More strongly typed and generally preferred in C++11
  • Example usage:

libcellml::Prefixes prefix = libcellml::Prefixes::MICRO;
libcellml::Variable::InterfaceTypes interfaceType1 = libcellml::Variable::InterfaceTypes::NONE;

vs. the current style:

libcellml::PREFIXES prefix = libcellml::PREFIX_MICRO;
libcellml::Variable::INTERFACE_TYPES interfaceType1 = libcellml::Variable::INTERFACE_TYPE_NONE;

We need to be sure to include a funding acknowledgement section in the documentation and track all the funding received to support libCellML development. Perhaps even on the front page of the website with logos and links?

To date we have not used the GitHub issue labels feature in this project. It would be useful to see whether people think this is something we should start doing? And if we do, we should probably add our intended interpretation for the labels to the contributing docs.

This issue is for implementing support for use case 1.viii, creating a model with imported components.

Add the fused gtest source code that will be used for unit testing the library.

In #98, @jonc125 pointed out that there is extraneous text that has crept into our Apache license that reads 'Some license of other'

The use cases we wish to satisfy are:

• manipulation of a model with multi-level component encapsulation hierarchy
  • remove a component
  • change the name of a top-level component
  • change the name of an encapsulated child component
  • replace one component with a new component
  • take a component (remove the component and return it to the user)
  • determine if a component with a given name exists in a model or component
  • determine the number of components encapsulated by a model or component

The initial code stub should give the outline for how the source code, tests and documentation should be arranged. Including a fully functioning test on the version of the library. Thus also showing how Buildbot is integrated into the process.

I was wondering about the use of an XML library, not required as yet but would probably be helpful once deserialisation comes in to play. Originally I thought we'll just use libxml2 but maybe tinyxml2 (https://github.com/leethomason/tinyxml2) will be sufficient. We could include this in the code and carry it around, much simpler than finding dependencies (especially on Windows).

Thoughts?

This issue is for discussion around the object model that we should implement to at least meet the needs of Use Cases 1.i - 1.iii

The use cases we wish to satisfy are:

• a model with a single component
  • a component with a valid name
  • a component with an invalid name
• a model with two or more components
• a model with three components and an encapsulation hierarchy
  • one component encapsulating two children
  • one component encapsulating a single child which in turn encapsulates a single child
  • an invalid cyclical encapsulation hierarchy

Before we move on to connections, we should add support for the variable interface attribute (public / private / public_and_private / none ). I'll put in pull requests for the corresponding updates to the use-cases doc, the object model, tests, and implementation under this issue.

Current thinking is to implement the interface attribute as an enum rather than simple strings.

Implement code to satisfy use case 1.i

I know David isn't at this stage yet, but it occurred to me that this might be a question which required some discussion & investigation, and would be useful to start early so we don't hold him up!

The thinking was: Given CellML 1.2 removes the directionality of connections, there will need to be more analysis of the mathematical model in order to determine the unknowns and to be able to determine the resulting set of equations and the order in which they may need to be evaluated. My current thinking is that this kind of thing should be handled by some kind of computational algebra system - so hopefully this will just be a matter of finding the right library to use and getting our MathML into that, possibly with some pre-processing. This will also give us the math in a tool that will enable symbolic optimisations & transformations, a la Chaste.

Does anyone have experience of such libraries in C++? I'm only familiar with Python options such as Sage and the underlying SymPy. A brief google search suggests SymbolicC++ as one option.

This issue is for determining what the default values for the configuration options should be, here are the current options that can be configured along with their current default value:

LIBCELLML_UNIT_TESTS: ON
LIBCELLML_TREAT_WARNINGS_AS_ERRORS: OFF
LIBCELLML_BUILD_TYPE: Release
LIBCELLML_INSTALL_PREFIX: ${CMAKE_INSTALL_PREFIX}
LIBCELLML_BUILD_SHARED: OFF

[only available with gnu compilers]
LIBCELLML_COVERAGE: OFF
LIBCELLML_MEMCHECK: OFF

Due to the use of the term 'current thinking' we should look at trying to capture this in a document. The 'current thinking' is encapsulated by the tests and the change to the use cases and has been driven in part through offline discussions, clarification of points, and issues arising from implementation.

Such a document would be quite dynamic and changeable.