ADR Suggestion Dependent Parameters

[damskii9992]

General

It can be beneficial in a model to have Parameters which are defined through a relation to other parameters/descriptors. These dependent parameters are defined by their relation and thus should not be fitted during minimization. Their value should be updated when the values of the independent parameters which they depend on are changed. It should be possible to easily convert a dependent parameter to a dependent parameter and vice versa.

Current Implementation

Currently, this is handled by the "constraints" objects which are created separately and then assigned to the parameter, such as:

a = Parameter(name='a', value=0.2)
b = Parameter(name='b', value=1)
constraint = ObjConstraint(a, '2*', b)
b.user_constraints['SET_A'] = constraint

The "constraints" object can only constrain according to a select few operations and only 1 parameter to another.

Proposed Implementation

The concept of a dependent Parameter can be implemented using the generic "Observer" coding pattern, with all the dependent parameters being observers subscribing to the independent parameters.
To allow for great flexibility in the type of possible dependencies, the update of a dependent parameter can be done using the asteval python interpreter with its functionality limited to only arithmetic and logical operation, and its symtable including only the independent parameters.

The observer pattern

The observer pattern is a fairly simple pattern including only 4 basic methods and 1 attribute:

class ConcreteSubject(ABC):
    """
    The Subject owns some important state and notifies observers when the state
    changes.
    """

    _state: int = None
    """
    For the sake of simplicity, the Subject's state, essential to all
    subscribers, is stored in this variable.
    """

    _observers: List[Observer] = []
    """
    List of subscribers. In real life, the list of subscribers can be stored
    more comprehensively (categorized by event type, etc.).
    """

    def _attach(self, observer: Observer) -> None:
        print("Subject: Attached an observer.")
        self._observers.append(observer)

    def _detach(self, observer: Observer) -> None:
        self._observers.remove(observer)

    """
    The subscription management methods.
    """

    def _notify_observers(self) -> None:
        """
        Trigger an update in each subscriber.
        """

        print("Subject: Notifying observers...")
        for observer in self._observers:
            observer._update(self)

This is the basic construct of the observed object, here namely the independent parameters. Since a dependent Parameter can use a DescriptorNumber for its relation, this part of the observer pattern should be implemented on the DescriptorNumber

class Observer(ABC):
    """
    The Observer interface declares the update method, used by subjects.
    """

    @abstractmethod
    def _update(self, subject: Subject) -> None:
        """
        Receive update from subject.
        """
        pass

Since only Parameters can be a dependent parameter, the _update method is defined in the Parameter class.

Avoiding cyclic dependencies

The problem

Since parameters can be made dependent after they're created, it is possible to end up in an infinite loop where a dependent parameters update triggers another dependent parameters update which in turn triggers the first parameters update and so on:

flowchart LR;
   A-->|update|B;
   B-->|update|C;
   C-->|update|D;
   D-->|update|B;

Loading

The solution

It is possible to avoid this by simply requiring that dependent parameters only depend on independent parameters, but it is easy to imagine a use-case where a dependency on a dependency is beneficial. A better solution instead is to use update_ids. The concept is simple:
If an update is triggered by a manual change, such as a value change of an independent parameter, the update gets assigned a unique id.
This unique id is then passed to the observers along with the unique_name of the object that triggered the update;

def _notify_observers(self, update_id=None) -> None:
     """Trigger an update in each subscriber."""
     if update_id is None:
        self._global_object.update_id_iterator += 1
        update_id = self._global_object.update_id_iterator
     for observer in self._observers:
         observer._update(update_id=update_id, updating_object=self.unique_name)

In the observers _update method, the update id is checked against an internal dictionary for the updating object. If the stored update id for the updating object is different from the new one, set the stored update id to the new one and proceed with the update, and notify its own observers, passing along the update_id, otherwise raise an error warning that a cyclic dependency has been detected:

def __update(self, update_id: int, updating_object: str) -> None
   if self._dependency_updates[updating_object] == update_id:
      raise RuntimeError
   else:
      update stuff
      self._dependency_updates[updating_object] = update_id
      self._notify_observers(update_id=update_id)

This implementation allows for dependencies of dependencies and will detect if a cyclic dependency has been created.

An edge-case

While this implementation does allow for dependencies of dependencies, it will also flag some perfectly valid dependency trees as cyclic dependencies, such as:

flowchart LR;
   A-->|2nd update|B;
   A-->|1st update|C;
   B-->|2nd update|C;
   C-->|1st update|D;
   C-->|2nd update|D;

Loading

In the dependency-tree above, Parameter D gets updated by Parameter C twice with the same update id, first when A directly updates C which in turns trigger the update of D, and then again when A updates B, which updates C which again updates D.
This dependency-tree is perfectly valid, but will be flagged as a cyclic dependency because Parameter D gets updated twice by Parameter C with the same update id.

Making a dependent Parameter

There will be 2 ways to make a dependent Parameter. An already created Parameter can be made dependent by using the make_dependent_on method:

a = Parameter(name='a', value=2)
b = Parameter(name='b', value=1)
b.make_dependent_on(dependency_expression='2*easypeasy', dependency_map={'easypeasy' : a})

Or by using the class method from_dependency to construct it directly:

a = Parameter(name='a', value=2)
b = Parameter.from_dependency(dependency_expression='2*easypeasy', dependency_map={'easypeasy' : a})

In either case, the Parameters internal attribute _independent will be set to False, which will lock all the setter methods and disable the parameter for fitting.
In addition, since a "fixed" and "dependent" parameter does not make sense, the fixed attribute will also be set to False.
The _independent attribute is a read-only attribute, meaning its setter simply raises a error. To make a dependent parameter independent, one has to use the make_independent() method.
This is done to ensure that the object is properly detached from the list of observers for all its independent parameters:

def make_independent(self) -> None
   for dependency in self._dependency_map.values():
      dependency._detach_observer(self)
   self._independent = True

For the same reason, to change the dependency of an already dependent parameter, one has to use the make_dependent_on method again.

The dependency_expression evaluation with asteval

When a parameter is made dependent, a python interpreter object is created with asteval and attached to it. We use asteval to limit the interpreters functionality to only arithmetic and logical expressions, to avoid many of the potential safety issues with embedded interpreters: https://lmfit.github.io/asteval/motivation.html.

The asteval interpreter has no access to the local or global namespace, so in order to use Parameters or DescriptorNumbers in it, these first have to be added to the interpreters symtable. This is the purpose of the optional argument dependency_map, which is a dictionary mapping the names used in the dependency_expression to existing objects.

After the dependency_map has been added to the asteval interpreters symtable, the dependency_expression is evaluated with it.
If the resulting output is either a DescriptorNumber or a Parameter, the dependent parameters attributes are updated to the ones of the output:

def _update(self):
   temp= self._dependency_interpreter(self._clean_dependency_string)
   self._scalar.value = temp.value
   self._scalar.unit = temp.unit
   self._scalar.variance = temp.variance
   self._min.value = temp.min if isinstance(temp, Parameter) else temp.value
   self._max.value = temp.max if isinstance(temp, Parameter) else temp.value
   self._notify_observers()

If the resulting output is not a DescriptorNumber or a Parameter, an error is raised.
Note that the min and max values are simply set to the value of the output if the output is a DescriptorNumber.

Unique names in the dependency_expression

To improve the ease of use, especially when the parameters to otherwise add to the dependency_map is hidden away behind many layers of objects, or if its destination is simply unknown, we also allow the use of unique_names in the dependency_expression:

a = Parameter(name='a', value=2, unique_name='EasyPeasy')
b = Parameter.from_dependency(dependency_expression='2*"EasyPeasy"')

To use unique_names in the dependency_expression they must be encapsulated by either "" or '' (depending on which were used to define the dependency_expression string). When unique_names are used, the objects does not need to be added to the dependency_map argument. Mixtures of dependency_map arguments and unique_names can be used.

