bioemu2 0.1.0rc0__tar.gz

bioemu2-0.1.0rc0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bioemu2-0.1.0rc0/NOTICES.md

@@ -0,0 +1,135 @@
+# NOTICES
+
+Except where otherwise noted, code authored for BioEmu2 by Microsoft is
+licensed under the MIT License. This distribution also contains third-party
+code under the licenses and notices described below and in the relevant source
+files. See `LICENSE` and `licenses/LICENSE.BOLTZ-MIT`, `licenses/LICENSE.GEOSTD`,
+`licenses/LICENSE.NVIDIA-FOLD-CP-MIT`, `licenses/LICENSE.PYTORCH3D-BSD`,
+`licenses/LICENSE.TORCH-SCATTER-MIT`, `licenses/LICENSE.LGPL-3.0`, and
+`licenses/LICENSE.GPL-3.0`.
+
+## Stereochemistry reference data
+
+`src/bioemu2/assets/stereo_chemistry.yaml` contains bond-length and
+bond-angle reference data exported from
+[OpenStructure 2.11.1](https://git.scicore.unibas.ch/schwede/openstructure/-/tree/2.11.1)
+(commit `aeebc45c0fc2e3255cb45178013dad5a00999a39`). The `monlib` section
+comes from OpenStructure's `modules/mol/alg/pymod/stereo_data.json`, derived
+from CCP4 MON_LIB, which is licensed under the GNU Lesser General Public
+License, version 3.0. The license is reproduced in `licenses/LICENSE.LGPL-3.0`,
+together with the GNU GPL version 3 in `licenses/LICENSE.GPL-3.0`.
+
+The `monlib_link` section comes from OpenStructure's
+`modules/mol/alg/pymod/stereochemistry.py` (`GetDefaultStereoLinkData`).
+Its nucleotide link parameters are adapted from geostd's
+`rna_dna/chain_link_rna2p.cif`. A
+[historical revision](https://github.com/phenix-project/geostd/blob/aef2b63e65ffab32157da4d6422723982a3e7d6d/rna_dna/chain_link_rna2p.cif)
+contains the corresponding values; OpenStructure does not specify the exact
+geostd revision it used. The geostd license is reproduced in `licenses/LICENSE.GEOSTD`.
+Its peptide and disulfide link parameters come from CCP4's
+`standard_geometry.cif`. OpenStructure identifies both link-data sources in
+the source file above. No legacy Engh-Huber section is included in this asset.
+
+The following geostd notice is reproduced from its `COPYRIGHT.txt`:
+
+```text
+geostd Copyright (c) 2009, The Regents of the University of
+California, through Lawrence Berkeley National Laboratory (subject to
+receipt of any required approvals from the U.S. Dept. of Energy).  All
+rights reserved.
+
+If you have questions about your rights to use or distribute this
+software, please contact Berkeley Lab's Technology Transfer Department
+at TTD@lbl.gov referring to "geostd (LBNL Ref CR-2725)."
+
+NOTICE.  This software was developed under funding from the
+U.S. Department of Energy.  As such, the U.S. Government has been
+granted for itself and others acting on its behalf a paid-up,
+nonexclusive, irrevocable, worldwide license in the Software to
+reproduce, prepare derivative works, and perform publicly and display
+publicly.  Beginning five (5) years after the date permission to
+assert copyright is obtained from the U.S. Department of Energy, and
+subject to any subsequent five (5) year renewals, the U.S. Government
+is granted for itself and others acting on its behalf a paid-up,
+nonexclusive, irrevocable, worldwide license in the Software to
+reproduce, prepare derivative works, distribute copies to the public,
+perform publicly and display publicly, and to permit others to do so.
+```
+
+## Boltz-derived code
+
+BioMoA layers and operations, denoising and steering code, MSA feature
+preparation, data-interface code, and all-atom feature preparation under
+`src/bioemu2` contain portions copied or adapted from
+[Boltz v1.0.0](https://github.com/jwohlwend/boltz/tree/v1.0.0). Those portions
+are licensed under the MIT License reproduced in `licenses/LICENSE.BOLTZ-MIT`. This
+notice continues to apply where modules and symbols use BioEmu2-local names.
+
+Copyright (c) 2024 Jeremy Wohlwend, Gabriele Corso, Saro Passaro.
+
+Contact-conditioning code and feature conventions in
+`src/bioemu2/biomoa/modules/conditioning.py` and
+`src/bioemu2/conditioning/contact.py` are adapted from
+[Boltz at commit `b1ebfc46ecf57f5414e0d1a6f9027bbb122c53bc`](https://github.com/jwohlwend/boltz/tree/b1ebfc46ecf57f5414e0d1a6f9027bbb122c53bc).
+Those portions are also licensed under the MIT License reproduced in
+`licenses/LICENSE.BOLTZ-MIT`.
+
+## PyTorch3D rotation helpers
+
+The quaternion and rotation helpers in
+`src/bioemu2/denoising/augmentation.py` contain adapted portions of
+[PyTorch3D](https://github.com/facebookresearch/pytorch3d) under the BSD
+License reproduced in `licenses/LICENSE.PYTORCH3D-BSD`.
+
+Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
+
+## torch_scatter-derived code
+
+`src/bioemu2/structure/scatter.py` contains portions copied or adapted from
+[`torch_scatter`](https://github.com/rusty1s/pytorch_scatter) at commit
+`8ec9364b0bdcd99149952a25749ad211c2d0567b`, via the Microsoft-authored
+`mdmlff.src.mlff.utils.scatter` wrapper. The upstream MIT License is reproduced
+in `licenses/LICENSE.TORCH-SCATTER-MIT`.
+
+Copyright (c) 2020 Matthias Fey <matthias.fey@tu-dortmund.de>.
+
+## NVIDIA Fold-CP-derived code
+
+Context-parallel distributed primitives and operations under
+`src/bioemu2/context_parallel` contain portions copied, adapted, or ported from
+[NVIDIA Fold-CP](https://github.com/NVIDIA-BioNeMo/boltz-cp) at commit
+`f76f37a77c854b56b6250b426af8c2d63b501f7f`. Source files identify their
+upstream paths and describe material modifications. The upstream MIT License is
+reproduced in `licenses/LICENSE.NVIDIA-FOLD-CP-MIT`.
+
+Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+Fold-CP also identifies portions derived from
+[Boltz](https://github.com/jwohlwend/boltz) at commit
+`cb04aeccdd480fd4db707f0bbafde538397fa2ac`; the Boltz notice and license are
+provided above and in `licenses/LICENSE.BOLTZ-MIT`.
+
+## MDTraj patches
+
+`src/bioemu2/patches/mdtraj_patcher.py` contains modified portions of
+[MDTraj](https://github.com/mdtraj/mdtraj), specifically the
+`Topology.from_openmm` and `PDBxTrajectoryFile` implementations. The surrounding
+patching and integration code was authored for BioEmu2.
+
+The file is licensed under the GNU Lesser General Public License, version 3.0
+or any later version. The copied MDTraj portions were originally offered under
+the GNU Lesser General Public License, version 2.1 or any later version; this
+distribution exercises the option to use version 3.0 or any later version.
+
+The upstream MDTraj files also contain portions originating from OpenMM under
+the MIT License. Their complete copyright, permission, and warranty notices are
+retained in `src/bioemu2/patches/mdtraj_patcher.py`.
+
+## OpenMM patches
+
+`src/bioemu2/patches/openmm_patches.py` contains modified portions of
+[OpenMM](https://github.com/openmm/openmm) and is licensed under OpenMM's MIT
+license. The complete OpenMM copyright and permission notice is reproduced in
+that file.
+
+Portions copyright (c) 2015-2023 Stanford University and the Authors.

bioemu2-0.1.0rc0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: bioemu2
+Version: 0.1.0rc0
+Summary: Local protein structure and conformational sampling with BioEmu2.
+License-Expression: MIT
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/LICENSE.BOLTZ-MIT
+License-File: licenses/LICENSE.GEOSTD
+License-File: licenses/LICENSE.GPL-3.0
+License-File: licenses/LICENSE.LGPL-3.0
+License-File: licenses/LICENSE.NVIDIA-FOLD-CP-MIT
+License-File: licenses/LICENSE.PYTORCH3D-BSD
+License-File: licenses/LICENSE.TORCH-SCATTER-MIT
+License-File: NOTICES.md
+Requires-Dist: biopython>=1.88
+Requires-Dist: biotite>=1.5
+Requires-Dist: click
+Requires-Dist: einops
+Requires-Dist: huggingface_hub
+Requires-Dist: hydra-core
+Requires-Dist: mdtraj
+Requires-Dist: numba
+Requires-Dist: numpy<2.5
+Requires-Dist: omegaconf
+Requires-Dist: openmm
+Requires-Dist: pdbecif
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: rdkit
+Requires-Dist: requests
+Requires-Dist: scipy
+Requires-Dist: tenacity
+Requires-Dist: torch<2.14,>=2.11
+Requires-Dist: tqdm
+Requires-Dist: triton; sys_platform == "linux"
+Provides-Extra: cuda
+Requires-Dist: cuequivariance==0.11.1; sys_platform == "linux" and extra == "cuda"
+Requires-Dist: cuequivariance-torch==0.11.1; sys_platform == "linux" and extra == "cuda"
+Requires-Dist: cuequivariance-ops-torch-cu13==0.11.1; sys_platform == "linux" and extra == "cuda"
+Requires-Dist: cuequivariance-ops-cu13==0.11.1; sys_platform == "linux" and extra == "cuda"
+Provides-Extra: cuda12
+Requires-Dist: torch==2.13.0+cu126; sys_platform == "linux" and extra == "cuda12"
+Requires-Dist: cuequivariance==0.11.1; sys_platform == "linux" and extra == "cuda12"
+Requires-Dist: cuequivariance-torch==0.11.1; sys_platform == "linux" and extra == "cuda12"
+Requires-Dist: cuequivariance-ops-torch-cu12==0.11.1; sys_platform == "linux" and extra == "cuda12"
+Requires-Dist: cuequivariance-ops-cu12==0.11.1; sys_platform == "linux" and extra == "cuda12"
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: py3dmol>=2.5.5; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: ipykernel; extra == "viz"
+Requires-Dist: ipywidgets>=8; extra == "viz"
+Requires-Dist: matplotlib; extra == "viz"
+Requires-Dist: playwright; extra == "viz"
+Requires-Dist: py3Dmol; extra == "viz"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="assets/emu.png" alt="BioEmu2 logo" width="120">
+
+# BioEmu2
+
+### A foundation model for biomolecular structure and dynamics
+
+**Predict folded structures, sample equilibrium ensembles, and propagate structures forward in time.**
+
+[Installation](#installation) · [Quick start](#quick-start) · [Tutorials](#tutorials) · [Documentation](docs/)
+
+<br>
+
+<img src="https://github.com/microsoft/bioemu2/releases/download/readme-media/mcl1_puma_clean_grid_v2.gif" alt="BioEmu2 simulating the PUMA BH3 peptide binding MCL-1" width="420">
+
+<sub>BioEmu2 simulating the PUMA BH3 peptide binding MCL-1.</sub>
+
+</div>
+
+---
+
+BioEmu2, short for "biomolecular emulator", is developed by Microsoft Research
+AI for Science.
+
+Key features include:
+
+- molecular systems containing proteins, nucleic acids, ligands, and other
+  chemical components;
+- equilibrium sampling and structure prediction from the command line or
+  Python;
+- time-lagged trajectory generation with implicit transfer operator models;
+- contact conditioning and inference-time steering toward desired properties;
+- context-parallel sampling of structures that do not fit on one GPU.
+
+## System requirements
+
+BioEmu2 requires Linux and an NVIDIA GPU; macOS and Windows are not supported.
+The `cuda` extra installs CUDA 13 cuEquivariance, which requires compute
+capability 7.5 or newer, such as NVIDIA T4, A100, RTX A6000, L40S, H100, and B200
+([CUDA 13 release notes](https://docs.nvidia.com/cuda/archive/13.0.0/cuda-toolkit-release-notes/index.html#deprecated-architectures)).
+GPUs with compute capability 7.0 (Volta, such as NVIDIA V100) need the CUDA 12
+[installation](#installation) instead.
+We have tested V100 (compute capability 7.0), T4 (7.5, with the CUDA 12
+installation), A100 and RTX A6000 (8.0 and 8.6), and B200 (10.0); other eligible
+GPUs have not been verified end to end. Check
+your GPU's compute capability with
+`nvidia-smi --query-gpu=name,compute_cap --format=csv`.
+
+Context-parallel sampling requires at least four GPUs.
+
+## Installation
+
+Use Python 3.12, 3.13, or 3.14 on a supported Linux machine. We recommend
+installing BioEmu2 in an isolated
+[virtual environment](https://docs.python.org/3/library/venv.html) or
+[conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
+To install in an isolated virtual environment, create and activate it from the
+repository root:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+```
+
+Replace `python3.12` with the name or path of your Python 3.12, 3.13, or 3.14
+executable if needed. Use `python -m pip` so packages are installed into the
+active Python environment rather than a different interpreter's `pip`.
+
+Run the installation command for your GPU from the repository root.
+For GPUs with compute capability 7.5 or newer, such as NVIDIA T4, A100,
+RTX A6000, L40S, H100, and B200, use the `cuda` extra:
+
+```bash
+python -m pip install ".[cuda]"
+```
+
+Compute capability 7.0 (Volta, such as NVIDIA V100) is the oldest supported;
+on these GPUs, use the `cuda12` extra with the PyTorch CUDA 12.6 package index:
+
+```bash
+python -m pip install ".[cuda12]" \
+  --extra-index-url https://download.pytorch.org/whl/cu126
+```
+
+GPUs with compute capability below 7.0 are not supported.
+
+We tested BioEmu2 and evaluated its benchmark metrics with Python 3.12. Python
+3.13 and 3.14 pass the test suite, but we have not evaluated benchmark metrics
+with them.
+
+For development, see [DEVELOPER.md](DEVELOPER.md).
+
+For Jupyter or VS Code notebooks, follow the [notebook
+quickstart](#notebook-quickstart) to install visualization dependencies and
+register a kernel.
+
+## Quick start
+
+### CLI
+
+Sample eight equilibrium conformations of adenylate kinase (PDB 1AKE):
+
+```bash
+bioemu2 sample-equilibrium \
+  --pdb-id 1AKE \
+  --out outputs/adk
+```
+
+Or predict a folded structure from a PDB entry:
+
+```bash
+bioemu2 predict-structure \
+  --pdb-id 1UBQ \
+  --num-samples 1 \
+  --out outputs/ubiquitin
+```
+
+Propagate each sampled adenylate kinase conformation by 1 ns:
+
+```bash
+bioemu2 propagate \
+  --x0-cif outputs/adk/topology.cif \
+  --x0-xtc outputs/adk/samples.xtc \
+  --lag-time-ns 1 \
+  --out outputs/adk-propagated
+```
+
+Run `bioemu2 --help` to list all commands.
+
+### Python API using EmuSession
+
+Construct an `EmuSession` to sample and propagate structures:
+
+```python
+from pathlib import Path
+
+from bioemu2 import EmuSession, System, load_model, save_frames
+
+model = load_model()
+
+# Predict a folded structure for ubiquitin.
+ubiquitin = System.from_pdb_id("1UBQ")
+prediction = EmuSession(ubiquitin, model=model, mode="structure").sample(num_samples=1)
+save_frames(prediction, Path("outputs/ubiquitin"))
+
+# Sample equilibrium conformations of adenylate kinase.
+adk = System.from_pdb_id("1AKE")
+emu = EmuSession(adk, model=model, mode="equilibrium")
+samples = emu.sample(num_samples=8)
+save_frames(samples, Path("outputs/adk"))
+
+# Propagate each adenylate kinase conformation by 1 ns.
+endpoints = emu.propagate(samples, lag_time_ns=1.0)
+save_frames(endpoints, Path("outputs/adk-propagated"))
+```
+
+`save_frames()` writes `samples.xtc` and `topology.cif` to each output
+directory.
+
+See [define molecular systems](docs/system.md), [predict and sample
+structures](docs/sampling.md), and [propagate structures](docs/propagation.md)
+for more options. The functional Python APIs provide
+[high-level sampling](docs/functional-api.md#sample-structures) and
+[propagation](docs/functional-api.md#propagate-structures) functions similar to
+the CLI commands, plus lower-level workflows for explicit control of
+embeddings and samplers.
+
+## More workflows
+
+### Steer sampling
+
+Choose a steering sampler to favour structures with desired properties:
+
+```bash
+bioemu2 sample-equilibrium \
+  --system src/bioemu2/assets/examples/systems/myoglobin_101m.yaml \
+  --out outputs/myoglobin \
+  --sampler edm_gd
+```
+
+See [steer sampling](docs/steering.md) and [define steering
+potentials](docs/potentials.md) to select an algorithm and configure its
+objective.
+
+### Sample large structures across multiple GPUs
+
+Context parallelism distributes the model's pair representations across a
+square mesh of GPUs, reducing the memory required on each device:
+
+```bash
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+torchrun --standalone --nproc-per-node=4 \
+  --module bioemu2.cp sample-equilibrium \
+  --pdb-id 1AKE \
+  --checkpoint bioemu2-preview \
+  --num-samples 3 \
+  --out outputs/adk-cp
+```
+
+See [sample large structures with context
+parallelism](docs/context-parallel-sampling.md) for mesh requirements, the
+Python API, and current limitations.
+
+### Inspect and subsample MSAs
+
+Retrieve an alignment from ColabFold or load your own A3M files, inspect the
+raw sequences, and select or randomly subsample rows with Python indexing.
+Pass the resulting `MSA` directly to `EmuSession` to control the alignment
+used for structure prediction, equilibrium sampling, or propagation without
+manually constructing embeddings.
+
+See [use multiple sequence alignments](docs/msa.md) for local-file loading,
+[MSA subsampling](docs/msa.md#select-rows-and-subsample-an-msa), and
+[custom-MSA inference](docs/msa.md#use-a-custom-msa-for-inference).
+
+## Tutorials
+
+- [Define molecular systems](docs/system.md) from PDB IDs, structure files, or sequences.
+- [Convert Boltz input YAML](docs/boltz.md) into systems you can sample from.
+- [Customise multiple-sequence alignments](docs/msa.md) used to condition sampling.
+- [Predict and sample structures](docs/sampling.md) for a system.
+- [Improve sampling speed and scale to bigger systems](docs/speed-and-capacity.md) by choosing batch size and precision.
+- [Load a model checkpoint](docs/checkpoints.md), choose where checkpoints are cached, or use a local checkpoint.
+- [Propagate structures through time](docs/propagation.md).
+- [Reuse trunk embeddings](docs/reuse-embeddings.md) across sampling and propagation calls, in memory or on disk.
+- [Use the functional Python API](docs/functional-api.md) to sample and propagate without an `EmuSession`.
+- [Steer sampling](docs/steering.md) towards structures with desired properties.
+- [Define steering potentials](docs/potentials.md) that encode the properties you want to favour.
+- [Sample large structures](docs/context-parallel-sampling.md) across multiple GPUs with context parallelism.
+
+## Notebook quickstart
+
+The [`examples`](examples) directory contains complete workflows as regular
+Python files split into executable cells with `# %%` markers. This Python
+Interactive format provides notebook-style cells while keeping the examples as
+plain `.py` files. They require a Linux machine with a supported NVIDIA GPU and
+network access.
+
+Activate a Python environment as described in [installation](#installation).
+From the repository root, install BioEmu2 with the visualization dependencies
+and register a kernel. The `viz` extra includes `ipykernel` and `py3Dmol`:
+
+```bash
+python -m pip install ".[cuda,viz]"
+python -m ipykernel install --user --name bioemu2 --display-name "BioEmu2"
+```
+
+On compute capability 7.0 GPUs, such as NVIDIA V100, replace the first command
+with:
+
+```bash
+python -m pip install ".[cuda12,viz]" \
+  --extra-index-url https://download.pytorch.org/whl/cu126
+```
+
+Select the **BioEmu2** kernel in Jupyter or VS Code. If registration succeeds
+but the kernel does not appear in VS Code, restart VS Code and try again.
+To check that it uses the environment you installed into, run
+`import sys; print(sys.executable)` in a cell. The examples load system YAML
+from the installed `bioemu2` package,
+regardless of the working directory. Relative `outputs/` paths are written
+under the current working directory.
+
+Open a single-GPU example in VS Code and select **Run Cell**, or run **Jupyter:
+Run Current File in Interactive Window** from the Command Palette. Launch the
+context-parallel example with `torchrun` as described in the
+[context-parallel sampling guide](docs/context-parallel-sampling.md#python-api).
+
+To run without VS Code, convert an example with
+[Jupytext](https://jupytext.readthedocs.io/) and open it in JupyterLab:
+
+```bash
+python -m pip install jupytext jupyterlab
+jupytext --to notebook examples/sample_structures.py
+jupyter lab examples/sample_structures.ipynb
+```
+
+Select the **BioEmu2** kernel, then run individual cells or choose **Run All
+Cells** from the **Run** menu.
+
+In VS Code, you can instead run **Jupyter: Export Current Python File as Jupyter
+Notebook** from the Command Palette. Generated `.ipynb` files are ignored by
+Git.
+
+## License
+
+BioEmu2 is released under the [MIT License](LICENSE). It includes code and
+reference data adapted from other open-source projects; the [third-party
+notices](NOTICES.md) identify those components and their licenses.