ADR Suggestion New EasyScience base classes.

[damskii9992]

General

As has been outlined in detail in #110, the current base classes ObjBase, BasedBase and CollectionBase are over-engineered and convoluted classes which are difficult to edit and maintain.
This is mostly caused by two key features: "Parameter injection", which allows dynamic classes with attributes defined at instantiation, and "interface switching" which allows on-the-fly changing of the interface between different third-party calculators without loss of the current state.

Both of these features are undesirable for different reasons. Parameter injection is undesirable because they encourage creation of classes with unknown or changing API's, making it extremely difficult to develop and maintain features using these classes.
Interface switching is undesirable due to improper separation of responsibilities and very confusing logic, as outlined in #160.

This ADR has an initial implementation which can be reviewed in #159

Current Implementation

The current implementation has already been outlined in #110

Proposed Implementation

I propose to remove the 3 base classes ObjBase, BasedBase and CollectionBase in the future, and replace them with new simpler classes. For now, the new base classes will coexist with the old base classes until all dependent libraries have switched.

Specifically I propose 2 new base classes: NewBase which is the new root-base class of EasyScience, replacing BasedBase and ModelBase which inherits from NewBase but adds functionality to accommodate Parameter class attributes.

NewBase

This class will be renamed in the future, when we have properly switched to the new classes.
NewBase inherits from no other class, unlike BasedBase which inherits from SerializerComponent to add serialization capabilities. Instead NewBase implements those serialization capabilities itself directly, avoiding the need for an extra inheritance layer. 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 as_dict method:

def as_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, 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 Parameter 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 Parameter whereas the getter method return the Parameter instance, allowing users direct access to the Parameters 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 Parameter attributes are defined as such, ModelBase provides functionality for correct deserialization by overwriting the from_dict method to set the underlying _my_param attributes, since the class does not (and should not) take Parameter objects as inputs in its constructor.

Additionally ModelBase provides 3 convenience method to get all its Parameters. get_fit_parameters, which recursively finds all DescriptorNumber or Parameter attributes in the class:

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

And also get_fit_parameters which filters out dependent Parameters and DescriptorNumbers 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/deserialization of objects. This class gets extended with a deserialize_dict static method, which takes a dictionary and deserializes it, using classes own from_dict method if they're EasyScience classes, and the generic deserializer otherwise.

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

[henrikjacobsenfys]

Disclaimer: I haven't spent much time studying our base classes. This looks mostly good to me, but with some questions/comments.

I'm not sure if I like that the get_all_parameters method also gets DescriptorNumbers. The only DescriporNumbers I use so far are for unit handling, and I don't want hbar to show up when asking for a list of Parameters. If you want to include DescriptorNumbers we may need a fourth get_parameters type method?

I find it convenient, perhaps almost required, to pass Parameters as inputs to constructors. I could of course be wrong, but I'm using it in my Convolution class. Specifically, the offset, which is a fittable Parameter.

May be worth it to add display_name here - I see that it's in the PR :)

[damskii9992]

The display_name is mentioned here ;) But Piotr wants it moved to the ModelBase class, what do you think about that?

The get_all_parameters getting also DescriptorNumbers was based on the implementation in EasyDiffraction, maybe @AndrewSazonov has an opinion on that? We could have a fourth method which doesn't include DesriptorNumbers but filters out both dependent parameters and fixed parameters.

For passing Parameters to class constructors, using Piotrs words, that screams for a refactoring ;) Essentially Parameters should only live within their own classes. If they are accessed in other classes, then you pass the class which they belong to, to that other class. Like how the Analysis class doesn't take the Parameters from a SampleModel as input, but rather the entire SampleModel class.

[henrikjacobsenfys]

Reading is apparently hard for me haha. I have no strong opinion on which base class the name lives in.

I'll think about the refactoring!

[seventil]

Really apreciate the changes that improve the definition of classes interface.
Although it is mentioned that the current implementation allows for on-the-fly change of interfaces for calculators, the proposed implementation will have that as well with the proper adaptors (as we discussed earlier)

[damskii9992]

Yup, once we implement the idea originally discussed in #160