probabilistic generative model of conjunctions

.github/workflows/build.yml

@@ -1,5 +1,10 @@
 name: build
 
+env:
+  # Use the same ssh-agent socket value across all jobs
+  # Useful when a GH action is using SSH behind-the-scenes
+  SSH_AUTH_SOCK: /tmp/ssh_agent.sock
+
 on:
   push:
     branches: [ master ]
@@ -12,21 +17,36 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@master
-    - name: Set up Python 3.7
+    - name: Checkout repository
+      uses: actions/checkout@v3
+    - name: Set up Python 3.9
       uses: actions/setup-python@master
       with:
-        python-version: 3.7
+        python-version: 3.9
     - name: Install
       run: |
         python -m pip install --upgrade pip
-        pip install torch==1.7.1+cpu torchvision==0.8.2+cpu torchaudio==0.7.2 -f https://download.pytorch.org/whl/torch_stable.html
+        pip install matplotlib
+        pip install jupyter
+        pip install numpy
+        pip install torch==1.11.0+cpu torchvision==0.12.0+cpu torchaudio==0.11.0+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html
         pip install .[dev]
+        pip install sphinx
+        pip install sphinx-book-theme
+        pip install myst-nb
+        cd docs
+        make html linkcheck    
     - name: Test
       run: |
-        sh tests/run_basics.sh
+        coverage run -m pytest
+        coverage xml
     - name: Codecov
-      uses: codecov/codecov-action@v2
+      uses: codecov/codecov-action@v3
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         verbose: true
+    - name: Upload to github pages 🚀
+      if: ${{ github.event_name == 'push' }}
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: docs/_build/html # The folder the action should deploy.

docs/Makefile

@@ -3,10 +3,10 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -WT --keep-going
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/api.rst

@@ -0,0 +1,19 @@
+.. _api:
+
+API
+#########
+
+Kessler API
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Documentation
+
+   _autosummary/kessler.cdm
+   _autosummary/kessler.data
+   _autosummary/kessler.event
+   _autosummary/kessler.model
+   _autosummary/kessler.nn
+   _autosummary/kessler.observation_model
+   _autosummary/kessler.plot
+   _autosummary/kessler.util

docs/source/capabilities.ipynb → docs/capabilities.ipynb

@@ -2,16 +2,11 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "id": "b8ca3794",
    "metadata": {},
    "source": [
-    "# Capabilities"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Overview\n",
+    "# Capabilities\n",
+    "\n",
     "Kessler is an open-source Python package that currently includes Bayesian ML and probabilistic programming components. The library currently provides the following key capabiolities:\n",
     "\n",
     "\n",
@@ -28,7 +23,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -42,9 +37,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.9"
+   "version": "3.8.15"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 4
+ "nbformat_minor": 5
 }

docs/conf.py

@@ -0,0 +1,110 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+project = 'Kessler'
+copyright = "2020, 2021, 2022, 2023, 2024, 2025, Kessler contributors"
+author = 'Giacomo Acciarini, Atılım Güneş Baydin, Francesco Pinto'
+
+
+# The full version, including alpha/beta/rc tags
+import kessler
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../'))  # Add the root directory of your repo
+
+release = kessler.__version__
+
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["myst_nb", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.autosummary","sphinx.ext.napoleon"]
+
+
+# build the templated autosummary files
+autosummary_generate = True
+autosummary_imported_members = False
+napoleon_google_docstring = True
+numpydoc_show_class_members = False
+panels_add_bootstrap_css = False
+
+autosectionlabel_prefix_document = True
+
+# katex options
+#
+#
+katex_prerender = True
+
+napoleon_use_ivar = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+}
+
+
+autoclass_content = 'both'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", ".DS_Store",'jupyter_execute/**/*.ipynb','jupyter_execute/*.ipynb']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_logo = "_static/kessler_logo.png"
+
+html_theme_options = {
+    "repository_url": "https://github.com/kesslerlib/kessler/",
+    "repository_branch": "master",
+    "path_to_docs": "docs",
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "launch_buttons": {
+        "binderhub_url": "https://mybinder.org",
+        "notebook_interface": "jupyterlab"
+    },
+    "navigation_with_keys": False,
+}
+
+nb_execution_mode = "force"
+
+nb_execution_excludepatterns = ['basics.ipynb','cdms_analysis_and_plotting.ipynb','LSTM_training.ipynb']
+#autosummary_ignore_module = ['']
+
+latex_engine = "xelatex"
+
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+]

docs/source/credits.ipynb → docs/credits.ipynb

