schrodinger.utils.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 as “lambda_”. The reason that we have to use “lambda_” is because ‘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.

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

Bases: schrodinger.utils.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 = <_sre.SRE_Pattern object>¶

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

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

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.

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.

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

sval¶: Readonly. Returns the dereferenced Sea object.

update(val, tag=set([]))¶

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.

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

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

class schrodinger.utils.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.List(val=[], parent=None)¶

Bases: schrodinger.utils.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.

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

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

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

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

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.

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

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

update(ark=None, tag=set([]))¶

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’.

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

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

Bases: schrodinger.utils.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 = <_sre.SRE_Pattern object>¶

INDEX_PATTERN2 = <_sre.SRE_Pattern object>¶

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

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

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

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

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]”.

has_key(key)¶

key_value(tag=set([]), 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’.

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

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

set_value(key, value, tag=set([]))¶

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’.

update(ark=None, file=None, tag=set([]))¶

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.

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

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

class schrodinger.utils.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.

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.

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

clear_all_tag(propagate=True)¶

Removes all tags.

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

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

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.

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

pmode()¶: Returns the printing mode.

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.

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

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.

sval¶: Readonly. Returns the current Sea object.

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

schrodinger.utils.sea.asea_copy(src, des)¶: Copies all keys and the associated values in the ‘Map’ object ‘src’ to the ‘Map’ object ‘des’, but does not change the parent and pmode of the ‘des’.

schrodinger.utils.sea.boolean(s)¶

Returns True if the string ‘s’ is one of the following: ‘true’, ‘yes’, and ‘on’, or False if it is one of the following: ‘false’, ‘no’, and ‘off’.

Case difference will be ignored.

Raises a ValueError exception if ‘s’ is none of the above strings.

schrodinger.utils.sea.check_map(map, valid, ev, tag=set([]))¶: Checks the validity of a map.

schrodinger.utils.sea.check_map2(map, valid, tag=set([]))¶: Similiar to the ‘check_map’ function (see above), but no need to provide a ‘_Evalor’ object. A new ‘_Evalor’ object will be created and returned.

schrodinger.utils.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.expand_ark_string(my_ark, scope='')¶

schrodinger.utils.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.

schrodinger.utils.sea.expand_macro_old(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.

schrodinger.utils.sea.expand_sea_string(my_sea, scope='')¶

expand_sea return an expanded string of a sea obj. For instance, after calling expand_sea_string

eneseq ={
  name = foo.ene
  first = 0
}

is converted into

eneseq.name = "foo.ene"
eneseq.first = 0

schrodinger.utils.sea.filter(x, tag=set([]))¶: 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.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.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.

schrodinger.utils.sea.is_equal(a, b, epsilon=1e-06)¶: Compares two floating numbers and returns True if the absolute difference is within epsilon (defaults to 1E-6), False if not.

schrodinger.utils.sea.is_powerof2(x)¶: Returns True if ‘x’ is a power of 2, or False otherwise.

schrodinger.utils.sea.pathname(x)¶: Given a ‘Map’ object ‘x’, returns its pathname.

schrodinger.utils.sea.reg_xcheck(name, func)¶

Registers external checker.

Parameters:	name – Name of the checker. func – Callable object that checks validity of a parameter. For interface requirement, see ‘_xchk_power2’, or ‘_xchk_file_exists’, or ‘_xchk_dir_exists’ for example.

schrodinger.utils.sea.test()¶: Unit test.

Previous topic

Next topic

schrodinger.utils.sea module¶