Quickstart Notebook

The Orbitron Python API in a Jupyter notebook — load, measure, introspect, export.

Orbitron Python API — QuickstartInteractively load a small molecule, compute basic measurements, and produce quick exports.::: {.callout-note}## This page is a listing, not a runThe cells below are not executed when the site is built, so no outputs appear here. Run the notebook yourself to see them: the executable copy is `extensions/python-bridge/examples/api_quickstart.ipynb` in the repository, and the test suite executes it on every run, so what is printed here does work.:::> See also the Python API guide, the live viewer examples, and the Developer Guide.

SetupInstall the Orbitron Python extension into this environment from the repository root:`bashpython -m pip install -e extensions/python-bridge`That is the directory holding `pyproject.toml`; `extensions/python-bridge/python` is the package directory inside it and is not installable on its own. Install through pip rather than `maturin develop` — only the PEP 517 backend stages the WASM viewer assets into the package.

from pathlib import Pathfrom orbitron import Orbitron# Walk up to the workspace root rather than counting directories: this notebook# is published from a different depth than the source copy it is rendered from.NOTEBOOK_DIR = Path().resolve()REPO_ROOT = next(    (p for p in (NOTEBOOK_DIR, *NOTEBOOK_DIR.parents) if (p / 'Cargo.toml').is_file()),    None,)if REPO_ROOT is None:    raise RuntimeError(f'no Orbitron checkout above {NOTEBOOK_DIR}; set REPO_ROOT by hand')FIXTURES = REPO_ROOT / 'io' / 'pipelines' / 'tests' / 'fixtures'print('Repository root:', REPO_ROOT)print('Fixtures:', FIXTURES)

orb = Orbitron(verbose=True, data_root=str(REPO_ROOT))
scene_path = FIXTURES / 'xyz' / 'water.xyz'
scene = orb.load(str(scene_path))
scene

Geometry Measurements

# Atom ids are 1-based, matching the CLI selection DSL and the desktop's "Atom #N".
distance = orb.distance(scene, 1, 2)
angle = orb.angle(scene, 2, 1, 3)
center_of_mass = orb.center_of_mass(scene)
geometric_center = orb.geometric_center(scene)
bbox = orb.bounding_box(scene)
print(f'd(O1-H2) = {distance:.4f} Å')
print(f'H-O-H angle = {angle:.3f}°')
print('Center of mass:', center_of_mass)
print('Geometric centre:', geometric_center)
print('Bounding box:', bbox)

Scene Introspection

metadata = scene.metadata()
atoms = scene.atom_symbols()
print('Metadata:', metadata)
print('First symbols:', atoms[:5])
scene.atom_positions()[:3]

Export and Render

output_dir = NOTEBOOK_DIR / 'outputs'
output_dir.mkdir(parents=True, exist_ok=True)
roundtrip_xyz = output_dir / 'water_roundtrip.xyz'
render_png = output_dir / 'water.png'
orb.export(scene, str(roundtrip_xyz))
orb.render(scene, str(render_png), width=960, height=540)
roundtrip_xyz, render_png

Geometry Summary Helper

geometry_summary = orb.analyze_geometry(scene)
geometry_summary