---

name: universe-io description: "Load, construct, inspect, iterate, and write molecular systems with MDAnalysis Universe, readers, writers, and synthetic in-memory systems." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Universe I/O

Use this sub-skill when an MDAnalysis task starts from creating or loading a molecular system, attaching coordinates, iterating trajectories, validating coordinate/topology compatibility, or writing basic coordinate output.

Read First

• references/api-reference.md for exact entry points, signatures, and object responsibilities.
• references/workflows.md for loading, synthetic Universe.empty, in-memory trajectories, trajectory iteration, Merge, and basic writing recipes.
• references/troubleshooting.md for format, atom-count, topology-attribute, timestep, writer, and optional dependency failures.
• scripts/universe_smoke_check.py for a self-contained import and synthetic Universe check that does not use external test data files.

Use This For

• Pairing topology and coordinate inputs with MDAnalysis.Universe(topology, *coordinates, format=..., topology_format=...).
• Constructing small synthetic systems with Universe.empty(...) and optional MemoryReader trajectories.
• Replacing or attaching coordinates with Universe.load_new(...), including NumPy arrays via MemoryReader.
• Iterating u.trajectory, reading Timestep positions/dimensions/frame/time, and validating frame counts.
• Creating one-structure subsystems with Merge(...) and adding a new in-memory trajectory when needed.
• Choosing MDAnalysis.Writer(...), MDAnalysis.coordinates.reader(...), MDAnalysis.coordinates.writer(...), or AtomGroup.write(...) for basic output.

Route Elsewhere

• Selection strings, custom topology attributes, groups, guessing semantics, and topology manipulation belong in ../selections-topology/SKILL.md.
• RMSD/RDF/contacts/distances/hydrogen-bond and custom AnalysisBase workflows belong in ../analysis-workflows/SKILL.md.
• Transformation pipelines, wrap/unwrap/fit/center operations, and transformed-output recipes belong in ../transformations-writing/SKILL.md.
• Optional converter interoperability, fetchers, auxiliary data, and format dependency triage belong in ../formats-converters/SKILL.md.

Quick Checks

• Confirm len(u.atoms) equals u.trajectory.n_atoms after load or load_new.
• Confirm needed topology attributes exist before writing or downstream work, e.g. names, types, masses, residues, segments, bonds.
• Confirm u.trajectory.ts.positions.shape == (len(u.atoms), 3) and u.trajectory.ts.dimensions is meaningful before box-dependent operations.
• Prefer explicit format= or topology_format= for streams, ambiguous extensions, arrays, or filenames that MDAnalysis cannot infer.