Handling of writing new coordinate files

Collaboration diagram for Handling of writing new coordinate files:

Description

Provides basic functions to handle writing of new coordinate files.

The methods included in the coordinateio module implement the basics for manipulating and writing coordinate trajectory files and changing metadata in the underlying datastructures. Included are a container for storing modules that change trajectory data, as well as a manager to write output files that uses those methods. It can be used from within Framework for Trajectory Analysis (trajectoryanalysis), and uses methods from:

• Extensible Handling of Options (options)
• Parsing and Evaluation of Analysis Selections (selection)

Overview

The methods in coordinateio provide the infrastructure to perform operations on coordinate data files and structures during data analysis. It implements ways to change the information in coordinate data structures as well as checking that both input data and output method are matching for a given coordinate file writing operation. For this components verify first that all the requirements can be satisfied. Then components are build that will change the coordinate information accordingly.

The main parts are the outputadapters implemented using the IOutputAdapter interface to change information in a local (deep) copy of t_trxframes stored in the coordinatefile.

Outputadapter

Each OutputAdapter module implements the same IOutputAdapter interface and has to set its requirements for final processing as a flag from the enum in requirementflags. During processing, they implement a custom version of the processFrame directive that modifies the stored trajectory data before writing a new file to disk.

The interaction between the CoordinateFile and the OutputAdapter modules derived from IOutputAdapter is shown in the diagram below.

Once the CoordinateFile object and its registered modules are created, they can be used to iterate over input data to write new coordinate frames.

Preparing new OutputAdapters

If additional methods are needed to perform changes to the t_trxframe metadata, new OutputAdapters can be written that again implement the IOutputAdapter interface. The new method should follow the approach of the other modules that are present in changing a minimal set of t_trxframe data.

Author

Paul Bauer paul..nosp@m.baue.nosp@m.r.q@g.nosp@m.mail.nosp@m..com

Classes
class	gmx::TrajectoryFileOpener
	Low level method to take care of only file opening and closing. More...
class	gmx::TrajectoryFrameWriter
	Writes coordinate frames to a sink, e.g. a trajectory file. More...
class	gmx::IFrameConverter
	IFrameConverter interface for manipulating coordinate information. More...
class	gmx::IOutputAdapter
	OutputAdapter class for handling trajectory file flag setting and processing. More...
class	gmx::OutputSelector
	OutputSelector class controls setting which coordinates are actually written. More...
class	gmx::SetAtoms
	SetAtoms class controls availability of atoms data. More...
class	gmx::SetBox
	Allows changing box information when writing a coordinate file. More...
class	gmx::SetForces
	SetForces class allows changing writing of forces to file. More...
class	gmx::SetPrecision
	SetPrecision class allows changing file writing precision. More...
class	gmx::SetStartTime
	SetStartTime class allows changing trajectory time information. More...
class	gmx::SetTimeStep
	SetTimeStep class allows changing trajectory time information. More...
class	gmx::SetVelocities
	SetVelocities class allows changing writing of velocities to file. More...

Enumerations
enum	gmx::CoordinateFileFlags : unsigned long {   gmx::CoordinateFileFlags::Base = 1 << 0, gmx::CoordinateFileFlags::RequireForceOutput = 1 << 1, gmx::CoordinateFileFlags::RequireVelocityOutput = 1 << 2, gmx::CoordinateFileFlags::RequireAtomConnections = 1 << 3,   gmx::CoordinateFileFlags::RequireAtomInformation = 1 << 4, gmx::CoordinateFileFlags::RequireChangedOutputPrecision = 1 << 5, gmx::CoordinateFileFlags::RequireNewFrameStartTime = 1 << 6, gmx::CoordinateFileFlags::RequireNewFrameTimeStep = 1 << 7,   gmx::CoordinateFileFlags::RequireNewBox = 1 << 8, gmx::CoordinateFileFlags::RequireCoordinateSelection = 1 << 9, gmx::CoordinateFileFlags::Count }
	The enums here define the flags specifying the requirements of different outputadapter modules. More...
