Canonical Mathematical Model¶

This document is the entry point for the mathematical contract implemented by FuzzyRoutines. It defines the shared vocabulary, records the formulas exposed by the current public surfaces, and links each topic to its detailed contract and executable evidence. The detailed pages remain authoritative for numerical algorithms, compatibility exceptions, and proof boundaries.

The model is one-dimensional and scalar. Multidimensional fuzzy sets, type-2 fuzzy sets, symbolic algebra, and implicit interpolation are outside the current contract.

Contract and evidence hierarchy¶

When sources appear to disagree, use this order:

accepted architecture decisions define the intended contract;
this document states the integrated mathematical model;
focused mathematics pages define topic-specific details and evidence limits;
public docstrings describe callable behavior;
executable tests prove the behavior of the current implementation.

The current implementation status distinguishes accepted design from shipped behavior. The historical compatibility contract protects existing names and signatures; it does not make historical terminology mathematically canonical.

Scalar fuzzy set and domains¶

A scalar fuzzy set is the ordered pair

\[ A=(X,\mu_A), \qquad \mu_A:X\to[0,1], \]

where \(X\) is an explicitly declared ContinuousUniverse or DiscreteUniverse. Coordinates and grades are finite real scalars. Boolean, non-finite, and out-of-range grades are rejected rather than coerced.

The following concepts are distinct:

Concept	Definition	Current representation
Universe	Coordinates on which \(\mu_A\) defines \(A\)	`ContinuousUniverse` or `DiscreteUniverse`
Integration domain	Finite closed interval used by one numerical operation	`IntegrationDomain`
Positive support	\(\{x\in X\mid\mu_A(x)\gt 0\}\)	Exact region or explicit sampled evidence
Support closure	Closure of positive support relative to \(X\)	Exact region for supported representations
Core	\(\{x\in X\mid\mu_A(x)=1\}\)	Exact region for supported representations
Boundary	\(\{x\in X\mid0\lt \mu_A(x)\lt 1\}\)	Fuzzy transition region, not topological boundary
Height	\(\sup\{\mu_A(x)\mid x\in X\}\)	Exact scalar only when the representation supports proof

An integration domain is never inferred to be support. In particular, the historical FuzzySet.supportSet tuple is a compatibility spelling for a finite integration interval. Exact and sampled property semantics are specified in the universe and support contract and ADR-0002.

Membership-function families¶

MFunction is the historical analytical-family registry. Let \(S_{a,b}\) denote the quadratic increasing shoulder

\[ S_{a,b}(x)= \begin{cases} 0, & x\le a,\\ 2\left(\dfrac{x-a}{b-a}\right)^2, & a\lt x\le\dfrac{a+b}{2},\\ 1-2\left(\dfrac{x-b}{b-a}\right)^2, & \dfrac{a+b}{2}\lt x\lt b,\\ 1, & x\ge b. \end{cases} \]

The triangle and trapezium families use the protected historical parameter order even though their geometric breakpoint order is different:

\[ \mathrm{Tri}_{a,c,b}(x)= \begin{cases} 0, & x\le a,\\ \dfrac{x-a}{c-a}, & a\lt x\le c,\\ \dfrac{b-x}{b-c}, & c\lt x\le b,\\ 0, & x\gt b, \end{cases} \]

and

\[ \mathrm{Trap}_{a,c,d,b}(x)= \begin{cases} 0, & x\le a,\\ \dfrac{x-a}{c-a}, & a\lt x\lt c,\\ 1, & c\le x\le d,\\ \dfrac{b-x}{b-d}, & d\lt x\le b,\\ 0, & x\gt b. \end{cases} \]

Every stored membership parameter is a finite built-in int or float; Boolean values are rejected even though Python treats them as integers. The family-specific constraints below are additional to that blanket scalar contract. desirability stores no parameters, but its evaluation coordinate must still be a finite built-in scalar.

The implemented families are:

Historical identifier	Mathematical function	Valid parameters	Exact aliases
`hyperbolic`	\(1\) for \(x\le c\); otherwise \(1/(1+(a(x-c))^b)\)	\(a\gt 0\), \(b\gt 0\), finite \(c\)	None
`bell`	\(S_{a,b}(x)\) for \(x\lt b\); \(1\) on \([b,c]\); \(1-S_{c,c+b-a}(x)\) after \(c\)	\(a\lt b\le c\)	None
`parabolic`	\(S_{a,b}(x)\)	\(a\lt b\)	`sShoulder`
`triangle`	\(\mathrm{Tri}_{a,c,b}(x)\)	\(a\lt c\le b\); legacy order is `a, b, c`	None
`trapezium`	\(\mathrm{Trap}_{a,c,d,b}(x)\)	\(a\lt c\le d\lt b\); legacy order is `a, b, c, d`	None
`exponential`	\(\exp\!\left[-\tfrac12((x-a)/b)^2\right]\)	finite \(a\), \(b\gt 0\)	`gaussian`
`sigmoidal`	\(1/(1+\exp[-a(x-b)])\)	\(a\ne0\), finite \(b\)	`logistic`
`desirability`	\(\exp[-\exp(-y)]\)	finite \(y\); no stored parameters	`harringtonDesirability`

The exact piecewise triangle and trapezium equations, numerical branches, and historical parameter order are frozen by the membership-function contract. The legacy bell is a flat-top piecewise-quadratic family, not the generalized bell commonly used in other libraries. Registry aliases share the same implementation; they are not new families or permission to rename protected parameters.

Negations¶

Every negation maps \([0,1]\) to \([0,1]\). The modern set API requires an explicit NegationPolicy; it has no process-wide default.

The standard complement is

\[ N(x)=1-x. \]

The historical parametric strong negation has fixed point \(\alpha\in(0,1)\):

\[ N_\alpha(x)= \begin{cases} 1+x\dfrac{\alpha-1}{\alpha}, & x\le\alpha,\\ (x-1)\dfrac{\alpha}{\alpha-1}, & x\gt \alpha. \end{cases} \]

The parabolic family is the valid branch of

\[ 2\alpha-x-y=(2\alpha-1)(y-x)^2, \qquad \alpha\in\left[\frac14,\frac34\right]. \]

With \(D=1-8(2\alpha-1)(x-\alpha)\), the cancellation-resistant branch is

\[ N_\alpha(x)=x+\frac{4(\alpha-x)}{1+\sqrt{D}}. \]

It satisfies \(N(0)=1\), \(N(1)=0\), \(N(\alpha)=\alpha\), monotone decrease, and involution on its accepted domain. The epsilon argument retained by FuzzyNOTParabolic is compatibility-only and does not control the analytical algorithm. See the derivation and ADR-0004.

T-norms and s-norms¶

For \(x,y\in[0,1]\), the public scalar operators and modern policy values expose four dual families. The code values in the first column are protected historical registry identifiers, not the standard mathematical family names:

Historical identifier	Standard t-norm name	T-norm \(T(x,y)\)	Standard s-norm name	S-norm \(S(x,y)\)
`logic`	Minimum	\(\min(x,y)\)	Maximum	\(\max(x,y)\)
`algebraic`	Product	\(xy\)	Probabilistic (algebraic) sum	\(x+y-xy\)
`boundary`	Łukasiewicz	\(\max(x+y-1,0)\)	Łukasiewicz	\(\min(x+y,1)\)
`drastic`	Drastic product	\(y\) if \(x=1\); \(x\) if \(y=1\); otherwise \(0\)	Drastic sum	\(y\) if \(x=0\); \(x\) if \(y=0\); otherwise \(1\)

The historical spelling is SCoNorm; the modern set policy is SNormPolicy. Composition validates every operand before folding. The executable suite checks closure, commutativity, associativity, identities, and both De Morgan laws under standard negation.

Fuzzy-set algebra¶

All modern binary operations require exactly equal universes. They never infer a resampling grid, coordinate conversion, or universe reconciliation.

For sets \(A\) and \(B\) over the same universe:

\[ \begin{aligned} \mu_{\neg A}(x) &= N(\mu_A(x)),\\ \mu_{A\cap B}(x) &= T(\mu_A(x),\mu_B(x)),\\ \mu_{A\cup B}(x) &= S(\mu_A(x),\mu_B(x)),\\ \mu_{A\setminus B}(x) &= T(\mu_A(x),N(\mu_B(x))). \end{aligned} \]

Difference is directed. Under general fuzzy grades, \(A\setminus A\) is not required to be empty. Symmetric difference is not yet a public contract because it additionally requires an explicit s-norm and an accepted composition policy. See explicit fuzzy-set operations.

Mathematical equality and inclusion are also explicit operations:

\[ \begin{aligned} A=B &\iff \forall x\in X:\mu_A(x)=\mu_B(x),\\ A\subseteq B &\iff \forall x\in X:\mu_A(x)\le\mu_B(x). \end{aligned} \]

Discrete universes are checked exhaustively. Continuous arbitrary callables require a declared finite ComparisonDomain, so a positive result is evidence only on those coordinates, not a proof of global functional equality. Exact and tolerance policies are never implicit. See equality and inclusion.

Alpha-cuts, height, normalization, and convexity¶

FuzzyRoutines uses weak alpha-cuts:

\[ A_\alpha=\{x\in X\mid\mu_A(x)\ge\alpha\}, \qquad \alpha\in[0,1]. \]

Therefore \(A_0=X\), \(A_1\) is the core, and \(A_\beta\subseteq A_\alpha\) whenever \(0\le\alpha\le\beta\le1\). AlphaCut is exact for a declared finite DiscreteUniverse. SampleAlphaCut records a finite continuous grid and always reports isExact == False; its result is not continuous geometry.

For exact positive height \(h(A)\), normalization is

\[ \mu_{\mathrm{Normalize}(A)}(x)=\frac{\mu_A(x)}{h(A)}. \]

Zero height is rejected. Exact height is available for exhaustive discrete sets and supported analytical continuous families; arbitrary continuous callables fail closed rather than using a sampled maximum as proof. See the alpha-cut contract and normalization contract.

The accepted one-dimensional convexity definition is quasiconcavity:

\[ \mu_A(\lambda x+(1-\lambda)y) \ge\min(\mu_A(x),\mu_A(y)), \qquad \lambda\in[0,1]. \]

Equivalently, every positive weak alpha-cut is convex. This definition is accepted by ADR-0009, but the public convexity query and evidence-result API are not implemented. A finite continuous grid can expose a counterexample; absence of a sampled violation cannot prove global convexity. See the convexity design contract.

Linguistic terms and scales¶

The modern representation associates an exact non-empty name with one ScalarFuzzySet:

\[ L=(\text{name},A). \]

LinguisticScale stores a non-empty ordered tuple of LinguisticTerm values whose names are unique under Unicode case-insensitive comparison. Exact lookup preserves case; optional case-insensitive lookup compares complete case-folded names. Fuzzify() returns every ordered membership score and the maximum as confidence. An explicit FuzzificationPolicy defines the minimum confidence, absolute tie tolerance, and first, last, or all ordered tie selection. The governing contract is ADR-0013.

Diagnose() evaluates an explicit endpoint-preserving finite grid and records per-point maximum membership, active terms, gaps, overlaps, and partition-of- unity error. Its domain, sample count, activity threshold, and partition tolerance are explicit. The result is reproducible sampled evidence and never claims continuous proof between grid points. The diagnostic definitions and non-mutation boundary are fixed by ADR-0014.

The historical mutable FuzzyScale.levels list remains available as a compatibility surface, and GetLevelByName() retains its historical callable shape. Its existing Fuzzy() later-winner behavior remains supported but is an explicit last policy in the typed model. See the linguistic-term representation.

Centroid defuzzification¶

For a continuous fuzzy set and explicit finite integration domain \(D=[l,r]\), the implemented centroid is

\[ C(A,D)= \frac{\int_l^r x\mu_A(x)\,\mathrm{d}x} {\int_l^r \mu_A(x)\,\mathrm{d}x}. \]

Polynomial families use analytical moments. Gaussian membership uses stable closed forms when the finite area is resolvable. Other MFunction families and generic callables use deterministic adaptive Simpson integration with an explicit CentroidPolicy. A zero or non-finite area raises ValueError, and exhausted adaptive work raises CentroidConvergenceError; no best-so-far or fixed-grid estimate is returned as a converged result.

The compatibility method FuzzySet.Defuz() and the defuzValue property delegate to this strategy on every access. They observe current parameters and current supportSet integration bounds without a retained centroid cache. See the centroid contract and ADR-0005.

Implementation boundary¶

Capability	Status	Contract or evidence
Explicit continuous and discrete universes	Implemented	Universe and support
Historical analytical membership registry	Implemented and protected	Membership functions
Explicit negation, t-norm, and s-norm policy	Implemented	ADR-0004
Complement, intersection, union, difference	Implemented	Fuzzy-set operations
Equality and inclusion	Implemented	Relations
Exact discrete and sampled continuous cuts	Implemented	Alpha-cuts
Height and normalization	Implemented	Normalization
Typed linguistic representation	Implemented	Linguistic terms
Sampled scale diagnostics	Implemented	Linguistic terms
Analytical and adaptive centroid	Implemented	Centroid defuzzification
Executable convexity result API	Roadmap	Accepted design
Typed linguistic lookup and fuzzification	Implemented	Linguistic terms
Symmetric difference	Unsupported	ADR-0008
Multidimensional or type-2 fuzzy sets	Out of scope	Requires a separate architecture decision

Detailed contract index¶

Topic	Canonical detail
Finite scalar values	Finite-number policy
Numerical tolerances	Numerical edge policy
Domains and derived geometry	Universe and support
Membership families	Formula and parameter contracts
Stable numerical branches	Source formula and algorithm invariants
Negations	Parabolic derivation
Set operations	Complement, intersection, union, and difference
Relations	Equality and inclusion
Alpha-cuts	Exact and sampled alpha-cuts
Height and normalization	Fuzzy-set normalization
Convexity	Fuzzy-set convexity
Linguistic model	Typed linguistic-term representation
Defuzzification	Centroid defuzzification
Compatibility	Historical-to-modern migration

License¶

This documentation is licensed under the Apache License 2.0. Redistributions must preserve the license, copyright, and attribution notices described in NOTICE.