Documentation Update #80

Documentation To-Dos

• Add section explaining the Case + Options + Environment concept (Update documentation for v1.2.0 and document cases #146, new page Cases)
• Highlight uniqueness and reproducibility of result directories (Update documentation for v1.2.0 and document cases #146)
• Include explanation of reusing Options across multiple projects (Update documentation for v1.2.0 and document cases #146)
• Document how to define reproducible environments with Conda/Pip (Update documentation for v1.2.0 and document cases #146)
• Describe how to run cases in Docker/Podman containers (obsolete, the container adapters are removed in Remove container adapters and Dockerfile template #132)
• Include instructions for setting up passt and its system requirements (obsolete, see Remove container adapters and Dockerfile template #132)
• Replace deprecated method run_study() with the new method name across the documentation (not applicable: run_study() has not been renamed, so the docs use the current name)
• Expand upon general description and introduction (README rewrite, introduction updated in Update documentation for v1.2.0 and document cases #146)
• Improve user readability by modifying documentation structure (getting-started now covers adding remotes, rdm check and rdm push), e.g: getting-started.md explains creating remote repositories but not how to add remotes rdm remote set-url/ add, how to stage changes rdm check or how to push to remotes rdm push
• loading results from another repository into the target_project (using the CLI) is not implemented yet: load results based on the rdm-cache.json (available as rdm data fetch and documented)
• Bibliography doesn't show up in readthedocs.io: Section "bibliography" should load references.bib but fails, thus website remains empty (renders in the Sphinx build; the Read the Docs build is fixed in Install Read the Docs environment with Miniforge #136)

1. Unique Results from [Project + Options + Environment] and Reusability of Options

The documentation should explain that a combination of a specific Project, configuration Options, and runtime Environment defines a unique and reproducible run. This combination determines how results are stored and reloaded, and ensures consistency in comparisons and reruns.

Additionally, Options objects can be reused across different projects or used to define multiple configurations within a single project. This is essential for parameter sweeps or comparative studies and avoids redundant configuration code.

Internally, each Options instance is hashed to determine whether identical results already exist. Keys starting with an underscore (_) or containing double underscores (__) are excluded from the hash computation. This allows non-functional configuration (e.g., cache directories) to be specified without affecting result identity.

env = Environment(conda_packages={"cadet": ">5.0.3"}, pip_packages={"numpy": "2.0.2"})
options = Options({
            'objective': 'single-objective',
            'optimizer_options': DEFAULT_UNSGA_OPTIMIZER_OPTIONS,
            'debug': debug,
            'push': push,
        })
project_repo = ProjectRepo(path=study_root / name, url=study_url, branch=study_branch)
case = Case(project_repo=project_repo, options=options, environment=env)
case.run_study()  # notiz jetzt: sollte umbenannt werden weil wir Study deprecated haben.
assert case.has_results_for_this_run
case.load()
path = case.results_path

References:

• test_batch_runner.py
• diss_runner/run_all.py (Jugit repo, ask Jo)

2. Environment: Reproducibility via Conda/Pip Packages

The Environment object defines the runtime environment using Conda and/or Pip dependencies. This should be documented as a core part of each case setup to ensure results are reproducible and consistent across systems and collaborators.

Example:

env = Environment(
    conda_packages={"cadet": ">5.0.3"},
    pip_packages={"numpy": "2.0.2"}
)

3. Containerization Support (Docker/Podman)

Obsolete: the container adapters are removed in #132.

The documentation should include how to run a case inside a container, either Docker or Podman. This includes:

• The integration of the Case system with container execution
• The requirement for passt to enable container networking
• Platform-specific notes for setting up and exposing passt in the system environment

For Podman to work correctly, passt must be installed and accessible via the system PATH. This will require administrative setup on shared infrastructure, such as the IBT servers (ask Martin).

Example to ensure passt is in PATH:

os.environ["PATH"] += os.pathsep + "/home/bin/passt"

Reference test files:
- `test_container_docker.py`
- `test_container_podman.py`

4. Method naming update

The method run_study() used in the Case object is deprecated and will be renamed. All examples and documentation referencing it should be updated once the new name is finalized.