geometric-function-atlas 0.1.1__py3-none-any.whl

geometric_function_atlas/__init__.py

@@ -0,0 +1,46 @@
+"""Public API for reproducible Geometric Function Atlas computations."""
+
+from .catalog import get_generator, list_generators
+from .coefficients import GeneratorSeriesResult, generator_series, taylor_coefficients
+from .contracts import (  # noqa: F401
+    RESULT_SCHEMA_VERSION,
+    CheckStatus,
+    CorruptArtifactError,
+    FailureState,
+    InvalidInputError,
+    LiteratureStatus,
+    ResourceLimitError,
+    UnresolvedError,
+    UnsupportedError,
+    VerificationCheck,
+    VerificationReport,
+    failure_payload,
+    load_error_schema,
+    load_result_schema,
+    validate_error_payload,
+    validate_result_payload,
+)
+from .counterexamples import CounterexampleResult, verify_counterexample
+from .fekete_szego import FeketeSzegoResult, fekete_szego
+from .implementation_registry import (  # noqa: F401
+    get_trusted_implementation,
+    list_trusted_implementations,
+)
+from .models import Generator
+from .models import Z as z
+from .version import __version__
+
+__all__ = [
+    "CounterexampleResult",
+    "FeketeSzegoResult",
+    "Generator",
+    "GeneratorSeriesResult",
+    "__version__",
+    "fekete_szego",
+    "generator_series",
+    "get_generator",
+    "list_generators",
+    "taylor_coefficients",
+    "verify_counterexample",
+    "z",
+]

