pyretis.inout.engine_temperature package

Read the temperature an external engine runs and draws at.

An external engine states its temperature in its own input: the GROMACS mdp file, the CP2K input, the OpenMM Simulation, the AMS input and the LAMMPS script. The readers in this package read that temperature from the input alone, without building an engine. Each reader returns every temperature the input sets, keyed by the name of the setting, because one input can set several (one ref-t per GROMACS coupling group, a LAMMPS SET_TEMP variable next to a thermostat fix). A reader raises a ValueError that names the file and the key to set when the input leaves the temperature out, sets it in a form the reader cannot turn into a number, or changes it during the run (annealing, a ramp, a schedule). The LAMMPS and AMS readers also refuse a setting that sets or changes the temperature of the atoms by other means (a heat source, Monte Carlo moves at a temperature of their own), and a LAMMPS fix style or AMS block outside the ones the reader knows, whose effect on the temperature is unknown.

Modules

pyretis.inout.engine_temperature.common

The temperature types and the helpers the engine readers share.

pyretis.inout.engine_temperature.gromacs

The GROMACS mdp file.

pyretis.inout.engine_temperature.cp2k

The CP2K input file.

pyretis.inout.engine_temperature.openmm

The OpenMM Simulation.

pyretis.inout.engine_temperature.ams

The AMS input file.

pyretis.inout.engine_temperature.lammps_commands

The commands of a LAMMPS script as LAMMPS reads them.

pyretis.inout.engine_temperature.lammps_restart

The header of a LAMMPS restart file.

pyretis.inout.engine_temperature.lammps_script

The temperatures, the restart files and the time step of a LAMMPS script.

pyretis.inout.engine_temperature.lammps_scan

The scan of a LAMMPS script and of the files it includes.

Important classes and functions

EngineTemperatures (EngineTemperatures)

The temperatures read from one engine input.

SeparateTemperature (SeparateTemperature)

A setting that can give a part of the system a temperature of its own.

same_temperature (same_temperature())

Tell whether two temperatures are one temperature to the round-off of a double.

read_gromacs_temperatures (read_gromacs_temperatures())

Read gen-temp and the thermostat ref-t of a GROMACS mdp file.

mdp_key_as_written (mdp_key_as_written())

Return a key of a GROMACS mdp file as the file writes it.

cp2k_md_temperature (cp2k_md_temperature())

Return the TEMPERATURE keyword of a CP2K MOTION/MD section.

read_cp2k_temperatures (read_cp2k_temperatures())

Read MOTION/MD TEMPERATURE of a CP2K input file.

openmm_temperatures (openmm_temperatures())

Read the temperatures of the integrator and of the forces with a temperature (a thermostat or a barostat) of an OpenMM Simulation.

read_ams_temperatures (read_ams_temperatures())

Read the initial-velocity and thermostat temperatures of an AMS input.

read_lammps_temperatures (read_lammps_temperatures())

Read SET_TEMP, the thermostat fixes and the velocity commands of a LAMMPS script.

lammps_refused_fix (lammps_refused_fix())

Tell whether the reader of a LAMMPS script refuses a fix style.

LammpsRestartHeader (LammpsRestartHeader)

The unit system and the time step of a LAMMPS restart file.

LammpsRestarts (LammpsRestarts)

The unit system, the restart files and the time step of a LAMMPS script that reads a restart file.

is_lammps_restart_file (is_lammps_restart_file())

Tell whether a file starts as a LAMMPS restart file starts.

read_lammps_restart_header (read_lammps_restart_header())

Read the unit system and the time step of a LAMMPS restart file.

refuse_lammps_restart_file (refuse_lammps_restart_file())

Refuse a restart file that LAMMPS opens and the script contradicts.

read_lammps_restarts (read_lammps_restarts())

Read the unit system, the restart files and the time step of a LAMMPS script.

lammps_script_reads_restart (lammps_script_reads_restart())

Tell where a LAMMPS script can read a restart file.

read_lammps_timestep (read_lammps_timestep())

Read the time step LAMMPS runs a script with.

read_lammps_units (read_lammps_units())

Read the unit system LAMMPS runs a script with.

lammps_script_files (lammps_script_files())

Return the files that the include and jump commands of a script name.

lammps_script_commands (lammps_script_commands())

Return the commands of a LAMMPS script as LAMMPS reads them.

List of submodules

pyretis.inout.engine_temperature.common module

The temperature types and the helpers the engine readers share.

EngineTemperatures holds the temperatures read from one engine input, SeparateTemperature a setting that can give a part of the system a temperature of its own, and same_temperature() tells whether two temperatures are one temperature. The helpers turn a temperature written in an input into a number and split a line into words.

class pyretis.inout.engine_temperature.common.EngineTemperatures(source: str, values: dict = <factory>, unit: str = 'K', engine_units: str | None = None, separate: dict = <factory>, advice: str = '', advised: tuple = ())

Bases: object

The temperatures read from one engine input.

Variables:

  • source (string) – The file (or module) the temperatures were read from.

  • values (dict of float) – One entry per setting of the input that holds a temperature, keyed by the name of that setting (for instance 'gen-temp' or 'ref-t[System]'), in the order of the input.

  • unit (string) – 'K' for kelvin, or 'lj' for the reduced temperature of a LAMMPS script in units lj.

  • engine_units (string or None) – The unit system the input declares (the LAMMPS units command), or None for an input that declares none.

  • separate (dict of SeparateTemperature) – The settings of values that can give a part of the system a temperature of its own (the Drude temperature of an OpenMM integrator), keyed like values, with what a message calls that temperature and the setting it belongs to.

  • advice (string) – Said after the advice to set different temperatures to the same value: how the input gives a temperature that one of its settings derives (an OpenMM CustomIntegrator kT, the thermal energy, openmm_temperatures()). Empty for no more advice; it takes no part in comparing two EngineTemperatures.

  • advised (tuple of strings) – The keys of values that advice is about (the kT of each OpenMM CustomIntegrator). The advice is said when one of the settings the refusal asks to set to the same value is such a key and the others of those settings agree among themselves, or there are none: changing such a setting is then the fix (_advice_for()). It takes no part in comparing two EngineTemperatures.

_advice_for(keys)

Return the advice after the refusal of different temperatures.

Parameters:

keys (list of strings) – The keys of values that the refusal asks to set to the same value; they hold different temperatures.

Returns:

out (string) – advice when one of keys is in advised and the temperatures of the others of keys are one temperature (same_temperature()) or there are none: then a setting of advised holds another temperature than the others. Empty otherwise.

_apart(key, others)

Tell whether a setting of separate holds a temperature apart.

Parameters:

  • key (string) – The setting, a key of separate.

  • others (list of float) – The temperatures of the settings that are not in separate.

Returns:

out (boolean) – True when the setting holds another temperature (same_temperature()) than the setting it belongs to (SeparateTemperature.part_of), or, for a setting that belongs to none, than one of the other settings, or when there is no other setting.

advice: str = ''
advised: tuple = ()
agreed()

Return the one temperature that every setting holds.

Equal temperatures written in different ways (300, 300.0, 3.0E+02) are the same float. A temperature an engine computes from a thermal energy (an OpenMM CustomIntegrator kT) differs from the one given in kelvin by a few units in the last place; the settings hold one temperature when the lowest and the highest are one temperature (same_temperature()). A setting of separate that holds another temperature than the setting it belongs to (SeparateTemperature.part_of) gives a part of the system a temperature of its own, which PyRETIS does not support: an engine runs at one temperature.

Returns:

out (float) – The temperature of the first setting, in the order of values: for an OpenMM simulation, the temperature of the integrator, at which PyRETIS draws velocities.

Raises:

ValueError – If the input holds no temperature, or holds different ones. The message names each setting with its temperature; for a setting of separate that holds another temperature than the setting it belongs to, it says that PyRETIS does not support a separate temperature, and does not advise setting the two to the same value. The advice to set different temperatures to the same value is followed by advice when a setting of advised differs from the others, which agree among themselves (_advice_for()).

engine_units: str | None = None
separate: dict
source: str
unit: str = 'K'
values: dict
class pyretis.inout.engine_temperature.common.SeparateTemperature(name: str, part_of: str | None)

Bases: object

A setting that can give a part of the system a temperature of its own.

The Drude temperature of an OpenMM integrator thermostats the motion of each Drude particle relative to its core, and the temperature of the integrator (or of its thermostat chain) the rest of the motion. The setting gives the Drude pairs a temperature of their own when it holds another value than that temperature.

Variables:

  • name (string) – What a message calls the temperature, such as 'a separate Drude temperature'.

  • part_of (string or None) – The key, in EngineTemperatures.values, of the temperature of the integrator or thermostat chain the setting belongs to; None for an integrator without a temperature of its own (DrudeSCFIntegrator), whose setting is compared with every other setting of the input.

name: str
part_of: str | None
pyretis.inout.engine_temperature.common.TEMPERATURE_AGREEMENT_EPSILONS = 4

The largest difference, in machine epsilons relative to the larger temperature, between two temperatures that are one temperature. A temperature divided back from its thermal energy differs from the temperature by a few units in the last place: an OpenMM CustomIntegrator thermal energy kT computed as MOLAR_GAS_CONSTANT_R times T gives kT / R within 1.511 epsilons (3 units in the last place) of T as a Quantity converted to kJ/mol, the route of the shipped openmm_sim.py, and as the kT of MTSLangevinIntegrator, and within 0.532 epsilons as a float product (OpenMM 8.5; the 143,929 temperatures k/64 K and k/10 K from 1 K to 2000 K).

pyretis.inout.engine_temperature.common._closing_quote(text, index, quote, where)

Return the position of the quote that closes a quoted text.

Parameters:

  • text (string) – The line.

  • index (integer) – The position of the opening quote.

  • quote (string) – The opening quote.

  • where (string) – The file and line, for the error message.

Returns:

out (integer) – The position of the closing quote.

Raises:

ValueError – If the quote is not closed on the line.

pyretis.inout.engine_temperature.common._number_temperature(text, source, key)

Convert a temperature written as a decimal number to a float.

Parameters:

  • text (string) – The value as written in the input.

  • source (string) – The input file, for the error message.

  • key (string) – The setting that holds the temperature, for the error message.

Returns:

out (float) – The temperature.

Raises:

ValueError – If text is not a decimal number, or the number is not a positive temperature.

pyretis.inout.engine_temperature.common._positive_temperature(value, source, key)

Return a temperature that is a finite, positive number.

Parameters:

  • value (float) – The temperature read from the input.

  • source (string) – The input file, for the error message.

  • key (string) – The setting that holds the temperature, for the error message.

Returns:

out (float) – value.

Raises:

ValueError – If value is not finite or not positive.

pyretis.inout.engine_temperature.common._quote_at(text, index, quotes)

Return the quote that starts at a position of a line.

Parameters:

  • text (string) – The line.

  • index (integer) – The position.

  • quotes (tuple of strings) – The quotes of the input format, the longest first.

Returns:

out (string or None) – The quote that starts at index, or None.