This functionality is provided by the internal _process_dependency_unique_names method, which uses regex to scan the dependency_expression for unique_names, checks if these exists in the global_object and then adds them to the internal _dependency_map:

def _process_dependency_unique_names(self, dependency_expression: str):
   inputted_unique_names = re.findall("(\'.+?\')", dependency_expression)
   inputted_unique_names += re.findall('(\".+?\")', dependency_expression)
   for name in inputted_unique_names:
      name = name.strip("'\"")
      if name in self._global_object.map.vertices()
         parameter = self._global_object.map.get_item_by_key(name)
         self._dependency_map['__'+name+'__'] = parameter
         clean_dependency_string.replace(name, '__' +name+'__')

Note that the unique_names are pre-fixed and pre-pended with double underscores '__' in the _dependency_map and that the dependency_expression has the unique_names replaced internally with these new names instead. This is done in an attempt to avoid name clashes with names in the argument dependency_map.

Arithmetic and logic dependencies

To provide extremely flexible and user-friendly dependencies, we rely on the arithmetic operations between Parameters and DescriptorNumbers, as described in #54. This allows for many different kinds of complicated dependency expressions:

a = DescriptorNumber(name='a', value=2)
b = Parameter(name='b', value=10, unit='m')
c = Parameter(name='c', value=-5, unit='cm', variance=1)
d = Parameter.from_dependency(
   dependency_expression='5*a**2*b + c/a', 
   dependency_map={'a' : a, 'b' : b, 'c' : c}
   )

We use a very minimal configuration of the asteval interpreter, allowing only arithmetic operations in the dependency_expression, but we also open up for ternary operations, to allow for complicated logical dependencies:

a = Parameter(name='a', value=2)
d = Parameter.from_dependency(
   dependency_expression='-a if a.value<0 else a**2'
   dependency_map={'a' : a}
   )

[AndrewSazonov]

Note that in order to update the part of the GUI that displays the changed parameter, you must decorate the setter and getter of the parameter and emit the parameter changed signal, as shown in the example below:

from PySide6.QtCore import QObject, Signal, Slot, Property

class Model(QObject):
    definedChanged = Signal()

    def __init__(self):
        self._defined = False

    @Property(bool, notify=definedChanged)
    def defined(self):
        return self._defined

    @defined.setter
    def defined(self, newValue):
        if self._defined == newValue:
            return
        self._defined = newValue
        self.definedChanged.emit()

Now every time you assign a new value to the property defined, for example, model.defined = True, the signal definedChanged is emitted and the value of this property displayed in the GUI is updated.

[rozyczko]

Good point.
Also, please keep in mind that signal/slot mechanism is only available in event loop based code (Qt/QML). The underlying library/core code will not be able to use it.

[andped10]

To my understanding we would also need functionality to inform the independent parameter when a new dependent parameter is made dependent.

[AndrewSazonov]

Overall, this is a great suggestion. I have a few comments:

1. You are extending the concept of simple dependency types by introducing additional checks and attributes, such as those needed to handle cyclic dependencies. The diagrams illustrate these cases well, but I wonder how often such complex scenarios will actually occur in practice. It might be useful to compile a list of real-world use cases relevant to the various techniques our software is intended to support. This would help us evaluate what is truly necessary for analyzing real experimental data. While abstract examples like “A updates B, B updates C” are helpful, I currently do not see a clear need for the more complex cases in the context of diffraction. I would be interested to learn what might be required for other techniques, such as reflectometry, imaging, or spectroscopy. This could help us determine whether more advanced types of constraints or dependencies are needed, and if so, how those ideas could also be applied to diffraction. Additionally, such cases might be relevant when users want to use the easyscience module directly, without relying on technique-specific modules. For all these reasons, I believe it would be helpful to collect a set of concrete use cases, ideally with code examples from the user’s perspective, to evaluate how practical and convenient these approaches are in real data analysis.
2. Regarding the fixed attribute, we have discussed this before, and there was a suggestion to use free instead. The idea is that par.free = True is generally more intuitive and readable than par.fixed = False.
3. In the example -a if a.value < 0 else a**2, is a.value actually necessary instead of just a? If so, it might be confusing for users to know when each form should be used. This could benefit from additional clarification or a more user-friendly approach.

