Lay foundation for namedisl + add set-likes and operations between them

.gitignore

@@ -17,3 +17,5 @@ distribute*tar.gz
 
 .pylintrc.yml
 .run-pylint.py
+
+.codex

doc/conf.py

@@ -1,31 +1,37 @@
 from __future__ import annotations
 
+import sys
+from importlib import metadata
+from pathlib import Path
 from urllib.request import urlopen
 
 
-_conf_url = \
-        "https://raw.githubusercontent.com/inducer/sphinxconfig/main/sphinxconfig.py"
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+_conf_url = "https://tiker.net/sphinxconfig-v0.py"
 with urlopen(_conf_url) as _inf:
     exec(compile(_inf.read(), _conf_url, "exec"), globals())
 
-copyright = "2025- University of Illiois Board of Trustees"
-author = "Andreas Kloeckner"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.linkcode",
+]
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-ver_dic = {}
-with open("../namedisl/__init__.py") as vfile:
-    exec(compile(vfile.read(), "../namedisl/__init__.py", "exec"), ver_dic)
+autodoc_member_order = "bysource"
+autodoc_typehints = "none"
+
+project = "namedisl"
+copyright = "2025- University of Illinois Board of Trustees"
+author = "Andreas Kloeckner"
 
-version = ".".join(str(x) for x in ver_dic["__version__"])
-release = ver_dic["__version__"]
+release = metadata.version("namedisl")
+version = ".".join(release.split(".")[:2])
 
 intersphinx_mapping = {
     "islpy": ("https://documen.tician.de/islpy", None),
     "constantdict": ("https://matthiasdiener.github.io/constantdict/", None),
+    "python": ("https://docs.python.org/3", None),
 }
 
 nitpicky = True

doc/index.rst

@@ -1,11 +1,17 @@
 Welcome to namedisl's documentation!
 ====================================
 
+namedisl is a small wrapper around :mod:`islpy` for code that needs dimension
+names to carry semantic meaning.  It keeps isl's integer-set operations while
+offering a name-oriented interface for sets, maps, affine expressions, and
+piecewise affine expressions.
+
 .. toctree::
     :maxdepth: 2
     :caption: Contents:
 
     ref
+    internals
 
     🚀 Github <https://github.com/inducer/namedisl>
     💾 Download Releases <https://pypi.org/project/namedisl>

doc/internals.rst

@@ -0,0 +1,18 @@
+Internal Reference
+==================
+
+These interfaces support the public wrappers and are mainly useful when
+maintaining namedisl itself.
+
+.. automodule:: namedisl.core
+
+.. autoclass:: namedisl.core.NamedIslObject
+    :members:
+
+.. autofunction:: namedisl.core._deconstruct_object
+
+.. autofunction:: namedisl.core._make_named_object_pieces
+
+.. autofunction:: namedisl.core._align_two
+
+.. autofunction:: namedisl.core._align_and_apply_binary_op

doc/ref.rst

@@ -2,3 +2,89 @@ Reference
 =========
 
 .. automodule:: namedisl
+
+Set and Map Objects
+-------------------
+
+.. autofunction:: make_basic_set
+
+.. autofunction:: make_set
+
+.. autofunction:: make_basic_map
+
+.. autofunction:: make_map
+
+.. autofunction:: make_map_from_domain_and_range
+
+.. autoclass:: BasicSet
+    :members:
+    :inherited-members:
+    :special-members: __and__, __or__, __sub__, __lt__, __le__, __gt__, __ge__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: Set
+    :members:
+    :inherited-members:
+    :special-members: __and__, __or__, __sub__, __lt__, __le__, __gt__, __ge__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: BasicMap
+    :members:
+    :inherited-members:
+    :special-members: __and__, __or__, __sub__, __lt__, __le__, __gt__, __ge__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: Map
+    :members:
+    :inherited-members:
+    :special-members: __and__, __or__, __sub__, __lt__, __le__, __gt__, __ge__
+    :exclude-members: __init__, __new__
+
+Expression Objects
+------------------
+
+.. autofunction:: make_aff
+
+.. autofunction:: make_pw_aff
+
+.. autofunction:: make_qpolynomial
+
+.. autofunction:: make_pw_qpolynomial
+
+.. autofunction:: make_multi_aff
+
+.. autofunction:: make_pw_multi_aff
+
+.. autoclass:: Aff
+    :members:
+    :inherited-members:
+    :special-members: __add__, __sub__, __mul__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: PwAff
+    :members:
+    :inherited-members:
+    :special-members: __add__, __sub__, __mul__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: QPolynomial
+    :members:
+    :inherited-members:
+    :special-members: __add__, __sub__, __mul__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: PwQPolynomial
+    :members:
+    :inherited-members:
+    :special-members: __add__, __sub__, __mul__
+    :exclude-members: __init__, __new__
+
+.. autoclass:: MultiAff
+    :members:
+    :inherited-members:
+    :exclude-members: __init__, __new__
+
+.. autoclass:: PwMultiAff
+    :members:
+    :inherited-members:
+    :exclude-members: __init__, __new__

