pyretis.inout.setup package

This package handles set-up of simulations from settings.

Package structure

Modules

common.py (pyretis.inout.settings.common)

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

createforcefield.py (pyretis.inout.settings.createforcefield)

Handle creation of force fields from input simulation settings.

createsimulation.py (pyretis.inout.settings.createsimulation)

Handle creation of simulations from input simulation settings.

createsystem.py (pyretis.inout.settings.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.inout.setup.common
• pyretis.inout.setup.createforcefield
• pyretis.inout.setup.createsimulation
• pyretis.inout.setup.createsystem

pyretis.inout.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.

import_from (import_from())

A method to dynamically import method/classes etc. from user specified modules.

pyretis.inout.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.inout.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.inout.setup.common.import_from(module_path, function_name)

Import a method/class from a module.

This method will dynamically import a specified method/object from a module and return it. If the module can not be imported or if we can’t find the method/class in the module we will raise exceptions.

Parameters:

• module_path (string) – The path/filename to load from.
• function_name (string) – The name of the method/class to load.

Returns:

out (object) – The thing we managed to import.

Note

Here we need to handle different versions of python. This is due to the imp module being deprecated and the same time importlib is changing between versions 3.4 and 3.5 [1].

References

[1]	http://bugs.python.org/issue21436

pyretis.inout.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.inout.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.inout.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.inout.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.inout.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.inout.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.inout.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.

pyretis.inout.setup.createsimulation.create_simulation(settings, kwargs)

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.

• kwargs (dict) – This dict contains objects that might be needed to initialise the simulation for instance:

  • systemobject like System

    This is the system for which the simulation will run.

  • engineobject like EngineBase

    The engine to use for the simulation.

Returns:

out (object like Simulation) – This object will correspond to the selected simulation type.

pyretis.inout.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.inout.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.inout.setup.createsystem.create_system(settings, engine=None, restart=None)

Set up a system from the given settings.

In order to set up the system, there are several things we might need to do:

1. Set the initial positions.
2. Create/set-up the simulation box.
3. Set initial velocities.

Parameters:

• settings (dict) – The dict with the simulation settings.
• engine (object like EngineBase, optional) – The engine to be used for the simulation. This can be given in case we want to choose an external particle list type.
• restart (dict, optional) – A dict with restart information, if we are doing a restart.

Returns:

system (object like System) – The system object we create here.

pyretis.inout.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.inout.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.

pyretis.inout.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.inout.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.