API Documentation

Example: Loading a .h5md file from disk

To load a simulation from a .h5md trajectory file, pass a topology file and a path to the .h5md file to a Universe:

import zarrtraj
import MDAnalysis as mda
u = mda.Universe("topology.tpr", "trajectory.h5md")

The reader can also read .zarrmd files from disk.

zarrmd files are H5MD-formatted files stored in the Zarr format. To learn more, see the H5MD documentation, the Zarr documentation, and the zarrmd format page.

Example: Reading from cloud services

Zarrtraj currently supports reading from .h5md and .zarrmd files stored in AWS S3 buckets and, experimentally, Google Cloud buckets, Azure Blob storage, and Azure DataLakes.

AWS S3

To read from AWS S3, pass the S3 url path to the file as the trajectory argument:

import zarrtraj
import MDAnalysis as mda
import os

# Using environmental variables is a convenient way
# to manage AWS credentials
os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

u = mda.Universe("topology.tpr", "s3://sample-bucket/trajectory.h5md")

AWS provides a VSCode extension to manage AWS authentication profiles here.

Google Cloud Storage

First, follow these instructions to setup Application Default Credentials on the machine you’re streaming the trajectory to. Then, after ensuring your GCS bucket exists and you’ve logged in using the gcloud CLI with a user that has read access to the bucket, you can read from the GCS bucket as follows:

import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.tpr", "gcs://sample-bucket/trajectory.h5md")

Azure Blob Storage and Data Lakes

After configuring your storage account and container, the easiest way to authenticate is to use your storage accounts’ connection string which can be found in the Azure Portal:

import zarrtraj
import MDAnalysis as mda

# For production use, make sure to store your connection string in a secure location
os.environ["AZURE_STORAGE_CONNECTION_STRING"] = <str>

u = mda.Universe("topology.tpr", "az://sample-container/trajectory.h5md")

For more information on authenticating with Azure, see the adlfs documentation.

Warning

Zarrtraj is not optimized for reading trajectories in the cloud with random-access patterns. Iterate sequentially for best performance.

Example: Writing directly to cloud storage

Currently, writing directly to cloud storage is only supported for the zarrmd format. If you want to write directly to a cloud storage in the H5MD format, please raise an issue on the zarrtraj GitHub.

All datasets in the file will be written using the same chunking strategy: ~12MB per chunk, regardless of the data type, number of atoms, or number of frames in the trajectory. The only exceptions to this are when a single frame of the trajectory is larger than 12MB, in which case the chunk size will be 1 frame, or when the dataset is smaller than 12MB, in which case the dataset will be written in a single chunk.

import zarrtraj
import MDAnalysis as mda
from MDAnalysisTests.datafiles import PSF, DCD
import os

os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

u = mda.Universe(PSF, DCD)
with mda.Writer("s3://sample-bucket/trajectory.zarrmd",
                n_atoms=u.atoms.n_atoms) as w:
    for ts in u.trajectory:
        w.write(u.atoms)

For Google Cloud Storage, change the URL protocol to gcs and the authenticate with the gcloud CLI.

For Azure Blob Storage or Data Lakes, change the URL protocol to abfs/adl/az and authenticate with your storage account’s connection string.

For details on authenticating with different cloud services, see their respective trajectory reading sections above.

Classes

class zarrtraj.ZARR.ZARRH5MDReader(filename, storage_options=None, convert_units=True, group=None, cache_size=104857600, **kwargs)[source]

Reads .h5md and .zarrmd trajectory files using Zarr.

Note

Though the H5MD standard states that time datasets are optional, MDAnalysis requires that all time-dependent data have a time dataset in order to guarantee that all constructed Timestep objects have a time associated with them.

Parameters:

  • filename (str) – trajectory filename or URL

  • convert_units (bool (optional)) – convert units to MDAnalysis units

  • storage_options (dict (optional)) – options to pass to the storage backend via fsspec

  • group (str (optional)) – group in ‘particles’ to read from. Not required if only one group is present in ‘particles’

  • **kwargs (dict) – General reader arguments.

Raises:

  • RuntimeError – when Zarr is not installed

  • ValueError – when a unit is not recognized by MDAnalysis

  • ValueError – when the length units of position and box/edges in the trajectory group do not match

  • ValueError – when the time units of all time-dependent datasets do not match

  • ValueError – when convert_units=True but the H5MD file contains no units

  • ValueError – when an unsupported URL protocol is provided

  • ValueError – when dimension of unitcell is not 3

  • ValueError – when the simulation box is not ‘periodic’ or ‘none’

  • ValueError – when a position, velocity, force, or simulation group box is time-independent

  • ValueError – when the H5MD trajectory groups’ ‘box/edges’ and ‘position’ do not share the same step and time datasets

  • NoDataError – when the H5MD file does not contain an ‘h5md` group

  • NoDataError – when the H5MD file does not contain a ‘box` group

  • NoDataError – when the simulation box is ‘periodic’ but the H5MD trajectory group does not contain a ‘box/edges’ group

  • NoDataError – when the H5MD file contains multiple groups in ‘particles’ and the group kwarg is not provided

  • NoDataError – when a time-dependent dataset does not have a time dataset

  • NoDataError – when the H5MD file has no ‘position’, ‘velocity’, or ‘force’ group

OtherWriter(filename, **kwargs)

Returns a writer appropriate for filename.

Sets the default keywords start, step and dt (if available). n_atoms is always set from Reader.n_atoms.

See also

Reader.Writer()

Writer(filename, n_atoms=None, **kwargs)[source]

A trajectory writer with the same properties as this trajectory.

add_auxiliary(aux_spec: str | Dict[str, str] = None, auxdata: str | AuxReader = None, format: str = None, **kwargs) → None

Add auxiliary data to be read alongside trajectory.

Auxiliary data may be any data timeseries from the trajectory additional to that read in by the trajectory reader. auxdata can be an AuxReader instance, or the data itself as e.g. a filename; in the latter case an appropriate AuxReader is guessed from the data/file format. An appropriate format may also be directly provided as a key word argument.

On adding, the AuxReader is initially matched to the current timestep of the trajectory, and will be updated when the trajectory timestep changes (through a call to next() or jumping timesteps with trajectory[i]).

The representative value(s) of the auxiliary data for each timestep (as calculated by the AuxReader) are stored in the current timestep in the ts.aux namespace under aux_spec; e.g. to add additional pull force data stored in pull-force.xvg:

u = MDAnalysis.Universe(PDB, XTC)
u.trajectory.add_auxiliary('pull', 'pull-force.xvg')

The representative value for the current timestep may then be accessed as u.trajectory.ts.aux.pull or u.trajectory.ts.aux['pull'].

The following applies to energy readers like the EDRReader.

All data that is present in the (energy) file can be added by omitting aux_spec like so:

u.trajectory.add_auxiliary(auxdata="ener.edr")

aux_spec is expected to be a dictionary that maps the desired attribute name in the ts.aux namespace to the precise data to be added as identified by a data_selector:

term_dict = {"temp": "Temperature", "epot": "Potential"}
u.trajectory.add_auxiliary(term_dict, "ener.edr")

Adding this data can be useful, for example, to filter trajectory frames based on non-coordinate data like the potential energy of each time step. Trajectory slicing allows working on a subset of frames:

selected_frames = np.array([ts.frame for ts in u.trajectory
                            if ts.aux.epot < some_threshold])
subset = u.trajectory[selected_frames]

See also

remove_auxiliary()

Note

Auxiliary data is assumed to be time-ordered, with no duplicates. See the Auxiliary API.

add_transformations(*transformations)

Add all transformations to be applied to the trajectory.

This function take as list of transformations as an argument. These transformations are functions that will be called by the Reader and given a Timestep object as argument, which will be transformed and returned to the Reader. The transformations can be part of the transformations module, or created by the user, and are stored as a list transformations. This list can only be modified once, and further calls of this function will raise an exception.

u = MDAnalysis.Universe(topology, coordinates)
workflow = [some_transform, another_transform, this_transform]
u.trajectory.add_transformations(*workflow)

The transformations are applied in the order given in the list transformations, i.e., the first transformation is the first or innermost one to be applied to the Timestep. The example above would be equivalent to

for ts in u.trajectory:
   ts = this_transform(another_transform(some_transform(ts)))
Parameters:

transform_list (list) – list of all the transformations that will be applied to the coordinates in the order given in the list

See also

MDAnalysis.transformations

property aux_list

Lists the names of added auxiliary data.

check_slice_indices(start, stop, step)

Check frame indices are valid and clip to fit trajectory.

The usage follows standard Python conventions for range() but see the warning below.

Parameters:

  • start (int or None) – Starting frame index (inclusive). None corresponds to the default of 0, i.e., the initial frame.

  • stop (int or None) – Last frame index (exclusive). None corresponds to the default of n_frames, i.e., it includes the last frame of the trajectory.

  • step (int or None) – step size of the slice, None corresponds to the default of 1, i.e, include every frame in the range start, stop.

