hypergrid 0.0.1__tar.gz

hypergrid-0.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023-present Justin Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hypergrid-0.0.1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: hypergrid
+Version: 0.0.1
+Summary: Hypergrid enables concise declaration of parameter grids for hyperparameter optimization and batch jobs.
+Author-email: Justin Yan <justin@iomorphic.com>
+Project-URL: Homepage, https://github.com/justin-yan/hypergrid
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn<2; extra == "sklearn"
+
+# hypergrid
+
+Hypergrid enables concise declaration and manipulation of parameter grid spaces, with an aim towards use cases such as hyperparameter tuning or defining large batch jobs.
+
+Use the following features to lazily declare a parameter grid:
+
+- Dimension and Grid direct instantiation
+- `+` and `|` for "sum" or "union" types (concatenation)
+- `*` for "product" types
+- `&` for coiteration (zip)
+- `select` to project dimensions by name
+
+There are also a few transformations that can be lazily applied element-wise, which take a GridElement (a namedtuple of dimension<->value) as input.
+
+- `filter` to apply boolean predicate
+- `map` for lambda transformation
+- `map_to` for map + concat
+
+Once a parameter grid is declared, there are two ways to "materialize" your grid, which return GridElements.
+
+- `__iter__`: a grid is directly iterable
+- `sample`: allows you to sample from the grid according to a sampling strategy
+
+## Usage Examples
+
+```python
+from hypergrid.dsl import *
+from dataclasses import dataclass
+
+# First, we need to create a Dimension, which is essentially a named, finite, 1-d collection
+d = Dimension(custom_name=[1, 2, 3])        # any python Collection will work - set, dict, range(), etc.
+assert d.name == "custom_name"              # the argument name is used as the dimension's name.
+d.with_name("ints")                         # which you can reset
+Uniform(low=1, high=5).take(5)              
+ExponentialStep(start=1, step=1.1).take(6)  # You can also take a dimension from a Distribution or HIterable
+
+# You can `len(d)` or `[i for i in d]`, but grids are more interesting
+g = d.to_grid()
+i2d = Dimension(ints=[4, 5, 6])
+cd = Dimension(chars=["a", "b", "c", "d"])
+union_ints = g + i2d     # result is length 6: Concatenate two grids that have the same underlying dimensions
+product_g = g * cd       # result is length 12: tuples (1, "a") - take the cartesian product of the underlying grids
+zip_g = g & cd           # result is length 3: tuples (1, "a") - zip two grids together, up to the shorter grid
+
+ml = [i for i in zip_g]  # You can iterate through a grid
+tl = zip_g.take(5)       # or you can just take up to a certain number of grid elements from it
+print(tl[0].ints), print(tl[0].chars)  # The iterator elements are python NamedTuples taken from the dimension names.
+
+# These gridelements can be referenced and used in the grid higher-order functions
+zip_g.filter(lambda ge: ge.chars in ["a", "b"])    # result is length 2: keep the tuples (1, "a") and (2, "b")
+zip_g.map(doubled=lambda ge: ge.ints * 2)          # result is length 3, with single attribute (drops `ints` and `chars`)
+mt = zip_g.map_to(doubled=lambda ge: ge.ints * 2)  # result is length 3, appends `doubled` and keeps `ints` and `chars`
+print(mt.select("doubled", "ints").take(1)[0])     # resulting gridelement no longer has `chars`
+
+# There are some other utility methods on a grid:
+zip_g.sample()                                     # Randomly samples a single grid element from a grid
+zip_g.to_sklearn()                                 # The Grid.to_* methods convert HyperGrids to other grid formats
+
+# The general idea is to allow for fairly extensive grid construction routines
+@dataclass
+class FakeModel:
+    idx: int
+    param1: float
+
+g = HyperGrid(  # A grid with 4 x 10 combinations
+    ExponentialStep(start=1.0, step=1.5).take(4).with_name("param1"),
+    idx=range(10)
+).instantiate(model=FakeModel).select("model") + \
+    HyperGrid(  # A different grid with 15 combinations
+        Uniform(low=-1, high=1).take(5).with_name("param1"),
+        idx=[10, 20, 30]        
+    ).instantiate(model=FakeModel).select("model")
+assert len(g) == 55
+g.sample()
+```
+

