Skip to content

Unitful getters and setters for natural units #1810

Description

@luke-kiernan

Several PSY structs have fields in fixed natural units. How do we want to handle them? 3 options:

  1. Units required: support get_foo(comp, unit) and get_foo_unitful(comp, unit).
  2. Units optional: get_foo(comp), get_foo(comp, unit) (convert, returns float), and get_foo_unitful(comp, unit) (convert, returns unitful) are all accepted.
  3. Units not supported [current]: support get_foo(comp) only.

Moreover, we don't have to pick the same thing for every single field: we could have some where units are not supported, and others where units are optional.

Pros of 1: uniformity. get_active_power requires units.
Pros of 2: the best of both worlds. Units, but only when you want them; reverse-compatible.
Pros of 3: lowest effort.

Here's a sampling of the various things that are in natural units:

Struct Field Quantity type Natural units
ACBus base_voltage voltage (base) kV
ACBus angle voltage phase angle rad
ThermalStandard time_limits time (min up/down) min
several base_power apparent power (base) MVA
Line angle_limits angle difference rad
HydroTurbine powerhouse_elevation elevation (length) m
TwoTerminalLCCLine scheduled_dc_voltage DC voltage kV

I tend towards "units optional" everywhere, or almost everywhere (might be a few edge cases where it's a headache).

Activity

  1. self-assigned this
    on Sep 29, 2026
  2. kdayday commented on Sep 29, 2026

    @kdayday
    Contributor

    I think 2 is a good idea. I think the most important one to include is things that are durations; the schema is in min, but some operational durations (such as time_limits) are more commonly (and currently in PSY) defined in hours. Would be great to have a NU interface to handle that, and also keep the default user-facing side in hours instead of switching it to min.

    Some of these are likely not important, like rad category, but if we're going to do it for durations, then I think there's no harm in having AI do it for most of them. Then people can double-check their values are stored correctly if they want to.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions