fix PR issues and docs

jd-lara · jd-lara · commit e8f7f2780261 · 2026-05-28T18:10:55.000-06:00
diff --git a/docs/make.jl b/docs/make.jl
@@ -75,6 +75,7 @@ pages = OrderedDict(
             "explanation/dynamic_data.md",
             "explanation/supplemental_attributes.md",
             "explanation/plant_attributes.md",
+            "explanation/emissions_data.md",
             ],
         "Model Library" => Any[],
         "Reference" =>
diff --git a/docs/src/api/public.md b/docs/src/api/public.md
@@ -36,7 +36,8 @@ Modules = [PowerSystems]
 Pages   = ["outages.jl",
            "contingencies.jl",
            "impedance_correction.jl",
-           "plant_attribute.jl"
+           "plant_attribute.jl",
+           "emissions_data.jl"
            ]
 Public = true
 Private = false
diff --git a/docs/src/explanation/emissions_data.md b/docs/src/explanation/emissions_data.md
@@ -53,9 +53,9 @@ The `emission_rate` field accepts any [`ValueCurve`](@ref) subtype, typically an
 [`IncrementalCurve`](@ref) representing the emission rate (pollutant per unit of
 fuel or power):
 
-- **`IncrementalCurve(LinearFunctionData(0, rate), ...)`** — constant emission rate
-- **`IncrementalCurve(LinearFunctionData(slope, intercept), ...)`** — linearly varying rate
-- **`IncrementalCurve(PiecewiseStepData(...), ...)`** — piecewise step rate (`PiecewiseIncrementalCurve`)
+  - **`IncrementalCurve(LinearFunctionData(0, rate), ...)`** — constant emission rate
+  - **`IncrementalCurve(LinearFunctionData(slope, intercept), ...)`** — linearly varying rate
+  - **`IncrementalCurve(PiecewiseStepData(...), ...)`** — piecewise step rate (`PiecewiseIncrementalCurve`)
 
 When constructing with a scalar `Real` value, the rate is automatically wrapped in an
 `IncrementalCurve` with constant rate. This makes simple constant-rate cases ergonomic
@@ -73,9 +73,9 @@ tie it to the start binary variable in the unit commitment formulation).
 
 The following features are out of scope for this version and tracked in follow-up issues:
 
-- Time-varying emission rates (time series support)
-- Hot/warm/cold split of the start-up adder
-- `EmissionsCap` and `EmissionsPrice` supplemental attribute types
-- Removal rate / pollution control fraction
-- PowerSimulations.jl integration
-- Parser support (CSV, Matpower, PSS/E, RTS data format)
+  - Time-varying emission rates (time series support)
+  - Hot/warm/cold split of the start-up adder
+  - `EmissionsCap` and `EmissionsPrice` supplemental attribute types
+  - Removal rate / pollution control fraction
+  - PowerSimulations.jl integration
+  - Parser support (CSV, Matpower, PSS/E, RTS data format)
diff --git a/src/PowerSystems.jl b/src/PowerSystems.jl
@@ -346,6 +346,11 @@ export get_gwp
 export set_emission_rate!
 export set_start_up_adder!
 export set_gwp!
+export set_pollutant!
+export set_mass_unit!
+export set_basis!
+export set_energy_unit!
+export set_basis_and_energy_unit!
 
 export Service
 export AbstractReserve
diff --git a/src/emissions_data.jl b/src/emissions_data.jl
@@ -43,12 +43,6 @@ function _validate_nonneg_finite(val::Real, field::String)
     end
 end
 
-function _validate_pos_finite(val::Real, field::String)
-    if !isfinite(val) || val <= 0.0
-        throw(ArgumentError("$field must be finite and > 0.0, got $val"))
-    end
-end
-
 function _validate_basis_energy_unit(basis::EmissionBasis, energy_unit::EnergyUnit)
     if basis == EmissionBasis.FUEL_INPUT
         if energy_unit != EnergyUnit.MMBTU && energy_unit != EnergyUnit.GJ
@@ -66,9 +60,63 @@ function _validate_basis_energy_unit(basis::EmissionBasis, energy_unit::EnergyUn
                 ),
             )
         end
+    else
+        throw(
+            ArgumentError(
+                "unhandled EmissionBasis $basis; update _validate_basis_energy_unit",
+            ),
+        )
     end
 end
 
