pele.storage.database

Module source

Database for simulation data in a relational database

class pele.storage.database.Minimum

Source

class Minimum(Base):

The Minimum class represents a minimum in the database.

Parameters:

energyfloat

coordsnumpy array

coordinates

Attributes:

energy

the energy of the minimum

coords

the coordinates of the minimum. This is stored as a pickled numpy array which SQL interprets as a BLOB.

fvib

the log product of the squared normal mode frequencies. This is used in the free energy calcualations

pgorder

point group order

invalid

a flag that can be used to indicate a problem with the minimum. E.g. if the Hessian has more zero eigenvalues than expected.

user_data

Space to store anything that the user wants. This is stored in SQL as a BLOB, so you can put anything here you want as long as it’s serializable. Usually a dictionary works best.

See also

Database, TransitionState

Notes

To avoid any double entries of minima and be able to compare them, only use Database.addMinimum() to create a minimum object.

Minimum.id()

Source

def id(self):

return the sql id of the object

Minimum.__eq__()

Source

def __eq__(self, m):

m can be integer or Minima object

class pele.storage.database.TransitionState

Source

class TransitionState(Base):

Transition state object

The TransitionState class represents a saddle point in the database.

Parameters:

energyfloat

coordsnumpy array

min1Minimum object

first minimum

min2Minimum object

first minimum

eigenvalfloat, optional

lowest (single negative) eigenvalue of the saddle point

eigenvecnumpy array, optional

eigenvector which corresponds to the negative eigenvalue

fvibfloat

log product of squared frequencies for free energy calculation

pgorderinteger

point group order

Attributes:

energy

The energy of the transition state

coords

The coordinates of the transition state. This is stored as a pickled numpy array which SQL interprets as a BLOB.

fvib

The log product of the squared normal mode frequencies. This is used in the free energy calcualations

pgorder

The point group order

invalid

A flag that is used to indicate a problem with the transition state. E.g. if the Hessian has more than one negaive eigenvalue then it is a higher order saddle.

user_data

Space to store anything that the user wants. This is stored in SQL as a BLOB, so you can put anything here you want as long as it’s serializable. Usually a dictionary works best.

minimum1, minimum2

These returns the minima on either side of the transition state

eigenvec

The vector which points along the direction crossing the transition state. This is the eigenvector of the lowest non-zero eigenvalue.

eigenval

The eigenvalue corresponding to eigenvec. A.k.a. the curvature along the direction given by eigenvec

See also

Database, Minimum

Notes

To avoid any double entries and be able to compare them, only use Database.addTransitionState to create a TransitionStateobject.

programming note: The functions in the database require that ts.minimum1._id < ts.minimum2._id. This will be handled automatically by the database, but we must remember not to screw it up

TransitionState.id()

Source

def id(self):

return the sql id of the object

class pele.storage.database.SystemProperty

Source

class SystemProperty(Base):

table to hold system properties like potential parameters and number of atoms

The properties can be stored as integers, floats, strings, or a pickled object. Only one of the property value types should be set for each property.

SystemProperty.value()

Source

def value(self):

return the property value

SystemProperty.item()

Source

def item(self):

return a tuple of (name, value)

class pele.storage.database.MinimumAdder

Source

class MinimumAdder:

This class manages adding minima to the database

Parameters:

dbdatabase object

Ecut: float, optional

energy cutoff, don’t add minima which are higher in energy

max_n_minimaint, optional

keep only the max_n_minima with the lowest energies. If E is greater than the minimum with the highest energy in the database, then don’t add this minimum and return None. Else add this minimum and delete the minimum with the highest energy. if max_n_minima < 0 then it is ignored.

commit_intervalint, optional

Commit the database changes to the hard drive every commit_interval steps. Committing too frequently can be slow, this is used to speed things up.

MinimumAdder.__call__()

Source

def __call__(self, E, coords):

this is called to add a minimum to the database

MinimumAdder.__del__()

Source

def __del__(self):

ensure that all the changes to the database are committed to the hard drive

class pele.storage.database.Database

Source

class Database:

Database storage class

The Database class handles the connection to the database. It has functions to create new Minima and TransitionState objects. The objects are persistent in the database and exist as soon as the Database class in connected to the database. If any value in the objects is changed, the changes are automatically persistent in the database (TODO: be careful, check commit transactions, …)

Database uses SQLAlchemy to connect to the database. Check the web page for available connectors. Unless you know better, the standard sqlite should be used. The database can be generated in memory (default) or written to a file if db is specified when creating the class.

Parameters:

dbstring, optional

filename of new or existing database to connect to. default creates new database in memory.

accuracyfloat, optional

energy tolerance to count minima as equal

connect_stringstring, optional

connection string, default is sqlite database

compareMinimacallable, bool = compareMinima(min1, min2), optional

called to determine if two minima are identical. Only called if the energies are within accuracy of each other.

createdbboolean, optional

create database if not exists, default is true

Attributes:

enginesqlalchemy database engine

sessionsqlalchemy session

accuracyfloat

on_minimum_removedsignal

called when a minimum is removed from the database

on_minimum_addedsignal

called when a new, unique, minimum is added to the database

on_ts_removedsignal

called when a transition_state is removed from the database

on_ts_addedsignal

called when a new, unique, transition state is added to the database

compareMinima

See also

Minimum

TransitionState

