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.
Copyright Schrodinger, LLC. All rights reserved.
- 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.
- 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 bval¶
Readonly. Returns a new
Atom
object, which has all macros expanded and references dereferenced.
- property val¶
Readwrite. When read, this returns the current value.
- update(val, tag={})¶
Updates the value with ‘val’. If ‘val’ is a
Atom
, then thisAtom
object will be altered to be the same as ‘val’. So the type of the value of this object can be altered by theupdate
function. If ‘val’ is not aAtom
, 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.- __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 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).- 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.
- pop(key, default=None)¶
Removes a key and returns associated value, if key is not found returns default.
- 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 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 ifvalue
is aSea
object thevalue
object itself (as opposed to a copy) will be included into thisMap
object after this function call, as a result, the originalSea
objectvalue
might be mutated as necessary. This function is much faster thanset_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)¶
- 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.