
<p align="center">
  <img src="https://github.com/user-attachments/assets/1e156ecb-75d5-4004-b768-cbd8edab7940" width="300">
</p>

<!-- ![sb_logo](https://github.com/user-attachments/assets/6c5d9280-70b2-4f66-8bfb-c513317aea06) -->

# Spaceborne

---
[![Documentation Status](https://readthedocs.org/projects/spaceborne/badge/?version=latest)](https://spaceborne.readthedocs.io/en/latest/?badge=latest)

## Quickstart
For detailed instructions on how to install and use Spaceborne, please refer to the [documentation](https://spaceborne.readthedocs.io/en/latest/).

To install the code, we recommend using a dedicated Conda environment. Clone the repository, then checkout the latest release (e.g. `v2025.05.1`) with

```bash
git checkout <latest_version_tag>
```

and run

```bash
conda env create -f environment.yaml
conda activate spaceborne
pip install .
```
**As the code is evolving quite quickly at the moment, please make sure to check for new [releases](https://github.com/davidesciotti/Spaceborne/releases) periodically**

🐍 note: using `mamba` instead of `conda` in the first line will significantly speed up the environment creation. To install `mamba`, run `conda install mamba` in your `base` environment.

Spaceborne leverages `julia` for computationally intensive tasks. We recommend installing `julia` via [`juliaup`](https://github.com/JuliaLang/juliaup):

```bash
curl -fsSL https://install.julialang.org | sh  # Install juliaup
juliaup default 1.10                           # Install Julia version 1.10
```

Then, install the required Julia packages:

```bash
julia -e 'using Pkg; Pkg.add("LoopVectorization"); Pkg.add("YAML"); Pkg.add("NPZ")'
```

### Running the Code

All the available options and configurations can be found, along with their explanation, in the `config.yaml` file. To run `Spaceborne` *with the configuration specified in the* `Spaceborne/config.yaml` *file*, simply execute the following command:

```bash
python main.py
```

If you want to use a configuration file with a different name and/or location, you can instead run with

```bash
python main.py --config=<path_to_config_file>
```

for example:

```bash
python main.py --config="path/to/my/config/config.yaml"
```

To display the plots generated by the code, add the `--show-plots` flag:

```bash
python main.py --config="path/to/my/config/config.yaml" --show-plots
```

Additionally, in the `config.yaml` file you can set `save_figs: True` to save the figures in the `<output_folder>/figs` path.

### Using Docker 🐋

If you find issues with the installation, you can happily disregard the above instructions and run the code through Docker. To do this, install [Docker Desktop](https://www.docker.com/products/docker-desktop/) or the [Docker engine](https://docs.docker.com/engine/); then, in the root of the cloned repository (again, remember to checkout the latest release), run:

```bash
docker-compose up --build
```

Note that the `--build` flag is only needed the first time you run the code (or if you modify the `environment.yaml` or `Dockerfile`, which is *discouraged*). For subsequent runs, simply do:

```bash
docker-compose up
```

Finally, to stop the container, do

```bash
docker-compose down
```

That's it! The container will use your local `config.yaml` file and output to the directories specified in your configuration, just as if you were running locally.

---


