Add support for multidimensional metrics

[kzscisoft]

Add Support for Tensor Metrics

Issue: #833

Python Version(s) Tested: 3.13

Operating System(s): Ubuntu 25.04

Documentation PR: https://github.com/simvue-io/docs/pull/77

📝 Summary

Allows the user to define a grid and then log tensors as metrics (or multidimensional metrics) to that grid.

🔄 Changes

Low Level API

• Creation of Grid class for defining a new grid:

grid = Grid.new(
    name="my_grid",
    grid=numpy.vstack([
        numpy.linspace(0, 10, 10),
        numpy.linspace(10, 20, 10)
    ]),
    labels=["x", "y"]
)
grid.attach_metric_for_run(run_id, "A")

• Creation of GridMetrics class for logging metrics across multiple grids for a given run:

metrics = GridMetrics.new(
    run=run_id,
    data=[
        {
            "timestamp": datetime.datetime.now(datetime.timezone.utc).strftime(
                "%Y-%m-%dT%H:%M:%S.%f"
            ),
            "time": _time,
            "step": _step,
            "array": numpy.ones((10, 10)),
            "grid_identifier": _grid.id,
            "metric": "A"
        }
    ],
)

User API

For the user, log_metrics has been updated to allow numpy arrays as metric values, the user must firstly assign or create a grid for that metric:

run.assign_metric_to_grid(
    metric_name="A",
    grid_name="base_grid",
    axes_ticks=numpy.vstack([
        numpy.linspace(0, 10, 10),
        numpy.linspace(10, 20, 10)
    ]),
    axes_labels=["x", "y"]
)
run.log_metrics({"x": 2, "A": numpy.ones((10, 10))}

Note if the user does not specify axes_ticks and axes_labels it is assumed the grid already exists.

✔️ Checklist

• Unit and integration tests passing.
• Pre-commit hooks passing.
• Quality checks passing.
• Updated the documentation.

[wk9874]

This is not a full review since I'm encountering the bug which I've left as a comment, so haven't yet tested if it works correctly

[wk9874]

What happens if the run id is not found in the mapping?

(should never happen, but I think that is the cause of the offline metrics issue which is plaguing us)

[kzscisoft]

Added additional raise statement

[wk9874]

What does this function do? Are the values the ticks? In which case why do we need step as my understanding is the grid axes should be fixed throughout right?

[kzscisoft]

It returns the values at a given step from a grid for a given run and metric, missing parameters and wrong so modified now

[wk9874]

Also what is the span?

[kzscisoft]

@alahiff I think you would be able to explain this better

[wk9874]

Should grids be created before runs? Wont they require a run ID to attach to?

[kzscisoft]

No Grid.new does not require a run, the attachment happens later, and can only happen if a run is available.

[wk9874]

But in offline mode, attach_to_run is called inside on_reconnect, which will be called when the sender tries to send the grid. Meaning if the cache contains a run and a grid, it will try to connect the grid to a run which does not yet exist, since the run has not yet been sent

[wk9874]

@kzscisoft does the client work for getting 2D metrics?

[wk9874]

Looks good to me!

Please open a new PR on the docs repo to compliment this. In particular, please mention that the shape of 2D metrics may be unexpected - axes are expected in (x, y) format, while data is in (row, column) format.