namedisl/__init__.py

@@ -1,9 +1,15 @@
 """
-.. autoclass:: BasicSet
+Name-aware wrappers for :mod:`islpy` objects.
 
-.. autofunction:: make_basic_set
-"""
+namedisl offers small Python wrappers around isl sets, maps, and expression
+objects.  The wrappers keep a separate mapping from dimension names to isl
+dimension positions, align operands by name before applying binary operations,
+and reconstruct ordinary :mod:`islpy` objects when callers need to interoperate
+with islpy or downstream libraries.
 
+Most users should construct objects through the ``make_*`` functions exported
+from this module.
+"""
 
 from __future__ import annotations
 
@@ -31,74 +37,54 @@
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 """
-import re
-from collections.abc import Mapping
-from dataclasses import dataclass
-from importlib import metadata
-from typing import TypeAlias, TypeVar, overload
-
-from constantdict import constantdict
-from typing_extensions import override
-
-import islpy as isl
-
-
-__version__ = metadata.version("namedisl")
-_match = re.match(r"^([0-9.]+)([a-z0-9]*?)$", __version__)
-assert _match
-VERSION = tuple(int(nr) for nr in _match.group(1).split("."))
-
-
-IslObject = TypeVar("IslObject", isl.BasicSet, isl.Set)
-NameToDim: TypeAlias = Mapping[str, tuple[isl.dim_type, int]]
-
-
-def _strip_names(obj: IslObject) -> tuple[IslObject, NameToDim]:
-    name_to_dim: dict[str, tuple[isl.dim_type, int]] = {}
-    for tp in isl._CHECK_DIM_TYPES:
-        for i in range(obj.dim(tp)):
-            name = obj.get_dim_name(tp, i)
-            if name is None:
-                raise ValueError("unnamed dimension found")
-            if name in name_to_dim:
-                raise ValueError(f"non-unique dim name: {name}")
-            name_to_dim[name] = (tp, i)
-
-            # FIXME: Enable, to avoid misunderstandings
-            # obj = obj.set_dim_id(tp, i, None)
-
-    return obj, constantdict(name_to_dim)
-
-
-def _restore_names(obj: IslObject, name_to_dim: NameToDim) -> IslObject:
-    for name, (dt, i) in name_to_dim.items():
-        obj = obj.set_dim_name(dt, i, name)
-
-    return obj
-
-
-@dataclass(frozen=True)
-class BasicSet:
-    _obj: isl.BasicSet
-    _name_to_dim: NameToDim
-
-    @override
-    def __str__(self) -> str:
-        return str(_restore_names(self._obj, self._name_to_dim))
-
-
-@overload
-def make_basic_set(src: str, ctx: isl.Context | None = None) -> BasicSet:
-    ...
-
-
-@overload
-def make_basic_set(src: isl.BasicSet) -> BasicSet:
-    ...
-
-
-def make_basic_set(src: str | isl.BasicSet, ctx: isl.Context | None = None) -> BasicSet:
-    obj = isl.BasicSet(src, ctx) if isinstance(src, str) else src
 
-    obj, name_to_dim = _strip_names(obj)
-    return BasicSet(obj, name_to_dim)
+from .expression_like import (
+    Aff,
+    MultiAff,
+    PwAff,
+    PwMultiAff,
+    PwQPolynomial,
+    QPolynomial,
+    make_aff,
+    make_multi_aff,
+    make_pw_aff,
+    make_pw_multi_aff,
+    make_pw_qpolynomial,
+    make_qpolynomial,
+)
+from .set_like import (
+    BasicMap,
+    BasicSet,
+    Map,
+    Set,
+    make_basic_map,
+    make_basic_set,
+    make_map,
+    make_map_from_domain_and_range,
+    make_set,
+)
+
+
+__all__ = [
+    "Aff",
+    "BasicMap",
+    "BasicSet",
+    "Map",
+    "MultiAff",
+    "PwAff",
+    "PwMultiAff",
+    "PwQPolynomial",
+    "QPolynomial",
+    "Set",
+    "make_aff",
+    "make_basic_map",
+    "make_basic_set",
+    "make_map",
+    "make_map_from_domain_and_range",
+    "make_multi_aff",
+    "make_pw_aff",
+    "make_pw_multi_aff",
+    "make_pw_qpolynomial",
+    "make_qpolynomial",
+    "make_set",
+]