fpy2 0.2.3__tar.gz → 0.2.4__tar.gz

fpy2-0.2.4/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: fpy2
+Version: 0.2.4
+Summary: An embedded DSL for numerical computing
+Author-email: Brett Saiki <bsaiki@cs.washington.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bksaiki/fpy
+Project-URL: Issues, https://github.com/bksaiki/fpy/issues
+Project-URL: Documentation, https://fpy.readthedocs.io/
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: titanfp==0.1.2
+Requires-Dist: gmpy2==2.3.1
+Requires-Dist: numpy
+Requires-Dist: z3-solver>=4.13
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: hypothesis==6.135; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: sphinx-pyproject; extra == "dev"
+Dynamic: license-file
+
+# FPy
+
+An embedded Python DSL for specifying and simulating numerical algorithms.
+
+Important links:
+ - PyPI package: [fpy2](https://pypi.org/project/fpy2/)
+ - Documentation: [fpy.readthedocs.io](https://fpy.readthedocs.io/)
+ - GitHub: [fpy](https://github.com/bksaiki/fpy)
+ - Guide: [USAGE.md](docs/USAGE.md)
+
+## Example
+
+FPy is Python with explicit control of both the mathematics and
+rounding: every operation is correctly rounded by the *rounding context*
+it appears in, and contexts are ordinary values you can pass around —
+including `fp.REAL`, which never rounds.  Here is a blocked dot product:
+the products are exact, each block of `K` elements is summed in a narrow
+format, and the running total is `float32`.
+
+```python
+import fpy2 as fp
+
+@fp.fpy(ctx=fp.REAL)
+def dot(xs: list[fp.Real], ys: list[fp.Real], K: int, block: fp.Context) -> fp.Real:
+    """A blocked dot product: exact products, blocks of `K` summed in `block`.
+    The length of `xs` must be a multiple of `K`."""
+    assert len(xs) == len(ys)
+    acc = 0
+    for start in range(0, len(xs), K):
+        with block:
+            inner_acc = 0
+            for x, y in zip(xs[start:start + K], ys[start:start + K]):
+                with fp.REAL:
+                    p = x * y       # every product is exact ...
+                inner_acc += p      # ... but block sums round to `block`
+        with fp.FP32:
+            acc += inner_acc        # one fp32 addition per block
+    return acc
+
+@fp.fpy(ctx=fp.REAL)
+def dot_ref(xs: list[fp.Real], ys: list[fp.Real]) -> fp.Real:
+    """The same dot product, with no rounding anywhere."""
+    return sum([x * y for x, y in zip(xs, ys)])
+
+xs = ys = [0.1] * 4096
+exact = dot_ref(xs, ys).as_rational()   # the true value, as a Fraction
+
+print(f'{"block":>6} {"format":>9} {"result":>11} {"rel. error":>11}')
+for K, name, ctx in [(4096, 'float16', fp.FP16), (32, 'float16', fp.FP16),
+                     (4096, 'bfloat16', fp.BF16), (32, 'bfloat16', fp.BF16),
+                     (32, 'float32', fp.FP32)]:
+    r = dot(xs, ys, K, ctx)
+    err = abs(r.as_rational() - exact) / exact
+    print(f'{K:>6} {name:>9} {float(r):>11.6f} {float(err):>11.3%}')
+```
+
+which prints
+
+```
+ block    format      result  rel. error
+  4096   float16   32.000000     21.875%
+    32   float16   40.968750      0.021%
+  4096  bfloat16    4.000000     90.234%
+    32  bfloat16   40.250000      1.733%
+    32   float32   40.959972      0.000%
+```
+
+A flat `float16` accumulator stalls out once the running total dwarfs
+the product being added to it; summing 32 elements at a time keeps the
+error three orders of magnitude smaller.
+
+See the [usage guide](docs/USAGE.md) for the language and the
+[examples page](https://fpy.readthedocs.io/en/latest/example.html) for
+more.
+
+## Installation
+
+FPy can be installed from PyPI with either `uv` or `pip`, or built from
+source for development.  The following instructions assume a `bash`-like
+shell.
+
+### Installing from PyPI
+
+Requirements:
+ - Python 3.11 or later
+
+To install the latest stable release of FPy, run:
+```bash
+uv pip install fpy2
+```
+or, with `pip`:
+```bash
+pip install fpy2
+```
+The Triton backend also needs PyTorch, Triton and a GPU: install `fpy2[triton]`.
+
+### Installing from source
+
+Requirements:
+ - Python 3.11 or later
+ - `make`
+
+#### With `uv` (preferred)
+
+[uv](https://docs.astral.sh/uv/) is the recommended development
+workflow — it handles the virtual environment and dependency
+installation in a single step:
+```bash
+uv sync
+```
+This creates `.venv/` and installs FPy in editable mode along with the
+`dev` dependency group, pinned by `uv.lock`.  Rerun it to reset `.venv/` to
+the lockfile; it removes anything installed by hand.  Activate the
+environment with
+```bash
+source .venv/bin/activate
+```
+or prefix individual commands with `uv run` (e.g. `uv run pytest tests/unit`).
+
+#### With `pip` (legacy)
+
+This path is preserved for compatibility with existing tooling; new
+contributors should prefer `uv` above.
+
+If you do not have a Python virtual environment,
+create one using
+```bash
+python3 -m venv .venv/
+```
+and activate it using
+```bash
+source .venv/bin/activate
+```
+To install an instance of FPy for development, run:
+```bash
+pip install -e .[dev]
+```
+
+To uninstall FPy, run:
+```bash
+pip uninstall fpy2
+```
+
+### Testing
+
+There are a number of tests that can be run through
+the `Makefile` including
+```bash
+make lint
+```
+to ensure formatting and type safety;
+```bash
+make unittest
+```
+to run the unit tests;
+```bash
+make infratest
+```
+to run the infrastructure tests.

fpy2-0.2.4/README.md

@@ -0,0 +1,159 @@
+# FPy
+
+An embedded Python DSL for specifying and simulating numerical algorithms.
+
+Important links:
+ - PyPI package: [fpy2](https://pypi.org/project/fpy2/)
+ - Documentation: [fpy.readthedocs.io](https://fpy.readthedocs.io/)
+ - GitHub: [fpy](https://github.com/bksaiki/fpy)
+ - Guide: [USAGE.md](docs/USAGE.md)
+
+## Example
+
+FPy is Python with explicit control of both the mathematics and
+rounding: every operation is correctly rounded by the *rounding context*
+it appears in, and contexts are ordinary values you can pass around —
+including `fp.REAL`, which never rounds.  Here is a blocked dot product:
+the products are exact, each block of `K` elements is summed in a narrow
+format, and the running total is `float32`.
+
+```python
+import fpy2 as fp
+
+@fp.fpy(ctx=fp.REAL)
+def dot(xs: list[fp.Real], ys: list[fp.Real], K: int, block: fp.Context) -> fp.Real:
+    """A blocked dot product: exact products, blocks of `K` summed in `block`.
+    The length of `xs` must be a multiple of `K`."""
+    assert len(xs) == len(ys)
+    acc = 0
+    for start in range(0, len(xs), K):
+        with block:
+            inner_acc = 0
+            for x, y in zip(xs[start:start + K], ys[start:start + K]):
+                with fp.REAL:
+                    p = x * y       # every product is exact ...
+                inner_acc += p      # ... but block sums round to `block`
+        with fp.FP32:
+            acc += inner_acc        # one fp32 addition per block
+    return acc
+
+@fp.fpy(ctx=fp.REAL)
+def dot_ref(xs: list[fp.Real], ys: list[fp.Real]) -> fp.Real:
+    """The same dot product, with no rounding anywhere."""
+    return sum([x * y for x, y in zip(xs, ys)])
+
+xs = ys = [0.1] * 4096
+exact = dot_ref(xs, ys).as_rational()   # the true value, as a Fraction
+
+print(f'{"block":>6} {"format":>9} {"result":>11} {"rel. error":>11}')
+for K, name, ctx in [(4096, 'float16', fp.FP16), (32, 'float16', fp.FP16),
+                     (4096, 'bfloat16', fp.BF16), (32, 'bfloat16', fp.BF16),
+                     (32, 'float32', fp.FP32)]:
+    r = dot(xs, ys, K, ctx)
+    err = abs(r.as_rational() - exact) / exact
+    print(f'{K:>6} {name:>9} {float(r):>11.6f} {float(err):>11.3%}')
+```
+
+which prints
+
+```
+ block    format      result  rel. error
+  4096   float16   32.000000     21.875%
+    32   float16   40.968750      0.021%
+  4096  bfloat16    4.000000     90.234%
+    32  bfloat16   40.250000      1.733%
+    32   float32   40.959972      0.000%
+```
+
+A flat `float16` accumulator stalls out once the running total dwarfs
+the product being added to it; summing 32 elements at a time keeps the
+error three orders of magnitude smaller.
+
+See the [usage guide](docs/USAGE.md) for the language and the
+[examples page](https://fpy.readthedocs.io/en/latest/example.html) for
+more.
+
+## Installation
+
+FPy can be installed from PyPI with either `uv` or `pip`, or built from
+source for development.  The following instructions assume a `bash`-like
+shell.
+
+### Installing from PyPI
+
+Requirements:
+ - Python 3.11 or later
+
+To install the latest stable release of FPy, run:
+```bash
+uv pip install fpy2
+```
+or, with `pip`:
+```bash
+pip install fpy2
+```
+The Triton backend also needs PyTorch, Triton and a GPU: install `fpy2[triton]`.
+
+### Installing from source
+
+Requirements:
+ - Python 3.11 or later
+ - `make`
+
+#### With `uv` (preferred)
+
+[uv](https://docs.astral.sh/uv/) is the recommended development
+workflow — it handles the virtual environment and dependency
+installation in a single step:
+```bash
+uv sync
+```
+This creates `.venv/` and installs FPy in editable mode along with the
+`dev` dependency group, pinned by `uv.lock`.  Rerun it to reset `.venv/` to
+the lockfile; it removes anything installed by hand.  Activate the
+environment with
+```bash
+source .venv/bin/activate
+```
+or prefix individual commands with `uv run` (e.g. `uv run pytest tests/unit`).
+
+#### With `pip` (legacy)
+
+This path is preserved for compatibility with existing tooling; new
+contributors should prefer `uv` above.
+
+If you do not have a Python virtual environment,
+create one using
+```bash
+python3 -m venv .venv/
+```
+and activate it using
+```bash
+source .venv/bin/activate
+```
+To install an instance of FPy for development, run:
+```bash
+pip install -e .[dev]
+```
+
+To uninstall FPy, run:
+```bash
+pip uninstall fpy2
+```
+
+### Testing
+
+There are a number of tests that can be run through
+the `Makefile` including
+```bash
+make lint
+```
+to ensure formatting and type safety;
+```bash
+make unittest
+```
+to run the unit tests;
+```bash
+make infratest
+```
+to run the infrastructure tests.

{fpy2-0.2.3 → fpy2-0.2.4}/fpy2/__init__.py

@@ -36,6 +36,7 @@ from .backend import (
     Backend,
     CppCompiler,
     FPCoreCompiler,
+    TritonCompiler,
 )
 
 # runtime support

{fpy2-0.2.3 → fpy2-0.2.4}/fpy2/analysis/__init__.py

@@ -9,6 +9,7 @@ from .array_size import (
     ListSize,
     TupleSize,
     concrete_size,
+    static_trip_count,
 )
 from .call_graph import CallGraph, CallGraphAnalysis, CallGraphError
 from .context_use import (
@@ -17,13 +18,16 @@ from .context_use import (
     ContextUse,
     ContextUseAnalysis,
     ContextUseSite,
+    PartialContext,
+    ScopeContext,
 )
 from .define_use import DefCtx, DefineUse, DefineUseAnalysis, UseSite
 from .defs import DefAnalysis
 from .escape import Escape, EscapeSummary
 from .format_infer import FormatAnalysis, FormatInfer
+from .hoistability import Hoistability, HoistabilityAnalysis
 from .live_vars import LiveVars
-from .partial_eval import PartialEval, PartialEvalInfo
+from .partial_eval import PartialEval, PartialEvalInfo, base_env
 from .purity import Purity
 from .reachability import Reachability
 from .reaching_defs import (

{fpy2-0.2.3 → fpy2-0.2.4}/fpy2/analysis/alias.py

@@ -53,9 +53,7 @@ Equality rather than inclusion is deliberate.  Each place denotes exactly one
 region and distinct regions are disjoint — Steensgaard-style, where a
 subset-based solver would give each place an overlapping points-to *set* — so
 different regions never alias and the same region may.  That over-approximates,
-the safe direction for every consumer, and it is adequate here: measured over the
-test corpus, only three merges anywhere lose precision against a subset-based
-solver.
+the safe direction for every consumer, and it is adequate here.
 
 An expression kind not in the table is handled conservatively: it gets its own
 allocation site, and every list-carrying variable inside it is marked shared
@@ -350,6 +348,9 @@ class _Regions:
     def sites_at(self, c: Region) -> frozenset[AllocSite]:
         return frozenset(self._sites.get(self.find(c), ()))
 
+    def is_slot(self, c: Region) -> bool:
+        return self._slots.get(self.find(c), 0) > 0
+
     def referrers(self, c: Region) -> int:
         root = self.find(c)
         return len(self._names.get(root, ())) + self._slots.get(root, 0)
@@ -402,6 +403,8 @@ class AliasAnalysis:
     Attributes:
         sites:            every list allocation, plus one per nested parameter list.
         written_regions:  regions an ``xs[i] = e`` here stores into.
+        stored_regions:   regions whose cells a store here replaces:
+                          ``xss[i][j] = e`` replaces a row's, not ``xss``'s.
         slot_replaced:    element regions an ``xss[i] = <list>`` replaces.
         returned_levels:  regions the ``return``s hand back, by depth.
         consumed_defs:    per region, definitions whose value *moves* into a
@@ -414,6 +417,7 @@ class AliasAnalysis:
     _by_expr: dict[Expr, Region]
     _site_region: dict[AllocSite, Region]
     written_regions: set[Region] = field(default_factory=set)
+    stored_regions: set[Region] = field(default_factory=set)
     slot_replaced: set[Region] = field(default_factory=set)
     returned_levels: list[set[Region]] = field(default_factory=list)
     consumed_defs: dict[Region, set[Definition]] = field(default_factory=dict)
@@ -516,6 +520,17 @@ class AliasAnalysis:
         """The allocations that may live in *region*."""
         return frozenset() if region is None else self._regions.sites_at(region)
 
+    def inside_at(self, region: Region) -> bool:
+        """Whether *region* is a place *within* a container — a list's elements,
+        a tuple's field — rather than a place a name denotes.
+
+        A container holds many elements, so such a region stands for one list
+        per element of its container, however few allocations reach it.  That
+        is the difference between "may be the same list", which a region
+        answers, and "is exactly one list", which it does not.
+        """
+        return self._regions.is_slot(region)
+
     def is_shared(self, site: AllocSite) -> bool:
         """Whether more than one place may refer to *site*."""
         return self._regions.referrers(self._site_region[site]) > 1
@@ -576,6 +591,12 @@ class AliasAnalysis:
             return False
         return self._regions.find(ca) is self._regions.find(cb)
 
+    def may_change(self, d: Definition) -> bool:
+        """Whether the list *d* names may have an element replaced, through
+        any name here or by a call it is handed to."""
+        r = self.region_of(d)
+        return r is None or r in self.stored_regions or self.escapes_at(r)
+
 
 class _EscapeVars(DefaultVisitor):
     """Marks every list-carrying variable inside an expression as shared outward.
@@ -633,6 +654,7 @@ class _Builder(DefaultVisitor):
         facts = _RegionFacts(alias, self.def_use)
         facts._visit_function(self.func, None)
         alias.written_regions = facts.written
+        alias.stored_regions = facts.stored
         alias.slot_replaced = facts.slot_replaced
         alias.returned_levels = facts.returned_levels
         alias.consumed_defs = facts.consumed
@@ -929,6 +951,7 @@ class _RegionFacts(DefaultVisitor):
         self.alias = alias
         self.def_use = def_use
         self.written: set[Region] = set()
+        self.stored: set[Region] = set()
         self.slot_replaced: set[Region] = set()
         self.returned_levels: list[set[Region]] = []
         self.consumed: dict[Region, set[Definition]] = {}
@@ -947,6 +970,9 @@ class _RegionFacts(DefaultVisitor):
             if isinstance(d, AssignDef) and isinstance(d.site, IndexedAssign):
                 if (r := alias.region_of(d)) is not None:
                     self.written.add(r)
+                depth = len(d.site.indices) - 1
+                if (r := alias.region_of(d, depth)) is not None:
+                    self.stored.add(r)
 
     def _visit_block(self, block: StmtBlock, ctx):
         outer, self._siblings = self._siblings, set(block.stmts)