Mathematics Tool Kit

The first set of topics I want to discuss relate to why Mach 30 needs MTK. At the most basic level, we need MTK so we can do math (specifically engineering math). But, it is not enough to just do the math, we need to be able to document it (both to ensure we meet our standards for OSHW and to support quality peer review). Ideally we want a single tool that can do the math and document the math to facilitate following our ground rules of OSHW documentation. 

1. Document before you act - With engineering math, this means doing things like finding the correct mathematical models, identifying the key equations from those models, and demonstrating why the selected models are the correct ones to use. This involves writing narratives and the equations covering the items above and citing sources used to arrive at the selected equations. This phase should also identify test cases for later verification efforts. 
2. Document as you act - In engineering math, a critical part of "as you act" is coding up the equations from the mathematical models, preferably into reusable modules (functions, classes, etc). When I am writing up rigorous verification of my engineering math, I like to provide commentary on the critical sections of the code, showing how specific lines of code implement the required equations or methodologies (such as solver algorithms). Being able to easily switch between the code I am writing and this kind of documentation in the same tool would be a huge productivity boost, making it easier to follow this ground rule. 
3. Document after you act - Once the engineering math has been implemented, it needs to be tested. The test cases need to be run, the results should be verified and interpreted visually with plots and tables and with narrative commentary to prove to readers that the code is ready to be used. 

Yesterday I talked about how Mach 30's OSHW documentation ground rules help shape how we should go about doing engineering math.  Tonight I want to talk about how we could break up the tasks discussed last night to be done by different volunteers to distribute the work and to enable remote collaboration by a team of contributors that results in high quality, well tested, and well documented engineering math in reusable modules.

I will do this by telling a little story (some may recognize this as a CONOPS or CONcept of OPerations).  Let me begin by setting the scene.  Let's say Mach 30 needs to do engineering analysis (aka math) on ballistic trajectories for a sub-orbital test vehicle (the rocket science equivalent to throwing a ball, very high). Engineer Isaac knows all of the physics and math involved to predict the vehicle's flight, but he is not comfortable coding it up. Fortunately, Mach 30 also has Programmer Ada who rocks at writing Python and can easily translate math to code.  

So, they decide to team up on developing Mach 30's ballistic analysis. Isaac starts a new MTK project and writes a short intro covering why we need this new analysis, and then spends most of his time researching and writing down (aka he documents before they act):

• the equations we need to use for this analysis
• why these are the right equations
• how to use them, with an example
• some test cases (inputs and expected outputs)

This work is in Isaac's wheelhouse. He is able to knock it out quickly and easily.  Best of all this work is fun for him.  When he is done he easily shares this work with Ada since they are using a common platform for their contributions to the project.

Ada takes over to design and implement the Python class that will perform the calculations Isaac specified. As she develops her code in MTK, she references and expands the documentation, which is open in a panel next to her code for easy access.  She adds a section showing how different parts of her code compute the results of the equations and how they do so with the correct data and in the correct order (documenting as she acts).  Ada then writes up the test cases in a test suite and includes the results of those test cases in the documentation (a kind of documenting after she acts).  

Notice how the only documentation Ada is writing directly relates to her code and just explains how it works in relation to the material Isaac provided. Everything else Ada is doing involves writing a key Python library for Mach 30.  Even the test cases are easier to write because they are based on engineering research from Isaac. This is a productive and enjoyable contribution for Ada involving a minimum of fuss reviewing and writing documentation.

Isaac then takes a look at the updated MTK project's documentation, instead of having to review each line of source code.  Isaac pays special attention to the implementation details ("hmm, yes that code excerpt does compute the value for equation 3") and the test results which could include tables and figures ("yup, that's the right plot"). If he has questions, he can get on a hangout to review things with Ada. When they are about done, Isaac writes up a short conclusion and abstract wrapping up the documentation (one last bit of documenting after they act). 

The jointly created documentation could be shared inside and outside Mach 30 for peer review and the Python class would be ready for use after addressing any comments from the peer review. Of course, those comments and updates would be handled in MTK as well. 

OK, here goes another round of brain dumping. This reply is about identifying the functions and implementing elements that go into making MTK (under the new implementation decision to use IPython and friends). Bold elements are functions, and Italic elements are implementing elements.

• Provide a common platform for implementing and documenting engineering math - MTK
  • Enable the development of engineering math - IPython runtime hosted in Spyder IDE
    • Support calculations of physical quantities by supporting units in mathematical calculations - Pint units library
  • Enable the documentation of engineering math - Customized Jupyter notebooks hosted in Spyder IDE
    • Support easy movement between narrative and mathematical expression producing professional PDFs - Stock Jupyter notebooks
    • Support editing documentation in IDE environment - Spyder extension to display web content displaying Jupyter notebooks
    • Support displaying formatted code inline in documentation - Custom Jupyter notebook magic to implement formatted text output from source file
    • Support easy plotting of engineering data - <insert Jupyter plotting library here>
    • Support inclusion of calculation results inline with narrative sections - Jupyter Python Markdown notebook extension
    • Support "hidden" calculations to suppress repetitive calculations from exported reports without removing them from the documentation source - Jupyter Code Folding notebook extension
    • Support displaying tables of engineering data, including units - <probably from Pandas support in IPython/Jupyter>

Here is an open source SysML tool to look at when generating new block diagrams - https://eclipse.org/papyrus/