chisao 0.1.0__tar.gz

chisao-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

chisao-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (CPU / NumPy backend)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check src tests
+          black --check src tests
+
+      - name: Test
+        run: pytest -q

chisao-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# CuPy / build artifacts
+*.so

chisao-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to ChiSao are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is
+[SemVer](https://semver.org/).
+
+## [0.1.0] — unreleased
+
+### Added
+- First standalone release. Extracted from the SunBURST package
+  (`sunburst.utils.chisao` + `sunburst.utils.single_whip`) into an independent
+  `chisao` package and repository.
+- `chisao.seeding`: decoupled population seeders.
+  - `carry_tiger_seed` / `carry_tiger_rays` — structured ray-based seeding
+    (vertex-to-vertex, vertex-to-edge, wall-to-wall, QR-orthonormal sunburst),
+    lifted from `CarryTigerToMountain` without the evidence machinery.
+  - `random_seed` — uniform baseline seeder.
+- `optimize(func, bounds, seeder=...)` — high-level wrapper that seeds a
+  population and runs `sticky_hands`, mirroring the paper's two-seeder comparison.
+- src-layout packaging, MIT license, pytest suite (CPU), GitHub Actions CI.
+
+### Notes
+- Core optimizer (`sticky_hands`) carries internal version `3.2.0`, unchanged
+  from the SunBURST source.

chisao-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ira Wolfson
+
+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.

chisao-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: chisao
+Version: 0.1.0
+Summary: GPU-native parallel optimizer for multimodal black-box functions via convergence-anticonvergence oscillation
+Project-URL: Homepage, https://github.com/beastraban/chisao
+Project-URL: Repository, https://github.com/beastraban/chisao
+Project-URL: Issues, https://github.com/beastraban/chisao/issues
+Author-email: Ira Wolfson <irawolfsonprof@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: black-box-optimization,global-optimization,gpu,mode-finding,multimodal-optimization,optimization,population-methods
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20
+Requires-Dist: scipy>=1.7
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: cupy>=11.0; extra == 'gpu'
+Provides-Extra: profile
+Requires-Dist: psutil>=5.8; extra == 'profile'
+Description-Content-Type: text/markdown
+
+# chisao
+ChiSao optimizer

chisao-0.1.0/README.md

@@ -0,0 +1,2 @@
+# chisao
+ChiSao optimizer

chisao-0.1.0/benchmarks/README.md

@@ -0,0 +1,72 @@
+# ChiSao SFU Benchmark
+
+Reproduces the ChiSao mode-recovery results from the paper on the
+[Simon Fraser University optimization test suite](https://www.sfu.ca/~ssurjano/optimization.html):
+42 functions, both seeders (`random` and `carry_tiger`), across dimension.
+
+This harness covers the **ChiSao** columns of the paper (random vs carry\_tiger
+recovery rate and wall-clock). The CPU baselines (Differential Evolution,
+Basin-Hopping, CMA-ES) are reported separately and are not part of this script.
+
+## Run
+
+From the repository root, with the package installed (`pip install -e .`):
+
+```bash
+# quick smoke (seconds on CPU)
+python benchmarks/sfu_benchmark.py --funcs rastrigin sphere ackley --dims 2 --trials 2
+
+# a multimodal group across low dimensions
+python benchmarks/sfu_benchmark.py --group multimodal --dims 2 4 8 --trials 10
+
+# the full suite, paper dimensions, JSON output
+python benchmarks/sfu_benchmark.py --dims 2 4 8 16 32 64 --trials 10 --out sfu_results.json
+```
+
+CLI options:
+
+| Flag           | Meaning                                                        |
+| -------------- | ------------------------------------------------------------- |
+| `--funcs`      | Specific functions (names from the registry).                 |
+| `--group`      | One of `multimodal`, `multimodal_2d`, `bowl`, `valley`, ...   |
+| `--dims`       | Dimensions to test (default `2 4 8`).                         |
+| `--trials`     | Independent trials per function/dim (default `5`).            |
+| `--out`        | Write full results to a JSON file.                            |
+| `--source-dir` | Point at a working tree instead of the installed package.     |
+
+By default the harness does `import chisao` (the installed package). GPU is used
+automatically when CuPy is present; otherwise it runs on NumPy (the high
+dimensions are slow on CPU — use a GPU for `d >= 16`).
+
+## Paper run settings
+
+Each trial seeds a population and runs `chisao.sticky_hands` with the settings
+below (see `run_one` in `sfu_benchmark.py`). These are the settings that
+reproduce the paper — in particular, the `random` seeder only matches the
+paper's numbers with `reseed_strategy='sunburst'` and `cannon_through_sky=True`:
+
+```python
+N = 50 * (10 + ceil(log2(max(2, D))))      # population size
+params = dict(
+    method='lbfgs',
+    n_converge=10,
+    n_anticonverge=5,
+    n_oscillations=3,
+    stick_tolerance=1e-3,
+    reseed_strategy='sunburst',            # Repulse Monkey
+    cannon_through_sky=True,
+    estimate_widths=False,
+)
+```
+
+The two seeders (`seed_random`, `seed_carry_tiger`) are defined in the script.
+`seed_carry_tiger` is the same 4-component ray recipe exposed by the package as
+`chisao.carry_tiger_seed` (vertex-to-vertex, vertex-to-edge, wall-to-wall, and a
+QR-orthonormal sunburst from the domain center), with
+`n_rays = 10 + log2(d)` and 50 samples per ray.
+
+## Success criterion
+
+A trial succeeds if a recovered peak lies within the function's L∞ tolerance of
+a global optimum (`tol` in `FUNC_REGISTRY`). Functions with multiple equivalent
+optima (`multi_opt=True`) are matched against the nearest of their global optima.