Documentation Update

[hannahlanzrath]

Documentation To-Dos

• Add section explaining the Case + Options + Environment concept
• Highlight uniqueness and reproducibility of result directories
• Include explanation of reusing Options across multiple projects
• Document how to define reproducible environments with Conda/Pip
• Describe how to run cases in Docker/Podman containers
• Include instructions for setting up passt and its system requirements
• Replace deprecated method run_study() with the new method name across the documentation
• Expand upon general description and introduction
• Improve user readability by modifying documentation structure, 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
• Bibliography doesn't show up in readthedocs.io: Section "bibliography" should load references.bib but fails, thus website remains empty

---

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)

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.

[katharinapaul2403]

Follow-Up on 2. Environment: Reproducibility via Conda/Pip Packages

With every run of the project code, a new output branch with the results is created. At the same time, the main branch of the output repository tracks these runs in the "run_history" directory. Every branch has it's own sub-directory in the run_history directory. Within this branch, the following files are stored for every run:

• conda_environment.yml
• conda_independent_environment.yml
• metadata.json
• pip_independent_requirements.txt
• pip_requirements.txt

The conda_environment.yml shows the environment used for the run and also every single package contained in this environment with their respective version number. This includes conda and pip packages.

Does this solve the issue or does anything need to be implemented in RDM in addition to these run_history logs?