defoundry 0.1.0__py3-none-any.whl

defoundry-0.1.0.dist-info/METADATA

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: defoundry
+Version: 0.1.0
+Summary: Composable Differential Evolution optimizer
+Author: Honza
+License-Expression: MIT
+Project-URL: Repository, https://github.com/vrbaj/differential_evolution
+Project-URL: Issues, https://github.com/vrbaj/differential_evolution/issues
+Keywords: optimization,differential-evolution,global-optimization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: mypy>=1.10; extra == "test"
+Requires-Dist: ruff>=0.6; extra == "test"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Provides-Extra: docs
+Requires-Dist: Sphinx<9,>=8; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex<3,>=2.6; extra == "docs"
+Requires-Dist: sphinx-rtd-theme<4,>=3; extra == "docs"
+Dynamic: license-file
+
+# DEFoundry — Differential Evolution
+
+This repository now provides a small, explicit Differential Evolution package with independently composable mutation strategies and crossover operators.
+
+## What changed
+
+- The optimizer is now a real Python package: `differential_evolution/`
+- Mutation and crossover are separate components
+- Randomness is explicit and reproducible
+- A deterministic test suite verifies formulas and DE invariants
+- The original `main.py`, `population_initialization.py`, and `testing_functions.py` remain as compatibility shims
+- Full `SHADE` and `LSHADE` optimizers are available for success-history adaptive DE
+
+## Installation
+
+DEFoundry requires Python 3.11 or later and has no mandatory runtime dependencies.
+The distribution name is `defoundry`; the Python import is `differential_evolution`.
+
+```bash
+python3 -m pip install defoundry
+```
+
+For development, install from a source checkout with `python3 -m pip install -e .`.
+Maintainers can follow the [release guide](https://github.com/vrbaj/differential_evolution/blob/master/RELEASE.md)
+to validate and publish distributions.
+
+## Core concepts
+
+- target vector: the current population member being evolved
+- donor vector: the output of a mutation strategy
+- trial vector: the result of applying a crossover operator to the target and donor
+
+The optimizer orchestrates:
+
+1. population initialization
+2. donor-vector mutation
+3. target/donor crossover
+4. boundary handling
+5. objective evaluation
+6. greedy one-to-one selection
+
+## Built-in mutation strategies
+
+- `Rand1`
+- `Rand2`
+- `Best1`
+- `Best2`
+- `CurrentToBest1`
+- `CurrentToBest2`
+- `CurrentToRand1`
+- `CurrentToRand2`
+- `TrigonometricMutation`
+- `DirectedMutation`
+- `NeighborhoodSearchMutation`
+
+## Built-in scale-factor controllers
+
+- `ConstantScaleFactor`
+- `RandomizedScaleFactor`
+- `AdaptiveScaleFactor`
+
+## Built-in crossover-rate controllers
+
+- `ConstantCrossoverRate`
+- `AdaptiveCrossoverRate`
+
+These can be passed anywhere a mutation strategy expects `scale` or `difference_scale`.
+
+```python
+from differential_evolution import AdaptiveScaleFactor, Rand1
+
+mutation = Rand1(scale=AdaptiveScaleFactor(initial=0.5, tau=0.1, lower=0.1, upper=0.9))
+```
+
+For the Brest et al. paper's full `jDE` control-parameter scheme, pair `AdaptiveScaleFactor` with `AdaptiveCrossoverRate`, or use the convenience helper:
+
+```python
+from differential_evolution import DifferentialEvolution, jde_rand_1_bin, sphere_function
+
+components = jde_rand_1_bin()
+optimizer = DifferentialEvolution(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=20,
+    mutation=components.mutation,
+    crossover=components.crossover,
+    max_generations=100,
+    seed=123,
+)
+```
+
+## Built-in crossover operators
+
+- `BinomialCrossover`
+- `ExponentialCrossover`
+- `IdentityCrossover`
+
+`IdentityCrossover` is useful for canonical current-to-rand style runs where no extra crossover is desired.
+
+## Built-in diversity measures
+
+- `PopulationDiameter`
+- `PopulationRadius`
+- `AverageDistanceAroundPopulationCenter`
+- `AverageDistanceAroundAllIndividuals`
+- `PopulationCoherence`
+- `DimensionalVariance`
+- `AggregatedDistribution`
+- `AveragePairwiseDistance`
+
+You can disable diversity tracking by leaving `diversity_measures=None`, or track several measures at once:
+
+```python
+from differential_evolution import (
+    AveragePairwiseDistance,
+    DifferentialEvolution,
+    PopulationDiameter,
+    Rand1,
+    BinomialCrossover,
+    sphere_function,
+)
+
+optimizer = DifferentialEvolution(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=20,
+    mutation=Rand1(scale=0.8),
+    crossover=BinomialCrossover(crossover_rate=0.9),
+    diversity_measures=[
+        PopulationDiameter(),
+        AveragePairwiseDistance(),
+        "population_coherence",
+    ],
+    max_generations=50,
+    seed=123,
+)
+result = optimizer.run()
+print(result.diversity_history["population_diameter"])
+```
+
+`PopulationCoherence` compares the movement of the population center between consecutive generations with the average movement of individuals. Its first recorded value is `0.0` because there is no previous generation yet.
+
+`AggregatedDistribution` is implemented here as a project-specific marginal dispersion statistic: each coordinate is normalized to `[0, 1]`, binned, and summarized by the variance-to-mean ratio of occupancy counts.
+
+## Built-in initializers
+
+- `RandomInitializer`
+- `TentInitializer`
+- `OppositionInitializer`
+- `QuasiOppositionInitializer`
+- `SobolInitializer`
+
+`SobolInitializer` supports up to 40 dimensions and `2**30` sequence points.
+It applies a seed-dependent digital shift by default; pass `scramble=False`
+for the unshifted sequence. See the current
+[algorithm reference](https://github.com/vrbaj/differential_evolution/blob/master/docs/algorithm_reference.rst#initialization).
+
+## Population reduction
+
+The optimizer can optionally reduce population size during the run:
+
+- `LinearPopulationReduction`
+- `HyperbolicTangentPopulationReduction`
+
+```python
+from differential_evolution import (
+    BinomialCrossover,
+    DifferentialEvolution,
+    LinearPopulationReduction,
+    Rand1,
+    sphere_function,
+)
+
+optimizer = DifferentialEvolution(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=20,
+    mutation=Rand1(scale=0.8),
+    crossover=BinomialCrossover(crossover_rate=0.9),
+    population_schedule=LinearPopulationReduction(min_population_size=4),
+    max_evaluations=2000,
+    seed=123,
+)
+```
+
+`LinearPopulationReduction` follows the L-SHADE idea of shrinking linearly with used function-evaluation budget when `max_evaluations` is provided. If `max_evaluations` is omitted, it falls back to generation progress. `HyperbolicTangentPopulationReduction` is a project-specific smooth nonlinear schedule.
+
+Supply at least one stopping limit. `max_generations` defaults to `None`, so an evaluation budget alone runs until that budget is exhausted. If both limits are supplied, the first one reached stops the run.
+
+When the population is reduced, the worst individuals by current fitness are removed. Users must choose a minimum population size that remains compatible with the mutation strategy in use.
+
+## SHADE and L-SHADE
+
+The package also includes dedicated optimizers for the full success-history adaptive algorithms:
+
+- `SHADE`
+- `LSHADE`
+
+`SHADE` includes:
+
+- `current-to-pbest/1`
+- external archive
+- Cauchy sampling of `F`
+- Gaussian sampling of `CR`
+- success-history memories `M_F` and `M_CR`
+
+`LSHADE` extends `SHADE` with linear population size reduction.
+
+```python
+from differential_evolution import LSHADE, sphere_function
+
+optimizer = LSHADE(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=18,
+    min_population_size=4,
+    memory_size=6,
+    max_evaluations=2000,
+    seed=123,
+)
+result = optimizer.run()
+```
+
+## Saving runs
+
+For post-run investigation, enable `record_snapshots=True` and save the result:
+
+```python
+result = optimizer.run()
+result.save_json("shade_run.json")
+result.save_pickle("shade_run.pkl")
+```
+
+Each snapshot stores the generation number, evaluation count, best solution, population size, optional population and fitness arrays, diversity values, and algorithm-specific extra state. For `SHADE` and `LSHADE`, the extra state includes the external archive and the parameter memories.
+
+## Example
+
+```python
+from differential_evolution import (
+    BinomialCrossover,
+    DifferentialEvolution,
+    ExponentialCrossover,
+    Rand1,
+    Best1,
+    sphere_function,
+)
+
+optimizer = DifferentialEvolution(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=20,
+    mutation=Rand1(scale=0.8),
+    crossover=BinomialCrossover(crossover_rate=0.9),
+    max_generations=50,
+    seed=123,
+)
+result = optimizer.run()
+
+optimizer_alt = DifferentialEvolution(
+    objective=sphere_function,
+    bounds=[(-5.0, 5.0), (-5.0, 5.0)],
+    population_size=20,
+    mutation=Best1(scale=0.5),
+    crossover=ExponentialCrossover(crossover_rate=0.8),
+    max_generations=50,
+    seed=123,
+)
+result_alt = optimizer_alt.run()
+```
+
+## Custom components
+
+Any callable with the right signature can be injected.
+
+```python
+class MyMutation:
+    def __call__(self, context):
+        target = context.population[context.target_index]
+        return [value * 0.5 for value in target]
+
+
+class MyCrossover:
+    def __call__(self, target_vector, donor_vector, rng):
+        trial = list(target_vector)
+        trial[0] = donor_vector[0]
+        return trial
+```
+
+## Reproducibility
+
+Use `seed=` or pass a custom RNG object. The optimizer does not use module-level global random state.
+
+## Compatibility
+
+The original constructor remains available from a source checkout only:
+
+```python
+from main import DifferentialEvolution
+```
+
+Installed users can use `from differential_evolution.compat import DifferentialEvolution`.
+Both paths emit a deprecation warning and forward into the new implementation.
+Details are in [MIGRATION.md](https://github.com/vrbaj/differential_evolution/blob/master/MIGRATION.md).
+
+## Verification
+
+- algorithm audit: [ALGORITHM_AUDIT.md](https://github.com/vrbaj/differential_evolution/blob/master/ALGORITHM_AUDIT.md)
+- migration notes: [MIGRATION.md](https://github.com/vrbaj/differential_evolution/blob/master/MIGRATION.md)
+- tests: `python3 -m unittest discover -s tests -v`
+- examples: `python3 -m examples.basic_usage`, `python3 -m examples.custom_components`, `python3 -m examples.diversity_measures`, and `python3 -m examples.population_initialization`
+
+### Review corrections and compatibility
+
+See [review fixes](https://github.com/vrbaj/differential_evolution/blob/master/docs/review_fixes.md) for changes and the disposition of the
+reported findings. Plain DE now clips to bounds by default; SHADE/L-SHADE use
+parent-aware midpoint repair. Mutation and crossover components are copied per
+optimizer; inspect adapted state on `optimizer.mutation` and `optimizer.crossover`.
+`run()` is single-use. `result.success` means a usable objective value was found,
+not numerical convergence; `result.message` reports the exhausted limit.
+
+Sobol initialization uses a seeded digital shift by default. Use
+`SobolInitializer(scramble=False)` for the original unshifted sequence. All
+fixed-dimensional benchmarks, including Ackley, require exactly two coordinates.

defoundry-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+defoundry-0.1.0.dist-info/licenses/LICENSE,sha256=J51U_0iHTQ2nz798bkyc7rPSYITcGVsMNf2KlhZTBfA,1062
+differential_evolution/__init__.py,sha256=E0DHLP7guIXv8ZmJtzimn9Og9eYvf2-ZJY_tFaMyhLA,3433
+differential_evolution/_numeric.py,sha256=2AgpmOjZGXVKTAwkxkfQodL-c5vD4Iyg64Os93ccVWo,2595
+differential_evolution/benchmarks.py,sha256=GfkBaliJjQmE8HVe-gVJbaWVpLKePIrZ5vNbbxjVfLA,7378
+differential_evolution/boundaries.py,sha256=CnDToPfD9v2gz8IUS7D_zTMlo2126muR5gdcb1ZB_BQ,3951
+differential_evolution/compat.py,sha256=Tvh1uY-VUIz2xZvDecvMpsrhZTocdpXD-S1xBzq24FA,6740
+differential_evolution/crossover_rates.py,sha256=n2IqdiFZOns_DUdCc7VMqoqt8vsTSSNySJG7aDmEIn0,3644
+differential_evolution/crossovers.py,sha256=MLJLVTP3VnDYsEi7bWOAOJE5kzmu69lfdfzuKZS_QGM,6391
+differential_evolution/diversity.py,sha256=4zCpk_TVhzjlh7sqf7NCMwcebHUG0lLMxB-6mk3Gy_8,12769
+differential_evolution/history.py,sha256=t6RI3qnn8hSFng0XFZrOqCUalhkCR4V9ZErNo14m-5U,1508
+differential_evolution/initializers.py,sha256=Ni4mZ-NeU3tu4gjtu75iIu41R0UMTt62fd8u6RMo0VI,12846
+differential_evolution/jde.py,sha256=S7Z6jqTxJDXgCfohyAbSbFv-nOMqWy-7A7ytKiq9QoM,1562
+differential_evolution/mutation.py,sha256=JlM0kfCpx6SreEslV-M6s95gdWH5Lk9YHnGC1c4BhHM,22987
+differential_evolution/optimizer.py,sha256=wLjY2xEIHrChteRrC3XFNHFbxX4Jp2VELQ4pK7REq4s,21588
+differential_evolution/population_schedules.py,sha256=dHYxj8hzLwexe1Ehu7LxEqP5y0xRwrJRVi3MXg40swM,3817
+differential_evolution/protocols.py,sha256=Z1ry7-PccxM7C2DqmpY4LR2bis5SgkaVdqGxNVK9vB0,1331
+differential_evolution/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+differential_evolution/result.py,sha256=XtJrCtJMiHaqUxzyUIEE78KvhF3W_E9YtMBz0dyj5Cg,1337
+differential_evolution/scales.py,sha256=11rUGaA45aJD8ahPzIesxghFG3Hu2-r9WyMPKkjQomQ,4898
+differential_evolution/shade.py,sha256=QPCwpGxlCbbSwaXX3z66SrDhvXLjwB75Ck3WH9OcH9Y,14206
+defoundry-0.1.0.dist-info/METADATA,sha256=bF00U2Ds0dnDWdFlOu7qSu_n7SIfWesVp5YB2d8nHOg,11771
+defoundry-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+defoundry-0.1.0.dist-info/top_level.txt,sha256=_dSOtYkjdxsSYRfQxQONLBWvAIpRSGToBjmCJYO3f7k,23
+defoundry-0.1.0.dist-info/RECORD,,

defoundry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

defoundry-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Honza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

defoundry-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+differential_evolution

differential_evolution/__init__.py

@@ -0,0 +1,134 @@
+"""Composable Differential Evolution optimizer."""
+
+from .benchmarks import (
+    ackley_function,
+    beale_function,
+    booth_function,
+    bukin_function,
+    easom_function,
+    eggholder_function,
+    goldstein_price_function,
+    himmelblau_function,
+    levi_function,
+    mccormick_function,
+    matyas_function,
+    rastrigin_function,
+    schaffer_n2_function,
+    sphere_function,
+    three_hump_camel_function,
+)
+from .boundaries import (
+    ClipBoundaryHandler,
+    NoBoundaryHandler,
+    RandomResetBoundaryHandler,
+    MidpointBoundaryHandler,
+    ReflectionBoundaryHandler,
+)
+from .crossovers import BinomialCrossover, ExponentialCrossover, IdentityCrossover
+from .crossover_rates import AdaptiveCrossoverRate, ConstantCrossoverRate
+from .initializers import (
+    OppositionInitializer,
+    QuasiOppositionInitializer,
+    RandomInitializer,
+    SobolInitializer,
+    TentInitializer,
+)
+from .diversity import (
+    AggregatedDistribution,
+    AverageDistanceAroundAllIndividuals,
+    AverageDistanceAroundPopulationCenter,
+    AveragePairwiseDistance,
+    DimensionalVariance,
+    PopulationCoherence,
+    PopulationDiameter,
+    PopulationRadius,
+)
+from .jde import JDEComponents, jde_rand_1_bin
+from .mutation import (
+    Best1,
+    Best2,
+    CurrentToBest1,
+    CurrentToBest2,
+    CurrentToRand1,
+    CurrentToRand2,
+    DirectedMutation,
+    MutationContext,
+    NeighborhoodSearchMutation,
+    Rand1,
+    Rand2,
+    TrigonometricMutation,
+    sample_distinct_indices,
+)
+from .optimizer import DifferentialEvolution
+from .population_schedules import (
+    HyperbolicTangentPopulationReduction,
+    LinearPopulationReduction,
+)
+from .result import OptimizeResult
+from .scales import AdaptiveScaleFactor, ConstantScaleFactor, RandomizedScaleFactor
+from .shade import LSHADE, SHADE
+
+__all__ = [
+    "LSHADE",
+    "SHADE",
+    "AdaptiveCrossoverRate",
+    "AdaptiveScaleFactor",
+    "AggregatedDistribution",
+    "AverageDistanceAroundAllIndividuals",
+    "AverageDistanceAroundPopulationCenter",
+    "AveragePairwiseDistance",
+    "Best1",
+    "Best2",
+    "BinomialCrossover",
+    "ClipBoundaryHandler",
+    "ConstantCrossoverRate",
+    "ConstantScaleFactor",
+    "CurrentToBest1",
+    "CurrentToBest2",
+    "CurrentToRand1",
+    "CurrentToRand2",
+    "DifferentialEvolution",
+    "DimensionalVariance",
+    "DirectedMutation",
+    "ExponentialCrossover",
+    "HyperbolicTangentPopulationReduction",
+    "IdentityCrossover",
+    "JDEComponents",
+    "LinearPopulationReduction",
+    "MidpointBoundaryHandler",
+    "MutationContext",
+    "NeighborhoodSearchMutation",
+    "NoBoundaryHandler",
+    "OppositionInitializer",
+    "OptimizeResult",
+    "PopulationCoherence",
+    "PopulationDiameter",
+    "PopulationRadius",
+    "QuasiOppositionInitializer",
+    "Rand1",
+    "Rand2",
+    "RandomInitializer",
+    "RandomResetBoundaryHandler",
+    "RandomizedScaleFactor",
+    "ReflectionBoundaryHandler",
+    "SobolInitializer",
+    "TentInitializer",
+    "TrigonometricMutation",
+    "ackley_function",
+    "beale_function",
+    "booth_function",
+    "bukin_function",
+    "easom_function",
+    "eggholder_function",
+    "goldstein_price_function",
+    "himmelblau_function",
+    "jde_rand_1_bin",
+    "levi_function",
+    "matyas_function",
+    "mccormick_function",
+    "rastrigin_function",
+    "sample_distinct_indices",
+    "schaffer_n2_function",
+    "sphere_function",
+    "three_hump_camel_function",
+]

differential_evolution/_numeric.py

@@ -0,0 +1,73 @@
+"""Overflow-safe coordinate arithmetic for finite search bounds."""
+
+import math
+from collections.abc import Sequence
+from fractions import Fraction
+
+from .protocols import RandomSource
+
+
+def require_integer(value: object, name: str) -> None:
+    """Reject fractional counts and booleans before they reach loops or budgets."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer.")
+
+
+def mean(values: Sequence[float], *, total: float | None = None) -> float:
+    """Preserve ordinary arithmetic, avoiding overflow of a finite-value sum."""
+    if total is None:
+        total = sum(values)
+    if math.isfinite(total) or not all(math.isfinite(value) for value in values):
+        return total / len(values)
+    return float(sum(Fraction(value) for value in values) / len(values))
+
+
+def sum_differences(base: float, *terms: tuple[float, float, float]) -> float:
+    """Compute base + sum(scale * (left - right)), with an overflow fallback.
+
+    Ordinary coordinates retain their floating-point operation order. Exact
+    arithmetic recovers finite results lost to intermediate overflow. A result
+    outside float range becomes signed infinity for boundary repair.
+    """
+    value = base
+    for scale, left, right in terms:
+        value += scale * (left - right)
+    if math.isfinite(value):
+        return value
+    if not math.isfinite(base) or not all(
+        math.isfinite(number) for term in terms for number in term
+    ):
+        return value
+    exact = Fraction(base) + sum(
+        Fraction(scale) * (Fraction(left) - Fraction(right))
+        for scale, left, right in terms
+    )
+    try:
+        return float(exact)
+    except OverflowError:
+        return math.inf if exact > 0 else -math.inf
+
+
+def interpolate(lower: float, upper: float, fraction: float) -> float:
+    width = upper - lower
+    if math.isfinite(width):
+        value = lower + fraction * width
+    else:
+        value = (1.0 - fraction) * lower + fraction * upper
+    return min(max(lower, upper), max(min(lower, upper), value))
+
+
+def uniform(lower: float, upper: float, rng: RandomSource) -> float:
+    if math.isfinite(upper - lower):
+        return rng.uniform(lower, upper)
+    return interpolate(lower, upper, rng.random())
+
+
+def midpoint(left: float, right: float) -> float:
+    total = left + right
+    return total / 2 if math.isfinite(total) else left / 2 + right / 2
+
+
+def opposite(value: float, lower: float, upper: float) -> float:
+    total = lower + upper
+    return total - value if math.isfinite(total) else lower + (upper - value)