hypergrid-0.0.1/README.md

@@ -0,0 +1,76 @@
+# hypergrid
+
+Hypergrid enables concise declaration and manipulation of parameter grid spaces, with an aim towards use cases such as hyperparameter tuning or defining large batch jobs.
+
+Use the following features to lazily declare a parameter grid:
+
+- Dimension and Grid direct instantiation
+- `+` and `|` for "sum" or "union" types (concatenation)
+- `*` for "product" types
+- `&` for coiteration (zip)
+- `select` to project dimensions by name
+
+There are also a few transformations that can be lazily applied element-wise, which take a GridElement (a namedtuple of dimension<->value) as input.
+
+- `filter` to apply boolean predicate
+- `map` for lambda transformation
+- `map_to` for map + concat
+
+Once a parameter grid is declared, there are two ways to "materialize" your grid, which return GridElements.
+
+- `__iter__`: a grid is directly iterable
+- `sample`: allows you to sample from the grid according to a sampling strategy
+
+## Usage Examples
+
+```python
+from hypergrid.dsl import *
+from dataclasses import dataclass
+
+# First, we need to create a Dimension, which is essentially a named, finite, 1-d collection
+d = Dimension(custom_name=[1, 2, 3])        # any python Collection will work - set, dict, range(), etc.
+assert d.name == "custom_name"              # the argument name is used as the dimension's name.
+d.with_name("ints")                         # which you can reset
+Uniform(low=1, high=5).take(5)              
+ExponentialStep(start=1, step=1.1).take(6)  # You can also take a dimension from a Distribution or HIterable
+
+# You can `len(d)` or `[i for i in d]`, but grids are more interesting
+g = d.to_grid()
+i2d = Dimension(ints=[4, 5, 6])
+cd = Dimension(chars=["a", "b", "c", "d"])
+union_ints = g + i2d     # result is length 6: Concatenate two grids that have the same underlying dimensions
+product_g = g * cd       # result is length 12: tuples (1, "a") - take the cartesian product of the underlying grids
+zip_g = g & cd           # result is length 3: tuples (1, "a") - zip two grids together, up to the shorter grid
+
+ml = [i for i in zip_g]  # You can iterate through a grid
+tl = zip_g.take(5)       # or you can just take up to a certain number of grid elements from it
+print(tl[0].ints), print(tl[0].chars)  # The iterator elements are python NamedTuples taken from the dimension names.
+
+# These gridelements can be referenced and used in the grid higher-order functions
+zip_g.filter(lambda ge: ge.chars in ["a", "b"])    # result is length 2: keep the tuples (1, "a") and (2, "b")
+zip_g.map(doubled=lambda ge: ge.ints * 2)          # result is length 3, with single attribute (drops `ints` and `chars`)
+mt = zip_g.map_to(doubled=lambda ge: ge.ints * 2)  # result is length 3, appends `doubled` and keeps `ints` and `chars`
+print(mt.select("doubled", "ints").take(1)[0])     # resulting gridelement no longer has `chars`
+
+# There are some other utility methods on a grid:
+zip_g.sample()                                     # Randomly samples a single grid element from a grid
+zip_g.to_sklearn()                                 # The Grid.to_* methods convert HyperGrids to other grid formats
+
+# The general idea is to allow for fairly extensive grid construction routines
+@dataclass
+class FakeModel:
+    idx: int
+    param1: float
+
+g = HyperGrid(  # A grid with 4 x 10 combinations
+    ExponentialStep(start=1.0, step=1.5).take(4).with_name("param1"),
+    idx=range(10)
+).instantiate(model=FakeModel).select("model") + \
+    HyperGrid(  # A different grid with 15 combinations
+        Uniform(low=-1, high=1).take(5).with_name("param1"),
+        idx=[10, 20, 30]        
+    ).instantiate(model=FakeModel).select("model")
+assert len(g) == 55
+g.sample()
+```
+

