pyretis.inout.formats package

This sub-package handles data formats for PyRETIS.

The methods and classes defined in this package will format the data created by PyRETIS and also enable the reading of such output data.

Further, this package includes some methods for interacting with other simulation packages.

Package structure

Modules

formatter.py (pyretis.inout.formats.formatter)

Generic methods for formatting output from PyRETIS. Defines the base class for all formatters.

cp2k.py (pyretis.inout.formats.cp2k)

A module defining input/output methods for use with CP2k.

cross.py (pyretis.inout.formats.cross)

Formatting of crossing data from PyRETIS.

energy.py (pyretis.inout.formats.energy)

Formatting of energy data from PyRETIS.

gromacs.py (pyretis.inout.formats.gromacs)

A module defining input/output methods for use with GROMACS.

__init__.py

This file.

order.py (pyretis.inout.formats.order)

Formatting of order parameter data from PyRETIS.

path.py (pyretis.inout.formats.path)

Formatting of path/trajectory data from PyRETIS.

pathensemble.py (pyretis.inout.formats.pathensemble)

Formatting of path ensemble data from PyRETIS.

snapshot.py (pyretis.inout.formats.snapshot)

Formatting of snapshot data from PyRETIS.

txt_table.py (pyretis.inout.formats.txt_table)

Definition of a table-like format.

xyz.py (pyretis.inout.formats.xyz)

A module defining input/output methods for use with a XYZ format.

Important classes defined in this package

CrossFormatter (CrossFormatter)

A class for formatting crossing data from flux simulations.

EnergyFormatter (EnergyFormatter)

A class for formatting energy data from PyRETIS.

EnergyPathFormatter (EnergyPathFormatter)

A class for formatting energy data for paths.

OrderFormatter (OrderFormatter)

A class for formatting order parameter data.

OrderPathFormatter (OrderPathFormatter)

A class for formatting order parameter data for paths.

PathExtFormatter (PathExtFormatter)

A class for formatting external trajectories.

PathIntFormatter (PathIntFormatter)

A class for formatting internal trajectories.

PathEnsembleFormatter (PathEnsembleFormatter)

A class for formatting path ensemble data.

SnapshotFormatter (SnapshotFormatter)

Generic class for formatting system snapshots (coordinates).

TxtTableFormatter (TxtTableFormatter)

A class for creating a table-like format.

List of submodules

• pyretis.inout.formats.cp2k
• pyretis.inout.formats.cross
• pyretis.inout.formats.energy
• pyretis.inout.formats.formatter
• pyretis.inout.formats.gromacs
• pyretis.inout.formats.order
• pyretis.inout.formats.pathensemble
• pyretis.inout.formats.path
• pyretis.inout.formats.snapshot
• pyretis.inout.formats.txt_table
• pyretis.inout.formats.xyz

pyretis.inout.formats.formatter module

Module for defining the generic formatting of output data from PyRETIS.

Important classes defined here

OutputFormatter (OutputFormatter)

A generic class for formatting output from PyRETIS.

PyretisLogFormatter (PyretisLogFormatter)

A class representing a formatter for the PyRETIS log file.

Important methods defined here

apply_format (apply_format())

Apply a format string to a given float value. This method can be used for formatting text for tables (i.e. if we want a fixed width).

format_number (format_number())

Format a number based on its size.

get_log_formatter (get_log_formatter())

Select a formatter for logging based on a given message level.

class pyretis.inout.formats.formatter.OutputFormatter(name, header=None)

Bases: object

A generic class for formatting output from PyRETIS.

name

A string which identifies the formatter.

Type:string

header

A header (or table heading) with information about the output data.

Type:string

print_header

Determines if we are to print the header or not. This is useful for classes making use of the formatter to determine if they should write out the header or not.

Type:boolean

__init__(name, header=None)

Initialise the formatter.

Parameters:

• name (string) – A string which identifies the output type of this formatter.
• header (dict, optional) – The header for the output data

__str__()

Return basic info about the formatter.

format(step, data)

Use the formatter to generate output.

Parameters:

• step (integer) – This is assumed to be the current step number for generating the output.
• data (list, dict or similar) – This is the data we are to format. Here we assume that this is something we can iterate over.

property header

Define the header as a property.

load(filename)

Read generic data from a file.

Since this class defines how the data is formatted it is also convenient to have methods for reading the data defined here. This method will read entire blocks of data from a file into memory. This will be slow for large files and this method could be converted to also yield the individual “rows” of the blocks, rather than the full blocks themselves.

Parameters:filename (string) – The path/file name of the file we want to open. Yields:data (list of tuples of int) – This is the data contained in the file. The columns are the step number, interface number and direction.

See also

read_some_lines()

static parse(line)

Parse formatted data.

This method is intended to be the “inverse” of the format() method. In this particular case, we assume that we read floats from columns in a file. One input line corresponds to a “row” of data.

Parameters:line (string) – The string we will parse. Returns:out (list of floats) – The parsed input data.

class pyretis.inout.formats.formatter.PyretisLogFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: Formatter

Hard-coded formatter for the PyRETIS log file.

This formatter will just adjust multi-line messages to have some indentation.

format(record)

Apply the PyRETIS log format.

pyretis.inout.formats.formatter._make_header(labels, width, spacing=1)

Format a table header with the given labels.

Parameters:

• labels (list of strings) – The strings to use for the table header.
• width (list of ints) – The widths to use for the table.
• spacing (int) – The spacing between the columns in the table

Returns:

out (string) – A header for the table.

pyretis.inout.formats.formatter.apply_format(value, fmt)

