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 handing 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.
createoutput.py (pyretis.inout.settings.createoutput)
Handle creation of output tasks 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_output_tasks (create_output_tasks())
Create output tasks from input settings.
create_simulation (create_simulation())
Create a simulation from input settings.
create_system (create_system())
Create a system from input settings.

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)[source]

Create external objects from settings.

This method will handle 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) – This dictionary contains the settings for 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 – This object represents the class we are requesting here.

Return type:

object

pyretis.inout.setup.common.check_settings(settings, required)[source]

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 if will return True. Typically, and 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)[source]

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 – The thing we managed to import.

Return type:

object

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)[source]

Create order parameters from settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation.
Returns:out – This object represents the order parameter.
Return type:object like OrderParameter
pyretis.inout.setup.common.create_engine(settings)[source]

Create an engine from settings.

Parameters:settings (dict) – This dictionary contains the settings for the simulation.
Returns:out – This object represents the engine.
Return type:object like EngineBase
pyretis.inout.setup.common.create_potential(settings, key_settings)[source]

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 – The object representing the potential function.

Return type:

object like PotentialFunction

pyretis.inout.setup.createoutput module

Module for handling output from simulations.

This module defines functions and classes for handling the output from simulations.

Important classes defined here

OutputTask (OutputTask)
A generic class for handling output tasks.
OutputTaskScreen (OutputTaskScreen)
A class for handling output tasks that will print to the screen.
OutputTaskFile (OutputTaskFile)
A class for handling output tasks that will write to a file.
OutputTaskFileCombine (OutputTaskFileCombine)
A class for handling output tasks that will write to a file, but require some special pre-processing of the data to be written. Currently, this is only used to move files physically when storing external paths.

Important methods defined here

create_output_tasks (create_output_tasks())
Function that sets up output tasks from a dictionary of settings.
class pyretis.inout.setup.createoutput.OutputTask(name, result, writer, when)[source]

Bases: object

A base class for writing simulation output.

This class will handle a output task for a simulation. The output task may be something that should print to the screen or a file. This object is a general class for output tasks and the specific writers (‘tasks’) for file and screen are implemented in OutputTaskFile and OutputTaskScreen.

name

string – This string identifies the task, it can for instance be used to reference the dictionary used to create the writer.

result

tuple of strings – This string defines the result we are going to output.

writer

object like Writer – This object will handle the actual formatting of the result.

when

dict – Determines if the task should be executed.

__str__()[source]

Output some info about this output task.

output(simulation_result)[source]

Output a task, given results from a simulation.

This will output the task using the result found in the simulation_result which should be the dictionary returned from a simulation object (e.g. object like Simulation) after a step. For trajectories, we expect that simulation_result contain the key traj so we can pass it to the trajectory writer.

Parameters:simulation_result (dict) – This is the result from a simulation step.
Returns:out – True if the writer wrote something, False otherwise.
Return type:boolean
target = 'undefined'
write(step, *result)[source]

Write the obtained result using the writer.

Parameters:
  • step (dict) – Information about the current simulation step.
  • result (Any type) – This is the result to be written, handled by the writer.
Returns:

out – True if we managed to do the writing, False otherwise.

Return type:

boolean

pyretis.inout.setup.createoutput.create_output_tasks(settings, directory=None, engine=None)[source]

Generate output tasks from settings and defaults.

This function will return actual objects that can be added to the simulation. It uses task_from_settings to generate the output tasks which can be added to a simulation.

Parameters:
  • settings (dict) – These are the settings for the simulation.
  • directory (string) – The directory to write output files to.
  • engine (object like EngineBase) – This object is used to determine if we need to do something special for external engines. If no engine is given, we do not do anything special.
Yields:

out (object like OutputTask.)

pyretis.inout.setup.createforcefield module

This module handles 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)[source]

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 – This object represents the force field.
Return type:object like ForceField
pyretis.inout.setup.createforcefield.create_potentials(settings)[source]

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 creation of simulations from settings.

The different simulations are defined as objects which inherits from the base Simulation class defined in pyretis.simulation.simulation. Here, we are treat each simulation with a special case since they are indeed special :-)

Important methods defined here

create_simulation (create_simulation())
Method for creating a simulation object from settings.
pyretis.inout.setup.createsimulation.create_simulation(settings, kwargs)[source]

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:

    • system : object like System
      This is the system for which the simulation will run.
    • engine : object like EngineBase
      The engine to use for the simulation.
Returns:

out – This object will correspond to the selected simulation type.

Return type:

object like Simulation

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)[source]

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)[source]

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 – The system object we create here.

Return type:

object like System

pyretis.inout.setup.createsystem.create_velocities(system, settings, vel)[source]

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 – True if we actually generated velocities.

Return type:

boolean

pyretis.inout.setup.createsystem.set_up_box(settings, boxs, dim=3)[source]

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) – Number of dimensions for the box. This is used only as a last resort when no information about the box is given.
Returns:

box – The box if we managed to create it, otherwise None.

Return type:

object like BoxBase or None

pyretis.inout.setup.createsystem.initial_positions_file(settings)[source]

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)[source]

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.