ProteinMotion 0.15.0 — Cα-only morphs, fixes, and readable source

ProteinMotion 0.15.0 morphs Cα-only models, fixes bugs found in a review of the whole package, and documents the source code throughout.

Cα-only morphs

• StructureMorph animates coarse models and predicted folding pathways that contain only Cα atoms. Each residue turns with the Cα trace of its neighbours, and consecutive Cα atoms are joined by virtual bonds that keep their 3.8 Å spacing.
• Chains without backbone N, C, and O get secondary structure from Cα geometry, so their cartoons show helices and strands. proteinmotion.secondary.trace_states(ca) exposes the assignment.
• StructureMorph(source, target, align=False) keeps structures that are already superposed where they are.

Plots

• TimeSeriesPlot(show_value=False) hides the cursor value, for a second trace drawn on the same axes.
• Write on a plot staggers over the glyphs the plot draws, as documented, instead of a count of one before the first frame.

Fixes

• Camera chains such as self.camera.animate.focus(region) follow a moving region in any argument order of play(), and play(rate_func=...) eases chained animations once.
• DensityMap.from_file no longer treats cryo-EM volumes (space group 1 with a 90° cell, as MRC2014 writes them) as periodic crystals, so sampling and crops stop at the box edge. Crops follow the map's own max_voxels.
• Heatmap.distances(region=...) leaves out the region's ligands, ions, and water, which were placed at the last atom in the file.
• Camera.clearest_view picks the nearest of several equally clear views.
• Protein.build works for a single residue; MD files without a clock no longer raise from Trajectory.times; "atoms" highlight halos fit ions; the newest cached AlphaFold model is chosen by version number.
• Residues without a one-letter code show X in labels, sequence tracks, and conservation. read_alignment accepts blank lines before a Clustal header, reads the first of several Stockholm alignments, and raises FileNotFoundError for a missing path.
• Torsion names accept the labels' symbols, such as "χ₁". A chain end before another chain's proline is no longer scored as pre-proline, and classify returns "undefined" for residues without φ or ψ.
• libx265 movies get the hvc1 tag that Apple players need. Renderer rejects msaa values other than 1 and 4 before opening a GPU. The command line applies EEVEE options when the scene class chooses EEVEE, keeps the scene's own EEVEE settings, and reports bad values as usage errors.
• Backbone matching no longer builds an array that reached 4 GB for 800-residue chains.

Readable source

Every module now starts with a description of what it holds and who calls it. Comments explain the algorithms, constants, units, and the per-atom and GPU array layouts. CONTRIBUTING.md describes how a frame goes from the timeline to pixels. These changes leave rendered output bit-for-bit unchanged.

Upgrade notes

• A scene that listed a camera.animate focus before a moving molecule in one play() call, or chained a Focus under a clip-wide rate_func, renders differently.
• Sampling a cryo-EM map outside its box returns NaN instead of wrapped values.
• Heatmap.distances(region=...) has one row and column per polymer residue of the region.
• MD files whose frame times do not strictly increase have no timestamps, and plots use frame indices. read_alignment treats a one-line string as a file path.

Install

python -m pip install --upgrade proteinmotion==0.15.0

For interactive preview and trajectory readers:

python -m pip install --upgrade 'proteinmotion[preview,md]==0.15.0'

Morphs guide · Torsions guide · Synchronized plots · Rendered examples

Validation

A source archive and wheel built from a clean export of the release tree passed strict distribution metadata validation and were installed into a fresh Python 3.12 environment outside the checkout. Native and Studio movies rendered from that installation and decoded completely. The full suite passed 366 tests, including native Metal GPU and Blender checks; six NVIDIA encoder tests were skipped on the Apple M3 Max. Each bug fix has a regression test that fails on 0.14.0. Stills from all 87 documentation and gallery scenes are unchanged apart from two Write animations, whose clips were re-rendered. The website build, type checks, and 146 exported pages passed verification.

The PyPI publishing workflow additionally checks wheel installation on Linux (Python 3.11–3.14), Windows, and macOS before upload.