Package schrodinger :: Package utils :: Module sea

Module sea


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.
  
Copyright Schrodinger, LLC. All rights reserved.

Classes

[hide private]

Sea
This is the base class the 'Atom', 'List', and 'Map' classes.

Atom
This class represents the "atomic" parameters in a config file.

Hydrogen

List
This class represents the "list" parameters in a config file.

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

Map
This class represents the "map" parameters in a config file.

_Evalor
This is the evaluator class for checking validity of parameters.

Functions

[hide private]

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.

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

_debug_print(s, nl=True)
Prints out some information for debugging purposes.

_val_filter(val)
Filters a given value 'val' and returns a new 'Sea' (or its derivatives) object representing the value.

_list_filter(val_list)
Returns a 'List' object for the given list of objects.

_escape_dollar(s)
This function is needed by the 'expand_macro' function below.

_escape_dollar2(s)
This function is needed by the 'expand_macro' function below.

_strip_bracket(s)
Mutates a given string 's' by following the following rules: 1.

_strip_bracket2(s)
Mutates a given string 's' by following the following rules: 1.

expand_macro_old(s, macro_dict)
Replaces the macros in the string 's' using the values given by the macro dictionary 'macro_dict'.

expand_macro(s, macro_dict)
Replaces the macros in the string 's' using the values given by the macro dictionary 'macro_dict'.

get_val(my_macro_dict, sea_object)
Returns values of the `sea_object' with the given macro dictionary (`macro_dict').

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

pathname(x)
Given a 'Map' object 'x', returns its pathname.

diff(x, reference)
Returns the difference between 'x' and 'reference'.

filter(x, tag=set([]))
Extracts a subset of keys from the 'Map' object 'x' that has the tag.

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.

expand_sea_string(my_sea, scope='')
expand_sea return an expanded string of a sea obj.

expand_ark_string(my_ark, scope='')

__op_mul(map, arg)
Evaluates the "multiplication" expression and returns product of the arg[0], arg[1], arg[3], ...

__op_eq(map, arg)
Evaluates the "equal" expression and returns True the arg[0] and arg[1] are equal or False otherwise.

__op_lt(map, arg)
Evaluates the "less than" expression and returns True the arg[0] is less than arg[1] or False otherwise.

__op_le(map, arg)
Evaluates the "less or equal" expression and returns True the arg[0] is less than or equal to arg[1] or False otherwise.

__op_gt(map, arg)
Evaluates the "greater than" expression and returns True the arg[0] is greater than arg[1] or False otherwise.

__op_ge(map, arg)
Evaluates the "greater or equal" expression and returns True the arg[0] is greater than or equal to arg[1] or False otherwise.

__op_and(map, arg)
Evaluates the "logic and" expression and returns True if both arg[0] and arg[1] are true.

__op_or(map, arg)
Evaluates the "logic or" expression and returns True if either arg[0] or arg[1] is true.

__op_not(map, arg)
Evaluates the "logic not" expression and returns True if arg[0] is false or False if arg[0] is true.

__op_at(map, arg)
Evaluates the "at" expression and returns the referenced value.

__op_minus(map, arg)
Evaluates the "minus" expression and returns arithmatic result (the difference between two values, or the negative value).

__op_cat(map, arg)
Contatenate two strings and returns the result.

__op_sizeof(map, arg)
Evaluates the "less than" expression and returns True the arg[0] is less than arg[1] or False otherwise.

is_powerof2(x)
Returns True if 'x' is a power of 2, or False otherwise.

_xchk_power2(map, valid, ev, prefix)
This is an external checker.

_xchk_file_exists(map, valid, ev, prefix)
This is an external checker.

_xchk_dir_exists(map, valid, ev, prefix)
This is an external checker.

_eval(map, arg)
Evaluates the expression and returns the results.

reg_xcheck(name, func)
Registers external checker.

_match(map, valid, ev, prefix, tag)
Finds the best match.

_check_atom(atom, valid, ev, prefix)
Checks the validity of atom.

_check_list(map, valid, ev, prefix, tag)
Checks the validity of list.

_check_map(map, valid, ev, prefix='', tag=set([]))
Checks the validity of a map.

check_map(map, valid, ev, tag=set([]))
Checks the validity of a map.

check_map2(map, valid, tag=set([]))
Similiar to the 'check_map' function (see above), but no need to provide a '_Evalor' object.

test()
Unit test.

Variables

[hide private]

__CHECK_SEA_DEBUG = False
hash(x)

__debug_str_buf = ''

macro_dict = {}

