microecs 0.4.1__tar.gz → 0.4.2__tar.gz

{microecs-0.4.1 → microecs-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.4.1
+Version: 0.4.2
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -76,7 +76,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -124,7 +124,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
@@ -133,7 +133,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
 2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
@@ -152,7 +152,7 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
@@ -169,7 +169,7 @@ Edge cases worth knowing:
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:

{microecs-0.4.1 → microecs-0.4.2}/README.md

@@ -64,7 +64,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -112,7 +112,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
@@ -121,7 +121,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
 2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
@@ -140,7 +140,7 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
@@ -157,7 +157,7 @@ Edge cases worth knowing:
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:

{microecs-0.4.1 → microecs-0.4.2}/microecs/__init__.py

@@ -1,10 +1,10 @@
 """init file"""
 
 from .world import World
-from .query_result import QueryResult
+from .query_result import QueryResult, Field
 from .pool import Pool
 from .entity import Entity
 from .component import Component
 from .utils import EntityId
 
-__all__ = ["World", "QueryResult", "Pool", "Component", "Entity", "EntityId"]
+__all__ = ["World", "QueryResult", "Field", "Pool", "Component", "Entity", "EntityId"]

{microecs-0.4.1 → microecs-0.4.2}/microecs/query_result.py

@@ -8,7 +8,8 @@ from .pool import Pool
 # Note: if QueryResult gets new fields, add them here! Otherwise the user code may overwrite them e.g. qr._len=xxx
 QUERY_RESULT_INTERNAL_ATTRS = {"pool_list", "entity_ids", "fields", "_field_shapes", "_field_dtypes", "_data", "_len"}
 
-class _Field(np.lib.mixins.NDArrayOperatorsMixin):
+class Field(np.lib.mixins.NDArrayOperatorsMixin):
+    """Field is a single field (column) from a QueryResult object obtained from world.query(...)"""
     def __init__(self, parts: list[np.ndarray]):
         self.parts = parts
         self._lens = [len(p) for p in self.parts]
@@ -22,7 +23,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
         return np.concatenate(self.parts) if len(self.parts) != 1 else self.parts[0]
 
     def _chunk(self, x: T, i: int) -> T:
-        if isinstance(x, _Field):
+        if isinstance(x, Field):
             return x.parts[i]
         if isinstance(x, np.ndarray) and x.ndim == len(self.shape) and x.shape[0] == self.len:
             return x[self._bounds[i]:self._bounds[i + 1]]
@@ -30,16 +31,16 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
 
     def _apply_fn_on_parts(self, fn: Callable, op_args: list, **kwargs):
         # op args can be 1 element (-qr.velocity), 2 elements (qr.position * 0.1), 3 elements (np.where(a, b, c)), etc.
-        # all of them must be chunked based on how many we have in this _Field so each subpart is called independently.
+        # all of them must be chunked based on how many we have in this Field so each subpart is called independently.
         results = []
         for i, part in enumerate(self.parts):
             pool_args = [self._chunk(x, i) for x in op_args]
-            part_result: _Field = fn(*pool_args, **kwargs)
+            part_result: Field = fn(*pool_args, **kwargs)
             # we expect f(arr(N, ...)) -> arr(N, ...) where N = number of items in the pool
             # for e.g. np.linalg.norm(velocity, axis=1) should do (N, 2) -> (N, 1) so the first axis is preserved
             assert len(part_result) == part.shape[0], f"Result: {part_result.shape} vs {part.shape}"
             results.append(part_result)
-        return _Field(results)
+        return Field(results)
 
     def __array_ufunc__(self, ufunc, method, *inputs, out=None, **kwargs):
         """wrapper for elementwise (python) primitives, e.g. qr.position[:] += 1"""
@@ -48,7 +49,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
         if out is None:
             return self._apply_fn_on_parts(ufunc, inputs, **kwargs)
 
-        assert len(out) == 1 and isinstance(out[0], _Field), out
+        assert len(out) == 1 and isinstance(out[0], Field), out
         for i in range(len(self.parts)):
             pool_args = [self._chunk(x, i) for x in inputs]
             ufunc(*pool_args, out=out[0].parts[i], **kwargs)
@@ -64,7 +65,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
             not (isinstance(key, tuple) and key and key[0] == slice(None))):
             raise TypeError("entity-axis assignment crosses pools; use [:] or [:, k] or [i][...]")
 
-        if isinstance(value, _Field):
+        if isinstance(value, Field):
             for i, part in enumerate(self.parts):
                 part[key] = value.parts[i]
             return
@@ -78,10 +79,10 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
 
     def __getitem__(self, key):
         if key is Ellipsis or (isinstance(key, tuple) and key and (key[0] is Ellipsis or key[0] == slice(None))):
-            return _Field([part[key] for part in self.parts])
+            return Field([part[key] for part in self.parts])
 
         raise TypeError(("Only batch updates are supported, e.g. `qr.attr[:]=xxx` or `qr.attr[:, k]=xxx`. "
-                         "Use .numpy() for a proper array. For entity-level ops use `world.get_entity(eid).attr=xxx"))
+                         "Use .numpy() for a proper array. For entity-level ops use `world.get_entity(eid).attr=xxx`"))
 
     def __iter__(self):
         for part in self.parts:
@@ -108,7 +109,7 @@ class QueryResult:
     def __getattr__(self, name):
         if (data := self.__dict__.get("_data")) is not None and name in data:
             # the 'or' part is in case no pools match the query and we want qr.position[:] += 1 still to work (noop)
-            return _Field(data[name] or [np.empty((0, *self._field_shapes[name]), self._field_dtypes[name])])
+            return Field(data[name] or [np.empty((0, *self._field_shapes[name]), self._field_dtypes[name])])
         raise AttributeError(f"'{name}' not part of {self.fields}")
 
     def __setattr__(self, name, value):

{microecs-0.4.1 → microecs-0.4.2}/microecs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.4.1
+Version: 0.4.2
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -76,7 +76,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -124,7 +124,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
@@ -133,7 +133,7 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
 2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
@@ -152,7 +152,7 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
@@ -169,7 +169,7 @@ Edge cases worth knowing:
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:

{microecs-0.4.1 → microecs-0.4.2}/setup.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from setuptools import setup, find_packages
 
 NAME = "microecs"
-VERSION = "0.4.1"
+VERSION = "0.4.2"
 DESCRIPTION = "MicroECS: Minimal Entity Component System (ECS) in python and numpy"
 URL = "https://gitlab.com/meehai/microecs"