Metadata-Version: 2.5
Name: quicksat
Version: 0.1.0
Summary: First-pass satellite sizing: mass, data, delta-V and agility budgets, a scenario on a real orbit, power and battery checks, a 3D viewer and file editors
Keywords: satellite,systems engineering,mass budget,power budget,spacecraft design,delta-v,attitude,solar panels,orbit
Author: Egemen Imre
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
License-File: LICENSE.md
Requires-Dist: astropy
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas[output-formatting]
Requires-Dist: portion
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: sgp4
Requires-Dist: pytest ; extra == "test"
Requires-Dist: coverage ; extra == "test"
Requires-Dist: pytest-xdist ; extra == "test"
Project-URL: Changelog, https://github.com/egemenimre/quicksat/blob/master/CHANGELOG.md
Project-URL: Documentation, https://github.com/egemenimre/quicksat/tree/master/docs
Project-URL: Homepage, https://github.com/egemenimre/quicksat/
Project-URL: Issues, https://github.com/egemenimre/quicksat/issues
Project-URL: Repository, https://github.com/egemenimre/quicksat/
Provides-Extra: test
Import-Name: quicksat

# quicksat

[![CircleCI](https://dl.circleci.com/status-badge/img/gh/egemenimre/quicksat/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/egemenimre/quicksat/tree/master)
[![codecov](https://codecov.io/github/egemenimre/quicksat/graph/badge.svg?token=ANT5QB5UB8)](https://codecov.io/github/egemenimre/quicksat)

A first-pass satellite sizing tool, in two parts:

- **[Sizing](#sizing)** works out the mass, data, delta-V and attitude agility budgets. Each budget is a table, worked out from a few input files and a reference orbit.
- **[Scenario and power](#scenario-and-power-with-the-viewer)** flies the satellite through a timeline of activities on a real orbit, and checks the power: what the solar panels generate, what the equipment draws, and the battery between them. A 3D viewer shows the run.

The two parts share no input files. The budgets use a reference orbit, while the scenario needs a real orbit, with an epoch and a node. quicksat is kept simple on purpose. It gives a first-pass sizing, not a full systems engineering environment.

![The viewer with the power sample: the orbit, the body, the current data, the ground track, the timeline, the net power and the battery](https://raw.githubusercontent.com/egemenimre/quicksat/master/docs/images/power_viewer.webp)

*The power sample in the viewer, during the downlink to Svalbard. The wings have turned to face the sun.*

## Install

```bash
pip install quicksat
```

Then copy the samples into a folder of your own. They come from GitHub, for the version you installed, with their data, their notebooks, and the viewers and editor pages written from them:

```bash
python -m quicksat init my_satellite
```

The folder holds `sizing/`, `scenario/` and `power/`. Where this page says `sample/`, read `my_satellite/`. The notebooks need Jupyter, such as `pip install jupyterlab`.

To work on quicksat itself, clone the repository, and install it from there:

```bash
conda env create -f environment.yml
conda activate quicksat
pip install -e .
```

## Sizing

The sizing sample is a small Earth observation satellite on a 500 km sun-synchronous orbit. Its files are in `sample/sizing/data/`. The workflow:

1. **Edit the files.** Double-click [`sample/sizing/editor/editor.html`](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/editor/editor.html) to open the Sizing Editor in your browser. Its Setup tab takes you through every file, step by step, and the other tabs edit one budget each. Save the files, as a zip or one by one, and put them back in `sample/sizing/data/`. The files are YAML and CSV, with units written out, such as `750 g` or `800 Mbit/s`, so they can be edited by hand too.
2. **Run the notebooks** in `sample/sizing/`, in the order below. Each reads the files and builds its budget. Delta-V and agility also read the mass budget.
3. **Read the tables.** Each notebook ends with its budget laid out as a document, and the figures that answer the usual questions.

| Budget | What it gives | Sample | Reference |
|---|---|---|---|
| Mission | The reference orbit and the design life, which every budget shares | | [mission](https://github.com/egemenimre/quicksat/blob/master/docs/sizing/mission_ref.ipynb) |
| Mass | Dry and wet mass, by location, subsystem and owner, with two layers of margin | [mass](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/mass_budget.ipynb) | [mass](https://github.com/egemenimre/quicksat/blob/master/docs/sizing/mass_budget_ref.ipynb) |
| Data | Data made against data sent down each day, and the memory needed between passes | [data](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/data_budget.ipynb) | [data](https://github.com/egemenimre/quicksat/blob/master/docs/sizing/data_budget_ref.ipynb) |
| Delta-V | Delta-V by phase and type, and the propellant it needs | [delta-V](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/delta_v_budget.ipynb) | [delta-V](https://github.com/egemenimre/quicksat/blob/master/docs/sizing/delta_v_ref.ipynb) |
| Agility | Slew times about roll and pitch, from the wheels and the inertia, with a wheel failed or not | [roll](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/agility_roll.ipynb), [pitch](https://github.com/egemenimre/quicksat/blob/master/sample/sizing/agility_pitch.ipynb) | [agility](https://github.com/egemenimre/quicksat/blob/master/docs/sizing/agility_ref.ipynb) |
| Radiator | Not yet specified | | |

The sample works one satellite through each budget. The reference explains each input field, how each figure is worked out, and where the budget stops. For your own satellite, see [how to initialise a satellite](https://github.com/egemenimre/quicksat/blob/master/docs/guides/sizing/initialise_a_satellite.md). [How to edit and run the sizing files](https://github.com/egemenimre/quicksat/blob/master/docs/guides/sizing/edit_the_sizing_files.md) goes round the loop in the Sizing Editor.

## Scenario and power, with the viewer

The power sample flies a 510 km sun-synchronous orbit for three orbits, with imaging, a downlink to Svalbard, and wings that turn to the sun. Its files are in `sample/power/data/`: the scenario, the 3D model, the power system and the consumption table. The workflow:

1. **Edit the files.** Double-click [`sample/power/editor/editor.html`](https://github.com/egemenimre/quicksat/blob/master/sample/power/editor/editor.html) to open the editor in your browser. Its Setup tab takes you through every file, step by step, with an explanation of each choice. The other tabs edit the same data by theme, and a side panel shows the 3D model. Change something, such as the battery's capacity or an activity's trigger. Then save the files, as a zip or one by one, and put them back in `sample/power/data/`.
2. **Run the budget.** Run [`sample/power/power_budget.ipynb`](https://github.com/egemenimre/quicksat/blob/master/sample/power/power_budget.ipynb) in Jupyter, or `python -m quicksat.power sample/power/data sample/power/output` from the command line. Either flies the scenario, works out the generation, the loads and the battery, and checks the budget.
3. **Read the results.** The notebook shows each orbit's energy, the battery's charge, and three checks. The command prints the checks only. In the sample, the lowest charge is 83.6%, above its 70% limit, and every orbit has at least 16.5 W h to spare.
4. **See the run in the viewer.** Both write [`sample/power/output/power_viewer.html`](https://github.com/egemenimre/quicksat/blob/master/sample/power/output/power_viewer.html). Double-click it to see the run in 3D, with the ground track, the timeline, the power and the attitude. Its Attitude tab also gives the attitude as files for other tools.

**Or skip the copy and the run.** `python -m quicksat.editor serve sample/power/data sample/power/output` starts the editor's server, on your computer only, and opens the editor in your browser. Its **Create the viewer** button, in the Files tab, runs the files as they are on the page and writes the viewer. **Open the viewer** then shows it. The server does not change the files in the folder: save them when you want to keep them. See [how to edit, run and view a scenario](https://github.com/egemenimre/quicksat/blob/master/docs/guides/scenario/edit_and_view_a_scenario.md).

![The editor's Articulations step, with the wing +y selected and turned in the 3D panel](https://raw.githubusercontent.com/egemenimre/quicksat/master/docs/images/file_editor.webp)

*The editor's Articulations step. The selected wing shows in the 3D panel, turned with the slider.*

![The viewer's Power tab: the timeline, the power generated and consumed, the battery's charge, the current power and the power setup](https://raw.githubusercontent.com/egemenimre/quicksat/master/docs/images/power_viewer_power_tab.webp)

*The viewer's Power tab. The power and the battery's charge follow the timeline, with the power setup beside them.*

The scenario sample works the same way, for the timeline alone: [`sample/scenario/editor/editor.html`](https://github.com/egemenimre/quicksat/blob/master/sample/scenario/editor/editor.html), then [`sample/scenario/scenario.ipynb`](https://github.com/egemenimre/quicksat/blob/master/sample/scenario/scenario.ipynb) or `python -m quicksat.scenario sample/scenario/data sample/scenario/output`, then `sample/scenario/output/scenario_viewer.html`.

| Part | What it gives | Sample | Reference |
|---|---|---|---|
| Scenario | The timeline on a real orbit: eclipses, attitudes, slews and ground passes, checked against each activity's needs | [scenario](https://github.com/egemenimre/quicksat/blob/master/sample/scenario/scenario.ipynb) | [scenario](https://github.com/egemenimre/quicksat/blob/master/docs/scenario/scenario_ref.ipynb) |
| Power generation | Each solar panel's power, with the wings that turn and the model's own shadows | [generation](https://github.com/egemenimre/quicksat/blob/master/sample/power/power_generation.ipynb) | [generation](https://github.com/egemenimre/quicksat/blob/master/docs/power/power_generation_ref.ipynb) |
| Power consumption | What the equipment draws in each mode | [consumption](https://github.com/egemenimre/quicksat/blob/master/sample/power/power_consumption.ipynb) | [consumption](https://github.com/egemenimre/quicksat/blob/master/docs/power/power_consumption_ref.ipynb) |
| Power budget | The battery's charge through the run, and whether each orbit has energy to spare | [budget](https://github.com/egemenimre/quicksat/blob/master/sample/power/power_budget.ipynb) | [budget](https://github.com/egemenimre/quicksat/blob/master/docs/power/power_budget_ref.ipynb) |

[How to edit, run and view a scenario](https://github.com/egemenimre/quicksat/blob/master/docs/guides/scenario/edit_and_view_a_scenario.md) goes round this loop in full, for the samples or a folder of your own. For what each field means, see [how to set up and run a scenario](https://github.com/egemenimre/quicksat/blob/master/docs/guides/scenario/set_up_a_scenario.md) and [how to set up and run a power budget](https://github.com/egemenimre/quicksat/blob/master/docs/guides/power/set_up_a_power_budget.md).

**The editors** open with the files of the folder that their page was written for. **Open a folder…**, on the first Setup step, reads any other folder, and **Open** on a tab reads one file. Or write a page for a folder of your own. A folder with a `scenario.yaml` gets the Scenario Editor, and a folder of sizing files gets the Sizing Editor:

```bash
python -m quicksat.editor sample/power/data sample/power/editor
```

**Keep your notes in `comments` fields.** Every block of a file can hold one, and so can the file as a whole, in the sizing files too. The editors write their own help as `#` lines, and replace any other `#` comments when they save. When an editor opens a file with such comments, it lists them, and moves each one you choose into a `comments` field. Write a `#` comment on the lines above what it describes, so that it goes to the right block.

## Documentation

The documentation follows the [Diátaxis](https://diataxis.fr/) split. The samples are tutorials, the guides show how to do one task, and the references explain how each part works. The notebooks, their data and the tests are grouped in three domains: `sizing`, `scenario` and `power`. Each set of notebooks reads its own copy of the inputs, so a change to a sample cannot change a figure in a reference.

Two documents cover the project as a whole:

- [`decisions.md`](https://github.com/egemenimre/quicksat/blob/master/docs/explanations/decisions.md) records the decisions that shaped quicksat, and why each was made.
- [`conventions.md`](https://github.com/egemenimre/quicksat/blob/master/docs/reference/conventions.md) holds the rules for the code and the notebooks: units, constants and tests. Read it before changing the code.

## License

GPL-3.0-or-later. See [`LICENSE.md`](https://github.com/egemenimre/quicksat/blob/master/LICENSE.md).

