pyretis.setup package

pyretis.setup package

This package handles set-up of simulations from settings.

Package structure

Modules

common.py (pyretis.setup.common)

Common methods for handling settings. Defines a method to dynamically import methods and classes from user-specified modules.

createforcefield.py (pyretis.setup.createforcefield)

Handle creation of force fields from input simulation settings.

createsimulation.py (pyretis.setup.createsimulation)

Handle creation of simulations from input simulation settings.

createsystem.py (pyretis.setup.createsystem)

Handle creation of systems from input simulation settings.

__init__.py

This file. Handles imports for PyRETIS.

Important methods defined in this package

create_engine (create_engine())

Create an engine from input settings.

create_force_field (create_force_field())

Create a force field from input settings.

create_orderparameter (create_orderparameter())

Create an order parameter from input settings.

create_simulation (create_simulation())

Create a simulation from input settings.

create_system (create_system())

Create a system from input settings.

List of submodules

• pyretis.setup.common
• pyretis.setup.createforcefield
• pyretis.setup.createsimulation
• pyretis.setup.createsystem

pyretis.setup.common module

This module defines common methods for the settings handling.

Important methods defined here

create_external (create_external())

Method to create objects from settings.

check_settings (check_settings())

Check that required simulation settings are actually given.

create_engine (create_engine())

Method to create an engine from settings.

create_orderparameter (create_orderparameter())

Method to create order parameters from settings.

create_potential (create_potential())

Method to create a potential from settings.

pyretis.setup.common.check_settings(settings, required)

Check that required simulation settings are actually given.

This method will look for required settings in the given settings. If one or more keys from the given required list of strings are not found, this method will return False. Otherwise, it will return True. Typically, an exception should be raised if False is returned, this is handled outside the method in case someone wants to add some magic handling of missing settings.

Parameters:

• settings (dict) – This dict contains the given settings
• required (list of strings) – This list contains the settings that are required and which we will check the presence of.

Returns:

• result (boolean) – True if all required settings are present, False otherwise.
• not_found (list of strings) – There are the required settings we did not find.

pyretis.setup.common.create_engine(settings)

Create an engine from settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:out (object like EngineBase) – This object represents the engine.

pyretis.setup.common.create_external(settings, key, factory, required_methods, key_settings=None)

Create external objects from settings.

This method will handle the creation of objects from settings. The requested objects can be PyRETIS internals or defined in external modules.

Parameters:

• settings (dict) – This dictionary contains the settings for the simulation.
• key (string) – The setting we are creating for.
• factory (callable) – A method to call that can handle the creation of internal objects for us.
• required_methods (list of strings) – The methods we need to have if creating an object from external files.
• key_settings (dict, optional) – This dictionary contains the settings for the specific key we are processing. If this is not given, we will try to obtain these settings by settings[key]. The reason why we make it possible to pass these as settings is in case we are processing a key which does not give a simple setting, but a list of settings. It that case settings[key] will give a list to process. That list is iterated somewhere else and key_settings can then be used to process these elements.

Returns:

out (object) – This object represents the class we are requesting here.

pyretis.setup.common.create_orderparameter(settings)

Create order parameters from settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:out (object like OrderParameter) – This object represents the order parameter.

pyretis.setup.common.create_potential(settings, key_settings)

Create a potential from settings.

Parameters:

• settings (dict) – This dictionary contains the settings for the simulation.
• key_settings (dict) – Settings for the potential we are creating.

Returns:

out (object like PotentialFunction) – The object representing the potential function.

pyretis.setup.createforcefield module

This module handles the creation of force fields from simulation settings.

Important methods defined here

create_potentials (create_potentials())

Method for creating potentials from a dictionary of settings. Note that this method will make use of create_potential().

create_force_field (create_force_field())

Method to create a force field from input settings.

pyretis.setup.createforcefield.create_force_field(settings)

Create a force field from input settings.

This method will create the required potential functions with the specified parameters from settings.