geometric_function_atlas/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m geometric_function_atlas``."""
+
+from .cli import main
+
+raise SystemExit(main())

geometric_function_atlas/catalog.py

@@ -0,0 +1,98 @@
+"""Curated Ma–Minda generators used by the published radius portfolio."""
+
+from __future__ import annotations
+
+import sympy as sp
+
+from .models import Generator, Z
+from .version import GENERATOR_CATALOG_VERSION
+
+_GENERATORS = (
+    Generator(
+        key="starlike",
+        name="Classical starlike class",
+        expression=(1 + Z) / (1 - Z),
+        citation="Classical starlike class; Janowski (1973) with A=1, B=-1",
+    ),
+    Generator(
+        key="bell",
+        name="Bell-number starlike class",
+        expression=sp.exp(sp.exp(Z) - 1),
+        citation="Cho, Kumar, Kumar & Ravichandran (2019)",
+    ),
+    Generator(
+        key="cosh_sqrt",
+        name="Cosh-square-root starlike class",
+        expression=sp.cosh(sp.sqrt(Z)),
+        citation="Mundalia & Swaminathan (2023)",
+    ),
+    Generator(
+        key="crescent",
+        name="Crescent (lune) starlike class",
+        expression=Z + sp.sqrt(1 + Z**2),
+        citation="Raina & Sokół (2015)",
+    ),
+    Generator(
+        key="exponential",
+        name="Exponential starlike class",
+        expression=sp.exp(Z),
+        citation="Mendiratta, Nagpal & Ravichandran (2015)",
+    ),
+    Generator(
+        key="lemniscate",
+        name="Lemniscate starlike class",
+        expression=sp.sqrt(1 + Z),
+        citation="Sokół & Stankiewicz (1996)",
+    ),
+    Generator(
+        key="rational_kr",
+        name="Kumar–Ravichandran rational starlike class",
+        expression=(
+            1
+            + Z
+            * ((1 + sp.sqrt(2)) + Z)
+            / ((1 + sp.sqrt(2)) * ((1 + sp.sqrt(2)) - Z))
+        ),
+        citation="Kumar & Ravichandran (2016)",
+    ),
+    Generator(
+        key="sigmoid",
+        name="Modified-sigmoid starlike class",
+        expression=2 / (1 + sp.exp(-Z)),
+        citation="Goel & Kumar (2020)",
+    ),
+    Generator(
+        key="sine",
+        name="Sine starlike class",
+        expression=1 + sp.sin(Z),
+        citation="Cho, Kumar, Kumar & Ravichandran (2019)",
+    ),
+)
+
+_BY_KEY = {generator.key: generator for generator in _GENERATORS}
+
+
+def list_generators() -> tuple[Generator, ...]:
+    """Return the built-in generators in stable key order."""
+
+    return tuple(sorted(_GENERATORS, key=lambda generator: generator.key))
+
+
+def get_generator(key: str) -> Generator:
+    """Return a built-in generator or fail with a discoverable error."""
+
+    try:
+        return _BY_KEY[key]
+    except KeyError as exc:
+        available = ", ".join(sorted(_BY_KEY))
+        raise KeyError(f"unknown generator {key!r}; available: {available}") from exc
+
+
+def generator_artifact_version(generator: Generator) -> str:
+    """Return the catalog version or identify a caller-supplied definition."""
+
+    return (
+        GENERATOR_CATALOG_VERSION
+        if _BY_KEY.get(generator.key) is generator
+        else "user-supplied"
+    )

geometric_function_atlas/cli.py

@@ -0,0 +1,282 @@
+"""Command-line interface for independent reproduction workflows."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import json
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from .catalog import get_generator, list_generators
+from .coefficients import generator_series
+from .contracts import (
+    CorruptArtifactError,
+    FailureState,
+    InvalidInputError,
+    ResourceLimitError,
+    UnresolvedError,
+    UnsupportedError,
+    failure_payload,
+    validate_error_payload,
+)
+from .counterexamples import verify_counterexample
+from .fekete_szego import fekete_szego
+from .version import __version__
+
+EXIT_SUCCESS = 0
+EXIT_INVALID_INPUT = 2
+EXIT_UNSUPPORTED = 3
+EXIT_UNRESOLVED = 4
+EXIT_RESOURCE_LIMIT = 5
+EXIT_CORRUPT_ARTIFACT = 6
+
+EXIT_CODES = {
+    FailureState.INVALID_INPUT.value: EXIT_INVALID_INPUT,
+    FailureState.UNSUPPORTED.value: EXIT_UNSUPPORTED,
+    FailureState.UNRESOLVED.value: EXIT_UNRESOLVED,
+    FailureState.RESOURCE_LIMIT.value: EXIT_RESOURCE_LIMIT,
+    FailureState.CORRUPT_ARTIFACT.value: EXIT_CORRUPT_ARTIFACT,
+}
+
+
+def _write(payload: Any, *, as_json: bool) -> None:
+    if as_json:
+        _write_utf8(
+            json.dumps(
+                payload,
+                indent=2,
+                ensure_ascii=False,
+                allow_nan=False,
+                sort_keys=True,
+            )
+        )
+    elif isinstance(payload, list):
+        for row in payload:
+            print(f"{row['key']}: {row['formula']} — {row['citation']}")
+    else:
+        for key, value in payload.items():
+            print(f"{key}: {value}")
+
+
+def _write_utf8(text: str, *, stream: Any = None) -> None:
+    """Write JSON as UTF-8 even when the console locale is not UTF-8."""
+
+    target = sys.stdout if stream is None else stream
+    buffer = getattr(target, "buffer", None)
+    if buffer is not None:
+        buffer.write(text.encode("utf-8") + b"\n")
+        buffer.flush()
+    else:
+        target.write(f"{text}\n")
+
+
+def _generators(args: argparse.Namespace) -> None:
+    payload = [
+        {
+            "key": generator.key,
+            "name": generator.name,
+            "formula": generator.formula,
+            "citation": generator.citation,
+            "reference_url": generator.reference_url,
+        }
+        for generator in list_generators()
+    ]
+    _write(payload, as_json=args.json)
+
+
+def _coefficients(args: argparse.Namespace) -> None:
+    result = generator_series(get_generator(args.generator), order=args.order)
+    _write(result.to_dict(), as_json=args.json)
+
+
+def _fekete_szego(args: argparse.Namespace) -> None:
+    result = fekete_szego(args.generator, mu=args.mu)
+    _write(result.to_dict(precision=args.precision), as_json=args.json)
+
+
+def _comma_separated_numbers(value: str, *, label: str) -> list[float]:
+    if len(value) > 4096:
+        raise ResourceLimitError(f"{label} input is too long")
+    parts = [part.strip() for part in value.split(",")]
+    if not parts or any(not part for part in parts):
+        raise InvalidInputError(f"{label} must be comma-separated real numbers")
+    try:
+        return [float(part) for part in parts]
+    except ValueError as exc:
+        raise InvalidInputError(
+            f"{label} must be comma-separated real numbers"
+        ) from exc
+
+
+def _verify_counterexample(args: argparse.Namespace) -> None:
+    coefficients = _comma_separated_numbers(
+        args.coefficients, label="coefficients"
+    )
+    point = _comma_separated_numbers(args.point, label="point")
+    if len(point) != 2:
+        raise InvalidInputError("point must have the form real,imaginary")
+    result = verify_counterexample(
+        coefficients,
+        point=(point[0], point[1]),
+        property=args.property,
+    )
+    if args.json:
+        _write(result.to_dict(), as_json=True)
+        return
+
+    if result.certified and result.property == "starlike":
+        verdict = "CERTIFIED COUNTEREXAMPLE"
+    elif result.certified:
+        verdict = "CERTIFIED CRITERION VIOLATION"
+    elif result.property == "starlike":
+        verdict = "NO COUNTEREXAMPLE CERTIFIED AT THIS POINT"
+    else:
+        verdict = "NO CRITERION VIOLATION CERTIFIED AT THIS POINT"
+    criterion_names = {
+        "starlike": "starlikeness",
+        "becker_univalent": "Becker criterion",
+        "nehari_univalent": "Nehari criterion",
+    }
+    real, imaginary = result.point
+    sign = "+" if imaginary >= 0 else "-"
+    comparison = "<=" if result.property == "starlike" else ">"
+    lines = [
+        verdict,
+        f"Criterion: {criterion_names[result.property]}",
+        f"Witness: z = {real:g} {sign} {abs(imaginary):g}i",
+        (
+            "Certified value: "
+            f"[{result.interval_lower:g}, {result.interval_upper:g}]"
+        ),
+        f"Counterexample condition: value {comparison} {result.threshold:g}",
+    ]
+    _write_utf8("\n".join(lines))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="geometric-function-atlas",
+        description="Reproduce and review Geometric Function Atlas computations.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    generators = subparsers.add_parser("generators", help="list built-in generators")
+    generators.add_argument("--json", action="store_true", help="emit JSON")
+    generators.set_defaults(handler=_generators)
+
+    coefficients = subparsers.add_parser(
+        "coefficients", help="compute exact generator Taylor coefficients"
+    )
+    coefficients.add_argument("generator")
+    coefficients.add_argument("--order", type=int, required=True)
+    coefficients.add_argument("--json", action="store_true", help="emit JSON")
+    coefficients.set_defaults(handler=_coefficients)
+
+    fs = subparsers.add_parser(
+        "fekete-szego", help="compute an exact Ma-Minda Fekete-Szego constant"
+    )
+    fs.add_argument("generator")
+    fs.add_argument("--mu", required=True, help="real rational value, e.g. 1/2")
+    fs.add_argument("--precision", type=int, default=16)
+    fs.add_argument("--json", action="store_true", help="emit JSON")
+    fs.set_defaults(handler=_fekete_szego)
+
+    counterexample = subparsers.add_parser(
+        "verify-counterexample",
+        help="rigorously check a supplied counterexample witness",
+    )
+    counterexample.add_argument(
+        "--coefficients",
+        required=True,
+        help="comma-separated a2,a3,... for f(z)=z+a2*z^2+...",
+    )
+    counterexample.add_argument(
+        "--point",
+        required=True,
+        help="witness point as real,imaginary; use --point=-0.75,0 for negatives",
+    )
+    counterexample.add_argument("--property", default="starlike")
+    counterexample.add_argument("--json", action="store_true", help="emit JSON")
+    counterexample.set_defaults(handler=_verify_counterexample)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    command_line = list(sys.argv[1:] if argv is None else argv)
+    wants_json = "--json" in command_line
+    if wants_json:
+        parse_errors = io.StringIO()
+        try:
+            with contextlib.redirect_stderr(parse_errors):
+                args = parser.parse_args(command_line)
+        except SystemExit as exc:
+            if exc.code == 0:
+                raise
+            payload = failure_payload(
+                FailureState.INVALID_INPUT,
+                parse_errors.getvalue().strip() or "invalid command-line arguments",
+            )
+            validate_error_payload(payload)
+            _write_utf8(
+                json.dumps(
+                    payload,
+                    indent=2,
+                    ensure_ascii=False,
+                    allow_nan=False,
+                    sort_keys=True,
+                )
+            )
+            return EXIT_INVALID_INPUT
+    else:
+        args = parser.parse_args(command_line)
+    try:
+        args.handler(args)
+    except (
+        CorruptArtifactError,
+        UnresolvedError,
+        UnsupportedError,
+        ResourceLimitError,
+        InvalidInputError,
+        KeyError,
+        TypeError,
+        ValueError,
+    ) as exc:
+        state = _failure_state(exc)
+        if getattr(args, "json", False):
+            payload = failure_payload(state, str(exc))
+            validate_error_payload(payload)
+            _write_utf8(
+                json.dumps(
+                    payload,
+                    indent=2,
+                    ensure_ascii=False,
+                    allow_nan=False,
+                    sort_keys=True,
+                )
+            )
+            return EXIT_CODES[state]
+        print(f"{parser.prog}: error: {exc}", file=sys.stderr)
+        return EXIT_CODES[state]
+    return EXIT_SUCCESS
+
+
+def _failure_state(exc: Exception) -> str:
+    if isinstance(exc, CorruptArtifactError):
+        return FailureState.CORRUPT_ARTIFACT.value
+    if isinstance(exc, UnresolvedError):
+        return FailureState.UNRESOLVED.value
+    if isinstance(exc, UnsupportedError):
+        return FailureState.UNSUPPORTED.value
+    if isinstance(exc, ResourceLimitError):
+        return FailureState.RESOURCE_LIMIT.value
+    return FailureState.INVALID_INPUT.value

