Overview¶

• Overview
  • The Need for MTK
  • MTK Design
  • MTK Workflow

The Need for MTK¶

As Mach 30 moves into more complex engineering projects, its development community will have a greater need to perform up front mathematical analysis to design, size, and predict the performance of those projects. As open source hardware developers, it is essential that we document the fundamental principles, implementation, and results of those analyses. Ideally, we would create this documentation at the same time (and in the same environment) as we are creating those analyses (under Mach 30's "Document as you act" OSHW Ground Rule).

This is where MTK comes in. MTK combines the analysis capabilities of Sage (a Python based math analysis tool) with the document creation power of LaTeX to create a single environment for creating and documenting mathematical analyses. As an added bonus, the use of Python for writing the analysis codes (through Sage) allows Mach 30 to take the analyses created and documented in MTK and use them directly in CadQuery to drive our parametric CAD models when designing and making physical components.

MTK Design¶

MTK combines Sage and LaTeX with support libraries for both packages to deliver the required math and documentation capabilities. The mathematical analysis in implemented by running Python code in Sage. The Python units library, Pint, is included in the Sage environment so hardware developers can include units as a core feature in every analysis. Consistently and correctly managing units is essential in engineering projects as can be seen with Mars Climate Orbiter. This probe missed its orbital insertion maneuver and was lost when the developers and operators mis-communicated about the units for the orbital insertion burn.

The LaTeX IDE (MacTex on Macs and Kile on Linux) provides a unified environment for creating and documenting the mathematical analysis. The Python source code is integrated into the LaTeX document through two libraries. First, execution of the Python code is implemented through SageTex, a library provided with Sage specifically for importing Sage analyses and providing their results in LaTeX documents. Second, formatted source code can is included in the document for review using the Minted LaTeX library. Including the source code with line numbers and syntax highlighting enables developers to easily cross reference implementation with documentation of the fundamental principles behind the analysis.

MTK Workflow¶

An MTK analysis is composed of two main components: the implementation of the analysis in Python and the documentation of the analysis in LaTeX. A developer can start with either the implementation or the documentation. Note, Mach 30's OSHW Ground Rules urge developers to interweave the two actions ("Document before, as, and after you act").

Regardless of the order of development, the Python source is integrated into the LaTeX document in two ways. The Python is imported for execution using SageTex commands and the Python is included for documentation using Minted commands. These files are created and edited in MTK and the analysis is executed in the same typesetting step which produces the final document in the LaTeX IDE. The result is a PDF file containing the the documentation for and results of the analysis ready for presentation to other developers or inclusion in a project's overall documentation.