Parameters:settings (dict) – This dictionary contains the settings for a single potential. Returns:out (object like ForceField) – This object represents the force field.

pyretis.setup.createforcefield.create_potentials(settings)

Create potential functions from given simulations settings.

This method will basically loop over the given potential settings and just run create_potential() for each setting.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:

• out[0] (list) – A list of potential functions.
• out[1] (list) – A list of parameters for the potential functions.

pyretis.setup.createsimulation module

This module handles the creation of simulations from settings.

The different simulations are defined as objects which inherit from the base Simulation class defined in pyretis.simulation.simulation. Here, we are treating each simulation with a special case.

Important methods defined here

create_simulation (create_simulation())

Method for creating a simulation object from settings.

create_ensemble (create_ensemble())

Method for creating an ensemble dictionary from settings.

create_ensembles (create_ensembles())

Method for creating a list of ensemble from settings.

create_nve_simulation (create_mve_simulation())

Method for creating a nve simulation object from settings.

create_mdflux_simulation (create_mdflux_simulation())

Method for creating a mdflux simulation object from settings.

create_umbrellaw_simulation (create_umbrellaw_simulation())

Method for creating a umbrellaw simulation object from settings.

create_tis_simulation (create_tis_simulation())

Method for creating a tis simulation object from settings.

create_retis_simulation (create_retis_simulation())

Method for creating a retis simulation object from settings.

prepare_system (prepare_system())

Method for creating a system object from settings.

prepare_engine (prepare_engine())

Method for creating an engine object from settings.

pyretis.setup.createsimulation.create_ensemble(settings)

Create the path ensemble from (ensemble) simulation settings.

Parameters:settings (dict) – This dict contains the settings needed to create the path ensemble. Returns:ensemble (dict of) – objects that contains all the information needed in the ensemble.

pyretis.setup.createsimulation.create_ensembles(settings)

Create a list of dictionary from ensembles simulation settings.

Parameters:settings (dict) – This dict contains the settings needed to create the path ensemble. Returns:ensembles (list of dicts) – List of ensembles.

pyretis.setup.createsimulation.create_mdflux_simulation(settings)

Set up and create a MD FLUX simulation.

Parameters:settings (dict) – The settings needed to set up the simulation. Returns:SimulationMDFlux (object like SimulationMDFlux) – The object representing the simulation to run.

pyretis.setup.createsimulation.create_nve_simulation(settings)

Set up and create a NVE simulation.

Parameters:settings (dict) – The settings needed to set up the simulation. Returns:SimulationNVE (object like SimulationNVE) – The object representing the simulation to run.

pyretis.setup.createsimulation.create_retis_simulation(settings)

Set up and create a RETIS simulation.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:SimulationRETIS (object like SimulationRETIS) – The object representing the simulation to run.

pyretis.setup.createsimulation.create_simulation(settings)

Create simulation(s) from given settings.

This function will set up some common simulation types. It is meant as a helper function to automate some very common set-up task. It will here check what kind of simulation we are to perform and then call the appropriate function for setting that type of simulation up.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:simulation (object like Simulation) – This object will correspond to the selected simulation type.

pyretis.setup.createsimulation.create_tis_simulation(settings)

Set up and create a single TIS simulation.

Parameters:settings (dict) – The settings needed to set up the simulation. Returns:SimulationTIS (object like SimulationSingleTIS) – The object representing the simulation to run.

pyretis.setup.createsimulation.create_umbrellaw_simulation(settings)

Set up and create a Umbrella Window simulation.

Parameters:settings (dict) – The settings needed to set up the simulation. Note that mincycle is trasmitted as steps to the object, but is has a different meaning than the other simulations. Returns:UmbrellaWindowSimulation (obj like UmbrellaWindowSimulation) – The object representing the simulation to run.

pyretis.setup.createsimulation.prepare_engine(settings)

Create an engine from given settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:engine (object like engine) – This object will correspond to the selected simulation type.

pyretis.setup.createsimulation.prepare_system(settings)

Create a system from given settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation. Returns:syst (object like syst) – This object will correspond to the selected simulation type.

pyretis.setup.createsystem module

This module handles the set-up of initial positions and a box.

The initial positions can either be generated on a lattice, or it can be read from a file.

Important methods defined here

set_up_box (set_up_box())

Create a simulation box from simulation settings.

create_initial_positions (create_initial_positions())

Get initial positions based on settings. This will either be read from a file or generated on a lattice.

create_system (create_system())

Set up a system from given settings. This method will probably also need to set/get the initial positions and velocities for the particles and set up the simulation box.

create_velocities (create_velocities())

Create velocities from settings for a system with particles.

initial_positions_file (initial_positions_file())

Get initial positions from a file.

initial_positions_lattice (initial_positions_lattice())

Get initial positions by generating a lattice.

pyretis.setup.createsystem._assign_mass_from_file(filename, unit)

Assign masses and imasses to particles from a configuration file.

This function is useful when velocities will be internally modified while using an external engine.

Parameters:

• filename (string) – The configuration file.
• unit (string) – The system of units.

pyretis.setup.createsystem._get_snapshot_from_file(pos_settings, units)

Get a configuration snapshot from a file.

This snapshot will be used to set up the initial configuration.

Parameters:

• pos_settings (dict) – A dict with information on what we should read.
• units (string) – The internal units.

Returns:

• snapshot (dict) – The snapshot we found in the file. It will at least have the keys with the positions (‘x’, ‘y’, ‘z’) and atom name ‘atomnames’. It may have information about velocities (‘vx’, ‘vy’, ‘vz’) and the box (‘box’).
• convert (dict) – Dictionary with conversion factors to internal units.

pyretis.setup.createsystem.create_initial_positions(settings)

Set up the initial positions from the given settings.

The settings can specify the initial positions as a file or to be generated on a lattice by PyRETIS.

Parameters:settings (dict) – Settings for creating the initial positions. Returns:

• out[0] (object like Particles) – The particles we created.
• out[1] (list) – The size associated with the particles. Can be used to create a box.
• out[2] (boolean) – True if we have read/created velocities different from just zeros. This is only True if we have read from a file with velocities.

pyretis.setup.createsystem.create_system(settings)

Create a system from input settings.

Parameters:settings (dict) – The dict with the simulation settings. Returns:system (object like System) – The system object we create here.

pyretis.setup.createsystem.create_velocities(system, settings, vel)

Create velocities from settings for a system.

Parameters:

• system (object like System) – The system to create velocities for. It’s needed since we need to know the degrees of freedom.
• settings (dict) – Settings to use for creating the velocities.
• vel (boolean) – If True, we already read velocities. They will now be overwritten. We just make some warnings about this.

Returns:

out (boolean) – True if we actually generated velocities.

pyretis.setup.createsystem.initial_positions_file(settings)

Get initial positions from an input file.

Parameters:settings (dict) – The input settings for the simulation. Returns:

• particles (object like Particles) – The particles we created.
• size (list of floats) – A size for the region we created. This can be used to create a box.
• vel_read (boolean) – True if we read velocities from the input file.

pyretis.setup.createsystem.initial_positions_lattice(settings)

Generate initial positions based on given settings.

We assume here the input values are given with the correct units as dictated by settings['system']['units'].

Parameters:settings (dict) – The input settings for the simulation. Returns:

• particles (object like Particles) – The particles we created.
• size (list of floats) – A size for the region we created. This can be used to create a box.

pyretis.setup.createsystem.set_up_box(settings, boxs, dim=3)

Set up a box from given settings.

Parameters:

• settings (dict) – The dict with the simulation settings.
• boxs (dict or None) – If no box settings are given, we can still create a box, inferred from the positions of the particles. This dict contains the settings to do so.
• dim (integer, optional) – Number of dimensions for the box. This is used only as a last resort when no information about the box is given.

Returns:

box (object like BoxBase or None) – The box if we managed to create it, otherwise None.