geometric_function_atlas/coefficients.py

@@ -0,0 +1,206 @@
+"""Exact coefficient operations for Ma–Minda generators."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import sympy as sp
+
+from .catalog import generator_artifact_version, get_generator
+from .contracts import (
+    CheckStatus,
+    FailureState,
+    InvalidInputError,
+    ResourceLimitError,
+    VerificationCheck,
+    VerificationReport,
+    build_result_payload,
+)
+from .models import Generator, canonical_expression_dag, validate_exact_expression
+from .version import GENERATOR_FIXTURE_ID, SOURCE_ARTIFACT_COMMIT
+
+MAX_TAYLOR_ORDER = 64
+
+
+@dataclass(frozen=True, slots=True)
+class GeneratorSeriesResult:
+    """Exact generator coefficients with reproducibility metadata."""
+
+    generator: Generator
+    order: int
+    coefficients: tuple[sp.Expr, ...]
+    method: str = "exact_symbolic_taylor_series"
+
+    def __post_init__(self) -> None:
+        if isinstance(self.order, bool) or not isinstance(self.order, int):
+            raise TypeError("order must be a positive integer")
+        if self.order < 1:
+            raise InvalidInputError("order must be at least 1")
+        if self.order > MAX_TAYLOR_ORDER:
+            raise ResourceLimitError(f"order must be at most {MAX_TAYLOR_ORDER}")
+        if not isinstance(self.generator, Generator):
+            raise TypeError("generator must be a Generator")
+        if self.method != "exact_symbolic_taylor_series":
+            raise ValueError("method is a closed package-owned value")
+        normalized: list[sp.Expr] = []
+        for value in self.coefficients:
+            if isinstance(value, (bool, float)):
+                raise TypeError("coefficients must be exact symbolic values")
+            exact = sp.Integer(value) if isinstance(value, int) else value
+            if not isinstance(exact, sp.Expr):
+                raise TypeError("coefficients must be exact symbolic values")
+            validate_exact_expression(exact)
+            normalized.append(exact)
+        if len(normalized) != self.order:
+            raise ValueError("coefficients length must equal order")
+        object.__setattr__(self, "coefficients", tuple(normalized))
+
+    @property
+    def evidence_status(self) -> str:
+        """Return the package-derived computational evidence state."""
+
+        if not self.verification_report.success:
+            return FailureState.UNRESOLVED.value
+        return "proven_exact_under_declared_assumptions"
+
+    @property
+    def verification_report(self) -> VerificationReport:
+        normalized = sp.simplify(
+            self.generator.expression.subs(self.generator.variable, 0)
+        )
+        expected: Any
+        try:
+            expected_coefficients = taylor_coefficients(
+                self.generator, order=self.order
+            )
+            coefficients_ok = expected_coefficients == self.coefficients
+            expected = [str(value) for value in expected_coefficients]
+            reason = "stored coefficients do not match the exact expansion"
+        except (TypeError, ValueError):
+            expected = "unavailable (invalid or over-limit order)"
+            coefficients_ok = False
+            reason = "exact expansion could not be recomputed"
+        return VerificationReport(
+            checks=(
+                VerificationCheck(
+                    name="generator_normalization",
+                    checked="generator value at z = 0",
+                    expected="1",
+                    observed=str(normalized),
+                    status=CheckStatus.PASS if normalized == 1 else CheckStatus.FAIL,
+                    scope="generator definition",
+                    failure_reason=(
+                        None
+                        if normalized == 1
+                        else "generator is not normalized at the origin"
+                    ),
+                ),
+                VerificationCheck(
+                    name="exact_taylor_coefficients",
+                    checked=f"Taylor coefficients through order {self.order}",
+                    expected=expected,
+                    observed=[str(value) for value in self.coefficients],
+                    status=(
+                        CheckStatus.PASS if coefficients_ok else CheckStatus.FAIL
+                    ),
+                    scope="exact symbolic expansion",
+                    failure_reason=None if coefficients_ok else reason,
+                ),
+            )
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return build_result_payload(
+            result_type="generator_series",
+            canonical_inputs={"generator": self.generator.key, "order": self.order},
+            exact_expressions={
+                "generator": self.generator.formula,
+                "coefficients": [str(value) for value in self.coefficients],
+            },
+            method=self.method,
+            evidence_status=self.evidence_status,
+            assumptions=("phi(0) = 1", "expression uses only the variable z"),
+            source_references=(self.generator.citation,),
+            artifact_versions={
+                "generator_catalog": generator_artifact_version(self.generator),
+                "source_commit": SOURCE_ARTIFACT_COMMIT
+                if generator_artifact_version(self.generator) != "user-supplied"
+                else "caller-supplied",
+                "fixture_or_proof": GENERATOR_FIXTURE_ID,
+            },
+            verification=self.verification_report,
+            exact_expression_dag=canonical_expression_dag(
+                {
+                    "generator": self.generator.expression,
+                    "coefficients": self.coefficients,
+                }
+            ),
+            provenance=(
+                "caller_supplied"
+                if generator_artifact_version(self.generator) == "user-supplied"
+                else "built_in"
+            ),
+            legacy_fields={
+                "generator": self.generator.key,
+                "generator_formula": self.generator.formula,
+                "generator_citation": self.generator.citation,
+                "order": self.order,
+                "coefficients": [str(value) for value in self.coefficients],
+            },
+        )
+
+
+def _resolve_generator(generator: str | Generator) -> Generator:
+    if isinstance(generator, str):
+        return get_generator(generator)
+    if not isinstance(generator, Generator):
+        raise TypeError("generator must be a built-in key or Generator")
+    return generator
+
+
+def taylor_coefficients(
+    generator: str | Generator,
+    *,
+    order: int,
+) -> tuple[sp.Expr, ...]:
+    """Return exact ``B_1, …, B_order`` for ``phi(z) = 1 + Σ B_n z^n``.
+
+    Custom :class:`Generator` objects are accepted so reproductions are not
+    limited to the built-in catalog. The normalization ``phi(0) = 1`` is checked
+    exactly before coefficients are returned.
+    """
+
+    if isinstance(order, bool) or not isinstance(order, int):
+        raise TypeError("order must be a positive integer")
+    if order < 1:
+        raise InvalidInputError("order must be at least 1")
+    if order > MAX_TAYLOR_ORDER:
+        raise ResourceLimitError(f"order must be at most {MAX_TAYLOR_ORDER}")
+
+    resolved = _resolve_generator(generator)
+    expression = resolved.expression
+    variable = resolved.variable
+    if sp.simplify(expression.subs(variable, 0) - 1) != 0:
+        raise InvalidInputError(f"generator {resolved.key!r}: phi(0) must equal 1")
+
+    polynomial = sp.series(expression, variable, 0, order + 1).removeO().expand()
+    return tuple(
+        sp.simplify(polynomial.coeff(variable, degree))
+        for degree in range(1, order + 1)
+    )
+
+
+def generator_series(
+    generator: str | Generator,
+    *,
+    order: int,
+) -> GeneratorSeriesResult:
+    """Return exact coefficients plus a structured provenance record."""
+
+    resolved = _resolve_generator(generator)
+    return GeneratorSeriesResult(
+        generator=resolved,
+        order=order,
+        coefficients=taylor_coefficients(resolved, order=order),
+    )