hypergrid-0.0.1/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hypergrid"
+version = "0.0.1"
+authors = [
+    { name="Justin Yan", email="justin@iomorphic.com" }
+]
+description = "Hypergrid enables concise declaration of parameter grids for hyperparameter optimization and batch jobs."
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    ######
+    ### Custom Dependencies Section Begin
+    ######
+
+    ######
+    ### Custom Dependencies Section End
+    ######
+]
+
+[project.urls]
+"Homepage" = "https://github.com/justin-yan/hypergrid"
+
+[dependency-groups]
+dev = [
+    "pytest>5",
+    "hypothesis>5",
+    "coverage>5",
+    "ruff>0.2.1",
+    "mypy>1.2"
+]
+
+[tool.setuptools]
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.package-data]
+"hypergrid" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+#######
+### Miscellaneous Tool Configuration
+#######
+[tool.ruff]
+line-length = 150
+target-version = "py311"
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["hypergrid"]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q --doctest-modules"
+log_cli = true
+log_cli_level = "WARN"
+log_cli_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
+log_cli_date_format = "%Y-%m-%d %H:%M:%S"
+
+[tool.mypy]
+mypy_path = "src"
+disallow_untyped_defs = true
+disallow_any_unimported = true
+allow_redefinition = false
+ignore_errors = false
+implicit_reexport = false
+local_partial_types = true
+no_implicit_optional = true
+strict_equality = true
+strict_optional = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+######
+### Custom Directives Section Begin
+######
+
+
+[[tool.mypy.overrides]]
+module = [
+    "sklearn.*",
+]
+ignore_errors = true
+ignore_missing_imports = true
+
+
+[project.optional-dependencies]
+sklearn = [
+    "scikit-learn<2",
+]
+
+######
+### Custom Directives Section End
+######

hypergrid-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hypergrid-0.0.1/src/hypergrid/dimension.py

@@ -0,0 +1,44 @@
+import random
+from collections.abc import Collection
+from typing import TYPE_CHECKING, Generic, Iterator, Self, TypeAlias, TypeVar
+
+if TYPE_CHECKING:
+    from hypergrid.grid import HyperGrid
+
+T = TypeVar("T")
+RawDimension: TypeAlias = tuple[str, Collection]
+
+
+class Dimension(Generic[T]):
+    name: str
+
+    def __init__(self, **kwargs: Collection[T]):
+        assert len(kwargs) == 1, "Dimension is 1-d, use Grids for multiple dimensions"
+        for name, values in kwargs.items():
+            assert isinstance(values, Collection), "Dimension assumes finite length"
+            self.name = name
+            self.values = values
+
+    def __repr__(self) -> str:
+        return f"Dimension({repr(self.values)})"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __len__(self) -> int:
+        return len(self.values)
+
+    def __iter__(self) -> Iterator[T]:
+        yield from self.values
+
+    def sample(self) -> T:
+        return random.choice(self.values)  # type: ignore
+
+    def with_name(self, name: str) -> Self:
+        self.name = name
+        return self
+
+    def to_grid(self) -> "HyperGrid":
+        from hypergrid.grid import HyperGrid
+
+        return HyperGrid(self)

hypergrid-0.0.1/src/hypergrid/dsl.py

@@ -0,0 +1,6 @@
+from hypergrid.dimension import Dimension
+from hypergrid.gen.distribution import Uniform
+from hypergrid.gen.iterable import ExponentialStep
+from hypergrid.grid import HyperGrid
+
+__all__ = ["HyperGrid", "Dimension", "Uniform", "ExponentialStep"]

hypergrid-0.0.1/src/hypergrid/ext/sklearn.py