Apply a format string to a given float value.

Here we check the formatting of a float. We are forcing a maximum length on the resulting string. This is to avoid problems like: ‘{:7.2f}’.format(12345.7) which returns ‘12345.70’ with a length 8 > 7. The intended use of this function is to avoid such problems when we are formatting numbers for tables. Here it is done by switching to an exponential notation. But note however that this will have implications for how many decimal places we can show.

Parameters:

• value (float) – The float to format.
• fmt (string) – The format to use.

Note

This function converts numbers to have a fixed length. In some cases this may reduce the number of significant digits. Remember to also output your numbers without this format in case a specific number of significant digits is important!

pyretis.inout.formats.cp2k module

Some method for interacting with input/output from CP2K.

Important methods defined here

update_cp2k_input (update_cp2k_input())

A method for updating a CP2K input file and creating a new one.

read_cp2k_input (read_cp2k_input())

A method to read a CP2K input file.

class pyretis.inout.formats.cp2k.SectionNode(title, parent, settings, data=None)

Bases: object

A class representing a section in the CP2K input.

title

The title of the section

Type:string

parent

The parent section if this node represents a sub-section.

Type:string

settings

The setting(s) for this particular node.

Type:list of strings

data

A section of settings if the node defines several settings.

Type:string

children

A set with the sub-sections of this section.

Type:set of objects like SectionNode

level

An integer to remember how far down this node is. E.g. if the level is 2, this node is a sub-sub-section. This is used for printing.

Type:integer

parents

A list representing the path from the node to the top section.

Type:list of strings or None

__init__(title, parent, settings, data=None)

Initialise a node.

Parameters:

• title (string) – The title of the section.
• parent (object like SectionNode) – The parent if this section is a sub-section.
• settings (list of strings) – The settings defined in this section.
• data (list of strings, optional) – A section of settings.

add_child(child)

Add a sub-section to the current section.

get_all_parents()

Find the path to the top of the tree.

pyretis.inout.formats.cp2k._add_node(target, settings, data, nodes, node_ref)

Just add a new node.

pyretis.inout.formats.cp2k.cp2k_settings(settings, input_path)

Read and processes cp2k settings.

Parameters:

• settings (dict) – The current input settings..
• input_path (string) – The CP2K input path

pyretis.inout.formats.cp2k.dfs_print(node, visited)

Walk through the nodes and print out text.

Parameters:

• node (object like SectionNode) – The object representing a C2PK section.
• visited (set of objects like SectionNode) – The set contains the nodes we have already visited.

Returns:

out (list of strings) – These strings represent the CP2K input file.

pyretis.inout.formats.cp2k.read_box_data(box_data)

Read the box data.

Parameters:box_data (list of strings) – The settings for the SUBSYS->CELL section. Returns:

• out[0] (numpy.array, 1D) – The box vectors, in the correct order.
• out[1] (list of booleans) – The periodic boundary setting for each dimension.

pyretis.inout.formats.cp2k.read_cp2k_box(inputfile)

Read the box from a CP2K file.

Parameters:inputfile (string) – The file we will read from. Returns:

• out[0] (numpy.array) – The box vectors.
• out[1] (list of booleans) – For each dimension, the list entry is True if periodic boundaries should be applied.

pyretis.inout.formats.cp2k.read_cp2k_energy(energy_file)

Read and return CP2K energies.

Parameters:energy_file (string) – The input file to read. Returns:out (dict) – This dict contains the energy terms read from the CP2K energy file.

pyretis.inout.formats.cp2k.read_cp2k_input(filename)

Read a CP2K input file.

Parameters:filename (string) – The file to open and read. Returns:nodes (list of objects like SectionNode) – The root section nodes found in the file.

pyretis.inout.formats.cp2k.read_cp2k_restart(restart_file)

Read some info from a CP2K restart file.

Parameters:restart_file (string) – The file to read. Returns:

• pos (numpy.array) – The positions.
• vel (numpy.array) – The velocities.
• box_size (numpy.array) – The box vectors.
• periodic (list of booleans) – For each dimension, the list entry is True if periodic boundaries should be applied.

pyretis.inout.formats.cp2k.remove_node(target, node_ref, root_nodes)

Remove a node (and it’s children) from the tree.

Parameters:

• target (string) – The target node, on form root->section->subcection.
• node_ref (dict) – A dict with all the nodes.
• root_nodes (list of objects like SectionNode) – The root nodes.

pyretis.inout.formats.cp2k.set_parents(listofnodes)

Set parents for all nodes.

pyretis.inout.formats.cp2k.update_cp2k_input(template, output, update=None, remove=None)

Read a template input and create a new CP2K input.

Parameters:

• template (string) – The CP2K input file we use as a template.
• output (string) – The CP2K input file we will create.
• update (dict, optional) – The settings we will update.
• remove (list of strings, optional) – The nodes we will remove.

pyretis.inout.formats.cp2k.update_node(target, settings, data, node_ref, nodes, replace=False)

Update the given target node.

If the node does not exist, it will be created.

Parameters:

• target (string) – The target node, on form root->section->subsection
• settings (list of strings) – The settings for the node.
• data (list of strings or dict) – The data for the node.
• node_ref (dict of SectionNode) – A dict of all nodes in the tree.
• nodes (list of SectionNode) – The root nodes.
• replace (boolean, optional) – If this is True and if the nodes have some data, the already existing data will be ignored. We also assume that the data is already formatted.

pyretis.inout.formats.cross module

Module for formatting crossing data from PyRETIS.

Important classes defined here

CrossFormatter (CrossFormatter)

A class for formatting crossing data from flux simulations.

CrossFile (CrossFile)

A class for handling PyRETIS crossing files.

class pyretis.inout.formats.cross.CrossFile(filename, file_mode, backup=True)

Bases: FileIO

A class for handling PyRETIS crossing files.

__init__(filename, file_mode, backup=True)

Create the cross file with correct formatter.

class pyretis.inout.formats.cross.CrossFormatter

Bases: OutputFormatter

A class for formatting crossing data from flux simulations.

This class handles formatting of crossing data. The format for the crossing file is three columns:

1. The first column is the step number (an integer).
2. The second column is the interface number (an integer). These are numbered from 1 (_NOT_ from 0).
3. The direction we are moving in - + for the positive direction or - for the negative direction. Internally this is converted to an integer (+1 or -1).

CROSS_FMT = '{:>10d} {:>4d} {:>3s}'

__init__()

Initialise the crossing formatter.

format(step, data)

Generate output data to be written to a file or screen.

This will format the crossing data in a space delimited form.

Parameters:

• step (int) – This is the current step number. It is only used here for debugging and can possibly be removed. However, it’s useful to have here since this gives a common interface for all formatters.
• data (list of tuples) – The tuples are crossing with interfaces (if any) on the form (timestep, interface, direction) where the direction is ‘-’ or ‘+’.

Yields:

out (string) – The line(s) to be written.

See also

check_crossing(), calculates

Note

We add 1 to the interface number here. This is for compatibility with the old FORTRAN code where the interfaces are numbered 1, 2, … rather than 0, 1, … .

static parse(line)

Parse crossing data.

The format is described in format(), this method will parse this format for a _single_ row of data.

Parameters:line (string) – A line to parse. Returns:

• out[0] (integer) – The step number.
• out[1] (integer) – The interface number.
• out[2] (integer) – The direction, left (-1) or right (1).

Note

A ‘1’ will be subtracted from the interface in analysis. This is just for backward compatibility with the old FORTRAN code.

pyretis.inout.formats.energy module

Module for formatting energy data from PyRETIS.

Important classes defined here

EnergyFormatter (EnergyFormatter)

A class for formatting energy data from PyRETIS.

EnergyPathFormatter (EnergyPathFormatter)

A class for formatting energy data for paths.

EnergyFile (EnergyFile)

A class for handling PyRETIS energy files.

EnergyPathFile (EnergyPathFile)

A class for handling PyRETIS energy path files.

class pyretis.inout.formats.energy.EnergyFile(filename, file_mode, backup=True)

Bases: FileIO

A class for handling PyRETIS energy files.

__init__(filename, file_mode, backup=True)

Create the file object and attach the energy formatter.

class pyretis.inout.formats.energy.EnergyFormatter(name='EnergyFormatter')

Bases: OutputFormatter

A class for formatting energy data from PyRETIS.

This class handles formatting of energy data. The data is formatted in 5 columns:

1. Time, i.e. the step number.
2. Potential energy.
3. Kinetic energy.
4. Total energy, should equal the sum of the two previous columns.
5. Temperature.

ENERGY_FMT = ['{:>10d}', '{:>14.6f}', '{:>14.6f}', '{:>14.6f}', '{:>14.6f}', '{:>14.6f}']

ENERGY_TERMS = ('vpot', 'ekin', 'etot', 'temp')

HEADER = {'labels': ['Time', 'Potential', 'Kinetic', 'Total', 'Temperature'], 'width': [10, 14]}

__init__(name='EnergyFormatter')

Initialise the formatter for energy.

apply_format(step, energy)

Apply the energy format.

Parameters:

• step (int) – The current simulation step.
• energy (dict) – A dict with energy terms to format.

Returns:

out (string) – A string with the formatted energy data.

format(step, data)

Yield formatted energy data. See :py:meth:.`apply_format`.

load(filename)

Load entire energy blocks into memory.

Parameters:filename (string) – The path/file name of the file we want to open. Yields:data_dict (dict) – This is the energy data read from the file, stored in a dict. This is for convenience so that each energy term can be accessed by data_dict[‘data’][key].

class pyretis.inout.formats.energy.EnergyPathFile(filename, file_mode, backup=True)

Bases: FileIO

A class for handling PyRETIS energy path files.

__init__(filename, file_mode, backup=True)

Create the file object and attach the energy formatter.

class pyretis.inout.formats.energy.EnergyPathFormatter

Bases: EnergyFormatter

A class for formatting energy data for paths.

ENERGY_TERMS = ('vpot', 'ekin')

HEADER = {'labels': ['Time', 'Potential', 'Kinetic'], 'width': [10, 14]}

__init__()

Initialise.

format(step, data)

Format the order parameter data from a path.

Parameters:

• step (int) – The cycle number we are creating output for.
• data (tuple) – Here we assume that data[0] contains an object like PathBase and that data[1] is a string with the status for the path.

Yields:

out (string) – The strings to be written.

pyretis.inout.formats.gromacs module

Module for handling GROMACS input/output.

Important methods defined here

read_gromacs_generic (read_gromacs_generic())

A method for reading snapshots from any GROMACS file.

read_gromacs_file (read_gromacs_file())

A method for reading snapshots from a GROMACS GRO file.

read_gromacs_gro_file (read_gromacs_gro_file())

Read a single snapshot from a GROMACS GRO file.

write_gromacs_gro_file (write_gromacs_gro_file())

Write configuration in GROMACS GRO format.

read_gromos96_file (read_gromos96_file())

Read a single configuration GROMACS .g96 file.

