Unitful getters and setters

[luke-kiernan]

Add unitful getters and setters. Interface:

get_active_power(gen) # errors: must specify units
get_active_power(gen, {NU/SU/DU}) # natural units/system base/device base, with units attached 
get_active_power(gen, Float64) # system base, no units attached: internal usage.

5 + get_active_power(gen, NU) # errors: unitless combined with unitful
5 MW + get_active_power(gen, NU) # ok
0.5 SU + get_active_power(gen, NU) # errors: relative combined with natural

set_active_power!(gen, 0.5) # errors: must specify units
set_active_power!(gen, 0.5 {SU/DU}) # system base/device base
set_active_power!(gen, 50 MW) # natural units

Relies on IS #574. This will break stuff downstream left and right, yes, but here's why I think it's worth it:

1. Usability. It is very very easy to unknowingly mix units. The classic one: read in a time series from a CSV in natural units, then attach it to a system in SYSTEM_BASE.
2. Type stability. Our stateful unit system is inherently type unstable.
3. Maintenance. After the catch-all "not having adequate test cases," I've found more bugs due to units issues than anything else.

edit: at the moment, turns out 1-argument getters/setters assume system base. But I'd prefer to have them error: better that than get silently incorrect results. Also, I'd consider adding a 3-arg setter, with the units separate: set_active_power!(gen, 1, {DU/SU/NU}

edit: You can still mess up by adding or comparing device-base quantities from components with different base powers. Same goes for comparing SU quantities between different systems.

[luke-kiernan]

Here is perhaps the biggest argument for these changes:

This is profiling "add up active powers on all thermal gens in the 10k bus system:"

function sum_su_strip(gens)
    s = 0.0
    for g in gens
        s += IS.ustrip(get_active_power(g, IS.SystemBaseUnit())) # change this line
    end
    return s
end

[luke-kiernan]

Change get_active_power etc. to be non-unitful. Move unitful ones to a different name. Setters are fine as-is.

Does mean for get-then-set you need:
set_active_power!(gen, get_active_power_unitful(gen, SU))

[luke-kiernan]

I plan to address #1128 (and am looking for some input on that issue), but otherwise this PR is pretty much finished.

The one other detail that comes to mind: once I go make a compatible branch of PSB, I could also reset those 3 unit tests to using PSB systems. (I currently have them using tiny systems we build here so that the tests pass.)

[luke-kiernan]

As I'm working my way through all the downstream packages, I'm finding a few more things here and there. I'll post the linked PRs here:

• PSB: #194 Basically done. Tests pass locally, but there's a few errors logged. Looks like they're pre-existing. Depends on #17 in PowerFlowFileParsers.jl
• PNM: #308. Done. All tests pass locally. edit: oh, there's merge conflicts.

[jd-lara]

Code review

Found 2 issues:

1. Four flow-limit helper accessors still call the single-argument getter forms that this PR removed, so they will throw MethodError at runtime. get_flow_limits and get_active_power_flow_limits now only exist in their two-argument (component, units) form (see AreaInterchange.jl#L91 and TransmissionInterface.jl#L68), but these callers were not migrated:

PowerSystems.jl/src/models/supplemental_accessors.jl

Lines 311 to 334 in 93c99a5

	"""
	function get_from_to_flow_limit(a::AreaInterchange)
	return get_flow_limits(a).from_to
	end
	"""
	Get the flow limits from destination [`Area`](@ref) to source [`Area`](@ref) for an [`AreaInterchange`](@ref).
	"""
	function get_to_from_flow_limit(a::AreaInterchange)
	return get_flow_limits(a).to_from
	end
	"""
	Get the minimum active power flow limit for a [`TransmissionInterface`](@ref).
	"""
	function get_min_active_power_flow_limit(tx::TransmissionInterface)
	return get_active_power_flow_limits(tx).min
	end
	"""
	Get the maximum active power flow limit for a [`TransmissionInterface`](@ref).
	"""
	function get_max_active_power_flow_limit(tx::TransmissionInterface)
	return get_active_power_flow_limits(tx).max
	end

2. The with_units_base docstring examples call the removed single-argument get_active_power(gen) form, so the documented usage would now error. Additionally, the new getters take units explicitly and no longer consult the unit state that with_units_base sets, so the docstring's behavior is stale.

PowerSystems.jl/src/base.jl

Lines 543 to 548 in 93c99a5

	```julia
	active_power_mw = with_units_base(sys, UnitSystem.NATURAL_UNITS) do
	get_active_power(gen)
	end
	# now active_power_mw is in natural units no matter what units base the system is in
	```

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}