utilities Package

dict_mods Module

This module allows you to modify a dict (a spec) using another dict (an instruction). The main method of interest is apply_dictmod().

This code is based heavily on the Ansible class of custodian <https://pypi.python.org/pypi/custodian>, but simplifies it considerably for the limited use cases required by FireWorks.

fireworks.utilities.dict_mods.apply_mod(modification, obj)

Note that modify makes actual in-place modifications. It does not return a copy.

Args:
modification:
Modification must be {action_keyword : settings}, where action_keyword is a supported DictMod
obj:
A dict to be modified
fireworks.utilities.dict_mods.get_nested_dict(input_dict, key)

fw_serializers Module

This module aids in serializing and deserializing objects.

To serialize a FW object, refer to the documentation for the FWSerializable class. To de-serialize an object, refer to the documentation for the FWSerializable class and load_object() method.

  • you can de-serialize explicitly, e.g. FWObject.from_dict() to enforce a FWObject instance as the result
  • you can de-serialize implicitly, e.g. load_object() to search for the correct Class dynamically

The implicit method is especially useful if you don’t know in advance which subclass of a base class your serialization might point to. e.g. if you require some type of Quadrilateral, a serialization from your collaborator might point to a Square, Rhombus, or Rectangle, and you might not know which one in advance...

Some advantages:
  • Robust with regard to code refactorings even in implicit loading given certain reasonable guidelines on fw_name.
  • Simple to allow a superclass to define all the serializations for its subclasses, removing code repetition

(in particular, note that from_dict is a class method rather than a static method, allowing use of self) - Decorators aid in some of the routine parts of the serialization, such as adding the _fw_name key - Both JSON and YAML file import/export are naturally and concisely supported within the framework. - Auto-detect and proper loading of JSON and YAML files - Proper JSON handling of datetime (both encoding and decoding) and UTF-8 strings - In some cases, objects can be serialized/deserialized extremely concisely, by use of only their fw_name (if no parameters are needed to describe the object)

A dict created using FWSerializer’s to_dict() method should be readable by Pymatgen’s PMGDecoder, when the serialize_fw() decorator is used.

fireworks.utilities.fw_serializers.DATETIME_HANDLER(obj)
class fireworks.utilities.fw_serializers.FWSerializable

To create a serializable object within FireWorks, you should subclass this class and implement the to_dict() and from_dict() methods.

If you want the load_object() implicit de-serialization to work, you must also:
  • Use the @serialize_fw decorator on to_dict()
  • Override the _fw_name parameter with a unique key.

See documentation of load_object() for more details.

The use of @classmethod for from_dict allows you to define a superclass that implements the to_dict() and from_dict() for all its subclasses.

For an example of serialization, see the class QueueAdapterBase.

classmethod from_dict(m_dict)
classmethod from_file(filename, f_format=None)

Load a serialization of this object from a file :param filename: filename to read :param f_format: serialization format, default checks the filename extension

classmethod from_format(f_str, f_format='json')

convert from a String representation to its Object :param f_str: the String representation :param f_format: serialization format of the String (default json)

fw_name
to_db_dict()
to_dict()
to_file(filename, f_format=None, **kwargs)

Write a serialization of this object to a file :param filename: filename to write to :param f_format: serialization format, default checks the filename extension

to_format(f_format='json', **kwargs)

returns a String representation in the given format :param f_format: the format to output to (default json)

fireworks.utilities.fw_serializers.load_object(obj_dict)

Creates an instantiation of a class based on a dictionary representation. We implicitly determine the Class through introspection along with information in the dictionary.

We search for a class with the _fw_name property equal to obj_dict[‘_fw_name’] If the @module key is set, that module is checked first for a matching class to improve speed of lookup. Afterwards, the modules in the USER_PACKAGES global parameter are checked.

Refactoring class names, module names, etc. will not break object loading as long as:

  1. the _fw_name property is maintained the same AND
  2. the refactored module is kept within USER_PACKAGES

