Installation

Bedroc is a Python package that can be installed on a variety of platforms (e.g. Mac, Windows, Linux).

Python environment

It is recommended to install Bedroc in a virtual environment, whether you proceed with a quick install or a full developer setup. This helps isolate dependencies and maintain reproducibility.

For more information, see the Python documentation on venv.

We recommend using a modern dependency manager such as uv, which offers fast installs and reproducible environments by default (See section ‘2b. Install Bedroc’ below).

1. Quick install

Use pip:

pip install bedroc

Downloading the source code is also recommended if you’d like access to the example notebooks in notebooks/.

2. Developer install

2a. Fork and clone the repository

If you plan to contribute to Bedroc or want to work independently, it’s recommended to first fork the repository to your personal account or to an organisation you belong to. This gives you full control over your changes and the ability to manage your own branches.

Follow these steps:

Visit the main repository on GitHub: https://github.com/ExPlanetology/Bedroc
Click the Fork button (usually in the top-right corner of the page).
Choose whether to fork the repository to your personal account or to an organisation account.

After forking the repository, you should clone your fork (not the original) to begin development.

Cloning your fork:

Using SSH:

git clone git@github.com:<your-account>/Bedroc.git
cd Bedroc

Using HTTPS:

git clone https://github.com/<your-account>/Bedroc.git
cd Bedroc

Replace <your-account> with your actual GitHub username or organisation name. You can now work on your fork independently, create branches, and make changes as needed.

To keep your fork in sync with the original repository—or to submit changes via pull requests—you can follow the instructions in the GitHub documentation on configuring a remote upstream. This setup allows you to fetch updates from the main repository and integrate them into your fork.

To reduce the complexity of future merges, it is strongly recommended to keep your fork’s main branch closely aligned with the upstream repository. Avoid letting your fork diverge significantly. Submit bug fix pull requests as soon as possible. New features can be submitted at any time, as long as they are self-contained and do not break any existing infrastructure. This strategy helps ensure a smoother integration process and minimises maintenance burdens.

Note

You can also clone the main repository directly without forking, but this approach provides less flexibility and does not allow you to submit pull requests unless you have write access to the main repository.

2b. Install Bedroc

To install the package, you may use a Python project/package manager such as uv, poetry, or the standard pip tool. These tools manage dependencies using the project’s pyproject.toml file.

Recommended: use uv or poetry or similar for reproducible and locked environments. Alternatively, pip can be used for simpler workflows.

Option 1: uv (recommended)

This requires uv to be installed.

In the directory of the source code repository (where pyproject.toml is located), run:

uv sync

uv will create a virtual environment in a .venv directory inside the source repository and install the package along with its development tools and dependencies.

To activate the virtual environment the command is different depending on your operating system:

Mac/Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\Activate.ps1

For all operating systems you can deactivate (exit) the virtual environment by running:

deactivate

Optional extras:

To install documentation dependencies only:
```
uv sync --extra docs
```
To install everything (core + dev + docs):
```
uv sync --extra docs
```

Note

If you’re using VS Code, you may need to restart the editor for the virtual environment to be detected automatically. In some cases, additional configuration may be required—see the official guidance.

As a fallback, prefixing any command with uv will ensure it runs in the local (uv-created) environment, even if the virtual environment is not activated manually.

Option 2: pip

Create a virtual environment (if you haven’t already), typically at the uppermost level of the source code repository. Make sure that the Python version used is compatible with Bedroc’s requirements:

python -m venv .venv

To activate the virtual environment the command is different depending on your operating system:

Mac/Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\Activate.ps1

You may use the -e option for an editable install:

pip install -e .

To install additional dependencies:

For development tools:
```
pip install -e .[dev]
```
For documentation tools:
```
pip install -e .[docs]
```
For both:
```
pip install -e .[dev,docs]
```

Note

Zsh treats square brackets ([ ]) as globbing characters. You must quote or escape them when using pip. Use either of the following:

pip install -e '.[dev]'
# or
pip install -e .\[dev\]

3. Dependency notes

The dependencies in Bedroc are defined in the pyproject.toml file.

When working directly with the source code, it may be necessary to update the packages in your virtual environment so they match the versions specified in the latest pyproject.toml. This ensures compatibility with the current development state of Bedroc and avoids conflicts caused by outdated dependencies.

If you encounter issues installing Bedroc, work through the usual checks:

Is the Python version at least the required minimum?
Is the correct environment activated?
Is a lock file preventing dependency updates? (E.g., see uv project sync docs)

Error messages from the resolver are often helpful in diagnosing dependency conflicts. If you suspect the problem is specific to Bedroc, please open an issue on GitHub.