diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..320a0a4 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,24 @@ +# 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" + apt_packages: + - libsndfile1 + - libglu1-mesa + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + install: + - method: pip + path: ".[docs]" 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/includes/contributing.rst b/docs/source/includes/contributing.rst new file mode 100644 index 0000000..e75064b --- /dev/null +++ b/docs/source/includes/contributing.rst @@ -0,0 +1,13 @@ +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 + contributing/contribute_method.rst + contributing/configuring.rst \ No newline at end of file diff --git a/docs/source/includes/contributing/configuring.rst b/docs/source/includes/contributing/configuring.rst new file mode 100644 index 0000000..a6f35b7 --- /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 ``methods-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..7ea8a4f --- /dev/null +++ b/docs/source/includes/contributing/contribute_method.rst @@ -0,0 +1,269 @@ +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 ./ --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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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)) 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 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..ef1064d --- /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 = "" # ← 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}" + +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. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..2ba324d --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +CHORAS simulation-backend +========================= + +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 +via the same JSON file used for configuration. + +.. toctree:: + :maxdepth: 1 + :caption: Setup Instructions + + includes/setup.rst + +.. 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..286f1d6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,4 +5,39 @@ 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[tests,docs]"] + +[tool.setuptools] +# Explicitly declare that this distribution does not define top-level packages. +packages = [] \ No newline at end of file