From 38e5679ad36385a52fd87f56460269988fac6469 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Fri, 8 May 2026 19:58:59 +0200 Subject: [PATCH 01/14] Start adding documentation skeleton --- docs/.gitignore | 2 ++ docs/Makefile | 20 +++++++++++++ docs/make.bat | 35 ++++++++++++++++++++++ docs/source/conf.py | 67 +++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 16 +++++++++++ pyproject.toml | 38 +++++++++++++++++++++++- 6 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..015219a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +auto_examples/ +sg_execution_times.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..ef0e9bd --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,67 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "CHORAS simulation-backend" +copyright = "2026, The CHORAS developers" +author = "The CHORAS developers" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "myst_parser", + "sphinx_design", + "sphinx_copybutton", + 'sphinx_gallery.gen_gallery', +] +source_suffix = [".rst", ".md"] + +templates_path = ["_templates"] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "pydata_sphinx_theme" +html_static_path = ["_static"] +html_title = "CHORAS simulators" + +html_theme_options = { + "navbar_start": ["navbar-logo"], + "navbar_end": ["navbar-icon-links", "theme-switcher"], + "navbar_align": "left", + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/choras-org/simulation-backend", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + }, + ], + # Configure secondary (right) side bar + "show_toc_level": 3, # Show all subsections of notebooks + "secondary_sidebar_items": ["page-toc"], # Omit 'show source' link that that shows notebook in json format + "navigation_with_keys": True, + # Configure navigation depth for section navigation + "navigation_depth": 2, +} + +html_context = { + "default_mode": "light" +} + +# -- Gallery configuration ------------------------------------------------- +sphinx_gallery_conf = { + "examples_dirs": "../../examples", # path to your example scripts + "gallery_dirs": "auto_examples", # path to where to save gallery generated output + "image_scrapers": ("matplotlib",), +} \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..a220fc0 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,16 @@ +CHORAS simulation-backend +========================= + + +.. toctree:: + :maxdepth: 1 + :caption: Contribution Guidelines + + includes/contributing.rst + +.. toctree:: + :maxdepth: 1 + :caption: Examples + + auto_examples/index.rst + diff --git a/pyproject.toml b/pyproject.toml index c32c38c..6c57725 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,4 +5,40 @@ build-backend = "setuptools.build_meta" [project] name = "simulation_backend" version = "0.1.0" -description = "Simulation backend" \ No newline at end of file +requires-python = ">=3.10" +description = "Simulation backend" + +dependencies = [ + "gmsh", + "matplotlib", +] + +[project.optional-dependencies] + +tests = [ + "pytest", + "pytest-cov", + "watchdog", + "ruff", + "coverage", +] + +docs = [ + "sphinx", + "autodocsumm>=0.2.14", + "pydata-sphinx-theme", + "sphinx_mdinclude", + "sphinx-design", + "sphinx-favicon", + "sphinx-reredirects", + "myst-parser", + "sphinx-copybutton", + "sphinx-gallery", +] + +dev = ["simulation_backend[deploy,tests,docs]"] + +[tool.setuptools.packages] +# Turn off automatic package discovery, since we do not specify any packages in this project +# All code is implemented in the sub-packages +find = {namespaces = false} \ No newline at end of file From ca83d9f7502fec306d506dabc13278466186d68b Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Fri, 8 May 2026 20:07:53 +0200 Subject: [PATCH 02/14] Short explanation workflow logic --- docs/source/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index a220fc0..7680ea7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,6 +1,11 @@ CHORAS simulation-backend ========================= +The CHORAS simulation-backend contains all interfaces to simulation methods and softwares connected to CHORAS. +Each simulation method is implemented as a separate package with a command line interface (CLI), which is used by +the CHORAS backend to run simulations. Simulation configurations are defined via JSON files, which are created +by the CHORAS backend based on user input. After running a simulation, the results are passed back to the CHORAS backend +via the same JSON file used for configuration. .. toctree:: :maxdepth: 1 From 0edc7bf04b4373f94996b03febf7581a40266a8f Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Fri, 8 May 2026 23:26:05 +0200 Subject: [PATCH 03/14] Setup dev environment --- docs/source/includes/contributing.rst | 11 ++++ .../includes/contributing/setup_dev.rst | 50 +++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/source/includes/contributing.rst create mode 100644 docs/source/includes/contributing/setup_dev.rst diff --git a/docs/source/includes/contributing.rst b/docs/source/includes/contributing.rst new file mode 100644 index 0000000..c5f1863 --- /dev/null +++ b/docs/source/includes/contributing.rst @@ -0,0 +1,11 @@ +Contributing +============ + +This section provides guidelines for contributing a new simulation method to CHORAS. +The following steps will help you navigate the process. + + +.. toctree:: + :maxdepth: 1 + + contributing/setup_dev.rst \ No newline at end of file diff --git a/docs/source/includes/contributing/setup_dev.rst b/docs/source/includes/contributing/setup_dev.rst new file mode 100644 index 0000000..e3ab26e --- /dev/null +++ b/docs/source/includes/contributing/setup_dev.rst @@ -0,0 +1,50 @@ +Getting Started +=============== + +Ready to contribute? Here's how to set up your development environment for CHORAS. +We always recommend creating a `fork `_ of the repository you would like to contribute to. +This allows you to freely develop and test your changes without affecting the main repository until you're ready to submit a pull request. + +1. Fork the repository you want to contribute to (e.g., `choras/simulation-backend `_). Please make sure that you enable giving maintainers access to your fork, so we can help you if you run into issues. +2. Clone your forked main repository to your local machine: + + .. code-block:: bash + + git clone https://github.com//CHORAS + cd CHORAS + + If you only want to contribute to the frontend/backend, you can instead clone the original repository. + +3. Navigate into the CHORAS directory and initialize the three (``frontend-v2``, ``backend``, and ``simulation-backend``) submodules: + + .. code-block:: bash + + cd CHORAS + git submodule update --init --recursive + +4. Update the remote URL of the submodules to point to your forked repositories. For example, for the simulation-backend submodule: + + .. code-block:: bash + + cd simulation-backend + git remote set-url origin https://github.com//simulation-backend + + If you prefer to use SSH instead of HTTPS, the command would be: + + .. code-block:: bash + + git remote set-url origin git@github.com:/simulation-backend.git + +5. Optionally, you can also set up the upstream remote to keep your fork in sync with the original repository: + + .. code-block:: bash + + git remote add upstream https://github.com/choras/simulation-backend + +6. Finally, create a new branch for your changes: + + .. code-block:: bash + + git checkout -b my-feature-branch + +7. Now you're ready to start developing. Follow the instructions on the next page to start implementing an interface for your simulation method. \ No newline at end of file From 02d769c92b2292e5125dd395765aedc498cf17ec Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:42:42 +0200 Subject: [PATCH 04/14] Add copier template and configuration instructions for new methods --- docs/source/includes/contributing.rst | 3 +- .../includes/contributing/configuring.rst | 121 ++++++++ .../contributing/contribute_method.rst | 264 ++++++++++++++++++ 3 files changed, 387 insertions(+), 1 deletion(-) create mode 100644 docs/source/includes/contributing/configuring.rst create mode 100644 docs/source/includes/contributing/contribute_method.rst diff --git a/docs/source/includes/contributing.rst b/docs/source/includes/contributing.rst index c5f1863..614588f 100644 --- a/docs/source/includes/contributing.rst +++ b/docs/source/includes/contributing.rst @@ -8,4 +8,5 @@ The following steps will help you navigate the process. .. toctree:: :maxdepth: 1 - contributing/setup_dev.rst \ No newline at end of file + contributing/setup_dev.rst + contributing/contribute_method.rst diff --git a/docs/source/includes/contributing/configuring.rst b/docs/source/includes/contributing/configuring.rst new file mode 100644 index 0000000..60e5c95 --- /dev/null +++ b/docs/source/includes/contributing/configuring.rst @@ -0,0 +1,121 @@ +Integrating a new Method +====================== + +Add Example Settings +-------------------- + +Add a JSON file describing your method's adjustable parameters in ``example_settings/``. This will be used by the frontend to generate the UI for the method. Follow the format of ``mynewmethod_setting.json``. + +This file would have the following structure: + +- At the top level there would be an object with the two fields: + + - ``type``: Specified as ``"SimulationSettings"`` + - ``options``: Array of objects for settings options + +- Each object in that array describes one configurable parameter and uses the following fields: + + - ``name``: Human-readable label shown in the UI, e.g. ``"MyNewMethod parameter 1"`` + - ``id``: Internal identifier used in backend/frontend logic, e.g. ``"mnm_1"``. This must be unique per method. + - ``type``: Data type of the parameter value, e.g. ``"float"`` (other types can be added if the system supports them, such as ``"int"``, ``"bool"``, ``"string"``). + - ``display``: How this parameter is rendered in the UI, e.g. ``"text"`` for a text/number input field (could be other widgets if supported, such as sliders, dropdowns, etc.). + - ``min``: Minimum allowed value for numeric types. Used for validation and UI constraints. + - ``max``: Maximum allowed value for numeric types. Also used for validation and UI constraints. + - ``default``: Default value if the user does not provide one. Can be ``null`` if you want to force the user or backend to set it explicitly. + - ``step``: Increment used in the UI for numeric inputs (e.g. how much the value changes when the user uses arrow keys or a slider). + - ``endAdornment`` *(optional)*: Optional string shown next to the field in the UI, often for units (e.g. ``"dB"``, ``"m"``, ``"s"``). Empty string if not needed. + +Update Method Configuration +--------------------------- + +Update the file ``method-config.json`` in the ``simulation-backend`` directory with a new entry. + +This file lists all available simulation methods, so CHORAS can recognize yours. + +- ``simulationType``: The short name of the simulation acting as an identifier +- ``containerImage``: Name for the container image to be made +- ``envVars``: Dictionary of specific environment variables (if required) for Docker containers +- ``label``: Name of the method +- ``entryFile``: Python entry point to start execution +- ``setting``: Setting file name so that it can be loaded in frontend and backend +- ``repositoryURL``: Link to the original repository of the simulation method +- ``documentationURL``: Link to the documentation of the simulation method + +Update CHORAS +------------- + +Docker Image Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open the ``docker-compose.yml`` in the CHORAS root directory and add your method under ``services``: + +.. code-block:: yaml + + services: + # ... existing services ... + mynew-method: # ← Your method name (kept as service name) + platform: linux/amd64 # ← Keep unchanged + build: + context: ./simulation-backend # ← Keep unchanged + dockerfile: new_method/Dockerfile # ← Path to your Dockerfile + image: mynew_image:latest # ← EXACTLY match methods-config.json + profiles: + - sim_method # ← Keep unchanged + +Modify the Build Script +~~~~~~~~~~~~~~~~~~~~~~~ + +In the root directory, go to the ``CHORAS_BUILD.sh`` file and add the following commands based on your method before the ``docker compose up`` command: + +.. code-block:: bash + + # Export new method image for backend executor + echo "📦 Exporting MyNewMethod image..." + docker save -o backend/app/services/executors/mynew_image.tar mynew_image:latest + echo "✅ Docker image exported: mynew_image.tar" + +.. note:: + **Replace**: ``mynew_image.tar`` & ``mynew_image:latest`` with your actual image name. + +After this, delete the DB volume and all containers, and run the ``CHORAS_BUILD.sh`` bash command again. + +Debugging Execution +------------------- + +If a simulation fails (you see a **"Simulation Failed"** alert at the top of the screen), +you can inspect the underlying container logs. + +1. Open ``backend/app/services/executors/local_executor.py``. + +2. Locate the line that removes the container after execution (for example, a call that + stops or removes the container when it finishes): + + .. code-block:: python + + try: + client = docker.from_env() + container = client.containers.run( + image=image, + environment=env, # JSON_PATH is the container path, valid in child too + volumes={ + host_uploads_dir: { + "bind": container_uploads_dir, # same path in child container + "mode": "rw", + } + }, + detach=True, + working_dir=self.work_dir, + name=container_name, + # remove = True, # ← Comment This one + ) + return container + + except Exception as e: + logger.error(f"Failed to start Docker container: {e}") + raise + +3. Temporarily comment out that line so the container is not removed automatically. + +4. Rebuild the image and container. With the container kept alive after the simulation ends, you can open your container + runtime (e.g., Docker) and inspect the container logs to see detailed error messages + and tracebacks for the simulation method execution. diff --git a/docs/source/includes/contributing/contribute_method.rst b/docs/source/includes/contributing/contribute_method.rst new file mode 100644 index 0000000..0f9a0f6 --- /dev/null +++ b/docs/source/includes/contributing/contribute_method.rst @@ -0,0 +1,264 @@ +The Simulation Method Interface +=============================== + +Each simulation method interface in CHORAS is implemented in the format of a Python package which also specifies a command line interface (CLI) for running the method. + + +The CHORAS backend shares information and data with the simulation methods via JSON files. +When a simulation is scheduled, the backend writes a JSON file with all required configurations and input data. +The simulation method's interface executes the simulation based on the provided configuration and extends the same JSON +file with progress updates and finally the results, which are then read by the backend. + + +Creating the Scaffolding +------------------------ + +To simplify the process of adding a new method, we provide a template using the ``copier`` tool. +Copier allows you to generate a customized template based on input you provide. + +You can install copier with pip: + +.. code-block:: bash + + pip install copier + +Or with uv: + +.. code-block:: bash + + uv tool install copier + +From the ``simulation-backend`` directory, run: + +.. code-block:: bash + + copier copy https://github.com/choras-org/template_simulation_method ./ + +Questions for Customization +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Copier will ask you several questions to customize your interface. +These questions cover information about the author, the implemented method, and dependencies. + +.. note:: + The template always includes ``*.msh`` and ``*.geo`` files (named + ``test_room_.*``) and ``gmsh`` as a dependency. + Simply remove the ``.msh`` file if your method automatically generates + mesh files based on the geometry data defined in the ``*.geo`` file. + +**About gmsh initialization:** If your method requires ``gmsh.initialize()`` and +``gmsh.finalize()``, add them in your simulation method implementation (not in the CLI). +This keeps the CLI simple and allows better control over gmsh lifecycle. + +Example +~~~~~~~ + +.. code-block:: bash + + $ copier copy https://github.com/choras-org/template_simulation_method ./ + + 🎤 Author name + Your Name + 🎤 Author email + your.email@example.com + 🎤 What is the name of your simulation method (e.g., "DG", "DE", "Pyroomacoustics")? + MyMethod + 🎤 What is the lowercase (snake_case) version of your method name (used for package naming)? + mymethod + 🎤 Brief description of your simulation method + Python package for acoustic simulation using MyMethod + ... + +This will create a directory structure like: + +.. code-block:: text + + mymethod_method/ + ├── Dockerfile + ├── pyproject.toml + ├── mymethod_interface/ + │ ├── __init__.py + │ ├── __main__.py + │ ├── __cli__.py + │ ├── definition.py + │ └── mymethod_interface.py + └── tests/ + ├── conftest.py + ├── test_definition.py + ├── test_mymethod_cli.py + ├── test_fixtures.py + ├── test_input_mymethod.json + └── test_room_mymethod.geo + + +Next Steps After Generation +--------------------------- + +1. **Navigate to your new package:** + + .. code-block:: bash + + cd _method + +2. **Implement your simulation logic:** + Edit ``_interface/_interface.py`` and implement the + ``__method()`` function. + +3. **Update dependencies:** + Add any specific dependencies your method needs to ``pyproject.toml``. + +4. **Update test data:** + Modify the test JSON file in ``tests/test_input_.json`` to match your + method's expected input structure. + +5. **Add specific tests:** + Update the CLI test in ``tests/test__cli.py`` with assertions specific to + your method. + +6. **Install and test:** + + .. code-block:: bash + + pip install -e . + pytest tests/ + +7. **Build Docker image:** + + .. code-block:: bash + + docker build -t _method . --platform linux/amd64 + + +Dependencies +~~~~~~~~~~~~ + +- Include your method's dependencies with **explicit version numbers**. +- Prefer libraries that are installable via pip +- If your package is only hosted in a git repository, you can install it using: + + .. code-block:: shell + + "package_name @ git+https://gitprovider.com/user/project.git@{version}" + + If your package does not have a version number, you can use the commit hash: + + .. code-block:: shell + + "package_name @ git+https://gitprovider.com/user/project.git@{commit_hash}" + +Refer to the `Python Packaging Authority guide `_ for more options. + +**Note that providing a specific version number (or hash) is important** to ensure reproducibility (and stability) of the results and CHORAS as a platform. If your method is not yet installable via pip, please refer to `packaging guidelines `_ provided by the Python Packaging Authority. + +Structure Explanation +~~~~~~~~~~~~~~~~~~~~~ + +- ``definition.py``: Contains the ``SimulationMethod`` abstract base class. + + - Specifies the required methods for any simulation method implementation. + - Checks for None/empty paths and file existence. + - Provides a standardized way to export results to the backend and database. + +- ``_interface.py``: Your main implementation file + + - Implements the simulation logic into the standardized interface defined by ``SimulationMethod``. +- ``__init__.py``: Exports the main class and CLI entry point +- ``__main__.py``: Allows running as a module (``python -m ``) +- ``__cli__.py``: CLI implementation that reads ``JSON_PATH`` env variable +- ``tests/``: Contains tests for your method + + - ``test_definition.py``: Tests the base class + - ``test__cli.py``: Tests the CLI with mocks + - ``test_fixtures.py``: Tests fixture functionality + - ``conftest.py``: Shared fixtures for all tests + + +Customization Tips +------------------ + +Mesh Files +~~~~~~~~~~ + +The template includes ``.msh`` and ``.geo`` files by default. To remove them: + +1. Delete ``tests/test_room_*.msh`` and ``tests/test_room_*.geo`` +2. Remove ``gmsh`` from ``pyproject.toml`` dependencies +3. Remove ``gmsh`` from ``Dockerfile`` +4. Update ``tests/conftest.py`` to not copy these files +5. Update ``tests/test_input_*.json`` to remove ``geo_path`` and ``msh_path`` + +Gmsh Initialization +~~~~~~~~~~~~~~~~~~~ + +Gmsh requires explicit initialization and finalization. +Try to keep gmsh-related code as compact as possible and make sure that ``gmsh.finalize()`` is always called, even if errors occur. + +This can for example be achieved by wrapping corresponding code in a try-finally block: + +.. code-block:: python + + def run_simulation(self) -> None: + """Run the simulation.""" + import gmsh + + gmsh.initialize() + try: + self._mymethod_method(self.input_json_path) + finally: + gmsh.finalize() + +This approach: + +- Allows better control over gmsh lifecycle +- Makes it easier to test without gmsh + +Adding Custom Simulation Settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Edit the test JSON template to include your method-specific settings in the +``simulationSettings`` section: + +.. code-block:: json + + "simulationSettings": { + "your_setting_1": value1, + "your_setting_2": value2 + } + + +Common Patterns +--------------- + +Reading Input Data +~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + with open(json_file_path, "r") as json_file: + result_container = json.load(json_file) + +Extracting Source/Receiver Positions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + + source_coords = [ + result_container["results"][0]["sourceX"], + result_container["results"][0]["sourceY"], + result_container["results"][0]["sourceZ"], + ] + receiver_coords = [ + result_container["results"][0]["responses"][0]["x"], + result_container["results"][0]["responses"][0]["y"], + result_container["results"][0]["responses"][0]["z"], + ] + +Writing Results +~~~~~~~~~~~~~~~ + +.. code-block:: python + + result_container["results"][0]["responses"][0]["receiverResults"] = results.tolist() + + with open(json_file_path, "w") as json_output: + json_output.write(json.dumps(result_container, indent=4)) From db38a2abe2c952116f80e5a5e3cc376e5f812e75 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:48:16 +0200 Subject: [PATCH 05/14] setup instructions for users and contributors --- docs/source/includes/setup.rst | 8 ++ .../includes/setup/required_software.rst | 35 ++++++ docs/source/includes/setup/setup_user.rst | 116 ++++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 docs/source/includes/setup.rst create mode 100644 docs/source/includes/setup/required_software.rst create mode 100644 docs/source/includes/setup/setup_user.rst diff --git a/docs/source/includes/setup.rst b/docs/source/includes/setup.rst new file mode 100644 index 0000000..f344cfe --- /dev/null +++ b/docs/source/includes/setup.rst @@ -0,0 +1,8 @@ +Setup +===== + +.. toctree:: + :maxdepth: 1 + + setup/required_software.rst + setup/setup_user.rst diff --git a/docs/source/includes/setup/required_software.rst b/docs/source/includes/setup/required_software.rst new file mode 100644 index 0000000..0389aea --- /dev/null +++ b/docs/source/includes/setup/required_software.rst @@ -0,0 +1,35 @@ +Required Software +================= + +To run CHORAS, you need to have the following software installed on your machine: + +- git +- Docker Desktop (with WSL 2 backend for Windows users) + + +Git Installation +---------------- + +Install the latest version of Git from: +`https://git-scm.com/downloads `_ + +Follow the installer's default settings. + + +Docker Setup +------------ + +.. warning:: + If you're on Windows and unsure whether you need ``amd64`` or ``arm64``, + go to **Settings -> System -> About**. It will say *"x64-based processor"* + for AMD, or *"ARM-based processor"* for an ARM chip. + +1. Install Docker using the default settings. +2. Open **Docker Desktop** (the application must be running for CHORAS to work). +3. When prompted to sign in/up, click **Continue without signing up** or **Skip**. +4. If Docker Desktop tells you that WSL needs updating, click **Restart**. + If this doesn't work, open your terminal and run: + + .. code-block:: bash + + wsl --update diff --git a/docs/source/includes/setup/setup_user.rst b/docs/source/includes/setup/setup_user.rst new file mode 100644 index 0000000..2a36120 --- /dev/null +++ b/docs/source/includes/setup/setup_user.rst @@ -0,0 +1,116 @@ +Get Started using CHORAS +======================== + +In your terminal: + +.. code-block:: bash + + git clone + cd CHORAS + +This repository includes three submodules: + +- ``frontend-v2`` +- ``backend`` +- ``simulation-backend`` + +If you only want to use the Docker setup (recommended for running CHORAS locally), you do not need to touch these submodules manually. In that case, just follow the Docker-based instructions. + +If you want to: + +- Explore the underlying code, or +- Run simulations on the cloud + +then initialize the submodules: + +.. code-block:: bash + + git submodule update --init --recursive + +Cloud Connection Setup +====================== + +.. note:: + This step is only required if you want to offload heavy simulations to HPC clusters (e.g., SURF Cloud). + You can skip this section if you do not have cloud access yet. If you gain access later, come back and complete these steps. + +SSH Key Setup +------------- + +Generate and configure an SSH key on your machine following the GitHub guide: +`Generating a new SSH key and adding it to the ssh-agent `_ + +In the root directory of the CHORAS repository, open ``docker-compose.yml``. +Add the path to your local SSH key directory in volumes of backend: + +.. code-block:: yaml + + platform: linux/amd64 + build: + context: . # root of CHORAS + dockerfile: backend/Dockerfile + ports: + - "5001:5001" + env_file: + - .env.api + depends_on: + - db_service + - redis + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./uploads:/app/uploads + - ./simulation-backend:/app/simulation-backend + - .ssh:/root/.ssh:ro # Add this line + +Cloud Configuration Variables +------------------------------ + +After SSH is configured and you receive your cloud access details (IP address, username, etc.): + +1. Go to the backend submodule: + + .. code-block:: bash + + cd backend + +2. Open ``config.py`` and update the ``CloudConfig`` class at the end of the file: + + .. code-block:: python + + class CloudConfig: + """ + Cloud Configuration + """ + CLOUD_EXECUTOR_HOST = "145.38.205.131" # ← Update with your cloud IP + CLOUD_EXECUTOR_USER = "smondal" # ← Update with your username + CLOUD_EXECUTOR_KEY_PATH = f"{Path.home()}/.ssh/id_ed25519" + CLOUD_EXECUTOR_DIRECTORY = f"/data/storage/{CLOUD_EXECUTOR_USER}" + +3. In the ``CloudConfig`` class, update: + + - The **IP address** of the cloud + - The **username** + + with the values provided by your cloud/HPC provider (e.g., SURF). + +.. note:: + For Cloud/HPC, ``Singularity`` should be installed on it. + +Running CHORAS +============== + +From the root directory of the CHORAS repository: + +1. Make sure **Docker Desktop** is running. +2. In a terminal, run: + + .. code-block:: bash + + ./CHORAS_BUILD.sh + + This script builds and starts all required containers. + +3. Once the build completes, open your browser and go to: + `http://localhost:5173/ `_ + +You should now see the CHORAS user interface. From 5cefb0567892efae109ab2a51a6c9d94386e4e40 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:48:34 +0200 Subject: [PATCH 06/14] Add missing file in toc --- docs/source/includes/contributing.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/includes/contributing.rst b/docs/source/includes/contributing.rst index 614588f..e75064b 100644 --- a/docs/source/includes/contributing.rst +++ b/docs/source/includes/contributing.rst @@ -10,3 +10,4 @@ The following steps will help you navigate the process. contributing/setup_dev.rst contributing/contribute_method.rst + contributing/configuring.rst \ No newline at end of file From 6fcc82ed0a7ce802fa20ee69d9245a0299a467ea Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:49:00 +0200 Subject: [PATCH 07/14] Add readthedocs configuration --- .readthedocs.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..a38d9c4 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,11 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version, and other tools you might need +build: + os: ubuntu-24.04 + tools: + python: "3.12" \ No newline at end of file From 43f8520078ce439f8931dbcee73e594fdbbf3679 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:53:20 +0200 Subject: [PATCH 08/14] Set up installation via docs dependencies in pyproject.toml --- .readthedocs.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index a38d9c4..7c043e2 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,4 +8,14 @@ version: 2 build: os: ubuntu-24.04 tools: - python: "3.12" \ No newline at end of file + python: "3.12" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + install: + - method: pip + path: ".[docs]" From add336be489f4206739f82c14ea0911d47346864 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:55:44 +0200 Subject: [PATCH 09/14] Fix wrong path to sphinx configuration file in readthedocs configuration --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 7c043e2..9b2e5c1 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -12,7 +12,7 @@ build: # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: docs/conf.py + configuration: docs/source/conf.py # Optionally set the version of Python and requirements required to build your docs python: From 19ff71fe00591ccab533f5095041040a32f03e48 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 00:58:02 +0200 Subject: [PATCH 10/14] Add missing apt dependencies --- .readthedocs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 9b2e5c1..320a0a4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -9,6 +9,9 @@ build: os: ubuntu-24.04 tools: python: "3.12" + apt_packages: + - libsndfile1 + - libglu1-mesa # Build documentation in the docs/ directory with Sphinx sphinx: From 24424408874d97c8194cd31fb1ce69fbf104376b Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 01:01:13 +0200 Subject: [PATCH 11/14] Add setup instructions for users --- docs/source/index.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index 7680ea7..80247fa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,12 @@ the CHORAS backend to run simulations. Simulation configurations are defined via by the CHORAS backend based on user input. After running a simulation, the results are passed back to the CHORAS backend via the same JSON file used for configuration. +.. toctree:: + :maxdepth: 1 + :caption: Setup Instructions + + includes/setup.rst + .. toctree:: :maxdepth: 1 :caption: Contribution Guidelines From e7449d5ea8e9aa330582b6ca6e2566ed936c7d89 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 08:25:22 +0200 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/source/includes/contributing/configuring.rst | 14 +++++++------- docs/source/includes/setup/setup_user.rst | 6 +++--- docs/source/index.rst | 2 +- pyproject.toml | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/source/includes/contributing/configuring.rst b/docs/source/includes/contributing/configuring.rst index 60e5c95..a6f35b7 100644 --- a/docs/source/includes/contributing/configuring.rst +++ b/docs/source/includes/contributing/configuring.rst @@ -1,5 +1,5 @@ Integrating a new Method -====================== +======================== Add Example Settings -------------------- @@ -28,7 +28,7 @@ This file would have the following structure: Update Method Configuration --------------------------- -Update the file ``method-config.json`` in the ``simulation-backend`` directory with a new entry. +Update the file ``methods-config.json`` in the ``simulation-backend`` directory with a new entry. This file lists all available simulation methods, so CHORAS can recognize yours. @@ -52,15 +52,15 @@ Open the ``docker-compose.yml`` in the CHORAS root directory and add your method .. code-block:: yaml services: - # ... existing services ... - mynew-method: # ← Your method name (kept as service name) + # ... existing services ... + mynew-method: # ← Your method name (kept as service name) platform: linux/amd64 # ← Keep unchanged build: - context: ./simulation-backend # ← Keep unchanged - dockerfile: new_method/Dockerfile # ← Path to your Dockerfile + context: ./simulation-backend # ← Keep unchanged + dockerfile: new_method/Dockerfile # ← Path to your Dockerfile image: mynew_image:latest # ← EXACTLY match methods-config.json profiles: - - sim_method # ← Keep unchanged + - sim_method # ← Keep unchanged Modify the Build Script ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/includes/setup/setup_user.rst b/docs/source/includes/setup/setup_user.rst index 2a36120..ef1064d 100644 --- a/docs/source/includes/setup/setup_user.rst +++ b/docs/source/includes/setup/setup_user.rst @@ -60,7 +60,7 @@ Add the path to your local SSH key directory in volumes of backend: - /var/run/docker.sock:/var/run/docker.sock - ./uploads:/app/uploads - ./simulation-backend:/app/simulation-backend - - .ssh:/root/.ssh:ro # Add this line + - /.ssh:/root/.ssh:ro # Add this line Cloud Configuration Variables ------------------------------ @@ -81,8 +81,8 @@ After SSH is configured and you receive your cloud access details (IP address, u """ Cloud Configuration """ - CLOUD_EXECUTOR_HOST = "145.38.205.131" # ← Update with your cloud IP - CLOUD_EXECUTOR_USER = "smondal" # ← Update with your username + CLOUD_EXECUTOR_HOST = "" # ← Update with your cloud IP + CLOUD_EXECUTOR_USER = "" # ← Update with your username CLOUD_EXECUTOR_KEY_PATH = f"{Path.home()}/.ssh/id_ed25519" CLOUD_EXECUTOR_DIRECTORY = f"/data/storage/{CLOUD_EXECUTOR_USER}" diff --git a/docs/source/index.rst b/docs/source/index.rst index 80247fa..2ba324d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,7 @@ CHORAS simulation-backend ========================= -The CHORAS simulation-backend contains all interfaces to simulation methods and softwares connected to CHORAS. +The CHORAS simulation-backend contains all interfaces to simulation methods and software connected to CHORAS. Each simulation method is implemented as a separate package with a command line interface (CLI), which is used by the CHORAS backend to run simulations. Simulation configurations are defined via JSON files, which are created by the CHORAS backend based on user input. After running a simulation, the results are passed back to the CHORAS backend diff --git a/pyproject.toml b/pyproject.toml index 6c57725..6e7e350 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,7 +36,7 @@ docs = [ "sphinx-gallery", ] -dev = ["simulation_backend[deploy,tests,docs]"] +dev = ["simulation_backend[tests,docs]"] [tool.setuptools.packages] # Turn off automatic package discovery, since we do not specify any packages in this project From 88e0712cdeeee3d72cd3e966dcf820aa722f7bea Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 09:09:12 +0200 Subject: [PATCH 13/14] Manually define an empty package in the top level pyproject..toml --- pyproject.toml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 6e7e350..286f1d6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,7 +38,6 @@ docs = [ dev = ["simulation_backend[tests,docs]"] -[tool.setuptools.packages] -# Turn off automatic package discovery, since we do not specify any packages in this project -# All code is implemented in the sub-packages -find = {namespaces = false} \ No newline at end of file +[tool.setuptools] +# Explicitly declare that this distribution does not define top-level packages. +packages = [] \ No newline at end of file From e0d537277e08a932c14d8dd4f1c26ecb8b8b1c96 Mon Sep 17 00:00:00 2001 From: Marco Berzborn Date: Sat, 9 May 2026 09:19:35 +0200 Subject: [PATCH 14/14] Clarify copier command (add --trust flag) --- docs/source/includes/contributing/contribute_method.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/includes/contributing/contribute_method.rst b/docs/source/includes/contributing/contribute_method.rst index 0f9a0f6..7ea8a4f 100644 --- a/docs/source/includes/contributing/contribute_method.rst +++ b/docs/source/includes/contributing/contribute_method.rst @@ -32,7 +32,12 @@ From the ``simulation-backend`` directory, run: .. code-block:: bash - copier copy https://github.com/choras-org/template_simulation_method ./ + copier copy https://github.com/choras-org/template_simulation_method ./ --trust + +Note that the ``--trust`` flag is required. No code will be executed except for printing additional instructions. + +.. warning:: + Make sure to run the above command from the ``simulation-backend`` directory or that you point the output path correctly, otherwise the generated files will be created in the wrong location. Questions for Customization ~~~~~~~~~~~~~~~~~~~~~~~~~~~