Reading bytes and editing structures

Read an in-memory fileCopy Anchor Link

Use Reader when a structure arrives as bytes rather than a filesystem path. Supply name when the bytes have no filename so MolFrame can identify the format.

from pathlib import Path
import molframe

payload = Path("model.cif").read_bytes()
reader = molframe.Reader(payload, name="model.cif")
print(reader.byte_length)
structure = reader.read()

molframe.read(payload, name="model.cif") is the equivalent one-call form. The name is format-identification metadata; it does not change the bytes.

Editing a structureCopy Anchor Link

A structure is immutable. An edit is a transaction: Structure.edit() returns a StructureEditor, topology changes are staged, and finish() validates the result as a whole and returns a new Structure. The original, and every view into it, is untouched, whether finish() succeeds or raises.

edited = structure.edit()
edited.rename_chain(0, "A")             # a zero-based hierarchy index, not an author label
edited.delete(structure.select("water"))
renamed = edited.finish()

Topology edits are refused with MOLFRAME-E3014 while the structure carries domain extensions (biological assemblies, symmetry, non-crystallographic symmetry, model-quality metadata) because they refer to atoms and chains the edit may remove. edited.clear_extensions() is the explicit, lossy choice that allows the edit.

Rewriting coordinatesCopy Anchor Link

Coordinates are edited through a separate, memory-budgeted transaction on a private copy:

scoped = structure.edit().coordinates(context=molframe.ExecutionContext(memory_budget=2**28))
positions = scoped.positions()          # writable (atoms, 3) float32 view of the copy
positions += 1.0
moved = scoped.commit()                 # a new structure with its own copy of the result

The copy is charged to the context's budget before it is allocated, and refused with MemoryBudgetError if it does not fit. commit() publishes an independent snapshot: writing to positions afterwards cannot change a structure that was already committed. The original structure is never modified.