+# Emission-rate helpers (shared between constructor and setters)
+
+"""Wrap a scalar emission rate in a constant-rate `IncrementalCurve` after validation."""
+function _emission_rate_curve(val::Real)
+    _validate_nonneg_finite(val, "emission_rate")
+    return IS.IncrementalCurve(LinearFunctionData(0.0, Float64(val)), nothing, nothing)
+end
+
+"""
+Validate that an `emission_rate` [`ValueCurve`](@ref) holds only finite coefficients and
+non-negative rate values (the rate at zero input and every tabulated rate must be `>= 0`).
+"""
+function _validate_emission_rate_curve(curve::IS.ValueCurve)
+    _validate_emission_rate_function_data(get_function_data(curve))
+    return
+end
+
+function _validate_emission_rate_function_data(fd::LinearFunctionData)
+    _validate_nonneg_finite(get_constant_term(fd), "emission_rate (rate at zero input)")
+    isfinite(get_proportional_term(fd)) || throw(
+        ArgumentError(
+            "emission_rate slope must be finite, got $(get_proportional_term(fd))",
+        ),
+    )
+    return
+end
+
+function _validate_emission_rate_function_data(fd::QuadraticFunctionData)
+    _validate_nonneg_finite(get_constant_term(fd), "emission_rate (rate at zero input)")
+    for term in (get_proportional_term(fd), get_quadratic_term(fd))
+        isfinite(term) ||
+            throw(ArgumentError("emission_rate coefficients must be finite, got $term"))
+    end
+    return
+end
+
+function _validate_emission_rate_function_data(
+    fd::Union{PiecewiseLinearData, PiecewiseStepData},
+)
+    for r in get_y_coords(fd)
+        _validate_nonneg_finite(r, "emission_rate")
+    end
+    return
+end
+
+# Safe fallback for any future FunctionData subtype not enumerated above.
+_validate_emission_rate_function_data(::IS.FunctionData) = nothing
+
 """
     EmissionsData(; name, pollutant, emission_rate, basis, energy_unit, ...)
 
@@ -92,20 +140,16 @@ function EmissionsData(;
     internal::InfrastructureSystemsInternal = InfrastructureSystemsInternal(),
 )
     _validate_nonneg_finite(start_up_adder, "start_up_adder")
-    _validate_pos_finite(gwp, "gwp")
+    _validate_nonneg_finite(gwp, "gwp")
 
     # Validate basis/energy_unit combination
     _validate_basis_energy_unit(basis, energy_unit)
 
-    # Convert scalar to IncrementalCurve with constant rate
+    # Normalize emission_rate to a validated ValueCurve
     if emission_rate isa Real
-        _validate_nonneg_finite(emission_rate, "emission_rate")
-        rate = IS.IncrementalCurve(
-            LinearFunctionData(0.0, Float64(emission_rate)),
-            nothing,
-            nothing,
-        )
+        rate = _emission_rate_curve(emission_rate)
     else
+        _validate_emission_rate_curve(emission_rate)
         rate = emission_rate
     end
 
@@ -152,15 +196,14 @@ get_internal(value::EmissionsData) = value.internal
 
 """Set [`EmissionsData`](@ref) `emission_rate` with a [`ValueCurve`](@ref)."""
 function set_emission_rate!(value::EmissionsData, val::IS.ValueCurve)
+    _validate_emission_rate_curve(val)
     value.emission_rate = val
     return
 end
 
 """Set [`EmissionsData`](@ref) `emission_rate` with a scalar (wraps in `IncrementalCurve` with constant rate)."""
 function set_emission_rate!(value::EmissionsData, val::Real)
-    _validate_nonneg_finite(val, "emission_rate")
-    value.emission_rate =
-        IS.IncrementalCurve(LinearFunctionData(0.0, Float64(val)), nothing, nothing)
+    value.emission_rate = _emission_rate_curve(val)
     return
 end
 
@@ -179,7 +222,54 @@ end
 
 """Set [`EmissionsData`](@ref) `gwp`."""
 function set_gwp!(value::EmissionsData, val::Real)
-    _validate_pos_finite(val, "gwp")
+    _validate_nonneg_finite(val, "gwp")
     value.gwp = Float64(val)
     return
 end
+
+"""Set [`EmissionsData`](@ref) `pollutant`."""
+function set_pollutant!(value::EmissionsData, val::PollutantType)
+    value.pollutant = val
+    return
+end
+
+"""Set [`EmissionsData`](@ref) `mass_unit`."""
+function set_mass_unit!(value::EmissionsData, val::MassUnit)
+    value.mass_unit = val
+    return
+end
+
+"""
+Set [`EmissionsData`](@ref) `basis`, validating it against the current `energy_unit`. To
+switch between FUEL_INPUT and POWER_OUTPUT (which also requires changing `energy_unit`),
+use [`set_basis_and_energy_unit!`](@ref) instead.
+"""
+function set_basis!(value::EmissionsData, val::EmissionBasis)
+    _validate_basis_energy_unit(val, value.energy_unit)
+    value.basis = val
+    return
+end
+
+"""Set [`EmissionsData`](@ref) `energy_unit`, validating it against the current `basis`."""
+function set_energy_unit!(value::EmissionsData, val::EnergyUnit)
+    _validate_basis_energy_unit(value.basis, val)
+    value.energy_unit = val
+    return
+end
+
+"""
+Set [`EmissionsData`](@ref) `basis` and `energy_unit` together, validating the combination.
+This is the supported way to retarget an attribute between FUEL_INPUT and POWER_OUTPUT,
+since neither field can be changed individually without transiently violating the
+basis/energy_unit invariant.
+"""
+function set_basis_and_energy_unit!(
+    value::EmissionsData,
+    basis::EmissionBasis,
+    energy_unit::EnergyUnit,
+)
+    _validate_basis_energy_unit(basis, energy_unit)
+    value.basis = basis
+    value.energy_unit = energy_unit
+    return
+end
diff --git a/test/test_emissions_data.jl b/test/test_emissions_data.jl
@@ -93,14 +93,25 @@
             start_up_adder = -0.5,
         )
 
-        # Zero gwp
+        # Zero gwp is allowed (e.g. a pollutant excluded from CO2-equivalent accounting)
+        zero_gwp = EmissionsData(;
+            name = "zero_gwp",
+            pollutant = PollutantType.SO2,
+            emission_rate = 1.0,
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+            gwp = 0.0,
+        )
+        @test get_gwp(zero_gwp) == 0.0
+
+        # Negative gwp is rejected
         @test_throws ArgumentError EmissionsData(;
             name = "bad",
             pollutant = PollutantType.CO2,
             emission_rate = 1.0,
             basis = EmissionBasis.FUEL_INPUT,
             energy_unit = EnergyUnit.MMBTU,
-            gwp = 0.0,
+            gwp = -1.0,
         )
 
         # MWH with FUEL_INPUT
@@ -167,6 +178,103 @@
         @test_throws ArgumentError set_gwp!(e, Inf)
     end
 
+    @testset "ValueCurve emission_rate validation" begin
+        # Negative constant rate (rate at zero input < 0)
+        @test_throws ArgumentError EmissionsData(;
+            name = "bad",
+            pollutant = PollutantType.CO2,
+            emission_rate = IS.IncrementalCurve(
+                LinearFunctionData(0.0, -5.0), nothing, nothing,
+            ),
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+        )
+
+        # Non-finite slope
+        @test_throws ArgumentError EmissionsData(;
+            name = "bad",
+            pollutant = PollutantType.CO2,
+            emission_rate = IS.IncrementalCurve(
+                LinearFunctionData(Inf, 1.0), nothing, nothing,
+            ),
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+        )
+
+        # Negative piecewise step rate
+        @test_throws ArgumentError EmissionsData(;
+            name = "bad",
+            pollutant = PollutantType.SO2,
+            emission_rate = IS.IncrementalCurve(
+                PiecewiseStepData([0.0, 100.0, 200.0], [50.0, -10.0]),
+                0.0,
+                nothing,
+            ),
+            basis = EmissionBasis.POWER_OUTPUT,
+            energy_unit = EnergyUnit.MWH,
+        )
+
+        # A decreasing-but-non-negative-at-origin linear rate is allowed
+        ok = EmissionsData(;
+            name = "ok",
+            pollutant = PollutantType.NOX,
+            emission_rate = IS.IncrementalCurve(
+                LinearFunctionData(-0.001, 5.0), nothing, nothing,
+            ),
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+        )
+        @test get_emission_rate(ok) ==
+              IS.IncrementalCurve(LinearFunctionData(-0.001, 5.0), nothing, nothing)
+
+        # Setter rejects an invalid ValueCurve too
+        e = EmissionsData(;
+            name = "setter_curve",
+            pollutant = PollutantType.CO2,
+            emission_rate = 1.0,
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+        )
+        @test_throws ArgumentError set_emission_rate!(
+            e,
+            IS.IncrementalCurve(LinearFunctionData(0.0, -1.0), nothing, nothing),
+        )
+    end
+
+    @testset "Validated setters for enum fields" begin
+        e = EmissionsData(;
+            name = "setters",
+            pollutant = PollutantType.CO2,
+            emission_rate = 1.0,
+            basis = EmissionBasis.FUEL_INPUT,
+            energy_unit = EnergyUnit.MMBTU,
+        )
+
+        set_pollutant!(e, PollutantType.NOX)
+        @test get_pollutant(e) == PollutantType.NOX
+
+        set_mass_unit!(e, MassUnit.LB)
+        @test get_mass_unit(e) == MassUnit.LB
+
+        # Valid energy_unit change within FUEL_INPUT (MMBTU -> GJ)
+        set_energy_unit!(e, EnergyUnit.GJ)
+        @test get_energy_unit(e) == EnergyUnit.GJ
+
+        # Individual setters enforce the basis/energy_unit invariant
+        @test_throws ArgumentError set_basis!(e, EmissionBasis.POWER_OUTPUT)
+        @test_throws ArgumentError set_energy_unit!(e, EnergyUnit.MWH)
+
+        # Combined setter is the supported way to switch basis + energy_unit atomically
+        set_basis_and_energy_unit!(e, EmissionBasis.POWER_OUTPUT, EnergyUnit.MWH)
+        @test get_basis(e) == EmissionBasis.POWER_OUTPUT
+        @test get_energy_unit(e) == EnergyUnit.MWH
+
+        # Combined setter still rejects an inconsistent pair
+        @test_throws ArgumentError set_basis_and_energy_unit!(
+            e, EmissionBasis.FUEL_INPUT, EnergyUnit.MWH,
+        )
+    end
+
     @testset "Default mass_unit is KG" begin
         e = EmissionsData(;
             name = "test_defaults",
