pyretis.inout package

The sub-package handles input and output for PyRETIS.

This package is intended for creating various forms of output from the PyRETIS program. It include writers for simple text based output and plotters for creating figures. Figures and the text results can be combined into reports, which are handled by the report module.

Package structure

Imports from the other modules. (pyretis.inout.common)
Common functions and variables for the input/output. These functions are mainly intended for internal use and are not imported here. (pyretis.inout.settings)
A module which handles the reading/writing of settings. (pyretis.inout.restart)
A module which handles restart reading/writing.


analysisio (pyretis.inout.analysisio)
Handles the input and output needed for analysis.
plotting (pyretis.inout.plotting)
Handles plotting. It defines simple things like colors etc. for plotting. It also defines functions which can be used for specific plotting by the analysis and report tools.
report (
Generate reports with results from simulations.
setup (pyretis.inout.setup)
Handles set-up of simulations etc. from user settings.
writers (pyretis.inout.writers)
Handle formatting and presentation of text based output.

Important classes defined in this package

CrossWriter (CrossWriter)
A class for writing crossing data.
EnergyWriter (EnergyWriter)
A class for writing energy data.
EnergyPathWriter (EnergyPathWriter)
A class for writing out energy data for paths.
OrderWriter (OrderWriter)
A class for writing order parameter data.
OrderPathWriter (OrderPathWriter)
A class for writing out order parameter data for paths.
TrajWriter (TrajWriter)
Generic class for writing trajectory output.
PathExtWriter (PathExtWriter)
A class for writing external paths to file.
PathEnsembleWriter (PathEnsembleWriter)
Class for writing path ensemble data.
TxtTable (TxtTable)
Class for writing/create text based tables.

Important methods defined in this package

create_engine (create_engine())
Create an engine from input settings.
create_force_field (create_force_field())
Create a force field from input settings.
create_orderparameter (create_orderparameter())
Create an order parameter from input settings.
create_output_tasks (create_output_tasks())
Create output tasks from input settings.
create_simulation (create_simulation())
Create a simulation from input settings.
create_system (create_system())
Create a system from input settings.
generate_report (generate_report())
A function to generate reports from analysis output(s).
parse_settings_file (parse_settings_file())
Method for parsing settings from a given input file.
write_settings_file (write_settings_file())
Method for writing settings from a simulation to a given file.
write_restart_file (write_restart_file())
Method for writing restart information.


pyretis.inout.common module

This file contains common functions for the input/output.

It contains some functions that is used when generating reports, typically to format tables and numbers.

Important classes defined here

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).
check_python_version (check_python_version())
Method that will give warnings when we use older and untested versions of python.
create_backup (create_backup())
A function to handle the creation of backups of old files.
make_dirs (make_dirs())
Create directories (for path simulation).
print_to_screen (print_to_screen())
A method used for printing to screen.
pyretis.inout.common.apply_format(value, fmt)[source]

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.

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


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!


Method that will give a warning about old python version(s).


Check if a file exist and create backup if requested.

This function will check if the given file name exist and if it does, it will move that file to a new file name such that the given one can be used without overwriting.

Parameters:outputfile (string) – This is the name of the file we wish to create.
Returns:out – This string is None if no backup is made, otherwise it will just say what file was moved (and to where).
Return type:string


No warning is issued here. This is just in case the msg returned here will be part of some more elaborate message.


Create directories for path simulations.

This function will create a folder using a specified path. If the path already exist and if it’s a directory, we will do nothing. If the path exist and is a file we will raise an OSError exception here.

Parameters:dirname (string) – This is the directory to create.
Returns:out – A string with some info on what this function did. Intended for output.
Return type:string
pyretis.inout.common.print_to_screen(txt=None, level=None)[source]

Method to print output to standard out.

This method is included to ensure that output from PyRETIS to the screen is written out in a uniform way across the library and application(s).

  • txt (string) – The text to write to the screen.
  • level (string) – The level can be used to color the output.
class pyretis.inout.common.PyretisLogFormatter(fmt=None, datefmt=None, style='%')[source]

Bases: logging.Formatter

Hardcoded formatter for the PyRETIS log file.

This formatter will just adjust multiline messages to have some indentation.


pyretis.inout.restart module

This module defines how we write and read restart files.

Important methods defined here

read_restart_file (read_restart_file())
Method for reading restart information from a file.
write_restart_file (write_restart_file())
Method for writing the restart file.
write_path_ensemble_restart (:py:func`.write_path_ensemble_restart`)
Method for writing restart files for path ensembles.

Read restart info for a simulation.

Parameters:filename (string) – The file we are going to read from.
pyretis.inout.restart.write_restart_file(filename, simulation)[source]

Write restart info for a simulation.

  • filename (string) – The file we are going to write to.
  • simulation (object like Simulation) – A simulation object we will get information from.

Write a restart file for a path ensemble.

Parameters:path_ensemble (object like PathEnsemble) – The path ensemble we are writing restart info for.

pyretis.inout.settings module

This module handles parsing of input settings.

This module define the file format for PyRETIS input files.

Important methods defined here

parse_settings_file (parse_settings_file())
Method for parsing settings from a given input file.
write_settings_file (write_settings_file())
Method for writing settings from a simulation to a given file.
pyretis.inout.settings.parse_settings_file(filename, add_default=True)[source]

Parse settings from a file name.

Here, we read the file line-by-line and check if the current line contains a keyword, if so, we parse that keyword.

  • filename (string) – The file to parse.
  • add_default (boolean) – If True, we will add default settings as well for keywords not found in the input.

settings – A dictionary with settings for PyRETIS.

Return type:


pyretis.inout.settings.write_settings_file(settings, outfile, backup=True)[source]

Write simulation settings to an output file.

This will write a dictionary to a output file in the PyRETIS input file format.

  • settings (dict) – The dictionary to write
  • outfile (string) – The file to create
  • backup (boolean, optional) – If True, we will backup existing files with the same file name as the provided file name.


This will currently fail if objects have made it into the supplied settings.