Hidden Assumptions in mdanalysis
12 assumptions this code never checks · 5 critical · spanning Shape, Domain, Contract, Resource, Temporal, Scale, Ordering, Environment
Every codebase relies on things it never checks. Most of them are routine. CodeSea looked at mdanalysis/mdanalysis and picked out the few most likely to cause trouble. The full list is just below.
Most of what this code assumes is routine. These 3 are the ones most likely to cause trouble here. The rest are minor; they're under "Show everything".
If atom counts differ, NumPy broadcasting will fail with dimension mismatch errors, or if counts match but atom ordering differs, the alignment will compute rotation matrices based on wrong atom correspondences, producing meaningless RMSD values and incorrect structural alignments
If trajectory coordinates are in nanometers but reference structure is in Angstroms (common with different MD packages), contact fractions will be completely wrong - a 4.5 Angstrom cutoff becomes 4.5 nanometers, missing most real contacts and detecting spurious long-range contacts
If _single_frame() calls trajectory.next() or changes the current frame, the iteration logic breaks, causing frames to be skipped or processed multiple times, leading to incorrect time-series data in results.times and analysis metrics
Show everything (9 more)
All AtomGroup objects and analysis parameters can be successfully pickled for inter-process communication - the multiprocessing backend serializes the entire analysis state to worker processes
If this fails: If AtomGroups contain unpicklable objects (like lambda functions in custom selections or certain topology attributes), multiprocessing will fail with PicklingError, forcing fallback to serial execution without warning the user about the performance degradation
package/MDAnalysis/analysis/backends.py:BackendMultiprocessing
Trajectory frames are accessed in sequential order during analysis - caching mechanisms expect forward iteration and may not handle random access efficiently
If this fails: If analysis algorithms jump between non-consecutive frames (like comparing frame 1000 to frame 10), the trajectory cache becomes ineffective, causing repeated disk I/O that can slow analysis by 10-100x for large trajectory files
package/MDAnalysis/coordinates/base.py:TrajectoryReader
Atomic coordinate arrays will fit in available memory as contiguous NumPy arrays - positions property returns the full coordinate array of shape (n_atoms, 3) for all atoms in the group
If this fails: For large systems (>1M atoms), coordinate arrays can exceed 24GB memory, causing MemoryError crashes during analysis. This hits protein complexes, membrane systems, and solvated systems without warning as array size scales with system complexity
package/MDAnalysis/core/groups.py:AtomGroup.positions
Atom ordering in GRO topology files matches the coordinate ordering in trajectory frames - parser creates atom index mappings based on file order without validation
If this fails: If topology and trajectory files have atoms in different orders (possible when files are generated by different tools or preprocessing steps), AtomGroup.positions will return coordinates for wrong atoms, making all spatial analysis incorrect while appearing to work normally
package/MDAnalysis/topology/GROParser.py:parse
GRO files use standard GROMACS formatting conventions with exact column positions - coordinate parsing depends on fixed-width format assumptions
If this fails: If GRO files are created by non-GROMACS tools with slightly different formatting (different precision, spacing, or column alignment), coordinate parsing will silently read wrong values, corrupting all subsequent analysis without raising parse errors
package/MDAnalysis/coordinates/GRO.py:GROReader
Periodic boundary conditions (PBC) are consistently applied or ignored across all distance calculations - algorithms assume box dimensions in trajectory frames represent the same coordinate system convention
If this fails: If some trajectory frames have PBC information in different conventions (box matrix vs box vectors) or missing PBC data, distance calculations become inconsistent across frames, causing spurious jumps in contact analysis, RMSD, and other spatial measurements
package/MDAnalysis/lib/distances.py:distance_functions
The mobile and reference AtomGroups passed to analysis classes belong to compatible Universe objects with the same topology structure - atom indices and properties should correspond between universes
If this fails: If analysis receives AtomGroups from different topology sources (e.g., comparing protein from one simulation to different protein variant), atom index references become invalid, leading to accessing wrong atoms or IndexError crashes during coordinate operations
package/MDAnalysis/analysis/base.py:AnalysisBase.__init__
Analysis results accumulate in frame order and the results.times array corresponds directly to the frame indices processed - time values are assumed to be monotonically increasing
If this fails: If trajectory frames have non-monotonic timestamps (from concatenated simulations with overlapping times, or restarted runs), the time series analysis becomes meaningless for temporal correlation calculations, and plotting results against time produces confusing non-linear time axes
package/MDAnalysis/analysis/base.py:Results
The testsuite GRO file size is representative of typical usage patterns for benchmarking - performance measurements use a fixed small test system
If this fails: Benchmark results may not reflect real-world performance for large systems (>100K atoms) where memory allocation patterns, I/O bottlenecks, and parsing complexity scale non-linearly, potentially misleading users about expected performance on production datasets
benchmarks/benchmarks/GRO.py:time_create_GRO_universe
See the full structural analysis of mdanalysis: the pipeline, data models, and system behavior that put these assumptions in context.
Full analysis of mdanalysis/mdanalysis →Frequently Asked Questions
What does mdanalysis assume that could break in production?
The one most likely to cause trouble: The reference structure and target structure AtomGroups contain the same number of atoms in the same order - the QCP algorithm expects coordinate arrays of shape (N, 3) where N is identical between reference and target If this fails, If atom counts differ, NumPy broadcasting will fail with dimension mismatch errors, or if counts match but atom ordering differs, the alignment will compute rotation matrices based on wrong atom correspondences, producing meaningless RMSD values and incorrect structural alignments
How many hidden assumptions does mdanalysis have?
CodeSea found 12 assumptions mdanalysis relies on but never validates, 5 of them critical, spanning Shape, Domain, Contract, Resource, Temporal, Scale, Ordering, Environment. Most are routine — the analysis flags the two or three most likely to actually bite.
What is a hidden assumption?
Something the code depends on but never checks: a data shape, an ordering, an environment condition, a scale limit, or a contract with another service. It holds until the world it runs in changes, then fails silently.