Migration notes: 1.0.3 to 2.0.0

These notes describe the prepared 2.0.0 candidate; the stable release remains subject to the human readiness gate. They complement the changelog, compatibility guide, and executable historical-to-modern examples.

Before upgrading

Use CPython 3.13 or 3.14 and validate the application on its actual interpreter. Python 3.12 and earlier are outside the v2 support promise. The historical Python 3.6 classifier does not carry forward. Package metadata is now owned by pyproject.toml, with standard wheel and source-distribution builds; legacy setup.py no longer owns version generation.

The current project-owned tree uses Apache-2.0 rather than the historical MIT license. Preserve LICENSE and NOTICE plus applicable copyright and attribution notices in redistribution. The immutable 1.0.3 baseline keeps its original license. See licensing and provenance.

Imports and historical calls

Continue importing historical classes and operators from fuzzyroutines.FuzzyRoutines. The root fuzzyroutines package exposes the curated modern API. The facade's wildcard export contains fifteen supported functions and classes, rather than every imported helper. Applications that previously obtained math, copy, or other helper modules through a wildcard must import those standard-library modules directly; facade attributes math and copy have also been removed.

Protected names and call shapes remain supported, including Defuz(), Fuzzy(), GetLevelByName(), and the historical membership identifiers. Keep the legacy triangle mapping a=left, b=right, c=peak. Translate explicitly when adopting modern Triangle(left, peak, right) or Trapezoid factories; copying positional values between conventions can change the shape.

Facade extraction preserves historical class/function module identities and has both new-pickle round trips and an actual pre-extraction fixture. This evidence covers extraction compatibility, not arbitrary Python-version pickle portability. Historical names and mutable level dictionaries remain observable; the observed-surface inventory records which names have tests beyond ADR-0001's narrower protected contract.

Inputs that now fail explicitly

Check application inputs before upgrading; malformed values no longer produce apparently valid fallback results. The following numeric restrictions describe the historical facade; the modern API's broader MembershipScalar contract is documented in the finite scalar policy.

• Scalar fuzzy degrees must be finite int or float values in [0, 1]. Booleans, NaN, infinity, strings and array-like inputs are rejected.
• Membership coordinates must be finite non-Boolean int or float scalars; values outside [0, 1] are valid coordinates. Construction and parameter replacement require exactly the family's declared finite parameters and valid geometry. Retained mutable parameter mappings do not permit corrupt state to be silently evaluated as zero.
• Variadic composition requires at least one operand, validates every operand, and rejects unknown families. FuzzyNOT requires alpha in (0, 1); FuzzyNOTParabolic requires alpha in [1/4, 3/4].
• Scale levels must have their required fields; names colliding under case-insensitive lookup are rejected. Use unique complete names rather than relying on ambiguous lookup.

Historical failures remain concrete built-in exceptions. Modern categories are available from fuzzyroutines.exceptions and preserve applicable catches for TypeError, ValueError, and ArithmeticError. Arbitrary exceptions from custom membership callbacks propagate; they are not converted to zero or reclassified. See PR #274 and the corrected-bug ledger.

Numerical results and retained settings

FuzzySet.Defuz() and defuzValue now recompute from current membership parameters and supportSet bounds. The bounds are a finite integration interval, not mathematical positive support. Analytical moments replace fixed sampling for supported families; other callables use adaptive integration. Update assertions that depended on a stale centroid or the retired 1000-point right-endpoint result. The recorded historical reference cases have an absolute comparison bound of 5e-4; this is not a universal error promise.

Zero area has no centroid and raises ValueError through the historical facade rather than the old sampled sum's indirect ZeroDivisionError; update zero-area exception handlers accordingly. Modern undefined results have their explicit error category; unresolved adaptive integration raises CentroidConvergenceError. Handle those failures instead of using a midpoint or old cached value. Modern CentroidPolicy controls accuracy and work. MFunction.accuracy remains writable but is ignored by centroid evaluation; FuzzyNOTParabolic's retained epsilon no longer controls its analytical execution.

Bell evaluation preserves its parameter mapping. Historical scale Fuzzy() still chooses the later maximum, including all-zero ties, and returns the original level dictionary. Historical case-insensitive lookup uses uppercase complete names; modern lookup uses Unicode case folding. Modern fuzzification makes no-match and first, last, or all tie policies explicit. Do not silently substitute modern defaults for historical selection rules.

Adopt modern APIs incrementally

Use explicit universes, immutable scalar sets and membership factories, operator policies, and separate integration domains when the implemented modern API covers the application's operation. Exact properties, alpha-cuts, normalization and relations retain their evidence boundaries; sampled reports do not prove continuous behavior. Linguistic scores and diagnostics are also available. Existing historical calls do not need a blanket rename.

The complete migration guide links executable examples and explains each available path. Public modern typing and signature coverage under Tasks #92 and #95 are implemented and checked against installed wheels on CPython 3.13 and 3.14; see the typing contract. The final candidate still requires its own CI evidence. Optional vectorization is a decision and out-of-package experiment, not an importable backend. Public convexity queries, transparent caches, free-threaded support and general performance claims are not migration targets.