You can get around these limitations if you really want: i) If you want to change the fw_name of an object you can set the FW_NAME_UPDATES key ii) If you want to put a refactored module in a new place add an entry to USER_PACKAGES

Parameters:obj_dict – the dict representation of the class
fireworks.utilities.fw_serializers.load_object_from_file(filename, f_format=None)

implicitly load an object from a file. just a friendly wrapper to load_object()

Parameters:
  • filename – the filename to load an object from
  • f_format – the serialization format (default is auto-detect based on filename extension)
fireworks.utilities.fw_serializers.recursive_deserialize(func)

a decorator to add FW serializations keys see documentation of FWSerializable for more details

fireworks.utilities.fw_serializers.recursive_serialize(func)

a decorator to add FW serializations keys see documentation of FWSerializable for more details

fireworks.utilities.fw_serializers.serialize_fw(func)

a decorator to add FW serializations keys see documentation of FWSerializable for more details

fw_utilities Module

class fireworks.utilities.fw_utilities.DataServer(address=None, authkey=None, serializer='pickle')

Bases: multiprocessing.managers.BaseManager

Provide a server that can host shared objects between multiprocessing Processes (that normally can’t share data). For example, a common LaunchPad is shared between processes and pinging launches is coordinated to limit DB hits.

classmethod setup(launchpad)
Parameters:launchpad – (LaunchPad) object
Returns:
fireworks.utilities.fw_utilities.acquire_db_lock()

Acquire lock on database

fireworks.utilities.fw_utilities.create_datestamp_dir(root_dir, l_logger, prefix='block_')

Internal method to create a new block or launcher directory. The dir name is based on the time and the FW_BLOCK_FORMAT

Parameters:
  • root_dir – directory to create the new dir in
  • l_logger – the logger to use
  • prefix – the prefix for the new dir, default=”block_
fireworks.utilities.fw_utilities.get_fw_logger(name, l_dir=None, file_levels=('DEBUG', 'ERROR'), stream_level='DEBUG', formatter=<logging.Formatter object at 0x10f6fb710>, clear_logs=False)

Convenience method to return a logger.

Parameters:
  • name – name of the logger that sets the groups, e.g. ‘group1.set2’
  • l_dir – the directory to put the log file
  • file_levels – iterable describing level(s) to log to file(s). default: (‘DEBUG’, ‘ERROR’)
  • stream_level – level to log to standard output. default: ‘DEBUG’
  • formatter – logging format. default: FW_LOGGING_FORMATTER
  • clear_logs – whether to clear the logger with the same name
fireworks.utilities.fw_utilities.get_my_host()
fireworks.utilities.fw_utilities.get_my_ip()
fireworks.utilities.fw_utilities.get_slug(m_str)
fireworks.utilities.fw_utilities.log_exception(m_logger, msgs)

A shortcut wrapper around log_fancy for exceptions

Parameters:
  • m_logger – (logger) The logger object
  • msgs – ([str]) String or iterable of Strings, will be joined by newlines
fireworks.utilities.fw_utilities.log_fancy(m_logger, msgs, log_lvl='info', add_traceback=False)

A wrapper around the logger messages useful for multi-line logs. Helps to group log messages by adding a fancy border around it, which enhances readability of log lines meant to be read as a unit.

Parameters:
  • m_logger – (logger) The logger object
  • log_lvl – (str) The level to log at
  • msgs – ([str]) a String or iterable of Strings
  • add_traceback – (bool) add traceback text, useful when logging exceptions (default False)
fireworks.utilities.fw_utilities.log_multi(m_logger, msg, log_lvl='info')
Parameters:
  • m_logger – (logger) The logger object
  • msg – (str) a String to log
  • log_lvl – (str) The level to log at
fireworks.utilities.fw_utilities.release_db_lock(safe=True)

Release lock on database :param safe: (bool) ignore errors (e.g., lock never acquired)

Table Of Contents

This Page