enum	gmx::FrameConverterFlags : unsigned long {   gmx::FrameConverterFlags::NoGuarantee = 1 << 0, gmx::FrameConverterFlags::MoleculesAreWhole = 1 << 1, gmx::FrameConverterFlags::NoPBCJumps = 1 << 2, gmx::FrameConverterFlags::MoleculeCOMInBox = 1 << 3,   gmx::FrameConverterFlags::ResidueCOMInBox = 1 << 4, gmx::FrameConverterFlags::AtomsInBox = 1 << 5, gmx::FrameConverterFlags::UnitCellIsRectangular = 1 << 6, gmx::FrameConverterFlags::UnitCellIsTriclinic = 1 << 7,   gmx::FrameConverterFlags::UnitCellIsCompact = 1 << 8, gmx::FrameConverterFlags::SystemIsCenteredInBox = 1 << 9, gmx::FrameConverterFlags::FitToReferenceRotTrans = 1 << 10, gmx::FrameConverterFlags::FitToReferenceRotTransXY = 1 << 11,   gmx::FrameConverterFlags::FitToReferenceTranslation = 1 << 12, gmx::FrameConverterFlags::FitToReferenceTranslationXY = 1 << 13, gmx::FrameConverterFlags::FitToReferenceProgressive = 1 << 14, gmx::FrameConverterFlags::NewSystemCenter = 1 << 15,   gmx::FrameConverterFlags::Count }
	The enums here define the guarantees provided by frameconverters concerning the modifications they provide. More...

Files
file	coordinatefile.cpp
	Implements methods from coordinatefile.h.
file	coordinatefile.h
	CoordinateFile takes care of opening files and writing output to them.
file	coordinatefileenums.h
	Defines enum class defining the different requirements that outputadapters have for the output file type. OutputManager objects can only be built with OutputAdapters whose requirements can be implemented with the available input.
file	frameconverterenums.h
	Defines enum class defining the guarantees provided by different frameconverters for the coordiante file manipulations done by them.
file	register.cpp
	Implements gmx::ProcessFrameConversion.
file	register.h
	Declares gmx::ProcessFrameConversion.
file	iframeconverter.h
	Interface class for frame handling, provides handles for all calls.
file	ioutputadapter.h
	Declares gmx::IOutputAdapter interface for modifying coordinate file structures before writing them to disk.
file	outputadaptercontainer.cpp
	Implements gmx::OutputAdapterContainer.
file	outputadaptercontainer.h
	Declares gmx::OutputAdapterContainer, a storage object for multiple outputadapters derived from the IOutputadaper interface.
file	outputselector.cpp
	Implements outputselector class.
file	outputselector.h
	Declares gmx::OutputSelector.
file	setatoms.cpp
	Implements setatoms class.
file	setatoms.h
	Declares gmx::SetAtoms.
file	setbox.h
	Declares gmx::SetBox.
file	setforces.cpp
	Implements setforce class.
file	setforces.h
	Declares gmx::SetForces.
file	setprecision.cpp
	Implements setprecision class.
file	setprecision.h
	Declares gmx::SetPrecision.
file	setstarttime.cpp
	Implements setstarttime class.
file	setstarttime.h
	Declares gmx::SetStartTime.
file	settimestep.cpp
	Implements settimestep class.
file	settimestep.h
	Declares gmx::SetTimeStep.
file	setvelocities.cpp
	Implements SetVelocities class.
file	setvelocities.h
	Declares gmx:SetVelocities.
file	outputadapters.h
	Public API convenience header for accessing outputadapters.
file	requirements.cpp
	Implements helper function to populate requirements from user input.
file	requirements.h
	Storage object for requirements to build coordinate file writer.
file	builder.cpp
	Tests for outputmanager.
file	coordinate_test.h
	Helper classes for coordinatefile and coordinateio tests.
file	frameconverter.h
	Helper classes for frameconverter tests.
file	outputadaptercontainer.cpp
	Tests for outputadaptercontainer.
file	outputadapters.cpp
	Tests for outputmanager.
file	outputadapters.h
	Helpers and data for outputadapter module tests.
file	register.cpp
	Tests for frameconverter registration method.
file	requirements.cpp
	Tests for processing of user input.