write_gromos96_file (write_gromos96_file())

Write configuration in GROMACS g96 format.

read_xvg_file (read_xvg_file())

For reading .xvg files from GROMACS.

read_trr_header (read_trr_header())

Read a header from an open TRR file.

read_trr_data (read_trr_data())

Read data from an open TRR file.

skip_trr_data (skip_trr_data())

Skip reading data from an open TRR file and move on to the next header.

read_trr_file (read_trr_file())

Yield frames from a TRR file.

trr_frame_to_g96 (trr_frame_to_g96())

Dump a specific frame from a TRR file to a .g96 file.

write_trr_frame (write_trr_frame())

A simple method to write to a TRR file.

pyretis.inout.formats.gromacs._add_matrices_to_snapshot(snapshot)

Extract positions and velocities as matrices from GROMACS.

The extracted positions and velocities will be added to the given snapshot.

Parameters:snapshot (dict) – This dict contains the data read from the GROMACS file. Returns:

• xyz (numpy.array) – The positions as an array, (N, 3).
• vel (numpy.array) – The velocities as an array, (N, 3).

pyretis.inout.formats.gromacs._get_chunks(start, end, size)

Yield chunks between start and end of the given size.

pyretis.inout.formats.gromacs.read_gromacs_file(filename)

Read GROMACS GRO files.

This method will read a GROMACS file and yield the different snapshots found in the file. This file is intended to be used if we want to read all snapshots present in a file.

Parameters:filename (string) – The file to open. Yields:out (dict) – This dict contains the snapshot.

Examples

>>> from pyretis.inout.formats.gromacs import read_gromacs_file
>>> for snapshot in read_gromacs_file('traj.gro'):
...     print(snapshot['x'][0])

pyretis.inout.formats.gromacs.read_gromacs_generic(filename)

Read GROMACS files.

This method will read a GROMACS file and yield the different snapshots found in the file. This file is intended to be used to just count the n of snapshots stored in a file.

Parameters:filename (string) – The file to check. Yields:out (None.)

pyretis.inout.formats.gromacs.read_gromacs_gro_file(filename)

Read a single configuration GROMACS GRO file.

This method will read the first configuration from the GROMACS GRO file and return the data as give by read_gromacs_lines(). It will also explicitly return the matrices with positions, velocities and box size.

Parameters:filename (string) – The file to read. Returns:

• frame (dict) – This dict contains all the data read from the file.
• xyz (numpy.array) – The positions. The array is (N, 3) where N is the number of particles.
• vel (numpy.array) – The velocities. The array is (N, 3) where N is the number of particles.
• box (numpy.array) – The box dimensions.

pyretis.inout.formats.gromacs.read_gromos96_file(filename)

Read a single configuration GROMACS .g96 file.

Parameters:filename (string) – The file to read. Returns:

• rawdata (dict of list of strings) – This is the raw data read from the file grouped into sections. Note that this does not include the actual positions and velocities as these are returned separately.
• xyz (numpy.array) – The positions.
• vel (numpy.array) – The velocities.
• box (numpy.array) – The simulation box.

pyretis.inout.formats.gromacs.read_trr_data(fileh, header)

Read box, coordinates etc. from a TRR file.

Parameters:

• fileh (file object) – The file handle for the file we are reading.
• header (dict) – The header read from the file.

Returns:

data (dict) – The data we read from the file. It may contain the following keys if the data was found in the frame:

• box : the box matrix,
• vir : the virial matrix,
• pres : the pressure matrix,
• x : the coordinates,
• v : the velocities, and
• f : the forces

pyretis.inout.formats.gromacs.read_trr_file(filename, read_data=True)

Yield frames from a TRR file.

pyretis.inout.formats.gromacs.read_trr_header(fileh)

Read a header from a TRR file.

Parameters:fileh (file object) – The file handle for the file we are reading. Returns:header (dict) – The header read from the file.

pyretis.inout.formats.gromacs.read_xvg_file(filename)

Return data in xvg file as numpy array.

pyretis.inout.formats.gromacs.skip_trr_data(fileh, header)

Skip coordinates/box data etc.

This method is used when we want to skip a data section in the TRR file. Rather than reading the data, it will use the size read in the header to skip ahead to the next frame.

Parameters:

• fileh (file object) – The file handle for the file we are reading.
• header (dict) – The header read from the TRR file.

pyretis.inout.formats.gromacs.trr_frame_to_g96(trr_file, index, outfile)

Dump a TRR frame to a GROMOS96 (.g96) file.

Parameters:

• trr_file (string) – The TRR file to read from.
• index (integer) – The index for the frame to dump from trr_file.
• outfile (string) – The g96 file to write.

pyretis.inout.formats.gromacs.write_gromacs_gro_file(outfile, txt, xyz, vel=None, box=None)

Write configuration in GROMACS GRO format.

Parameters:

• outfile (string) – The name of the file to create.
• txt (dict of lists of strings) – This dict contains the information on residue-numbers, names, etc. required to write the GRO file.
• xyz (numpy.array) – The positions to write.
• vel (numpy.array, optional) – The velocities to write.
• box (numpy.array, optional) – The box matrix.

pyretis.inout.formats.gromacs.write_gromos96_file(filename, raw, xyz, vel, box=None)

Write configuration in GROMACS .g96 format.

Parameters:

• filename (string) – The name of the file to create.
• raw (dict of lists of strings) – This contains the raw data read from a .g96 file.
• xyz (numpy.array) – The positions to write.
• vel (numpy.array) – The velocities to write.
• box (numpy.array, optional) – The box matrix.