pyretis.inout.engine_temperature.common._split_words(text, quotes, where)

Split a line into words, keeping quoted text in one word.

Parameters:

  • text (string) – The line.

  • quotes (tuple of strings) – The quotes of the input format, the longest first.

  • where (string) – The file and line, for the error message.

Returns:

out (list of strings) – The words, with the quotes removed.

Raises:

ValueError – If a quote is not closed.

pyretis.inout.engine_temperature.common.same_temperature(first, second)

Tell whether two temperatures are one temperature.

Two temperatures are one temperature when they differ by at most TEMPERATURE_AGREEMENT_EPSILONS machine epsilons (8.9e-16) relative to the larger one: the round-off of a temperature computed from a thermal energy. 250 K and 250.0000000000001 K are one temperature; 250 K and 250.001 K are two.

Parameters:

  • first (float) – A temperature.

  • second (float) – Another temperature, in the unit of first.

Returns:

out (boolean) – True when the two are one temperature.

pyretis.inout.engine_temperature.gromacs module

Read the temperatures of a GROMACS mdp file.

read_gromacs_temperatures() reads the temperatures of an mdp file, read_mdp_settings() its settings as grompp reads them, and mdp_key_as_written() returns a key of the file as the file writes it.

pyretis.inout.engine_temperature.gromacs._gromacs_name(name)

Return an mdp key or option the way grompp compares it.

grompp compares mdp keys and their options ignoring case and the characters - and _, so ref-t, ref_t and REF-T are the same key and V-rescale and v_rescale the same option.

Parameters:

name (string) – The key or option as written in the mdp file.

Returns:

out (string) – name in lower case with every - and _ removed.

pyretis.inout.engine_temperature.gromacs._gromacs_thermostat_active(settings, filename)

Tell whether an mdp file couples the system to ref-t.

The stochastic integrators sd and bd couple to ref-t themselves. The other integrators couple to ref-t when tcoupl is set to a thermostat. GROMACS defaults to integrator = md and tcoupl = no.

Parameters:

  • settings (dict of string) – The mdp settings, from read_mdp_settings().

  • filename (string) – The mdp file, for the error message.

Returns:

out (boolean) – True if the run is coupled to ref-t.

Raises:

ValueError – If tcoupl is not a GROMACS thermostat option.

pyretis.inout.engine_temperature.gromacs.mdp_key_as_written(filename, key)

Return a key of a GROMACS mdp file as the file writes it.

Parameters:

  • filename (string) – The mdp file.

  • key (string) – The key, in any form grompp takes for it (gen-temp, gen_temp, GEN-TEMP; _gromacs_name()).

Returns:

out (string or None) – The key as the first key = value line of the file that sets it writes it, outside a ; comment and without the white space around it; None when no line sets it.

pyretis.inout.engine_temperature.gromacs.read_gromacs_temperatures(filename)

Read the temperatures of a GROMACS mdp file.

gen-temp is the temperature of the velocities GROMACS draws for a velocity_generation = "engine" run, and it is required: GROMACS draws at 300 K when it is absent. When the run is coupled to a thermostat (integrator = sd or bd, or tcoupl other than no), each ref-t value is the bath temperature of one tc-grps group and is read too. A ref-t without a thermostat has no effect in GROMACS and is left out.

Parameters:

filename (string) – The mdp file.

Returns:

out (object like EngineTemperatures) – 'gen-temp', and 'ref-t[<group>]' for every tc-grps group of a coupled run, in kelvin.

Raises:

ValueError – If gen-temp is absent, annealing is set for a group, a coupled run does not give one ref-t per tc-grps group, or a temperature is not a positive number.

pyretis.inout.engine_temperature.gromacs.read_mdp_settings(filename)

Read the settings of a GROMACS mdp file as grompp reads them.

A ; starts a comment. Every other non-blank line is key = value, split at its first = (a define value can hold more). A key with an empty value takes the GROMACS default, so it is left out of the result.

Parameters:

filename (string) – The mdp file.

Returns:

out (dict of string) – The values, keyed by the key in the form _gromacs_name() gives it ('reft' for ref-t).

Raises:

ValueError – If a line has no = or no key, or a key is set twice (grompp refuses all three).

pyretis.inout.engine_temperature.cp2k module

Read the temperature of a CP2K input file.

read_cp2k_temperatures() reads MOTION/MD TEMPERATURE of a CP2K input file, and cp2k_md_temperature() returns the TEMPERATURE keyword of a MOTION/MD section.

pyretis.inout.engine_temperature.cp2k._cp2k_keyword_values(md_lines, keyword, source, unit)

Return the values of one keyword of a CP2K section.

The keyword is matched as a whole word and ignoring case, so temperature 400 sets TEMPERATURE and TEMPERATURE_ANNEALING 0.99 sets another keyword.

Parameters:

  • md_lines (list of strings) – The keyword lines of the section.

  • keyword (string) – The keyword, in upper case.

  • source (string) – The CP2K input, for the error message.

  • unit (string or None) – The unit tag the keyword accepts, see _cp2k_number().

Returns:

out (list of floats) – One value per line that sets the keyword.

pyretis.inout.engine_temperature.cp2k._cp2k_number(words, source, key, unit)

Convert the value words of a CP2K keyword to one number.

Parameters:

  • words (list of strings) – The words that follow the keyword: an optional unit tag ([K]) and the number.

  • source (string) – The CP2K input, for the error message.

  • key (string) – The keyword, for the error message.

  • unit (string or None) – The one unit tag the keyword accepts (compared ignoring case), or None for a keyword that takes no unit.

Returns:

out (float) – The number.

Raises:

ValueError – If the unit tag is another one, or the value is not one number.

pyretis.inout.engine_temperature.cp2k._cp2k_text(line)

Return a CP2K input line without its comment.

CP2K starts a comment at ! or #.

Parameters:

line (string) – A line of the CP2K input.

Returns:

out (string) – The line up to the first ! or #, stripped.

pyretis.inout.engine_temperature.cp2k.cp2k_md_temperature(md_lines, source)

Return the TEMPERATURE keyword of a CP2K MOTION/MD section.

The keyword is matched as a whole word and ignoring case, and it takes an optional [K] unit tag: TEMPERATURE 300, temperature 300 and TEMPERATURE [K] 300 all give 300. Other keywords that start with the same letters, such as TEMPERATURE_ANNEALING, are other keywords.

Parameters:
Returns:

out (float or None) – The temperature in kelvin, or None when the section sets no TEMPERATURE.

Raises:

ValueError – If the section sets TEMPERATURE more than once, gives it in another unit than kelvin, or sets a value that is not a number.

pyretis.inout.engine_temperature.cp2k.read_cp2k_temperatures(filename)

Read MOTION/MD TEMPERATURE of a CP2K input file.

The temperature is required: CP2K runs at 300 K when it is absent. The reader refuses the inputs whose temperature changes during the run or differs between regions: TEMPERATURE_ANNEALING or ANNEALING other than 1, and MOTION/MD/THERMAL_REGION. The input is read as the CP2K engines read it, with its @INCLUDE files and @SET variables resolved (pyretis.inout.formats.cp2k.read_cp2k_template()), so the reader and the engines read the same temperature.

Parameters:

filename (string) – The CP2K input file.

Returns:

out (object like EngineTemperatures) – 'MOTION/MD TEMPERATURE', in kelvin.

Raises:

pyretis.inout.engine_temperature.openmm module

Read the temperatures of an OpenMM Simulation.

openmm_temperatures() reads the temperatures of the integrator and of the forces with a temperature (a thermostat or a barostat) of an OpenMM Simulation.

pyretis.inout.engine_temperature.openmm._openmm_compound_temperatures(integrator, name, source)

Read the temperatures of an OpenMM CompoundIntegrator.

Parameters:

  • integrator (object like openmm.CompoundIntegrator) – The compound integrator.

  • name (string) – The name of the compound integrator in the keys, with its place in a CompoundIntegrator that holds it.

  • source (string) – The module the simulation comes from, for the error message.

Returns:

  • values (dict of float) – The temperatures in kelvin of each integrator it holds (_openmm_integrator_temperatures()), those of the integrator it steps with (getCurrentIntegrator) first; empty when it holds none.

  • separate (dict of SeparateTemperature) – The keys of values that are a temperature of the Drude pairs of their own.

  • thermal (list of strings) – The keys of values read from the global variable kT of a CustomIntegrator.

pyretis.inout.engine_temperature.openmm._openmm_integrator_temperatures(integrator, source, prefix='')

Read the temperatures one OpenMM integrator states.

The temperature of the integrator is getTemperature() and, for a CustomIntegrator that holds the global variable kT (the thermal energy in kJ/mol), kT divided by the molar gas constant (pyretis.engines.openmm.custom_integrator_temperature()): a CustomIntegrator of a class with getTemperature() (as those of openmmtools) states both temperatures, which must agree. A Nose-Hoover integrator has one temperature per thermostat chain, plus the relative temperature of a chain that thermostats particle pairs (Drude pairs), and a Drude Langevin integrator has the Drude temperature; these two are a temperature of the Drude pairs of their own (SeparateTemperature). A CompoundIntegrator states the temperatures of every integrator it holds, the current one or not, read in the same way: each of them can step the simulation. The temperatures of the integrator it steps with (getCurrentIntegrator) come first.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator.

  • source (string) – The module the simulation comes from, for the error message.

  • prefix (string, optional) – The start of the keys of the temperatures: empty for the integrator of the simulation, and the place in its CompoundIntegrator for an integrator a CompoundIntegrator holds ('CompoundIntegrator integrator 0 ').

Returns:

  • values (dict of float) – The temperatures in kelvin, keyed by the integrator method or the variable they come from; empty for an integrator that states none.

  • separate (dict of SeparateTemperature) – The keys of values that are a temperature of the Drude pairs of their own.

  • thermal (list of strings) – The keys of values read from the global variable kT of a CustomIntegrator.

Raises:

ValueError – If a method that gives a temperature returns no temperature Quantity (_openmm_kelvin()).

pyretis.inout.engine_temperature.openmm._openmm_kelvin(value, source, key)

Return a temperature an OpenMM method returns, in kelvin.

Parameters:

  • value (object) – What the method returns.

  • source (string) – The module the simulation comes from, for the error message.

  • key (string) – The integrator and the method, as 'WithT.getTemperature()', for the error message.

Returns:

out (float) – The temperature in kelvin.

Raises:

ValueError – If value is not an openmm.unit.Quantity with a unit of temperature.

pyretis.inout.engine_temperature.openmm._openmm_no_temperature_message(integrator, source)

Return the refusal of an OpenMM simulation that states no temperature.

The message names the integrator of the simulation (and, for a CompoundIntegrator, the integrators it holds), says that the System has no force with a temperature, and how to state the temperature without changing the dynamics: an AndersenThermostat with collision frequency 0. For a CustomIntegrator the message says that it states its temperature by its global variable kT, which it does not hold, and that it applies the AndersenThermostat in an addUpdateContextState() step.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator of the simulation, which states no temperature.

  • source (string) – The module the simulation comes from.