@@ -0,0 +1,32 @@
+try:
+    from sklearn.model_selection import ParameterGrid
+except ImportError:
+    raise ImportError("If using sklearn conversion functionality, install hypergrid with `sklearn` extras via `pip install hypergrid[sklearn]`")
+
+from hypergrid.grid import Grid, HyperGrid, ProductGrid
+
+
+def _grid_to_sklearn(grid: Grid) -> ParameterGrid:  # type: ignore[no-any-unimported]
+    """
+    SKLearn's ParameterGrid accepts {str: sequence}
+
+    Because these ParameterGrids don't directly compose, we use a recursive helper, and then convert the composable dicts
+      into a ParameterGrid in this outer wrapper.
+    """
+    return ParameterGrid(_grid_to_sklearn_recursive_helper(grid))
+
+
+def _grid_to_sklearn_recursive_helper(grid: Grid) -> dict:
+    """
+    SKLearn's param_grid dictionaries only support simple cartesian products, so only the Grid and ProductGrid elements
+      are convertible to SKLearn parameter grids.
+    """
+    match grid:
+        case HyperGrid():
+            return {dim.name: [v for v in dim] for dim in grid.dimensions}
+        case ProductGrid():
+            d1 = _grid_to_sklearn_recursive_helper(grid.grid1)
+            d2 = _grid_to_sklearn_recursive_helper(grid.grid2)
+            return d1 | d2
+        case _:
+            raise ValueError("Converting Grid to SKLearn ParameterGrid is not compatible with")

hypergrid-0.0.1/src/hypergrid/gen/distribution.py

@@ -0,0 +1,27 @@
+import random
+from typing import Any, Iterator, Protocol, TypeVar, runtime_checkable
+
+from hypergrid.gen.iterable import HIterable
+
+T = TypeVar("T", covariant=True)
+
+
+@runtime_checkable
+class Distribution(HIterable, Protocol[T]):
+    def sample(self) -> T: ...
+
+    def __iter__(self) -> Iterator[T]:
+        while True:
+            yield self.sample()
+
+    def __call__(self, *args: Any, **kwargs: Any) -> T:
+        return self.sample()
+
+
+class Uniform(Distribution):
+    def __init__(self, low: float, high: float) -> None:
+        self.low = low
+        self.high = high
+
+    def sample(self) -> float:
+        return random.uniform(self.low, self.high)

hypergrid-0.0.1/src/hypergrid/gen/iterable.py

@@ -0,0 +1,32 @@
+from itertools import islice
+from typing import Iterator, Protocol, Self, TypeVar, runtime_checkable
+
+from hypergrid.dimension import Dimension
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class HIterable(Protocol[T]):
+    name: str = "anonymous"
+
+    def __iter__(self) -> Iterator[T]: ...
+
+    def take(self, n: int) -> Dimension[T]:
+        return Dimension(**{self.name: [i for i in islice(self, n)]})
+
+    def with_name(self, name: str) -> Self:
+        self.name = name
+        return self
+
+
+class ExponentialStep(HIterable):
+    def __init__(self, start: float, step: float) -> None:
+        self.start = start
+        self.step = step
+
+    def __iter__(self) -> Iterator[float]:
+        cursor = self.start
+        while True:
+            yield cursor
+            cursor *= self.step

