Model Documentation and Tools

As mathematical models grow larger and more complex they become harder to analyse and understand. Once a model is sufficiently complex, the likelihood of someone being able to replicate its behaviour based on the model description in a publication becomes negligible. Making the model source code available is necessary but insufficient to render a model comprehensible, hence the proliferation of semantic markup languages and detailed guidelines to describe models and in silico experiments.

The importance of clear, concise and helpful documentation is also paramount to ensuring a published model and the accompanying simulations are sufficiently well-described that the published results can be replicated independently of the original model implementation. It can be hard to write good prose and to teach the user rather than simply telling them what to do. That’s why it’s important a have good editor; only edit the documentation yourself as a last resort. Good documentation means that your model/software is learnable.

The discipline of software engineering has led to the production of a plethora of languages, tools and processes that can help improve the design, description and maintenance of a complex piece of software. Below is a (very incomplete) list of languages and tools that I have found helpful for the design, implementation, validation and documentation of non-trivial mathematical models.






Type Systems