[damskii9992]

1. If you just want thought-up examples of cases where this could be useful, I can easily think up a few. If you want a real-world use-case where it was already needed, then I unfortunately don't have any, as I implemented this mostly because I happened to think up a solution, rather than because I needed the solution.
2. We still have the alias par.free = not par.fixed. I don't myself find free to be more intuitive than fixed, so I simply kept this as-is.
3. Currently par.value is needed only because we haven't implemented the logic dunder methods for the Parameter class, if/when those are implemented, the .value part won't be needed.

[AndrewSazonov]

Another comment: in this implementation, you are using the Observer pattern, where all dependent parameters act as observers subscribing to changes in the independent parameters. What is the advantage of this approach compared to, for example, implementing a separate class that manages all dependencies centrally, so that individual parameters do not need to know about each other?

[damskii9992]

What you're suggesting is called the Mediator pattern.
The Mediator pattern is more complex but flexible because it allows for looser coupling between objects and two-way communication.
The Observer pattern is simpler and only works for 1-way communication, such as the one needed for our dependent parameters.
So in short, the advantage is simplicity. This implementation is the simplest working code structure.

From Stackexchange https://softwareengineering.stackexchange.com/questions/134432/mediator-vs-observer:

The Observer pattern works well when no coordination between the observers is necessary and the observes relationship goes one way.

For example, let objects B and C observe object A. When object A fires event X, then object B should execute method Y() and object C should execute method Z(). If methods B.Y() and C.Z() are totally independent and require no coordination, then go ahead and use the observer pattern.

On the other hand, if B.Y() must be executed before C.Z() then you will want to use the Mediator pattern where the mediator encapsulates this coordination. In this scenario, mediator M would observe object A and would have references to objects B and C. When A fires event X, M will handle the event and call B.Y() and C.Z() in the prescribed order.

Also, if objects A, B and C need to observe each other then using a mediator as an intermediary will go a long way to decouple these objects and avoid spaghetti code.

[AndrewSazonov]

One more question. Let's use one of the diagrams you showed earlier:

flowchart LR;
   A-->|update|B;
   B-->|update|C;
   C-->|update|D;
   D-->|update|B;

Loading

Do you have any mechanism to handle the case where, for example, parameter C is deleted? In diffraction, this could occur e.g. if the user changes the type of atomic displacement for a given atom. In such a case, one parameter might be removed and another added dynamically. How would the proposed implementation handle this scenario?

[damskii9992]

Good catch!
We will need to implement the __del__ dunder method to handle this, as the deletion would currently lead to broken dependencies. Will add this to the feature list ^^

[damskii9992]

After investigation: I was completely wrong about this. In Python objects are not deleted when you do:

del par

Instead, this just deletes the REFERENCE par to the actual object. Now if par was a dependent Parameter, or other Parameters depended on it, it is kept alive through THOSE objects references to it, meaning that no dependency is actually broken.
If a lot of dependent parameters are continuously deleted, this could cause problems with memory.
A solution could be to make the dependent parameter references into weak references, causing them to not keep objects alive. Do we want to do this and then deal with the potential problems of broken dependencies?

[rozyczko]

What is the reason for having from_dependency instantiation mechanism for a new Parameter?
Creation of parameters tends to always precede defining the constraints on those parameters, at least in diffraction, reflectometry and SANS.
Is it different in other techniques?

[damskii9992]

It is just a convenience function. But for any Parameter which is created explicitly for the purpose of being a dependent parameter, it will be convenient to have. An example of this is the Fraction object which will be needed in: EasyImaging easyscience/imaging-lib#13