Examples

>>> from pele.storage import Database
>>> db = Database(db="test.db")
>>> for energy in np.random.random(10):
>>>     a.addMinimum(energy, np.random.random(10))
>>>
>>> for minimum in database.minima():
>>>     print minimum.energy

Database.get_lowest_energy_minimum()

Source

def get_lowest_energy_minimum(self):

return the minimum with the lowest energy

Database.addMinimum()

Source

def addMinimum(
    self, E, coords, commit=True, max_n_minima=-1, pgorder=None, fvib=None
):

add a new minimum to database

Parameters:

Efloat

coordsnumpy.array

coordinates of the minimum

commitbool, optional

commit changes to database

max_n_minimaint, optional

keep only the max_n_minima with the lowest energies. If E is greater than the minimum with the highest energy in the database, then don’t add this minimum and return None. Else add this minimum and delete the minimum with the highest energy. if max_n_minima < 0 then it is ignored.

Returns:

minimumMinimum

minimum which was added (not necessarily a new minimum)

Database.getMinimum()

Source

def getMinimum(self, mid):

return the minimum with a given id

Database.addTransitionState()

Source

def addTransitionState(
    self,
    energy,
    coords,
    min1,
    min2,
    commit=True,
    eigenval=None,
    eigenvec=None,
    pgorder=None,
    fvib=None,
):

Add transition state object

Parameters:

energyfloat

energy of transition state

coordsnumpy array

coordinates of transition state

min1, min2Minimum

minima on either side of the transition states

eigenvalfloat

the eigenvalue (curvature) across the transition state

eigenvecnumpy array

the eigenvector associated with eigenval

commitbool

commit changes to sql database

Returns:

tsTransitionState

the transition state object (not necessarily new)

Database.getTransitionState()

Source

def getTransitionState(self, min1, min2):

return the TransitionState between two minima

Returns:

tsNone or TransitionState

Database.getTransitionStatesMinimum()

Source

def getTransitionStatesMinimum(self, min1):

return all transition states connected to a minimum

Returns:

tsNone or TransitionState

Database.getTransitionStateFromID()

Source

def getTransitionStateFromID(self, id_):

return the transition state with id id_

Database.minima()

Source

def minima(self, order_energy=True):

return an iterator over all minima in database

Parameters:

order_energybool

order the minima by energy

Notes

Minimum.coords is deferred in database queries. If you need to access coords for multiple minima it is much faster to undefer before executing the query by, e.g. session.query(Minimum).options(undefer(“coords”))

Database.transition_states()

Source

def transition_states(self, order_energy=False):

return an iterator over all transition states in database

Database.minimum_adder()

Source

def minimum_adder(self, Ecut=None, max_n_minima=None, commit_interval=1):

wrapper class to add minima

Since pickle cannot handle pointer to member functions, this class wraps the call to add minimum.

Parameters:

Ecut: float, optional

energy cutoff, don’t add minima which are higher in energy

max_n_minimaint, optional

keep only the max_n_minima with the lowest energies. If E is greater than the minimum with the highest energy in the database, then don’t add this minimum and return None. Else add this minimum and delete the minimum with the highest energy. if max_n_minima < 0 then it is ignored.

Returns:

handler: minimum_adder class

minimum handler to add minima

Database.removeMinimum()

Source

def removeMinimum(self, m, commit=True):

remove a minimum from the database

Remove a minimum and any objects (TransitionState) pointing to that minimum.

Database.mergeMinima()

Source

def mergeMinima(self, min1, min2):

merge two minima in the database

min2 will be deleted and everything that points to min2 will point to min1 instead.

Database.remove_transition_state()

Source

def remove_transition_state(self, ts, commit=True):

remove a transition states from the database

Database.number_of_minima()

Source

def number_of_minima(self):

return the number of minima in the database

Notes

This is much faster than len(database.minima()), but is is not instantaneous. It takes a longer time for larger databases. The first call to number_of_minima() can be much faster than subsequent calls.

Database.number_of_transition_states()

Source

def number_of_transition_states(self):

return the number of transition states in the database

See also

number_of_minima

Notes

see notes for number_of_minima()

Database.get_property()

Source

def get_property(self, property_name):

return the minimum with a given name

Database.add_property()

Source

def add_property(
    self, name, value, dtype=None, commit=True, overwrite=True
):

add a system property to the database

Parameters:

namestring

the name of the property

valueobject

the value of the property

dtypestring

the datatype of the property. This can be “int”, “float”, “string”, “pickle”, or None. If None, the datatype will be automatically determined.

This could anything, such as a potential parameter, the number of atoms, or the

list of frozen atoms. The properties can be stored as integers, floats,

strings, or a pickled object. Only one of the property value types

should be set for each property.

For a value of type “pickle”, pass the object you want pickled, not

the pickled object. We will do the pickling and unpickling for you.

Database.add_properties()

Source

def add_properties(self, properties, overwrite=True):

add multiple properties from a dictionary

propertiesdict

a dictionary of (name, value) pairs. The data type of the value will be determined automatically

pele.storage.database.test_fast_insert()

Source

def test_fast_insert():

bulk inserts are really slow, we should add something along the lines of this answer to speed things up where needed

http://stackoverflow.com/questions/11769366/why-is-sqlalchemy-insert-with-sqlite-25-times-slower-than-using-sqlite3-directly