pyretis.inout.formats.gromacs.write_trr_frame(filename, data, endian=None, double=False, append=False)

Write data in TRR format to a file.

Parameters:

• filename (string) – The name/path of the file to write to.
• data (dict) – The data we will write to the file.
• endian (string, optional) – Select the byte order; big-endian or little-endian. If not specified, the native byte order will be used.
• double (boolean, optional) – If True, we will write in double precision.
• append (boolean, optional) – If True, we will append to the file, otherwise, the file will be overwritten.

pyretis.inout.formats.order module

Module for formatting order parameter data from PyRETIS.

Important classes defined here

OrderFormatter (OrderFormatter)

A class for formatting order parameter data.

OrderPathFormatter (OrderPathFormatter)

A class for formatting order parameter data for paths.

OrderFile (OrderFile)

A class for handling PyRETIS order parameter files.

OrderPathFile (OrderPathFile)

A class for handling PyRETIS order parameter files for paths.

class pyretis.inout.formats.order.OrderFile(filename, file_mode, backup=True)

Bases: FileIO

A class for handling PyRETIS order parameter files.

__init__(filename, file_mode, backup=True)

Create the order file with correct formatter.

class pyretis.inout.formats.order.OrderFormatter(name='OrderFormatter')

Bases: OutputFormatter

A class for formatting order parameter data.

The format for the order file is column-based and the columns are:

1. Time.
2. Main order parameter.
3. Collective variable 1
4. Collective variable 2
5. …

ORDER_FMT = ['{:>10d}', '{:>12.6f}']

__init__(name='OrderFormatter')

Initialise a OrderFormatter formatter.

format(step, data)

Yield formatted order parameters. See format_data().

format_data(step, orderdata)

Format order parameter data.

Parameters:

• step (int) – This is the current step number.
• orderdata (list of floats) – These are the order parameters.

Yields:

out (string) – The strings to be written.

load(filename)

Read order parameter data from a file.

Since this class defines how the data is formatted it is also convenient to have methods for reading the data defined here. This method will read entire blocks of data from a file into memory. This will be slow for large files and this method could be converted to also yield the individual “rows” of the blocks, rather than the full blocks themselves.

Parameters:filename (string) – The path/file name of the file we want to open. Yields:data_dict (dict) – This is the order parameter data in the file.

See also

read_some_lines()

class pyretis.inout.formats.order.OrderPathFile(filename, file_mode, backup=True)

Bases: FileIO

A class for handling PyRETIS order parameter path files.

__init__(filename, file_mode, backup=True)

Create the order path file with correct formatter.

class pyretis.inout.formats.order.OrderPathFormatter

Bases: OrderFormatter

A class for formatting order parameter data for paths.

__init__()

Initialise.

format(step, data)

Format the order parameter data from a path.

Parameters:

• step (int) – The cycle number we are creating output for.
• data (tuple or list) – Here, data[0] contains a object like PathBase which is the path we are creating output for. data[1] contains the status for this path.

Yields:

out (string) – The strings to be written.

pyretis.inout.formats.pathensemble module

Module for formatting path ensemble data from PyRETIS.

Important classes defined here

PathEnsembleFormatter (PathEnsembleFormatter)

A class for formatting path ensemble data.

PathEnsembleFile (PathEnsembleFile)

A class for handling PyRETIS path ensemble files.

class pyretis.inout.formats.pathensemble.PathEnsembleFile(filename, file_mode, ensemble_settings=None, backup=True)

Bases: PathEnsemble, FileIO

A class for handling PyRETIS path ensemble files.

This class inherits from the PathEnsemble and this makes it possible to run the analysis directly on this file.

__init__(filename, file_mode, ensemble_settings=None, backup=True)

Set up the file-like object.

Parameters:

• filename (string) – The file to open.
• file_mode (string) – Determines the mode for opening the file.
• ensemble_settings (dict, optional) – Ensemble specific settings.
• backup (boolean, optional) – Determines how we handle existing files when the mode is set to writing.

get_paths()

Yield paths from the file.

class pyretis.inout.formats.pathensemble.PathEnsembleFormatter

Bases: OutputFormatter

A class for formatting path ensemble data.

This class will effectively define the data which we store for each path ensemble. The data is stored in columns with the format defined below and contains:

1. The current cycle number: ‘Step’.
2. The number of accepted paths: ‘No.-acc’.
3. The number of shooting moves attempted: ‘No.shoot’.
4. Starting location (with respect to interfaces): ‘l’. This can be L if a path starts on the left side, R if it starts on the right side and * if it did not reach the interface.
5. Marker for crossing he middle interface: (‘m’). This is either M (when the middle interface is crossed by the path) or * (if the middle interface is no crossed).
6. End point for the path: ‘r’. The possible values here are similar to the values for the starting location given above.
7. The length of the generated path: ‘Length’.
8. The status of the path: ‘Acc’. This is one of the possible path statuses defined in pyretis.core.path.
9. The type of move executed for generating the path: ‘Mc’. This is one of the moves defined in pyretis.core.path.
10. The smallest order parameter in the path: ‘Min-O’.
11. The largest order parameter in the path: ‘Max-O’.
12. The index in the path for the smallest order parameter: ‘Idx-Min’.
13. The index in the path for the largest order parameter: ‘Idx-Max’.
14. The order parameter for the shooting point, immediately after the shooting move: ‘O-shoot’.
15. The index in the source path for the shooting point: ‘Idx-sh’.
16. The index in the new path for the shooting point: ‘Idx-shN’.
17. The statistical weight of the path: ‘Weight’.

