pyretis.analysis package¶
This package defines analysis tools for the PyRETIS program.
The analysis tools are intended to be used for analysis of the simulation output from the PyRETIS program. The typical use of this package is in post-processing of the results from a simulation (or several simulations).
Package structure¶
Modules¶
- __init__.py
This file, imports from the other modules. The method to analyse results from MD flux simulations is defined here since it will make use of analysis tools from energy_analysis.py and order_analysis.py.
- analysis.py (
pyretis.analysis.analysis) General methods for numerical analysis.
- energy_analysis.py (
pyretis.analysis.energy_analysis) Defines methods useful for analysing the energy output.
- histogram.py (
pyretis.analysis.histogram) Defines methods useful for generating histograms.
- order_analysis.py (
pyretis.analysis.order_analysis) Defines methods useful for analysis of order parameters.
- path_analysis.py (
pyretis.analysis.path_analysis) Defines methods for analysis of path ensembles.
Important methods defined in this package¶
- analyse_energies (
analyse_energies()) Analyse energy data from a simulation. It will calculate a running average, a distribution and do a block error analysis.
- analyse_flux (
analyse_flux()) Analyse flux data from a MD flux simulation. It will calculate a running average, a distribution and do a block error analysis.
- analyse_orderp (
analyse_orderp()) Analyse order parameter data. It will calculate a running average, a distribution and do a block error analysis. In addition, it will analyse the mean square displacement (if requested).
- analyse_path_ensemble (
analyse_path_ensemble()) Analyse the results from a single path ensemble. It will calculate a running average of the probabilities, a crossing probability, perform a block error analysis, analyse lengths of paths, type of Monte Carlo moves and calculate an efficiency.
- match_probabilities (
match_probabilities()) Method to match probabilities from several path simulations. Useful for obtaining the overall crossing probability.
- histogram (
histogram()) Generates histogram, basically a wrapper around numpy’s
histogram.- match_all_histograms (
match_all_histograms()) Method to match histograms from umbrella simulations.
- retis_flux (
retis_flux()) Method for calculating the initial flux for RETIS simulations.
- retis_rate (
retis_rate()) Method for calculating the rate constant for RETIS simulations.
- construct_M (
construct_M()) Build the partial-path (REPPTIS) MSM transition matrix from the local crossing probabilities.
- global_pcross_msm (
global_pcross_msm()) Global crossing probability from a REPPTIS MSM transition matrix.
- mfpt_to_first_last_state (
mfpt_to_first_last_state()) Mean first passage time between the boundary states of a REPPTIS MSM (used for the flux and rate of slow permeation processes).
- pyretis.analysis._energy_rows(energydata)¶
Return the names of the columns of energy data and their rows.
- Parameters:
energydata (dict or None) – The columns of an energy file by name, the steps under ‘time’ (
pyretis.inout.formats.energy.EnergyFormatter.load()); None, or an empty list, for no energy data.- Returns:
names (list of strings) – The names of the columns, ‘time’ first.
rows (numpy.array or None) – The rows, one per step, the step first and the columns in the order of names; None when the data hold no row.
- Raises:
ValueError – When the data are not a dict that holds the steps under ‘time’, nor empty.
- pyretis.analysis._refuse_no_rows(rows, name)¶
Stop the analysis of energy data or order data without rows.
- Parameters:
rows (numpy.array) – The rows that the part keeps (
pyretis.analysis.flux_parts.RunParts.kept_rows()).name (string) – ‘energy’ or ‘order’, for the message.
- Raises:
ValueError – When there is no row, with the functions that analyse the data there are.
- pyretis.analysis.analyse_md_flux(crossdata, energydata, orderdata, settings)¶
Analyse the output from a MD-flux simulation.
The obtained results will be returned as a convenient structure for plotting or reporting. The data are the rows of the files of a run without start lines, as
pyretis.inout.analysisio.analysisio.read_first_block()gives them (it refuses the files of a run of this version, whichpyretis.inout.analysisio.analysisio.analyse_file()reads), and they are read by the rules of such files (pyretis.analysis.flux_parts.data_run_parts()): one part from the step of the first row of the order data or the energy data, which ends at the last such row (or, without such a row, at the end that the settings give, with a note). The analysis stops when the steps of the data, or the restart file that the settings name, show that the data may not hold one whole run; the backups of the settings file that the directory of a run can hold, whichpyretis.inout.analysisio.analysisio.analyse_file()reads as one more sign, are not looked for, since the data come from no directory. The flux, energy and order parameter analyses then read the part aspyretis.inout.analysisio.analysisio.analyse_file()reads it from the files: the same data give the same results, or the same stop. What the analyses leave out of the data, or read in a way the user should know, is logged as a warning.- Parameters:
crossdata (list of tuples) – This is the data containing information about crossings: for each crossing, the step, the interface number (counted from 1) and the direction (1 or -1).
energydata (dict) – This is the raw data for the energies: the columns of an energy file by name, the steps under ‘time’ (
pyretis.inout.formats.energy.EnergyFormatter.load()).orderdata (numpy.array) – This is the raw data for the order parameter: the rows of an order file, the step in the first column.
settings (dict) – The settings for the analysis (e.g block length for error analysis) and some settings from the simulation (interfaces, time step etc.).
- Returns:
results (dict) – This dict contains the results from the different analysis as a dictionary. This dict can be used further for plotting or for generating reports.
- Raises:
pyretis.analysis.flux_parts.PartsStop – When the data may not hold one whole run, with the message that says why (
unmarked_parts_problem()).pyretis.analysis.flux_analysis.FluxAnalysisStop – When the flux analysis gives no flux for the run, with the message that says why (
analyse_flux()).ValueError – When the energy data or the order data hold no row, as
pyretis.inout.analysisio.analysisio.analyse_file()stops the analysis of a file without rows; and when the energy data are not the columns of an energy file by name.
List of submodules¶
pyretis.analysis.analysis module¶
Module defining functions useful in the analysis of simulation data.
Important methods defined here¶
- running_average (
running_average()) Method to calculate a running average.
- block_error (
block_error()) Perform block error analysis.
- block_error_corr (
block_error_corr()) Method to run a block error analysis and calculate relative errors and correlation length.
- pyretis.analysis.analysis.analyse_data(data, settings, segments=None)¶
Analyse the given data and run some common analysis procedures.
Specifically, it will:
Calculate a running average.
Obtain a histogram.
Run a block error analysis.
- Parameters:
data (numpy.array, 1D) – This numpy.array contains the data as a function of time.
settings (dict) – This dictionary contains settings for the analysis.
segments (list of ints, optional) – The number of points of each segment of the data, as the rows of the parts of a run: the running average and the histogram take every point, and a block of the block error analysis holds points of one segment (
block_error()). None for data of one segment.
- Returns:
result (dict) – This dict contains the results.
- pyretis.analysis.analysis.block_error(data, maxblock=None, blockskip=1, weights=None, segments=None)¶
Perform block error analysis.
This function will estimate the standard deviation in the input data by performing a block analysis. The number of blocks to consider can be specified or it will be taken as the half of the length of the input data. Averages and variance are calculated using an on-the-fly algorithm [1].
Data made of segments, as the rows of the parts of a run, are cut into blocks within each segment, from its first point; the points at the end of a segment that do not fill a block are left out, as those at the end of the data are. The blocks of all segments give the averages and the errors, and the longest block is the longest that gives two blocks (
longest_block()).- Parameters:
data (numpy.array (or iterable with data points)) – The data to analyse.
maxblock (int, optional) – Can be used to set the maximum length of the blocks to consider. Note that the maxblock will never be set longer than half the length in data.
blockskip (int, optional) – This can be used to skip certain block lengths, i.e. blockskip = 1 will consider all blocks up to maxblock, while blockskip = n will consider every n’th block up to maxblock, i.e. it will use block lengths equal to 1, 1 + n, 1 + 2*n, and so on.
weights (numpy.array (or iterable with weights), optional) – The weight of each data point, for a weighted average and variance. When it is not given, the points of a one-dimensional data weigh the same, and a two-dimensional data holds the data points in its first column and their weights in its second.
segments (list of ints, optional) – The number of points of each segment of the data, in order; None for data of one segment.
- Returns:
blocklen (numpy.array) – These contain the block lengths considered.
block_avg (numpy.array) – The averages as a function of the block length.
block_err (numpy.array) – Estimate of errors as a function of the block length.
block_err_avg (float) – Average of the error estimate using blocks where
length > maxblock//2.
References
- pyretis.analysis.analysis.block_error_corr(data, maxblock=None, blockskip=1, segments=None)¶
Run block error analysis on the given data.
This will run the block error analysis and return the relative errors and correlation length.
- Parameters:
data (numpy.array) – Data to analyse.
maxblock (int, optional) – The maximum block length to consider.
blockskip (int, optional) – This can be used to skip certain block lengths, i.e. blockskip = 1 will consider all blocks up to maxblock, while blockskip = n will consider every n’th block up to maxblock, i.e. it will use block lengths equal to 1, 1 + n, 1 + 2*n, and so on.
segments (list of ints, optional) – The number of points of each segment of the data, whose blocks hold points of one segment only (
block_error()); None for data of one segment.
- Returns:
out[0] (numpy.array) – These contains the block lengths considered (blen).
out[1] (numpy.array) – Estimate of errors as a function of the block length (berr).
out[2] (float) – Average of the error estimate for blocks (berr_avg) with
length > maxblock // 2.out[3] (numpy.array) – Estimate of relative errors normalised by the overall average as a function of block length (rel_err).
out[4] (float) – The average relative error (avg_rel_err), for blocks with
length > maxblock // 2.out[5] (numpy.array) – The estimated correlation length as a function of the block length (ncor).
out[6] (float) – The average (for blocks with length > maxblock // 2) estimated correlation length (avg_ncor).
- pyretis.analysis.analysis.block_error_problem(rows, maxblock=None, blockskip=1, name='the file', output_key=None, segments=None)¶
Say why a block error analysis of rows gives no average error.
block_error()takes blocks of 1,1 + blockskip,1 + 2 * blockskip, … rows, up to the longest block: half the rows, ormaxblockwhen it is 1 or more and shorter. For rows of several parts of a run, a block holds rows of one part, and the longest block is the longest that gives two blocks (longest_block()). It averages the errors of the blocks longer than half the longest block, and gives NaN when there is no such block.- Parameters:
rows (int) – The number of rows of the data.
maxblock (int, optional) – The longest block asked for,
[analysis] maxblock.blockskip (int, optional) – The steps between the lengths of two blocks,
[analysis] blockskip.name (string, optional) – The file that holds the rows, for the message.
output_key (string, optional) – The
[output]key that sets how often the run writes the file, for the message; None when there is none.segments (list of ints, optional) – The number of rows of each part of the run, when the rows are of several parts; None for rows of one part.
- Returns:
out (string or None) – Why there is no average error, and what to set, as the end of a sentence; None when there is one.
- pyretis.analysis.analysis.longest_block(segments)¶
Return the longest block that gives two blocks of segments of data.
A block holds consecutive points of one segment: the points of two segments are never in one block. A block length gives two full blocks or more when a segment holds two blocks of it, or two segments hold one each.
- Parameters:
segments (list of ints) – The number of points of each segment.
- Returns:
out (int) – The longest block length that gives two full blocks or more: half the points of a single segment.
- pyretis.analysis.analysis.mean_square_displacement(data, ndt=None, segments=None)¶
Calculate the mean square displacement for the given data.
- Parameters:
data (numpy.array, 1D) – This numpy.array contains the data as a function of time.
ndt (int, optional) – This parameter is the number of time origins. I.e. points up to ndt will be used as time origins. If not specified the value of the input
data.size // 5will be used.segments (list of ints, optional) – The number of points of each segment of the data, as the rows of the parts of a run: the displacements are taken within each segment, and pooled over the segments. None for data of one segment.
- Returns:
msd (numpy.array, 2D) – The first column is the mean squared displacement and the second column is the corresponding standard deviation.
- pyretis.analysis.analysis.running_average(data)¶
Create a running average of the given data.
The running average will be calculated over the rows.
- Parameters:
data (numpy.array) – This is the data we will average.
- Returns:
out (numpy.array) – The running average.
pyretis.analysis.biretis_analysis module¶
The rates of a bidirectional RETIS (biretis) run.
The analysis reads the pathensemble.txt of each ensemble of the run
(pyretis.core.biretis.biretis_windows() gives the layout) and
gives
the flux out of each state, from the path lengths of its
[0^-]and its[0^+]:f = 1 / ((<L0-> - 2 + <L0+> - 2) dt);the crossing probability of each state, the product of the local crossing probabilities of its ladder and of the shared ensembles;
k_AB = f_A P_A,k_BA = f_B P_BandK = k_AB / k_BA.
A shared ensemble holds each reactive path in both orientations, one per family, with equal weight. Its local crossing probability for state A counts the paths that start in A and cross the next A interface, and half of the reactive paths of both orientations:
P_A = (c_AA + (n_AB + n_BA) / 2) / (n_AA + (n_AB + n_BA) / 2),
and the same for state B. As in the crossing analysis of the other
tasks, the rows of the initialisation paths (a kicked or loaded path,
pyretis.core.path.INITIAL_MOVES) are not samples of their
ensemble and are left out. The errors are the standard errors over
blocks of cycles. [analysis] skip_initial_cycles and
skip_final_cycles leave out cycles at the start and the end, as for
the other tasks (pyretis.analysis.path_analysis.initial_skip()
and pyretis.analysis.path_analysis.final_skip()).
The layout of the input gives each ensemble directory its role, and the
analysis reads the run with the layout of the run: an input whose
interfaces, interfaces_b or shared differ from the ones the
run recorded, a run with an ensemble directory beyond the layout or
without one of it, and a row whose start side is not one of its slot’s
role are refused, and the message says to analyse the run with the
input of the run (or with -i output.toml, where the run directory
holds one); without a record of the windows, the message for a directory
beyond the layout names the other layout and an earlier run in the same
directory as its causes, and adds that the directory can be moved out of
the run directory. When the run recorded the windows of the input in its
output.toml, the layout is the run’s: an ensemble directory beyond
it (left by an earlier run in the same directory) is left out of the
analysis, and a warning names it.
- pyretis.analysis.biretis_analysis.analyse_biretis(settings, run_path)¶
Return the rates of a biretis run and their block errors.
- Parameters:
settings (dict) – The settings of the run.
run_path (string) – The directory of the run.
- Returns:
out (dict) – The estimates of
_estimates()over the cycles analysed, anderrors, the standard error of each rate overN_BLOCKSblocks of cycles, None where a block gives no estimate or one of zero.- Raises:
ValueError – If the
moves.txtof an ensemble does not record the MD of each move, which tells the initialisation paths apart (sampled_rows()), if the skips leave out every recorded cycle or leave fewer cycles than blocks (pyretis.inout.pathensemble_output.skip_cycle_bounds()), or if neither[engine]nor the input of the engine gives the time step (pyretis.core.engine_time.engine_time_per_step()), or if the windows ofsettingsare not the run’s: the run recorded other windows (refuse_other_windows()), the run has an ensemble directory beyond the layout and recorded no windows (_check_directories_beyond_the_layout()) or lacks one of it (_refuse_missing_directories()), or a row the analysis uses starts on a side the role of its slot has not (_refuse_rows_of_another_role()).
- pyretis.analysis.biretis_analysis.format_biretis_report(result)¶
Return the text report of a biretis analysis.
- Parameters:
result (dict) – What
analyse_biretis()returns.- Returns:
out (string) – The report.
- pyretis.analysis.biretis_analysis.read_occupancy_rows(filename)¶
Read the occupancy rows of a
pathensemble.txt.- Parameters:
filename (string) – The file.
- Returns:
out (dict of numpy.ndarray) – The cycle (
step), the start and end flags (l,r), the move (move), the length, the smallest and largest order (min_o,max_o) and the occupancy (frac) of each row of a path the ensemble held; the rows of attempted moves (pyretis.inout.formats.pathensemble.row_is_trial()) are left out.
- pyretis.analysis.biretis_analysis.sampled_rows(rows)¶
Return the rows of the paths that are samples of their ensemble.
The rows of an initialisation path, a path whose move is one of
pyretis.core.path.INITIAL_MOVES, are left out. This is the rule ofpyretis.core.path.continues_initialisation()for a run that records the MD of each move inmoves.txt, as a biretis run does.- Parameters:
rows (dict of numpy.ndarray) – What
read_occupancy_rows()returns.- Returns:
out (dict of numpy.ndarray) – The rows of the sampled paths.
pyretis.analysis.energy_analysis module¶
Methods for analysing energy data from simulations.
Important methods defined here¶
- analyse_energies (
analyse_energies()) Run the analysis for energies (kinetic, potential etc.).
- energy_analysis_stop (
energy_analysis_stop()) Say why the settings let the energy analysis not run.
- run_particle_number (
run_particle_number()) Return the number of particles of the run that the settings give.
- run_temperature_dof (
run_temperature_dof()) Return the degrees of freedom of the temperature of the run that the settings give.
- is_particle_number (
is_particle_number()) Return whether a value is a number of particles.
- unread_record_message (
unread_record_message()) Say that the analysis reads no number of particles or degrees of freedom of the run.
- differing_npart_message (
differing_npart_message()) Say that a stated number of particles differs from the recorded one.
- curve_stop (
curve_stop()) Say why the energy analysis draws no Boltzmann distribution.
- undrawn_curves_message (
undrawn_curves_message()) Say that the particles of the run let no Boltzmann distribution be drawn.
- ineffective_npart_message (
ineffective_npart_message()) Say that a stated number of particles is used for no Boltzmann distribution.
- format_dof (
format_dof()) Give degrees of freedom, one for each dimension, as text.
- pyretis.analysis.energy_analysis.analyse_energies(energies, settings, segments=None)¶
Run the energy analysis on several energy types.
The function will run the energy analysis on several energy types and collect the energies into a structure which is convenient for plotting the results.
The Boltzmann distributions of the kinetic energy and the temperature are drawn with the number of particles N of the run (
run_particle_number()) and the degrees of freedom of its temperature (run_temperature_dof()): n_i in the dimension i, and f, the sum of the n_i. The run’s temperature (pyretis.core.particlefunctions.calculate_kinetic_temperature()) is the average over the dimensions of 2 K_i / (n_i k), with K_i the kinetic energy of the dimension i, whose Boltzmann distribution is the Gamma distribution of shape n_i / 2 and scale kT.- Parameters:
energies (dict) – This dict contains the energies to analyse.
settings (dict) – This dictionary contains settings for the analysis.
segments (list of ints, optional) – The number of rows of each part of the run, when the rows are of several parts (
pyretis.analysis.flux_parts): the averages and the distributions take every row, and the blocks of the block error analysis are taken within each part and pooled over the parts. None for rows of one part.
- Returns:
results (dict) – For each energy key results[key] contains the result from the energy analysis. The kinetic energy per particle (‘ekin’) and the temperature (‘temp’) also hold their Boltzmann distribution under ‘boltzmann-dist’: for the kinetic energy per particle, K / N, the Gamma distribution of shape f / 2 and scale kT / N; for the temperature, when all n_i are equal, the Gamma distribution of shape f / 2 and scale T / (f / 2). With unequal n_i the temperature holds no ‘boltzmann-dist’, and holds why under ‘boltzmann-undrawn’. When the settings give no particles of an internal engine, or no degrees of freedom of the run (
curve_stop()), neither holds a ‘boltzmann-dist’, and both hold why under ‘boltzmann-undrawn’. When the rows give no average block error (block_error_problem()), every energy holds why under ‘blockerror-uncomputed’, and the analysis logs it as a warning.- Raises:
ValueError – If the settings hold no
[system] temperature, or, for the Boltzmann distributions, give no number of particles of the run or degrees of freedom that can be used. The message says why (energy_analysis_stop()).
See also
- pyretis.analysis.energy_analysis.curve_stop(settings)¶
Return why no Boltzmann distribution is drawn, or None.
The energy analysis draws the Boltzmann distributions of the kinetic energy and the temperature for the particles of an internal engine, whose energy file holds the kinetic energy per particle and the temperature over the degrees of freedom of the run (
pyretis.core.particlefunctions.calculate_thermo()). It draws them when the analysis kept no reason against them from the record of the run (pyretis.inout.settings.UNDRAWN_CURVES, set bypyretis.inout.analysisio.analysisio.run_particle_settings()), the settings give[particles] type = 'internal', and they give the degrees of freedom of the run (run_temperature_dof()).- Parameters:
settings (dict) – The settings of the analysis.
- Returns:
out (string or None) – Why the energy analysis draws no Boltzmann distribution of the kinetic energy or of the temperature; None when it draws them.
- pyretis.analysis.energy_analysis.differing_npart_message(stated, recorded, record)¶
Return the stop message for a stated npart unlike the recorded one.
- Parameters:
stated (object) – The
[particles] npartthat the settings state.recorded (integer) – The number of particles that the record of the run holds.
record (string) – The record of the run, named for the message (for example, “the restart file <name>, which the run continues”).
- Returns:
out (string) – The message the energy analysis stops with: the stated number differs from the recorded one, with both numbers.
- pyretis.analysis.energy_analysis.energy_analysis_stop(settings)¶
Return why the energy analysis cannot run on settings, or None.
The energy analysis draws the Boltzmann distributions of the kinetic energy and the temperature at
[system] temperature, which the analysis reads from the record of the run (pyretis.inout.run_record.read_settings()), with the number of particles of the run (run_particle_number()) and the degrees of freedom of its temperature (run_temperature_dof()). Settings without the temperature let the energy analysis not run; so do settings that let it draw the distributions (curve_stop()) without a number of particles or degrees of freedom that it can use.- Parameters:
settings (dict) – The settings of the analysis.
- Returns:
out (string or None) – Why the energy analysis cannot run, with advice: for settings without
[system] temperature, why they hold none (_no_temperature_message()); for settings with it, why they give no number of particles or degrees of freedom of the run that can be used (_particle_number_problem()). None when the energy analysis runs.
- pyretis.analysis.energy_analysis.format_dof(counts)¶
Give degrees of freedom, one for each dimension, as text.
- Parameters:
counts (list of floats) – The degrees of freedom, one for each dimension.
- Returns:
out (string) – The numbers, separated by a comma, each without a fraction when it is a whole number.
- pyretis.analysis.energy_analysis.ineffective_npart_message(stated, checked)¶
Return the message for a stated npart that is used for no curve.
- Parameters:
stated (object) – The
[particles] npartthat the settings state.checked (integer or None) – The number of particles that the record of the run holds, when the analysis checked the stated number against it (
pyretis.inout.settings.CHECKED_NPART); else None.
- Returns:
out (string) – The message: the energy analysis, which draws no Boltzmann distribution, uses no number of particles; a stated number that the analysis checked against the record of the run takes no other effect, and any other takes no effect.
- pyretis.analysis.energy_analysis.is_particle_number(value)¶
Return whether a value is a number of particles.
- Parameters:
value (object) – The value.
- Returns:
out (boolean) – True for an integer, not a boolean, larger than zero.
- pyretis.analysis.energy_analysis.run_particle_number(settings)¶
Return the number of particles of the run that the settings give.
The settings give
[particles] npart. The analysis of an md-flux run sets it to the number of particles that the restart file of the run records, or keeps why it reads none (pyretis.inout.analysisio.analysisio.run_particle_settings()).[particles] mass, a table keyed by the name of a particle, gives no number of particles.- Parameters:
settings (dict) – The settings of the analysis.
- Returns:
out (object or None) –
[particles] npartwhen the settings hold it; None when they hold none, and when the analysis kept why it reads no number of particles of the run (pyretis.inout.settings.UNRESOLVED_PARTICLES).
- pyretis.analysis.energy_analysis.run_temperature_dof(settings)¶
Return the degrees of freedom of the run’s temperature, or None.
The settings give them under
[analysis]pyretis.inout.settings.RUN_TEMPERATURE_DOF: for each dimension of the velocities, the number of degrees of freedom that the temperature of the run divides the kinetic energy of that dimension by. The analysis of an md-flux run reads them from the restart file of the run (pyretis.inout.analysisio.analysisio.run_particle_settings()).- Parameters:
settings (dict) – The settings of the analysis.
- Returns:
out (object or None) – The degrees of freedom, one for each dimension, when the settings hold them; None when they do not.
- pyretis.analysis.energy_analysis.undrawn_curves_message(reason)¶
Return the message for Boltzmann distributions that are not drawn.
- Parameters:
reason (string) – What the record of the run or the settings give instead of the particles of an internal engine and the degrees of freedom of its temperature, without a final full stop.
- Returns:
out (string) – The message of the energy analysis: it draws no Boltzmann distribution of the kinetic energy or of the temperature, and why.
- pyretis.analysis.energy_analysis.unread_record_message(reason)¶
Return the stop message for a record of the run not read.
- Parameters:
reason (string) – Why the analysis reads no number of particles or degrees of freedom of the run, with advice, without a final full stop.
- Returns:
out (string) – The message the energy analysis stops with.
pyretis.analysis.flux_analysis module¶
Methods for analysis of crossings for flux data.
Important methods defined here¶
- analyse_flux (
analyse_flux()) Run analysis for simulation flux data. This will calculate the initial flux for a simulation.
- check_flux_settings (
check_flux_settings()) Stop the flux analysis of a run whose settings give crossings that it cannot read.
- FluxAnalysisStop (
FluxAnalysisStop) The error by which the flux analysis says why a run gives no flux.
- exception pyretis.analysis.flux_analysis.FluxAnalysisStop¶
Bases:
ValueErrorWhy the flux analysis of a run gives no flux.
analyse_flux()andcheck_flux_settings()raise it with a message that says why the settings or the output of the run give no flux, and what to do instead.pyretis analysethen stops the flux analysis alone: the other analyses of the run run, and the report says why it holds no flux (pyretis.inout.analysisio.analysisio.run_analysis_files()).
- class pyretis.analysis.flux_analysis.FluxPart(key, start, end, start_line, crossings, start_order=None, source=None, lines=None)¶
Bases:
objectOne part of an md-flux run, as the flux analysis reads it.
- Variables:
key (tuple of ints or None) – The part number and the start step of the part, as its start line gives them; None for a run without start lines.
start (int) – The step the part starts at.
end (int or None) – The last step of the part that is analysed. None when nothing shows where the part ended: it holds no time to analyse.
start_line (dict or None) – The start line of the part (
pyretis.core.flux_state.parse_part_line()), which gives the state of the run at the start of the part; None for a run without start lines, whose state follows from its crossings or from start_order.crossings (list of tuples) – The crossings of the part up to end: the step, the interface number counted from 1 and the direction (1 or -1), in the order of the steps and, within a step, of the interfaces.
start_order (float or None) – For a run without start lines, its order parameter at its first step, as its order file holds it (
first_order()); None when it is not known.source (string or None) – The name of the file that holds the crossings, for the messages; None for crossings that no file gives.
lines (list of ints or None) – For each crossing, the number of its line in source (counted from 1); None when no file gives them.
- __init__(key, start, end, start_line, crossings, start_order=None, source=None, lines=None)¶
Set the part.
- pyretis.analysis.flux_analysis.analyse_flux(fluxdata, settings, start_order=None, parts=None)¶
Run the analysis on the given flux data.
This will run the flux analysis and collect the results into a structure which is convenient for plotting and reporting the results.
The flux of an interface is its number of effective crossings divided by the time spent in the overall state A. A run written in parts (
pyretis.analysis.flux_parts) is analysed part by part, from the state of the run at the start of each part, and the parts are pooled; no two parts are joined. The time of each part in the overall state A is cut into windows ofanalysis.skipcrosssteps (_calculate_flux), and the windows of all the parts, in the order of the parts, give the running average of the flux and its block error. Each window counts in both with its length (_weighted_windows), so the running average at the end of the last window is the number of effective crossings divided by the time spent in the overall state A.A part whose state at its start is not known, a fresh run that starts outside A and outside B (outside A for a run with fewer than three interfaces, which has no state B), counts no time and no crossing up to its first entry into A or B (
_count_part).Without parts, fluxdata is the crossing data of a run without start lines from step 0 to the end of the run that its settings give (
run_end_step()). The crossings of such a run give the side of each interface that the run starts on (_start_sides); a run that crosses no interface stays on the side of each interface that it starts on, which its order parameter at its first step gives (start_order,_sides_without_crossing).- Parameters:
fluxdata (list of tuples of integers) – This array contains the data obtained from a MD simulation for the fluxes: for each crossing, the step, the interface number (counted from 1) and the direction (1 or -1), in the order of the steps and, within a step, of the interfaces. It is not read when parts is given.
settings (dict) – This dict contains the settings for the analysis. Note that this dictionary also needs some settings from the simulation, in particular the number of cycles, the interfaces and information about the time step.
start_order (float, optional) – The order parameter of the run at its first step, as the order file of the run holds it: the first row of
order.txt(first_order()). The analysis reads it when fluxdata holds no crossing. None when it is not known. It is not read when parts is given.parts (list of objects like
FluxPart, optional) – The parts of the run, in the order of the run (pyretis.analysis.flux_parts.RunParts.flux_parts()).
- Returns:
results (dict) – This dict contains the results from the flux analysis. The keys are defined in the results variable; ‘parts’ holds, for each part, its key, its start and end, the step from which it is counted (‘counted_from’, None when it never is) and its times in the states.
- Raises:
FluxAnalysisStop – When
check_flux_settings()stops the analysis; when the settings give no time step; when a run without start lines holds no crossing and start_order does not tell the state the run stayed in (_sides_without_crossing); when a start line gives the sides of another number of interfaces than the settings; whenanalysis.skipcrossis not positive; when the run spends no step in the overall state A, as a run that starts in B and never enters A; when no part shows where it ended (_no_end_message); when it spends less than one window in the overall state A; and when the crossings are not those of an md-flux run: a crossing that does not follow the state of the run, or that is outside the steps of its part (_count_part), or sides at the start that no run is in (_part_state).
- pyretis.analysis.flux_analysis.check_flux_settings(settings)¶
Stop the flux analysis of a run whose crossings it cannot read.
The flux analysis takes the first interface as the boundary of the state A and, with three interfaces or more, the last as the boundary of the state B, so the run must have one interface or more, sorted from small to large (
pyretis.inout.checker.mdflux_interfaces_problem()); and it counts every crossing of the run, which a run with[output] cross-fileabove 1 does not write (pyretis.inout.checker.mdflux_cross_file_problem()).- Parameters:
settings (dict) – The settings of the run. Settings without
[output] cross-filegive a run that wrote every crossing.- Raises:
FluxAnalysisStop – When the run has no interface, or its interfaces are not sorted, or
[output] cross-fileis above 1, with the message that says what to do.
- pyretis.analysis.flux_analysis.find_crossings(order, interfaces)¶
Find crossings with interfaces for given order parameter data.
- Parameters:
order (numpy.array (1D)) – Order parameters, as a function of time.
interfaces (list of floats) – The interfaces for which we will investigate crossings.
- Returns:
out (list of tuple) – Each tuple contains the crossings on the following form: (step, interface-number, direction), where direction = ‘+’ if the interface was crossed while moving to the right and ‘-’ if the movement was towards the left.
- pyretis.analysis.flux_analysis.first_order(orderdata)¶
Return the order parameter of the first row of order data.
- Parameters:
orderdata (numpy.array or None) – The rows of an order file: the step, the order parameter and any collective variables (
pyretis.inout.formats.order.OrderFormatter).- Returns:
out (float or None) – The order parameter of the first row, the first step the order file holds; None when there is no row.
- pyretis.analysis.flux_analysis.run_end_step(settings)¶
Return the last step of an md-flux run, as its settings give it.
- Parameters:
settings (dict) – The settings of the run.
- Returns:
out (int or None) –
[simulation] endcycle, or[simulation] stepswhen the settings give no end cycle.
pyretis.analysis.flux_parts module¶
The parts of an md-flux run, as its output files hold them.
An md-flux run is written in parts: a fresh run is part 1, and each
continuation of a restart file is the part after the part that wrote
the restart file (pyretis.core.flux_state). Each part writes
a start line where it starts writing order.txt, energy.txt and
cross.txt, and an end line where it stops writing them at a normal
end, a soft exit or an error; a part that is killed writes no end line.
The part number and the start step are the key of a part, which its
lines share in the three files.
The analysis reads the parts of each file in the order of the file and never joins two parts:
A start line at step S drops, in the same file, the rows of every earlier part from step S on and the crossings of every earlier part after step S: the later part made those steps again. The later part keeps its own row of step S. The crossings of step S stay with the earlier part, whose state after them is the state the later part starts from. A part that starts again at the step of an earlier part with the same key (a continuation started twice from one restart file) so replaces it, and a fresh run started again in the same directory replaces every part before it.
A part ends at the step of its end line; a part without an end line ends at its last row of
order.txtorenergy.txt. A part with neither holds no time to analyse, and its crossings are left out. Crossings after the end of a part are left out too.The parts kept by the rule above are matched by their key across the three files. A part with rows in
order.txtorenergy.txtand no start line incross.txtdid not write its crossings, and the flux analysis stops (RunParts.flux_parts()).Files without start lines, as an md-flux run of a PyRETIS without them writes, hold one part from their first row to their last row. When they hold no row of
order.txtorenergy.txt(a run that wrotecross.txtalone), the part ends at the end that the settings of the run give, and the log and the report say so: a run that stopped before it is counted up to it. When their steps, the restart file that their settings name, or backups of the settings file in the directory show that they may hold a part that does not start the run, or more than one part (unmarked_parts_problem()), the flux, energy and order parameter analyses stop.
Important classes defined here¶
Important methods defined here¶
- read_run_parts (
read_run_parts()) Read the parts of a run from its files.
- data_run_parts (
data_run_parts()) Read the parts of a run from the rows of its files.
- pyretis.analysis.flux_parts.PART_FILE_TYPES = ('cross', 'energy', 'order')¶
The files of an md-flux run that hold its parts, by their type.
- exception pyretis.analysis.flux_parts.PartsStop¶
Bases:
ValueErrorWhy the files of an md-flux run give no analysis.
read_run_parts()gives it (RunParts.stop) when the files hold several parts without start lines, or lines and rows that no md-flux run writes. The flux, energy and order parameter analyses of the run then stop, with its message.
- class pyretis.analysis.flux_parts.RunParts(blocks, settings, directory, stop=None)¶
Bases:
objectThe parts of an md-flux run that its files hold.
- Variables:
blocks (dict) – For each file type, the parts in the order of the file (
read_part_blocks()), cut by the drop rule.marked (boolean) – True when the files hold start lines.
stop (string or None) – Why the flux, energy and order parameter analyses do not run (
PartsStop); None when they run.notes (list of strings) – What the analyses leave out of the files, or read in a way the user should know, for the log and the report.
parts (list of dicts) – One dict per part kept in any file, in the order of their start steps: ‘key’, ‘start’, ‘end’, ‘ended’ (how it ended), ‘analysed’ (the last step analysed) and ‘dropped’ (what the drop rule and the end of the part leave out, by file type).
- __init__(blocks, settings, directory, stop=None)¶
Read the parts from the blocks of the files.
- Parameters:
blocks (dict) – For each file type that the run wrote, its parts (
read_part_blocks()).settings (dict) – The settings of the run.
directory (string or None) – The directory of the run; None for rows that no directory holds (
data_run_parts()).stop (string, optional) – Why the files give no analysis, when reading them said so (
PartsStop): the blocks are then not read.
- _end_of(key)¶
Return the end of a part and how it ended.
- Parameters:
key (tuple of ints or None) – The key of the part; None for files without start lines.
- Returns:
end (int or None) – The step of its end line; without one, the step of its last row of
order.txtorenergy.txt; for files without start lines and without such a row, the end that the settings give (pyretis.analysis.flux_analysis.run_end_step()); None otherwise.ended (string) – How the part ended: the end of its end line (‘normal end’, ‘soft exit’ or ‘error’), ‘no end line’ for a part that ends at its last row, ‘from the settings’ for a part that ends where the settings give, or ‘no row and no end line’.
- Raises:
PartsStop – When the end lines of the part in two files give two different ends.
- _note_earlier_parts()¶
Note that the files hold the run from a part after its first.
A continuation in a folder of its own, or in the folder of the run with
backup = "backup", writes files whose first start line is that of a later part: the analyses cover the steps of the parts in the files only.
- _note_later_end()¶
Note how the end of a run without start lines is taken.
A run whose files hold no start line ends at its last row of
order.txtorenergy.txt; when the settings of the run give a later end ([simulation] endcycle, orsteps), the run stopped before it, or wrote no row of its last steps. A run without such a row ends where its settings give, which no row shows: a run that stopped before it is counted up to it.
- _part_of(key)¶
Return the part of a key.
- _parts_without_crossings()¶
Return the parts with rows and no start line in cross.txt.
- Returns:
out (list of tuples) – The keys of the parts kept in
order.txtorenergy.txtwith a row there, and without a start line incross.txt.
- _set_parts()¶
Set the parts that the files keep, with their ends and drops.
- _start_order()¶
Return the first order parameter of a run without start lines.
- Returns:
out (float or None) – The order parameter of the first row of
order.txt, when the files hold no start line and that row is of the step the run starts at; None otherwise.
- _start_unmarked_blocks()¶
Give the rows of files without start lines their start step.
The run starts at the step of the first row of
order.txtorenergy.txt(unmarked_parts_problem()checks that it is step 0 or[simulation] startcycle), or, without such a row, at[simulation] startcycle.
- flux_parts()¶
Return the parts of the run as the flux analysis reads them.
- Returns:
out (list of objects like) –
pyretis.analysis.flux_analysis.FluxPartThe parts kept incross.txt, in the order of the file.- Raises:
PartsStop – When the analyses of the run stop (
stop).pyretis.analysis.flux_analysis.FluxAnalysisStop – When a part with rows in
order.txtorenergy.txthas no start line incross.txt: it did not write every crossing, and the flux analysis stops alone.
- kept_rows(file_type)¶
Return the rows of a file that the analyses read.
- Parameters:
file_type (string) – ‘order’ or ‘energy’.
- Returns:
rows (numpy.array) – The rows kept of every part (the drop rule, the end of each part), in the order of the file, the step in the first column.
segments (list of ints) – The number of rows of each part that keeps rows, in the same order: rows of two parts are never joined.
- Raises:
PartsStop – When the analyses of the run stop (
stop).
- table(flux_parts=None)¶
Return one row per part for the report.
- Parameters:
flux_parts (list of dicts, optional) – What the flux analysis counted of each part (
pyretis.analysis.flux_analysis.analyse_flux(), ‘parts’ of its result): ‘key’, ‘counted_from’ and ‘OA’. None when the flux analysis did not run.- Returns:
out (list of lists of strings) – For each part: the part number, its start step, its end step, how it ended, the step from which the flux counts it, its time in the overall state A and what the analyses leave out of it.
- pyretis.analysis.flux_parts.data_run_parts(crossdata, energyrows, orderdata, settings)¶
Read the parts of an md-flux run from its rows.
The rows are those of the files of a run without start lines, as
pyretis.inout.analysisio.analysisio.read_first_block()gives them, and they are read by the rules of such files (RunParts): one part from the step of the first row oforder.txtorenergy.txt, which ends at the last such row, or, without such a row, at the end that the settings of the run give, with a note. The steps of the rows and the restart file that the settings name show when the rows may not hold one whole run (unmarked_parts_problem()); the backups of the settings file, which a directory holds, are not looked for: the rows come from no directory.- Parameters:
crossdata (list of tuples or None) – The crossings of the run: the step, the interface number (counted from 1) and the direction (1 or -1).
energyrows (list of lists or None) – The rows of the energy file of the run, the step first.
orderdata (numpy.array or None) – The rows of the order file of the run, the step first.
settings (dict) – The settings of the run.
- Returns:
out (object like
RunParts) – The parts of the run; itsRunParts.stopsays why the analyses do not run.
- pyretis.analysis.flux_parts.read_part_blocks(file_type, file_name)¶
Read what each part of a run wrote to one of its files.
The lines of the file are read in order: a start line opens a part, an end line closes the part it names, and each row belongs to the part that is open. Rows before the first start line form a block without a key.
- Parameters:
file_type (string) – ‘cross’, ‘energy’ or ‘order’.
file_name (string) – The file.
- Returns:
out (list of objects like
_FileBlock) – The parts in the order of the file.- Raises:
PartsStop – When an end line closes no open part, or names another part than the open one; when a row follows the end line of its part; when a part holds a row before its start step, or rows whose steps go back (for
energy.txtandorder.txt: a step that is not after the step of the row above it).
- pyretis.analysis.flux_parts.read_run_parts(files, settings, directory)¶
Read the parts of an md-flux run from its files.
- Parameters:
files (dict) – The files of the run that exist, by type (‘cross’, ‘energy’, ‘order’).
settings (dict) – The settings of the run.
directory (string) – The directory of the run.
- Returns:
out (object like
RunParts) – The parts of the run; itsRunParts.stopsays why the analyses do not run.
- pyretis.analysis.flux_parts.unmarked_parts_problem(blocks, settings, directory)¶
Say whether files without start lines may not hold one whole run.
Files without start lines are written by an md-flux run of a PyRETIS that does not mark the parts of a run. Their steps show more than one part when a step repeats or goes back in one of them, or when the first row of
order.txtorenergy.txtis after step 0 and is not the[simulation] startcycleof the settings (the files start where an earlier part stopped). The settings of a run that continues an earlier run name the restart file it starts from ([simulation] restart): its files start where the earlier part stopped, which files without rows oforder.txtandenergy.txtdo not show. Backups of the settings file of a run in the directory (out.tomlorout.rstfollowed by_000,_001, …), which a run makes when it starts where a run ran before, show that the files may hold more than one run; a run started again with[output] backup = "backup"leaves them beside the files of one run. Rows that no directory holds (data_run_parts()) show no backups.- Parameters:
blocks (dict) – For each file type, the rows of the file as one block (
read_part_blocks()); an empty list for a file without rows.settings (dict) – The settings of the run.
directory (string or None) – The directory of the run; None for rows that no directory holds.
- Returns:
out (string or None) – The message that names each sign found and what to do; None when no sign is found.
pyretis.analysis.histogram module¶
Histogram functions for data analysis.
This module defines some simple functions for histograms.
Important methods defined here¶
- histogram (
histogram()) Create a histogram from given data.
- match_all_histograms (
match_all_histograms()) Function to match histograms, for instance from an umbrella sampling simulation.
- histogram_and_avg (
histogram_and_avg()) Create a histogram and return bins, midpoints and simple statistics.
- pyretis.analysis.histogram.histogram(data, bins=10, limits=(-1, 1), density=False, weights=None)¶
Create a histogram of the given data.
- Parameters:
data (numpy.array) – The data for making the histogram.
bins (int, optional) – The number of bins to divide the data into.
limits (tuple/list, optional) – The max/min values to consider.
density (boolean, optional) – If True the histogram will be normalized.
weights (numpy.array, optional) – Weighting factors for data.
- Returns:
hist (numpy.array) – The binned counts.
bins (numpy.array) – The edges of the bins.
bin_mid (numpy.array) – The midpoint of the bins.
- pyretis.analysis.histogram.histogram_and_avg(data, bins, density=True, weights=None)¶
Create histogram an return bins, midpoints and simple statistics.
The simple statistics include the mean value and the standard deviation. The return structure is useful for plotting routines. The midpoints returned are the midpoints of the bins.
- Parameters:
data (either 1D numpy.array or 2D numpy.array) – This is the data to create the histogram from. The eventual second dimension contains the weights.
bins (int) – The number of bins to use for the histogram.
density (boolean, optional) – If density is true, the histogram will be normalized.
weights (numpy.array, optional) – Weighting factors for data. Not used if data contains them.
- Returns:
out[0] (numpy.array) – The histogram (frequency) values.
out[1] (numpy.array) – The midpoints for the bins.
out[2] (tuple of floats) – These are some simple statistics, out[2][0] is the average out[2][1] is the standard deviation.
- pyretis.analysis.histogram.match_all_histograms(histograms, umbrellas)¶
Match several histograms from an umbrella sampling.
- Parameters:
histograms (list of numpy.arrays) – The histograms to match.
umbrellas (list of lists) – The umbrella windows used in the computation.
- Returns:
histograms_s (list of numpy.arrays) – The scaled histograms.
scale_factor (list of floats) – The scale factors.
matched_count (numpy.array) – Count for overall matched histogram (an “averaged” histogram).
pyretis.analysis.order_analysis module¶
Module defining functions for analysis of order parameters.
Important methods defined here¶
- analyse_orderp (
analyse_orderp()) Run a simple order parameter analysis.
- pyretis.analysis.order_analysis.analyse_orderp(orderdata, settings, segments=None)¶
Run the analysis on several order parameters.
The results are collected into a structure which is convenient for plotting.
- Parameters:
orderdata (numpy.arrays) – The data read from the order parameter file.
settings (dict) – This dictionary contains settings for the analysis.
segments (list of ints, optional) – The number of rows of each part of the run, when the rows are of several parts (
pyretis.analysis.flux_parts): the averages and the distributions take every row, and the blocks of the block error analysis and the displacements of the mean square displacement are taken within each part and pooled over the parts. None for rows of one part.
- Returns:
results (numpy.array) – For each order parameter key, results[key] contains the result of the analysis. The result of the first order parameter holds its mean square displacement under ‘msd’, and the lag of each row of it under ‘msd_time’: its number of rows times the steps between two rows, times the time of a step. The lags are those that the rows give (
_msd_lags()); when they give no lag, or not every lag that[analysis] maxordermsdasks for, or when the rows are not equally spaced in steps, it holds what is not computed and why under ‘msd-uncomputed’, and the analysis logs it as a warning. When the rows give no average block error (block_error_problem()), the result of each order parameter holds why under ‘blockerror-uncomputed’, and the analysis logs it as a warning.
See also
NoneNote
We here (and in the plotting routines) make certain assumptions about the structure, i.e. the positions are assumed to have a specific meaning: column zero is the time, column one the order parameter and so on.
pyretis.analysis.retis_diagnostics module¶
Sampling diagnostics and a cycle-aligned WHAM check for RETIS reports.
The caller supplies production occupancy rows after applying exactly the same initialisation and cycle-window gates as the matched analysis. WHAM uses the existing Q-factor recursion, evaluated at the actual interfaces so no histogram-grid rounding enters the rate comparison.
- class pyretis.analysis.retis_diagnostics.OccupancyDiagnostics¶
Bases:
objectCollect held paths, including repeats following rejected moves.
Columns of
samplesare cycle, length, maximum order parameter, estimator weight (fraction / HA weight), path number, and raw occupancy fraction. Missing global path identities are NaN; they must never be guessed from path length or ensemble-local counters.- __init__()¶
Start an empty record of retained path occupancies.
- array()¶
Return a consistently shaped numeric occupancy array.
- observe(path, in_window)¶
Update the held path and record its in-window occupancy.
- pyretis.analysis.retis_diagnostics._block_lengths(nrows)¶
Return the block lengths, in rows of the counts, the error scans.
- Parameters:
nrows (int) – The rows of the counts.
- Returns:
out (list of ints) – Lengths doubling from one row, while the counts hold at least
MIN_BLOCKSblocks of the length.[analysis] maxblock, the longest block of the block analysis of matching, does not limit them: the criterion of_jackknife_error()asks for the blocks a run needs.
- pyretis.analysis.retis_diagnostics._crossing_counts(samples, interfaces)¶
Accumulate weighted crossings and raw occupancies by cycle group.
- Parameters:
samples (list of numpy.array) – The occupancy rows of each positive ensemble.
interfaces (list of floats) – The interfaces of the ensembles and the last one.
- Returns:
out[0] (numpy.array) – Per row of
out[2]consecutive retained cycles, ensemble and target interface: estimator mass, raw occupancy mass, weighted crossings.out[1] (int) – The number of retained cycles.
out[2] (int) – The cycles of one row (
_cycle_group()).
- pyretis.analysis.retis_diagnostics._cycle_blocks(ncycles, group, nblocks)¶
Return the block of each retained cycle, as the scalar error forms it.
- Parameters:
ncycles (int) – The number of retained cycles.
group (int) – The cycles of one row of the counts (
_crossing_counts()).nblocks (int) – The rows form this many nearly equal contiguous blocks (
numpy.array_split, as_jackknife()).
- Returns:
out (numpy.array) – The block index of each retained cycle, in their order.
- pyretis.analysis.retis_diagnostics._cycle_group(ncycles)¶
Return the number of consecutive retained cycles one row sums.
The counts of the WHAM error keep at most
MAX_ROWSrows, so their memory grows with the ensembles and the interfaces but not with the length of the run; one row per cycle took 768 MB for 1e5 cycles of 30 ensembles.- Parameters:
ncycles (int) – The number of retained cycles.
- Returns:
out (int) – The cycles of one row, 1 or more.
- pyretis.analysis.retis_diagnostics._jackknife(counts, interfaces, nblocks)¶
Return the delete-one-block jackknife error of WHAM.
- Parameters:
counts (numpy.array) – The counts of
_crossing_counts().interfaces (list of floats) – The interfaces of the ensembles and the last one.
nblocks (int) – The rows form this many nearly equal contiguous blocks, each deleted in turn from all ensembles together.
- Returns:
out (float) – The error, or NaN when deleting a block leaves an ensemble without weight.
- pyretis.analysis.retis_diagnostics._jackknife_error(counts, group, interfaces)¶
Return the jackknife error of WHAM at blocks long against correlation.
Blocks shorter than the correlation time of the run give too small an error. The error is scanned at the lengths of
_block_lengths()and taken, as in Lee et al., Phys. Rev. E 83, 066706 (2011), at the shortest lengthLfrom which every scanned length meets the reblocking criterionL**3 > 2 N (error_L / error_1)**4, withLandN, the rows of the counts, counted in rows, anderror_1the error of one-row blocks.(error_L / error_1)**2estimates how many rows one independent sample takes, so that the criterion asks for longer blocks the more correlated the run is, and is not met while the blocks are shorter than its correlation time. The longest length alone is not taken: a longer length cannot confirm an error that only it gives, and one block length of few blocks can meet the criterion by chance. One-row blocks never meet it (1 <= 2 N), so that an error needs the lengths 2 and 4 at least: with fewer than4 * MIN_BLOCKSrows there is none, whatever the correlation.- Parameters:
counts (numpy.array) – The counts of
_crossing_counts().group (int) – The cycles of one row of the counts.
interfaces (list of floats) – The interfaces of the ensembles and the last one.
- Returns:
out[0] (float) – The error, or NaN.
out[1] (int) – The blocks of the error, 0 for NaN.
out[2] (string or None) – Why the error is NaN, as the end of a sentence; None otherwise.
- pyretis.analysis.retis_diagnostics._occupancy_fraction(path, weight)¶
Return the share of its ensemble an accepted path holds, c_nj.
- Parameters:
path (dict) – A parsed
pathensemble.txtrow of an accepted path.weight (float) – Its estimator multiplier (
_estimator_multiplier()).
- Returns:
out (float) – The
FracInccolumn of the row; for a row withHA-weightbut noFracInc, the multiplier times theHA-weight, which isHA-weight / Weight, the share the writer stores; for a row of the 17 canonical columns, written without the coordinator, 1: it records no fractional share, and its path is the whole occupancy of the ensemble, aspyretis.analysis.path_analysis._occupancy_share()reads it.
- pyretis.analysis.retis_diagnostics._path_maximum_counts(samples, interfaces, bins)¶
Count distinct global paths where available, otherwise raw occupancy.
- pyretis.analysis.retis_diagnostics._profile_jackknife(blocks, interfaces, points, curve, nblocks)¶
Return the jackknife error band of the WHAM curve and its estimates.
- Parameters:
blocks (numpy.array) – The totals of each block (
_profile_totals()).interfaces (numpy.array) – The interfaces of the ensembles and the last one.
points (numpy.array) – The order parameters of the curve.
curve (numpy.array) – The WHAM curve of all blocks.
nblocks (int) – The blocks of the scalar error, 0 when it has none.
- Returns:
out[0] (numpy.array) – The error at each point, NaN where the curve is 0 or without blocks.
out[1] (numpy.array) – The curve recomputed after deleting each block, one row per block; no rows without blocks.
- pyretis.analysis.retis_diagnostics._profile_totals(samples, points, group, nblocks)¶
Accumulate tail counts by cycle block without a cycle/grid cube.
A maximum contributes at grid points strictly below it, matching the crossing convention in the scalar estimator. All interfaces occur exactly in
points. Aggregating maxima into grid intervals first keeps memory proportional to blocks, ensembles and grid points. The blocks are those of the scalar error (_cycle_blocks()), or one block when it has none.
- pyretis.analysis.retis_diagnostics._reblocked_error(lengths, errors, nrows, group)¶
Return the error that the reblocking criterion takes from a scan.
- Parameters:
lengths (list of ints) – The scanned block lengths, in rows, of
_block_lengths().errors (list of floats) – The finite jackknife error at each length; the first, of one-row blocks, is not 0.
nrows (int) – The rows of the counts.
group (int) – The cycles of one row of the counts.
- Returns:
out (tuple) – The error, its blocks and why it is NaN, as
_jackknife_error()returns them.
- pyretis.analysis.retis_diagnostics._wham_probability(totals, interfaces)¶
Apply the shared WHAM recursion to weighted crossing counts.
- pyretis.analysis.retis_diagnostics._wham_profile(totals, interfaces, points)¶
Reconstruct a crossing curve and its additive ensemble contributions.
- pyretis.analysis.retis_diagnostics.analyse_retis_diagnostics(results)¶
Collect report diagnostics from the already windowed analysis.
- pyretis.analysis.retis_diagnostics.path_length_acf(samples)¶
Return the path-length ACF versus scheduler-move lag.
Uses Hall et al. Eq. (6): sum of centred lagged products divided by the total centred sum of squares, with ACF(0) = 1. Multiple occupants of one cycle contribute their occupancy-weighted mean length. Gaps stay gaps rather than being compressed into adjacent moves. A constant series has undefined ACF and is returned as NaN.
- pyretis.analysis.retis_diagnostics.wham_report(positives, flux)¶
Estimate WHAM probability and its contiguous-block jackknife error.
Contiguous blocks of retained cycles are deleted in turn, from all ensembles together, which keeps the time correlations within a block and the correlations between ensembles. The block length doubles from one row of the counts (
_cycle_group()), and the error is taken at blocks long against the correlation time of the run (_jackknife_error()). The rows split into nearly equal blocks, which differ by at most one row; the usual delete-one-group jackknife is then an approximation.The comparison uses the report’s initial flux for both estimators. Rate uncertainty combines the WHAM probability standard error and the existing flux standard error in quadrature, as in retis_rate; probability/flux covariance is not included.
- pyretis.analysis.retis_diagnostics.wham_visualisation(positives, wham=None)¶
Explain pooled paths, WHAM weights, the curve and block uncertainty.
The displayed ensemble fractions are contributions to the WHAM numerator, normalised at each lambda. They are not independent-path counts or effective sample sizes. The probability band and deleted-block estimates use the same cycle blocks as the scalar report uncertainty, those of
wham(wham_report()of the same ensembles), which is computed when not given.
pyretis.analysis.path_analysis module¶
Methods for analysis of path ensembles.
Important methods defined here¶
- analyse_path_ensemble (
analyse_path_ensemble()) Method to analyse a path ensemble, it will calculate crossing probabilities and information about moves etc. This method can be applied to files as well as path ensemble objects.
- match_probabilities (
match_probabilities()) Match probabilities from several path ensembles and calculate efficiencies and the error for the matched probability.
- retis_flux (
retis_flux()) Calculate the initial flux with errors for a RETIS simulation.
- retis_flux_row (
retis_flux_row()) Give the [0^-] crossing probability, the running estimate and the block error of the initial flux for the report.
- retis_rate (
retis_rate()) Calculate the rate constant with errors for a RETIS simulation.
- pyretis.analysis.path_analysis.analyse_path_ensemble(path_ensemble, settings)¶
Analyse a path ensemble.
This function will make use of the different analysis functions and analyse a path ensemble. It should work on both PathEnsemble and PathEnsembleFile objects. The running average is a cumulative average, see Wikipedia for details [wikimov].
- Parameters:
path_ensemble (object like
PathEnsemble) – This is the path ensemble to analyse.settings (dict) – This dictionary contains settings for the analysis. We make use of the following keys:
ngrid: The number of grid points for calculating the crossing probability as a function of the order parameter.
maxblock: The max length of the blocks for the block error analysis. Note that this will maximum be equal the half of the length of the data, see block_error in .analysis.
blockskip: Can be used to skip certain block lengths. A blockskip equal to n will consider every n’th block up to maxblock, i.e. it will use block lengths equal to 1, 1+n, 1+2n, etc.
bins: The number of bins to use for creating histograms.
- Returns:
out (dict) – This dictionary contains the main results for the analysis which can be used for plotting or other kinds of output.
See also
_update_shoot_stats(),_pcross_lambda_cumulative()andpy:func:._create_shoot_histograms.
References
[wikimov]Wikipedia, “Moving Average”, https://en.wikipedia.org/wiki/Moving_average
- pyretis.analysis.path_analysis.analyse_repptis_ensemble(path_ensemble, settings)¶
Analyse a repptis path ensemble.
Like
analyse_path_ensemble(), this function makes use of the different analysis functions, here to analyse a repptis path ensemble.- Parameters:
path_ensemble (object like
PathEnsemble) – This is the path ensemble to analyse.settings (dict) – This dictionary contains settings for the analysis. We make use of the following keys:
ngrid: The number of grid points for calculating the crossing probability as a function of the order parameter.
maxblock: The max length of the blocks for the block error analysis. Note that this will maximum be equal the half of the length of the data, see block_error in .analysis.
blockskip: Can be used to skip certain block lengths. A blockskip equal to n will consider every n’th block up to maxblock, i.e. it will use block lengths equal to 1, 1+n, 1+2n, etc.
bins: The number of bins to use for creating histograms.
- Returns:
out (dict) – This dictionary contains the main results for the analysis which can be used for plotting or other kinds of output.
- pyretis.analysis.path_analysis.match_probabilities(path_results, detect, settings=None)¶
Match probabilities from several path ensembles.
It calculates the efficiencies and errors for the matched probability.
- Parameters:
path_results (list) – These are the results from the path analysis. path_results[i] contains the output from analyse_path_ensemble applied to ensemble no. i. Here we make use of the following keys from path_results[i]: * pcross: The crossing probability. * prun: The running average of the crossing probability. * blockerror: The output from the block error analysis. * efficiency: The output from the efficiency analysis. * ensemble: The name of the ensemble.
detect (list of floats) – These are the detect interfaces used in the analysis. detect[i] is the detect interface of ensemble no. i.
settings (dict, optional) – This dictionary contains settings for the analysis. Here we make use of the following keys from the analysis section:
ngrid: The number of grid points used per ensemble when building the crossing probability as a function of the order parameter (pcross). The grid for ensemble i spans [interfaces[1], min(orderparam.max(), max(interfaces))] with ngrid linearly spaced points; the spacing therefore depends on each ensemble’s range. The total-probability output is the concatenation of the pcross slices lambda <= detect from every ensemble, so its resolution near a given interface is set by the ngrid of the ensemble that owns that region. The default (1001) gives sub-percent resolution for typical interface spacings; increase it for finer interpolation.
maxblock: The max length of the blocks for the block error analysis. Note that this will maximum be equal the half of the length of the data, see block_error in .analysis.
blockskip: Can be used to skip certain block lengths. A blockskip equal to n will consider every n’th block up to maxblock, i.e. it will use block lengths equal to 1, 1+n, 1+2n, etc.
bins: The number of bins to use for creating histograms.
- Returns:
results (dict) – These are results for the over-all probability and error and also some over-all TIS efficiencies. The matching skips an ensemble with no accepted paths, and the crossing probability prob (and relerror) is then NaN: it is the product over every ensemble. The two lists below hold one entry for each ensemble it matched, in the order of path_results:
matched-prob: The crossing probability of the ensemble as a function of the order parameter (two columns), scaled by the product of the crossing probabilities (prun[-1]) of the ensembles matched before it.
matched-ensembles: The name of the ensemble.
- pyretis.analysis.path_analysis.perm_calculations(results0, pcross, pcross_err)¶
Calculate the permeability.
This function collects the relevant permeability properties from the output data. It then calculates the permeability and its error based on the values of xi, tau, and the crossing probability pcross.
- Parameters:
results0 (dict) – Results from the analysis of ensemble [0^-]
pcross (float) – Estimated crossing probability
pcross_err (float) – Relative error in crossing probability.
- Returns:
xxi (float) – The value of xi
tau (float) – The value of tau
perm (float) – The value of the permeability
xi_err (float) – The error in xi
tau_err (float) – The error in tau
perm_err (float) – The error in permeability
- pyretis.analysis.path_analysis.retis_flux(results0, results1, timestep)¶
Calculate the initial flux for RETIS.
- Parameters:
results0 (dict) – Results from the analysis of ensemble [0^-]
results1 (dict) – Results from the analysis of ensemble [0^+]
timestep (float) – The simulation timestep.
- Returns:
flux (float) – The initial flux.
flux_error (float) – The relative error in the initial flux.
- pyretis.analysis.path_analysis.retis_flux_row(results0, results1, timestep, maxblock)¶
Return the data of the [0^-] row of the report.
The row has three panels: the crossing probability of [0^-] towards smaller order parameters, the running estimate of the initial flux and the share of [0^-] and of [0^+] in its relative error.
- Parameters:
results0 (dict) – The analysis of [0^-].
results1 (dict) – The analysis of [0^+].
timestep (float) – The time of one step of a path.
maxblock (int or None) – The largest block length of the settings,
maxblockof theanalysissection.
- Returns:
row (dict) – The ensemble name (
ensemble) and its directory name (ensemble_simple),lambda0and theleft_boundof [0^-] (None when nothing bounds it), and thefluxand its relative errorrelerror, asretis_flux()gives them (NaN when it is not defined). When [0^-] has accepted paths,pcross: the grid and the crossing probability towards smaller order parameters. When the flux is defined,cycleandfluxrun: the running estimate of the flux, andblockerror: the share of [0^-] and of [0^+] in the relative error of the flux (_flux_block_error()).
- pyretis.analysis.path_analysis.retis_rate(pcross, pcross_relerror, flux, flux_relerror)¶
Calculate the rate constant for RETIS.
- Parameters:
pcross (float) – Estimated crossing probability
pcross_relerror (float) – Relative error in crossing probability.
flux (float) – The initial flux.
flux_relerror (float) – Relative error in the initial flux.
- Returns:
rate (float) – The rate constant
rate_error (float) – The relative error in the rate constant.
- pyretis.analysis.path_analysis.skip_paths(weights, nacc, nskip)¶
Skips not counted paths.
- Parameters:
weights (array of integers) – The weights of the paths.
nacc (integer) – Number of accepted paths.
nskip (integer) – Number of paths to skip.
- Returns:
new_weights (array of integers) – The new weights of the paths once skipped the nskip ones.
new_acc (integer) – Recomputed number of accepted paths.
pyretis.analysis.repptis_analysis module¶
This module computes the local and global crossing probabilities of REPPTIS partial paths (see [vervust2026loc]).
Local and global crossing probabilities for partial path TIS (REPPTIS).
A REPPTIS run samples short partial paths, each classified by where it
enters and leaves the ensemble: LML / LMR / RML / RMR
(Left/Right entry, Middle, Left/Right exit). From the
weighted counts of these path types this module computes:
the local crossing probabilities of one ensemble (
local_crossing_probabilities()) – the per-ensemblep_mm(LML) /p_mp(LMR) /p_pm(RML) /p_pp(RMR) that feed the REPPTIS Markov state model (pyretis.analysis.repptis_msm), andthe global crossing probability across all ensembles (
global_crossing_probabilities_from_local()) via the closed-form recursion, an alternative to the MSM that does not need the transition-time vector.
The probabilities are those of the analysis of Vervust, Wils, Safaei,
Zhang and Ghysels (J. Chem. Theory Comput. 2026), computed from the
lmrs / weights arrays that
pyretis.analysis.path_analysis.analyse_repptis_ensemble()
produces.
References
W. Vervust, E. Wils, S. Safaei, D. T. Zhang and A. Ghysels, “Estimating full path lengths and kinetics from partial path transition interface sampling simulations”, J. Chem. Theory Comput. (2026), https://doi.org/10.1021/acs.jctc.5c01498.
- pyretis.analysis.repptis_analysis.global_crossing_probabilities_from_local(p_minus_plus, p_minus_minus, p_plus_plus, p_plus_minus)¶
Return global crossing probabilities from the local ones.
Combine the per-ensemble local crossing probabilities into the global crossing probabilities using the closed-form REPPTIS recursion
\[P^+_j = \frac{p^{LMR}_{j-1} P^+_{j-1}} {p^{LMR}_{j-1} + p^{LML}_{j-1} P^-_{j-1}}, \quad P^-_j = \frac{p^{RML}_{j-1} P^-_{j-1}} {p^{LMR}_{j-1} + p^{LML}_{j-1} P^-_{j-1}},\]with \(P^+_0 = P^-_0 = 1\).
P_crossis the corresponding TIS probability of crossing interfacei + 1.- Parameters:
p_minus_plus (sequence of float) – Per-ensemble local probability of type
LMR(forward crossing).p_minus_minus (sequence of float) – Per-ensemble local probability of type
LML(return left).p_plus_plus (sequence of float) – Per-ensemble local probability of type
RMR(return right).p_plus_minus (sequence of float) – Per-ensemble local probability of type
RML(cross left).
- Returns:
p_min (list of float) – Per ensemble
i, the probability of reaching state A before interfacei + 1given a crossing ofi.p_plus (list of float) – Per ensemble
i, the probability of reaching interfacei + 1before A given a crossing ofi.p_cross (list of float) – Per ensemble
i, the TIS probability of crossingi + 1.
Notes
If any input contains
nan, or a denominator vanishes, the function returns[nan, nan, nan], so a degenerate ensemble does not silently produce a spurious finite rate.
- pyretis.analysis.repptis_analysis.local_crossing_probabilities(lmrs, weights, tr=False)¶
Return the local crossing probabilities of one REPPTIS ensemble.
The accepted partial paths of an
[i^+-]/[0^+-']ensemble are classified by type (RMR/RML/LMR/LML) and weighted by their Monte-Carlo weights. The local crossing probability of a type is its weight divided by the total weight of paths entering from the same side: paths entering from the left (LMR+LML) and from the right (RMR+RML) are normalised separately. This routine is not for the[0^-']ensemble.- Parameters:
lmrs (sequence of string) – One
"LMR"-style type tag per accepted path (the joined left/middle/right interface flags). Tags that are not one ofPATH_TYPES(partial*tags) contribute zero weight.weights (sequence of int or float) – The Monte-Carlo weight of each accepted path (same length and order as
lmrs).tr (boolean, optional) – If True, apply infinite time-reversal reweighting: double the
RMRandLMLweights and symmetriseRML/LMR. Default is False.
- Returns:
p (dict) – Local crossing probabilities keyed by path type (
RMR/RML/LMR/LML), plus the milestoning arrival probabilities2R/2L. A probability isnanwhen its normalising weight is zero.
- pyretis.analysis.repptis_analysis.path_type_taus(orders_list, lmrs, weights, interfaces)¶
Return the weighted-average transition times per path type.
For every accepted path the total interior time (
tau_total()), the time before the middle crossing (tau_before_middle()) and the time after it (tau_after_middle()) are computed and weight-averaged per path type. The middle (recrossing) timetaumis the remaindertau - tau1 - tau2. These per-type, per-ensemble averages feed the REPPTIS MSM mean-first-passage-time vector (pyretis.analysis.repptis_msm.construct_tau_vector()).- Parameters:
orders_list (sequence of numpy.ndarray) – One order-parameter trajectory per accepted path.
lmrs (sequence of string) – The path type of each accepted path (same length/order).
weights (sequence of int or float) – The Monte-Carlo weight of each accepted path.
interfaces (sequence of float) – The ensemble’s
(left, middle, right)interfaces.
- Returns:
dict – Maps each path type (
LML/LMR/RML/RMR) to a dict with keystau/tau1/tau2/taum(the weighted averages, ornanwhen the type is unsampled).
- pyretis.analysis.repptis_analysis.tau_after_middle(orders, ptype, interfaces)¶
Return the steps a path takes after its last middle crossing.
The mirror of
tau_before_middle(), measured from the end of the path inward: for a path that exits left (LML/RML) from the left interface, for a path that exits right (LMR/RMR) from the right interface.- Parameters:
orders (numpy.ndarray) – The per-phase-point order parameters of the path.
ptype (string) – The path type (
LMR/LML/RML/RMR).interfaces (sequence of float) – The ensemble’s
(left, middle, right)interfaces.
- Returns:
int – The number of steps after the last middle crossing.
- Raises:
ValueError – If the path type is not recognised.
- pyretis.analysis.repptis_analysis.tau_before_middle(orders, ptype, interfaces)¶
Return the steps a path takes to first cross the middle interface.
For a left-entering path (
LMR/LML) this is the number of steps between the first crossing of the left interfaceinterfaces[0]and the first crossing of the middle interfaceinterfaces[1]; for a right-entering path (RML/RMR) it is measured from the right interfaceinterfaces[2]inward.- Parameters:
orders (numpy.ndarray) – The per-phase-point order parameters of the path; column 0 is the main order parameter.
ptype (string) – The path type (
LMR/LML/RML/RMR).interfaces (sequence of float) – The ensemble’s
(left, middle, right)interfaces.
- Returns:
int – The number of steps before the middle interface is crossed.
- Raises:
ValueError – If the path type is not recognised.
- pyretis.analysis.repptis_analysis.tau_total(orders, ptype, interfaces)¶
Return the path length between its first and last boundary crossing.
The total time the path spends inside the ensemble, excluding the leading segment before the entry crossing and the trailing segment after the exit crossing. Equals
tau_before_middle+tau_after_middle+ the middle (recrossing) time.- Parameters:
orders (numpy.ndarray) – The per-phase-point order parameters of the path.
ptype (string) – The path type (
LMR/LML/RML/RMR).interfaces (sequence of float) – The ensemble’s
(left, middle, right)interfaces.
- Returns:
int – The number of interior steps of the path.
- Raises:
ValueError – If the path type is not recognised.
pyretis.analysis.repptis_msm module¶
Markov-state-model kinetics for partial path TIS (REPPTIS).
REPPTIS samples short partial paths, so the crossing probability, mean first passage time (MFPT), flux and rate cannot be read off the path ensembles directly the way they are for full RETIS. This module reconstructs them by building a Markov state model (MSM) over the partial-path ensembles from the local crossing probabilities and the per-ensemble transition times, following the closed-form analysis of Vervust, Wils, Safaei, Zhang and Ghysels [vervust2026] (building on the permeability-from-(RE)TIS formalism of Ghysels, Roet, Davoudi and van Erp [ghysels2021], and the REPPTIS replica-exchange scheme of Vervust, Zhang, van Erp and Ghysels [vervust2023]).
Note on the index convention¶
In the paper, N + 1 is the number of interfaces, while in this
code N is the number of interfaces directly. Both yield the same
state-space size NS = 4 * N - 5 (paper: 4 * (N - 1) - 1).
Important methods defined here¶
- construct_M (
construct_M()) Build the PPTIS transition matrix from the local crossing probabilities.
- construct_M_milestoning (
construct_M_milestoning()) Build the milestoning transition matrix.
- global_pcross_msm (
global_pcross_msm()) Global crossing probability from the transition matrix.
- mfpt_to_absorbing_states (
mfpt_to_absorbing_states()) Mean first passage time to a set of absorbing states.
- mfpt_to_first_last_state (
mfpt_to_first_last_state()) Mean first passage time to the first or last state.
- construct_tau_vector (
construct_tau_vector()) Flatten the per-path-type transition times into the MSM vector.
References
W. Vervust, E. Wils, S. Safaei, D. T. Zhang and A. Ghysels, “Estimating full path lengths and kinetics from partial path transition interface sampling simulations”, J. Chem. Theory Comput. (2026), https://doi.org/10.1021/acs.jctc.5c01498 (arXiv:2602.12835).
A. Ghysels, S. Roet, S. Davoudi and T. S. van Erp, “Exact non-Markovian permeability from rare event simulations”, Phys. Rev. Research 3, 033068 (2021), https://doi.org/10.1103/PhysRevResearch.3.033068.
W. Vervust, D. T. Zhang, T. S. van Erp and A. Ghysels, “Path sampling with memory reduction and replica exchange to reach long permeation timescales”, Biophys. J. 122, 2960-2972 (2023), https://doi.org/10.1016/j.bpj.2023.02.021.
- pyretis.analysis.repptis_msm.check_valid_indices(M, absor, kept)¶
Validate the absorbing and non-absorbing state indices.
Ensure that the indices of absorbing (
absor) and non-absorbing (kept) states are correctly defined, in range, and partition the state space (each state in exactly one of the two sets).- Parameters:
M (numpy.ndarray) – The transition matrix of the Markov process.
absor (array-like) – Indices of absorbing states.
kept (array-like) – Indices of non-absorbing (nonboundary) states.
- Raises:
ValueError – If there are duplicate indices in
absororkept, if any index is out of bounds, or if any state is neither inabsornor inkept(or in both).
- pyretis.analysis.repptis_msm.construct_M(p_mm, p_mp, p_pm, p_pp, N)¶
Construct the PPTIS transition matrix M.
The matrix describes the probabilities of transitioning between states in the PPTIS framework, built from the local crossing probabilities for the different path types (LML, LMR, RML, RMR).
- Parameters:
p_mm (list of float) – Local crossing probabilities for the LML (Left-to-Left) path type. Must have length
N - 1.p_mp (list of float) – Local crossing probabilities for the LMR (Left-to-Right) path type. Must have length
N - 1.p_pm (list of float) – Local crossing probabilities for the RML (Right-to-Left) path type. Must have length
N - 1.p_pp (list of float) – Local crossing probabilities for the RMR (Right-to-Right) path type. Must have length
N - 1.N (int) – The number of interfaces. Must be at least 3.
- Returns:
M (numpy.ndarray) – The transition matrix of shape
(NS, NS), whereNS = 4 * N - 5.- Raises:
ValueError – If any of the input constraints are not met (e.g. invalid lengths or values).
- pyretis.analysis.repptis_msm.construct_M_N3(p_mm, p_mp, NS)¶
Construct the PPTIS transition matrix M for the case N=3.
Build the transition matrix when there are exactly 3 interfaces.
- Parameters:
p_mm (list of float) – Local crossing probabilities for the LML (Left-to-Left) path type. Must have length 2.
p_mp (list of float) – Local crossing probabilities for the LMR (Left-to-Right) path type. Must have length 2.
NS (int) – The dimension of the transition matrix. Must satisfy
NS = 4 * N - 5withN = 3.
- Returns:
M (numpy.ndarray) – The transition matrix of shape
(NS, NS).- Raises:
ValueError – If the input probability lists do not have the correct length or if
NSis invalid.
- pyretis.analysis.repptis_msm.construct_M_milestoning(p_min, p_plus, N)¶
Construct the transition matrix M for milestoning PPTIS.
Build a transition matrix for a milestoning framework. The states are lambda0-, lambda0+, lambda1, …, lambda(N-1) = B.
- Parameters:
p_min (list of float) – Probabilities of transitioning to the previous milestone. Must have length
N - 1.p_plus (list of float) – Probabilities of transitioning to the next milestone. Must have length
N - 1.N (int) – The number of interfaces (milestones). Must be at least 3.
- Returns:
M (numpy.ndarray) – The transition matrix of shape
(NS, NS), whereNS = N + 1.- Raises:
ValueError – If
Nis less than 3 or if the lengths ofp_minandp_plusare notN - 1.
- pyretis.analysis.repptis_msm.construct_tau_vector(N, NS, taumm, taump, taupm, taupp)¶
Construct the flattened vector of PPTIS transition times.
The per-path-type transition times (LML, LMR, RML, RMR) are organised into a single flattened vector following the PPTIS ensemble structure.
- Parameters:
N (int) – The number of ensembles. Must be at least 3.
NS (int) – The expected size of the output vector. Must satisfy
NS = 4 * N - 5.taumm (list of float) – Transition times for the LML (Left-to-Left) path type. Must have length
N.taump (list of float) – Transition times for the LMR (Left-to-Right) path type. Must have length
N.taupm (list of float) – Transition times for the RML (Right-to-Left) path type. Must have length
N.taupp (list of float) – Transition times for the RMR (Right-to-Right) path type. Must have length
N.
- Returns:
tau (numpy.ndarray) – A flattened vector of transition times with length
NS.- Raises:
ValueError – If any of the input constraints are not met (e.g. invalid lengths or values).
- pyretis.analysis.repptis_msm.create_labels_states(N)¶
Generate labels for absorbing and non-absorbing states.
Create two lists of state labels:
labels1for the two absorbing states (0-andB), andlabels2for theN-2non-absorbing states.- Parameters:
N (int) – The total number of states. Must be at least 3.
- Returns:
labels1 (list of str) – Labels for the two absorbing states.
labels2 (list of str) – Labels for the
N-2non-absorbing states.
- Raises:
ValueError – If
Nis less than 3.
- pyretis.analysis.repptis_msm.create_labels_states_all(N)¶
Generate labels for all states in sequential order.
Create a single list of state labels: the absorbing state
0-, all non-absorbing states, then the absorbing stateB.- Parameters:
N (int) – The total number of states. Must be at least 3.
- Returns:
labels (list of str) – Labels for all
Nstates in sequential order.- Raises:
ValueError – If
Nis less than 3.
- pyretis.analysis.repptis_msm.get_pieces_matrix(M, absor, kept)¶
Partition a transition matrix into absorbing/nonboundary blocks.
Split
Minto four submatrices:Mp(nonboundary to nonboundary),D(nonboundary to absorbing),E(absorbing to nonboundary), andM11(absorbing to absorbing).- Parameters:
M (numpy.ndarray) – The transition matrix of the Markov process.
absor (array-like) – Indices of absorbing states.
kept (array-like) – Indices of non-absorbing (nonboundary) states.
- Returns:
Mp (numpy.ndarray) – Submatrix for nonboundary-to-nonboundary transitions.
D (numpy.ndarray) – Submatrix for nonboundary-to-absorbing transitions.
E (numpy.ndarray) – Submatrix for absorbing-to-nonboundary transitions.
M11 (numpy.ndarray) – Submatrix for absorbing-to-absorbing transitions.
- Raises:
ValueError – If
absorandkeptcontain invalid or overlapping indices.
- pyretis.analysis.repptis_msm.get_pieces_vector(vec, absor, kept)¶
Partition a vector into absorbing/nonboundary sub-vectors.
Split
vecintov1(elements at absorbing-state indices) andv2(elements at nonboundary-state indices).- Parameters:
vec (numpy.ndarray) – A 1D array of state values.
absor (array-like) – Indices of absorbing states.
kept (array-like) – Indices of non-absorbing (nonboundary) states.
- Returns:
v1 (numpy.ndarray) – A column vector (
len(absor) x 1) of elements atabsor.v2 (numpy.ndarray) – A column vector (
len(kept) x 1) of elements atkept.
- Raises:
ValueError – If
absorandkeptcontain invalid or overlapping indices, ifvecis not 1D, or ifvecdoes not have the expected lengthlen(absor) + len(kept).
- pyretis.analysis.repptis_msm.global_pcross_msm(M, doprint=False)¶
Compute global crossing probabilities in a Markov process.
Calculate the probability of reaching state
-1before state0under different conditions, using the transition matrix. The function solves a linear system rather than inverting matrices, for better numerical stability.- Parameters:
M (numpy.ndarray) – A square transition matrix representing the Markov process. Must have at least 3 states.
doprint (bool, optional) – If True, log intermediate computation details. Default False.
- Returns:
z1 (numpy.ndarray) – A 2-element array with crossing probabilities for states 0 and -1.
z2 (numpy.ndarray) – An
(NS-2)-element array with crossing probabilities for the other states.y1 (numpy.ndarray) – A 2-element array with adjusted crossing probabilities for states 0 and -1.
y1[0]is the global crossing probability from state 0 to -1, given that the process starts at 0 and leaves it.y2 (numpy.ndarray) – An
(NS-2)-element array with adjusted crossing probabilities for the other states.
- Raises:
ValueError – If the transition matrix has fewer than three states.
- pyretis.analysis.repptis_msm.mfpt_to_absorbing_states(M, tau1, taum, tau2, absor, kept, doprint=False, remove_initial_m=True)¶
Compute the mean first passage time (MFPT) to absorbing states.
Calculate the MFPT to reach any of the specified absorbing states, both unconditionally (
g) and conditionally on leaving the current state (h). The system is solved without explicit matrix inversion, for numerical stability.- Parameters:
M (numpy.ndarray) – The transition matrix of the Markov process.
tau1 (numpy.ndarray) – Time before the first visit to an absorbing state.
taum (numpy.ndarray) – Time spent between the first and last visit to an absorbing state.
tau2 (numpy.ndarray) – Time after the last visit to an absorbing state.
absor (list or numpy.ndarray) – Indices of absorbing states.
kept (list or numpy.ndarray) – Indices of nonboundary (non-absorbing) states.
doprint (bool, optional) – If True, log intermediate computation details. Default False.
remove_initial_m (bool or str, optional) – If True or
"m", the middle part (taum) is removed from the initial state’s MFPT. Default True.
- Returns:
g1 (numpy.ndarray) – Array of size
(n_absorb, 1)with unconditional MFPTs for the absorbing states.g2 (numpy.ndarray) – Array of size
(n_kept, 1)with unconditional MFPTs for the nonboundary states.h1 (numpy.ndarray) – Array of size
(n_absorb, 1)with conditional MFPTs for the absorbing states.h2 (numpy.ndarray) – Array of size
(n_kept, 1)with conditional MFPTs for the nonboundary states.
- Raises:
ValueError – If the transition matrix has fewer than three states, or if the absorbing and nonboundary states do not partition the state space.
- pyretis.analysis.repptis_msm.mfpt_to_first_last_state(M, tau1, taum, tau2, doprint=False)¶
Compute the MFPT to reach either state 0 or state -1.
Calculate the MFPT to reach the first (0) or last (
NS-1) state by treating these two states as absorbing. The key result ish1[0], the MFPT from state 0 to either 0 or -1, given that the process leaves state 0. Callsmfpt_to_absorbing_states()withremove_initial_m="m"so the intermediate passage time is excluded.- Parameters:
M (numpy.ndarray) – The transition matrix of the Markov process.
tau1 (numpy.ndarray) – Time before the first visit to an absorbing state.
taum (numpy.ndarray) – Time spent between the first and last visit to an absorbing state.
tau2 (numpy.ndarray) – Time after the last visit to an absorbing state.
doprint (bool, optional) – If True, log intermediate computation details. Default False.
- Returns:
g1 (numpy.ndarray) – Unconditional MFPT for the absorbing states (0 and
NS-1).g2 (numpy.ndarray) – Unconditional MFPT for the nonboundary states.
h1 (numpy.ndarray) – Conditional MFPT for the absorbing states.
h2 (numpy.ndarray) – Conditional MFPT for the nonboundary states.
- Raises:
ValueError – If the transition matrix has fewer than three states.
- pyretis.analysis.repptis_msm.print_all_tau(pathensembles, taumm, taump, taupm, taupp)¶
Print all tau values for each path ensemble.
- Parameters:
pathensembles (list) – List of path ensemble objects, each with a
.nameattribute.taumm (array-like) – First tau metric for each path.
taump (array-like) – Second tau metric for each path.
taupm (array-like) – Third tau metric for each path.
taupp (array-like) – Fourth tau metric for each path.
- Raises:
ValueError – If the input arrays do not have the same length as
pathensembles.
- pyretis.analysis.repptis_msm.print_vector(g, states=None, sel=None)¶
Print a vector
gwith the corresponding state labels.- Parameters:
g (array-like) – The vector to print.
states (list of str, optional) – Labels corresponding to each state. If None, indices are used.
sel (list of int, optional) – Indices of the selected states to print. If None, all states are printed.
- Raises:
ValueError – If
selis provided but does not match the length ofg.
pyretis.analysis.wham_analysis module¶
WHAM crossing-probability analysis for infinite-swapping RETIS.
This module computes per-interface and total crossing probabilities, the
initial flux, and the rate constant from the path-data matrix of the
infinite-swapping (replica-exchange) sampler – a literal
infswap_data.txt if the run directory has one (a run of an earlier
PyRETIS, or a pyretis.analysis.combine_data merge output),
otherwise reconstructed from the per-ensemble output the scheduler
writes (see get_path_data_matrix()).
The estimator follows the standard weighted-histogram (WHAM)
crossing-probability procedure for transition interface sampling: the
high-acceptance (HA) weight unweighting, the eta normalisation, the
Q-factor WHAM stitch (Lervik and van Erp, J. Chem. Theory Comput. 11,
2440 (2015)), a point-matching cross-check and a block-error analysis.
The functions return their results as values.
Data-file column layout (after str.split on a data line):
0– path index1– path length2– maximum order parameter (lambda_max)3 .. 3 + nintf - 1–Cxy(fractional sampling occurrence) for ensembles[0-],[0+],[1+], …3 + nintf .. 3 + 2*nintf - 1– the high-acceptance (HA) weights for the same ensembles.
Here nintf is the number of interfaces and i0plus = 4 is the column
of the [0+] ensemble.
- pyretis.analysis.wham_analysis.INFSWAP_DATA_NAMES = ('infswap_data.txt', 'infretis_data.txt')¶
Names of the combined infinite-swapping data file, in the order they are looked for.
infretis_data.txtis read so that archived simulations that wrote that name can be analysed.
- pyretis.analysis.wham_analysis._default_lamres(interfaces)¶
Pick a default order-parameter resolution from the interfaces.
The WHAM stitch places every interface on a uniform grid of step
lamresviaround((lambda - lambda_A) / lamres). To keep adjacent interfaces on distinct grid points the step must be small relative to the smallest interface spacing: a step larger than a gap can round both interfaces of that gap onto the same grid index, which corrupts the per-interface crossing probabilities. We therefore take one tenth of the smallest spacing.- Parameters:
interfaces (list of float) – Strictly increasing interface positions.
- Returns:
lamres (float) – The chosen resolution.
- pyretis.analysis.wham_analysis._load_run_config(directory='.')¶
Load the scheduler configuration of a run’s run file as a dict.
Reads the first of
output.toml/restart.toml/infswap.tomlfound indirectory, or returnsNoneif none exists.output.tomlis the run file andrestart.tomlthe run file of an earlier PyRETIS; aninfswap.tomlis read as the input of the run when neither is there. A run file with the canonical sections of the run gives the scheduler configuration the key table builds from them (pyretis.inout.run_record.load_run()), with its[current]state; an input of the legacy-runner schema gives the one of its canonical form (pyretis.inout.run_record.load_legacy_run()); every other file is a state file of the scheduler configuration, read as it is. The run file is read as the analysis reads it (pyretis.inout.run_record.read_scheduler_config()with the reader'analysis'), which refuses no run for its temperatures. The configuration gives the interfaces, the ensembles and the time step of the run, not its temperature, which the analysis reads with the settings it analyses (pyretis.inout.run_record.read_settings()): it is read again (pyretis.inout.checker.reread_quietly()), without the warnings of the temperatures of the run.
- pyretis.analysis.wham_analysis._rec_blocks(reduced)¶
Recover block averages from a reduced running-average array.
- pyretis.analysis.wham_analysis._running_flux(matrix, interval=1.0)¶
Running-average conventional flux, one entry per path.
The
[0-]/[0+]path lengths are in simulation steps;interval(the time per step,timestep * subcycles) converts the running flux to a flux per unit time. Seewham_crossing_probability()for theintervalconvention.
- pyretis.analysis.wham_analysis._running_lengths(matrix)¶
Weighted mean path length in the [0-] and [0+] ensembles.
- pyretis.analysis.wham_analysis._running_pm(matrix, interfaces, lamres)¶
Compute the running point-matching total crossing probability.
Running point-matching total crossing probability: at each path the product over ensembles of
P_A(lambda_{i+1} | lambda_i)evaluated from the local crossing probabilities accumulated so far.
- pyretis.analysis.wham_analysis._unweight_matrix(matrix, nintf)¶
Unweight the
Cxycolumns by the HA-weights, in place.Standard WHAM unweighting step: each
Cxyvalue is divided by its HA-weight, the (now redundant) HA-weight column is overwritten with the running sum of the pre-unweightingCxy(needed for the running WHAM averages), and finally eachCxycolumn is divided by the average inverse HA-weight so theetavalues are comparable across ensembles that use different moves (e.g.[0+]shooting vs[i+]wire fencing).- Parameters:
matrix (list of list of float) – The data matrix from
read_data_matrix(); modified in place.nintf (int) – Number of interfaces.
- pyretis.analysis.wham_analysis._validate_lamres(interfaces, lamres)¶
Check that
lamresresolves every interface separately.Raises if two interfaces round to the same grid index (the stitch would double-count an ensemble) and warns if an interface does not sit exactly on the grid (the per-interface crossing probability is then read at the nearest grid point; the interface is mis-placed by at most
lamres / 2in lambda, and the probability error that induces depends on the local crossing-probability slope). Failing loud here is deliberate: a wrong crossing probability is worse than a refusal to run.- Parameters:
interfaces (list of float) – Strictly increasing interface positions.
lamres (float) – Candidate order-parameter resolution.
- pyretis.analysis.wham_analysis._wham_pq(n_plus_ens, interfaces, lamres, eta, v_alpha)¶
WHAM crossing probabilities at the interfaces and Q-factors.
WHAM crossing probabilities at the interfaces and Q-factors (Q-factor recursion of Lervik and van Erp, J. Chem. Theory Comput. 11, 2440 (2015)). Returns
P(crossing probability at each interface, withlambda_Bappended) andQ(the per-ensemble normalisation factors forv_alpha).
- pyretis.analysis.wham_analysis._wham_ptot_run(interfaces, ploc_matrix, sum_pxy)¶
Running-average total crossing probability via WHAM.
ploc_matrix[j][i]isP_A(lambda_i | lambda_j)from the[j+]ensemble using the data so far.Each ensemble
jenters the q-factor stitch weighted bysum_pxy[j]: its effective sample count = the sum of the HA-weights of its paths (the pre-unweightingCxysum from_unweight_matrix()). Because an HA-weight is a sample multiplicity, this makes WHAM – unlike point matching – not invariant when the same paths are re-expressed with larger HA-weights: a larger weight means more effective samples and hence more statistical weight. That is intentional and faithful to the q-factor recursion of Lervik and van Erp, J. Chem. Theory Comput. 11, 2440 (2015); see thetest_wham_synthetic_weightedregression test.
- pyretis.analysis.wham_analysis.analyse_wham_output(run_dir, interfaces, lamres=None, nskip=0, minblocks=5, interval=1.0, *, skip_begin=0, skip_end=0)¶
Run the standard WHAM analysis on an infinite-swapping run.
- Parameters:
run_dir (str) – The run directory (see
get_path_data_matrix(): a literalinfswap_data.txtinside it takes precedence, falling back to reconstruction from per-ensemble output).interfaces (sequence of float) – The interface positions
[lambda_0, ..., lambda_B](from the run’s run file / config, seeread_interfaces()).lamres (float, optional) – Order-parameter resolution (see
wham_crossing_probability()).nskip (int, optional) – Number of initial paths to discard: the first
nskiprows of a literal data file, or the firstnskippaths of the run’s full path list, the initialisation paths included (seeget_path_data_matrix()).minblocks (int, optional) – Minimum number of blocks for the block-error analysis.
interval (float, optional) – Simulation time per recorded step (
timestep * subcycles), for converting the flux to a rate per unit time. Seewham_crossing_probability(); read it from the run config withread_engine_interval(). The default1.0yields a rate per step.skip_begin (int, optional) – Number of first cycles to leave out, the
[analysis] skip_initial_cyclesof the crossing analysis (seeget_path_data_matrix()). Defaults to 0.skip_end (int, optional) – Number of last cycles to leave out, the
[analysis] skip_final_cyclesof the crossing analysis. Defaults to 0.
- Returns:
results (dict) – The dictionary returned by
wham_crossing_probability(), pluspath_lengths(thepath_length_statistics()dict).
- pyretis.analysis.wham_analysis.detect_infswap_output(directory='.')¶
Check if a directory contains infinite-swapping sampler output.
infswap_data.txtandinfretis_data.txtare recognised, the first taking precedence; without either, the analysis reconstructs the data from per-ensemble output.- Parameters:
directory (str) – Path to check.
- Returns:
data_file (str or None) – Path to the infinite-swapping data file if found, else None.
- pyretis.analysis.wham_analysis.get_path_data_matrix(run_dir='.', nskip=0, skip_begin=0, skip_end=0)¶
Return the path-data matrix for a run, from whichever source exists.
The scheduler writes the per-ensemble route, which is the only output format; WHAM-style analysis reconstructs the same matrix from the
pathensemble.txt/ha_weight.txtfiles (pyretis.inout.pathensemble_output.reconstruct_path_data_matrix()). A literal combined data file (for example apyretis.analysis.combine_datamerge output) takes precedence when present, viadetect_infswap_output(), so this is the single entry point every consumer (pyretis.analysis.interface_estimation. interfaces_from_data(), the WHAM report ofpyretis analyse) should call instead ofread_data_matrix()directly.- Parameters:
run_dir (str, optional) – The run directory: either a literal data file lives directly in it, or it holds the numbered per-ensemble output directories.
nskip (int, optional) – Number of initial rows/paths to discard: the first
nskiprows of a literal data file, or the firstnskippaths of the run’s full path list, the initialisation paths included (pyretis.inout.pathensemble_output. reconstruct_path_data_matrix()).skip_begin (int, optional) – Number of first cycles of the run to leave out, the same cycles in every ensemble’s output, as the crossing analysis leaves them out (
pyretis.inout.pathensemble_output.skip_cycle_bounds(),pyretis.inout.pathensemble_output.run_cycles()). A literal data file records no cycles, so it is refused with a cycle skip.skip_end (int, optional) – Number of last cycles of the run to leave out.
- Returns:
matrix (list of list of float) – See
read_data_matrix().- Raises:
FileNotFoundError – Neither a literal data file nor per-ensemble output directories were found in
run_dir.ValueError – The rows would sum stone-skipping weights of the other acceptance rule; see
pyretis.analysis.ss_weight_check. refuse_biased_path_data(). Or the run is a biretis run (refuse_biretis_path_data()).ValueError – A cycle skip is asked for and the matrix comes from a literal data file, whose rows record no cycle.
- pyretis.analysis.wham_analysis.has_pathensemble_output(directory='.')¶
Check if a directory holds numbered per-ensemble output directories.
- Parameters:
directory (str) – Path to check.
- Returns:
boolean – True if
directoryhas at least one numeric-named subdirectory (the000,001, … layout).
- pyretis.analysis.wham_analysis.path_length_statistics(matrix)¶
Compute path-length statistics from a data matrix.
- Parameters:
matrix (list of list of float) – Data matrix from
read_data_matrix().- Returns:
stats (dict) –
mean,std,min,max,medianof path lengths.
- pyretis.analysis.wham_analysis.read_data_matrix(filename, nskip=0)¶
Read an
infswap_data.txtfile into a numeric matrix.- Parameters:
filename (str) – Path to the
infswap_data.txtfile.nskip (int, optional) – Number of initial data rows to discard (loaded paths / equilibration).
- Returns:
matrix (list of list of float) – One row per path;
"----"entries are mapped to0.0.
- pyretis.analysis.wham_analysis.read_engine_interval(directory='.')¶
Read the time per step (
timestep * subcycles) from a run config.The infinite-swapping data file records path lengths in steps, so the WHAM flux/rate needs this interval to be expressed per unit time (the convention of the PyRETIS flux analysis). The value is read from the run’s
[engine]section, mirroringpyretis.analysis.flux_analysis.analyse_flux()(timestep * subcycles, withsubcyclesdefaulting to 1).- Parameters:
directory (str) – Directory containing the run file (
output.toml, arestart.tomlor aninfswap.toml).- Returns:
interval (float or None) –
timestep * subcycles, orNoneif no config is found or it has no enginetimestep; the caller then decides whether to fail or fall back to a per-step rate.
- pyretis.analysis.wham_analysis.read_interfaces(directory='.')¶
Read the interface list from a run’s run file.
- Parameters:
directory (str) – Directory containing the run file (
output.toml, arestart.tomlor aninfswap.toml).- Returns:
interfaces (list of float or None) – The interface positions, or
Noneif no config is found.
- pyretis.analysis.wham_analysis.rec_block_errors(runav, minblocks)¶
Block-error analysis of a running-average series.
Standard recursive block-error analysis of the running average.
- Parameters:
runav (sequence of float) – The running average of an observable, one entry per path.
minblocks (int) – Minimum number of blocks in the block-error analysis.
- Returns:
half_av_err (float) – Average relative error over the second half of the block lengths.
n_stat_ineff (float) – Statistical inefficiency estimate.
rel_errors (list of float) – Relative error as a function of block length.
- pyretis.analysis.wham_analysis.refuse_biretis_path_data(run_dir)¶
Refuse the path data of a biretis run.
The path data of a run (the WHAM analysis, the interface estimate, the training sets and
pyretis.analysis.combine_data) reads its ensembles as the one ladder of a run from state A. The ensembles of a biretis run are the ladders of two states and the shared ensembles, and its paths start in either state.- Parameters:
run_dir (string) – The run directory.
- Raises:
ValueError – If the run file of
run_diris the one of a biretis run.
- pyretis.analysis.wham_analysis.wham_crossing_probability(matrix, interfaces, lamres=None, minblocks=5, interval=1.0)¶
Compute WHAM crossing probabilities and rate from a data matrix.
Core WHAM crossing-probability, flux and rate computation; the results are returned in a dictionary. The matrix is modified in place by the HA-weight unweighting step.
- Parameters:
matrix (list of list of float) – Data matrix from
read_data_matrix()(alreadynskip-ped).interfaces (sequence of float) – The interface positions
[lambda_0, ..., lambda_B].lamres (float, optional) – Order-parameter resolution. Defaults to one tenth of the smallest interface spacing (see
_default_lamres()); this keeps non-uniform interfaces on distinct grid points. Whatever value is used is validated by_validate_lamres().minblocks (int, optional) – Minimum number of blocks for the block-error analysis.
interval (float, optional) – Simulation time per recorded path step, i.e.
timestep * subcycles. The[0-]/[0+]path lengths are in steps, so the flux is divided by this to give a rate per unit time – matching the PyRETIS flux analysis (pyretis.analysis.flux_analysis.analyse_flux()). The default1.0gives a rate per step; pass the real interval to obtain a physical rate.
- Returns:
results (dict) – Keys:
pcross_pm/pcross_wham(total crossing probability, point-matching and WHAM),pcross_pm_relerr/pcross_wham_relerr(relative block errors),pcross_at_intf(WHAM crossing probability at each interface),pcross_at_intf_pm(point-matching version),flux,rate_pm/rate_wham,rate_pm_relerr,length_0minus/length_0plus,n_records,lambda_valuesandpcross_curve_wham/pcross_curve_pm(the fullP_A(lambda)profiles).
pyretis.analysis.combine_data module¶
Combine several infinite-swapping runs into one data file.
Several runs – possibly with different interface sets, e.g.
successive infinit interface-placement steps, or independent runs to
be pooled for better statistics – are merged into a single
infswap_data.txt-shaped data file + config whose interfaces are the
union of the inputs. Each run’s path data is read via
pyretis.analysis.training_set.get_path_data() (a literal
infswap_data.txt if the run has one, else reconstructed from the
per-ensemble output the scheduler writes), with the run’s skip as its
nskip. Each run’s ensemble columns are re-mapped onto the union
interfaces, and the rows are proportionally interleaved so a downstream
block-error estimate sees a representative mix from every run.
The merged output is a derived analysis file (an explicit merge a user
asks for) in the infswap_data.txt matrix shape, which the WHAM
analysis and interfaces_from_data read.
- pyretis.analysis.combine_data.combine_data(tomls, run_dirs, skip=(100,), out='combo')¶
Combine several runs into
<out>.txt+<out>.toml.- Parameters:
tomls (list of str) – The input TOML config files, one per run (interfaces are read from each).
run_dirs (list of str) – The matching run directories, in the same order – a literal
infswap_data.txtinside one is used if present, otherwise its path data is reconstructed from per-ensemble output (seepyretis.analysis.training_set.get_path_data()).skip (sequence of int, optional) – Number of initial paths to discard per run – either one value for all runs or one per run. It is the
nskipofpyretis.analysis.training_set.get_path_data(): the firstskiprows of a literal data file, or the firstskippaths of the run’s full path list, the initialisation paths included.out (str, optional) – Output basename; writes
<out>.txtand<out>.toml.
- Returns:
interfaces (list of float) – The union interface set written to
<out>.toml.
pyretis.analysis.interface_estimation module¶
Scientific core of the iterative infinit interface-placement driver.
The infinit tool repeatedly runs a short simulation, re-estimates
the crossing probability with WHAM, and re-places the interfaces so every
ensemble carries roughly the same local crossing probability – converging
on a good interface set automatically.
This module holds the pure, testable heart of one such iteration:
binless_pcross()– build the binless WHAM crossing-probability curvep(x)from the per-path weights returned bypyretis.analysis.path_weights.get_path_weights();estimate_updated_interfaces()– given that curve and the current interfaces, compute the next iteration’s interfaces (and matching shooting-move list): interface-cap filtering, the “not enough data” guard, geometric placement viaestimate_interface_positions(), rounding to the lambda resolution, and the land-on-state-A/B fix-ups;interfaces_from_data()– the convenience chain data file -> weights -> Pcross -> updated interfaces.
The outer driver loop, which runs the simulation of each iteration and
re-places the interfaces with interfaces_from_data(), is
pyretis.tools.interface_optimizer.
- pyretis.analysis.interface_estimation.binless_pcross(max_op, weight, first_interface)¶
Build the binless crossing-probability curve from path weights.
A path that reaches order parameter
max_opwith unbiased weightweightcontributes to the crossing probability at every order parameter up tomax_op. Sorting the paths bymax_opand accumulating their weights from the top down therefore gives the (unnormalised) probability to cross each order-parameter value; dividing by the total weight makes it a probability that starts at1at the first interface.- Parameters:
max_op (array_like) – The maximum order parameter of every positive-ensemble path.
weight (array_like) – The matching WHAM-unbiased path weight (see
pyretis.analysis.path_weights.get_path_weights()).first_interface (float) – The first interface (state-A) order parameter; the curve is anchored at
(first_interface, 1.0).
- Returns:
x (numpy.ndarray) – The order-parameter values (no duplicates, increasing).
p (numpy.ndarray) – The crossing probability at each
x(decreasing,p[0] == 1).
- pyretis.analysis.interface_estimation.estimate_updated_interfaces(x, p, interfaces, *, pl_target=0.3, num_ens=None, n_workers=1, lamres=0.001, interface_cap=None, precedence='workers')¶
Compute the next iteration’s interfaces from a Pcross curve.
Filter at the interface cap, bail out if the crossing probability could not be constructed, place interfaces at geometric local-Pcross spacing, round down to the lambda resolution, and nudge any interface that landed on a state boundary.
- Parameters:
x, p (array_like) – The binless crossing-probability curve (see
binless_pcross()).interfaces (list of float) – The current interface positions (only the first and last, state A and state B, are used here).
pl_target (float, optional) – Target per-ensemble local crossing probability (default 0.3). The worker term
p[-1] ** (1 / (2 * n_workers))evaluates to exactly2 * n_workersensembles: the count goes roughly aslog(ptot) / log(pl), so raisingplRAISES it. Under the"workers"precedence the effective target ismax(pl_target, p[-1] ** (1 / (2 * n_workers))), so the worker term is a FLOOR on the ensemble count and sets the interface spacing whenever it exceedspl_target. Under"target"the effective target ispl_target. A conflict, the worker term exceedingpl_target, is logged as a warning under either precedence.num_ens (int, optional) – If given, place exactly this many ensembles (overrides
pl_target).n_workers (int, optional) – The number of simulation workers; the per-ensemble target and a lower bound on the ensemble count both depend on it.
lamres (float, optional) – The lambda resolution; interfaces are rounded down to a multiple of it (default 0.001).
interface_cap (float, optional) – Do not place interfaces above this order parameter (default: the last/state-B interface).
precedence (string, optional) – Which side wins when the requested
pl_targetand the worker-count floor conflict."workers"(the default) lets the floor raise the ensemble count;"target"keeps the requested spacing and accepts that fewer than2 * n_workersensembles leaves workers idle. The conflict is logged as a warning under either choice, so a change to the interface design is always reported. The [infinit] driver places with the default,"workers".
- Returns:
result (dict or None) –
Noneif the crossing probability could not be constructed, is 1 up to the cap or a few units of the last place below 1 (its ratio per ensemble rounds to 1), or places interfaces that do not increase strictly (the caller should keep the current interfaces). Otherwise a dict withinterfaces(the new list),shooting_moves("sh","sh"then"wf"per positive ensemble) andpl_used(the actual per-ensemble local crossing probability).
- pyretis.analysis.interface_estimation.interfaces_from_data(run_dir, interfaces, nskip=0, **kwargs)¶
Estimate updated interfaces directly from a run’s path data.
Convenience chain: read the data matrix (a literal
infswap_data.txtif one exists inrun_dir, else reconstructed from the per-ensemble output – seepyretis.analysis.wham_analysis.get_path_data_matrix()), compute the WHAM-unbiased path weights, build the binless crossing probability, and re-estimate the interfaces. Keyword arguments are forwarded toestimate_updated_interfaces().- Parameters:
run_dir (str) – The run directory (see
pyretis.analysis.wham_analysis. get_path_data_matrix()).interfaces (list of float) – The current interface positions.
nskip (int, optional) – Number of initial paths to discard: the first
nskiprows of a literal data file, or the firstnskippaths of the run’s full path list, the initialisation paths included (seepyretis.analysis.wham_analysis.get_path_data_matrix()).**kwargs – Forwarded to
estimate_updated_interfaces()(pl_target,num_ens,n_workers,lamres,interface_cap,precedence).
- Returns:
result (dict or None) – As returned by
estimate_updated_interfaces()(Noneif the crossing probability could not be constructed, is 1 up to the cap or a few units of the last place below 1, or places interfaces that do not increase strictly).
pyretis.analysis.interface_placement module¶
Automatic interface placement from a crossing-probability curve.
Given a (binless) crossing-probability curve – order parameter x
versus total crossing probability p – place TIS/RETIS interfaces so
that every ensemble carries approximately the same target local crossing
probability pl_target (geometric spacing in p).
This is the self-contained scientific core of infinit; the iterative
“run a short simulation, re-estimate the crossing probability with WHAM,
re-place the interfaces, repeat” driver is
pyretis.tools.interface_optimizer. The crossing-probability curve
consumed here is the binless Pcross that
pyretis.analysis.interface_estimation.binless_pcross() builds from
the path weights of pyretis.analysis.path_weights.get_path_weights(),
or any monotonically-decreasing p(x).
- pyretis.analysis.interface_placement.estimate_interface_positions(x, p, pl_target=0.3, num_ens=None)¶
Estimate interfaces equally spaced with respect to
pl_target.The interfaces are placed so the cumulative crossing probability drops by a constant factor (
pl_target) from one interface to the next – i.e. each ensemble has a local crossing probability of aboutpl_target. The final (state-B / cap) interface is not added, so the probability to reach it stayspl_target.- Parameters:
x (array_like) – The order-parameter values of the crossing-probability curve (assumed to contain no duplicates, as produced by the binless
Pcross).p (array_like) – The total crossing probability at each
x(monotonically decreasing,p[0] == 1).pl_target (float, optional) – The target local crossing probability per ensemble (default 0.3).
num_ens (int, optional) – The number of ensembles to place. If
None(default) it is derived frompl_targetand the final crossing probabilityp[-1].
- Returns:
interfaces (list of float) – The estimated interface positions (the first is
x[0]; the state-B interface is not included).pl_used (float) – The actual per-interface local crossing probability used (so the
num_ensinterfaces tilep[-1]exactly).
pyretis.analysis.path_weights module¶
Unbiased per-path weights and the transmission coefficient.
This module holds two infinite-swapping analysis tools:
get_path_weights()– the WHAM-unbiased equilibrium weight of every positive-ensemble path, so that an observable can be averaged as<O> = sum_i w_i O_i(predictive-power analysis, binless crossing probability, …).transmission_coefficient()– the conditional transmission coefficient for a proposed transition-state value along a chosen collective variable, defined as in Figure 8 of J. Chem. Theory Comput. (doi:10.1021/acs.jctc.5c01814).
The path weights use the same WHAM unweighting as
pyretis.analysis.wham_analysis; the data are the
infswap_data.txt-shaped matrix returned by
pyretis.analysis.wham_analysis.get_path_data_matrix() (a literal
file if the run directory has one, otherwise reconstructed from the
per-ensemble output the scheduler writes).
- pyretis.analysis.path_weights.get_path_weights(matrix, interfaces)¶
Compute the WHAM-unbiased weight of every positive-ensemble path.
The
[0-]ensemble (the firstCxy/HA-weight column) is excluded; weights are computed for the paths sampled in the positive ensembles.- Parameters:
matrix (list of list of float) – The
infswap_data.txtmatrix as returned bypyretis.analysis.wham_analysis.read_data_matrix(). Each row is[path_nr, length, max_op, Cxy_0 ... Cxy_{n-1}, HA_0 ... HA_{n-1}]with"----"already mapped to0.0.interfaces (list of float) – The interface positions (
ninterfaces=> nensemble columns, ensemble 0 being[0-]).
- Returns:
path_nr (numpy.ndarray) – The path index of every positive-ensemble path.
max_op (numpy.ndarray) – The maximum order parameter of each such path.
weight (numpy.ndarray) – The WHAM-unbiased equilibrium weight of each such path.
- pyretis.analysis.path_weights.transmission_coefficient(matrix, interfaces, order_files, ts, *, dim=1, nskip=0)¶
Estimate the conditional transmission coefficient for a CV.
Counts, for every reactive-or-recrossing positive-ensemble path, how many times the chosen collective variable
dimcrosses the proposed transition-state valuets, and forms the WHAM-weighted ratio of reactive paths to total positive crossings.- Parameters:
matrix (list of list of float) – The
infswap_data.txtmatrix (seeget_path_weights()).interfaces (list of float) – The interface positions.
order_files (callable) –
order_files(path_nr)must return the per-frame order-parameter array of that path (columns[time, cv_0, cv_1, ...]), orNoneif it is unavailable.ts (float) – The proposed transition-state value (along the original order parameter; reactive paths are still defined by it).
dim (int, optional) – The collective-variable column of the order array to count crossings for (default 1, the first CV after the time column).
nskip (int, optional) – Number of initial paths in
matrixto discard.
- Returns:
tcoeff (float) – The conditional transmission coefficient.
pyretis.analysis.training_set module¶
Collect a machine-learning training set from path-sampling output.
The module selects a set of configurations spread across the order-parameter range (one frame per chosen path, drawn from the interface band that path belongs to) so they can be used to train, e.g., a machine-learned committor / shooting-point selector:
every draw comes from an explicit
pyretis.core.random_gen.RandomGenerator, so a given seed reproduces the same selection (PyRETIS determinism);the reproducible selection (
select_training_frames(), no trajectory I/O) is separate from the trajectory export (collect_training_set(), which reads/writes frames with ASE and is therefore limited to ASE-readable trajectory formats).
- pyretis.analysis.training_set.collect_training_set(paths, interfaces, input_dir, n_frames, rgen, out='trainingset')¶
Select training frames and export them to an
.xyz+ report.This reads and writes trajectory frames with ASE, so only ASE-readable trajectory formats (multi-frame
.xyz,.traj, NetCDF, …) are supported. The reproducible selection step (select_training_frames()) has no such restriction.- Parameters:
paths, interfaces, input_dir, n_frames, rgen – See
select_training_frames().out (str, optional) – Output basename; writes
<out>.xyzand<out>_report.txt.
- Returns:
selected (list of tuple) – The selected frames (see
select_training_frames()).
- pyretis.analysis.training_set.get_path_data(run_dir, nskip=0)¶
Return
read_path_data()’s shape for a run, from either source.Like
pyretis.analysis.wham_analysis.get_path_data_matrix(): a literal combined infinite-swapping data file inrun_dirtakes precedence (read viaread_path_data()); otherwise the same per-path dicts are built from the per-ensemble output (pyretis.inout.pathensemble_output.reconstruct_path_data_matrix(), converted column-for-column to the[Cxy, HA-weight]string-pair shaperead_path_data()returns, whichselect_training_frames()andpyretis.analysis.combine_dataread).- Parameters:
run_dir (str) – The run directory.
nskip (int, optional) – Number of initial rows/paths to discard: the first
nskiprows of a literal data file, or the firstnskippaths of the run’s full path list, the initialisation paths included (pyretis.inout.pathensemble_output. reconstruct_path_data_matrix()).
- Returns:
paths (list of dict) – See
read_path_data().- Raises:
ValueError – The paths would carry stone-skipping weights of the other acceptance rule; see
pyretis.analysis.ss_weight_check. refuse_biased_path_data(). Or the run is a biretis run (pyretis.analysis.wham_analysis.refuse_biretis_path_data()).
- pyretis.analysis.training_set.read_path_data(filename)¶
Parse an
infswap_data.txtfile into per-path dictionaries.Each returned path records the ensembles it participated in (those columns where both the
Cxyand the high-acceptance weight are present).- Parameters:
filename (str) – Path to the
infswap_data.txtfile.- Returns:
paths (list of dict) – One dict per path with keys
pn(path number, str),len(str),max_op(float) andcols(a dict mapping the ensemble column index to its[Cxy, HA-weight]strings).
- pyretis.analysis.training_set.select_training_frames(paths, interfaces, input_dir, n_frames, rgen)¶
Reproducibly select training frames spread over the interfaces.
Paths are grouped by the ensembles they visited; from each group an even share of paths is drawn (without replacement, no path reused across groups), and from each path one frame is drawn from that group’s interface band. All draws use
rgen, so a given generator state reproduces the selection exactly.- Parameters:
paths (list of dict) – As returned by
read_path_data().interfaces (list of float) – The interface positions.
input_dir (str) – Directory holding the per-path
<pn>/order.txtfiles.n_frames (int) – Target number of frames (split evenly across the groups).
rgen (object like
RandomGenerator) – The random generator used for every selection.
- Returns:
selected (list of tuple) –
(path_nr, frame_index, order_value, ensemble)for each chosen frame, ordered by path number.
pyretis.analysis.ss_weight_check module¶
Find the cycles an analysis leaves out for their stone-skipping weights.
Stone skipping without high acceptance ([tis] high_accept = false)
accepts a trial by the Metropolis factor min(1, c_old / c_new) on the
crossing counts, which samples the path ensemble itself, so each of its
paths carries weight 1 (pyretis.core.moves.ss_weight_move()). A
row whose HA-weight holds the crossing count of such a path over-weights
the paths that cross the middle interface often, and every weighted
average over its ensemble is biased. Such rows are found from the run’s
own files:
[current] ss_weight_from_cyclein the run’s state file (pyretis.core.moves.SS_WEIGHT_RULE_KEY) is the first cycle whose rows carry the weight of the rule their path was sampled with. The rows before it are the candidates, and so is every row of a run whose state file does not hold the key.[current] ss_weight_before(pyretis.core.moves.SS_WEIGHT_BEFORE_KEY) records the move list and layout the candidate rows were written with, and the paths held at the boundary. Without it, the run’s own settings wrote every candidate row.[current] high_accept_changesand the[tis] high_acceptof the run file give the rule each stretch of cycles was sampled with. Only rows sampled without high acceptance are candidates.Only an ensemble whose weight follows a stone-skipping move holds candidates, and a row with HA-weight 0 adds nothing to a weighted sum.
An ensemble is affected when its candidate rows carry more than one distinct HA-weight. A single value is a constant factor over those rows, and a weighted average cancels it.
Where no weight decides where a path goes (TIS, PPTIS, REPPTIS), each affected ensemble loses its candidate cycles and every other ensemble keeps all of its cycles. Where the positive ensembles share the infinite-swapping permanent, the weights also placed the paths, so every ensemble loses the candidate cycles, together with the cycles up to the last row of a path held at the boundary. A path that leaves the live set does not return, so each row after that point belongs to a path placed by the weights of the rule it was sampled with. Those rows start from the paths the candidate cycles left behind, as a run starts from its initial paths, and may need an equilibration skip of their own.
A run whose rows carry no HA-weight and that has no state file is not the scheduler’s output; stone skipping without high acceptance gives its paths weight 1, and it is analysed as it is.
- pyretis.analysis.ss_weight_check.affected_ensembles(rows, candidates, stretches, first_rule_cycle)¶
Return the ensembles whose candidate rows carry varying weights.
- Parameters:
rows (dict of lists of tuples) –
(cycle, path_number, ha_factor)of every occupancy row, by ensemble number.candidates (set of integers) – The ensembles from
candidate_ensembles().stretches (list of tuples) – The stretches from
rule_stretches().first_rule_cycle (integer or None) – The first cycle written with the rule’s weight; None when every row may carry the crossing count.
- Returns:
out (dict of sets) – The distinct HA-weights of each affected ensemble’s candidate rows, by ensemble number.
- pyretis.analysis.ss_weight_check.candidate_ensembles(layout, ensemble_numbers)¶
Return the ensembles whose weight follows a stone-skipping move.
- Parameters:
layout (dict) – The settings from
rows_layout().ensemble_numbers (iterable of integers) – The ensembles (output directory numbers) of the run.
- Returns:
out (set of integers) – The ensembles mapped to
ss. Every ensemble when the layout records no move list.- Raises:
ValueError – If the move list holds
ssin a layout whose directories cannot be mapped to its moves.
- pyretis.analysis.ss_weight_check.check_weights(run_config, filenames)¶
Check a run’s rows for stone-skipping weights of the other rule.
- Parameters:
run_config (dict) – The run’s scheduler configuration, with its
[current]state.filenames (dict of strings) –
pathensemble.txtby ensemble number.
- Returns:
out (object like
WeightCheck) – The affected ensembles and the cycles each ensemble leaves out.
- pyretis.analysis.ss_weight_check.leave_out_biased_cycles(sim_settings, ensemble_settings, ensemble_files)¶
Raise each ensemble’s first analysed cycle past its biased cycles.
- Parameters:
sim_settings (dict) – The analysis settings of the run.
ensemble_settings (list of dicts) – The per-ensemble analysis settings, updated in place: the
[analysis] skip_initial_cyclesof an ensemble that leaves out cycles is raised to cover them.ensemble_files (list of lists of tuples) – The
(file_type, filename)pairs of each ensemble.
- Raises:
ValueError – If an ensemble has no cycle left to analyse.
- pyretis.analysis.ss_weight_check.read_weight_rows(filename)¶
Read the cycle, path number and HA-weight of an ensemble’s rows.
- Parameters:
filename (string) – The ensemble’s
pathensemble.txt.- Returns:
occupancy (list of tuples or None) –
(cycle, path_number, ha_factor)for every row that records a path the ensemble held. None when the rows carry no HA-weight and noha_weight.txtlies beside the file.cycles (list of integers) – The cycle of every data row, in file order.
- Raises:
ValueError – If
ha_weight.txtdoes not line up with the rows row by row.
- pyretis.analysis.ss_weight_check.refusal_bounds(rows, affected, coupled, first_rule_cycle, held=None)¶
Return the last cycle each ensemble leaves out.
- Parameters:
rows (dict of lists of tuples) –
(cycle, path_number, ha_factor)of every occupancy row, by ensemble number.affected (iterable of integers) – The affected ensembles.
coupled (boolean) – Whether the ensembles share the swap permanent.
first_rule_cycle (integer or None) – The first cycle written with the rule’s weight; None when every row may carry the crossing count.
held (list of integers, optional) – The paths held at the boundary, locked ones included. A coupled run with a boundary needs them.
- Returns:
out (dict) – The last left-out cycle by ensemble number,
math.infwhen every cycle is left out. Empty when nothing is affected.- Raises:
ValueError – If a coupled run with a boundary records no held paths.
- pyretis.analysis.ss_weight_check.refuse_biased_path_data(run_dir)¶
Refuse a path-data matrix over rows that carry biased weights.
A path-data matrix sums every cycle a path contributed, so it cannot leave a range of cycles out; it is refused when any ensemble is affected, and when a path held across the weight boundary carries two different HA-weights, which one matrix row cannot hold.
- Parameters:
run_dir (string) – The run directory.
- Raises:
ValueError – If the matrix would sum biased weights.
- pyretis.analysis.ss_weight_check.rows_layout(run_config)¶
Return the settings the candidate rows were written with.
- Parameters:
run_config (dict) – The run’s scheduler configuration, with its
[current]state.- Returns:
out (dict) – The
[current] ss_weight_beforerecord when the state holds one, the run’s[simulation]settings otherwise.
- pyretis.analysis.ss_weight_check.rule_stretches(run_config)¶
Return the
high_accepteach stretch of cycles was sampled with.- Parameters:
run_config (dict) – The run’s scheduler configuration, with its
[current]state.- Returns:
out (list of tuples) –
(last_cycle, high_accept)in cycle order. A stretch runs from the cycle after the previous entry’slast_cycle(from the first cycle for the first entry) to its ownlast_cycle; the last entry’slast_cycleis None.- Raises:
ValueError – If the recorded changes do not chain: a change starts from a value other than the one the previous change set, or the last change sets a value other than the one the run records.