utilities Package

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.
  • Simple to allow a superclass define all the serializations for its subclasses, removing code repetition
  • 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.

The FW serialization is compatible with pymatgen’s MSONable interface when the serialize_fw decorator is used on the to_dict() methods.

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='AUTO_DETECT')

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
classmethod to_dict()
to_file(filename, f_format='AUTO_DETECT')

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

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='AUTO_DETECT')

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.serialize_fw(func)

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

fw_utilities Module

fireworks.utilities.fw_utilities.get_fw_logger(name, l_dir='.', file_levels=('DEBUG', 'ERROR'), stream_level='DEBUG', formatter=<logging.Formatter object at 0x10721ad10>, 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.log_exception(m_logger, msgs)

A shortcut wrapper around log_fancy for exceptions :param m_logger: The logger object :param msgs: An iterable of Strings, will be joined by newlines

fireworks.utilities.fw_utilities.log_fancy(m_logger, log_lvl, msgs, add_traceback=False)

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

Parameters:
  • m_logger – The logger object
  • log_lvl – The level to log at
  • msgs – a String or iterable of Strings
  • add_traceback – add traceback text, useful when logging exceptions (default False)

Table Of Contents

This Page