HEADER = {'labels': ['Step', 'No.-acc', 'No.-shoot', 'l', 'm', 'r', 'Length', 'Acc', 'Mc', 'Min-O', 'Max-O', 'Idx-Min', 'Idx-Max', 'O-shoot', 'Idx-sh', 'Idx-shN', 'Weight'], 'width': [10, 10, 10, 1, 1, 1, 7, 3, 2, 16, 16, 7, 7, 16, 7, 7, 7]}

PATH_FMT = '{0:>10d} {1:>10d} {2:>10d} {3:1s} {4:1s} {5:1s} {6:>7d} {7:3s} {8:2s} {9:>16.9e} {10:>16.9e} {11:>7d} {12:>7d} {13:>16.9e} {14:>7d} {15:7d} {16:>16.9e}'

__init__()

Initialise the formatter for path ensemble data.

format(step, data)

Format path ensemble data.

Here we generate output based on the last path from the given path ensemble.

Parameters:

• step (int) – The current cycle/step number.
• data (object like PathEnsemble) – The path ensemble we will format here.

Yields:

out (string) – The formatted line with the data from the last path.

load(filename)

Yield the different paths stored in the file.

The lines are read on-the-fly, converted and yielded one-by-one.

Parameters:filename (string) – The path/filename to open. Yields:out (dict) – The information for the current path.

parse(line)

Parse a line to a simplified representation of a path.

Parameters:line (string) – The line of text to parse. Returns:out (dict) – The dict with the simplified path information.

pyretis.inout.formats.path module

Module for formatting path-trajectory data from PyRETIS.

Important classes defined here

PathExtFormatter (PathExtFormatter)

A class for formatting external trajectories. Since this format is intended for paths created by an external software it will simply contain locations for the files where the snapshots are stored.

PathIntFormatter (PathIntFormatter)

A class for formatting internal trajectories. The format used is relatively simple and does not contain information about atoms, just the coordinates. The output for n-dimensional system contains 2n columns (positions and velocities). This formatter is intended for use with objects like Path.

PathExtFile (PathExtFile)

A class for writing path data for external paths.

PathIntFile (PathIntFile)

A class for writing path data for internal paths.

class pyretis.inout.formats.path.PathExtFile(filename, file_mode, backup=True)

Bases: FileIO

A class for writing path data.

__init__(filename, file_mode, backup=True)

Create the path writer with correct format for external paths.

class pyretis.inout.formats.path.PathExtFormatter

Bases: OutputFormatter

A class for formatting external trajectories.

The external trajectories as stored as files and this path formatter includes the location of these files.

FMT

The string to use for the formatting.

Type:string

FMT = '{:>10}  {:>20s}  {:>10}  {:>5}'

__init__()

Initialise the PathExtFormatter formatter.

format(step, data)

Format path data for external paths.

Parameters:

• step (integer) – The current simulation step.
• data (list) – Here, data[0] is assumed to be an object like Path` and data[1] a string containing the status of this path.

Yields:

out (string) – The trajectory as references to files.

static parse(line)

Parse the line data by splitting text on spaces.

Parameters:line (string) – The line to parse. Returns:out (list) – The columns of data.

class pyretis.inout.formats.path.PathIntFile(filename, file_mode, backup=True)

Bases: FileIO

A class for writing path data.

__init__(filename, file_mode, backup=True)

Create the path writer with correct format for internal paths.

class pyretis.inout.formats.path.PathIntFormatter

Bases: OutputFormatter

A class for formatting internal trajectories.

__init__()

Initialise the PathIntFormatter formatter.

format(step, data)

Format path data for internal paths.

Parameters:

• step (integer) – The current simulation step.
• data (list) – Here, data[0] is assumed to be an object like Path and data[1] a string containing the status of this path.

Yields:

out (string) – The trajectory (positions & velocities).

load(filename)

Load trajectories from a path file.

Parameters:filename (string) – The path/file name of the file we want to open. Yields:data (dict) – The trajectory & comment read from the path file.

static parse(line)

Parse positions and velocities from a single line.

Parameters:line (string) – The line to parse. Returns:

• pos (list of floats) – The positions read from the file.
• vel (list of floats) – The velocities read from the file.

read_snapshots(data)

Read snapshots from data.

Parameters:data (list of strings) – The data we are reading into snapshots. Yields:out (dict) – A dict representing the snapshot with positions and velocities.

pyretis.inout.formats.snapshot module

Module for formatting snapshot data from PyRETIS.

Important classes defined here

SnapshotFormatter (SnapshotFormatter)

Generic class for formatting system snapshots (coordinates). Note it is intended to format objects like System. The format is very similar to the XYZ format.

SnapshotFile (SnapshotFile)

A class for a collection of snapshots.

Important methods defined here

adjust_coordinate (adjust_coordinate())

Helper method to add dimensions when formatting data in 1D or 2D to a format that requires 3D data.

read_txt_snapshots (read_txt_snapshots())

For reading PyRETIS snapshots from a file.

class pyretis.inout.formats.snapshot.SnapshotFile(filename, file_mode, backup=True, format_settings=None)

Bases: FileIO

A class for a collection of snapshots.

__init__(filename, file_mode, backup=True, format_settings=None)

Create the snapshot file with the possible settings.

class pyretis.inout.formats.snapshot.SnapshotFormatter(write_vel=True, fmt=None)

Bases: OutputFormatter

Generic class for formatting system snapshots.

write_vel

If True, we will also format velocities

Type:boolean

fmt

Format to use for position output.

Type:string

fmt_vel

Format to use for position and velocity output.

Type:string

__init__(write_vel=True, fmt=None)

Initialise the formatter.

Parameters:

• write_vel (boolean, optional) – If True, the formatter will attempt to output velocities.
• fmt (string, optional) – Selects the format to use.

_format_with_vel(particles)

Format positions of particles for output.

Parameters:particles (object like Particles) – The particles for which we will format information. Yields:out (string) – The formatted output, to be written.

_format_without_vel(particles)

Format positions of particles for output.

Parameters:particles (object like Particles) – The particles for which we will format information. Yields:out (string) – The formatted output, to be written.

data_keys = ('atomname', 'x', 'y', 'z', 'vx', 'vy', 'vz')

format(step, data)

Generate the snapshot output.

Parameters:

• step (integer) – The current step number for generating the output.
• data (object like System) – The system we are generating output for.

format_snapshot(step, system)

Format the given snapshot.

Parameters:

• step (int) – The current simulation step.
• system (object like System) – The system object with the positions to format.

Returns:

out (list of strings) – The formatted snapshot.

load(filename)

Read snapshots from a given file.

Parameters:filename (string) – The path/filename to open. Yields:out (dict) – This dict contains the snapshot.

static parse(line)

Not implemented - line parser for snapshots.

For snapshots, we use a specialized reader that will read entire system snapshots. To avoid confusion, we just give a warning here.

pyretis.inout.formats.snapshot.adjust_coordinate(coord)

Adjust the dimensionality of coordinates.

This is a helper method for trajectory writers.

A lot of the different formats expects us to have 3 dimensional data. This method just adds dummy dimensions equal to zero.

Parameters:coord (numpy.array) – The real coordinates. Returns:out (numpy.array) – The “zero-padded” coordinates.

pyretis.inout.formats.snapshot.read_txt_snapshots(filename, data_keys=None)

Read snapshots from a text file.

Parameters:

• filename (string) – The file to read from.
• data_keys (tuple of strings, optional) – This tuple determines the data we are to read. It can be of type ('atomname', 'x', 'y', 'z', ...).

Yields:

out (dict) – A dictionary with the snapshot.

pyretis.inout.formats.txt_table module

Module defining a table-like output format.

Important classes defined here

TxtTableFormatter (TxtTableFormatter)

A class for creating a table-like format.

PathTableFormatter (PathTableFormatter)

A class for table-like output from path simulations.

ThermoTableFormatter (ThermoTableFormatter)

A class for thermodynamic (energy) output. Useful for output from MD-simulations.

Important methods defined here

txt_save_columns (txt_save_columns)

For writing simple column-based output.

class pyretis.inout.formats.txt_table.PathTableFormatter

Bases: TxtTableFormatter

A special table output class for path ensembles.

This object will return a table of text with a header and with formatted rows for a path ensemble. The table rows will contain data from the PathEnsemble.nstats variable. This table is just meant as output to the screen during a path ensemble simulation.

__init__()

Initialise the PathTableFormatter.

format(step, data)

Generate the output for the path table.

Here we overload the TxtTableFormatter.format() method in order to write path ensemble statistics to (presumably) the screen.

Parameters:

• step (int) – This is the current step number or a cycle number in a simulation.
• data (object like PathEnsemble) – This is the path ensemble we are generating output for.

Yields:

out (string) – The formatted output.

class pyretis.inout.formats.txt_table.ThermoTableFormatter

Bases: TxtTableFormatter

A special text table for energy output.

This object will return a table of text with a header and with formatted rows for energy output. Typical use is in MD simulation where we want to display energies at different steps in the simulations.

__init__()

Initialise the ThermoTableFormatter.

class pyretis.inout.formats.txt_table.TxtTableFormatter(variables, title, **kwargs)

Bases: OutputFormatter

A class for generating table output.

This class handles formatting of output data to a table-like format.

variables

These are the variables we will use in the table.

Type:list of strings

fmt

The format to apply to the columns.

Type:string

row_fmt

A list of strings used for formatting, used to construct fmt.

Type:list of strings

title

A title for the table.

Type:string

Example

For creating a new table, a dictionary is convenient for grouping the settings:

>>> tabl = {
...    'title': 'Energy output',
...    'var': ['step', 'temp', 'vpot'
...            'ekin', 'etot', 'press'],
...    'format': {'labels': ['Step', 'Temp', 'Pot',
...               'Kin', 'Tot', 'Press'],
...               'width': (10, 12),
...               'spacing': 2,
...               'row_fmt': ['{:> 10d}', '{:> 12.6g}']
...              }
...    }
>>> table = TxtTableFormatter(tabl['var'], tabl['title'], **tabl['format'])

__init__(variables, title, **kwargs)

Initialise the TxtTable object.

Parameters:

• variables (list of strings) – These are the variables we will use in the table. If the header is not specified, then we will create one using these variables.
• title (string) – A title for the table.
• kwargs (dict) – Additional settings for the formatter. This may contain:

  • widthlist of ints

    The (maximum) width of the columns. If the number of items in this list is smaller than the number of variables, we simply repeat the last width for the number of times we need.

  • labelslist of strings

    Table headers to use for the columns.

  • spacinginteger

    The separation between columns. The default value is 1.

  • row_fmtlist of strings

    The format to apply to the columns. If the number of items in this list is smaller than the number of variables, we simply repeat the last width for the number of times we need.

__str__()

Return a string with some info about the TxtTableFormatter.

format(step, data)

Generate output from a dictionary using the requested variables.

Parameters:

• step (int) – This is the current step number or a cycle number in a simulation.
• data (dict) – This is assumed to a dictionary containing the row items we want to format.

Yields:

out (string) – A line with the formatted output.

pyretis.inout.formats.txt_table._fill_list(the_list, length, fillvalue=None)

Fill a list to a specified length.

Parameters:

• the_list (list) – The list to fill.
• length (int) – The required length.
• fillvalue (optional) – The value to insert. If None is given the last item in the list is repeated.

pyretis.inout.formats.txt_table.txt_save_columns(outputfile, header, variables, backup=False)

Save variables to a text file using numpy.savetxt.

Note that the variables are assumed to be numpy.arrays of equal shape and that the output file may also be a compressed file in gzip format (this is selected by letting the output file name end with ‘.gz’).

Parameters:

• outputfile (string) – Name of the output file to create.
• header (string) – A string that will be written at the beginning of the file.
• variables (tuple or list of numpy.arrays) – These are the variables that will be saved to the text file.
• backup (boolean, optional) – Determines if we should backup old files or not.

pyretis.inout.formats.xyz module

Module for handling the output/input of trajectory data.

This module defines some classes for writing out and reading snapshots and trajectories in a XYZ-like format. By XYZ-like we here mean that we also include velocities as part of the file.

Important methods defined here

format_xyz_data (format_xyz_data())

A method for formatting position/velocity data into a XYZ-like format. This can be used by external engines to convert to a standard format.

read_xyz_file (read_xyz_file())

A method for reading snapshots from a XYZ file.

reverse_xyz_file (reverse_xyz_file())

Method to read an XYZ-file in reverse, helps xyz_merge() merge trajectories.

txt_to_xyz (txt_to_xyz())

Method for converting/extracting paths from the internal trajectory format and writing them as a .xyz file.

write_xyz_file (write_xyz_file())

Just a convenience method for writing to a new file.

write_xyz_trajectory (write_xyz_trajectory())

A helper method to write xyz trajectories. This will also attempt to write box information to the XYZ-header.

xyz_merge (xyz_merge())

A method to merge a forward and a backward XYZ trajectory. This method is mainly used when creating a whole trajectory for visualisation.

pyretis.inout.formats.xyz._reverse_xyz_buffer(buff, output)

Reverse the order in a XYZ buffer and extract frames.

Parameters:

• buff (string) – A buffer read from a .xyz file.
• output (object like file object) – Where we write the reversed frames.

Returns:

out (string) – The left-over data which did not make a full frame.

pyretis.inout.formats.xyz.format_xyz_data(pos, vel=None, names=None, header=None, fmt=None)

Format XYZ data for outputting.

Parameters:

• pos (numpy.array) – The positions to write.
• vel (numpy.array, optional) – The velocities to write.
• names (list, optional) – The atom names.
• header (string, optional) – Header to use for writing the XYZ-file.
• fmt (string, optional) – A format to use for the writing

Yields:

out (string) – The formatted lines.

pyretis.inout.formats.xyz.read_xyz_file(filename)

Read files in XYZ format.

This method will read a XYZ file and yield the different snapshots found in the file.

Parameters:filename (string) – The file to open. Yields:out (dict) – This dict contains the snapshot.

Examples

>>> from pyretis.inout.formats.xyz import read_xyz_file
>>> for snapshot in read_xyz_file('traj.xyz'):
...     print(snapshot['x'][0])

Note

The positions will NOT be converted to a specified set of units.

pyretis.inout.formats.xyz.reverse_xyz_file(filename, outputfile)

Reverse the order for frames in a given XYZ-file.

Parameters:

• filename (string) – The input .xyz file to open.
• outputfile (string) – The .xyz file to write.

Note

This method will NOT reverse velocities.

pyretis.inout.formats.xyz.write_xyz_file(filename, pos, vel=None, names=None, header=None)

Create a new XYZ file with the given file name.

Parameters:

• filename (string) – The file to create.
• pos (numpy.array) – The positions to write.
• vel (numpy.array, optional) – The velocities to write.
• names (list, optional) – The atom names.
• header (string, optional) – Header to use for writing the XYZ-file.

Note

We will here just overwrite if the file already exists.

Examples

>>> import numpy as np
>>> from pyretis.inout.formats.xyz import write_xyz_file
>>> xyz = 10 * np.random.rand(10, 3)
>>> write_xyz_file('conf.xyz', xyz)
>>> vel = 10 * np.random.rand(10, 3)
>>> write_xyz_file('confv.xyz', xyz, vel)

pyretis.inout.formats.xyz.write_xyz_trajectory(filename, pos, vel, names, box, step=None, append=True)

Write XYZ snapshot to a trajectory.

This is intended as a lightweight alternative for just dumping snapshots to a trajectory file.

Parameters:

• filename (string) – The file name to dump to.
• pos (numpy.array) – The positions we are to write.
• vel (numpy.array) – The velocities we are to write.
• names (list of strings) – Atom names to write.
• box (numpy.array) – The box dimensions/vectors
• step (integer, optional) – If the step is given, then the step number is written to the header.
• append (boolean, optional) – Determines if we append or overwrite an existing file.

Note

We will here append to the file.

pyretis.inout.formats.xyz.xyz_merge(backward, forward, merged)

Merge forward and backward trajectories into one.

Parameters:

• backward (string) – File path to the backward trajectory.
• forward (string) – File path to the forward trajectory.
• merged (string) – File path to the merged (output) trajectory. This will overwrite existing files with the same file path!

Note

The velocities in the backward trajectory will not be reversed, the purpose of this method is mainly to make whole trajectories for visualisation purposes.