Returns:

start, stop, step – Integers representing the slice

Return type:

tuple (int, int, int)

Warning

The returned values start, stop and step give the expected result when passed in range() but gives unexpected behavior when passed in a slice when stop=None and step=-1

This can be a problem for downstream processing of the output from this method. For example, slicing of trajectories is implemented by passing the values returned by check_slice_indices() to range()

range(start, stop, step)

and using them as the indices to randomly seek to. On the other hand, in MDAnalysis.analysis.base.AnalysisBase the values returned by check_slice_indices() are used to splice the trajectory by creating a slice instance

slice(start, stop, step)

This creates a discrepancy because these two lines are not equivalent:

range(10, -1, -1)             # [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
range(10)[slice(10, -1, -1)]  # []
close()[source]

close reader

convert_forces_from_native(force, inplace=True)

Conversion of forces array force from native to base units

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_forces_to_native(force, inplace=True)

Conversion of force array force from base to native units.

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_pos_from_native(x, inplace=True)

Conversion of coordinate array x from native units to base units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_pos_to_native(x, inplace=True)

Conversion of coordinate array x from base units to native units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_from_native(t, inplace=True)

Convert time t from native units to base units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.) In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_to_native(t, inplace=True)

Convert time t from base units to native units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_velocities_from_native(v, inplace=True)

Conversion of velocities array v from native to base units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

convert_velocities_to_native(v, inplace=True)

Conversion of coordinate array v from base to native units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

copy()[source]

Return independent copy of this Reader.

New Reader will have its own file handle and can seek/iterate independently of the original.

Will also copy the current state of the Timestep held in the original Reader.

Note

ZARRH5MDReader overrides this method to copy the copied reader’s timestep to the cache’s timestep

Changed in version 2.2.0: Arguments used to construct the reader are correctly captured and passed to the creation of the new class. Previously the only n_atoms was passed to class copies, leading to a class created with default parameters which may differ from the original class.

property dt: float

Time between two trajectory frames in picoseconds.

property frame: int

Frame number of the current time step.

This is a simple short cut to Timestep.frame.

get_aux_attribute(auxname, attrname)

Get the value of attrname from the auxiliary auxname

Parameters:

  • auxname (str) – Name of the auxiliary to get value for

  • attrname (str) – Name of gettable attribute in the auxiliary reader

See also

set_aux_attribute()

get_aux_descriptions(auxnames=None)

Get descriptions to allow reloading the specified auxiliaries.

If no auxnames are provided, defaults to the full list of added auxiliaries.

Passing the resultant description to add_auxiliary() will allow recreation of the auxiliary. e.g., to duplicate all auxiliaries into a second trajectory:

descriptions = trajectory_1.get_aux_descriptions()
for aux in descriptions:
    trajectory_2.add_auxiliary(**aux)
Returns:

List of dictionaries of the args/kwargs describing each auxiliary.

Return type:

list

See also

MDAnalysis.auxiliary.base.AuxReader.get_description()

iter_as_aux(auxname)

Iterate through timesteps for which there is at least one assigned step from the auxiliary auxname within the cutoff specified in auxname.

See also

next_as_aux(), iter_auxiliary()

iter_auxiliary(auxname, start=None, stop=None, step=None, selected=None)

Iterate through the auxiliary auxname independently of the trajectory.

Will iterate over the specified steps of the auxiliary (defaults to all steps). Allows to access all values in an auxiliary, including those out of the time range of the trajectory, without having to also iterate through the trajectory.

After interation, the auxiliary will be repositioned at the current step.

Parameters:

  • auxname (str) – Name of the auxiliary to iterate over.

  • (start, stop, step) (optional) – Options for iterating over a slice of the auxiliary.

  • selected (lst | ndarray, optional) – List of steps to iterate over.

Yields:

AuxStep object

See also

iter_as_aux()

property n_frames

number of frames in trajectory

next() → Timestep

Forward one step to next frame.

next_as_aux(auxname)

Move to the next timestep for which there is at least one step from the auxiliary auxname within the cutoff specified in auxname.

This allows progression through the trajectory without encountering NaN representative values (unless these are specifically part of the auxiliary data).

If the auxiliary cutoff is not set, where auxiliary steps are less frequent (auxiliary.dt > trajectory.dt), this allows progression at the auxiliary pace (rounded to nearest timestep); while if the auxiliary steps are more frequent, this will work the same as calling next().

