ADR Suggestion Calculator Factory

[andped10]

In version 1.1.2 of the EasyScience we rely on the class Objects.Inferface.InterfaceFactoryTemplate to obtain functionality to determine the result/response from a sample. In reflectometry these results/responses are the reflectivity curve and the SLD curve. The current solution allows the user to change between different physics calculators by switching the state of the "Factory".

There are several issues with the current setup:

• The name Interface way to generic and even misleading. Instead it should be Calculator
• Another challenge with the generic naming approach is that the main method is called fit_func that is complete non-explanatory
• It is confusing that the code part is called a Factory since it doesn't produce any objects as expected from a factory pattern
  • Not sure, but create actually seems to produce an interface (calculator)
• Its state is complex to maintain (which physical calculator that is being used)
  • It has complicated dependencies (generate_bindings)
  • Might even have to update the Fitter

In an attempt to simplify the calculator functionality the following changes are suggested:

• Change towards a setup similar to fitting.minimizers where the factory is only responsible for producing the requested calculator object
  • No state information should be hold be the factory
• The produced calculator would correspond to one and only one physical model
• The constructor for the produced calculator should take a model/sample as its main argument
  • Only able to do single point calculations for this provided model/sample
  • Could have method to update the model/sample
• The produced calculator should probably have a method with a generic name that would be called when doing fitting
  • Can be ensured by having an base class for the calculators where this method is defined as abstract
• At the EasyScience level it will probably only be a matter of defining the calculator base class and defining an abstract base factory to ensure that such calculator objects are returned
• The concrete calculator factory would be implemented in the product specific EasyXXXLib repo similar to where the interfaces (calculators) are implemented

[rozyczko]

Let's do some high level planning here

1. Summary of current issues

Issue	Current state	Proposed solution
Generic naming	Interface, fit_func are too non-explanatory	Instead use: Calculator, calculate
Misleading pattern	Factory holds state and has complex dependencies	Pure factory that only produces calculators, no state
Binding complexity	generate_bindings tighlty couples calculator to model	Calculator takes model in constructor, manages its own parameter sync
State Management	Factory tracks _current_interface, '_interface_obj` etc.	No state in factory! Claculator instance is standalone

2. Proposed architecture overview

┌─────────────────────────────────────────────────────────────────┐
│                    EasyScience Core Library                     │
├─────────────────────────────────────────────────────────────────┤
│  CalculatorBase (Abstract)                                      │
│  ├── __init__(model, instrumental_parameters, **kwargs)         │
│  ├── calculate(x) -> np.ndarray  [abstract]                     │
│  ├── update_model(model) -> None                                │
│  ├── update_instrumental_parameters(params) -> None             │
│  ├── model property                                             │
│  └── instrumental_parameters property                           │
├─────────────────────────────────────────────────────────────────┤
│  CalculatorFactory (Abstract)                                   │
│  ├── available_calculators() -> List[str]                       │
│  └── create(name, model, instrumental_parameters, **kwargs)     │
│       -> CalculatorBase                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    EasyXXXLib (Product-specific)                │
├─────────────────────────────────────────────────────────────────┤
│  ReflectivityCalculator(CalculatorBase)                         │
│  ├── __init__(sample, instrumental_params, **kwargs)            │
│  ├── calculate(q) -> reflectivity curve                         │
│  └── get_sld_profile() -> SLD curve                             │
├─────────────────────────────────────────────────────────────────┤
│  ReflectivityCalculatorFactory(CalculatorFactory)               │
│  ├── available_calculators() -> ['refl1d', 'refnx', ...]        │
│  └── create('refl1d', sample, instr_params) -> Refl1dCalculator │
└─────────────────────────────────────────────────────────────────┘

4. Key Design Decisions

• Model ownership: Calculator owns a reference to the model (and optional instr params), not the other way around
• No bindings: Calculator reads parameters directly from model/instr params when calculate() is called
• Stateless factory: Factory only creates, doesn't track which calculator is "current"
• Single responsibility: Each calculator corresponds to one physical model/sample

5. Example usage:

# In EasyReflectometryLib
class ReflectometryCalculatorFactory(CalculatorFactoryBase):
    _calculators = {'refl1d': Refl1dCalculator, 'refnx': RefnxCalculator}
    
    def create(self, name: str, model, instrumental_parameters, **kwargs) -> CalculatorBase:
        return self._calculators[name](model, instrumental_parameters, **kwargs)