hypergrid-0.0.1/src/hypergrid/grid.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import itertools
+import random
+from collections import namedtuple
+from collections.abc import Collection
+from functools import cached_property
+from math import prod
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional, Protocol, Type, runtime_checkable
+
+from hypergrid.gen.iterable import HIterable
+from hypergrid.util import instantiate_lambda
+
+if TYPE_CHECKING:
+    from sklearn.model_selection import ParameterGrid
+
+from hypergrid.dimension import Dimension, RawDimension
+
+
+@runtime_checkable
+class Grid(Protocol):
+    grid_element: Type[tuple]
+
+    @property
+    def dimension_names(self) -> list[str]:
+        return list(self.grid_element._fields)  # type: ignore[attr-defined]
+
+    def __repr__(self) -> str: ...
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __len__(self) -> int: ...
+
+    def __iter__(self) -> Iterator: ...
+
+    def take(self, n: int) -> list:
+        return [i for i in itertools.islice(self, n)]
+
+    def sample(self) -> tuple: ...
+
+    def __add__(self, other: Grid | Dimension | RawDimension) -> SumGrid:
+        match other:
+            case Grid():
+                return SumGrid(self, other)
+            case Dimension():
+                return SumGrid(self, HyperGrid(other))
+            case (str(s), coll) if isinstance(coll, Collection):  # RawDimension
+                return SumGrid(self, HyperGrid(Dimension(**{s: coll})))
+            case _:
+                raise ValueError("Invalid argument for grid operation")
+
+    def __or__(self, other: Grid | Dimension | RawDimension) -> SumGrid:
+        return self.__add__(other)
+
+    def __mul__(self, other: Grid | Dimension | RawDimension) -> ProductGrid:
+        match other:
+            case Grid():
+                return ProductGrid(self, other)
+            case Dimension():
+                return ProductGrid(self, HyperGrid(other))
+            case (str(s), coll) if isinstance(coll, Collection):  # RawDimension
+                return ProductGrid(self, HyperGrid(Dimension(**{s: coll})))
+            case _:
+                raise ValueError("Invalid argument for grid operation")
+
+    def __and__(self, other: Grid | Dimension | HIterable | RawDimension) -> ZipGrid:
+        match other:
+            case Grid():
+                return ZipGrid(self, other)
+            case Dimension():
+                return ZipGrid(self, HyperGrid(other))
+            case (str(s), coll) if isinstance(coll, Collection):  # RawDimension
+                return ZipGrid(self, HyperGrid(Dimension(**{s: coll})))
+            case HIterable():
+                return ZipGrid(self, HyperGrid(other.take(len(self))))
+            case _:
+                raise ValueError("Invalid argument for grid operation")
+
+    def filter(self, predicate: Callable[[Any], bool]) -> FilterGrid:
+        return FilterGrid(self, predicate)
+
+    def select(self, *dim_names: str) -> SelectGrid:
+        return SelectGrid(self, *dim_names)
+
+    def map(self, **kwargs: Callable[[Any], Any]) -> MapGrid:
+        return MapGrid(self, **kwargs)
+
+    def map_to(self, **kwargs: Callable[[Any], Any]) -> MapToGrid:
+        return MapToGrid(self, **kwargs)
+
+    def instantiate(self, **kwargs: Type) -> MapToGrid:
+        return self.map_to(**{name: instantiate_lambda(cls) for name, cls in kwargs.items()})
+
+    def to_sklearn(self) -> ParameterGrid:  # type: ignore[no-any-unimported]
+        from hypergrid.ext.sklearn import _grid_to_sklearn
+
+        return _grid_to_sklearn(self)
+
+
+class HyperGrid(Grid):
+    dimensions: list[Dimension]
+
+    def __init__(self, *args: Dimension, **kwargs: Collection) -> None:
+        dims = list(args)
+        for dim, values in kwargs.items():
+            dims.append(Dimension(**{dim: values}))
+        assert len(dims) > 0, "Must provide at least one meaningful dimension"
+        assert len(dims) == len(set(dims)), "Dimension names must be unique"
+        self.dimensions = dims
+        self.grid_element = namedtuple("GridElement", [dim.name for dim in self.dimensions])  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        dim_str = ", ".join([repr(dim) for dim in self.dimensions])
+        return f"HyperGrid({dim_str})"
+
+    def __len__(self) -> int:
+        return prod([len(dim) for dim in self.dimensions])
+
+    def __iter__(self) -> Iterator:
+        for element_tuple in itertools.product(*[dim.__iter__() for dim in self.dimensions]):
+            yield self.grid_element(*element_tuple)
+
+    def sample(self) -> tuple:
+        return self.grid_element(*tuple([dim.sample() for dim in self.dimensions]))
+
+
+class SumGrid(Grid):
+    def __init__(self, grid1: Grid, grid2: Grid) -> None:
+        assert set(grid1.dimension_names) == set(grid2.dimension_names)
+        self.grid1 = grid1
+        self.grid2 = grid2
+        self.grid_element = grid1.grid_element
+
+    def __repr__(self) -> str:
+        return f"SumGrid({repr(self.grid1)}, {repr(self.grid2)})"
+
+    def __len__(self) -> int:
+        return len(self.grid1) + len(self.grid2)
+
+    def __iter__(self) -> Iterator:
+        for grid_element in itertools.chain(self.grid1, self.grid2):
+            yield grid_element
+
+    def sample(self) -> tuple:
+        return random.choice([ge for ge in self])
+
+
+class ProductGrid(Grid):
+    def __init__(self, grid1: Grid, grid2: Grid) -> None:
+        assert set(grid1.dimension_names).isdisjoint(set(grid2.dimension_names)), "Dimensions must be exactly matching"
+        self.grid1 = grid1
+        self.grid2 = grid2
+        self.grid_element = namedtuple("GridElement", grid1.dimension_names + grid2.dimension_names)  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        return f"ProductGrid({repr(self.grid1)}, {repr(self.grid2)})"
+
+    def __len__(self) -> int:
+        return len(self.grid1) * len(self.grid2)
+
+    def __iter__(self) -> Iterator:
+        for grid_element1, grid_element2 in itertools.product(self.grid1, self.grid2):
+            yield self.grid_element(*(grid_element1 + grid_element2))
+
+    def sample(self) -> tuple:
+        ge1 = self.grid1.sample()
+        ge2 = self.grid2.sample()
+        return self.grid_element(*(ge1 + ge2))
+
+
+class ZipGrid(Grid):
+    """
+    Mimic python "zip" of two iterables.
+    """
+
+    def __init__(self, grid1: Grid, grid2: Grid) -> None:
+        assert set(grid1.dimension_names).isdisjoint(set(grid2.dimension_names)), "Dimensions must be exactly matching"
+        self.grid1 = grid1
+        self.grid2 = grid2
+        self.grid_element = namedtuple("GridElement", grid1.dimension_names + grid2.dimension_names)  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        return f"ZipGrid({repr(self.grid1)}, {repr(self.grid2)})"
+
+    def __len__(self) -> int:
+        return min(len(self.grid1), len(self.grid2))
+
+    def __iter__(self) -> Iterator:
+        for grid_element1, grid_element2 in zip(self.grid1, self.grid2):
+            yield self.grid_element(*(grid_element1 + grid_element2))
+
+    def sample(self) -> tuple:
+        return random.choice([ge for ge in self])
+
+
+class FilterGrid(Grid):
+    _iter_cache: Optional[list] = None
+
+    def __init__(self, grid: Grid, predicate: Callable[[Any], bool]) -> None:
+        self.grid = grid
+        self.predicate = predicate
+        self.grid_element = grid.grid_element
+
+    def __repr__(self) -> str:
+        return f"FilterGrid({repr(self.grid)}, {self.predicate.__name__})"
+
+    def __len__(self) -> int:
+        return self._len
+
+    @cached_property
+    def _len(self) -> int:
+        return len([x for x in self])
+
+    def __iter__(self) -> Iterator:
+        for grid_element in self.grid:
+            if self.predicate(grid_element):
+                yield grid_element
+
+    def sample(self) -> tuple:
+        if self._iter_cache is not None:
+            sublist = self._iter_cache
+        else:
+            sublist = [ge for ge in self]
+            self._iter_cache = sublist
+        return random.choice(sublist)
+
+
+class SelectGrid(Grid):
+    def __init__(self, grid: Grid, *select_dims: str) -> None:
+        assert len(set(select_dims)) == len(select_dims), "Selected columns must all be unique"
+        assert set(select_dims) <= set(grid.dimension_names), "Selected dimensions must be subset of grid dimensions"
+        self.grid = grid
+        self.select_dims = select_dims
+        self.grid_element = namedtuple("GridElement", [name for name in grid.dimension_names if name in self.select_dims])  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        return f"SelectGrid({repr(self.grid)}, {repr(self.select_dims)})"
+
+    def __len__(self) -> int:
+        return len(self.grid)
+
+    def __iter__(self) -> Iterator:
+        for grid_element in self.grid:
+            yield self.grid_element(*self._process_single(grid_element))
+
+    def sample(self) -> tuple:
+        return self.grid_element(*self._process_single(self.grid.sample()))
+
+    def _process_single(self, ge: tuple) -> list:
+        element_list = []
+        for dim_name in self.dimension_names:
+            try:
+                selected_value = getattr(ge, dim_name)
+            except AttributeError:
+                selected_value = None
+            element_list.append(selected_value)
+        return element_list
+
+
+class MapGrid(Grid):
+    def __init__(self, grid: Grid, **kwargs: Callable[[Any], Any]) -> None:
+        assert len(set(kwargs.keys())) == len(kwargs.keys()), "New columns must all have unique names"
+        self.grid = grid
+        self.dimension_mapping = kwargs
+        self.grid_element = namedtuple("GridElement", list(kwargs.keys()))  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        mappings_str = ", ".join([f"{dim_name}={func.__name__}" for dim_name, func in self.dimension_mapping.items()])
+        return f"MapGrid({repr(self.grid)}, {mappings_str})"
+
+    def __len__(self) -> int:
+        return len(self.grid)
+
+    def __iter__(self) -> Iterator:
+        for grid_element in self.grid:
+            yield self.grid_element(**self._process_single(grid_element))
+
+    def sample(self) -> tuple:
+        return self.grid_element(**self._process_single(self.grid.sample()))
+
+    def _process_single(self, ge: tuple) -> dict:
+        return {dim_name: func(ge) for dim_name, func in self.dimension_mapping.items()}
+
+
+class MapToGrid(Grid):
+    def __init__(self, grid: Grid, **kwargs: Callable[[Any], Any]) -> None:
+        assert len(set(kwargs.keys())) == len(kwargs.keys()), "New columns must all have unique names"
+        assert set(grid.dimension_names).isdisjoint(set(kwargs.keys())), "New columns must not have name collisions with old columns"
+        self.grid = grid
+        self.dimension_mapping = kwargs
+        self.grid_element = namedtuple("GridElement", grid.dimension_names + list(kwargs.keys()))  # type: ignore[misc]
+
+    def __repr__(self) -> str:
+        mappings_str = ", ".join([f"{dim_name}={func.__name__}" for dim_name, func in self.dimension_mapping.items()])
+        return f"MapToGrid({repr(self.grid)}, {mappings_str})"
+
+    def __len__(self) -> int:
+        return len(self.grid)
+
+    def __iter__(self) -> Iterator:
+        for grid_element in self.grid:
+            yield self.grid_element(**self._process_single(grid_element))
+
+    def sample(self) -> tuple:
+        return self.grid_element(**self._process_single(self.grid.sample()))
+
+    def _process_single(self, ge: tuple) -> dict:
+        new_values = {dim_name: func(ge) for dim_name, func in self.dimension_mapping.items()}
+        return ge._asdict() | new_values  # type: ignore

