packingcubes 0.2.1__tar.gz → 0.2.3__tar.gz

{packingcubes-0.2.1 → packingcubes-0.2.3}/CHANGELOG.md

@@ -1,4 +1,113 @@
-## [unreleased]
+## [0.2.3] - 2026-03-25
+
+### 🚀 Features
+
+- Adding loading factor ([29f05af](https://github.com/astrosocket/packingcubes/commit/29f05afd3b16cd9591a0f16d9b147e5b214be124))
+- Allow multiple dfs/sbs and save to file ([c5f0e54](https://github.com/astrosocket/packingcubes/commit/c5f0e5406bccdd18adf4af4be68594ad94369dbd))
+- Allow dataset as argument to KDTree ([944540d](https://github.com/astrosocket/packingcubes/commit/944540d2c61ad0242dd17325aed32a98423db9fa))
+- Add auto thread based default cubes_per_side ([c24f39b](https://github.com/astrosocket/packingcubes/commit/c24f39b016fed12a73b270ff8049ef1793263d11))
+- Expose save_dataset flag, make output optional ([bbbd234](https://github.com/astrosocket/packingcubes/commit/bbbd2346fcd0cc4584842fe3c81dd04df0d94f7b))
+
+### 🐛 Bug Fixes
+
+- Assuming search_ball_sizes even when none ([1e6a018](https://github.com/astrosocket/packingcubes/commit/1e6a01808acda955b7b7a0fe8769ed562ac22b60))
+
+### 🚜 Refactor
+
+- Remove empty sidecar file header creation ([668a914](https://github.com/astrosocket/packingcubes/commit/668a914980a6fb1b0a7f0ccef5af5c903c3f379f))
+
+### ⚡ Performance
+
+- Move cubes reordering into parallel loop ([857295b](https://github.com/astrosocket/packingcubes/commit/857295b25257727f9a199ce42eae9c06dc9a8447))
+- Add unsafe BoundingSphere creation ([af01b30](https://github.com/astrosocket/packingcubes/commit/af01b303608eb3c2d5d5afa55a8dc114103139df))
+- Combine search methods and use single shape creation ([75985e9](https://github.com/astrosocket/packingcubes/commit/75985e99e4d270f69e4dae052360e4d1812f7bb6))
+- Switch to check_overlap ([68edfd6](https://github.com/astrosocket/packingcubes/commit/68edfd6845249aa80fc79965ad4f81c4a20f6dfb))
+- Inline _cubes_position, remove extra calculation ([83b51e7](https://github.com/astrosocket/packingcubes/commit/83b51e7a50ca027d4360d4995938965bd33b668a))
+- Use explicit bounds in box references ([cac5169](https://github.com/astrosocket/packingcubes/commit/cac51691fdf7f61e360e665c59eb15e11d13f8e5))
+
+### 🧪 Testing
+
+- Number of bugfixes ([fcd5af2](https://github.com/astrosocket/packingcubes/commit/fcd5af21b718367f6e5dbc6cc1fa53f1eebe7e6b))
+- Refactor timing_test to use fewer globals, general improvements ([b1e66b8](https://github.com/astrosocket/packingcubes/commit/b1e66b888644bad32c8de10390876eecca20a12e))
+- Handle error in timing gracefully ([c4df754](https://github.com/astrosocket/packingcubes/commit/c4df7544d08649f49e6e7d5499ab9f2341e4124c))
+- Switch to faster query_ball_point options ([340d8a3](https://github.com/astrosocket/packingcubes/commit/340d8a3d63c907924638662ef8104a4f8c779cbb))
+- Display number of threads if cubes testing ([d55daa8](https://github.com/astrosocket/packingcubes/commit/d55daa8d61462674ea6876ac27828cc013662dc8))
+## [0.2.2.2] - 2026-03-20
+
+### ⚙️ Miscellaneous Tasks
+
+- Add twine to build group, specify markdown ([#13](https://github.com/astrosocket/packingcubes/issues/13)) ([ed349a5](https://github.com/astrosocket/packingcubes/commit/ed349a51c4fc36099aa09c33d856ed7a63d1ce9f))
+## [0.2.2.1] - 2026-03-20
+
+### ⚙️ Miscellaneous Tasks
+
+- Add twine to build group, specify markdown ([a33903e](https://github.com/astrosocket/packingcubes/commit/a33903e9f4d228a35046cc7bcef8012aa8f52d2f))
+## [0.2.2] - 2026-03-20
+
+### 🚀 Features
+
+- Flesh out the readme ([e757b45](https://github.com/astrosocket/packingcubes/commit/e757b4586b2c79fe11e2152f70019a567f367d01))
+- Support passing a regular array to Cubes constructor ([c59097b](https://github.com/astrosocket/packingcubes/commit/c59097b8eb844dda5be5510125b7b4c487e7c54c))
+- Allow loading cubes data from file ([d45b5d7](https://github.com/astrosocket/packingcubes/commit/d45b5d70ee30975a870f75ee6ee348e745fafa37))
+- Allow optional particle type when getting indices ([17084be](https://github.com/astrosocket/packingcubes/commit/17084be15b8d69830f378ce69f4c01e2db05037f))
+- Allow specifying a string or Path when saving cubes ([1674664](https://github.com/astrosocket/packingcubes/commit/1674664e8e41dfe4739b3af796160a8018767ef3))
+- Add CLI option to specify where cubes should be saved ([823d4fe](https://github.com/astrosocket/packingcubes/commit/823d4fe6216e833a5c9b2b4c56aa1bd539302b5f))
+- Support more general BoxLike for cube_box argument ([a4b8545](https://github.com/astrosocket/packingcubes/commit/a4b8545f248dbe67039dda145697fedb6291a9b6))
+- Add flag to save datasets in make_cubes ([5e16e98](https://github.com/astrosocket/packingcubes/commit/5e16e987e47abca74e6a214022920372d14b124b))
+- Add method to save out sorted positions and indices ([cdc9be2](https://github.com/astrosocket/packingcubes/commit/cdc9be26c6fc7d2cb3a6fa8e72cee5968a8939da))
+- Allow 1 & 2D data for KDTrees ([01f2828](https://github.com/astrosocket/packingcubes/commit/01f2828a391baf27f212be04c23ff38fe9200ae3))
+- Expose the InMemory class ([f870ccd](https://github.com/astrosocket/packingcubes/commit/f870ccd970323969efefe3b02c10a9c3ad9b0ab0))
+
+### 🐛 Bug Fixes
+
+- Remove old view of data when loading new positions ([b8be47c](https://github.com/astrosocket/packingcubes/commit/b8be47cbea55dd0bbeba98eb4478623b62b3ce52))
+
+### 💼 Other
+
+- Fix argument typing ([c913ffb](https://github.com/astrosocket/packingcubes/commit/c913ffb844ec98bcdc4ceb58737908a0b68a6377))
+- Fix typing complaints from mypy ([4736c03](https://github.com/astrosocket/packingcubes/commit/4736c03b370bc58d29ddf3b1ffa904d285d417ab))
+
+### 🚜 Refactor
+
+- Remove yt timing ([243d15f](https://github.com/astrosocket/packingcubes/commit/243d15f4d5c3ddb6f3890fbe210d5f393ed6326c))
+- Remove more Dataset-Cubes interdependence ([7778fb7](https://github.com/astrosocket/packingcubes/commit/7778fb770653868a747285f4f479d4aec7e80f05))
+- Remove the cache file for HDF5Datasets ([d33987b](https://github.com/astrosocket/packingcubes/commit/d33987bebc74372def420a116025844aa2e6d3ab))
+- Remove some missed debugging print statements ([24d5ebd](https://github.com/astrosocket/packingcubes/commit/24d5ebd6a51ee39743182f1766beb6eaa25b1b3b))
+
+### 📚 Documentation
+
+- Add docstring to _get_particle_indices_in_shape ([60b9fac](https://github.com/astrosocket/packingcubes/commit/60b9facd1b904817a8420283070dc8debf0b4db8))
+- Add missing docstring to make_cubes ([59b4be6](https://github.com/astrosocket/packingcubes/commit/59b4be626fe514973d5806341575435216f4aed1))
+- Add _data_container to attribute list ([c087267](https://github.com/astrosocket/packingcubes/commit/c0872671595523642590da3a860b891650b4bcf7))
+
+### ⚡ Performance
+
+- Skip loading particle data if not actually changing particle_type ([e4476d3](https://github.com/astrosocket/packingcubes/commit/e4476d376f3dde3eb4d6bec1f28987d8e1bff79b))
+
+### 🧪 Testing
+
+- Allow 1 and 2D arrays for KDTree ([02c53d8](https://github.com/astrosocket/packingcubes/commit/02c53d88d3a3a720de50999430fdaacf2a8f557e))
+## [0.2.1] - 2026-03-19
+
+### 🐛 Bug Fixes
+
+- Fix typo ([547cd0a](https://github.com/astrosocket/packingcubes/commit/547cd0ad8fbe1390787ada6a2844d530bf3a6051))
+
+### ⚙️ Miscellaneous Tasks
+
+- Readd pypi publishing ([1d374ab](https://github.com/astrosocket/packingcubes/commit/1d374ab11ea3aad609c8002e4ec54a02b6f9885c))
+- Move scm variable ([9cd97e5](https://github.com/astrosocket/packingcubes/commit/9cd97e5d0eef020d4dbf67b2f4b496bca23f8b35))
+- Attempt testpypi publishing ([47e169c](https://github.com/astrosocket/packingcubes/commit/47e169c7ecbb85e4b618f6bcfd11963c0a215c34))
+- Set fetch-depth, remove local version component ([b071880](https://github.com/astrosocket/packingcubes/commit/b071880f730e591f6be6cc48ac864ae09e00e3bb))
+- Fix version export, add setuptools_scm ([fb4e24b](https://github.com/astrosocket/packingcubes/commit/fb4e24b156ed5e2b1db291819877c77fc6d9b7e9))
+- Print version and turn of upload temporarily ([2993a11](https://github.com/astrosocket/packingcubes/commit/2993a11ebcd944df6b10b58ba48ae46d612309bc))
+- Forgot to add pixi run ([ccf9e5d](https://github.com/astrosocket/packingcubes/commit/ccf9e5d7043885cf106df18e9c2b47a01edd9d84))
+- Switch to pixi install in pypi pipeline ([8a9e35f](https://github.com/astrosocket/packingcubes/commit/8a9e35f541a41e57ec13eedc67fb864071fe1d51))
+- Switch to runtime version checking ([3130d73](https://github.com/astrosocket/packingcubes/commit/3130d7320e808a91b409eebdb2a86ccb992c96d7))
+- Add install step ([a458f0f](https://github.com/astrosocket/packingcubes/commit/a458f0fa0433d5790f406ca29202d867f030e5a2))
+- Update workflow to remove the frozen status and update lockfile ([9a21b96](https://github.com/astrosocket/packingcubes/commit/9a21b966afa59327b9e7ba5dd14264996f449cda))
+- Add verbosity to publishing to help resolve error ([062eb10](https://github.com/astrosocket/packingcubes/commit/062eb10805a33bca1de9f9c5e9983cdd6903619c))
+## [0.2.0] - 2026-03-18
 
 ### 🚀 Features
 
@@ -44,6 +153,9 @@
 
 ### 🐛 Bug Fixes
 
+- Missing character in repository-url ([2e13f53](https://github.com/astrosocket/packingcubes/commit/2e13f53e9b2808e76dfaa4f194d1924a6007c8df))
+- Invert typo in publishing workflow ([35d2815](https://github.com/astrosocket/packingcubes/commit/35d281532a14799e81ef1c6b6061a66d2c9bac81))
+- Fix typo in publishing workflow ([8a99a56](https://github.com/astrosocket/packingcubes/commit/8a99a56c8639e214e2f9eb1683f51843293d63ad))
 - Jitter=0 not being set correctly ([63fce23](https://github.com/astrosocket/packingcubes/commit/63fce233a11b4f58203c7b20bccf25ddad214f63))
 - Used < instead of <= ([4c44186](https://github.com/astrosocket/packingcubes/commit/4c441863d32ff5d3ac05ca1ddfc7569bb700ab9e))
 - Move per node behavior to subfunction ([1da6e20](https://github.com/astrosocket/packingcubes/commit/1da6e20a3d766a3beedf38862ac9e5b2c30778b6))
@@ -224,6 +336,15 @@
 
 ### ⚙️ Miscellaneous Tasks
 
+- Add pypi publishing workflow and fix testpypi workflow ([4410603](https://github.com/astrosocket/packingcubes/commit/4410603ded84e0937f4673ba6b013001a3481e65))
+- Set pydocstyle and fix license file name ([76da9fb](https://github.com/astrosocket/packingcubes/commit/76da9fbb3dfefa1231ab2b4ed54d7383294d053e))
+- Fix extra space in dependabot timing ([#7](https://github.com/astrosocket/packingcubes/issues/7)) ([b2ac0f4](https://github.com/astrosocket/packingcubes/commit/b2ac0f4dbb7cf1bbc312e577f3786caaf6994942))
+- Fix extra space in dependabot timing ([9102209](https://github.com/astrosocket/packingcubes/commit/9102209cd90bf7d9e8074427c6830fb8ec37d530))
+- Switch to frozen install in CI ([1a974f0](https://github.com/astrosocket/packingcubes/commit/1a974f0e59585f506223875cef3bc2672eea7cb8))
+- Update lockfile and jupyter environment ([933886d](https://github.com/astrosocket/packingcubes/commit/933886d166ab12224d3b495f664169549964a837))
+- Update checkout version in workflows ([e9706ac](https://github.com/astrosocket/packingcubes/commit/e9706acdc86c5cea6ef262acc8703df1a69ff2a4))
+- Update pixi version in CI ([8c5ffcf](https://github.com/astrosocket/packingcubes/commit/8c5ffcf4a4b7880b999d7b83bd58a4015f5d5d1d))
+- Add project metadata and pypi release workflow ([ebb04b6](https://github.com/astrosocket/packingcubes/commit/ebb04b61edade29ef545b986b18be1197270e9fc))
 - Add pykdtree for future benchmarking ([6787bdd](https://github.com/astrosocket/packingcubes/commit/6787bdd622c9e236b949645ab9dbbe0b75d2c9e5))
 - Updating lock file ([ceab923](https://github.com/astrosocket/packingcubes/commit/ceab9234bbeb8485af1190508242b30b3b587b79))
 - Remove old CurrentNode comment ([8c3562b](https://github.com/astrosocket/packingcubes/commit/8c3562b0cabf73245866ad6625b4b263d60e6243))
@@ -316,4 +437,5 @@
 
 - Add basic .gitlint file ([5c3a2e2](https://github.com/astrosocket/packingcubes/commit/5c3a2e261d21f06afea804f4a81eabd72b8cfad4))
 - Ignore profiler output ([7e302b3](https://github.com/astrosocket/packingcubes/commit/7e302b39745f7ca79257b20f2eb7e44b1cd00b99))
+## [0.0.0] - 2025-10-29
 <!-- generated by git-cliff -->

packingcubes-0.2.3/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: packingcubes
+Version: 0.2.3
+Summary: PackingCubes octree implementation for astro data
+Author: Michael Ryan
+Author-email: Josh Borrow <josh@joshborrow.com>
+License-Expression: MIT
+Project-URL: home, https://github.com/astrosocket/packingcubes
+Project-URL: source, https://github.com/astrosocket/packingcubes
+Project-URL: issues, https://github.com/astrosocket/packingcubes/issues/new
+Keywords: astronomy,astrophysics
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: h5py
+Requires-Dist: numba
+Requires-Dist: xxhash<4,>=3.6.0
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == "viz"
+Requires-Dist: pygfx; extra == "viz"
+Requires-Dist: rendercanvas; extra == "viz"
+Requires-Dist: pyside6; extra == "viz"
+Provides-Extra: jupyter
+Requires-Dist: jupyter-rfb; extra == "jupyter"
+Provides-Extra: benchmark
+Requires-Dist: scipy; extra == "benchmark"
+Requires-Dist: unyt; extra == "benchmark"
+Provides-Extra: all
+Requires-Dist: packingcubes[viz]; extra == "all"
+Requires-Dist: packingcubes[jupyter]; extra == "all"
+Requires-Dist: packingcubes[benchmark]; extra == "all"
+Dynamic: license-file
+
+# packingcubes
+
+[![PyPI](https://img.shields.io/pypi/v/packingcubes)](https://pypi.org/project/packingcubes)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/packingcubes)](https://pypi.org/project/packingcubes/)
+
+<!--- Tests and style --->
+[![Tested with Hypothesis](https://img.shields.io/badge/hypothesis-tested-brightgreen.svg)](https://hypothesis.readthedocs.io/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/charliermarsh/ruff)
+
+
+Compact octree implementation used for Socket
+
+`packingcubes` aims to provide a fast, minimal-memory-usage octree
+implementation, specialized for use in astronomical/astrophysical contexts.
+It's written in pure python, with [Numba](https://numba.pydata.org/)-based
+acceleration of the critical code paths.
+
+## Requirements
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/packingcubes)](https://pypi.org/project/packingcubes/) 
+is required. Python versions outside this range may work, but their usage is
+not supported, and at least some features are >Python 3.12. 
+
+### Python packages
+* `numpy` - required for core routines
+* `numba` - required for core routines (and most of the speed)
+* `h5py` - required for reading snapshot data and saving `Cubes` and
+   `PackedTree`s
+* `xxhash` - required for core routines (packed metadata format)
+
+### Optional packages
+Visualization (the `viz` group):
+* `matplotlib` - to use basic octree visualization and plotting (see
+   Basic_Usage in the Examples)
+* `pygfx` - to do interactive octree visualization (see Example_PackedTree in
+   the Examples)
+* `rendercanvas` - to do interactive octree visualization
+* `pyside6` - performant interactive octree visualization (uses Qt, other
+   options include `wgpu-py`, `pyodide`. See the
+  [rendercanvas backends](https://rendercanvas.readthedocs.io/stable/backends.html)
+   documentation for more details
+
+Jupyter (the `jupyter` group):
+* `jupyter-rfb` - for interactive octree visualization in a notebook (see the Visualization section, above)
+
+Benchmark (the `benchmark` group):
+* `scipy` - we benchmark against `scipy`'s `KDTree`
+* `unyt` - for unit-aware timing purposes
+
+The `all` group combines all of the above.
+
+## Usage
+### Installation
+We're on [PyPI](https://pypi.org/project/packingcubes), so installation is as
+simple as
+
+```sh
+pip install packingcubes
+```
+or
+```sh
+uv pip install packingcubes
+```
+or
+```sh
+pixi add packingcubes --pypi
+```
+
+Additional package requirements can be installed via optional dependencies (see
+the requirements section for the lists). Examples:
+```sh
+pip install "packingcubes[viz, jupyter]"
+```
+or 
+```sh
+pixi add packingcubes[all] --pypi
+```
+
+
+### Construction
+#### From a snapshot on disk
+From the command line:
+
+```sh
+packcubes SNAPSHOT OUTPUT
+```
+will generate a `Cubes` data structure and store it in the `OUTPUT` hdf5 file
+along with the sorted positions and shuffle-list.
+
+Alternatively:
+```python
+import packingcubes
+
+cubes = packingcubes.Cubes("path/to/snapshot.hdf5")
+
+cubes.save("path/to/output.hdf5")
+# sorted positions/indices are stored in .snapshot_sorted.hdf5 by default
+
+# to save elsewhere, use
+dataset = packingcubes.HDF5Dataset(
+    "path/to/snapshot.hdf5", sorted_filepath="path/to/output.hdf5"
+)
+cubes = packingcubes.Cubes(dataset)
+
+# if you already have positions_data as an Nx3 matrix, you can use
+cubes = packingcubes.Cubes(positions_data)
+# Note: this data will be sorted in place! you may want to make a copy
+
+# You can also do the following for easy saving. 
+# The data will still not be copied (by default)
+dataset = packingcubes.InMemory(positions=positions_data)
+cubes = packingcubes.Cubes(dataset)
+dataset.save("path/to/output.hdf5")
+```
+
+Several configuration options are available, see `packcubes --help` or `help(packingcubes.Cubes)` for more information.
+
+You can load the saved Cubes with 
+
+```python
+import packingcubes
+
+cubes = packingcubes.Cubes("path/to/saved_cubes.hdf5")
+```
+
+### Searching
+Currently, `packingcubes` provides two public methods for searching your
+dataset:
+
+```python
+# particle_types is a string or Sequence[str] that maps to a particle type in
+#   the snapshot
+# center is anything that can be converted by numpy's array method to an (3,)
+#   array, and is the sphere's center
+# radius is a float
+indices_dict = cubes.get_indices_in_sphere(particle_types, center, radius)
+```
+
+```python
+# particle_types is a string or Sequence[str] that maps to a particle type in
+#   the snapshot
+# box is anything that can be converted by numpy's array method to an (6,)
+#   float array where the first 3 elements are the front-left-bottom corner,
+#   and the second 3 elements are the box width, depth, and height 
+#   (aka [x, y, z, dx, dy, dz])
+indices_dict = cubes.get_indices_in_box(particle_types, box)
+```
+
+For both methods, the returned object is a dictionary of `particle_type` keys
+mapped to lists of (start, stop) tuples, representing the start and stop
+indices of contiguous tuples in the **sorted** dataset. 
+
+So the search pipeline might go something like:
+
+```python
+# cubes are associated with HDF5Dataset dataset created from orig_dataset 
+# which is an h5py File object
+indices_dict = cubes.get_indices_in_sphere(
+    center, radius, particle_types=["PartType0", "Black_Holes"]
+)
+
+velocities_list = []
+with h5py.File(orig_dataset_file) as orig_dataset:
+    for start,stop in indices_dict["PartType0"]:
+        shuffle = dataset.index[start:stop]
+        # WARNING: the following could be very slow if shuffle gets
+        # large (>10000)
+        v = orig_dataset["PartType0/Velocity"][shuffle,:]
+        velocities_list.extend(v)
+
+velocities = np.fromiter(velocities_list)
+```
+
+**Warning**: this could become slow if the `shuffle` sections get big 
+(`len(shuffle)>1000`)! This is because HDF5 loading is inefficient in this
+manner (the `v =` line), not because of the search (the `indices_dict =`
+and `shuffle =` lines). 
+
+The sorting is already performed for the positions information (it was
+necessary to construct the tree), but `packingcubes` does not apply the sort to
+the other fields in the snapshot. 
+
+So if you only need positional information, 
+```python
+indices_dict = cubes.get_indices_in_sphere(center, radius)
+
+positions_list = []
+# We don't need to open the orig_dataset file
+dataset.particle_type = "PartType0"
+for start,stop in indices_dict["PartType0"]:
+    positions_list.extend(dataset.positions[start:stop])
+
+positions = np.fromiter(positions_list)
+```
+should be very fast.
+
+If you need a different field, (like the `velocities`, as above), we recommend
+preloading the entire velocities array, using the shuffle list to presort it,
+and then treating it analogously to the `dataset.positions` field or saving it
+back out: 
+```python
+indices_dict = cubes.get_indices_in_sphere(center, radius)
+indices = indices_dict["PartType0"]
+
+with h5py.File(orig_dataset_path) as orig_dataset:
+    loaded_velocities = orig_dataset["PartType0/velocity"]
+# Just to make sure we're looking at the correct particle type
+dataset.particle_type = "PartType0"
+loaded_velocities = loaded_velocities[dataset.index,:]
+
+# use directly
+velocities_list = []
+for start,stop in indices:
+    velocities_list.extend(loaded_velocities[start:stop])
+
+# or save it back out
+with h5py.File(sorted_velocity_path, "a") as outfile:
+    outfile["PartType0/velocity"] = loaded_velocities
+...
+velocities_list = []
+with h5py.File(sorted_velocity_path) as vel_dataset:
+    for start, stop in indices:
+        velocities_list.extend(
+            vel_dataset["PartType0/velocity"][start:stop, :]
+        )
+
+
+velocities = np.fromiter(velocities_list)
+```
+
+If this seems like a hassle, consider the [GUSTEAU](https://www.github.com/astrosocket/gusteau)
+project, which among many other improvements, will do all of this additional
+field sorting (and the original cubing) for you!
+
+
+### KDTree
+We have also reimplemented some of the API from the `KDTree` in `scipy.spatial`,
+notably the `query_ball_point` method (This is also what the benchmarks compare
+against). Example usage modified from the `scipy.spatial.KDTree` [documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.KDTree.query_ball_point.html):
+```python
+>>> import numpy as np
+>>> from packingcubes import KDTree # this is the only change you need to make
+>>> x, y = np.mgrid[0:5, 0:5]
+>>> points = np.c_[x.ravel(), y.ravel()]
+>>> tree = KDTree(points)
+>>> sorted(tree.query_ball_point([2, 0], 1))
+[5, 10, 11, 15]
+```
+
+#### Caveats:
+* The provided dataset may be sorted in-place. See the `KDTree` constructor's
+  `data` and `copy_data` arguments for more information on when that occurs. 
+* Only `query`, `query_ball_point`, and `query_ball_tree` are fully supported.
+  `query_pairs` and `count_neighbors` are a work in progress (`query_pairs` may
+  not provide completely correct output, `count_neighbors` does not yet have
+  the `KDTree` API portion implemented and may not be correct).
+  `sparse_distance_matrix` is not planned. Both `count_neighbors` and
+  `sparse_distance_matrix` will raise `NotImplementedErrors`.
+* Only `query_ball_point` has been benchmarked and is guaranteed to be
+  performant. We are currently working on `query`'s performance, but will not
+  plan on beating `scipy`.
+* A number of optional constructor and method arguments are not supported (for
+  example, setting the distance metric `p` to a number other than 2). Some of
+  these may be supported in the future (like `p=3`), others will not (like
+  `balanced_tree`). For the most part, we emit warnings if an argument or its
+  value does not make sense in the `packingcubes` context and try to only raise
+  errors if there is no possible analog and/or a significant change in behavior.
+* Only 1, 2, and 3D data is supported. PackedTrees specifically expect 3D data
+  (since it's an octree implementation), thus 1 and 2D data will be copied and
+  padded with 0s (e.g. `[[1, 2], [3, 4]]` will become `[[1, 2, 0], [3, 4, 0]]`
+  ). This should not signficantly impact memory usage (beyond the copy) and the
+  PackedTree should just function as a binary or quadtree.
+* For performance reasons, some of the `packingcube` default output formats may
+  not match the `scipy` output formats (`array`s instead of `list`s, for
+  example). For those methods where that's a possibility, additional arguments
+  can be provided which will enforce the the "proper" format (e.g. by setting
+  `return_lists=True`) at a small performance penalty.
+* Likewise for performance reasons, some of the the default `packingcube`
+  output indices will be in terms of the sorted dataset (remember, the dataset
+  will be sorted in-place unless specified otherwise). For those methods, you
+  may be able to specify `return_data_inds=False` to get indices into the
+  unsorted dataset. Alternatively, reference the `sort_index` property.
+
+## Development requirements
+### uv
+To get ready for development, create a virtual enviroment and install the
+package:
+```
+uv venv --python=3.12
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+pre-commit install
+```
+
+We use ruff for formatting. When you go to commit your code, it will
+automatically be formatted thanks to the pre-commit hook.
+
+Tests are performed using pytest.
+### pixi
+Using with pixi is pretty easy, simply
+```sh
+pixi shell
+```
+To look at visualizations, run tests, or develop, simply specify the
+corresponding environment
+```sh
+# visualizations
+pixi shell -e viz
+# testing (also includes viz)
+pixi shell -e test
+# developing (also includes viz & test)
+pixi shell -e dev
+pre-commit install
+```
+and e.g. to run tests, say
+```sh
+pixi run test
+```
+which runs `pytest  --cov=packingcubes` in the `dev` environment.