_STRIP_BRACKET_PATTERN = re.compile(r'\x00\[[^\[]*?\$[^\]]*?\x...

__OP = {"*": __op_mul, "==": __op_eq, "<": __op_lt, "<=": __op...

__TYPE = {"str": str, "str1":(str, [1, 1000000000],), "float":...

__CONVERTIBLE_TO = {<type 'float'>: [<type 'str'>], <type 'int...

__xcheck = {"power2": _xchk_power2, "file_exists": _xchk_file_...

__package__ = 'schrodinger.utils'

Function Details

[hide private]

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.

_debug_print(s, nl=True)

Prints out some information for debugging purposes.

Parameters:

s - The string to print.
nl - Appends a new line to the string and flushes out the current contents in the print buffer.

_val_filter(val)

Filters a given value 'val' and returns a new 'Sea' (or its derivatives) object representing the value.

Parameters:

val - This object can be of the following types:
- 'Sea' or derivative: This function will just return a deep copy of 'val'
- list or tuple: This function will return a 'List' (see below) object.
- Other non dict types: This function will return a 'Atom' (see below) object.

_list_filter(val_list)

Returns a 'List' object for the given list of objects. Usually, we do not need to call this function directly. Call '_val_filter' instead.

Parameters:

val_list - This should be either a list or a tuple object. The elements of the list or tuple can be of any type.

_escape_dollar(s)


This function is needed by the 'expand_macro' function below.
It replaces dollar char '$' as in the following cases:
   $$, $[, $]
in a string with the '' char. The results for these cases will be the
following:
   , [, ]
respectively.

_escape_dollar2(s)


This function is needed by the 'expand_macro' function below.
It replaces dollar char '$' as in the following cases:
   $$, $[, $]
in a string with the '' char. The results for these cases will be the
following:
   , [, ]
respectively.

_strip_bracket(s)


Mutates a given string 's' by following the following rules:
1. If there is a dollar sign '$' within a fragment of string that is
   delimited by '[' and ']', the entire fragment including the
   '[' and ']' delimiters will be removed.
2. If there is no dollar sign within the fragment, then the fragment will
   be retained, and only the delimiters will be removed.
Examples:
  _strip_bracket( "desmond[_$JOBNAME]" ) # Returns "desmond"
  _strip_bracket( "desmond[_jobname]" )  # Returns "desmond_jobname"

This function is usually used together with the '_escape_dollar' function
in the 'expand_macro' function (see below).

_strip_bracket2(s)


Mutates a given string 's' by following the following rules:
1. If there is a dollar sign '$' within a fragment of string that is
   delimited by '[' and ']', the entire fragment including the
   '[' and ']' delimiters will be removed.
2. If there is no dollar sign within the fragment, then the fragment will
   be retained, and only the delimiters will be removed.
Examples:
  _strip_bracket( "desmond[_$JOBNAME]" ) # Returns "desmond"
  _strip_bracket( "desmond[_jobname]" )  # Returns "desmond_jobname"

This function is usually used together with the '_escape_dollar' function
in the 'expand_macro' function (see below).

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.

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.

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

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.

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

__op_mul(map, arg)

Evaluates the "multiplication" expression and returns product of the arg[0], arg[1], arg[3], ...

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two or more elements.
map - The original map that the elements in the 'arg' refer.

__op_eq(map, arg)

Evaluates the "equal" expression and returns True the arg[0] and arg[1] are equal or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_lt(map, arg)

Evaluates the "less than" expression and returns True the arg[0] is less than arg[1] or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_le(map, arg)

Evaluates the "less or equal" expression and returns True the arg[0] is less than or equal to arg[1] or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_gt(map, arg)

Evaluates the "greater than" expression and returns True the arg[0] is greater than arg[1] or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_ge(map, arg)

Evaluates the "greater or equal" expression and returns True the arg[0] is greater than or equal to arg[1] or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_and(map, arg)

Evaluates the "logic and" expression and returns True if both arg[0] and arg[1] are true.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_or(map, arg)

Evaluates the "logic or" expression and returns True if either arg[0] or arg[1] is true.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

__op_not(map, arg)

Evaluates the "logic not" expression and returns True if arg[0] is false or False if arg[0] is true.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contain only 1 element. More than 1 elements will cause a 'ValueError' exception.
map - The original map that the elements in the 'arg' refer.

__op_at(map, arg)

Evaluates the "at" expression and returns the referenced value.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contain only 1 element. More than 1 elements will cause a 'ValueError' exception.
map - The original map that the elements in the 'arg' refer.

__op_minus(map, arg)

Evaluates the "minus" expression and returns arithmatic result (the difference between two values, or the negative value).

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains at most two elements. More than two elements will cause a 'ValueError' exception.
map - The original map that the elements in the 'arg' refer.

__op_cat(map, arg)

Contatenate two strings and returns the result.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains at least 1 elements.
map - The original map that the elements in the 'arg' refer.

__op_sizeof(map, arg)

Evaluates the "less than" expression and returns True the arg[0] is less than arg[1] or False otherwise.

Parameters:

arg - The 'arg' should be a 'sea.List' object that contains two elements. Elements beyond the first two will be ignored.
map - The original map that the elements in the 'arg' refer.

_xchk_power2(map, valid, ev, prefix)

This is an external checker. It checks whether an integer value is power of 2 or not.

Parameters:

map - 'map' contains the value to be checked. Use 'map.val' to get the value.
valid - 'valid' contains the validation criteria for the to-be-checked value.
ev - The evaluator, where the error messeages are collected.
prefix - The prefix of the checked parameter.

_xchk_file_exists(map, valid, ev, prefix)

This is an external checker. It checks whether a file (not a dir) exists.

Parameters:

map - 'map' contains the value to be checked. Use 'map.val' to get the valuefile name.
valid - 'valid' contains the validation criteria for the to-be-checked value.
ev - The evaluator, where the error messeages are collected.
prefix - The prefix of the checked parameter.

_xchk_dir_exists(map, valid, ev, prefix)

This is an external checker. It checks whether a dir (not a file) exists.

Parameters:

map - 'map' contains the value to be checked. Use 'map.val' to get the valuefile name.
valid - 'valid' contains the validation criteria for the to-be-checked value.
ev - The evaluator, where the error messeages are collected.
prefix - The prefix of the checked parameter.

_eval(map, arg)

Evaluates the expression and returns the results.

Parameters:

arg - 'arg' can be either a 'sea.List' object or a 'sea.Atom' object, representing a prefix expression.
map - The original map that the elements in the 'arg' refer.

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.

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.

Variables Details

[hide private]

_STRIP_BRACKET_PATTERN

Value:

re.compile(r'\x00\[[^\[]*?\$[^\]]*?\x00\]')

__OP

Value:

{"*": __op_mul, "==": __op_eq, "<": __op_lt, "<=": __op_le, ">": __op_
gt, ">=": __op_gt, "&&": __op_and, "||": __op_or, "!": __op_not, "@": 
__op_at, "-": __op_minus, "cat": __op_cat, "sizeof": __op_sizeof,}

__TYPE

Value:

{'bool': <function boolean at 0x103c9e60>,
 'bool0': (<function boolean at 0x103c9e60>, [False]),
 'bool1': (<function boolean at 0x103c9e60>, [True]),
 'enum': <type 'str'>,
 'float': <type 'float'>,
 'float+': (<type 'float'>, [0, inf]),
 'float-': (<type 'float'>, [-inf, 0]),
 'float0_1': (<type 'float'>, [0, 1.0]),
...

__CONVERTIBLE_TO

Value:

{<type 'float'>: [<type 'str'>],
 <type 'int'>: [<type 'float'>, <type 'str'>]}

__xcheck

Value:

{"power2": _xchk_power2, "file_exists": _xchk_file_exists, "dir_exists
": _xchk_dir_exists,}

Module sea

boolean(s)

_debug_print(s, nl=True)

_val_filter(val)

_list_filter(val_list)

_escape_dollar(s)

_escape_dollar2(s)

_strip_bracket(s)

_strip_bracket2(s)

expand_macro_old(s, macro_dict)

expand_macro(s, macro_dict)

diff(x, reference)

filter(x, tag=set([]))

expand_sea_string(my_sea, scope='')

__op_mul(map, arg)

__op_eq(map, arg)

__op_lt(map, arg)

__op_le(map, arg)

__op_gt(map, arg)

__op_ge(map, arg)

__op_and(map, arg)

__op_or(map, arg)

__op_not(map, arg)

__op_at(map, arg)

__op_minus(map, arg)

__op_cat(map, arg)

__op_sizeof(map, arg)

_xchk_power2(map, valid, ev, prefix)

_xchk_file_exists(map, valid, ev, prefix)

_xchk_dir_exists(map, valid, ev, prefix)

_eval(map, arg)

reg_xcheck(name, func)

check_map2(map, valid, tag=set([]))

_STRIP_BRACKET_PATTERN

__OP

__TYPE

__CONVERTIBLE_TO

__xcheck

filter(x, tag=`set([])`)

expand_sea_string(my_sea, scope=`''`)

check_map2(map, valid, tag=`set([])`)