file	requirements.h
	Helpers and data for flag setting method.
file	setatoms.cpp
	Tests for gmx::SetAtoms.
file	setbothtime.cpp
	Tests for combination of gmx::SetTimeStep and gmx::SetStartTime.
file	setstarttime.cpp
	Tests for gmx::SetStartTime.
file	settimestep.cpp
	Tests for gmx::SetTimeStep.
file	testmodule.cpp
	Implements test module.
file	testmodule.h
	Dummy module used for tests and as an implementation example.

Enumeration Type Documentation

enum gmx::CoordinateFileFlags : unsigned long

strong

The enums here define the flags specifying the requirements of different outputadapter modules.

When building the object for deciding on the output to a new coordinate file, the CoordinateFile object needs to be able to validate that the dependencies of attached IOutputAdapters are fulfilled. Classes and interfaces that use the enum can check their dependencies against the information encoded in the flags and can then perform an appropriate reaction if there is a mismatch.

Todo:

Use std::bitset<16> for the entries.

Enumerator
Base	Base setting that says that the module has no requirements. Sets the flags to default setting to make sure all output methods are supported.
RequireForceOutput	Requires output method to support force output. If set, only output methods supporting writing of forces will work, others will generate an invalid input error.
RequireVelocityOutput	Requires output method to support velocity output. If set, only writing to files that support velocity output will succeed. Other writing methods will generate an error.
RequireAtomConnections	Requires support for connection information in output format. If set, only file output that supports writing of connection information will succeed. This means for now that only PDB and TNG files can be written. Other file writing methods will fail.
RequireAtomInformation	Requires that output format supports the writing of atom information to the file. If set, files will only be written if they can output the information from t_atoms and otherwise create an error while writing.
RequireChangedOutputPrecision	Requires that output format supports writing user-specified output precision. If set, output will only be written if the format supports the writing of custom precision of the included data.
RequireNewFrameStartTime	Requires that output format supports writing time to the file.
RequireNewFrameTimeStep	Requires that output format supports writing time to the file.
RequireNewBox	Requires that output format supports writing box information.
RequireCoordinateSelection	Requires output to support changes to selection of coordinates. Default for most methods, will need to be able to write coordinates to output file or generate an error.
Count	Needed for enumeration array.

enum gmx::FrameConverterFlags : unsigned long

strong

The enums here define the guarantees provided by frameconverters concerning the modifications they provide.

A method can specify different kind of guarantees for the operation, and aggregate methods can combine those flags to provide an overview about what has happened to a coordinate frame during processing.

Enumerator
NoGuarantee	Base setting means no guarantee is done by a module.
MoleculesAreWhole	Tells us that molecules have been made whole.
NoPBCJumps	Tells us that no jumps over periodic boundary are present. Implies molecules are made whole.
MoleculeCOMInBox	Tells us that COM of all molecules is in the box.
ResidueCOMInBox	Tells us that COM of residues is in the box.
AtomsInBox	Tells us that all atoms are in the box.
UnitCellIsRectangular	Tells us a converter changed the unit cell to rectangular.
UnitCellIsTriclinic	Tells us a converter changed the unit cell to triclinic.
UnitCellIsCompact	Tells us a converter changed the unit cell to compact.
SystemIsCenteredInBox	Tells us that converter centered system in a box. Invalidated by calling a method that changes the type of box.
FitToReferenceRotTrans	Tells us that converter has fit coordinate data to reference. Specific for rotational and translational fit.
FitToReferenceRotTransXY	Tells us that converter fit coordinate data to reference. Specific for rotation and translation in XY plane.
FitToReferenceTranslation	Tells us that converter fit coordinate data to reference. Specific for translational fit.
FitToReferenceTranslationXY	Tells us that converter fit coordinate data to reference. Specific for translational fit in XY plane.
FitToReferenceProgressive	Tells us that converter fit coordinate data to reference. Specific for progressive fit.
NewSystemCenter	Tells us that converter has set a new center for the system. This affects the routines that place atoms in the box and the unit cell changing routines, so they have to be invalidated by any method setting this flag.
Count	Final entry to get number of operations.