schrodinger.utils.sea.sea module¶

Functionality for “ark” file format handling.

‘sea’ stands for Schrodinger Enhanced Ark.

The syntax of the ark format can be found elsewhere (e.g., Desmond User Manual).

Below is an example, demonstrating the most basic usage of this module.

Say we have a file called ‘config.cfg’ with the following content:

------start of the content------
fep = {
   lambda   = "default:12"
   i_window = ?
   output   = {
      name     = "$JOBNAME$[_replica$REPLICA$].dE"
      first    = 0.0
      interval = 1.2
   }
}
temperature = [300.0 310.0 320.0]
------end of the content------

We can parse it with a code like this:

import schrodinger.utils.sea as sea

cfg = sea.Map( open( "config.cfg", "r" ).read() )

In fact, the code does much more than merely parsing the content. But the important thing here is that at the end we get an ‘Map’ object that enables us to easily manipulate settings for the file as shown below:

assert( cfg.fep.lambda_    .val == "default:12" )
assert( cfg.fep.i_window   .val == None )
assert( cfg.output.first   .val == 0.0 )
assert( cfg.output.interval.val == 1.2 )
assert( cfg.output.name.raw_val == "$JOBNAME$[_replica$REPLICA$].dE" )
assert( cfg.temperature[0].val  == 300.0 )
assert( cfg.temperature[1].val  == 310.0 )
assert( cfg.temperature[2].val  == 320.0 )
assert( cfg.temperature   .val  == [300.0, 310.0, 320.0]

# Another way to access the data:
assert( cfg["fep"]["lambda"  ].val == "default:12" )
assert( cfg["fep"]["i_window"].val == None )

cfg.output.first.val = 1.0
assert( cfg.output.first.val == 1.0 )

cfg.output.i_window.val = 1
assert( cfg.output.first.val == 1 )

cfg.fep.lambda_.val = "a different string"
assert( cfg.fep.lambda_.val == "a different string" )

cfg.temperature[0].val = 20.0
assert( cfg.temperature[0].val == 20.0 )

# Adds a new key-value pair.
cfg["new_key"] = 1

# Deletes an existing key-value pair.
del cfg.fep["interval"]

print str( cfg )
#Result:
#fep = {
#   i_window = 1
#   lambda = "a different string"
#   new_key = 1
#   output = {
#      name = "$JOBNAME$[_replica$REPLICA$].dE"
#      first = 1.0
#   }
#}
#temperature = [20.0 310.0 320.0]

Some explanations of the code:

The “.val” is in fact a python ‘property’ for reading and mutating the value of the parameter.
In the file, we have a parameter named “lambda”, but in the code, we access it with a trailing underscore as ‘lambda’ is a python keyword.
The value ‘?’ in the file will correspond to ‘None’ in python code.
The “.raw_val” is similar to the “.val”. The different is that the latter will give a value where the macro’s are expanded, whereas the former will give the original string. More information regarding macros is beyond the scope of this docstring, please refere to the document.
Notice an expression like: ‘temperature[0].val’ returns the value of the 0-th element of the list, while ‘temperature.val’ returns a buildin ‘list’ object for the entire list.

schrodinger.utils.sea.sea.update_macro_dict(new_macro_dict)¶

schrodinger.utils.sea.sea.set_macro_dict(new_macro_dict)¶

schrodinger.utils.sea.sea.get_macro_dict()¶

schrodinger.utils.sea.sea.expand_macro(s, macro_dict)¶

Replaces the macros in the string ‘s’ using the values given by the macro dictionary ‘macro_dict’. The expanded string will be returned.

Rules or conventions about macros and expansion:

All macros should start with a single ‘$’, followed by capital letters, e.g., “$JOBNAME”, “$USERNAME”.
Optional string fragments should be bracketed by ‘$[’ and ‘$]’, e.g., “myjob$[_lambda$LAMBDANO$]”, where “_lambda$LAMBDANO” is an optional string fragment.
Optional string fragments will be retained with the brackets ‘$[’ and ‘$]’ stripped off if the macro ‘$LAMBDANO’ is defined; otherwise, the optional string together with the brackets will be removed.

class schrodinger.utils.sea.sea.Sea(parent=None)¶

Bases: object

This is the base class the ‘Atom’, ‘List’, and ‘Map’ classes. A ‘Sea’ object will manage three types of information:

tag: As the name suggests, tags allow users of the ‘Sea’ object to label the object with strings and latter on to extract or print those with certain tags.

parent: Pointer (weak reference) to the parent of this ‘Sea’ object.

Operations to manipulate these data are defined in this base class.

__init__(parent=None)¶

Creates and initializes a ‘Sea’ object.

Parameters: parent – This parameter provides the parent of this ‘Sea’ object. It can be None.

property sval¶: Readonly. Returns the current Sea object.

apply(op)¶: Recursively applies the operation as given by ‘op’ to all ‘Sea’ subobjects of this ‘Sea’ object.

parent()¶: Rerturns the parent of this ‘Sea’ object or None if it does not have a parent.

set_parent(parent)¶: Sets the parent of this ‘Sea’ object to the given ‘parent’.

tag()¶: Returns tags, which are ‘set’ objects.

has_tag(tag)¶

Returns True if we already tagged this object with the given ‘tag’.

Parameters: tag – The given ‘tag’ can be a string, or a list of strings, or a ‘set’ of strings.

add_tag(tag, propagate=True)¶

Tags this object with another string(s).

Parameters

tag – The given ‘tag’ can be a string, or a list of strings, or a ‘set’ of strings.
propagate – If True, the function will propagate the operation to all ‘Sea’ subobjects.

remove_tag(tag, propagate=True)¶

Removes a tag.

Parameters

tag – The given ‘tag’ can be a string, or a list of strings, or a ‘set’ of strings.
propagate – If True, the function will propagate the operation to all ‘Sea’ subobjects.

reset_tag(tag, propagate=True)¶

Resets the tag of this object to the given ‘tag’.

Parameters

tag – The given ‘tag’ can be a string, or a list of strings, or a ‘set’ of strings.
propagate – If True, the function will propagate the operation to all ‘Sea’ subobjects.

clear_all_tag(propagate=True)¶

Removes all tags.

Parameters: propagate – If True, the function will propagate the operation to all ‘Sea’ subobjects.

pmode()¶: Returns the printing mode.

set_pmode(pmode, propagate=True)¶

Resets the printing mode of this object to the given ‘pmode’.

Parameters: propagate – If True, the function will propagate the operation to all ‘Sea’ subobjects.

dump(tag={})¶: Converts this ‘Sea’ object into a string that looks ugly (yet syntactically correct). This method is 50%-900% faster than the __str__ method.

class schrodinger.utils.sea.sea.Atom(s=None, type=None, parent=None)¶

Bases: schrodinger.utils.sea.sea.Sea

This class represents the “atomic” parameters in a config file. Atomic parameters do not contain further sub-elements. For example, ‘force.type’ is an atomic parameter, whereas ‘force’ is not because it has sub-elements like ‘type’, ‘gibbs’, etc.

Public attributes:

validate - None by default. This attribute can be set to be a callable object that assesses whether a given value is legal or not for this ‘Atom’ object. The callable object should be able to take one argument – the value subject to its assessment and returns either True (if the value is OK) or False (if the value is illegal).

WILDCARD_PATTERN = re.compile('\\*\\ *\\.')¶

static num_wildcard(s)¶: This function is used to tell about strings like “..keyword”. It returns a tuple object. The first element is the number of wildcards “*”, the second element is the word at the end after the ‘.’ symbol. For example: num_wildcard( “..keyword” ) will yield (2, “keyword”). See more examples in the unit tests below.

static guess_value_type(s)¶: Guesses the type of the object that ‘s’ represents. A tuple will be returned. The first element is the object of the guessed type, the second element is the type. If ‘s’ is a non-str object of buildin type, ‘s’ and its type will be returned. If ‘s’ is str object, the type of the object that the string represents will be guessed and the string will be converted to an object of the guessed type. Note these strings: “yes”, “true”, “on”, “no”, “false”, and “off” will be considered as bool type of objects. If ‘s’ is None, (None, None) will be returned. If ‘s’ is of other types than the above, a ValueError exception will be returned.

__init__(s=None, type=None, parent=None)¶

Constructs a ‘Atom’ object based on the value ‘s’.

Parameters

s – Can be a floating number, a boolean value, an integer number, or a string. If ‘s’ is a string. the function will try to guess the type of object that the string represents and convert the string to the guessed type. ‘s’ cannot be a dict, or tuple, or dict object.
type – Supplies a type, instead of using the guessed one. If it is None, the guessed type will be used.
parent – Specifies the parent of this ‘Atom’ object.

property raw_val¶: Readwrite. When read, this returns the raw value.

property sval¶: Readonly. Returns the dereferenced Sea object.

property bval¶: Readonly. Returns a new Atom object, which has all macros expanded and references dereferenced.

property dval¶: Readonly. Returns a new Atom object with dereferenced value.

property val¶: Readwrite. When read, this returns the current value.

update(val, tag={})¶

Updates the value with ‘val’. If ‘val’ is a Atom, then this Atom object will be altered to be the same as ‘val’. So the type of the value of this object can be altered by the update function. If ‘val’ is not a Atom, then this function will behave exactly the same as setting the value via the ‘val’ property.

Parameters

val – Can be any object as long as it can be converted to the internal type of the value via the _convert method. If ‘val’ cannot be converted, it is ignored.
tag – Add the tag to this object.

class schrodinger.utils.sea.sea.Hydrogen(s, type, parent=None)¶

Bases: schrodinger.utils.sea.sea.Atom

__init__(s, type, parent=None)¶: Just a slightly faster way to construct a ‘Atom’ object

class schrodinger.utils.sea.sea.List(val=[], parent=None)¶

Bases: schrodinger.utils.sea.sea.Sea, list

This class represents the “list” parameters in a config file. This class’ behavior is very similar to that of the buildin list class.

__init__(val=[], parent=None)¶

Constructs a List object from the given ‘val’.

Parameters

val – Must be either a list or tuple. The elements must be of either buildin types or Sea.
parent – Specifies the parent of this List object.

__contains__(item)¶: Return key in self.

property raw_val¶: Readwrite. When read, this returns the current value.

property bval¶: Readonly. Returns a new List object, which has all macros expanded and references dereferenced.

property dval¶: Readonly. Returns a new List object dereferenced values.

property val¶: Readwrite. When read, this returns the current value.

append(val)¶: Appends the given value ‘val’ to this list.

quick_append(val)¶: Appends the given value ‘val’ to this list.

extend(val_list)¶: Extends this list with the given list or tuple ‘val_list’.

insert(index, val)¶: Inserts the given value ‘val’ to the ‘index’-th position in the list.

pop(index=- 1)¶: Removes the ‘index’-th element from the list and returns the removed element. The parent of the returned element will be set to None.

index(obj, **kwargs)¶

Return first index of value.

Raises ValueError if the value is not present.

apply(op)¶: Recursively applies the operation as given by ‘op’ to all ‘Sea’ subobjects of this ‘Sea’ object.

update(ark=None, tag={})¶

Updates this list with ‘ark’.

Parameters

ark – If ‘ark’ is None, no effects. If the first element has a string value “!append!”, the remaining elements in ‘ark’ will be appended to this list. If the first element has a string value “!removed!”, the remaining elements in ‘ark’ will be removed from this list. Otherwise, this list will be completely reset to ‘ark’.
tag – Resets the tag of this list to the given ‘tag’.

class schrodinger.utils.sea.sea.Key(key)¶

Bases: str

An instance of this class will be used as the key of the Map class (see below).

__init__(key)¶: Constructs a new Key object for the given string ‘key’.

orig_key()¶: Returns the original string.

class schrodinger.utils.sea.sea.Map(ark={}, parent=None)¶

Bases: schrodinger.utils.sea.sea.Sea

This class represents the “map” parameters in a config file. This class’ behavior is very similar to that of the buildin dict class.

INDEX_PATTERN = re.compile('([^\\[]*)\\[ *([+-]*[1234567890]*) *\\]')¶

INDEX_PATTERN2 = re.compile('\\[ *[+-]*([1234567890]*) *\\]')¶

__init__(ark={}, parent=None)¶

Constructs a ‘Map’ object with a given ‘ark’. The ‘ark’ can be of the following types of objects:

dict The ‘Map’ object will be constructed consistent with the dict object.
Map The ‘ark’ will be deep-copied.
str The string will be parsed and the ‘Map’ object will be constructed for the parsed string.
list The elements of the list object must be of the above types. A new ‘Map’ object will be constructed using the first elements, and then the ‘Map’ object will be updated with the remaining objects in the list.

If ‘ark’ is not provided, an empty ‘Map’ will be constructed.

User can optionally specify the ‘parent’ parameter, which will set the parent of this ‘Map’ object to the given value of the ‘parent’ parameter.

property raw_val¶: Readwrite. When read, this returns the current raw value (references and macros kept as is).

property bval¶: Readonly. Returns a new Map object, which has all macros expanded and references dereferenced.

property dval¶: Readonly. Returns a new Map object with dereferenced values.

property val¶: Readwrite. When read, this returns the current value (macros will be expanded, and references will be dereferenced.

keys(tag={})¶: Returns references of all keys in a list. Note each element in the returned list will be of the ‘Key’ type.

values(tag={})¶: Returns references of all values in a list. Note each element in the returned list will be of the ‘Sea’ type.

key_value(tag={}, should_sort=False)¶: Returns the key and associated value in a list. Note each element in the returned list will be a 2-tuple object. The first element of the tuple is a reference of the key, and the second element is a reference of the value. User can optionally set the ‘should_sort’ parameter to True, which will let the function return a sorted list. The sorting will be based on the alphanumeric order of ‘key’.

clone(orig)¶: Lets this ‘Map’ object become a deep copy of the ‘orig’ ‘Map’ object.

apply(op)¶: Recursively applies the operation as given by ‘op’ to all ‘Sea’ subobjects of this ‘Sea’ object.

update(ark=None, file=None, tag={})¶

Updates this ‘Map’ object with the given ‘ark’ or with the given ‘file’.

Parameters

file – If ‘file’ is not None, it must be the name of a file in the ark file format. If ‘file’ is given, the ‘ark’ parameter will be ignored.
ark – ark can be a string or a dict or a ‘Map’ object. Or ark can be list of the previous objects.

has_key(key)¶

__contains__(key)¶: Returns True if this ‘Map’ object has the ‘key’. Returns False if otherwise.

get_value(key)¶

Returns the value of the given ‘key’.

Parameters: key – The ‘key’ can be a composite key (i.e., the pathway notation), such as, e.g., “key[1][2].key2.key3[2]”.

set_value(key, value, tag={})¶

Associates the given value with the given key. The difference between this function and the __setitem__ operator is that the former allows us to reset the tag of the value.

Parameters

key – The ‘key’ can be a composite key (i.e., the pathway notation), e.g., “key[1].key2[0].key3”.
tag – If the “tag” parameter is specified, the value of ‘tag’ will be used to tag the ‘value’.

set_value_fast(key, value, tag={})¶: Similar to set_value method. The difference is that if value is a Sea object the value object itself (as opposed to a copy) will be included into this Map object after this function call, as a result, the original Sea object value might be mutated as necessary. This function is much faster than set_value.

del_key(key: str)¶

Deletes the given key from this map.

Parameters: key – The ‘key’ can be a composite key in the pathway notation, e.g., “key[1].key2[0].key3”.

schrodinger.utils.sea.sea.get_val(my_macro_dict, sea_object)¶

Returns values of the sea_object with the given macro dictionary (macro_dict).
sea_object must be a single Sea object or a sequence Sea objects.
This function does not change the global macro_dict object.

schrodinger.utils.sea.sea.diff(x, reference)¶: Returns the difference between ‘x’ and ‘reference’. Both ‘x’ and ‘reference’ must be ‘Map’ objects. The difference is a 4-tuple: The first element is a ‘Map’ object containing the changed values in ‘x’, the second element is a ‘Map’ object containing the changed value in ‘reference’, the third element is a ‘Map’ object containing keys in x but not in ‘reference’, the forth element is a ‘Map’ object containing keys in ‘reference’ but not in ‘x’.

schrodinger.utils.sea.sea.sea_filter(x, tag={})¶: Extracts a subset of keys from the ‘Map’ object ‘x’ that has the tag. And returns a new ‘Map’ object containing the extracted keys.

schrodinger.utils.sea.sea.is_atom_list(a)¶

This function returns:: True - if ‘a’ is a List object and all of its elements are instances of the ‘Atom’ class, True - if ‘a’ is a List object and is empty, False - if otherwise.