# User code
sample = MultilayerSample(...)
instrument = InstrumentalParameters(resolution=0.05, ...)

factory = ReflectometryCalculatorFactory()
calculator = factory.create('refl1d', sample, instrument)

# Single point calculation (uses both sample and instrument internally)
reflectivity = calculator.calculate(q_values)
sld = calculator.get_sld_profile()

# Update instrument parameters (e.g., for different measurement conditions)
new_instrument = InstrumentalParameters(resolution=0.02, ...)
calculator.update_instrumental_parameters(new_instrument)

# Fitting
fitter = Fitter(sample, calculator.calculate)
result = fitter.fit(x_data, y_data)

# Switch calculator engine (keeps same model and instrument)
calculator_new = factory.create('refnx', sample, instrument)
fitter.fit_function = calculator_new.calculate

[damskii9992]

This all looks very good. I would like to point out that the way it is done for the minimizers, is that the factory is a simple function, rather than a class :)
I would also like to address where the calculator should live?
In Analysis?

[rozyczko]

I think it should be up to the library to decide who owns the calculator instance. For diffraction, the current choice is the Experiment, for Imaging, from what you said - it's the Sample. In reflectometry, it will be Analysis, as originally decided (in an ADR)

Also, calculator needs to include Instrumental Parameters, not just sample model.

[seventil]

Nice overall and agree with the suggested changes. I think the factory should be a class, as mentioned in Piotr's overview it can have a available_calculators() -> List[str] method or property. As I see it, the list of strings to choose from is the reason to have a factory in the first place, otherwise you could just import and init the necessary calculator

[AndrewSazonov]

In diffraction, the calculator factory originally lived in the Analysis object, and this worked well for simple use cases. However, real use cases revealed a limitation when simultaneous fitting of multiple experiments of different types is required. In such cases, a single calculator instance is not sufficient, since different experiment types may require different calculation engines.

While this may not be needed for every technique, one of the core ideas behind the calculator factory, and EasyScience in general, is to allow users to select different calculation engines. It is natural to expect that these engines will not have fully overlapping functionality. In a multi-experiment fit, this can mean that experiment A needs calculator1, while experiment B needs calculator2, at the same time.

This raises a design question: how should this be handled cleanly in the API?

1. Should Analysis hold a list of calculators, one per experiment?
2. Should the calculator instance live on the Experiment itself?
3. Or should there be an additional layer between Analysis and Experiment responsible for managing calculators?

From a user perspective, how would switching calculators look in such a setup? For example, instead of a single
project.analysis.calculator = "calculator1", how would a user select or change calculators for individual experiments in a multi-experiment analysis?

[damskii9992]

Adding comment from PR here for documentation purposes:
I think we can do better than this in the CalculatorFactory base class. How about if the factory base has an internal attribute _available_calculators which is an empty list and a generic method which attempts to import a package based on input, and if successful adds it to this list. That way we can have automatic granularity of installed calculators and even if a calculator for some reason fails to import on the users end we can still support the other calculators.

[damskii9992]

Or is this maybe over-engineering a bit?

[damskii9992]

Another question, should the Factory class be a singleton? If the factory has attributes which can be changed, I think it makes sense to make it a singleton.

[AndrewSazonov]

It's a bit unclear what the intended role of the abstract calculate() method in CalculatorBase is, especially when compared to technique-specific methods.

In reflectometry, calculate() is implemented in ReflectivityCalculator, but there is also a separate get_sld_profile() method defined only there. Could you clarify the conceptual difference between a reflectivity curve and an SLD profile? Are these two fundamentally different results that are both always relevant in reflectometry, or is one more of an auxiliary output?

If both outputs are essential, why is only one exposed through the generic calculate() interface, while the other is accessed via a technique-specific method?

More generally, how should we handle calculators that naturally produce multiple types of results? For example, in diffraction we may want both a calculated diffraction pattern and calculated Bragg peak positions. In such cases:

• Should calculate() still exist as an abstract method?
• Should it return a structured result object containing multiple outputs?
• Or should we expect technique-specific APIs for secondary results?