neoralab-openff

This repository is the monorepo entry point for the Neoralab OpenFF stack.

The repository now has a root pyproject.toml so it can be installed directly with uv, and the root package version is resolved dynamically from git metadata with versioningit.

The root distribution neoralab-openff is an umbrella package. It does not install its own importable Python module; instead, it depends on the package distributions published from the subprojects under packages/.

The OpenFF packages now live under packages/:

• packages/units
• packages/utilities
• packages/toolkit
• packages/interchange
• packages/forcefields

The first implementation target is a working local development setup that can run examples/molecular_dynamics/molecular_dynamics_ligand_receptor.py from a single repository checkout.

Development setup

This monorepo currently standardizes on Python 3.12 because units, utilities, and forcefields require it.

The ligand-receptor example is now runnable from the root with uv and writes its outputs into examples/molecular_dynamics/output/.

Using uv

From the repository root, create the uv environment and install the workspace members:

uv sync

Then run the smoke import check or the example with uv:

uv run python devtools/scripts/smoke_imports.py
uv run python examples/molecular_dynamics/molecular_dynamics_ligand_receptor.py

The example now shows tqdm progress bars for equilibration and production, including elapsed wall time.

If AmberTools is not available, ligand charge assignment falls back from am1bcc to RDKit charge methods so the local smoke run can still complete.

The script defaults are intentionally small for a CPU-friendly smoke test. For more realistic runs, edit the MDSettings block in examples/molecular_dynamics/molecular_dynamics_ligand_receptor.py and increase:

• equil_steps to 50_000+
• prod_steps to 2_500_000+ for about 10 ns at a 4 fs timestep
• progress_chunk_steps if you want coarser or finer progress bar updates

The root pyproject.toml defines a uv workspace over the package subprojects, so uv sync installs the umbrella package together with the local monorepo packages from packages/.

Installing from PyPI

Once the root package and its dependencies are published, the umbrella distribution can be installed with:

pip install neoralab-openff

This works because the root package is a meta-package that pulls in the member distributions. It is only sufficient on its own if those dependencies are also available from the configured package index.

Release publishing

The repository includes a root GitHub Actions workflow that builds and publishes neoralab-openff to PyPI when a version tag is pushed.

Expected setup:

• add a repository secret named PYPI_TOKEN
• push a version tag such as v0.1.0 or 0.1.0

The workflow builds the root sdist and wheel from pyproject.toml, runs twine check, and uploads with the PyPI token.

Using pixi

1. Install pixi.

2. From the repository root, create the environment and install the local packages:

   pixi run postinstall
   

3. Verify that the editable installs and force-field discovery work:

   pixi run smoke_imports
   

4. Run the ligand-receptor example:

   pixi run run_example
   

The example writes generated files into examples/molecular_dynamics/output/.

Current scope

This first monorepo pass focuses on:

• consolidating the package source trees under one repository;
• providing a single root environment and install workflow;
• making the ligand-receptor example runnable from the repository root.

Root-level release automation is now in place for the umbrella package. Subproject release automation is still separate work.