combstruct 0.1.0a0__py3-none-any.whl

combstruct/__init__.py

@@ -0,0 +1,60 @@
+"""Tools for working with Encyclopedia of Combinatorial Structures data.
+
+The initial public API parses Maple ``combstruct``-style specifications and
+computes exact sequence terms in the labelled or unlabelled universe.
+"""
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+from .catalog import (
+    Catalog,
+    CatalogError,
+    Structure,
+    StructureNotFoundError,
+    default_dataset,
+    get_structure,
+    iter_structures,
+)
+from .specification import (
+    Cardinality,
+    Constructor,
+    Expression,
+    Parser,
+    Reference,
+    Specification,
+    SpecificationError,
+    parse_specification,
+)
+from .terms import (
+    UnsupportedConstruction,
+    compute_terms,
+    load_record,
+)
+
+try:
+    __version__ = _distribution_version("combstruct")
+except _PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "Cardinality",
+    "Catalog",
+    "CatalogError",
+    "Constructor",
+    "Expression",
+    "Parser",
+    "Reference",
+    "Specification",
+    "SpecificationError",
+    "Structure",
+    "StructureNotFoundError",
+    "UnsupportedConstruction",
+    "__version__",
+    "compute_terms",
+    "default_dataset",
+    "get_structure",
+    "iter_structures",
+    "load_record",
+    "parse_specification",
+]

combstruct/__main__.py

@@ -0,0 +1,5 @@
+"""Run the command-line interface with ``python -m combstruct``."""
+
+from .terms import main
+
+raise SystemExit(main())

combstruct/catalog.py

