Python Bridge

extensions/python-bridge exposes the services layer via PyO3.

7.1 Installation

See §1.3 Python Package Installation for wheel installation instructions and from-source build steps. Quick verification:

python -c "import orbitron; print(orbitron.Orbitron().load('fixtures/benzene.xyz').atom_count())"

7.2 Usage overview

import orbitron

orb = orbitron.Orbitron(remote="mycluster:/scratch/user/runs")
scene = orb.load("benzene.out")  # path is relative to the remote root

print("Atoms:", scene.atom_count())
print("Bonds:", scene.bond_count())
print("First atom Z:", scene.atomic_numbers()[0])
print("Distance 0-1:", orb.distance(scene, 0, 1))

# Geometry analysis (same output as CLI)
summary = orb.analyze_geometry(scene)
print(summary["atoms"], "atoms", summary["warnings"])

# Render a PNG headlessly
orb.render(scene, "benzene.png", width=1920, height=1080)

# Grab an RGBA frame for embedding in another UI
frame = orb.render_frame(scene, width=1024, height=768)
rgba = frame.as_bytes()             # copy as Python bytes
mv = frame.as_memoryview()          # zero-copy memoryview

# Jupyter display helper (requires pillow)
from PIL import Image
from IPython.display import display

img = Image.frombytes("RGBA", (frame.width, frame.height), rgba)
display(img)

# Load trajectories (optimization/MD logs)
trajectory = orb.load_trajectory("path/to/trajectory.log")
print("Frames:", trajectory.frame_count())
last_frame = trajectory.last_frame()

# Structured export for custom dashboards
scene_data = scene.to_dict()
print(scene_data["atoms"][0]["position"])

# Serialize a SceneGraph for wasm/Jupyter widgets
scene_bytes = scene.to_bytes()

Available helpers mirror the CLI modules: analyze_orbitals, analyze_populations, analyze_vibrations, analyze_band_structure, analyze_density_of_states, export, bounding_box, etc. When remote= is configured, Orbitron fetches files from the remote host over SSH/SFTP before processing.

Chemical identifiers — generate InChI / InChIKey / SMILES / molecular formula, including for metal complexes and coordination compounds where RDKit-style perception fails:

scene = orb.load("cisplatin.xyz")
orb.inchi(scene)      # 'InChI=1S/...'
orb.inchikey(scene)   # 27-character hashed key
orb.smiles(scene)     # SMILES (organometallic sandwich rings degrade to chains)
orb.formula(scene)    # 'Cl2H4N2Pt' (Hill notation)

Periodic datasets (VASP band/DOS) are exposed through the scene when present:

periodic = scene.periodic_electronic_structure()
if periodic:
    print(periodic["fermi_energy_ev"])
    print(periodic["band_structure"]["spin_channels"])
    print(periodic["density_of_states"]["energies_ev"][:5])

Pass include_projections=True to request orbital/site projection weights (can be large).

Hands-on examples (repo root):
- extensions/python-bridge/examples/api_smoke_test.py — CLI-style smoke test that exercises loading, measurements, exports, rendering, and analysis helpers.
- extensions/python-bridge/examples/api_quickstart.ipynb — step-by-step notebook for geometry basics.
- extensions/python-bridge/examples/api_analysis_walkthrough.ipynb — notebook showcasing orbital, population, and vibrational summaries.
- extensions/python-bridge/examples/api_trajectory_view.ipynb — minimal trajectory preview with in-memory render frames.
- extensions/python-bridge/examples/api_viewer_widget.ipynb — Jupyter widget demo with wasm viewer + delta updates.
- extensions/python-bridge/examples/orbitron_tutorial.ipynb — end-to-end tutorial notebook for the Python bridge.
- viewer/wasm/scripts/generate_scene_bin.py — dump a SceneGraph to a binary file for the web viewer.

7.1 Installation

7.2 Usage overview

7.2 Fonts (WASM widget)