C Reader source map

The paths below refer to the published protein-extract-and-view-tools repository, revision 8714b8ca6e859236f46d17e16c79dfe896780ff8. They are relative to h5-reader/src. The local copy is at T:/nmr-shielding-release/h5-reader/src, also available on Batcave at /shared/2026Thesis/nmr-shielding-release/h5-reader/src.

Each entry identifies the code behind an explanation in the Reader chapter.

Topic

Start reading here

What the code shows
Protein ownership model/QtProtein.h Atom, residue and name vectors; unique_ptr<QtTopology>; explicit name accessors.
Typed atom identity model/QtAtom.h Atom, residue and parent indices; typed chemical categories rather than atom-name strings.
Residue grouping model/QtResidue.h; io/QtTopologySidecar.cpp:311,542 Builds residue membership from the sidecar’s residue indices; PopulateBackboneCache records backbone atom indices.
Topology lookup model/QtTopology.h, QtTopology.cpp Stores bonds and rings; builds lookups from each atom to the bonds and rings it belongs to.
Atom and residue names model/QtAtomNames.h, QtResidueNames.h, QtProtein.cpp Stores names and retrieves them in a chosen naming convention.
Data ownership after load io/QtProteinLoader.h:22; .cpp:116,168 QtLoadResult owns the protein and conformation separately; the loader builds both from common sidecar data.
Common frame interface model/Conformation.h:25; .cpp:27 Abstract accessors; current snapshot; synchronous requestSnapshot; readiness signal.
Single pose model/SingleConformation.cpp Position reads from the pose’s Pos column; snapshot is shared.
Trajectory model/TrajectoryConformation.cpp Owns the H5 reader, maps frame numbers and finds each frame’s NPY files.
Dense buffer layout model/QtTimeSeriesBuffers.h:210 QtPositionsTimeSeries::at: (atom * n_frames + frame) * 3.
Borrowed frame view model/QtFrame.h, QtFrame.cpp Holds a conformation pointer and row number; reads values through the conformation rather than owning arrays.
Frame identity io/TrajectoryFrameMap.h, TrajectoryFrameMap.cpp Maps stored rows to original frame numbers and back; finds sampled frames.
Loading NPY files io/FrameNpyLoader.cpp:31; QtFieldCatalog.gen.h; FrameFieldPolicy.h Maps filenames to FieldKind, checks row types and shapes, and loads selected columns.
Per-frame storage model/QtConformationSnapshot.h array<NpyColumn, FieldKind::Count>, original frame identity and borrowed protein pointer.
Typed result view model/QtRingKernelGroup.h, QtBiotSavartGroup.h Reads scalar, vector and tensor components from snapshot columns; returns an empty optional value if a column is absent.
Display transformation model/TransformedConformation.cpp:100,117,127 R p + t; explicit rotation accessor; unmodified underlying snapshot.
Loading a run app/ReaderMainWindow.cpp:613 Owns the load result; creates the display wrapper, scene, playback and selection; connects the views.
Closing a run app/ReaderMainWindow.cpp:1337 Detaches views and deletes the scene and controllers before releasing the data.
Shared selection model/AtomSelection.h QAbstractListModel of atom indices with focus and selection signals.
Changing frames app/QtPlaybackController.cpp; ReaderMainWindow.cpp:661,707,959 Current-frame update and signal connections to scene, inspector and dashboard.
Render scheduling app/MoleculeScene.cpp:412,535 Updates geometry and combines pending render requests into one queued Qt callback.
Inspector detail app/QtAtomInspectorDock.cpp:352,373,394 Connects to the conformation, requests a snapshot and handles the signal that it is ready.
Dashboard roles model/TrajectorySignalCatalog.h; DashboardSignalModel.h; DashboardPanelModel.h; app/DashboardDisplayController.h Lists available measurements, records selections and stores samples for display.
REST uses the application app/RestServer.cpp:1956,2192 /api/run/load calls the window’s loader; /frame/set requests a frame change through playback.
Model-input export io/ModelInputExporter.h; app/RestServer.cpp:1931 Reads the loaded data and exports it in steps queued through Qt.

The compiler-generated JSON in reader/analysis/generated/ records where classes and functions are declared. The event diagrams follow the signal connections made in the C++ source rather than listing every signal a class declares.