@@ -0,0 +1,293 @@
+"""Typed, read-only access to the Encyclopedia of Combinatorial Structures."""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+from typing import Any, Self
+
+
+class CatalogError(ValueError):
+    """The ECS catalogue or one of its records is invalid."""
+
+
+class StructureNotFoundError(LookupError):
+    """The requested ECS identifier is not present in the catalogue."""
+
+
+@dataclass(frozen=True, slots=True)
+class Structure:
+    """One immutable record from the Encyclopedia of Combinatorial Structures.
+
+    Symbolic results are stored as their original ECS strings. A missing
+    generating function, recurrence, closed form, or asymptotic equivalent is
+    represented by ``None``.
+    """
+
+    id: int
+    name: str
+    description: str
+    specification: str
+    labeled: bool
+    symbol: str
+    terms: tuple[int, ...]
+    references: tuple[str, ...]
+    generating_function: str | None = None
+    recurrence: str | None = None
+    closed_form: str | None = None
+    asymptotic_equivalent: str | None = None
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> Self:
+        """Create a structure from a canonical or web-encoded ECS record."""
+
+        structure_id = _integer(record, "id")
+        if structure_id <= 0:
+            raise CatalogError("ECS field 'id' must be positive")
+
+        labeled = record.get("labeled")
+        if not isinstance(labeled, bool):
+            raise CatalogError("ECS field 'labeled' must be a boolean")
+
+        return cls(
+            id=structure_id,
+            name=_nonempty_string(record, "name"),
+            description=_nonempty_string(record, "description"),
+            specification=_nonempty_string(record, "specification"),
+            labeled=labeled,
+            symbol=_nonempty_string(record, "symbol"),
+            terms=_terms(record),
+            references=_references(record),
+            generating_function=_optional_string(record, "gf"),
+            recurrence=_optional_string(record, "rec"),
+            closed_form=_optional_string(record, "closedform"),
+            asymptotic_equivalent=_optional_string(record, "equiv"),
+        )
+
+    def as_record(self) -> dict[str, Any]:
+        """Return a canonical mutable record using the ECS source field names."""
+
+        record: dict[str, Any] = {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "specification": self.specification,
+            "labeled": self.labeled,
+            "symbol": self.symbol,
+            "terms": list(self.terms),
+            "references": list(self.references),
+        }
+        optional_fields = {
+            "gf": self.generating_function,
+            "rec": self.recurrence,
+            "closedform": self.closed_form,
+            "equiv": self.asymptotic_equivalent,
+        }
+        record.update((name, value) for name, value in optional_fields.items() if value is not None)
+        return record
+
+
+class Catalog:
+    """A lazy, read-only collection of ECS structures.
+
+    ``dataset`` may be either the package's directory of canonical record files
+    or the historical consolidated JSON mapping used by the web application.
+    Omitting it selects the appropriate source for the current installation.
+    """
+
+    def __init__(self, dataset: str | Path | None = None):
+        self.dataset = Path(dataset) if dataset is not None else _default_catalog_dataset()
+        self._cache: dict[int, Structure] = {}
+
+    @cached_property
+    def ids(self) -> tuple[int, ...]:
+        """All available ECS identifiers in increasing order."""
+
+        if self.dataset.is_dir():
+            identifiers = tuple(
+                sorted(
+                    int(path.stem.removeprefix("ecs_")) for path in self.dataset.glob("ecs*/*.json")
+                ),
+            )
+        else:
+            identifiers = tuple(sorted(int(key) for key in self._record_mapping))
+
+        if len(identifiers) != len(set(identifiers)):
+            raise CatalogError(f"Duplicate ECS identifiers in {self.dataset}")
+        return identifiers
+
+    @cached_property
+    def _record_mapping(self) -> Mapping[str, Mapping[str, Any]]:
+        if not self.dataset.is_file():
+            raise CatalogError(f"ECS dataset does not exist: {self.dataset}")
+        with self.dataset.open(encoding="utf-8") as source:
+            records = json.load(source)
+        if not isinstance(records, dict):
+            raise CatalogError(f"Expected an ECS record mapping in {self.dataset}")
+        return records
+
+    def __len__(self) -> int:
+        return len(self.ids)
+
+    def __iter__(self) -> Iterator[Structure]:
+        for structure_id in self.ids:
+            yield self.get(structure_id)
+
+    def __contains__(self, structure_id: object) -> bool:
+        return (
+            isinstance(structure_id, int)
+            and not isinstance(structure_id, bool)
+            and structure_id in self.ids
+        )
+
+    def get(self, structure_id: int) -> Structure:
+        """Return one structure by ECS identifier."""
+
+        if not isinstance(structure_id, int) or isinstance(structure_id, bool):
+            raise TypeError("structure_id must be an integer")
+        if structure_id in self._cache:
+            return self._cache[structure_id]
+
+        if self.dataset.is_dir():
+            record = _load_record(self.dataset, structure_id)
+        else:
+            try:
+                stored_record = self._record_mapping[str(structure_id)]
+            except KeyError as error:
+                raise StructureNotFoundError(
+                    f"No ECS structure #{structure_id} in {self.dataset}",
+                ) from error
+            if not isinstance(stored_record, Mapping):
+                raise CatalogError(f"ECS structure #{structure_id} is not a JSON object")
+            record = dict(stored_record)
+
+        structure = Structure.from_record(record)
+        if structure.id != structure_id:
+            raise CatalogError(
+                f"ECS record #{structure_id} contains identifier {structure.id}",
+            )
+        self._cache[structure_id] = structure
+        return structure
+
+
+def _integer(record: Mapping[str, Any], field: str) -> int:
+    value = record.get(field)
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        raise CatalogError(f"ECS field {field!r} must be an integer")
+    try:
+        result = int(value)
+    except (TypeError, ValueError) as error:
+        raise CatalogError(f"ECS field {field!r} must be an integer") from error
+    if isinstance(value, float) and not value.is_integer():
+        raise CatalogError(f"ECS field {field!r} must be an integer")
+    return result
+
+
+def _nonempty_string(record: Mapping[str, Any], field: str) -> str:
+    value = record.get(field)
+    if not isinstance(value, str) or not value:
+        raise CatalogError(f"ECS field {field!r} must be a nonempty string")
+    return value
+
+
+def _optional_string(record: Mapping[str, Any], field: str) -> str | None:
+    value = record.get(field)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        raise CatalogError(f"ECS field {field!r} must be a nonempty string when present")
+    return value
+
+
+def _terms(record: Mapping[str, Any]) -> tuple[int, ...]:
+    values = record.get("terms")
+    if not isinstance(values, list):
+        raise CatalogError("ECS field 'terms' must be a list")
+    terms = tuple(_integer({"term": value}, "term") for value in values)
+    if any(term < 0 for term in terms):
+        raise CatalogError("ECS terms must be nonnegative")
+    return terms
+
+
+def _references(record: Mapping[str, Any]) -> tuple[str, ...]:
+    values = record.get("references")
+    if not isinstance(values, list) or not all(
+        isinstance(value, str) and value for value in values
+    ):
+        raise CatalogError("ECS field 'references' must be a list of nonempty strings")
+    return tuple(values)
+
+
+def default_dataset() -> Path:
+    """Return the legacy repository or installed-package ECS data location."""
+
+    repository_dataset = Path(__file__).resolve().parents[2] / "react-app" / "public" / "ecs.json"
+    if repository_dataset.is_file():
+        return repository_dataset
+
+    packaged_dataset = importlib.resources.files("combstruct").joinpath("data")
+    return Path(str(packaged_dataset))
+
+
+def _default_catalog_dataset() -> Path:
+    """Return canonical per-record data for the typed catalogue API."""
+
+    repository_dataset = Path(__file__).resolve().parents[2] / "structures"
+    if repository_dataset.is_dir():
+        return repository_dataset
+
+    packaged_dataset = importlib.resources.files("combstruct").joinpath("data")
+    return Path(str(packaged_dataset))
+
+
+def _load_record(dataset: Path, structure_id: int) -> dict[str, Any]:
+    """Load one raw ECS record from a directory or consolidated JSON file."""
+
+    if not isinstance(structure_id, int) or isinstance(structure_id, bool):
+        raise TypeError("structure_id must be an integer")
+
+    if dataset.is_dir():
+        record_path = dataset / f"ecs{structure_id // 100:02d}" / f"ecs_{structure_id:04d}.json"
+        try:
+            with record_path.open(encoding="utf-8") as source:
+                record = json.load(source)
+        except FileNotFoundError as error:
+            raise StructureNotFoundError(
+                f"No ECS structure #{structure_id} in {dataset}",
+            ) from error
+    else:
+        if not dataset.is_file():
+            raise CatalogError(f"ECS dataset does not exist: {dataset}")
+        with dataset.open(encoding="utf-8") as source:
+            records = json.load(source)
+        if not isinstance(records, dict):
+            raise CatalogError(f"Expected an ECS record mapping in {dataset}")
+        try:
+            record = records[str(structure_id)]
+        except KeyError as error:
+            raise StructureNotFoundError(
+                f"No ECS structure #{structure_id} in {dataset}",
+            ) from error
+
+    if not isinstance(record, dict):
+        raise CatalogError(f"ECS structure #{structure_id} is not a JSON object")
+    return record
+
+
+_DEFAULT_CATALOG = Catalog()
+
+
+def get_structure(structure_id: int) -> Structure:
+    """Return one structure from the bundled ECS catalogue."""
+
+    return _DEFAULT_CATALOG.get(structure_id)
+
+
+def iter_structures() -> Iterator[Structure]:
+    """Iterate over the bundled ECS catalogue in identifier order."""
+
+    return iter(_DEFAULT_CATALOG)

