ADR Suggestion, Descriptors and Parameter

[andped10]

General

To build a model we need to be able to specify variables of various types. The variables used in the model can be divided into two groups. The ones that are assigned a value and remain unchanged, Descriptors, and the other ones that change, Parameter. The latter tend to be the ones that are fitted to get a match between experimental observations and model predictions.

graph LR
DescriptorBase --> DescriptorNumber
DescriptorBase --> DescriptorStr
DescriptorBase --> DescriptorBool
DescriptorNumber --> Parameter
subgraph Non-fittable
   DescriptorNumber
   DescriptorStr
   DescriptorBool
end
subgraph Fittable
   Parameter
end

Loading

Descriptors

To handle variables that can be considered "static" (rarely change after the model has been constructed) we use descriptors. The types of descriptors in use are bool, string, or number values, which all share some base functionality contained in a base class.

DescriptorBase

All type specific descriptors inherit from this base class. The main properties of the base class are:

• name, name of this object (decorated with undo/redo functionality)
• display_name, optional pretty name for the object (decorated with undo/redo functionality)
• description, optional summary of what this object is for
• url, optional lookup url for documentation/information
• parent, optional link to the object which this descriptor is attached to

DescriptorBool

The bool descriptor holds the value of a builtin bool type. The additional property is:

• value, utilized to hold the value (decorated with undo/redo functionality)

DescriptorStr

The str descriptor holds the value of a builtin string type. The additional property is:

• value, utilized to hold the value (decorated with undo/redo functionality)

DescriptorNumber

The number is different from the two former descriptors as it is continuous. Furthermore it can be assigned a physical unit and a variance for the value. To provide this functionally the value is kept in a [scipp scalar]. The additional properties are:(https://scipp.github.io/generated/functions/scipp.scalar.html)

• value, the numerical value of the variable (decorated with undo/redo functionality)
• unit, optional physical unit for the numerical value (decorated with undo/redo functionality)
• variance, optional variance for the value (decorated with undo/redo functionality)
• full_value, the full scipp scalar holding all the above mentioned properties (decorated with undo/redo functionality)

To minimize user errors and simplify constraints, the unit and full_value cannot be changed after initialization. The unit can be converted between allowed types with the convert_unit method.

Parameter

The Parameter class inherits from DescriptorNumber and serves to hold model variables that change. Such changes could be when fitting the model towards experimental data. The additional properties are:

• min, optional minimum for the interval for the value (decorated with undo/redo functionality)
• max, optional maximum for the interval for the value (decorated with undo/redo functionality)
• free (was fixed), optional sets if the parameter is allowed to vary while fitting (decorated with undo/redo functionality)
• unconstrained (was enabled), optional sets if the objects value can be set or if constraints are applied (decorated with undo/redo functionality)
• callback, optional callback that serves as a link between the object and a potential Calculator

[AndrewSazonov]

It's a good idea to have more separation between parameters. I'm not sure if we'll use DescriptorBool for diffraction, but it might be useful for other techniques. But note this. There are parameters that cannot be refined, but that the user should be able to change even after the model is defined. For example, the name of the space group or its integer number in the International Tables for Crystallography. Or, for example, the radiation probe, which could be "neutron" or "x-ray". This case does not seem to fit any of the proposed types.

[andped10]

Currently I think the "parameters" being mentioned above should be considered DescriptorStr. The reason being that they will not be fitted are they not true constants, however, they can be modified (variable) for the given model but this is only rarely done. I think that is the purpose of the descriptor to hold such almost constant variables.

To me

• a descriptor is a discrete or continuous variable that needed by the model but that will NOT be fitted.
• a parameter is a numerical valued which is continuous and might be fitted.

[AndrewSazonov]

Ok, then the difference between descriptor and parameter is similar to what we had before, but now we should have a better structure. So, the diagram should look like the one below, right?

graph LR
DescriptorBase --> DescriptorNumber
DescriptorBase --> DescriptorStr
DescriptorBase --> DescriptorBool
DescriptorNumber --> Parameter
subgraph Non-fittable
   DescriptorNumber
   DescriptorStr
   DescriptorBool
end
subgraph Fittable
   Parameter
end

Loading

[damskii9992]

Following a discussion with @andped10 I updated the ADR suggestion to reflect a somewhat important change. In the new implementation, the unit of a DescriptorNumber or Parameter cannot be changed from fx. "m" to "s" after initialization, in contrast to the old implementation.

This choice is made to avoid the issue of potential users forgetting to update constraints or models after changing the unit type.

[rozyczko]

One valid (?) use case is when the user wants to modify not the actual unit but its power. Changing a Parameter from eg. ns to ps (pretty common in MD) would be something expected.

[damskii9992]

That is exactly what is covered by the convert_unit method.

[AndrewSazonov]

There can be two types of min/max properties for a parameter.

• The first type reflects possible physical constraints. For example, the atom site occupancy can only be in the range from 0 to 1.
• The second type is related to the limits within which this parameter can be varied by the minimiser during the fitting process.

The values of these types are not always the same, as the user may want to apply more strict constraints on the parameter value during minimisation than physical constraints.

[damskii9992]

But in this case the minimization limit will always be tighter than the physical limit, so why bother having a physical limit in the code at all? And in any case I don't see physical limits as belonging to the parameter class, as a generic parameter is exactly generic, but maybe a derived class specific for the application at hand, such as an atom class?

[AndrewSazonov]

Physical limits are useful information associated with a parameter, like the physical units that we have. So I think it's good to have physical limits already for this.

Moreover, physical limits can become the default initial limits for minimisation. If the user imposed more strict limits for minimisation and then decided to reset those limits, they should be reset back to physical limits. Thus, physical limits are always useful to have.

Physical limits can be implemented in a generic parameter and initialised to be from -Inf to +Inf. Then derived class can change them as needed.

[damskii9992]

Hmm, I see what you mean. So 2 kinds of limits:

• Physical limit, defaults to -inf to inf, not changeable by the user but is instead set by the derived class.
• User limit, defaults to None, settable by the user, but only within the physical limits.

And when the value is printed, which limit should then be printed with the value? Both limits would seem confusing, maybe just the physical one?

[AndrewSazonov]

I think you are right and it is better to show only the physical limits in the standard print of the parameter along with its value, standard uncertainty and units.

[AndrewSazonov]

For the parameter, I would suggest renaming the property enabled to, e.g., unconstrained, as the latter is more descriptive. The user should not be able to change the value of this property.

[damskii9992]

This one will likely be handled at a later time, for example in the ADR #10

[andped10]

I think it can be done relatively easy in an independent PR after we got #19 in.

@damskii9992 would it be alright if I make an issue for the suggested name changes (free and unconstrained). The other ADR #10 would then mainly concern changes to functionality.

[damskii9992]

@andped10 Sure, but it might still be changed in ADR #10 depending on the needs there. But feel free to make a separate issue. We can always just link it to the ADR later if that makes more sense :)

[andped10]

Added new issue: #24

[AndrewSazonov]

For the parameter, I would also suggest using the property free instead of fixed, as the latter is more difficult to read.

For example,

• job.parameters.resolution_u.fixed = False is not as simple as
• job.parameters.resolution_u.free = True.

[andped10]

Added new issue: #24

[damskii9992]

Finalized in the ADR #25