pyretis.inout.analysisio package¶
This package contains functions for input/output for the analysis.
The functions defined here will typically run the analysis on the given input and write outputs, typically this will be plots and simple text files.
Package structure¶
Modules¶
- analysisio.py (
analysisio) Methods that will output results from the analysis functions. The methods defined here can also be used to run an analysis on output files from PyRETIS.
- __init__.py
This file handles imports for PyRETIS.
Important methods defined here¶
- analyse_file (
analyse_file()) Method to analyse a file.
- run_analysis_files (
run_analysis_files()) Method to analyse simulation data in output files. This is a post-processing step.
List of submodules¶
pyretis.inout.analysisio.analysisio module¶
Methods that will output results from the analysis functions.
The Methods defined here will also run the analysis and output according to given settings.
Important methods defined here¶
- analyse_file (
analyse_file()) Method to analyse a file. For example, it can be used as
>>> from pyretis.inout.analysisio import analyse_file >>> result, raw_data = analyse_file('cross', 'cross.txt', settings)
To output the results, for instance by plotting, one can do:
>>> figures = output_results(file_type, plotter, result, raw_data) >>> txt_file = output_results(file_type, txt_plotter, result, raw_data)
- run_analysis_files (
run_analysis_files()) Method to run the analysis on a set of files. It will create output that can be used for reporting.
- pyretis.inout.analysisio.analysisio.ANALYSIS_STOPPED = 'stopped'¶
The key of the result of an analysis that did not run (
run_analysis_files()), which holds why.
- exception pyretis.inout.analysisio.analysisio.NoRowsStop¶
Bases:
ValueErrorWhy the analysis of an energy file or an order file does not run.
analyse_file()raises it with a message that says that the file holds no row, and what to do instead.pyretis analysethen stops the analysis of that file alone, and the report says why (run_analysis_files()).
- pyretis.inout.analysisio.analysisio.analyse_file(file_type, file_name, settings, parts=None)¶
Run analysis on the given file.
This function is included for convenience so that we can call an analysis like
analyse_file('cross', 'cross.txt')i.e. it should automatically open the file and apply the correct analysis according to a given file type. Here we return a function to do the analysis, so we are basically wrapping one of the analysis functions. This is done in case we wish to rerun the analysis but with different settings for instance.The crossing, energy and order files of an md-flux run are read with the other files of the run, beside them, by the parts of the run (
pyretis.analysis.flux_parts.read_run_parts()): the flux analysis reads the parts of the crossing file, and the energy and order analyses read the rows the parts keep. The analyses of an energy file and of an order file stop when the parts keep no row of the file (_refuse_no_rows()).- Parameters:
file_type (string) – This is the type of file we are to analyse.
file_name (string) – The file name to open.
settings (dict) – This dict contains settings which dictate how the analysis should be performed and information on how the simulation was performed.
parts (object like
RunParts, optional) – The parts of the md-flux run of a crossing, energy or order file (pyretis.analysis.flux_parts.RunParts); None to read them from the file and the files beside it (_parts_beside()).
- Returns:
results (list or dict) – The output from the analysis
raw_data (list, numpy.array or another type of object) – The raw data used in the analysis: for a crossing file, the crossings of its parts; for an energy file, the columns of the rows its parts keep, by name; for an order file, those rows.
- Raises:
pyretis.analysis.flux_parts.PartsStop – When the files of an md-flux run hold parts that the analysis cannot tell apart, with the message that says why.
- pyretis.inout.analysisio.analysisio.analysis_name(file_type)¶
Return the name of the analysis of a file type, for its messages.
- Parameters:
file_type (string) – The type of the file the analysis reads.
- Returns:
out (string) – ‘flux’ for the crossing file (‘cross’); the file type for the other files (
_ANALYSIS_NAMES).
- pyretis.inout.analysisio.analysisio.read_first_block(file_type, file_name)¶
Read the first block of data from a file.
This method reads the first block of data from a file: the rows up to the first comment line after a row. The file is read to its end, to check that it holds no line that marks a part of an md-flux run (
pyretis.core.flux_state.parse_part_line()): the files of an md-flux run of this version hold such lines, and the parts of the run are read byanalyse_file(), which this function does not do. When the file holds a second block, it is not read, and a warning says so.- Parameters:
file_type (string) – A string used for selecting the file object to use here.
file_name (string) – The file to open.
- Returns:
out (numpy.array) – The raw data read from the file.
- Raises:
ValueError – When the file type is not ‘energy’, ‘order’ or ‘cross’, and when the file holds a line that marks a part of an md-flux run.
- pyretis.inout.analysisio.analysisio.repptis_running_pcross_analysis(l_ptypes, has_zero_plus=True)¶
Recursive block analysis for repptis.
- Parameters:
l_ptypes (list) – List of cumsum ptypes for the ensembles [0+-‘], [1+-], … [N-1+-], or for [1+-], … [N-1+-] when
has_zero_plusis False.has_zero_plus (boolean, optional) – Whether the first entry of
l_ptypesis the [0+-’] window. With it, the crossing probabilities are P(lambda_i | lambda_0); without it, the first entry is the [1+-] window and they are P(lambda_i | lambda_1).
- Returns:
results (dict) – The results from the analysis.
- pyretis.inout.analysisio.analysisio.run_analysis(settings)¶
Run a predefined analysis task.
A
tisrun whose layout has the[0^-]takes the RETIS analysis (takes_retis_analysis()).- Parameters:
settings (dict) – Simulation settings and settings for the analysis.
- Returns:
out (dict) – A dictionary with the results from the analysis. This dict can be used to generate a report.
- pyretis.inout.analysisio.analysisio.run_analysis_files(settings, files, plotter, txt_plotter, parts=None)¶
Run the analysis on a collection of files.
An analysis that the settings let not run (the energy analysis of settings without
[system] temperature,_ANALYSIS_STOPS) stops alone, with its message logged as an error: its result holds no output and no figures, andANALYSIS_STOPPEDwith the message (stopped_analyses()). So does the flux analysis of a crossing file whose run, or settings, give no flux: it says why by raisingpyretis.analysis.flux_analysis.FluxAnalysisStop; and the analysis of an energy file or an order file that holds no row: it says why by raisingNoRowsStop. The analyses of the other files run and write their results.- Parameters:
settings (dict) – This dict contains settings which dictate how the analysis should be performed and it should also contain information on how the simulation was performed.
files (list of tuples) – This list contains the raw files to be analysed. The tuples are on format (‘filetype’, ‘filename’).
plotter (object like
Plotter) – This is the object that handles the plotting.txt_plotter (object like
Plotter) – This is the object that handles the text output.parts (object like
RunParts, optional) – The parts of an md-flux run that the files hold (pyretis.analysis.flux_parts.RunParts); None to read them from the files (analyse_file()).
- Returns:
out (dict) – The results from the analysis.
- pyretis.inout.analysisio.analysisio.run_particle_settings(settings, exe_path)¶
Return the settings of a run with the record of its particles.
The energy analysis draws the Boltzmann distributions of an internal engine’s run with the number of particles of the run and the degrees of freedom of its temperature (
pyretis.analysis.energy_analysis.analyse_energies()), which the analysis reads from the restart file that records the particles of the run (_particle_record()): for a run with[simulation] restart, the restart file it continues, from which it took its particles and the degrees of freedom of its temperature (pyretis.inout.settings.settings_from_restart(),pyretis.inout.restart.load_system_restart()); for any other run, the restart file it writes in its directory. The settings returned hold the number as[particles] npartand the degrees of freedom under[analysis]pyretis.inout.settings.RUN_TEMPERATURE_DOF(_temperature_dof()).Settings whose
[particles] typeis not ‘internal’ let the energy analysis draw no Boltzmann distribution (pyretis.analysis.energy_analysis.curve_stop()), and the restart file is not read. So does a restart file that is not found or cannot be read (_restart_record(),_unread_restart_message()), and one that records particles of another type than ‘internal’, such as those of an external engine (_undrawn_curves_reason()): the settings returned hold why under[analysis]pyretis.inout.settings.UNDRAWN_CURVES. So does a run whose engine, as the restart file records it, gives a kinetic energy that does not follow the Boltzmann distribution at[system] temperaturewith the degrees of freedom of its temperature, or that the analysis does not know to follow it (_engine_curves_message()): every run but those of the internal engine Langevin withhigh_friction = falsein a box without periodic dimensions. The engine is that of the run, not the[engine]of the settings analysed: a continuation runs the engine of the restart file it continues (pyretis.inout.settings.settings_from_restart()). None of these needs a number of particles: the energy analysis writes the distributions of the energies and of the temperature without the Boltzmann distributions, and says why.For particles of type ‘internal’ and a restart file that is read, when the analysis reads no number of particles or degrees of freedom from it (it records no type of particles, no number of particles,
_npart_of_particles(), or no degrees of freedom,_temperature_dof()), the settings returned hold why under[analysis]pyretis.inout.settings.UNRESOLVED_PARTICLES, and the energy analysis alone stops with it; a[particles] npartthat the settings state gives no degrees of freedom. A stated[particles] npartis checked against the number of particles that the restart file records, whether the energy analysis draws the Boltzmann distributions or not: when it differs, the energy analysis alone stops in the same way; when it equals it, the settings returned hold that number under[analysis]pyretis.inout.settings.CHECKED_NPART. A[particles] npartthat is not a positive integer is left for the energy analysis to refuse (pyretis.analysis.energy_analysis.energy_analysis_stop()). No number is taken from[particles] mass, a table keyed by the name of a particle.- Parameters:
settings (dict) – The settings of the analysis; not changed.
exe_path (string) – The directory of the run, where its output is analysed.
- Returns:
out (dict) – A copy of the settings (
pyretis.inout.settings.copy_settings()) with the number of particles of the run and the degrees of freedom of its temperature, or with why the energy analysis has none, or with why it draws no Boltzmann distribution.- Raises:
Exception – An error of unpickling the restart file that is not one of a file that cannot be read here (
_UNREADABLE_RESTART), as the unpickling raises it (_RestartUnpickler).
- pyretis.inout.analysisio.analysisio.stopped_analyses(results)¶
Return the analyses of a task that did not run, with why.
- Parameters:
results (object) – The results of
run_analysis().- Returns:
out (dict) – Why each analysis that did not run stopped (
run_analysis_files()), keyed by the type of the file it reads; empty when every analysis ran. Results that are not a dict of the results of each file type hold none.
- pyretis.inout.analysisio.analysisio.takes_retis_analysis(settings)¶
Say whether a
tisrun takes the RETIS analysis.A
task = "tis"run with two, or four or more interfaces and no[tis] ensemble_numbersamples the[0^-], the[0^+]and the body ensembles of its interfaces, the ensembles of aretisrun, without swaps (pyretis.inout.checker.ensemble_layout()gives it the[0^-]). The RETIS analysis (run_retis_analysis()) reads what it needs from thepathensemble.txtof each ensemble: the crossing probabilities of the[i^+], and the path lengths of the[0^-]and the[0^+], which give the flux.run_analysis()gives the run that analysis, andpyretis analysewrites its RETIS report. A swap acceptance ratio of a run without swaps is reported as not available, as for a move that is never attempted.- Parameters:
settings (dict) – The settings of the run, with the
[simulation]section and, when the input has one, the[tis]section.- Returns:
out (boolean) – True for a
tisrun whose layout has the[0^-].
- pyretis.inout.analysisio.analysisio.unanalysed_task(settings)¶
Say why
pyretis analysegives no analysis of a run.pyretis analyseanalyses the path-sampling tasks and themd-fluxtask (run_analysis()). Anmdormd-nverun writes its energies, its order parameter and its trajectory to files, and has no analysis of its own.- Parameters:
settings (dict) – The settings of the run.
- Returns:
out (string or None) – For an
mdormd-nverun, the message: the analysis it has not, the files that hold its results, and the task whose analysis gives the energy and the order parameter analyses; None for the other tasks.