Add abs(), diff() support to PhysicalValue (#262)

Author: akhilles

crates/pcb-sch/src/physical.rs

@@ -225,6 +225,24 @@ impl PhysicalValue {
         self.fits_within(other, default_tolerance)
     }
 
+    /// Get the absolute value of this physical value
+    pub fn abs(&self) -> PhysicalValue {
+        PhysicalValue {
+            value: self.value.abs(),
+            tolerance: self.tolerance,
+            unit: self.unit,
+        }
+    }
+
+    /// Get the absolute difference between two physical values
+    /// Returns an error if units don't match
+    pub fn diff(&self, other: &PhysicalValue) -> Result<PhysicalValue, PhysicalValueError> {
+        // Use the subtraction operator which validates units
+        let result = (*self - *other)?;
+        // Return the absolute value
+        Ok(result.abs())
+    }
+
     fn fields() -> SortedMap<String, Ty> {
         fn single_param_spec(param_type: Ty) -> ParamSpec {
             ParamSpec::new_parts([(ParamIsRequired::Yes, param_type)], [], None, [], None).unwrap()
@@ -234,6 +252,8 @@ impl PhysicalValue {
         let with_tolerance_param_spec = single_param_spec(Ty::union2(Ty::float(), Ty::string()));
         let with_value_param_spec = single_param_spec(Ty::union2(Ty::float(), Ty::int()));
         let with_unit_param_spec = single_param_spec(Ty::union2(Ty::string(), Ty::none()));
+        let diff_param_spec = single_param_spec(PhysicalValue::get_type_starlark_repr());
+        let abs_param_spec = single_param_spec(PhysicalValue::get_type_starlark_repr());
 
         SortedMap::from_iter([
             ("value".to_string(), Ty::float()),
@@ -264,6 +284,14 @@ impl PhysicalValue {
                     PhysicalValue::get_type_starlark_repr(),
                 ),
             ),
+            (
+                "abs".to_string(),
+                Ty::callable(abs_param_spec, PhysicalValue::get_type_starlark_repr()),
+            ),
+            (
+                "diff".to_string(),
+                Ty::callable(diff_param_spec, PhysicalValue::get_type_starlark_repr()),
+            ),
         ])
     }
 
@@ -1029,6 +1057,32 @@ fn physical_value_methods(methods: &mut MethodsBuilder) {
             new_unit,
         ))
     }
+
+    fn abs<'v>(
+        this: &PhysicalValue,
+        #[starlark(require = pos)] _arg: Value<'v>,
+    ) -> starlark::Result<PhysicalValue> {
+        Ok(this.abs())
+    }
+
+    fn diff<'v>(
+        this: &PhysicalValue,
+        #[starlark(require = pos)] other: Value<'v>,
+    ) -> starlark::Result<PhysicalValue> {
+        let other_pv = PhysicalValue::try_from(other).map_err(|_| {
+            PhysicalValueError::InvalidArgumentType {
+                unit: this.unit.quantity(),
+            }
+        })?;
+        this.diff(&other_pv).map_err(|err| {
+            PhysicalValueError::SubtractionError {
+                lhs_unit: this.unit.quantity(),
+                rhs_unit: other_pv.unit.quantity(),
+                error: err.to_string(),
+            }
+            .into()
+        })
+    }
 }
 
 #[starlark_value(type = "PhysicalValue")]
@@ -3109,4 +3163,92 @@ mod tests {
         assert_eq!(range.max, Decimal::from(10));
         assert_eq!(range.nominal, Some(Decimal::from(5)));
     }