Returns:

out (string) – The message.

pyretis.inout.engine_temperature.openmm._openmm_random_without_thermal_energy(integrator, prefix='')

Return the CustomIntegrators that draw random numbers without kT.

A CustomIntegrator that draws random numbers (pyretis.engines.openmm.custom_integrator_draws_random_numbers()) thermostats on its own, at the temperature its expressions use. One without the global variable kT holds that temperature in a variable PyRETIS does not read. A CompoundIntegrator holds the integrators of every CompoundIntegrator it holds.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator.

  • prefix (string, optional) – The start of the names returned: empty for the integrator of the simulation, and the place in its CompoundIntegrator for an integrator a CompoundIntegrator holds ('CompoundIntegrator integrator 0 ').

Returns:

out (list of strings) – The name of each such integrator, with its place in the CompoundIntegrator that holds it; empty when there is none.

pyretis.inout.engine_temperature.openmm._openmm_stepping_integrators(integrator)

Return the integrators an OpenMM integrator steps with.

Parameters:

integrator (object like openmm.Integrator) – The integrator.

Returns:

out (list) – Each integrator a CompoundIntegrator holds, those of a CompoundIntegrator it holds included, or [integrator] for any other integrator.

pyretis.inout.engine_temperature.openmm._openmm_thermal_energy_advice()

Return how PyRETIS reads the kT of an OpenMM integrator.

A kT computed with another value of the molar gas constant than OpenMM’s (0.0083144626 * T) reads as another temperature than T, which the forces with a temperature then differ from.

Returns:

out (string) – The advice, starting with a space: PyRETIS reads the temperature of the global variable kT of a CustomIntegrator (pyretis.engines.openmm.custom_integrator_temperature()) as kT divided by the MOLAR_GAS_CONSTANT_R of OpenMM.

pyretis.inout.engine_temperature.openmm._openmm_thermal_energy_temperatures(integrator, name)

Read the temperature of the kT of an OpenMM integrator.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator, which is not a CompoundIntegrator.

  • name (string) – The name of the integrator in the keys, with its place in a CompoundIntegrator that holds it.

Returns:

out (dict of float) – For a CustomIntegrator that holds the global variable kT (the thermal energy in kJ/mol), kT divided by the molar gas constant (pyretis.engines.openmm.custom_integrator_temperature()), in kelvin, keyed '<name> global variable kT'; empty for any other integrator.

pyretis.inout.engine_temperature.openmm._openmm_unread_temperature_variables(integrator, prefix='')

Return the variables named kT that PyRETIS reads no temperature from.

A CustomIntegrator gives its temperature by its global variable kT, spelled so (pyretis.engines.openmm.custom_integrator_temperature()). A variable named kT in another letter case (KT, kt, Kt), global or per degree of freedom, and a per-degree-of-freedom variable kT can hold the temperature at which the CustomIntegrator thermostats, and give no one temperature PyRETIS reads. A CompoundIntegrator holds the variables of every integrator it holds, those of a CompoundIntegrator it holds included.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator.

  • prefix (string, optional) – The start of the names returned: empty for the integrator of the simulation, and the place in its CompoundIntegrator for an integrator a CompoundIntegrator holds ('CompoundIntegrator integrator 0 ').

Returns:

out (list of strings) – Each such variable, with the integrator that holds it and its kind, as 'CustomIntegrator global variable KT'; empty when the integrator holds none.

pyretis.inout.engine_temperature.openmm._refuse_openmm_random_without_thermal_energy(integrator, source)

Refuse a random CustomIntegrator without the global variable kT.

A CustomIntegrator that draws random numbers and holds no global variable kT (_openmm_random_without_thermal_energy()), alone or in a CompoundIntegrator, nested ones included, thermostats at a temperature PyRETIS does not read. With a force with a temperature (a thermostat or a barostat) the run would draw, record and analyse at the temperature of the force, so the simulation is refused whatever force with a temperature its System holds. A CustomIntegrator without kT that draws no random numbers (velocity Verlet) takes the temperature of such a force.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator of the simulation.

  • source (string) – The module the simulation comes from, for the error message.

Raises:

ValueError – If the integrator, or an integrator its CompoundIntegrator holds, is a CustomIntegrator that draws random numbers and has no global variable kT.

pyretis.inout.engine_temperature.openmm._refuse_unread_openmm_temperature_variables(integrator, source)

Refuse an OpenMM integrator with a kT variable PyRETIS does not read.

A CustomIntegrator that holds a variable named kT from which PyRETIS reads no temperature (_openmm_unread_temperature_variables(): in another letter case, or per degree of freedom), alone or in a CompoundIntegrator, nested ones included, can thermostat at the temperature that variable stands for. PyRETIS cannot compare that temperature with the one the simulation states (the integrator and the forces with a temperature), so the simulation is refused, whatever force with a temperature its System holds.

Parameters:

  • integrator (object like openmm.Integrator) – The integrator of the simulation.

  • source (string) – The module the simulation comes from, for the error message.

Raises:

ValueError – If the integrator, or an integrator its CompoundIntegrator holds, is a CustomIntegrator with such a variable.

pyretis.inout.engine_temperature.openmm.openmm_temperatures(simulation, source)

Read the temperatures of an OpenMM Simulation.

The temperatures of the integrator (_openmm_integrator_temperatures()): getTemperature() and, for a CustomIntegrator that holds the global variable kT (the thermal energy in kJ/mol), kT divided by the molar gas constant (pyretis.engines.openmm.thermal_energy_temperature()). A Nose-Hoover integrator has one temperature per thermostat chain, plus the relative temperature of a chain that thermostats particle pairs (Drude pairs), and a Drude Langevin integrator has the Drude temperature; these two are a temperature of the Drude pairs of their own (EngineTemperatures.separate). A CompoundIntegrator states the temperatures of every integrator it holds, the current one or not, read in the same way, those of the integrator it steps with (getCurrentIntegrator) first. A force of the System that carries a temperature parameter (AndersenThermostat and the Monte Carlo barostats) adds the value of that parameter in the Context. The engine runs at the first temperature when they are one temperature (EngineTemperatures.agreed()). When a temperature read from a kT differs from the others, which agree among themselves (or there are none), the refusal of different temperatures says how PyRETIS reads kT (_openmm_thermal_energy_advice(), EngineTemperatures.advised).

A simulation that states no temperature, an integrator without one (VerletIntegrator, a CustomIntegrator without the global variable kT, a CompoundIntegrator of such integrators) and no force with a temperature (a thermostat or a barostat), is refused: no temperature is assumed for it. The refusal says how to state the temperature without changing the dynamics: an AndersenThermostat with collision frequency 0, which changes no velocity.

A CustomIntegrator that holds a variable named kT from which PyRETIS reads no temperature, a per-degree-of-freedom one or a global one in another letter case (KT, kt, Kt), alone or in a CompoundIntegrator, nested ones included, can thermostat at the temperature of that variable, which PyRETIS cannot compare with the temperature the simulation states: the simulation is refused before any temperature is read, whatever force with a temperature its System holds (_refuse_unread_openmm_temperature_variables()). So is a CustomIntegrator that draws random numbers and holds no global variable kT, alone or in a CompoundIntegrator, nested ones included: its random numbers act at a temperature PyRETIS does not read (_refuse_openmm_random_without_thermal_energy()). A CustomIntegrator without kT that draws no random numbers (velocity Verlet) takes the temperature of a force with a temperature.

Parameters:

  • simulation (object like openmm.app.Simulation) – The simulation, with its integrator, System and Context.

  • source (string) – The module the simulation comes from, for the error message.

Returns:

out (object like EngineTemperatures) – The temperatures in kelvin, keyed by the integrator method, the variable or the force parameter they come from; the keys of the temperatures of an integrator a CompoundIntegrator holds start with its place ('CompoundIntegrator integrator 0 CustomIntegrator global variable kT').

Raises:

ValueError – If the integrator, or an integrator its CompoundIntegrator holds, is a CustomIntegrator with a variable named kT from which PyRETIS reads no temperature, or a CustomIntegrator that draws random numbers and has no global variable kT; if a method that gives a temperature (getTemperature()) returns no temperature Quantity; if neither the integrator (nor an integrator its CompoundIntegrator holds) nor a force of the System (a thermostat or a barostat) carries a temperature; or if a temperature is not positive.

pyretis.inout.engine_temperature.ams module

Read the temperatures of an AMS input file.

read_ams_temperatures() reads the initial-velocity and thermostat temperatures of an AMS input.

class pyretis.inout.engine_temperature.ams._AmsMolecularDynamics

Bases: object

The MolecularDynamics block of an AMS input, read line by line.

The block structure is the one of the AMS 2026.1 input: a line that holds only the name of a block that the open block holds opens it, and End closes it. A line that starts with the name of such a block and holds Key=value pairs is the block in compact notation. A line that holds only a Yes/No key sets the key to Yes. The lines of a non-standard block are rows of data.

Variables:

  • open_blocks (list of strings) – The names of the open blocks as the input writes them, the outermost (MolecularDynamics) first.

  • blocks (list of tuples) – One (name, keys) pair per InitialVelocities and Thermostat block, in the order of the input: name in lower case, and keys a dict from the key name in lower case to the list of its value words.

__init__()

Set up the state at the line that opens the block.

_path()

Return the open blocks as AMS names them, for the messages.

Returns:

out (string) – The names of the open blocks joined by %.

_read_key(where, words)

Read one key line of a sub-block the reader reads.

A key line is Key value. The one-word form Key=value is read as the same key.

Parameters:

  • where (string) – The file and line, for the error message.

  • words (list of strings) – The words of the line.

Raises:

ValueError – If the line holds an = in another form, names a key outside the keys of the sub-block, or sets a key twice.

_sub_block(where, words)

Open a sub-block, or read a sub-block in compact notation.

Parameters:

  • where (string) – The file and line, for the error message.

  • words (list of strings) – The words of the line: the name of the sub-block, and its Key=value pairs in compact notation.

Raises:

ValueError – If the sub-block is refused, or the line is neither the name alone nor the name and Key=value pairs.

read(where, words)

Apply one line of the block to the state.

Parameters:

  • where (string) – The file and line, for the error message.

  • words (list of strings) – The words of the line.

Returns:

out (boolean) – True if the line closes the MolecularDynamics block.

Raises:

ValueError – If the line names a block or key outside the MolecularDynamics block of the AMS 2026.1 input, names a refused block, or writes a key of a block the reader reads in a malformed way.

pyretis.inout.engine_temperature.ams._ams_compact_pairs(words)

Return the Key=value pairs of a block in AMS compact notation.

AMS ignores the spaces around the = of a pair, so Key=value, Key = value, Key= value and Key =value are the same pair. A value that holds spaces is quoted, and it is one word here.

Parameters:

words (list of strings) – The words of the line after the block name.

Returns:

out (list of tuples or None) – One (key, value) pair of strings per key, or None when the words are not a sequence of such pairs.

pyretis.inout.engine_temperature.ams._ams_lines(filename)

