openmmtools.storage.storageinterface.StorageInterfaceDirVar

class openmmtools.storage.storageinterface.StorageInterfaceDirVar(name, storage_interface, predecessor=None)

Storage Interface Directory/Variable (SIDV) class is a versatile, dynamic class which gives structure to the variables stored on disk by representing them as methods of the StorageInterface and other instances of itself. New variables and folders are created by simply trying to use them as properties of the class itself. The data stored and read is not kept in memory, the SIDV passes the data onto the writer or tells the fetcher to read from disk on demand.

The API only shows the protected and internal methods of the SIDV class which cannot be used for variable and directory names.

This class is NEVER meant to be used as its own object and should never be invoked by itself. The class is currently housed outside of the main StorageInterface class to show the API to users.

Examples are located in the StorageInterface main class

TODO: Move this class as an internal class of StorageInterface (NOT a subclass)

Attributes:

bound_target

Fetch the handler for the bound target, either the directory or the variable so that the user can directly manipulate the handler has they need.

directory

Checks if the object can be used as a directory for accepting other SIDV objects.

name

Pointer to this directory or variable as it will appear on the disk

path

Generate the complete path of this instance by getting its predecessor’s path + itself.

predecessor

Give the parent SIDV to construct the full path on the way down

variable

Checks if the object can be used in the .write, .append, .read functions can be used.

Methods

add_metadata(name, data)	Attempt to add metadata to the variable/directory.
append(data)	Write data to a variable whose size changes every time this function is called.
read()	Read the variable and its data from disk.
write(data[, at_index])	Write data to a variable which cannot be appended to or write data at a specific index of an appendable variable.

__init__(name, storage_interface, predecessor=None)

Parameters:

name : string

Specify the name of the storage variable on the disk. Full path is determined from the predecessor chain

storage_interface : StorageInterface instance

Acting interface which is handling top level IO operations on the file itself The storage driver which handles all the commands is derived from this interface

predecessor : StorageInterfaceDirVar

Directory-like SIDV above this instance

Methods

__init__(name, storage_interface[, predecessor])	Parameters:
add_metadata(name, data)	Attempt to add metadata to the variable/directory.
append(data)	Write data to a variable whose size changes every time this function is called.
read()	Read the variable and its data from disk.
write(data[, at_index])	Write data to a variable which cannot be appended to or write data at a specific index of an appendable variable.

Attributes

bound_target	Fetch the handler for the bound target, either the directory or the variable so that the user can directly manipulate the handler has they need.
directory	Checks if the object can be used as a directory for accepting other SIDV objects.
name	Pointer to this directory or variable as it will appear on the disk
path	Generate the complete path of this instance by getting its predecessor’s path + itself.
predecessor	Give the parent SIDV to construct the full path on the way down
variable	Checks if the object can be used in the .write, .append, .read functions can be used.

add_metadata(name, data)

Attempt to add metadata to the variable/directory. Usually a string input to include additional information about the variable.

Because this can act on DIRECTORY or VARIABLE types, all metadata is buffered until this instance of SIDV is bound to an object on the file itself.

This does not check if the metadata already exists and simply overwrites it if present.

Parameters:

name : string

Name of the metadata variable. Since this is data we are directly attaching to the variable or directory itself, we do not make this another SIDV instance.

data: What data you wish to attach to the `name`d metadata pointer.

append(data)

Write data to a variable whose size changes every time this function is called. The first dimension of the variable on disk will be appended with data after checking the size. If no variable exists, one is created with a dynamic variable size for its first dimension, then the other dimensions are inferred from the data.

This method raises an error if this instance of SIDV is DIRECTORY

Parameters:

data : any data type

This is what will be written to disk, the data will be processed by the STORAGESYSTEM as to how to actually handle the data once the units have been stripped out and assigned to this instance of SIDV.

Examples

Store a single int several times in a variable that is inside a directory >>> my_driver = NetCDFIODriver(‘my_store.nc’) >>> my_store = StorageInterface(my_driver) >>> x = 756 >>> my_store.IAmADir.AnInt.append(x) >>> my_store.IAmADir.AnInt.append(x+1) >>> my_store.IAmADir.AnInt.append(x+2)

bound_target

Fetch the handler for the bound target, either the directory or the variable so that the user can directly manipulate the handler has they need.

Returns:

handler : bound handler of the storage_driver’s variable or None

returns None if the target is not bound

directory

Checks if the object can be used as a directory for accepting other SIDV objects. Once this is True or bound, the .write, .append, and .read functions are locked out.

Returns:

directory_pointer : None, True, or storage_driver specific directory of storage

Returns None if this instance is a variable, or if its functionality has not been determined yet. Returns True if this SIDV will be a directory, but is not yet bound. i.e. has additional SIDV children spawned by __getattr__ method. Returns the storage_driver specific directory that this instance is bound to once assigned

name

Pointer to this directory or variable as it will appear on the disk

Returns:

name : string

path

Generate the complete path of this instance by getting its predecessor’s path + itself. This is a cascading function up the stack of SIDV’s until the top level attached to the main SI instance is reached, then reassembled on the way down.

Returns:

full_path : string

The complete path of this variable as it is seen on the storage file_name, returned as / separated values.

predecessor

Give the parent SIDV to construct the full path on the way down

Returns:

predecessor : None or StorageInterfaceDirVar instance

Returns this instance’s parent SIDV instance or None if it is the top level SIDV.

read()

Read the variable and its data from disk.

If this instance is unbound to an object in the storage_handler or is DIRECTORY, then this method raises an error.

Returns:

data

Data stored on VARIABLE read from disk and processed through the STORAGESYSTEM back into a Python type and possibly through the UNIT logic to recast into Quantity before being handed to the user.

variable

Checks if the object can be used in the .write, .append, .read functions can be used. Once this is set, this instance cannot be converted to a directory type.

Returns:

variable_pointer : None or storage_driver specific unit of storage

Returns None if this instance is a directory, or if its functionality has not been determined yet (this includes the variable not being assigned yet). Returns the storage_driver specific variable that this instance is bound to once assigned

write(data, at_index=None)

Write data to a variable which cannot be appended to or write data at a specific index of an appendable variable. This method is typically called when you do not want the value stored to change. The at_index flag should be an integer to specify that the appendable variable that this is should overwrite the data at the specific index.

This method raises an error if this instance of SIDV is DIRECTORY

Parameters:

data

This is what will be written to disk, the data will be processed by the STORAGESYSTEM as to how to actually handle the data once the units have been stripped out and assigned to this instance of SIDV.

at_index : int or None, default None

Change the behavior or “write” to act on an appendable variable instead Replace the data at the specific index of at_index with data Checks for compatible data should be/are handled at the storage_driver level

Examples

Store a numpy “eye” array to the variable “my_arr” >>> import numpy as np >>> my_driver = NetCDFIODriver(‘my_store.nc’) >>> my_store = StorageInterface(my_driver) >>> x = np.eye(3) >>> my_store.my_arr.write(x)

Save 2 entries of a list, then update the frist >>> my_driver = NetCDFIODriver(‘my_store.nc’) >>> my_store = StorageInterface(my_driver) >>> x = [0,0,1] >>> my_store.the_list.append(x) >>> my_store.the_list.append(x) >>> y = [1,1,1] >>> my_store.the_list.write(y, at_index=0)