See the Auxiliary API.

See also

iter_as_aux()

static parse_n_atoms(filename, group=None, so=None)[source]

Read the coordinate file and deduce the number of atoms

Returns:

n_atoms – the number of atoms in the coordinate file

Return type:

int

Raises:

NotImplementedError – when the number of atoms can’t be deduced

remove_auxiliary(auxname)

Clear data and close the AuxReader for the auxiliary auxname.

See also

add_auxiliary()

rename_aux(auxname, new)

Change the name of the auxiliary auxname to new.

Provided there is not already an auxiliary named new, the auxiliary name will be changed in ts.aux namespace, the trajectory’s list of added auxiliaries, and in the auxiliary reader itself.

Parameters:

  • auxname (str) – Name of the auxiliary to rename

  • new (str) – New name to try set

Raises:

ValueError – If the name new is already in use by an existing auxiliary.

rewind() → Timestep

Position at beginning of trajectory

set_aux_attribute(auxname, attrname, new)

Set the value of attrname in the auxiliary auxname.

Parameters:

  • auxname (str) – Name of the auxiliary to alter

  • attrname (str) – Name of settable attribute in the auxiliary reader

  • new – New value to try set attrname to

See also

get_aux_attribute(), rename_aux()

property time

Time of the current frame in MDAnalysis time units (typically ps).

This is either read straight from the Timestep, or calculated as time = Timestep.frame * Timestep.dt

timeseries(asel: AtomGroup | None = None, atomgroup: Atomgroup | None = None, start: int | None = None, stop: int | None = None, step: int | None = None, order: str | None = 'fac') → ndarray

Return a subset of coordinate data for an AtomGroup

Parameters:

  • asel (AtomGroup (optional)) – The AtomGroup to read the coordinates from. Defaults to None, in which case the full set of coordinate data is returned.

    Deprecated since version 2.7.0: asel argument will be renamed to atomgroup in 3.0.0

  • atomgroup (AtomGroup (optional)) – Same as asel, will replace asel in 3.0.0

  • start (int (optional)) – Begin reading the trajectory at frame index start (where 0 is the index of the first frame in the trajectory); the default None starts at the beginning.

  • stop (int (optional)) – End reading the trajectory at frame index stop-1, i.e, stop is excluded. The trajectory is read to the end with the default None.

  • step (int (optional)) – Step size for reading; the default None is equivalent to 1 and means to read every frame.

  • order (str (optional)) – the order/shape of the return data array, corresponding to (a)tom, (f)rame, (c)oordinates all six combinations of ‘a’, ‘f’, ‘c’ are allowed ie “fac” - return array where the shape is (frame, number of atoms, coordinates)

See also

MDAnalysis.coordinates.memory

Added in version 2.4.0.

property totaltime: float

Total length of the trajectory

The time is calculated as (n_frames - 1) * dt, i.e., we assume that the first frame no time as elapsed. Thus, a trajectory with two frames will be considered to have a length of a single time step dt and a “trajectory” with a single frame will be reported as length 0.

property transformations

Returns the list of transformations

units = {'length': None, 'time': None, 'velocity': None}

dict with units of of time and length (and velocity, force, … for formats that support it)

class zarrtraj.ZARR.ZARRMDWriter(filename, n_atoms, n_frames=None, compressor='default', precision=None, storage_options=None, convert_units=True, positions=True, velocities=True, forces=True, timeunit=None, lengthunit=None, velocityunit=None, forceunit=None, author='N/A', author_email=None, creator='MDAnalysis', creator_version='2.10.0', **kwargs)[source]

Writer for the H5MD format using Zarr.