Return the lines of an AMS input that hold input.

Parameters:

filename (string) – The AMS input file.

Returns:

out (list of tuples) – One (where, text) pair per line, with comments and blank lines left out: where names the file and line, and text is the line without its comment.

Raises:

ValueError – If a line is a preprocessor directive (@include), which reads input from another file.

pyretis.inout.engine_temperature.ams._ams_md_start(lines, filename)

Return where the MolecularDynamics block of an AMS input opens.

The block opens at a line that holds only MolecularDynamics (ignoring case).

Parameters:

  • lines (list of tuples) – The lines of the input, from _ams_lines().

  • filename (string) – The AMS input file, for the error message.

Returns:

out (integer) – The index in lines of the line that opens the block.

Raises:

ValueError – If the input has no such block, has more than one, or writes the block on one line.

pyretis.inout.engine_temperature.ams._ams_set_key(keys, key, value, block, where)

Store one key of a sub-block the reader reads.

Parameters:

  • keys (dict) – The keys of the sub-block read so far.

  • key (string) – The key, as the input writes it.

  • value (list of strings) – The value words of the key.

  • block (string) – The name of the sub-block, as the input writes it.

  • where (string) – The file and line of the key, for the error message.

Raises:

ValueError – If the key is outside the keys of the sub-block, or the sub-block sets it twice.

pyretis.inout.engine_temperature.ams._ams_sub_blocks(filename)

Return the sub-blocks of an AMS input that the reader reads.

Parameters:

filename (string) – The AMS input file.

Returns:

out (list of tuples) – The InitialVelocities and Thermostat blocks of the MolecularDynamics block, see _AmsMolecularDynamics.blocks.

Raises:

ValueError – If the input has no MolecularDynamics block, or the block has no matching End or holds a line the reader refuses.

pyretis.inout.engine_temperature.ams._ams_temperature(words, source, key)

Convert the value words of an AMS temperature key to one number.

Parameters:

  • words (list of strings) – The value words: the number, with an optional unit tag at the end of the line (the place of a unit in AMS input) or before the number.

  • source (string) – The AMS input, for the error message.

  • key (string) – The key, for the error message.

Returns:

out (float) – The temperature in kelvin.

Raises:

ValueError – If the unit tag is not [K], the key holds several values (a schedule), or the value is not a positive number.

pyretis.inout.engine_temperature.ams._ams_text(line)

Return an AMS input line without its comment.

AMS starts a comment at #, ! or ::.

Parameters:

line (string) – A line of the AMS input.

Returns:

out (string) – The line up to the first comment mark, stripped.

pyretis.inout.engine_temperature.ams.read_ams_temperatures(filename)

Read the temperatures of an AMS input file.

MolecularDynamics%InitialVelocities%Temperature is the temperature of the velocities AMS draws, and it is required. Every MolecularDynamics%Thermostat block with a Type other than None (the AMS default) adds its Temperature, which must be one value: several values are an annealing schedule.

The MolecularDynamics block is read with the blocks and keys of the AMS 2026.1 input. A line that is not a block or key of that input is refused, since its effect on the temperature is unknown, and so are the blocks that set or change the temperature of the atoms in another way: AddMolecules, fbMC, HeatExchange and ReplicaExchange. An input that includes another file (@include) is refused.

Parameters:

filename (string) – The AMS input file.

Returns:

out (object like EngineTemperatures) – 'MolecularDynamics%InitialVelocities%Temperature', and 'MolecularDynamics%Thermostat[<n>]%Temperature' for the n-th Thermostat block (counted from 1) that has a thermostat, in kelvin.

Raises:

ValueError – If the input has no initial-velocity temperature, a thermostat has no temperature or a schedule, a temperature is not a positive number, or the input holds a line the reader refuses.

pyretis.inout.engine_temperature.lammps_commands module

Read the commands of a LAMMPS script as LAMMPS reads them.

lammps_script_commands() returns the commands of a LAMMPS script, each with the number of the line it starts on. The helpers here decode a line, find its comment, substitute the variables of a command and name the style of a command. refuse_lammps_command_variables() refuses a LAMMPS command that defines variables of the script.

pyretis.inout.engine_temperature.lammps_commands._decode_lammps_line(raw, filename, number)

Return a line of a LAMMPS script as text.

LAMMPS reads the bytes of a script and echoes its lines, comments included, into its log file. PyRETIS copies lammps.in into the input of each run and reads the log of the run as UTF-8 text, so a line of a LAMMPS script must be UTF-8 text (ASCII is UTF-8 too).

Parameters:

  • raw (bytes) – The line, without its line break.

  • filename (string) – The LAMMPS script, for the error message.

  • number (integer) – The number of the line in the script, for the error message.

Returns:

out (string) – The line.

Raises:

ValueError – If the line holds bytes that are not UTF-8.

pyretis.inout.engine_temperature.lammps_commands._lammps_command_text(command, where)

Return a LAMMPS command without its comment, refusing non-ASCII.

LAMMPS runs a command after it drops the comment: a comment may hold any character. Before it runs the rest, LAMMPS replaces a few UTF-8 characters with ASCII ones (spaces, quotes, plus and minus signs) and changes the bytes of the others; PyRETIS reads the commands of a LAMMPS script as ASCII text, and refuses a command with a character that is not ASCII.

Parameters:

  • command (string) – The command, as the script writes it.

  • where (string) – The file and line of the command, for the error message.

Returns:

out (string) – The command without its comment.

Raises:

ValueError – If the command, without its comment, holds a character that is not ASCII.

pyretis.inout.engine_temperature.lammps_commands._lammps_comment_start(command)

Return where the comment of a LAMMPS command starts.

As LAMMPS reads a command, the comment starts at the first # that is not between single, double or triple quotes. After a quote that is not closed, no # starts a comment; LAMMPS stops at such a command.

Parameters:

command (string) – The command.

Returns:

out (integer or None) – The position of the # that starts the comment, or None when the command has no comment.

pyretis.inout.engine_temperature.lammps_commands._lammps_style(style)

Return a LAMMPS style name without its accelerator suffix.

Parameters:

style (string) – The style, for instance 'nvt/omp'.

Returns:

out (string) – The style, for instance 'nvt'.

pyretis.inout.engine_temperature.lammps_commands._lammps_substitute(text, variables, where)

Substitute the variables of a LAMMPS command outside quotes.

${name} and $x (a one-character name) are replaced by the value of the variable when the value is known from the script (_lammps_variable_value()), and $(expression) by the value of the expression when it is a plain number, written as LAMMPS writes it (%.20g). A reference with an unknown value stays as it is written, so a temperature that holds one is reported as not a number. The text from an unquoted # onwards is a comment and is dropped.

Parameters:

  • text (string) – The command.

  • variables (dict) – The variables defined so far, from their name to a (style, value) pair, where value is the text of the value or None when the script does not give it.

  • where (string) – The file and line of the command, for the error message.

Returns:

out (string) – The command after substitution, without its comment.

Raises:

ValueError – If a quote is not closed.

pyretis.inout.engine_temperature.lammps_commands._lammps_variable_value(variable)

Return the text a LAMMPS variable is substituted with.

Parameters:

variable (tuple or None) – The (style, value) pair of the variable, or None for a variable the script does not define.

Returns:

out (string or None) – The value, or None when the script does not give it. An equal variable has a value only when its formula is a plain number, which LAMMPS writes as %.15g.

pyretis.inout.engine_temperature.lammps_commands.lammps_script_commands(filename)

Return the commands of a LAMMPS script and the lines they start on.

The lines are read as LAMMPS reads them (Input::file of LAMMPS): a line ends at a line feed, and the white space at its end is dropped (_LAMMPS_LINE_SPACE); a line whose last character is & continues on the next line, without the & and the line break, and a command whose lines so far hold an odd number of triple quotes continues on the next line, after a line break. The comment of each command is dropped (_lammps_command_text()). The readers of the temperature and of the restart files of a script, the scan for read_restart and the reader of the settings of the LAMMPS engines (pyretis.engines.lammps_steps.read_lammps_input()) all read the commands here, so that no line inside a command, such as a line of a triple-quoted text, is read as a command of its own.

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (list of tuples) – One (line number, command) pair per command, with the number of the line the command starts on and the command without its comment.

Raises:

ValueError – If a line holds bytes that are not UTF-8 (_decode_lammps_line()), or a command, without its comment, a character that is not ASCII (_lammps_command_text()).

pyretis.inout.engine_temperature.lammps_commands.refuse_lammps_command_variables(lmp)

Refuse a LAMMPS command that defines variables of the script.

LAMMPS defines the variables of its command-line option -var (or -v) before it reads the script, as index variables, which the variable commands of the script do not replace. The readers of PyRETIS read the variables of the script only, and would take another time step, temperature or file than the ones LAMMPS runs with.

Parameters:

lmp (string or None) – The command that runs LAMMPS, as [engine] lmp gives it.

Raises:

ValueError – If a word of the command is -var or -v.

pyretis.inout.engine_temperature.lammps_restart module

Read the header of a LAMMPS restart file.

read_lammps_restart_header() reads the unit system and the time step of a LAMMPS restart file (LammpsRestartHeader), and is_lammps_restart_file() tells whether a file starts as a LAMMPS restart file starts.

class pyretis.inout.engine_temperature.lammps_restart.LammpsRestartHeader(source: str, units: str, timestep: float)

Bases: object

The unit system and the time step of a LAMMPS restart file.

Variables:

  • source (string) – The restart file.

  • units (string) – The unit system, the value of the UNITS flag of the header.

  • timestep (float) – The size of the time step, the value of the TIMESTEP flag of the header (NTIMESTEP is the number of the time step).

source: str
timestep: float
units: str
class pyretis.inout.engine_temperature.lammps_restart._LammpsRestartBytes(infile, filename)

Bases: object

The bytes of a LAMMPS restart file, read from its start.

Variables:

  • infile (file object) – The restart file, opened for reading in binary mode.

  • filename (string) – The restart file, for the error message.

  • size (integer) – The size of the file in bytes.

__init__(infile, filename)

Set up the reading of an open restart file.

Parameters:

  • infile (file object) – See the class attribute.

  • filename (string) – See the class attribute.

magic_at_end()

Return the last bytes of the file, as long as the magic string.

Returns:

out (bytes) – The bytes. The file position is restored.

number(kind, what)

Return the next int, bigint or double of the file.

Parameters:

  • kind (string) – 'int', 'bigint' or 'double'.

  • what (string) – What the number is, for the error message.

Returns:

out (integer or float) – The number.

read(count, what)

Return the next count bytes of the file.

Parameters:

  • count (integer) – The number of bytes.

  • what (string) – What the bytes hold, for the error message.

Returns:

out (bytes) – The bytes.

Raises:

ValueError – If the file ends before them.

string(what)

Return the next string of the file.

LAMMPS writes a string as the int number of its bytes, its NUL included, followed by the bytes.

Parameters:

what (string) – What the string is, for the error message.

Returns:

out (bytes) – The string, without its NUL.

Raises:

ValueError – If the length is not positive, or the bytes are not a string that ends with its only NUL.

pyretis.inout.engine_temperature.lammps_restart._lammps_restart_start(restart)

Read the start of a LAMMPS restart file and check it.

Parameters:

restart (object like _LammpsRestartBytes) – The file, at its start.

Raises:

ValueError – If the file does not start with the magic string, is written in another byte order or one that LAMMPS does not know, has another format revision than _LAMMPS_RESTART_REVISION, or does not end with the magic string.

pyretis.inout.engine_temperature.lammps_restart._lammps_restart_value(restart, name)

Read the value of a flag of the header of a LAMMPS restart file.

Parameters:

  • restart (object like _LammpsRestartBytes) – The file, after the flag.

  • name (string) – The flag, a key of _LAMMPS_RESTART_HEADER.

Returns:

out (bytes, integer, float or None) – The value of a string flag (bytes), of an int or bigint flag (integer) or of a double flag (float); None for a vector or the atom style.

Raises:

ValueError – If the file ends in the value, a string is not one that LAMMPS writes, or a vector has another count than the one that LAMMPS reads.

pyretis.inout.engine_temperature.lammps_restart.is_lammps_restart_file(filename)

Tell whether a file starts as a LAMMPS restart file starts.

Parameters:

filename (string) – The file.

Returns:

out (boolean) – True if filename is a file that starts with the magic string of a LAMMPS restart file, as read_restart reads it; False if it is not a file or starts otherwise.

pyretis.inout.engine_temperature.lammps_restart.read_lammps_restart_header(filename)

Read the unit system and the time step of a LAMMPS restart file.

The file is read as LAMMPS 22 Jul 2025 reads it with read_restart: the magic string, the byte order, the format revision, the magic string at the end of the file, and the flags of the header with their values, up to the negative flag that ends the header. LAMMPS takes the unit system of the run from the UNITS flag, and replaces the one of the units command of the script with it; it then takes the time step from the TIMESTEP flag, which the file holds after UNITS, and replaces the one of a timestep command before read_restart with it.

Parameters:

filename (string) – The restart file.

Returns:

out (object like LammpsRestartHeader) – The unit system and the time step of the file.

Raises:

ValueError – If the file does not exist, is not a file or cannot be read, if it is too short, does not start or end with the magic string, is written in another byte order or format revision, if its header holds a flag that is not a flag of the header or a value that is not one LAMMPS writes, if the header has no UNITS flag or names a unit system that LAMMPS does not know, or if it has no TIMESTEP flag or one that is not a positive finite number.

pyretis.inout.engine_temperature.lammps_script module

Read the temperatures, restart files and time step of a LAMMPS script.

read_lammps_temperatures() reads SET_TEMP, the thermostat fixes and the velocity commands of a LAMMPS script, and lammps_refused_fix() tells whether the reader refuses a fix style. read_lammps_restarts() reads the unit system, the restart files and the time step of a script (LammpsRestarts), and refuse_lammps_restart_file() refuses a restart file that LAMMPS opens and the script contradicts.

pyretis.inout.engine_temperature.lammps_script.LAMMPS_BROWNIAN_FIXES = ('brownian', 'brownian/sphere', 'brownian/asphere', 'brownian/poly')

The fix styles of LAMMPS (22 Jul 2025) that integrate Brownian dynamics, without inertia: the velocity they store for an atom is its displacement of the time step over the time step. The reader refuses them in every task with the advice of Brownian dynamics.

pyretis.inout.engine_temperature.lammps_script.LAMMPS_SET_TEMP_KEY = 'variable SET_TEMP'

The key of the temperature of the variable SET_TEMP in the temperatures read_lammps_temperatures() reads.

class pyretis.inout.engine_temperature.lammps_script.LammpsRestartFile(where: str, name: str, timesteps: tuple = ())

Bases: object

A read_restart command of a LAMMPS script.

Variables:

  • where (string) – The file and line of the command.

  • name (string) – The name of the restart file, as LAMMPS opens it.

  • timesteps (tuple of tuples) – One (where, value) pair per timestep command before the command (after the start of the script or its last clear command): the file and line of the timestep command and its time step, which must equal the one of the restart file.

name: str
timesteps: tuple = ()
where: str
class pyretis.inout.engine_temperature.lammps_script.LammpsRestarts(source: str, units: str | None, files: tuple = (), timestep: float | None = None, timestep_source: str | None = None, timestep_after: bool = False)

Bases: object

The unit system, the restart files and the time step of a script.

Variables:

  • source (string) – The LAMMPS script.

  • units (string or None) – The argument of the last units command of the script (after its last clear command), or None for a script without one.

  • files (tuple of objects like LammpsRestartFile) – One per read_restart command after the last clear command.

  • timestep (float or None) – The time step LAMMPS runs with after the last read_restart: the one of the last timestep command after it, else the one of its restart file. None for a script that reads no restart file.

  • timestep_source (string or None) – Where timestep is read: the timestep command (its file and line) or the restart file; None with timestep.

  • timestep_after (boolean) – True if a timestep command after the last read_restart sets timestep, False if the restart file does.

files: tuple = ()
source: str
timestep: float | None = None
timestep_after: bool = False
timestep_source: str | None = None
units: str | None
class pyretis.inout.engine_temperature.lammps_script._LammpsRestart(where: str, words: tuple, variable: bool, timesteps: tuple = ())

Bases: object

A read_restart command of a LAMMPS script.

Variables:

  • where (string) – The file and line of the command.

  • words (tuple of strings) – The words of the command, after substitution: read_restart, the file and the optional remap or noremap.

  • variable (boolean) – True if the command, as the script writes it, refers to a LAMMPS variable (_lammps_has_reference()).

  • timesteps (tuple of objects like _LammpsTimestep) – The timestep commands before the command, after the start of the script or its last clear command. LAMMPS replaces their time step with the one of the restart file.

timesteps: tuple = ()
variable: bool
where: str
words: tuple
class pyretis.inout.engine_temperature.lammps_script._LammpsScript(directory)

Bases: object

The state of a LAMMPS script read from top to bottom.

Variables:

  • directory (string) – The directory include paths are resolved in: the directory of the script given to read_lammps_temperatures(), where the engine runs LAMMPS with the files of input_path.

  • units (string or None) – The argument of the last units command after the start of the script or its last clear command.

  • variables (dict) – The variables, see _lammps_substitute().

  • fixes (dict) – The fixes that are defined, from the fix ID to the pair (key, temperature), with temperature None for a fix that is not a thermostat.

  • pair_temperatures (dict of float) – The temperatures of the thermostat pair styles (see _LAMMPS_THERMOSTAT_PAIR_STYLES) of the last pair_style command, keyed 'pair_style <style>'.

  • restarts (list of objects like _LammpsRestart) – The read_restart commands after the start of the script or its last clear command.

  • units_after_restart (string or None) – The file and line of the first units command after a read_restart command (after the start of the script or its last clear command), or None without one. LAMMPS stops at it: the restart file defines the simulation box.

  • pair_style_after_restart (boolean) – True if a pair_style command follows the last read_restart command. LAMMPS replaces a pair style set before read_restart with the one of the restart file.

  • timesteps (list of objects like _LammpsTimestep) – The timestep commands after the start of the script or its last clear command.

  • timestep_after_restart (object like _LammpsTimestep) – The last timestep command after the last read_restart command, or None without one. It sets the time step of the run; without it, the run has the time step of the restart file.

  • units_after_timestep (tuple of strings or None) – The file and line of the first units command after a timestep command, and of that timestep command (after the start of the script or its last clear command), or None without one. LAMMPS sets the time step to the default of the unit system at a units command.

  • velocities (dict of float) – The temperatures of the velocity create and velocity scale commands, keyed by the command.

  • including (list of strings) – The files being read, the outermost first.

__init__(directory)

Set up an empty script state.

Parameters:

directory (string) – See the class attribute.

_clear()

Apply a clear command to the state.

LAMMPS deletes the atoms and the fixes and restores the default settings, the unit system and the time step included. The variables stay defined.

_command(words, where, command)

Apply one command to the state.

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • command (string) – The command as the script writes it, before substitution.

_include(path, where)

Read a file named by an include command.

Parameters:

  • path (string) – The file, as the command names it.

  • where (string) – The file and line of the command, for the error message.

static _pair_style(words, where)

Read the temperatures of a pair_style command.

The words after the style are checked too, because a hybrid or hybrid/overlay style lists its sub-styles there. A thermostat pair style (see _LAMMPS_THERMOSTAT_PAIR_STYLES) gives Tstart and Tstop as the two words after its name.

Parameters:

  • words (list of strings) – The words of the command: pair_style, the style and its arguments.

  • where (string) – The file and line of the command, for the error message.

Returns:

out (dict of float) – The temperatures of the thermostat pair styles of the command, keyed 'pair_style <style>'; empty without one.

Raises:

ValueError – If one of the words is a pair style of _LAMMPS_REFUSED_PAIR_STYLES or another pair style of dissipative particle dynamics, or a thermostat pair style misses its temperature, gives it in a form that is not a positive number, or ramps it.

static _refuse_command(words, where)

Refuse a control-flow command.

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

Raises:

ValueError – If the command changes which commands LAMMPS runs (see _LAMMPS_CONTROL).

_units_or_timestep(words, where)

Apply a units or a timestep command.

LAMMPS sets the time step to the default of the unit system at a units command, replaces it with the one of the restart file at read_restart, and sets it at a timestep command.

Parameters:

  • words (list of strings) – The words of the command: units or timestep and its argument.

  • where (string) – The file and line of the command, for the error message.

_variable(words)

Apply a variable command to the state.

Parameters:

words (list of strings) – The words of the command: variable, the name, the style and its arguments.

_velocity(words, where)

Apply a velocity create or velocity scale command.

Parameters:

  • words (list of strings) – The words of the command: velocity, the group, create or scale, the temperature and the other arguments.

  • where (string) – The file and line of the command, for the error message.

read(filename)

Read the commands of a LAMMPS script into the state.

Parameters:

filename (string) – The script.

Raises:

ValueError – If the script uses a command this reader refuses, includes a file that is missing or already being read, or sets a temperature that cannot be read.

class pyretis.inout.engine_temperature.lammps_script._LammpsTimestep(where: str, word: str, value: float | None)

Bases: object

A timestep command of a LAMMPS script.

Variables:

  • where (string) – The file and line of the command.

  • word (string) – The argument of the command, after substitution.

  • value (float or None) – The time step, or None when the argument is not a number (_lammps_timestep_value()).

value: float | None
where: str
word: str
pyretis.inout.engine_temperature.lammps_script._lammps_fix_temperature(words, source, key)

Return the thermostat temperature of a LAMMPS fix command.

Parameters:

  • words (list of strings) – The words of the command: fix, the fix ID, the group, the style and its arguments.

  • source (string) – The LAMMPS script, for the error message.

  • key (string) – The name of the fix, for the error message.

Returns:

out (float or None) – The temperature of a thermostat fix (its Tstart), or None for a fix that leaves the temperature to the thermostat fixes.

