Release v0.1.3

.github/workflows/deploy_to_pypi.yml

@@ -17,6 +17,7 @@ jobs:
           python-version: 3.8
       - name: Install dependencies
         run: |
+          export SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True
           pip install --upgrade pip
           pip install setuptools wheel twine
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

.github/workflows/deploy_to_test_pypi.yml

@@ -17,6 +17,7 @@ jobs:
           python-version: 3.8
       - name: Install dependencies
         run: |
+          export SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True
           pip install --upgrade pip
           pip install setuptools wheel twine
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

.github/workflows/docker-image.yml

@@ -0,0 +1,44 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# GitHub recommends pinning actions to a commit SHA.
+# To get a newer version, you will need to update the SHA.
+# You can also reference a tag or branch, but the action may change without warning.
+
+name: Build and publish a Docker image for PASEOS
+
+on:
+  push:
+    branches: [ "release" ]
+
+  workflow_dispatch:
+
+jobs:
+  push_to_registry:
+    name: Push Docker image to Docker Hub
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build the Docker image
+        uses: actions/checkout@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
+        with:
+          images: gabrielemeoni/paseos
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/docker-nightly-image.yml

@@ -0,0 +1,44 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# GitHub recommends pinning actions to a commit SHA.
+# To get a newer version, you will need to update the SHA.
+# You can also reference a tag or branch, but the action may change without warning.
+
+name: Build and publish a Docker image for PASEOS-nightly
+
+on:
+  push:
+    branches: [ "main" ]
+
+  workflow_dispatch:
+
+jobs:
+  push_to_registry:
+    name: Push Docker image to Docker Hub
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build the Docker image
+        uses: actions/checkout@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@98669ae865ea3cffbcbaa878cf57c20bbf1c6c38
+        with:
+          images: gabrielemeoni/paseos-nightly
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

CITATION.cff

@@ -0,0 +1,57 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "PAseos Simulates the Environment for Operating multiple Spacecraft"
+authors:
+- given-names: Pablo  
+  family-names: Gómez
+  email: pablo.gomez@esa.int
+  affiliation: >-
+    Advanced Concepts Team, European Space Agency,
+    Noordwijk, The Netherlands
+    orcid: "https://orcid.org/0000-0002-5631-8240"
+- given-names: Johan
+  family-names: Östman
+  affiliation: >-
+    AI Sweden, Gothenburg, Sweden
+  orcid: "https://orcid.org/0000-0003-4138-0508"
+- given-names: Vinutha
+  family-names: Magal Shreenath
+  affiliation: >-
+    AI Sweden, Gothenburg, Sweden
+- given-names: Gabriele
+  family-names: Meoni
+  affiliation: >-
+    Phi-Lab, European Space Agency, Rome, Italy
+  orcid: "http://orcid.org/0000-0001-9311-6392"
+repository-code: "https://github.com/aidotse/PASEOS"
+url: "https://paseos.readthedocs.io/en/latest/"
+repository-artifact: "https://pypi.org/project/paseos/"
+license: GPL-3.0
+preferred-citation:
+  type: article
+  authors:
+  - given-names: Pablo
+    family-names: Gómez
+    email: pablo.gomez@esa.int
+    affiliation: >-
+      Advanced Concepts Team, European Space Agency,
+      Noordwijk, The Netherlands
+    orcid: "https://orcid.org/0000-0002-5631-8240"
+  - given-names: Johan
+    family-names: Östman
+    affiliation: >-
+      AI Sweden, Gothenburg, Sweden
+    orcid: "https://orcid.org/0000-0003-4138-0508"
+  - given-names: Vinutha
+    family-names: Magal Shreenath
+    affiliation: >-
+      AI Sweden, Gothenburg, Sweden
+  - given-names: Gabriele
+    family-names: Meoni
+    affiliation: >-
+      Phi-Lab, European Space Agency, Rome, Italy
+    orcid: "http://orcid.org/0000-0001-9311-6392"
+  doi: "10.48550/ARXIV.2302.02659"
+  journal: "ArXiV"
+  title: "PAseos Simulates the Environment for Operating multiple Spacecraft"
+  year: 2023

Dockerfile

@@ -0,0 +1,50 @@
+FROM ubuntu:22.10
+ARG CONDA_PYTHON_VERSION=3
+ARG USERNAME=user
+ARG HOME=/home/user
+ARG CONDA_DIR=$HOME/conda
+ARG USERID=1000
+
+
+# Create the user
+RUN useradd --create-home -s /bin/bash --no-user-group -u $USERID $USERNAME 
+
+# Instal basic utilities
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git wget unzip bzip2 sudo build-essential ca-certificates && \
+    apt-get install libsm6 libxext6  -y && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+## Install miniconda
+ENV PATH $CONDA_DIR/bin:$PATH
+RUN wget --quiet https://repo.continuum.io/miniconda/Miniconda$CONDA_PYTHON_VERSION-latest-Linux-x86_64.sh -O /tmp/miniconda.sh && \
+    echo 'export PATH=$CONDA_DIR/bin:$PATH' > /etc/profile.d/conda.sh && \
+    /bin/bash /tmp/miniconda.sh -b -p $CONDA_DIR && \
+    rm -rf /tmp/*
+
+
+RUN chown $USERNAME $HOME -R && \
+    adduser $USERNAME sudo && \
+    echo "$USERNAME ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+USER $USERNAME
+WORKDIR /home/$USERNAME/paseos
+
+# copy all files.
+COPY . $HOME/paseos
+
+# Install mamba
+RUN conda install -y mamba -c conda-forge
+RUN mamba env update --file environment.yml --name base
+
+# For interactive shell
+SHELL ["/bin/bash", "-c"]
+
+RUN echo ". activate base" >> $HOME/.bashrc  && \ 
+    chmod u+x $HOME/.bashrc && \ 
+    $HOME/.bashrc && \
+	pip install -e . --no-dependencies --ignore-requires-python
+
+
+ENV PATH $HOME/conda/envs/env/bin:$PATH

README.md

@@ -1,6 +1,6 @@
 ## PASEOS - PAseos Simulates the Environment for Operating multiple Spacecraft
 
-![Read the Docs (version)](https://img.shields.io/readthedocs/paseos/latest?style=flat-square) ![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/aidotse/PASEOS/.github/workflows/run_tests.yml?branch=main?style=flat-square) ![GitHub last commit](https://img.shields.io/github/last-commit/aidotse/PASEOS?style=flat-square)
+![Read the Docs (version)](https://img.shields.io/readthedocs/paseos/latest?style=flat-square) [![Tests](https://github.com/aidotse/paseos/actions/workflows/run_tests.yml/badge.svg)](https://github.com/aidotse/paseos/actions/workflows/run_tests.yml) ![GitHub last commit](https://img.shields.io/github/last-commit/aidotse/PASEOS?style=flat-square)
 ![GitHub](https://img.shields.io/github/license/aidotse/PASEOS?style=flat-square)
 ![GitHub contributors](https://img.shields.io/github/contributors/aidotse/PASEOS?style=flat-square)
 ![GitHub issues](https://img.shields.io/github/issues/aidotse/PASEOS?style=flat-square) ![GitHub pull requests](https://img.shields.io/github/issues-pr/aidotse/PASEOS?style=flat-square)
@@ -13,6 +13,8 @@
     <a href="https://github.com/aidotse/PASEOS/issues">Report Bug</a>
     ·
     <a href="https://github.com/aidotse/PASEOS/issues">Request Feature</a>
+    ·
+    <a href="https://arxiv.org/abs/2302.02659">Read the Paper</a>
 </p>
 
 Disclaimer: This project is currently under development. Use at your own risk.
@@ -130,11 +132,26 @@ Alternatively, you can install PASEOS by using [pip](https://www.pypy.org/) as f
 cd PASEOS
 pip install -e .
 ```
+### Using Docker
+Two [Docker](https://www.docker.com/) images are available:
+* [paseos](https://hub.docker.com/r/gabrielemeoni/paseos): corresponding to the latest release.
+* [paseos-nightly](https://hub.docker.com/r/gabrielemeoni/paseos-nightly): based on the latest commit on the branch `main`. 
+
+If you want to install PASEOS using Docker, access the desired repository and follow the provided instructions. 
 
 ## Examples
 
 The next examples will introduce you to the use of PASEOS.
 
+Comprehensive, self-contained examples can also be found in the `examples` folder where you can find an example on:
+
+* Modelling and analysing a large constellation with PASEOS
+* Modelling distributed learning on heterogeneous data in a constellation
+* Using PASEOS with MPI to run PASEOS on supercomputers
+* Using PASEOS to model the task of onboard satellite volcanic eruptions detection
+
+The following are small snippets on specific topics.
+
 ### Actors
 
 #### Create a PASEOS actor
@@ -277,6 +294,13 @@ Alternatively to the default `paseos.PowerDeviceType.SolarPanel` you can also us
 
 Note that at the moment only one power device is supported. Adding another will override the existing one.
 
+You can check the battery's state of charge and level in Ws with:
+
+```py
+print(my_actor.state_of_charge)
+print(my_actor.battery_level_in_Ws)
+```
+
 #### Thermal Modelling
 
 To model thermal constraints on spacecraft we utilize a model inspired by the one-node model described in [Martínez - Spacecraft Thermal Modelling and Test](http://imartinez.etsiae.upm.es/~isidoro/tc3/Spacecraft%20Thermal%20Modelling%20and%20Testing.pdf). Thus, we model the change in temperature as
@@ -393,7 +417,9 @@ For each actor you wish to model, you can create a PASEOS instance. Running mult
 
 #### Using the cfg
 
-When you instantiate PASEOS as shown in [Initializing PASEOS](#initializing-paseos), PASEOS instance is created by using the default configuration. However, sometimes it is useful to use a custom configuration. <br> The next code snippet will show how to start the PASEOS simulation with a time different from `pk.epoch(0)` by loading a custom configuration.
+When you instantiate PASEOS as shown in [Initializing PASEOS](#initializing-paseos), a PASEOS instance is created by using the default configuration. However, sometimes it is useful to use a custom configuration.
+
+The next code snippet will show how to start the PASEOS simulation with a time different from `pk.epoch(0)` (MJD2000) by loading a custom configuration.
 
 ```py
 import pykep as pk
@@ -430,6 +456,13 @@ cfg.sim.start_time=today.mjd2000 * pk.DAY2SEC
 sim = paseos.init_sim(local_actor)
 ```
 
+You can access the current simulation time (seconds since the start) and the current epoch like this:
+
+```py
+time_since_start_in_s = sim.simulation_time
+current_epoch = sim.local_time
+```
+
 #### Faster than real-time execution
 
 In some cases, you may be interested to simulate your spacecraft operating for an extended period. By default, PASEOS operates in real-time, thus this would take a lot of time. However, you can increase the rate of time passing (i.e. the spacecraft moving, power being charged / consumed etc.) using the `time_multiplier` parameter. Set it as follows when initializing PASEOS.
@@ -890,3 +923,15 @@ Created by $\Phi$[-lab@Sweden](https://www.ai.se/en/data-factory/f-lab-sweden).
 - Gabriele Meoni - gabriele.meoni at esa.int, gabriele.meoni at ai.se
 - Johan Östman - johan.ostman at ai.se
 - Vinutha Magal Shreenath - vinutha at ai.se
+
+## Reference
+
+If you have used `PASEOS`, please cite the following paper:
+```
+@article{gomez23paseos,
+  author = {Gómez, Pablo and Östman, Johan and Shreenath, Vinutha Magal and Meoni, Gabriele},
+  title = {{PA}seos {S}imulates the {E}nvironment for {O}perating multiple {S}pacecraft},
+  journal = {arXiv:2302.02659 [cs.DC]},
+  year = {2023},
+}
+```