pyvide 1.0.0__py3-none-any.whl

pyvide/__init__.py

@@ -0,0 +1,131 @@
+# pyVIDE -- pure-python re-implementation of the VIDE/ZOBOV void finder
+# Copyright (C) 2026 Nico Schuster
+#
+# An independent implementation of the algorithms of VIDE
+# (Copyright (C) 2010-2025 Guilhem Lavaux, 2011-2014 P. M. Sutter)
+# and ZOBOV (Mark Neyrinck), reproducing VIDE's output exactly.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; version 2 of the License.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, see <https://www.gnu.org/licenses/>.
+
+"""pyVIDE -- a pure-python re-implementation of the VIDE/ZOBOV void finder.
+
+pyVIDE finds voids in a distribution of tracers (or in a density field) with the
+watershed algorithm of ZOBOV (Neyrinck 2008) as it is implemented in VIDE
+(Sutter et al. 2015).
+
+**Fidelity policy.** pyVIDE reproduces VIDE; it does not improve on it.  On a
+VIDE-compatible path every quantity is computed with VIDE's own arithmetic --
+the same dtypes, the same operation order, the same accumulation order, down to
+float32 accumulations that a fresh implementation would naturally do in double.
+The point of pyVIDE is the *identical voids in a simpler environment*: pip
+install, numpy + scipy only, no compiler, no vendored qhull.  A number that
+differs from VIDE's is a bug, even when it is the more accurate number -- with
+one **stated** exception: where VIDE's number is an artefact of its own file
+format rather than of its arithmetic.  ``jozov2`` writes ``coreDens``,
+``zoneVol`` and ``voidVol`` through ``%e``, ``densCon`` through ``%f`` and
+``prob`` through ``%6.2e``, and ``pruneVoids`` reads them back into C
+``float``s, so every VIDE catalog carries the *printed* value.  pyVIDE stores
+those five untruncated, because discarding digits in a file it writes itself
+buys nothing; the truncation IS applied wherever it feeds a computation, most
+importantly ``voidVol -> radius``.  See ``docs/CATALOG_COLUMNS.md`` for the
+list and for how to compare the five against a VIDE catalog.  The VIDE source
+being reproduced is :data:`VIDE_REFERENCE`.
+
+On top of that it adds tracer weights, non-cubic boxes, per-axis periodicity, a
+direct density-field mode, a threshold-free merge-event log, the void tree's
+child lists, a catalog-only output mode for large parameter sweeps and
+array-or-path inputs, and it exposes parameters VIDE could not (``minRadius``,
+``maxCentralDen``).  None of those
+change the arithmetic: switch the new features off and set the parameters to
+VIDE's values, and the catalog is VIDE's catalog.  See ``README.md`` for the two
+dedicated sections "Additions in pyVIDE" and "What pyVIDE changes, and why",
+and ``docs/FIDELITY.md`` for the binding policy and what has been verified
+against what.
+
+Notes
+-----
+Only the symbols listed in ``__all__`` are part of the public API.
+"""
+
+from .errors import (
+    CatalogFormatError,
+    DuplicateTracersError,
+    InputError,
+    PyVideError,
+    TessellationError,
+)
+
+__version__ = "1.0.0"
+
+#: Integer stamped into every pyVIDE output file (npz/hdf5) and echoed in
+#: ``_info.txt``.  Loaders check it and refuse layouts they do not understand.
+FORMAT_VERSION = 1
+
+#: The VIDE source pyVIDE reproduces, bit for bit, on its VIDE-compatible paths.
+#:
+#: pyVIDE implements *one* behaviour -- this one -- and has no per-version
+#: compatibility switches.  Older VIDE builds differ here and there (for
+#: instance the sub-box centre line of ``zobov/voz1b1.c``, which older builds
+#: wrote as ``c[d] = ((float)b[d])*width``).  Those differences do not change
+#: the voids of a fully periodic box, and where they do change something the
+#: current source is the correct one, so pyVIDE follows the current source.
+#: Echoed into every run's ``_info.txt`` so a catalog always records which VIDE
+#: it corresponds to.
+VIDE_REFERENCE = {
+    "repository": "https://bitbucket.org/cosmicvoids/vide_public.git",
+    "branch": "master",
+    "commit": "8329b2c9ed6bd45218260df0488ba4c7020d2622",
+    "packageVersion": "2.0",
+    "retrieved": "2026-08-16",
+}
+
+# Imported last: ``api`` and ``io`` read ``__version__`` and ``FORMAT_VERSION``
+# from this module at import time, so they have to exist before the imports run.
+from .api import OUTPUT_SETS, identify_voids, run_summary  # noqa: E402
+from .io import (  # noqa: E402
+    VoidCatalog,
+    filter_catalog,
+    load_catalog,
+    members,
+)
+from .explain import explain  # noqa: E402
+# ‼ NOT added to __all__ below: see the note in explain.py.  Importing it
+# here makes pyvide.help(...) work; listing it would let
+# `from pyvide import *` shadow the builtin help.
+from .explain import help  # noqa: E402,A001
+from .fields import identify_voids_from_field  # noqa: E402
+from .rebuild import rebuild_catalog, rerun_watershed  # noqa: E402
+from .tree import build_tree  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "FORMAT_VERSION",
+    "VIDE_REFERENCE",
+    "identify_voids",
+    "identify_voids_from_field",
+    "OUTPUT_SETS",
+    "run_summary",
+    "VoidCatalog",
+    "load_catalog",
+    "members",
+    "filter_catalog",
+    "rebuild_catalog",
+    "rerun_watershed",
+    "build_tree",
+    "explain",
+    "PyVideError",
+    "InputError",
+    "DuplicateTracersError",
+    "TessellationError",
+    "CatalogFormatError",
+]