Raises:

ValueError – If the fix style is refused or in none of the fix tables, or the fix misses its temperature, gives it in a form that is not a positive number, or ramps it (Tstart and Tstop are two temperatures, same_temperature()).

pyretis.inout.engine_temperature.lammps_script._lammps_has_reference(text, where)

Tell whether a LAMMPS command refers to a LAMMPS variable.

LAMMPS substitutes a $ outside quotes and before an unquoted #, which starts a comment (_lammps_substitute()).

Parameters:

  • text (string) – The command, as the script writes it.

  • where (string) – The file and line of the command, for the error message.

Returns:

out (boolean) – True if the command holds a $ that LAMMPS substitutes.

Raises:

ValueError – If a quote is not closed.

pyretis.inout.engine_temperature.lammps_script._lammps_keyword_start(arguments, keyword, required, source, key)

Return where the temperatures after a fix keyword start.

Parameters:

  • arguments (list of strings) – The arguments of the fix, after its style.

  • keyword (string) – The keyword that the temperatures follow.

  • required (boolean) – True if the fix is refused without the keyword.

  • source (string) – The LAMMPS script, for the error message.

  • key (string) – The name of the fix, for the error message.

Returns:

out (integer or None) – The index in arguments of the first temperature, or None when the keyword is absent and not required.

Raises:

ValueError – If the keyword is required and absent, or given more than once: LAMMPS accepts a repeated keyword and runs with one of its values.

pyretis.inout.engine_temperature.lammps_script._lammps_refused_fix_advice(style)

Return the advice of the refusal of a LAMMPS fix style.

A fix of Brownian dynamics (LAMMPS_BROWNIAN_FIXES) gives the advice of Brownian dynamics in every task (pyretis.engines.engine.BROWNIAN_DYNAMICS_TASK_ADVICE): the reader refuses the fix in every task.

Parameters:

style (string) – A refused LAMMPS fix style, without its accelerator suffix.

Returns:

out (string) – The advice after a space, or an empty string for a style without advice.

pyretis.inout.engine_temperature.lammps_script._lammps_restart_path(script, restart)

Return the restart file that a read_restart command reads.

LAMMPS opens the file of a relative name in the directory it runs in, where the LAMMPS engines copy the files of extra_files from the input directory, the directory of the script. The reader looks for the file there, in script.directory, as it looks for the files that include names.

Parameters:
Returns:

out (string) – The path of the restart file.

Raises:

ValueError – If the command names no file, names it with a LAMMPS variable, with a * or a % (_LAMMPS_RESTART_PATTERNS), or names a file that is not there.

pyretis.inout.engine_temperature.lammps_script._lammps_temperature(word, source, key)

Convert a temperature argument of a LAMMPS command to a float.

Parameters:

  • word (string) – The argument, after substitution.

  • source (string) – The LAMMPS script, for the error message.

  • key (string) – The command that holds the temperature, for the error message.

Returns:

out (float) – The temperature.

Raises:

ValueError – If the argument is a v_ reference (LAMMPS evaluates it during the run) or not a positive number.

pyretis.inout.engine_temperature.lammps_script._lammps_thermostat_temperature(values, count, source, key)

Return the temperature of the arguments of a LAMMPS thermostat.

Parameters:

  • values (list of strings) – The temperature arguments: T, or Tstart and Tstop. The list is shorter than count when the command ends before them.

  • count (integer) – The number of temperature arguments, 1 or 2.

  • source (string) – The LAMMPS script, for the error message.

  • key (string) – The fix or pair style, for the error message.

Returns:

out (float) – The temperature.

Raises:

ValueError – If an argument is missing or is not a positive number, or if Tstart and Tstop are two temperatures (same_temperature()).

pyretis.inout.engine_temperature.lammps_script._lammps_timestep_value(word)

Return the time step of the argument of a timestep command.

Parameters:

word (string) – The argument, after substitution.

Returns:

out (float or None) – The time step, or None when the argument is not a decimal number (a v_ reference, a formula, a variable whose value the script does not give).

pyretis.inout.engine_temperature.lammps_script._lammps_units_after_timestep(units_where, step_where)

Return the refusal of a units command after a timestep.

Parameters:

  • units_where (string) – The file and line of the units command.

  • step_where (string) – The file and line of the timestep command before it.

Returns:

out (string) – The message.

pyretis.inout.engine_temperature.lammps_script._read_lammps_script(filename)

Read a LAMMPS script and refuse its restart and time step settings.

The refusals come one at a time: the unit system of a script that reads a restart file (_refuse_lammps_restart_units()), the time step (_refuse_lammps_timesteps()), the pair style of a script that reads a restart file (_refuse_lammps_restart_pair_style()).

Parameters:

filename (string) – The LAMMPS script.

Returns:

  • out[0] (object like _LammpsScript) – The script, read to its end.

  • out[1] (list of objects like LammpsRestartHeader) – The header of the restart file of each read_restart command of the script (after its last clear command).

Raises:

ValueError – As _LammpsScript.read(), _refuse_lammps_restart_units(), _refuse_lammps_timesteps() and _refuse_lammps_restart_pair_style() raise it.

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_restart_header(header, where, units, source, timesteps=())

Refuse a restart file whose units or time step a script contradicts.

LAMMPS runs in the unit system of the restart file, and replaces the one of the units command with it without a warning; it replaces the time step of a timestep command before read_restart with the one of the restart file, also without a warning. The units are checked first, then the time steps; two time steps are one within a relative _LAMMPS_TIMESTEP_RTOL.

Parameters:

  • header (object like LammpsRestartHeader) – The header of the restart file that read_restart reads.

  • where (string) – The file and line of the read_restart command.

  • units (string) – The unit system of the units command of the script.

  • source (string) – The LAMMPS script, for the error message.

  • timesteps (tuple of tuples, optional) – One (where, value) pair per timestep command before read_restart: the file and line of the command and its time step.

Raises:

ValueError – If the unit system of the restart file differs from units, or the time step of one of timesteps differs from the one of the restart file. The message names both values and the file.

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_restart_pair_style(script, filename)

Refuse a read_restart script without its pair style.

The binary restart file sets the pair style of the run, which PyRETIS does not read. The script must set the pair style with a pair_style command after read_restart, which replaces it.

Parameters:

  • script (object like _LammpsScript) – The script, read to its end.

  • filename (string) – The LAMMPS script, for the error message.

Raises:

ValueError – If the script reads a restart file and has no pair_style command after its last read_restart.

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_restart_units(script, filename)

Refuse a read_restart script without its unit system.

The binary restart file sets the unit system of the run. The script must state it with a units command before read_restart, the one of the restart file, which PyRETIS reads (read_lammps_restart_header()); LAMMPS stops at a units command after read_restart.

Parameters:

  • script (object like _LammpsScript) – The script, read to its end.

  • filename (string) – The LAMMPS script, for the error message.

Returns:

out (list of objects like LammpsRestartHeader) – The header of the restart file of each read_restart command of script.restarts, in their order; empty for a script that reads no restart file.

Raises:

ValueError – If the script reads a restart file and has no units command, has a units command after read_restart, names the restart file in a way _lammps_restart_path() refuses, reads a restart file that read_lammps_restart_header() refuses, or one whose unit system differs from the one of the units command (_refuse_lammps_restart_header()).

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_restart_without_temperature(script, values, filename)

Refuse a read_restart script that states no temperature.

PyRETIS does not read the temperature from the restart file, so the script itself must state it: with SET_TEMP, a thermostat fix, or a thermostat pair style (_LAMMPS_THERMOSTAT_PAIR_STYLES) after read_restart. A pair style before read_restart is replaced by the one of the restart file, and a velocity command does not count.

Parameters:

  • script (object like _LammpsScript) – The script, read to its end; script.pair_temperatures holds the temperatures of the thermostat pair styles of the last pair_style command, which follows the last read_restart (_refuse_lammps_restart_pair_style()).

  • values (dict of float) – The temperatures of SET_TEMP and of the thermostat fixes.

  • filename (string) – The LAMMPS script, for the error message.

Raises:

ValueError – If the script reads a restart file, values is empty and the script sets no thermostat pair style after read_restart.

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_timestep_word(timestep, what)

Refuse a timestep command whose time step is not a number.

Parameters:

  • timestep (object like _LammpsTimestep) – The command.

  • what (string) – Why PyRETIS reads the time step, for the error message.

Raises:

ValueError – If the argument of the command is not a number.

pyretis.inout.engine_temperature.lammps_script._refuse_lammps_timesteps(script, headers, filename)

Refuse a script whose time step PyRETIS would read wrongly.

LAMMPS sets the time step to the default of the unit system at a units command, so a units command after a timestep command is refused, in every script. In a script that reads a restart file, LAMMPS replaces the time step of a timestep command before read_restart with the one of the restart file, and a timestep command after the last read_restart sets the time step of the run; each of these must be a number, and one before read_restart must equal the time step of the restart file (_refuse_lammps_restart_header()).

Parameters:
Raises:

ValueError – If the script has a units command after a timestep command, or reads a restart file and has a timestep command before read_restart that is not a number or differs from the time step of the restart file, or a timestep command after the last read_restart that is not a number.

pyretis.inout.engine_temperature.lammps_script._same_lammps_timestep(value, reference)

Tell whether two LAMMPS time steps are one time step.

Two time steps are one within the relative tolerance _LAMMPS_TIMESTEP_RTOL, the tolerance within which two times per step of a run are one (pyretis.core.engine_time.TIME_PER_STEP_RTOL).

Parameters:

  • value (float) – The time step to compare.

  • reference (float) – The time step it is compared with.

Returns:

out (boolean) – True if value differs from reference by at most the tolerance times reference.

pyretis.inout.engine_temperature.lammps_script.lammps_refused_fix(style)

Return whether the temperature reader refuses a LAMMPS fix style.

A script with a fix of such a style is refused in every task (read_lammps_temperatures()): the fix sets or changes the temperature of the atoms in a way PyRETIS reads no temperature from.

Parameters:

style (string) – A LAMMPS fix style, with or without its accelerator suffix.

Returns:

out (boolean) – True for a refused style.

pyretis.inout.engine_temperature.lammps_script.read_lammps_restarts(filename)

Read the unit system, the restart files and the time step of a script.

The script is read as read_lammps_temperatures() reads it, with the same refusals of its restart and time step settings. The time step of a script that reads a restart file is the one LAMMPS runs with: the one of the last timestep command after the last read_restart, else the one of its restart file (read_lammps_restart_header()). The LAMMPS engines check, before each LAMMPS run, the restart files where LAMMPS opens them, in the directory it runs in.

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (object like LammpsRestarts) – The units command, the read_restart files and the time step.

Raises:

ValueError – As read_lammps_temperatures() raises it for the script and its restart and time step settings.

pyretis.inout.engine_temperature.lammps_script.read_lammps_temperatures(filename)

Read the temperatures of a LAMMPS script.

The script is read from top to bottom, with its include files, as LAMMPS reads it; a variable is substituted with the value it has where it is used. The temperatures are:

  • the variable SET_TEMP, which the velocity_generation = "engine" draw of the relaunch LAMMPS engine uses, and which a script for that draw must define;

  • the Tstart (equal to Tstop) of every thermostat fix that is defined at the end of the script (nvt, npt and their variants, bocs, langevin, langevin/eff, temp/berendsen, temp/csvr, temp/csld, temp/rescale, temp/rescale/eff, and the thermostats of the rigid-body fixes, gld), and the temp of every qtb fix;

  • the Tstart (equal to Tstop) of every dpd/tstat and dpd/ext/tstat pair style of the last pair_style command, also as a sub-style of a hybrid pair style;

  • the temperature of every velocity create and velocity scale command.

A script with read_restart takes its unit system, its time step and its pair style from the binary restart file. LAMMPS runs in the unit system of the restart file, and replaces the one of the units command with it without a warning; it replaces the time step of a timestep command before read_restart with the one of the restart file, also without a warning. PyRETIS reads the unit system and the time step of the restart file (read_lammps_restart_header()), which it looks for in the directory of the script, as the LAMMPS engines copy it from there when it is in their extra_files; it does not read the pair style of the restart file. The script is accepted when it states the unit system of the restart file with a units command before read_restart, has no timestep command before read_restart other than one of the time step of the restart file (within a relative 1e-9), sets the pair style with a pair_style command after read_restart, and states the temperature with SET_TEMP, a thermostat fix, or a thermostat pair style (dpd/tstat, dpd/ext/tstat) after read_restart; it is refused otherwise, for its units first, then for its time step, then for its pair style, then for its temperature. A restart file named with a LAMMPS variable, a * or a % is refused. The time step of the run is the one of the last timestep command after the last read_restart, else the one of the restart file (read_lammps_restarts()).

LAMMPS sets the time step to the default of the unit system at a units command, so a script with a units command after a timestep command is refused, with or without read_restart.

Every other fix style is looked up in the fix styles of the LAMMPS documentation and of LAMMPS 22 Jul 2025: a style that leaves the temperature to the thermostat fixes (an integrator, a constraint, a force, an output) is passed, and a style that sets or changes the temperature in another way (another thermostat, Monte Carlo moves at a temperature, a heat source, a friction force) is refused, as is a style outside these fix styles. A pair_style that sets or changes the temperature through the pair forces (dissipative particle dynamics but dpd/tstat and dpd/ext/tstat, brownian, dsmc, the lubrication, granular and mesocnt/viscous friction styles) is refused.

The reader sees the variables the files define. On the LAMMPS command line (-var) the PyRETIS LAMMPS engines add only pyretis_seed.

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (object like EngineTemperatures) – The temperatures, keyed 'variable SET_TEMP', 'fix <ID> <style>', 'pair_style <style>' and 'velocity <group> <create|scale>'. unit is 'lj' for units lj (the LAMMPS default) and 'K' for the other unit systems, and engine_units is the unit system.

Raises:

ValueError – If the script sets no temperature, sets one that is not a plain number (an equal formula, a v_ reference), ramps one, uses a refused or unknown fix style or a refused pair style, uses a command that changes which commands LAMMPS runs (if, jump, label, next, partition, python, run ... every), has a line that is not UTF-8 text or a command with a character that is not ASCII outside its comment (lammps_script_commands()), has a units command after a timestep command, reads a restart file without a units command before read_restart, with a units command after it, in another unit system than the one of the units command, with a timestep command before read_restart of another time step than the one of the restart file or a timestep command before or after read_restart that is not a number, without a pair_style command after read_restart or without stating SET_TEMP, a thermostat fix or a thermostat pair style after read_restart, names the restart file in a way that PyRETIS does not resolve, reads a restart file that read_lammps_restart_header() refuses, or names an unknown unit system.

pyretis.inout.engine_temperature.lammps_script.refuse_lammps_restart_file(header, restart, restarts)

Refuse a restart file that LAMMPS opens and the script contradicts.

LAMMPS opens the restart file of a read_restart command where it runs, which can be another file than the one that read_lammps_restarts() read in the input directory. The file that LAMMPS opens must hold the unit system of the units command and the time step of each timestep command before read_restart (_refuse_lammps_restart_header()); the file of the last read_restart, when no timestep command follows it, sets the time step of the run, and must hold the time step of LammpsRestarts.timestep, the time step of the engine.

Parameters:
Raises:

ValueError – If the unit system or the time step of the file contradicts the script, or the file sets the time step of the run and holds another one than the time step of the engine.

pyretis.inout.engine_temperature.lammps_scan module

Scan a LAMMPS script and the files it includes.

The scan follows the include and jump commands of a script. read_lammps_timestep() and read_lammps_units() read the time step and the unit system LAMMPS runs a script with, lammps_script_reads_restart() tells where a script can read a restart file, and lammps_script_files() returns the files that the include and jump commands of a script name.

pyretis.inout.engine_temperature.lammps_scan._lammps_fix_resets_timestep(words)

Tell whether a LAMMPS command defines a fix that changes the time step.

Parameters:

words (list of strings) – The words of the command, after substitution.

Returns:

out (boolean) – True for a fix command of a style of _LAMMPS_TIMESTEP_FIXES, with or without an accelerator suffix (_lammps_style()).

pyretis.inout.engine_temperature.lammps_scan._lammps_if_commands(words)

Return the commands of every branch of a LAMMPS if command.

As LAMMPS 22 Jul 2025 runs them (Input::ifthenelse), each command is an argument after then, after elif and its condition, or after else. Every branch is returned, since the scan does not evaluate the conditions.

Parameters:

words (list of strings) – The words of the if command: if, the condition, then and the commands of the branches.

Returns:

out (list of strings) – The commands of all branches, in their order.

pyretis.inout.engine_temperature.lammps_scan._lammps_mdi_plugin_commands(words)

Return the command of a LAMMPS mdi plugin command.

As LAMMPS 22 Jul 2025 reads it (MDIPlugin), mdi plugin and the name of the plugin are followed by keyword-value pairs (mdi, infile, extra, command); the value of command is a command, which LAMMPS runs.

Parameters:

words (list of strings) – The words of the mdi command.

Returns:

out (list of strings) – The command, or an empty list for another mdi command.

pyretis.inout.engine_temperature.lammps_scan._lammps_run_every_commands(words)

Return the commands of a LAMMPS run command with every.

As LAMMPS 22 Jul 2025 reads them (Run::command), the keywords upto (no value), start, stop, pre and post (one value each) may come before every; each argument after every and its number is a command, unless the one argument is NULL.

Parameters:

words (list of strings) – The words of the run command.

Returns:

out (list of strings) – The commands, empty for a run without every or with NULL.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan(filename, state)

Scan the commands of a script, or of a file it includes.

The commands are read as LAMMPS reads them (lammps_script_commands()), from top to bottom, without their comments, and substituted with the variables of the scan (_lammps_scan_words()). A file that is already being scanned (a file that includes itself) is not scanned again: its commands are scanned once.

Parameters:

  • filename (string) – The script, or a file it includes.

  • state (dict) – The state of the scan: directory, the directory the files of include and jump are looked for in, as _LammpsScript looks for them; variables, the variables (_lammps_scan_variable()); scanning, the files being scanned, the outermost first; restart, the file and line of the first read_restart command, or None; timestep, the file and line of the last timestep command after the last clear command, or None; units, the unit system of the last units command after the last clear command, or None, and units_where, its file and line; dt, the time step of the last timestep command after the last units or clear command, or None, and dt_where, its file and line (_lammps_scan_timestep()); clear, the file and line of the last clear command, or None; jump, the file and line of the first jump command, or None; files, the file as the command names it, the file and line and the name of each include and jump command whose file the scan reads (_lammps_scan_follow()); written, the file, the file and line and the words of each command that writes a file (_lammps_scan_writes()); units_after_timestep, the file and line of each units command after a timestep command and of the last timestep command before it; named, the file and line and the text of each command named with a variable (_lammps_scan_named()), in the order the scan reads them; marks, for each file scanned, from each of its labels (None for its start) to the number of named commands read before its first label command, where a jump to the label goes (_lammps_scan_jump()). Changed in place.

Raises:

ValueError – As lammps_script_commands() and _lammps_scan_command() raise it.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_command(words, where, state, runner=None)

Apply one command to a scan for read_restart.

Only the name of the command, its first word, tells what it is; the word read_restart elsewhere (in a print text, in a value) is no command. A command that runs other commands from its arguments has them scanned the same way, as commands that LAMMPS may run (_lammps_scan_runs()).

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()); changed in place: restart, timestep, units, units_where, dt, dt_where, clear, jump, units_after_timestep, variables, files and marks.

  • runner (string, optional) – The command that runs this one from its arguments, as the error messages name it; None for a command of the script.

Raises:

ValueError – As _refuse_lammps_scan_command(), _lammps_scan_timestep(), _lammps_scan_follow(), _lammps_scan_jump() and _lammps_scan_runs() raise it.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_follow(path, where, command, state)

Scan the file that an include or a jump command names.

Parameters:

  • path (string) – The file, as the command names it, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • command (string) – The command, include or jump.

  • state (dict) – The state of the scan (_lammps_scan()); the file is added to its files.

Raises:

ValueError – If the file is named with a LAMMPS variable that has no value in the script (_lammps_scan_variable()), or one written between quotes, which the scan does not substitute, or if the file does not exist: the scan cannot tell whether it reads a restart file; or as _lammps_scan() raises it for the file.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_jump(words, where, state)

Apply a jump command to a scan for read_restart.

A jump to another file is followed (_lammps_scan_follow()). A jump to the file being scanned (SELF, or its name) goes on from its label, or from the start of the file without one; LAMMPS looks for the label from the start of the file, so a label written more than once is its first one. To a label that the scan has read in the file, it runs the commands from the label again: a loop. The scan reads each command once, so it refuses a loop that runs again a command whose name, the file of whose include or jump, the time step of whose timestep, the unit system of whose units, the style of whose fix, or a command it runs from its arguments, is written with a variable (_lammps_scan_named()): the variable may have another value in the next pass. A jump to a file that includes the file being scanned is refused.

Parameters:

  • words (list of strings) – The words of the jump command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()).

Raises:

ValueError – If the loop runs again a command named with a variable, if the command jumps to a file that includes the file being scanned, or as _lammps_scan_follow() raises it.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_named(command, words, where)

Tell whether a LAMMPS command names a file or itself by a variable.

A command that LAMMPS runs again, in a loop, may read another file, set another time step or be another command when the variable that names it has another value (_lammps_scan_jump()). So may a command that an if, a run ... every, a partition or an mdi plugin command runs from its arguments when they hold a variable, which LAMMPS substitutes when it runs that command.

Parameters:

  • command (string) – The command, as the script writes it, before substitution.

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

Returns:

out (boolean) – True when the name of the command, the file of an include or a jump command, the time step of a timestep command, the unit system of a units command, the style of a fix command, or a command that the command runs from its arguments, is written with a LAMMPS variable.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_runs(words, where, state)

