Quickstart Notebook

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

Orbitron Python API — Quickstart

Interactively load a small molecule, compute basic measurements, and produce quick exports.

Rendered from extensions/python-bridge/examples/api_quickstart.ipynb. See also the Python API guide, the live viewer examples, and the Developer Guide.

Setup

Make sure the Orbitron Python extension is installed in this environment (e.g. pip install -e extensions/python-bridge/python).

from pathlib import Path
from orbitron import Orbitron

NOTEBOOK_DIR = Path().resolve()
REPO_ROOT = NOTEBOOK_DIR.parents[2]
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