EasyScience Base Classes

[damskii9992]

General

Base classes in EasyScience are developed to provide functionality which is shared among objects, such as serialization/de-serialization to dictionaries and unique_names ids.

Some functionality is shared among all (non-special) objects, this functionality is implemented in the NewBase class which is the root base class of EasyScience.
Other functionality is only shared among certain technique-library classes, one such example are all Model-type classes which handle Parameter attributes. The functionality to handle Parameter attributes is implemented in the ModelBase class which itself inherits from the NewBase class.

NewBase

This class will be renamed in the future, when we have properly switched to the new classes.
NewBase is the root base class of EasyScience and thus inherits from no other classes. It adds serialization/de-serialization to dictionary functionality to classes using the SerializerBase classs' static methods. Specifically it adds 3 methods:

def _arg_spec(self) -> Set[str]:
    spec = getfullargspec(self.__class__.__init__)
    names = set(spec.args[1:])
    return names

Which is needed for the SerializerBase class to serialize the NewBase class. The SerializerBase (which should be renamed), is a class with static methods which holds logic for generic serialization/deserialization. In EasyScience, serialization is handed by the to_dict method:

def to_dict(self, skip=None) -> Dict[str, Any]:
return SerializerBase._convert_to_dict(self, skip=skip)

Which serializes the class to a dictionary. For serialization to JSON or other formats, this dictionary can then be re-serialized. Deserialization is handled by the from_dict method, which by default uses the generic deserialization of the SerializerBase class. Inherited classes should then overwrite this method for custom deserialization.

@classmethod
def from_dict(cls, obj_dict) -> None:
    if not SerializerBase._is_serialized_easyscience_object(obj_dict):
        raise ValueError('Input must be a dictionary representing an EasyScience object.')
    kwargs = SerializerBase.deserialize_dict(obj_dict)
    return cls(**kwargs)

Additionally, the NewBase class implements the unique_name attribute and the logic to the global_object map (see #29), as well as the optional display_name attribute.

Finally the class implements the dunder methods:

• __dir__
• __copy__
• __deepcopy__
• __repr__

ModelBase

This class inherits from NewBase and adds functionality for Variable (Parameters and Descriptors) attributes which are modifiable for the user but not replaceable. This is done by implementing the setter method to simply overwrite the value of the Variable whereas the getter method return the Variable instance, allowing users direct access to the Variables methods and attributes, like fixed or min, i.e.:

@property
def my_param(self) -> Parameter:
    return self._my_param

@my_param.setter
def my_param(self, new_value: float) -> None:
    self._my_param.value = new_value

When Variable attributes are defined as such, ModelBase provides functionality for correct de-serialization by overwriting the from_dict method to set the underlying _my_param attributes, since the class does not (and should not) take Variable objects as inputs in its constructor.

Additionally ModelBase provides 4 convenience methods to get all its Variables. get_all_variables, which recursively finds all Variable attributes in the class:

def get_all_variables(self) -> List[DescriptorBase]:
    vars = []
    for attr_name in dir(self):
        attr = getattr(self, attr_name)
        if isinstance(attr, DescriptorBase):
            vars.append(attr)
        elif hasattr(attr, 'get_all_variables'):
            vars += attr.get_all_variables()
    return vars

And also get_all_parameters which filters out all Descriptors returning only Parameter attributes,
get_fittable_parameters which filters out dependent Parameters to only provide fittable Parameters and get_free_parameters which additionally filters out all fixed Parameters.

SerializerBase

The SerializerBase class is the current class responsible for serialization/de-serialization of objects. This class has a deserialize_dict static method, which takes a dictionary and de-serializes it, using classes own from_dict method if they're EasyScience classes, and the generic de-serializer otherwise.

This method allows classes themselves to define a from_dict method to determine how they are de-serialized, instead of just assuming that the __init__ constructor works with a serialized dictionary, which it won´t for Parameter attributes for example.

Link to the ADR suggestions:
#46
#110
#161