Scan the commands that a LAMMPS command runs from its arguments.

A partition command runs the rest of its words, after the partitions it names, as a command (Input::partition); an if, a run ... every and an mdi plugin command run quoted arguments (_LAMMPS_QUOTED_COMMANDS). Each such command is scanned as a command that LAMMPS may run (_lammps_scan_command()).

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()).

Raises:

ValueError – As _lammps_scan_command() raises it for a command that the command runs.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_script(filename)

Scan a LAMMPS script for its restart files and its time step.

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (dict) – The state of the scan at the end of the script (_lammps_scan()).

Raises:

ValueError – As lammps_script_reads_restart() raises it.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_text(command)

Return a LAMMPS command without its comment, with its quotes closed.

The text from an unquoted # onwards is a comment and is dropped. A quote that the command does not close, at which LAMMPS stops, is closed at the end of the command, so that the command is substituted and split into words (_lammps_substitute(), _split_words()) without an error.

Parameters:

command (string) – The command, as the script, or the command that runs it, writes it.

Returns:

out (string) – The command before its comment, with every quote closed.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_timestep(words, where, state, runner)

Apply a command that sets the time step to a scan.

LAMMPS sets the time step at a timestep command, to the default of the unit system at a units command (_LAMMPS_DEFAULT_TIMESTEPS), and to the default of the lj unit system, which it restores, at a clear command. The scan keeps what these commands set: dt, the time step of the last timestep command after the last units or clear command, and units, the unit system of the last units command after the last clear command. A units command after a timestep command, with no clear command between them, is added to units_after_timestep, and lammps_script_reads_restart() refuses it.

The scan reads each command once, from top to bottom, so it refuses such a command where LAMMPS may run it or not: a command that another command runs from its arguments, and a command after a jump command. It refuses a timestep command whose argument is not a number above 0 after substitution, and a fix with which LAMMPS changes the time step during a run (_LAMMPS_TIMESTEP_FIXES).

Parameters:

  • words (list of strings) – The words of the command, after substitution: a clear, a units or a timestep command, or a fix that changes the time step (_lammps_fix_resets_timestep()).

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()); changed in place.

  • runner (string or None) – The command that runs this one from its arguments, as the error messages name it; None for a command of the script.

Raises:

ValueError – If the command is a fix that changes the time step; if another command runs it, or it comes after a jump command; or if it is a units or a timestep command without an argument, or a timestep command whose argument is not a number above 0.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_unknown(variables, names)

Take the value of LAMMPS variables from the scan.

A variable that a command defines or moves on to its next value when the command may or may not run (inside the command of an if, of a run ... every, of a partition), or that a next command moves on, has no value for the scan.

Parameters:

  • variables (dict) – The variables of the scan (_lammps_scan_variable()); changed in place.

  • names (list of strings) – The names of the variables.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_values(words, state, runner)

Apply a variable or a next command to the variables of a scan.

A variable command of the script sets the variable as _lammps_scan_variable() reads it. A variable command that another command runs from its arguments, which may or may not run, and a next command leave their variables without a value (_lammps_scan_unknown()).

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • state (dict) – The state of the scan (_lammps_scan()); its variables are changed in place.

  • runner (string or None) – The command that runs this one from its arguments; None for a command of the script.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_variable(variables, words)

Apply a variable command to the variables of a scan.

A variable has a value for the scan when the script gives it one value: a string variable and an index variable of one word, and an equal variable, whose formula, the words after the style joined as LAMMPS joins them, is substituted when it is a plain number (_lammps_variable_value()). An index variable with several values, which a next command moves on to the next one, and a variable of another style have no value.

Parameters:

  • variables (dict) – The variables, from their name to a (style, value) pair, as _lammps_substitute() takes them; changed in place.

  • words (list of strings) – The words of the command: variable, the name, the style and its arguments.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_words(command, variables, where)

Return the words of a LAMMPS command, as the scan reads them.

Parameters:

  • command (string) – The command, as the script, or the command that runs it, writes it.

  • variables (dict) – The variables of the scan (_lammps_scan_variable()).

  • where (string) – The file and line of the command, for the error message.

Returns:

out (list of strings) – The words of the command without its comment, after substitution (_lammps_substitute()), with the quotes removed.

pyretis.inout.engine_temperature.lammps_scan._lammps_scan_writes(words, where, state)

Note the file that a print, fix print or log writes.

LAMMPS writes the text of a print command and of a print fix to the file of their file or append keyword, and its log to the file of a log command. A script that includes such a file reads the text it writes there, not the file of input_path (_lammps_scan_script() refuses it).

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()); the file is added to its written.

pyretis.inout.engine_temperature.lammps_scan._refuse_lammps_scan_after_jump(words, where, state, what)

Refuse a command after a jump that can change the time step.

After a jump command, which commands LAMMPS runs, and the values its variables have, depend on the jump and on the next commands that make LAMMPS skip it, while the scan reads the commands from top to bottom. Besides the commands that set the time step (_lammps_scan_timestep()), the scan refuses there a read_restart command, which sets the time step of its restart file, and a command written with a variable (_lammps_scan_named()), such as an include whose file is named with one.

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • state (dict) – The state of the scan (_lammps_scan()).

  • what (string) – What the command does, for the error message.

Raises:

ValueError – If the command comes after a jump command.

pyretis.inout.engine_temperature.lammps_scan._refuse_lammps_scan_code(words, where)

Refuse a command that runs LAMMPS commands the scan cannot read.

PyRETIS cannot tell whether such a command reads a restart file or changes the time step: Python code (the python command, the fix styles python, python/invoke and python/move, the pair style python and the python style of a variable), a plugin that plugin load loads, the commands an MDI driver sends to mdi engine, the commands of a KIM model (kim and the old kim_* commands), and the shell commands that change the files a script reads (_LAMMPS_SCAN_SHELL).

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

Raises:

ValueError – If the command is one of these.

pyretis.inout.engine_temperature.lammps_scan._refuse_lammps_scan_command(words, where, runner)

Refuse a command whose effect the scan for read_restart misses.

Parameters:

  • words (list of strings) – The words of the command, after substitution.

  • where (string) – The file and line of the command, for the error message.

  • runner (string or None) – The command that runs this one from its arguments, as the error messages name it; None for a command of the script.

Raises:

ValueError – If the name of the command holds a LAMMPS variable that has no single value in the script, if the command is one that _refuse_lammps_scan_code() refuses, or if another command runs an include, a jump or a read_restart.

pyretis.inout.engine_temperature.lammps_scan.lammps_script_files(filename)

Return the files that the include and jump commands of a script name.

The script is scanned as lammps_script_reads_restart() scans it, with the same refusals; the scan reads each file in the directory of the script.

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (list of tuples) – For each include command, and each jump command to another file, whose file the scan reads, in the order it reads them: the file as the command names it (after substitution), the file and line of the command, and the name of the command.

Raises:

ValueError – As lammps_script_reads_restart() raises it.

pyretis.inout.engine_temperature.lammps_scan.lammps_script_reads_restart(filename)

Tell where a LAMMPS script can read a restart file.

The scan reads the commands of the script, and of the files its include commands and its jump commands to another file name, as LAMMPS reads them (lammps_script_commands()): their comments dropped, their variables substituted where the script gives them one value (_lammps_scan_variable()). It reads the name of each command, its first word, only: the word read_restart in a print text or in the value of a variable is no command. The commands that if, run ... every, partition and mdi plugin run from their arguments are read the same way.

The scan refuses what keeps it from telling whether the script reads a restart file, or what time step LAMMPS runs with:

  • an include, a jump or a read_restart that another command runs from its arguments: PyRETIS does not follow them;

  • an include or a jump whose file is named with a variable that has no single value in the script, or that is written between quotes, or does not exist;

  • a command named by a variable that has no single value;

  • a loop (a jump back to a label of its file) that runs again a command named with a variable, an include or a jump whose file is named with one, or a command that runs commands with one from its arguments (_lammps_scan_named()), and a jump to a file that includes the file of the command (_lammps_scan_jump());

  • Python code, a plugin, an MDI engine, a KIM command and the shell commands that change the files a script reads (_refuse_lammps_scan_code());

  • a command that sets the time step (timestep, units, clear) that another command runs from its arguments, or that comes after a jump command; a timestep command whose argument is not a number after substitution; a dt/reset fix, with which LAMMPS changes the time step during a run (_lammps_scan_timestep());

  • in a script without read_restart, a units command after a timestep command, with no clear command between them, at which LAMMPS sets the time step to the default of the unit system (_lammps_scan_timestep()); a script with read_restart is read by read_lammps_restarts(), which refuses it too;

  • a line that is not UTF-8 text, and a command, without its comment, with a character that is not ASCII (lammps_script_commands()).

It refuses no other command, unlike read_lammps_restarts(), whose reader refuses what makes the temperature of the script unknown; it tells the scripts whose time step depends on a restart file from the others, and reads the time step of the others (read_lammps_timestep()).

Parameters:

filename (string) – The LAMMPS script.

Returns:

out (string or None) – The file and line of the first read_restart command, or None when the script has none.

Raises:

ValueError – If the script holds one of the commands the scan refuses.

pyretis.inout.engine_temperature.lammps_scan.read_lammps_timestep(filename)

Read the time step LAMMPS runs a script with.

The script is scanned as lammps_script_reads_restart() scans it, with the same refusals. The time step of a script that reads a restart file is the one read_lammps_restarts() gives: the one of the last timestep command after the last read_restart, else the one of the restart file. The time step of another script is the one its commands set (_lammps_scan_timestep()): the one of the last timestep command after the last units or clear command, else the default of the unit system of the last units command (_LAMMPS_DEFAULT_TIMESTEPS). A script that states no unit system and no time step after its last clear command, which LAMMPS runs with the default time step of the lj unit system, is refused: PyRETIS takes no unit system that the script does not state.

Parameters:

filename (string) – The LAMMPS script.

Returns:

  • out[0] (float) – The time step.

  • out[1] (string) – What sets it, with its file and line: a timestep command, a units command, whose default it is, or a restart file.

Raises:

ValueError – As lammps_script_reads_restart() raises it, and as read_lammps_restarts() raises it for a script that reads a restart file; and if the script states no unit system and no time step after its last clear command, or a unit system that LAMMPS does not have.

pyretis.inout.engine_temperature.lammps_scan.read_lammps_units(filename)

Read the unit system LAMMPS runs a script with.

The script is scanned as read_lammps_timestep() scans it, with the same refusals and with the files of its include and jump commands: the unit system is the one of the last units command after the last clear command (_lammps_scan_timestep()). A script that reads a restart file states the unit system of the restart file before read_restart, and read_lammps_restarts() refuses another.

Parameters:

filename (string) – The LAMMPS script.

Returns:

  • out[0] (string or None) – The unit system, or None for a script without a units command after its last clear command, which LAMMPS runs in lj units.

  • out[1] (string or None) – The file and line of that units command.

Raises:

ValueError – As lammps_script_reads_restart() raises it, and if the units command names a unit system that LAMMPS does not have.