Software Design Description (Legacy)

Introduction

We present a software design document for the Architect (hereafter referred to as the program): a high-level parametric design tool for the FINCH Eye hyperspectral imaging payload being developed by the University of Toronto Aerospace Team.

The objectives of the document are as follows:

• Outline all parts of the software and how they will work in a cohesive system architecture.

• Address various design concerns and describe rationales for the adopted solutions.

• Act as a stable reference over the course of development.

• Coordinate the developer team under a single vision.

In other words, formally document all rough work including research, equations, references, and software design decisions. The development of such a tool is motivated by the payload team’s need to arrive at refined component-specific requirements. As we have been finding through correspondence with component manufacturers, there are many component parameters that cannot be estimated from reference designs and rule-of-thumb estimates alone. Many are very much instrument-specific, and depend on the scientific objectives as well as many other coupled factors in the system. Attempts at modelling various aspects of the payload have been made (see the Optics Toolkit[1]). These tools have sufficed for the first few design iterations of the payload (up to FINCH Eye v2) but have largely been disjoint and under-documented. Now that the payload team is entering the final stages of design, however, a more formal approach is warranted: one that enables a unified analysis of the entire payload and all of its components. This is the vision for the Architect.

Source code for the project can be found on Github.

Design Values

The following design values guide the design of the program.

Modularity

The adopted software system architecture strives to enable as much modularity and configurability as necessary to enable whatever types of analyses and tradeoff studies are desired. Component models are implemented using object-oriented programming (OOP) to leverage the modularity of the paradigm. Similar components may inherit properties of a parent component (i.e. a VPH grating class may inherit methods and attributes from the surface-relief grating class). This reduces redundancy and the potential for buildup of technical debt.

Usability

The program strives to let the designer focus on the design as opposed to acting as a hindrance from it. Configuration of design parameters is simple, allowing for rapid iteration, with little to no need to get into the gritty details of the implementation. The method used to construct new analyses is straightforward and intuitive. Outputs are reported in a user-friendly format, and leverage multi-dimensional visualization tools.

Traceability

The program and its supporting documentation strive to be traceable. This means all equations and mathematical derivations are traceable back to a source, along with proper description of all assumptions associated with a particular model. This level of transparency is part of proper engineering practice as we mature the design of the payload.

Functional Requirements

Requirement language is to be interpreted as described in RFC 2119.

The program ...

1. Must enable calculation of any quantity of interest associated with the payload given the parameters that define the quantity.

2. Must allow for visualization of the parameter space for a given quantity to enable trade-off analyses.

3. Should allow for automatic optimization of a quantity of interest given a parameter space and constraints.

4. May expose controls and display results to a user-interface.

Scope & Limitations

The following defines the scope of what the program intends to be and what it is not. A well-defined scope for the project is necessary to ensure the primary objectives of the project are met within the time constraints, and to avoid the development of functionality that may be redundant in the context of the other pre-existing tools available to the optics team.

• Closed-form equations: All the equations that are used to model the payload system are closed-form. First- and/or second-order approximations are acceptable, such as the paraxial approximation. Consideration of higher-order phenomena such as optical aberrations is better left to detailed simulations in CODE V[2]

• Ray tracing: the program will not conduct ray tracing. While a ray tracing engine would allow for the direct coupling of mechanical constraints with the system parameters, this is again better left to CODE V. The program is intended to be a high-level design tool. In effect, this limits the types of physical parameters that can be solved for to angles and relative distances.

Platform

The program is to be developed as a Python application. A number of development environments and platforms were considered. The rationale for converging on Python is traced below.

• Desmos: High interactability with built-in sliders and plotting interface. High-fidelity visualization is possible, but requires considerable time investment to do right. Matrix algebra is possible, but requires some hacky solutions to implement. Quickly becomes cluttered and hard to document with more complex programs.

• GeoGebra: Big sister to Desmos. Matrix algebra is built-in, but same arguments of clutter and complexity apply as Desmos.

• Google Colab: Benefits of Python, plus sliders and other interactive UI elements easily creatable via markdown. Linear top-down structure may be limiting with respect to MathCAD.

• GSOLVER: Would produce the most accurate representation of our grating characteristics. Is only useful in the context of diffractor design, and may be excessive for our purposes. We should be alright with first- and second-order approximations of our diffractor models.

• MathCAD: Non-linear project structure makes for a more flexible development environment. Free version is very limited, and does not allow access to symbolic manipulation engine. Paid version is paid.

• MATLAB: Supports vectorization out of the box. MATLAB apps with a UI can be made fairly easily with sliders and plots, but the language is terrible. Period. MATLAB apps are nice, but can quickly become limiting compared to Python.

• Python: Greatest flexibility in most respects. Numpy allows for vectorized functions. Can pair with Tkinter or Pygame to produce UI. Nice graphs are possible using Plotly. No support for function overloading. UI development is not as straightforward as a MATLAB app.

• Unity: Language supports function overloading. Would require team to learn C#. Building the Architect on top of an entire game engine may be excessive, and not at all lightweight to run and develop on.

Recommendation: a Python application, with the potential for adding user-interactability through notebooks built using IPython in Google Colab.

System Architecture

From a system architecture perspective, the Architect can be seen as a collection of component models strung together in various arrangements or pipelines. We describe component models and pipelines in turn.

Components

Component models are implemented as classes (see Python documentation), possessing attributes that define the parameters of the component, alongside methods that enable the calculation of attributes that are not initially defined.

Component class architecture.

Where v, w, x, y, and z are attributes defining the component. Connecting lines are methods used to compute an attribute given the other attributes it depends on. It should be noted that not every parameter is necessarily dependent on every other parameter which defines the component. The concept of input and output variables is dropped in favour of a general multi-directional dependency approach. This is done to provide the design team with as much flexibility as possible in their analysis. For example, a designer wishing to know the associated signal-to-noise ratio (SNR) for a particular slit width might build a pipeline that computes SNR as a function of slit width and all other required parameters. At a later time, the designer may wish to know the slit width required to reach a particular SNR target. To accomplish this, they would simply do some rewiring of the components in the pipeline. The internal logic of the component classes would adjust accordingly to compute slit width as a function of SNR.

Vectorization

Tradebook

A tradebook refers to a collection of components wired together to produce some output(s).

[1] Powered by Desmos, mankind’s greatest invention. Second only to Python.

[2] CODE V is the optic team’s optical simulation tool.

Workflow}

The workflow for the development of component models (Stages A & B) is described:

1. A literature review is conducted on a specific component to source relevant parameters, equations, and typical values for the parameters that describe the component.
2. A mathematical model created and presented in this document. Any required derivations are made and presented. The assumptions and limitations of the model are noted.
3. Once the mathematical model for the component is peer-reviewed, it is implemented in the project source code.
4. Unit tests are written to validate the functionality of the component class.