hypergrid-0.0.1/src/hypergrid/util.py

@@ -0,0 +1,5 @@
+from typing import Callable, Type
+
+
+def instantiate_lambda(cls: Type) -> Callable:
+    return lambda ge: cls(**ge._asdict())

hypergrid-0.0.1/src/hypergrid.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: hypergrid
+Version: 0.0.1
+Summary: Hypergrid enables concise declaration of parameter grids for hyperparameter optimization and batch jobs.
+Author-email: Justin Yan <justin@iomorphic.com>
+Project-URL: Homepage, https://github.com/justin-yan/hypergrid
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn<2; extra == "sklearn"
+
+# hypergrid
+
+Hypergrid enables concise declaration and manipulation of parameter grid spaces, with an aim towards use cases such as hyperparameter tuning or defining large batch jobs.
+
+Use the following features to lazily declare a parameter grid:
+
+- Dimension and Grid direct instantiation
+- `+` and `|` for "sum" or "union" types (concatenation)
+- `*` for "product" types
+- `&` for coiteration (zip)
+- `select` to project dimensions by name
+
+There are also a few transformations that can be lazily applied element-wise, which take a GridElement (a namedtuple of dimension<->value) as input.
+
+- `filter` to apply boolean predicate
+- `map` for lambda transformation
+- `map_to` for map + concat
+
+Once a parameter grid is declared, there are two ways to "materialize" your grid, which return GridElements.
+
+- `__iter__`: a grid is directly iterable
+- `sample`: allows you to sample from the grid according to a sampling strategy
+
+## Usage Examples
+
+```python
+from hypergrid.dsl import *
+from dataclasses import dataclass
+
+# First, we need to create a Dimension, which is essentially a named, finite, 1-d collection
+d = Dimension(custom_name=[1, 2, 3])        # any python Collection will work - set, dict, range(), etc.
+assert d.name == "custom_name"              # the argument name is used as the dimension's name.
+d.with_name("ints")                         # which you can reset
+Uniform(low=1, high=5).take(5)              
+ExponentialStep(start=1, step=1.1).take(6)  # You can also take a dimension from a Distribution or HIterable
+
+# You can `len(d)` or `[i for i in d]`, but grids are more interesting
+g = d.to_grid()
+i2d = Dimension(ints=[4, 5, 6])
+cd = Dimension(chars=["a", "b", "c", "d"])
+union_ints = g + i2d     # result is length 6: Concatenate two grids that have the same underlying dimensions
+product_g = g * cd       # result is length 12: tuples (1, "a") - take the cartesian product of the underlying grids
+zip_g = g & cd           # result is length 3: tuples (1, "a") - zip two grids together, up to the shorter grid
+
+ml = [i for i in zip_g]  # You can iterate through a grid
+tl = zip_g.take(5)       # or you can just take up to a certain number of grid elements from it
+print(tl[0].ints), print(tl[0].chars)  # The iterator elements are python NamedTuples taken from the dimension names.
+
+# These gridelements can be referenced and used in the grid higher-order functions
+zip_g.filter(lambda ge: ge.chars in ["a", "b"])    # result is length 2: keep the tuples (1, "a") and (2, "b")
+zip_g.map(doubled=lambda ge: ge.ints * 2)          # result is length 3, with single attribute (drops `ints` and `chars`)
+mt = zip_g.map_to(doubled=lambda ge: ge.ints * 2)  # result is length 3, appends `doubled` and keeps `ints` and `chars`
+print(mt.select("doubled", "ints").take(1)[0])     # resulting gridelement no longer has `chars`
+
+# There are some other utility methods on a grid:
+zip_g.sample()                                     # Randomly samples a single grid element from a grid
+zip_g.to_sklearn()                                 # The Grid.to_* methods convert HyperGrids to other grid formats
+
+# The general idea is to allow for fairly extensive grid construction routines
+@dataclass
+class FakeModel:
+    idx: int
+    param1: float
+
+g = HyperGrid(  # A grid with 4 x 10 combinations
+    ExponentialStep(start=1.0, step=1.5).take(4).with_name("param1"),
+    idx=range(10)
+).instantiate(model=FakeModel).select("model") + \
+    HyperGrid(  # A different grid with 15 combinations
+        Uniform(low=-1, high=1).take(5).with_name("param1"),
+        idx=[10, 20, 30]        
+    ).instantiate(model=FakeModel).select("model")
+assert len(g) == 55
+g.sample()
+```
+

hypergrid-0.0.1/src/hypergrid.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+src/hypergrid/__init__.py
+src/hypergrid/dimension.py
+src/hypergrid/dsl.py
+src/hypergrid/grid.py
+src/hypergrid/py.typed
+src/hypergrid/util.py
+src/hypergrid.egg-info/PKG-INFO
+src/hypergrid.egg-info/SOURCES.txt
+src/hypergrid.egg-info/dependency_links.txt
+src/hypergrid.egg-info/not-zip-safe
+src/hypergrid.egg-info/requires.txt
+src/hypergrid.egg-info/top_level.txt
+src/hypergrid/ext/__init__.py
+src/hypergrid/ext/sklearn.py
+src/hypergrid/gen/__init__.py
+src/hypergrid/gen/distribution.py
+src/hypergrid/gen/iterable.py

hypergrid-0.0.1/src/hypergrid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hypergrid-0.0.1/src/hypergrid.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

hypergrid-0.0.1/src/hypergrid.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[sklearn]
+scikit-learn<2

hypergrid-0.0.1/src/hypergrid.egg-info/top_level.txt

@@ -0,0 +1 @@
+hypergrid