Metadata-Version: 2.4
Name: structural-computing-bench
Version: 0.1.0a1
Summary: Calibrate the cost models used by structural-computing's router via wall-clock measurements on your machine.
Author: Edward Chalk (sapientronic.ai)
License: structural-computing-bench
        
        Copyright (c) 2026 Edward Chalk (sapientronic.ai)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), 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:
        
        1. The above copyright notice and this permission notice shall be included
           in all copies or substantial portions of the Software.
        
        2. Attribution. Any publication, presentation, derivative work, or product
           that uses or builds on this Software must include visible attribution to
           Edward Chalk and sapientronic.ai. The phrase "Built on work by Edward Chalk
           (sapientronic.ai)" or equivalent is acceptable.
        
        3. 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.
        
        This license is modeled on the MIT License with an explicit attribution
        clause (clause 2).
        
Project-URL: Homepage, https://github.com/pcoz/structural-computing-bench
Project-URL: Source code, https://github.com/pcoz/structural-computing-bench
Project-URL: Issue tracker, https://github.com/pcoz/structural-computing-bench/issues
Project-URL: Related framework, https://github.com/pcoz/structural-computing
Keywords: benchmarking,calibration,structural-computing,matchgate,holant,performance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: structural-computing>=0.6.0a1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# structural-computing-bench

Calibrate the cost models used by
[`structural-computing`](https://github.com/pcoz/structural-computing)'s
router by measuring actual wall-clock performance of its leaf
evaluators on your machine and fitting a power-law / exponential model
to the measurements.

The router decides which evaluator to dispatch to based on a *predicted*
runtime. The shipped predictions are hand-picked defaults; this repo
produces machine-specific replacements so the predictions match what
your hardware actually does.

## Why a separate repo

The benchmark machinery is heavier than the core library — timing
primitives, GC handling, curve fitting, problem generators, plus
optional plotting / reporting. Keeping it out of the
`structural-computing` PyPI package means:

  * Users installing the framework don't pull in unused benchmarking code.
  * The bench repo can grow heavier deps later (matplotlib, scipy,
    hypothesis) without bloating the core.
  * Calibration runs can have their own CI and don't interleave with
    framework PRs.

The output is a small `calibration_data.py` (or `.json`) file that the
framework's `structural_computing.calibration.apply_calibration()` loads
to update the router's coefficients at runtime.

## Quick start

```
pip install -e .
python scripts/run_calibration.py --out calibration_data/my_machine.py
```

then in your application:

```python
import importlib.util, importlib
spec = importlib.util.spec_from_file_location(
    "my_calibration", "calibration_data/my_machine.py")
mod = importlib.util.module_from_spec(spec); spec.loader.exec_module(mod)

from structural_computing.calibration import apply_calibration
apply_calibration(mod.CALIBRATED_COSTS)

# Now the router uses your machine's measured constants.
```

## What gets measured

| Leaf evaluator              | Problem generator       | Default sizes        |
|-----------------------------|-------------------------|----------------------|
| `_count_solutions_leaf`     | random GF(2) affine     | n ∈ [4, 8, 12, 16, 20, 24] |
| `_matching_count_leaf` (T2) | n-cycle (planar)        | n ∈ [4, 6, 8, 10, 12, 14, 16] |
| `_matching_count_leaf` (T4) | K_{n,n} bipartite       | n ∈ [2, 3, 4, 5]     |
| `_matchgate_rank_leaf`      | symmetric arity-n sig   | n ∈ [2, 4, 6, 8, 10, 12] |

For each, the harness:

1. Generates a deterministic problem of size `n`.
2. Runs the leaf evaluator `repeat=5` times.
3. Records the median elapsed seconds (median is robust to GC pauses).
4. Fits both `time ≈ a * n^b` (power law) and `time ≈ a * exp(b * n)`
   (exponential); reports whichever has lower log-residual as the
   preferred model.

## License

MIT-with-attribution to Edward Chalk / sapientronic.ai.