combstruct/data/ecs00/ecs_0001.json

@@ -0,0 +1,35 @@
+{
+    "id": 1,
+    "name": "Alcohols or Unlabelled Non Plane Ternary Trees",
+    "description": "Alcohols or unlabelled non plane ternary Trees",
+    "specification": "{S = Union(Z,Prod(Z,Set(S,card = 3))), Z = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        0,
+        1,
+        0,
+        0,
+        1,
+        0,
+        0,
+        1,
+        0,
+        0,
+        2,
+        0,
+        0,
+        4,
+        0,
+        0,
+        8,
+        0,
+        0,
+        17,
+        0
+    ],
+    "references": [
+        "EIS A000598"
+    ],
+    "gf": "S(_x) = _x+_x*(1/3*S(_x^3)+1/2*S(_x)*S(_x^2)+1/6*S(_x)^3)"
+}

combstruct/data/ecs00/ecs_0002.json

@@ -0,0 +1,37 @@
+{
+    "id": 2,
+    "name": "Necklaces of 2 colours",
+    "description": "Necklaces of 2 colours; binary irreducible polynomials whose degree divides n",
+    "specification": "{S = Cycle(Union(c1,c2)), c1 = Atom, c2 =Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        0,
+        2,
+        3,
+        4,
+        6,
+        8,
+        14,
+        20,
+        36,
+        60,
+        108,
+        188,
+        352,
+        632,
+        1182,
+        2192,
+        4116,
+        7712,
+        14602,
+        27596,
+        52488
+    ],
+    "references": [
+        "EIS A000031",
+        "http://sue.csc.uvic.ca/~cos/inf/neck/NecklaceInfo.html",
+        "Same as ECS 130"
+    ],
+    "gf": "Sum(numtheory:-phi(j[1])/j[1]*ln(-1/(-1+2*_x^j[1])),j[1] = 1 .. infinity)"
+}

combstruct/data/ecs00/ecs_0003.json

@@ -0,0 +1,35 @@
+{
+    "id": 3,
+    "name": "Necklaces of 3 colours",
+    "description": "Necklaces of 3 colours",
+    "specification": "{S= Cycle(Union(c1,c2,c3)), c1 = Atom, c2 = Atom, c3 = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        0,
+        3,
+        6,
+        11,
+        24,
+        51,
+        130,
+        315,
+        834,
+        2195,
+        5934,
+        16107,
+        44368,
+        122643,
+        341802,
+        956635,
+        2690844,
+        7596483,
+        21524542,
+        61171659,
+        174342216
+    ],
+    "references": [
+        "EIS A001867"
+    ],
+    "gf": "Sum(numtheory:-phi(j[1])/j[1]*ln(-1/(-1+3*_x^j[1])),j[1] = 1 .. infinity)"
+}

combstruct/data/ecs00/ecs_0004.json