+
+    #[test]
+    fn test_abs_positive_value() {
+        let pv = physical_value(3.3, 0.0, PhysicalUnit::Volts);
+        let result = pv.abs();
+        assert_eq!(result.value, Decimal::from_f64(3.3).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Volts.into());
+        assert_eq!(result.tolerance, Decimal::ZERO);
+    }
+
+    #[test]
+    fn test_abs_negative_value() {
+        let pv = physical_value(-3.3, 0.0, PhysicalUnit::Volts);
+        let result = pv.abs();
+        assert_eq!(result.value, Decimal::from_f64(3.3).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Volts.into());
+        assert_eq!(result.tolerance, Decimal::ZERO);
+    }
+
+    #[test]
+    fn test_abs_preserves_tolerance() {
+        let pv = physical_value(-5.0, 0.05, PhysicalUnit::Amperes);
+        let result = pv.abs();
+        assert_eq!(result.value, Decimal::from_f64(5.0).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Amperes.into());
+        assert_eq!(result.tolerance, Decimal::from_f64(0.05).unwrap());
+    }
+
+    #[test]
+    fn test_diff_positive_difference() {
+        let pv1 = physical_value(10.0, 0.0, PhysicalUnit::Volts);
+        let pv2 = physical_value(3.0, 0.0, PhysicalUnit::Volts);
+        let result = pv1.diff(&pv2).unwrap();
+        assert_eq!(result.value, Decimal::from_f64(7.0).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Volts.into());
+        assert_eq!(result.tolerance, Decimal::ZERO);
+    }
+
+    #[test]
+    fn test_diff_negative_difference_returns_positive() {
+        let pv1 = physical_value(3.0, 0.0, PhysicalUnit::Volts);
+        let pv2 = physical_value(10.0, 0.0, PhysicalUnit::Volts);
+        let result = pv1.diff(&pv2).unwrap();
+        assert_eq!(result.value, Decimal::from_f64(7.0).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Volts.into());
+        assert_eq!(result.tolerance, Decimal::ZERO);
+    }
+
+    #[test]
+    fn test_diff_unit_mismatch() {
+        let pv1 = physical_value(10.0, 0.0, PhysicalUnit::Volts);
+        let pv2 = physical_value(3.0, 0.0, PhysicalUnit::Amperes);
+        let result = pv1.diff(&pv2);
+        assert!(result.is_err());
+        assert!(matches!(
+            result.unwrap_err(),
+            PhysicalValueError::UnitMismatch { .. }
+        ));
+    }
+
+    #[test]
+    fn test_diff_drops_tolerance() {
+        // Based on subtraction behavior, diff should drop tolerance
+        let pv1 = physical_value(10.0, 0.1, PhysicalUnit::Volts);
+        let pv2 = physical_value(3.0, 0.05, PhysicalUnit::Volts);
+        let result = pv1.diff(&pv2).unwrap();
+        assert_eq!(result.value, Decimal::from_f64(7.0).unwrap());
+        assert_eq!(result.tolerance, Decimal::ZERO);
+    }
+
+    #[test]
+    fn test_diff_with_string_conversion() {
+        // Test that diff works when the other value is parsed from a string
+        use starlark::values::Heap;
+
+        let heap = Heap::new();
+        let pv1 = heap.alloc(physical_value(3.3, 0.0, PhysicalUnit::Volts));
+        let pv2_str = heap.alloc("5V");
+
+        // Convert string to PhysicalValue
+        let pv2 = PhysicalValue::try_from(pv2_str).unwrap();
+        let pv1_val = PhysicalValue::try_from(pv1).unwrap();
+
+        // Test diff
+        let result = pv1_val.diff(&pv2).unwrap();
+        assert_eq!(result.value, Decimal::from_f64(1.7).unwrap());
+        assert_eq!(result.unit, PhysicalUnit::Volts.into());
+    }
 }

docs/pages/spec.mdx

@@ -815,6 +815,133 @@ main_rail = PowerRail("MAIN_RAIL",
 
 **Returns:** A callable net type constructor that creates typed net instances
 
+### builtin.physical_value(unit)
+
+**Built-in function** that creates unit-specific physical value constructor types for electrical quantities with optional tolerances.
+
+```python
+# Create physical value constructors for different units
+Voltage = builtin.physical_value("V")
+Current = builtin.physical_value("A")
+Resistance = builtin.physical_value("Ohm")
+Capacitance = builtin.physical_value("F")
+Inductance = builtin.physical_value("H")
+Frequency = builtin.physical_value("Hz")
+Temperature = builtin.physical_value("K")
+Time = builtin.physical_value("s")
+Power = builtin.physical_value("W")
+
+# Use the constructors to create physical values
+supply = Voltage("3.3V")
+current = Current("100mA")
+resistor = Resistance("4k7")  # 4.7kΩ using resistor notation
+
+# With tolerance
+precise_voltage = Voltage("3.3V").with_tolerance("5%")  # 3.3V ±5%
+loose_resistor = Resistance("10kOhm").with_tolerance(0.1)  # ±10%
+```
+
+**Parameters:**
+
+- `unit`: String identifier for the physical unit (e.g., `"V"`, `"A"`, `"Ohm"`, `"F"`, `"H"`, `"Hz"`, `"K"`, `"s"`, `"W"`)
+
+**Returns:** A `PhysicalValueType` that can be called to create `PhysicalValue` instances
+
+**Standard Usage:**
+
+This builtin is typically accessed through `@stdlib/units.zen`, which provides pre-defined constructors:
+
+```python
+load("@stdlib/units.zen", "Voltage", "Current", "Resistance", "unit")
+
+# Create physical values
+v = unit("3.3V", Voltage)
+i = unit("100mA", Current)
+
+# Perform calculations - units are tracked automatically
+p = v * i  # Power = Voltage × Current (330mW)
+r = v / i  # Resistance = Voltage / Current (33Ω)
+```
+
+**Physical Value Methods:**
+
+Physical values support several methods for manipulation:
+
+- `.with_tolerance(tolerance)` - Returns a new physical value with updated tolerance
+  - `tolerance`: String like `"5%"` or decimal like `0.05`
+- `.with_value(value)` - Returns a new physical value with updated numeric value
+  - `value`: Numeric value (int or float)
+- `.with_unit(unit)` - Returns a new physical value with updated unit (for unit conversion/casting)
+  - `unit`: String unit identifier or `None` for dimensionless
+- `.abs()` - Returns the absolute value of the physical value, preserving unit and tolerance
+  - No parameters required
+- `.diff(other)` - Returns the absolute difference between two physical values
+  - `other`: Another PhysicalValue or string (e.g., `"5V"`) to compare against
+  - Units must match or an error is raised
+  - Always returns a positive value
+  - Tolerance is dropped (consistent with subtraction behavior)
+
+**Attributes:**
+
+- `.value` - The numeric value as a float
+- `.tolerance` - The tolerance as a decimal fraction (e.g., 0.05 for 5%)
+- `.unit` - The unit string representation
+
+**Mathematical Operations:**
+
+Physical values support arithmetic with automatic unit tracking:
+
+```python
+# Multiplication - units multiply dimensionally
+power = Voltage("3.3V") * Current("0.5A")  # 1.65W
+
+# Division - units divide dimensionally
+resistance = Voltage("5V") / Current("100mA")  # 50Ω
+
+# Addition - requires matching units
+total = Voltage("3.3V") + Voltage("5V")  # 8.3V
+
+# Subtraction - requires matching units
+delta = Voltage("5V") - Voltage("3.3V")  # 1.7V
+
+# Absolute value
+abs_voltage = Voltage("-3.3V").abs()  # 3.3V
+
+# Difference (always positive)
+diff = Voltage("3.3V").diff(Voltage("5V"))  # 1.7V
+diff_str = Voltage("3.3V").diff("5V")       # 1.7V (strings are auto-converted)
+```
+
+**Note:** All arithmetic operations and methods automatically convert string arguments to physical values when possible. For example, `Voltage("3.3V") + "2V"` works and returns `5.3V`.
+
+**Tolerance Handling:**
+
+- Multiplication/Division: Tolerance preserved only for dimensionless scaling (e.g., `2 * 3.3V±1%` keeps 1%)
+- Addition/Subtraction: Tolerance is always dropped
+- `.abs()`: Tolerance is preserved
+- `.diff()`: Tolerance is dropped (consistent with subtraction)
+
+**Parsing Support:**
+
+Physical value constructors accept flexible string formats:
+
+```python
+# Basic format with units
+Voltage("3.3V")
+Current("100mA")
+
+# SI prefixes: m, μ/u, n, p, k, M, G
+Capacitance("100nF")
+Resistance("4.7kOhm")
+
+# Resistor notation (4k7 = 4.7kΩ)
+Resistance("4k7")
+
+# Temperature conversions
+Temperature("25C")   # Converts to Kelvin
+Temperature("77F")   # Converts to Kelvin
+```
+
 ### builtin.physical_range(unit)
 
 **Built-in function** that creates unit-specific range constructor types for defining bounded physical value ranges.