@@ -2,30 +2,26 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "stainless-bracket",
+   "id": "96b808b8",
    "metadata": {},
    "source": [
-    "# Credits\n"
+    "# Credits\n",
+    "\n",
+    "Kessler was initially developed by the Constellations team at the [Frontier Development Lab](https://frontierdevelopmentlab.org/) (FDL) Europe 2020, a public-private partnership between the European Space Agency (ESA), Trillium Technologies, and University of Oxford.\n",
+    "\n",
+    "The main developers are: Giacomo Acciarini ( giacomo.acciarini@gmail.com ), Francesco Pinto, Atılım Güneş Baydin.\n"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "monetary-albuquerque",
+   "id": "e36830ab",
    "metadata": {},
-   "source": [
-    "Kessler was initially developed by the Constellations team at the [Frontier Development Lab](https://frontierdevelopmentlab.org/) (FDL) Europe 2020, a public-private partnership between the European Space Agency (ESA), Trillium Technologies, and University of Oxford.\n",
-    "\n",
-    "\n",
-    "Constellations team members: Giacomo Acciarini (University of Oxford), Francesco Pinto (University of Oxford), Sascha Metz (TU Darmstadt), Sarah Boufelja (IBM), Sylvester Kaczmarek (Imperial College London), Klaus Merz (European Space Agency), José A. Martinez-Heras (European Space Agency), Francesca Letizia (European Space Agency), Christopher Bridges (University of Surrey), Atılım Güneş Baydin (University of Oxford).\n",
-    "\n",
-    "The main developers are: Giacomo Acciarini ( giacomo.acciarini@gmail.com ), Francesco Pinto ( francesco1.pinto@gmail.com ), Atılım Güneş Baydin ( gunes@robots.ox.ac.uk ).\n",
-    "\n"
-   ]
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -39,7 +35,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.9"
+   "version": "3.8.15"
   }
  },
  "nbformat": 4,

docs/source/index.rst → docs/index.md

@@ -5,37 +5,37 @@ Kessler is a Python package for machine learning applied to spacecraft collision
 
 The package comprises a Deep Learning module, where a Bayesian recurrent neural network can be trained with existing collections of CDM data and then deployed in order to predict the contents of future CDMs received up to now, with associated uncertainty estimates about all predictions.
 
-Kessler also includes a novel generative model of conjunction events and CDM sequences implemented using probabilistic programming and simulating the CDM generation process, which we will soon release to the public: stay tuned!
+Kessler also includes a novel generative model of conjunction events and CDM sequences implemented using probabilistic programming and simulating the CDM generation process.
 
-The documentation is currently a work in progress.
+For more details on the model and results, check out our publications listed in the README of the repository. 
+
+The authors are [Giacomo Acciarini](https://www.esa.int/gsp/ACT/team/giacomo_acciarini/), [Atılım Güneş Baydin](https://gbaydin.github.io/), [Dario Izzo](https://www.esa.int/gsp/ACT/team/dario_izzo/). The main developer is Giacomo Acciarini (giacomo.acciarini@gmail.com).
 
-.. toctree::
    :maxdepth: 1
    :caption: Getting started
 
-   install
+   install.rst
    capabilities
    credits
 
 
-.. toctree::
    :maxdepth: 1
    :caption: Tutorials
 
-   tutorials/basics
-   tutorials/cdms_analysis_and_plotting
-   tutorials/LSTM_training
-   tutorials/probabilistic_programming_module
+   notebooks/basics
+   notebooks/cdms_analysis_and_plotting
+   notebooks/LSTM_training
+   notebooks/probabilistic_programming_module
 
 
-.. toctree::
    :maxdepth: 1
    :caption: API documentation
 
-   kessler package <_autosummary/kessler>
+   api
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
+

docs/install.rst

@@ -0,0 +1,53 @@
+Installation
+============
+
+.. _installation_deps:
+
+
+Packages
+--------
+
+
+pip
+^^^
+
+`kessler` is available on [Pypi](https://pypi.org/project/kessler/). You can install it via `pip` as:
+
+.. code-block:: console
+
+   $ pip install kessler
+
+Installation from source
+------------------------
+
+
+Using ``git``:
+
+.. code-block:: console
+
+   $ git clone https://github.com/kesslerlib/kessler
+   $ cd kessler
+   $ pip install -e .
+
+We follow the usual PR-based development workflow, thus kessler's ``master``
+branch is normally kept in a working state.
+
+Verifying the installation
+--------------------------
+
+You can verify that dSGP4 was successfully compiled and
+installed by running the tests. To do so, you must first install the
+optional dependencies.
+
+.. code-block:: bash
+
+   $ pytest
+
+If this command executes without any error, then
+your kessler installation is ready for use.
+
+Getting help
+------------
+
+If you run into troubles installing kessler, please do not hesitate
+to contact us by opening an issue report on `github <https://github.com/kesslerlib/kessler/issues>`__.