Adapters: Defining Parameters

[pinkwah]

Parameters

(née Settings)

Part of the discussion regards how we should design defining parameters for a given model. The two versions that we have are using pydantic's BaseModel and rolling our own system that's similar to dataclasses/pydantic but satisfies our needs exactly.

We want to achieve the following:

1. It must be possible to specify input forms in the frontend without reinventing Plotly Dash or similar. That means we must limit what's possible to at most the options in EDS InputForm.
2. The implementor can have additional validations which will show up in the frontend.
3. The correct use is the easiest. We don't want to end up with a situation where eg. the correct thing to write Parameters.validate_model(parameters).temperature when the incorrect parameters["temperature"] is shorter and nicer, but will not validate anything.

Using Pydantic

The user can write a parameter model like so

class ArcsParameters(BaseParameters):
    temperature: int = Parameter(100, label="Temperature", min=100, max=300, unit="K")
    pressure: int = Parameter(10, label="Pressure", min=1, max=100, unit="bar A")

Where BaseParameters subclasses pydantic.BaseModel and Parameter is a function that returns pydantic.Field (which itself returns pydantic.FieldInfo).

We can't just use Field because it's not possible to directly set the fields that we want, like min, max, label, unit and choices. The Parameter will do so by wrapping Field and adding to json_schema_extra.

We must also subclass BaseModel so that we can add our own validations automatically, like for choices.

Pros:

• Uses a widely used and understood Python library
• For implementors it's easy to specify additional validations using @pydantic.field_validator

Cons:

• Risk of unforeseen usecase of Pydantic. Because Pydantic is a big library, an implementor might use it in a way that we couldn't account for, causing issues.
• Pydantic defines a lot of methods, which are all visible when used with LSP/intellisense. Might be somewhat confusing compared to a class where the only fields are the ones you explicitly defined.
• Have to define parameters separately from the adapter.

Rolling our own

Pydantic is an extension of @dataclass with added validations. We can do the same ourselves. It's also possible to define parameters directly in the main adapter class.

class ArcsAdapter(BaseAdapter):
    # ...
    
    temperature: int = Parameter(100, label="Temperature", min=100, max=300, unit="K")
    pressure: int = Parameter(10, label="Pressure", min=1, max=100, unit="bar A")

It's then possible to make use of parameters by accessing them via self.. Because BaseAdapter is designed to be simple, we avoid the overload of suggestions for methods that are unneeded.

Pros:

• We have full control over what it does
• No/few unnecessary knobs for the implementor to think about

Cons:

• Custom validations must be written manually

Difficulty of implementation

Both methods would require us to write code which validates parameters. For Pydantic we'll mostly be using their API, while when rolling our own we use the standard Python API for metaprogramming. I'd say both are of equivalent difficulty to understand.

[lars-petter-hauge]

Really nice wrap up of our discussion! Thank you so much!

I would argue that another con of adding parameters directly to the class is that it is necessary to instantiate the adapter, e.g.

adapter = ArgsAdapter(parameters)
adapter.run(concs)

versus

ArcsAdapter.run(concs, parameters)

This former creates a fictious split between parameters and concs, while they should be on the same level.

Furthermore, within the run function it would be different ways of accessing the two:

def run(concs):
    internal_run_model(concs = concs, temperature = self.temperature)

versus

@classmethod
def run(concs, settings):
    internal_run_model(concs = concs, temperature = settings.temperature)

Meaning that the latter could be a classmethod, while the former requires initialization. Would be nice to explicitly avoid any form of state.

[pinkwah]

I agree. I think a better solution in this case is that we already require the implementor to define concentrations on the class, so we can make self.concentrations make sense, where that would be the user-requested concentrations. So either we pass both parameters and concentrations to the function, or both as fields.

[lars-petter-hauge]

In that case perhaps the following would be a better way of how to use adapters, if we go with parameters defined in the class:

ArcsAdapter(concs, settings).run()

Not completely sure if I liked it, was just to avoid keeping that instance of the adapter, and having the two arguments on an equal level..

[lars-petter-hauge]

A couple more..

Suppose we should make the arguments optional, since otherwise it will be necessary to provide some dummy concentrations and settings in order to use the other adapter functions.. And then we could technically also put the adapter in a state that doesn't make it run..

adapter = ArgsAdapter() #  <-- we want to able to do this for the model_config url
adapter.user_has_access(user)
adapter.run() # <--- crash, although this should be only used after ArgsAdapter is initialised with concs and params.

Unsure if this is worth considering, but just putting it out there.. If we are to provide more than a single function.. I think having the arguments with the function call looks slightly nicer

ArgsAdapter(concs, first_setting).func1()
ArgsAdapter(concs, second_setting).func2()

versus

ArgsAdapter.func1(concs, first_setting)
ArgsAdapter.func2(concs, second_setting)

[lars-petter-hauge]

Pydantic defines a lot of methods, which are all visible when used with LSP/intellisense. Might be somewhat confusing compared to a class where the only fields are the ones you explicitly defined.

Although I agree, this is true for anyone using pydantic, isn't it? Hence this argument would go against using pydantic in any form or shape?

[pinkwah]

I reckon a user of Pydantic is interested in Pydantic's features, and so it may be expected. We aren't giving you Pydantic, we're giving you the option to use some Pydantic features. Notably, we will probably not allow you to write Field directly because we wouldn't know how to render it in the frontend.

But this is a fairly small "con". Tbh, I wish Pydantic didn't have all those model_* methods and they were free functions instead. model_validate(MyData, foo="bar", ...) vs MyData.model_validate(foo="bar", ...) but oh well.

[lars-petter-hauge]

Risk of unforeseen usecase of Pydantic. Because Pydantic is a big library, an implementor might use it in a way that we couldn't account for, causing issues.

Interesting thought.. I mean, we are still going to review any adapters coming into the repo, it's not like it's free for all. If we see a specific use case that causes issues for us we could always amend usage of pydantic, disallowing it.

[lars-petter-hauge]

There are also use cases for the ones implementing the Baseadapter (that would be us) when using pydantic, as any built in validators do not need to be tested, and we get schema out of the box..

[pinkwah]

We still need to create the schema ourselves via Field's json_schema_extra. So we're still doing the bulk of the work on both backend and frontend. Whether Pydantic loops over the fields or we do it manually, I think it's small compared to everything else.

[lars-petter-hauge]

I do like dataclass as well, they are simpler, less overhead, and you don't add more than you need. I just see that there are many things that will be solved if we use pydantic.