Skip to content

Add system parameter requests & model state spec#210

Open
TimothyWillard wants to merge 3 commits intomainfrom
parameter-rich-systems
Open

Add system parameter requests & model state spec#210
TimothyWillard wants to merge 3 commits intomainfrom
parameter-rich-systems

Conversation

@TimothyWillard
Copy link
Copy Markdown
Collaborator

Added SystemABC.requested_parameters()/model_state() to allow systems
to provide information about their underlying state specification,
including shape, as well as request parameters that comply with said
requirements. Also integrated this work into the existing wrapper system
to demonstrate the functionality.

  • Added requested_parameters()/model_state() methods to SystemABC.
  • Extended wrap()/_AdapterSystem to accept explicit parameter
    request and model state callbacks.
  • Updated _checked_partial() so already materialized ParameterValue
    instances are preserved when binding static parameters.
  • Simplified the documentation quick start wrapper config to the minimal
    valid example.

Copy link
Copy Markdown
Contributor

@jc-macdonald jc-macdonald left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — one non-blocking note on int coercion.

f"but received shape {value.shape.sizes}."
)
raise TypeError(msg) from exc
return annotation(scalar)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

int-annotated stepper params are conventionally counts/sizes, so values should be whole numbers — but nothing upstream rejects a config like value: 3.7 since FixedParameter doesn't know the stepper's expected type. Ideally this validation would live in the Pydantic layer (e.g. ParameterRequest carrying a dtype hint so sample() can reject non-integer values at config time), but until that link exists, a guard here would catch the mistake:

if annotation is int and scalar != int(scalar):
    msg = (
        f"Parameter '{name}' is annotated as int "
        f"but received non-integer value {scalar}."
    )
    raise TypeError(msg)
return annotation(scalar)

Consider filing an issue to track the upstream fix.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that's a good element to add here for now. I would also in the future like to add some richness to ParameterValue with typing info, so float vs int is explicit. Also adding in other common cases like positive, negative, constrained to (0,1), etc.

@TimothyWillard TimothyWillard force-pushed the parameter-rich-systems branch 5 times, most recently from 27181f1 to 7d7f8a4 Compare April 20, 2026 16:23
Added the `axis` module for realizing and manipulating axes from
configuration. Includes:

- `ResolvedShape` as a container for metadata about the shape of an
  object based on its axes.
- `Axis` as a data class for a realized axis that objects which need
  axes can use to do their calculations.
- `AxisCollection` as a mapping of `Axis` objects that simplify access
  when multiple axes are needed.
- Dropped deprecation warning from using the `axes` attribute of
  `ConfigurationModel`.

Follow up to #147, #164.
Introduced `ParameterValue` as the return type for `ParameterABC.sample`
that contains the underlying value as a numpy array as well as metadata,
which at this point is the `ResolvedShape`. This container type is
extensible for further metadata in the future such as type info and
could easily be converted to a generic to generalize the underlying
value, e.g. to use jax arrays or similar.

Also added `ModelStateSpecification`, `ParameterRequest` as a way for
systems to specify their underlying state and shape as well as request
parameters that match that specification. However, this is not connected
to systems yet.

Currently the shapes are not utilized in simulation, but existing
engines/systems should work as is due to the simulate command reducing
parameters to scalars before calling `Simulator.run`
Added `SystemABC.requested_parameters()/model_state()` to allow systems
to provide information about their underlying state specification,
including shape, as well as request parameters that comply with said
requirements. Also integrated this work into the existing wrapper system
to demonstrate the functionality.

- Added `requested_parameters()/model_state()` methods to `SystemABC`. 
- Extended `wrap()`/`_AdapterSystem` to accept explicit parameter
  request and model state callbacks.
- Updated `_checked_partial()` so already materialized `ParameterValue`
  instances are preserved when binding static parameters.
- Simplified the documentation quick start wrapper config to the minimal
  valid example.
@TimothyWillard TimothyWillard force-pushed the parameter-rich-systems branch from 7d7f8a4 to 4f0a7ea Compare April 28, 2026 18:32
@TimothyWillard TimothyWillard marked this pull request as ready for review April 28, 2026 18:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants