Source code for mga_surveyor.normalize

"""Generic affine-map normalization: keeps a `Method`'s inner/outer
polytope confined to the unit cube `[-1, 1]^k`, regardless of how
differently-scaled the underlying dimensions are (e.g. MW vs MWh), by
wrapping `explore.drive`'s three oracle callbacks
(`FurthestPointFn`/`ClosestPointFn`/`OptimalPointFn`) with a per-dimension
affine map computed from the box points -- `explore.drive`/`Method` need
no changes at all; they just see oracle functions that happen to speak
normalized coordinates instead of real ones.

Finding the actual closest point under this normalized geometry isn't
just a coordinate relabeling, though: a plain L1/Linf objective over raw
real-unit residuals doesn't correspond to the cube-normalized notion of
distance unless each dimension's residual is weighted by the same
per-dimension scale this module computes (`AffineMap.weights`) --
`normalize_oracle_fns` only computes that scale, the actual weighting has
to happen inside whatever solves the closest-point problem itself (see
`mga_surveyor.pypsa_ext.make_closest_point_fn`'s own `weights` parameter).
Without it, the point found would be closest under real-unit distance,
not the cube-normalized distance `Method` is actually exploring under.

None of this is PyPSA-specific -- same independence as `explore.py`
itself, so it's usable against `mga_surveyor.tests.lp_region` or any
other oracle implementation too.
"""
from dataclasses import dataclass
from typing import Callable

import numpy as np

from .explore import ClosestPointFn, FurthestPointFn, OptimalPointFn, box_directions


[docs] @dataclass(frozen=True) class AffineMap: """Per-dimension affine map real <-> normalized: `normalized = weights * (real - center)`, where `weights = 1 / half_range` -- calibrated so `[center - half_range, center + half_range]` maps exactly onto `[-1, 1]` per dimension. """ center: np.ndarray half_range: np.ndarray @property def weights(self) -> np.ndarray: """`1 / half_range` -- what a point's own coordinates get scaled by (`to_normalized`/`to_real`), and what a closest-point solve's objective needs to weight each dimension's residual by for "closest" to mean the same thing in real units as it does in this normalized cube (see module docstring).""" return 1.0 / self.half_range
[docs] def to_normalized(self, point: np.ndarray) -> np.ndarray: return self.weights * (np.asarray(point, dtype=float) - self.center)
[docs] def to_real(self, point: np.ndarray) -> np.ndarray: return np.asarray(point, dtype=float) / self.weights + self.center
[docs] def normal_to_normalized(self, normal: np.ndarray) -> np.ndarray: """A halfspace normal transforms by the *inverse* of what a point does (`half_range`, not `weights`) -- it's a dual vector (a gradient), not a point, so it transforms by the map's inverse-transpose, which for this diagonal map is just its inverse again. Substituting `x = to_real(x')` into a real-space halfspace `{x : normal . (x - p) <= 0}` gives exactly `{x' : normal_to_normalized(normal) . (x' - to_normalized(p)) <= 0}` -- the same halfspace, re-expressed in normalized coordinates.""" return np.asarray(normal, dtype=float) * self.half_range
[docs] def compute_affine_map(box_points: np.ndarray, keys: list[str] | None = None, atol: float = 1e-9) -> AffineMap: """From the `2k` box-direction points `explore.drive`'s bootstrap already computes (rows `0..k-1` = the `+e_i` maximizers, rows `k..2k-1` = the `-e_i` minimizers -- `explore.drive`'s own `box_directions` ordering), read off each dimension's true achievable `[min, max]` directly: row `i`'s own `i`-th coordinate IS that dimension's max (maximizing `e_i . x` maximizes `x_i` alone, nothing else), row `k+i`'s IS its min. Calibrated exactly, not approximately -- each dimension's achievable range maps onto exactly `[-1, 1]`. `keys` (default `None`): dimension names, used only to name the offending dimension(s) in the error below -- purely cosmetic, optional so this stays usable without them. :raises ValueError: If any dimension's achievable range is (numerically) zero -- fixed at a single value under the current slack budget. There's nothing meaningful to rescale by for a fixed dimension (`weights = 1 / half_range` would be a division by zero), and a dimension with no achievable range at all has no reason to be in `dimensions` in the first place -- likely the underlying network component isn't actually extendable. Raised (not silently worked around) so this fails loudly instead of quietly producing `inf`/`nan` downstream. """ box_points = np.asarray(box_points, dtype=float) k = box_points.shape[0] // 2 maxes = np.array([box_points[i, i] for i in range(k)]) mins = np.array([box_points[k + i, i] for i in range(k)]) half_range = (maxes - mins) / 2 degenerate = np.where(half_range <= atol)[0] if len(degenerate): names = [keys[i] if keys is not None else f"dimension {i}" for i in degenerate] msg = ( f"{', '.join(names)} {'is' if len(names) == 1 else 'are'} fixed at a single value " f"under the current slack budget (no achievable range) -- normalize=True has nothing " f"meaningful to rescale by for a fixed dimension. Remove it from `dimensions` (e.g. make " f"the underlying component extendable) or run without normalize=True." ) raise ValueError(msg) return AffineMap(center=(maxes + mins) / 2, half_range=half_range)
[docs] def presolve_box_points(furthest_point: FurthestPointFn, k: int) -> tuple[FurthestPointFn, np.ndarray, np.ndarray]: """Solve the `2k` box directions exactly once, right now, and return a `FurthestPointFn` that just returns this same already-computed result instead of re-solving -- for any caller that needs the box points (or needs whatever side effects that one solve has, e.g. an `on_solve` callback baked into `furthest_point` itself, as `mga_surveyor.pypsa_ext.make_furthest_point_fn` supports) before `explore.drive`'s own bootstrap gets to them, without `explore.drive` ending up re-solving (and re-triggering those side effects) a second time for nothing. """ directions = box_directions(k) box_points, box_normals = furthest_point(directions) box_points = np.asarray(box_points, dtype=float) box_normals = np.asarray(box_normals, dtype=float) def furthest_point_reused(directions: np.ndarray) -> tuple[np.ndarray, np.ndarray]: # Only ever called by drive() with exactly these same # box_directions (its docstring: "called once ... for # bootstrapping only") -- nothing to resolve. del directions return box_points, box_normals return furthest_point_reused, box_points, box_normals
[docs] def normalize_from_box_points( box_points: np.ndarray, box_normals: np.ndarray, make_closest_point: Callable[[np.ndarray], ClosestPointFn], optimal_fn: OptimalPointFn, keys: list[str] | None = None, ) -> tuple[FurthestPointFn, ClosestPointFn, OptimalPointFn, AffineMap]: """The rest of `normalize_oracle_fns`, split out for a caller that already has `box_points`/`box_normals` in hand (e.g. from its own `presolve_box_points` call, made for some other reason too -- like filtering candidate halfspaces against the box ones before they ever reach `Method.add_cut`) and doesn't want a second, redundant solve of the same `2k` directions. `make_closest_point(weights) -> ClosestPointFn` is a factory, not a ready-made `ClosestPointFn`, because the right weights (this `AffineMap`'s own `weights`) are only known once `box_points` are in hand -- see `mga_surveyor.pypsa_ext.make_closest_point_fn`'s own `weights` parameter for what those actually do to its objective. `keys` (default `None`): dimension names, passed straight through to `compute_affine_map` -- purely cosmetic, only used to name the offending dimension if it raises. Returns `(furthest_point_n, closest_point_n, optimal_fn_n, affine_map)` -- the wrapped trio, plus the `AffineMap` itself for a caller that needs to convert points already in real units (e.g. `extra_points`/`extra_halfspaces` from an earlier, interrupted run) into this same normalized space before folding them into `explore.drive`'s bootstrap. :raises ValueError: If any dimension has no achievable range (see `compute_affine_map`). """ affine_map = compute_affine_map(box_points, keys) closest_point = make_closest_point(affine_map.weights) def furthest_point_n(directions: np.ndarray) -> tuple[np.ndarray, np.ndarray]: del directions return ( np.array([affine_map.to_normalized(p) for p in box_points]), np.array([affine_map.normal_to_normalized(n) for n in box_normals]), ) def closest_point_n(target: np.ndarray) -> tuple[np.ndarray, np.ndarray]: point, normal = closest_point(affine_map.to_real(target)) return affine_map.to_normalized(point), affine_map.normal_to_normalized(normal) def optimal_fn_n() -> np.ndarray: return affine_map.to_normalized(optimal_fn()) return furthest_point_n, closest_point_n, optimal_fn_n, affine_map
[docs] def normalize_oracle_fns( furthest_point: FurthestPointFn, make_closest_point: Callable[[np.ndarray], ClosestPointFn], optimal_fn: OptimalPointFn, k: int, keys: list[str] | None = None, ) -> tuple[FurthestPointFn, ClosestPointFn, OptimalPointFn, AffineMap]: """Wrap the three `explore.drive` oracle callbacks so they speak normalized `[-1, 1]^k` coordinates instead of real units -- `explore.drive`/`Method` need no changes at all, they just see functions matching the same three protocols. Solves the `2k` box directions exactly once, here (`presolve_box_points`) -- `explore.drive`'s own bootstrap never needs to. A thin convenience wrapper over `presolve_box_points` + `normalize_from_box_points`, for a caller that doesn't need `box_points`/`box_normals` for anything else; see `normalize_from_box_points` for one that does. :raises ValueError: If any dimension has no achievable range (see `compute_affine_map`). """ _furthest_point_reused, box_points, box_normals = presolve_box_points(furthest_point, k) return normalize_from_box_points(box_points, box_normals, make_closest_point, optimal_fn, keys)