@@ -0,0 +1,35 @@
+{
+    "id": 4,
+    "name": "Necklaces of 4 colours",
+    "description": "Necklaces of 4 colours",
+    "specification": "{S = Cycle(Union(c1,c2,c3,c4)), c1 = Atom, c2 = Atom, c3 = Atom, c4 = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        0,
+        4,
+        10,
+        24,
+        70,
+        208,
+        700,
+        2344,
+        8230,
+        29144,
+        104968,
+        381304,
+        1398500,
+        5162224,
+        19175140,
+        71582944,
+        268439590,
+        1010580544,
+        3817763740,
+        14467258264,
+        54975633976
+    ],
+    "references": [
+        "EIS A001868"
+    ],
+    "gf": "Sum(numtheory:-phi(j[1])/j[1]*ln(-1/(-1+4*_x^j[1])),j[1] = 1 .. infinity)"
+}

combstruct/data/ecs00/ecs_0005.json

@@ -0,0 +1,35 @@
+{
+    "id": 5,
+    "name": "Necklaces of 5 colours",
+    "description": "Necklaces of 5 colours",
+    "specification": "{S = Cycle(Union(c1,c2,c3,c4,c5)), c1 = Atom, c2 = Atom, c3 = Atom, c4 = Atom, c5 = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        0,
+        5,
+        15,
+        45,
+        165,
+        629,
+        2635,
+        11165,
+        48915,
+        217045,
+        976887,
+        4438925,
+        20346485,
+        93900245,
+        435970995,
+        2034505661,
+        9536767665,
+        44878791365,
+        211927736135,
+        1003867701485,
+        4768372070757
+    ],
+    "references": [
+        "EIS A001869"
+    ],
+    "gf": "Sum(numtheory:-phi(j[1])/j[1]*ln(-1/(-1+5*_x^j[1])),j[1] = 1 .. infinity)"
+}

combstruct/data/ecs00/ecs_0006.json

@@ -0,0 +1,39 @@
+{
+    "id": 6,
+    "name": "Words of n letters in a two-letter alphabet",
+    "description": "Words of n letters in a two-letter alphabet",
+    "specification": "{S= Sequence(Union(a,b)), a = Atom, b = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        1,
+        2,
+        4,
+        8,
+        16,
+        32,
+        64,
+        128,
+        256,
+        512,
+        1024,
+        2048,
+        4096,
+        8192,
+        16384,
+        32768,
+        65536,
+        131072,
+        262144,
+        524288,
+        1048576
+    ],
+    "references": [
+        "EIS A000079",
+        "Same terms as ECS 267"
+    ],
+    "gf": "-1/(-1+2*_x)",
+    "rec": "{2*_f(_n)-_f(_n+1), _f(0) = 1}",
+    "closedform": "2^_n",
+    "equiv": "exp(-_n)^(-ln(2))"
+}

combstruct/data/ecs00/ecs_0007.json

@@ -0,0 +1,39 @@
+{
+    "id": 7,
+    "name": "Words of n letters in a 3-letter alphabet",
+    "description": "Words of n letters in a 3-letter alphabet",
+    "specification": "{S = Sequence(Union(a,b,c)), a = Atom, b = Atom, c = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        1,
+        3,
+        9,
+        27,
+        81,
+        243,
+        729,
+        2187,
+        6561,
+        19683,
+        59049,
+        177147,
+        531441,
+        1594323,
+        4782969,
+        14348907,
+        43046721,
+        129140163,
+        387420489,
+        1162261467,
+        3486784401
+    ],
+    "references": [
+        "EIS A000244",
+        "Same terms as ECS 268"
+    ],
+    "gf": "-1/(-1+3*_x)",
+    "rec": "{3*_f(_n)-_f(_n+1), _f(0) = 1}",
+    "closedform": "3^_n",
+    "equiv": "exp(-_n)^(-ln(3))"
+}

combstruct/data/ecs00/ecs_0008.json

@@ -0,0 +1,39 @@
+{
+    "id": 8,
+    "name": "Words of n letters in a 4-letter alphabet",
+    "description": "Words of n letters in a 4-letter alphabet",
+    "specification": "{S = Sequence(Union(a,b,c,d)), a = Atom, b = Atom, c = Atom, d = Atom}",
+    "labeled": false,
+    "symbol": "S",
+    "terms": [
+        1,
+        4,
+        16,
+        64,
+        256,
+        1024,
+        4096,
+        16384,
+        65536,
+        262144,
+        1048576,
+        4194304,
+        16777216,
+        67108864,
+        268435456,
+        1073741824,
+        4294967296,
+        17179869184,
+        68719476736,
+        274877906944,
+        1099511627776
+    ],
+    "references": [
+        "EIS A000302",
+        "Same terms as ECS 269"
+    ],
+    "gf": "-1/(-1+4*_x)",
+    "rec": "{4*_f(_n)-_f(_n+1), _f(0) = 1}",
+    "closedform": "4^_n",
+    "equiv": "exp(-_n)^(-2*ln(2))"
+}