Parameters:

  • filename (str) – filename or URL to write to

  • n_atoms (int) – number of atoms in the system

  • n_frames (int (optional)) – number of frames to be written in the output trajectory. If not provided, the trajectory will allocate more memory than necessary which may slow down trajectory write speed.

  • compressor (numcodecs.Codec (optional)) – compressor to use for the Zarr datasets. Will be applied to all datasets

  • precision (int (optional)) – applies the numcodecs.Quantize filter to Zarr datasets. Will be applied to all floating point datasets

  • storage_options (dict (optional)) – options to pass to the storage backend via fsspec

  • convert_units (bool (optional)) – Convert units from MDAnalysis to desired units [True]

  • positions (bool (optional)) – Write positions into the trajectory [True]

  • velocities (bool (optional)) – Write velocities into the trajectory [True]

  • forces (bool (optional)) – Write forces into the trajectory [True]

  • timeunit (str (optional)) – Option to convert values in the ‘time’ dataset to a custom unit, must be recognizable by MDAnalysis

  • lengthunit (str (optional)) – Option to convert values in the ‘position/value’ dataset to a custom unit, must be recognizable by MDAnalysis

  • velocityunit (str (optional)) – Option to convert values in the ‘velocity/value’ dataset to a custom unit, must be recognizable by MDAnalysis

  • forceunit (str (optional)) – Option to convert values in the ‘force/value’ dataset to a custom unit, must be recognizable by MDAnalysis

  • author (str (optional)) – Name of the author of the file

  • author_email (str (optional)) – Email of the author of the file

  • creator (str (optional)) – Software that wrote the file [MDAnalysis]

  • creator_version (str (optional)) – Version of software that wrote the file [MDAnalysis.__version__]

Raises:

  • RuntimeError – when Zarr is not installed

  • ValueError – when n_atoms is 0

  • ValueError – when n_frames is provided and not positive

  • ValueError – when precision is less than 0

  • ValueError – when ‘positions`, ‘velocities’, and ‘forces’ are all set to False

  • ValueError – when a unit is not recognized by MDAnalysis

  • TypeError – when the input object is not a Universe or AtomGroup

  • ValueError – when any of the optional timeunit, lengthunit, velocityunit, or forceunit keyword arguments are not recognized by MDAnalysis

  • ValueError – when convert_units is set to True but the trajectory being written has no units

  • NoDataError – when a timestep being written contains positions but no dimensions or vice versa

H5MD_VERSION = (1, 1)

currently written version of the file format

close()[source]

Close the trajectory file.

convert_dimensions_to_unitcell(ts, inplace=True)

Read dimensions from timestep ts and return appropriate unitcell.

The default is to return [A,B,C,alpha,beta,gamma]; if this is not appropriate then this method has to be overriden.

convert_forces_from_native(force, inplace=True)

Conversion of forces array force from native to base units

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_forces_to_native(force, inplace=True)

Conversion of force array force from base to native units.

Parameters:

  • force (array_like) – Forces to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input force is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.7.

convert_pos_from_native(x, inplace=True)

Conversion of coordinate array x from native units to base units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_pos_to_native(x, inplace=True)

Conversion of coordinate array x from base units to native units.

Parameters:

  • x (array_like) – Positions to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input x is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_from_native(t, inplace=True)

Convert time t from native units to base units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned (although note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.) In-place operations improve performance because allocating new arrays is avoided.

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_time_to_native(t, inplace=True)

Convert time t from base units to native units.

Parameters:

  • t (array_like) – Time values to transform

  • inplace (bool, optional) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input t is modified in place and also returned. (Also note that scalar values t are passed by value in Python and hence an in-place modification has no effect on the caller.)

Changed in version 0.7.5: Keyword inplace can be set to False so that a modified copy is returned unless no conversion takes place, in which case the reference to the unmodified x is returned.

convert_velocities_from_native(v, inplace=True)

Conversion of velocities array v from native to base units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

convert_velocities_to_native(v, inplace=True)

Conversion of coordinate array v from base to native units

Parameters:

  • v (array_like) – Velocities to transform

  • inplace (bool (optional)) – Whether to modify the array inplace, overwriting previous data

Note

By default, the input v is modified in place and also returned. In-place operations improve performance because allocating new arrays is avoided.

Added in version 0.7.5.

data_blacklist = ['step', 'time', 'dt']

These variables are not written from Timestep.data dictionary to the observables group in the H5MD file

has_valid_coordinates(criteria, x)

Returns True if all values are within limit values of their formats.

Due to rounding, the test is asymmetric (and min is supposed to be negative):

min < x <= max
Parameters:

  • criteria (dict) – dictionary containing the max and min values in native units

  • x (numpy.ndarray) – (x, y, z) coordinates of atoms selected to be written out

Return type:

bool

units = {'length': None, 'time': None, 'velocity': None}

dict with units of of time and length (and velocity, force, … for formats that support it)

write(obj)

Write current timestep, using the supplied obj.

Parameters:

obj (AtomGroup or Universe) – write coordinate information associate with obj

Note

The size of the obj must be the same as the number of atoms provided when setting up the trajectory.

Changed in version 2.0.0: Deprecated support for Timestep argument to write has now been removed. Use AtomGroup or Universe as an input instead.