Your first analysis¶

In this tutorial you will load a molecule, measure a bond, characterize its sugar ring, and save a figure. No installation is required to run the live examples. Each one includes its own imports and inputs.

1. Load a real structure¶

Glycan is a molecular State with carbohydrate recognition. The bundled glucose benchmark is an XYZ file: atom count, a comment line, then one element and three coordinates per line.

from matmalib import Glycan

glucose = Glycan.from_file("data/glucose.xyz")
print("Atoms:", len(glucose.atoms))
print("Coordinate array:", glucose.xyz.shape)
print("Sugar rings:", len(glucose.monomers))
print("Named atoms:", glucose.monomers[0].atom_assignment)

The coordinate array has shape (n_atoms, 3). atom_assignment maps chemical names to zero-based positions in glucose.atoms, making it possible to measure chemically meaningful distances without guessing atom positions.

2. Measure a ring bond¶

from matmalib import Glycan, StateEditor

glucose = Glycan.from_file("data/glucose.xyz")
named = glucose.monomers[0].named_atoms
bond = StateEditor.get_distance([named["C1"], named["C2"]])
print(f"C1–C2 distance: {bond:.3f} angstrom")

Distances retain the input coordinate unit; this fixture is in angstroms. Change C2 to O to measure the anomeric carbon–ring oxygen distance. Continue with molecules and geometry for angles, dihedrals, and coordinate editing.

3. Describe the ring shape¶

from matmalib import Glycan

glucose = Glycan.from_file("data/glucose.xyz")
cp = glucose.cremer_pople()[0]
pucker = glucose.identify_ring_puckers()[0]
print(f"Amplitude Q: {cp['Q']:.3f} angstrom")
print(f"Polar angle theta: {cp['theta']:.2f} degrees")
print("Canonical pucker:", pucker["label"], "—", pucker["family"])

Q measures departure from planarity. A six-membered chair has a polar angle near a pole of the Cremer–Pople sphere. The canonical classifier uses a separate dihedral-based reference comparison; its distance is not the CP polar angle. Learn that distinction in ring puckering.

4. Save your first figure¶

from matmalib import Glycan

glucose = Glycan.from_file("data/glucose.xyz")
fig, ax = glucose.snfg(show_names=True)
fig.savefig("glucose-snfg.svg", bbox_inches="tight")
print("Saved glucose-snfg.svg")

The runner displays the figure and a download link for the SVG. Change the input to data/fucosylated_trisaccharide.xyz to draw a branched glycan. The glycan tutorial explains the linkage labels and symbol choices.

Run on your own computer¶

Use Python 3.12 or newer. In a fresh environment:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install matmalib

This site documents the repository version 0.3.9, and live examples use its bundled source. The latest published package may differ. To use this checkout instead:

git clone https://github.com/marianski-lab/matmalib.git
cd matmalib
python -m pip install -e .

The base package declares NumPy, SciPy, Matplotlib, NetworkX, colormaps, py3Dmol, and Tornado. Pip installs these dependencies. Simulation engines are optional: the MLMD installation guide explains the md, aimnet, solvation, metadynamics, and mlmd extras. Use a current source checkout for newly added MLMD features until a release containing them is published.

Download the sample structures into a data directory beside your script, or replace the example path with your own file. In a local script, call matplotlib.pyplot.show() to display figures or use fig.savefig(...). The browser displays open Matplotlib figures automatically.