# aigverse.benchmarks

Standard benchmark suites for logic synthesis.

Fetches well-known benchmark circuits on demand and caches them locally, so a
script or an experiment can name a benchmark rather than shipping a downloader
and a copy of the data.

Nothing is downloaded at import time and no benchmark is bundled with
aigverse; the first call that needs a file fetches it. See the
[Benchmarks](../../../benchmarks.html.md) guide for a runnable example.

## Package Contents

### CACHE_ENV_VAR *= 'AIGVERSE_BENCHMARK_CACHE'*

### benchmark_cache() → [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path)

Resolves the directory downloaded benchmarks are cached in.

Resolution order: an explicit override set via [`set_benchmark_cache()`](#aigverse.benchmarks.set_benchmark_cache),
then the `AIGVERSE_BENCHMARK_CACHE` environment variable, then a per-user
cache directory appropriate to the platform.

* **Returns:**
  The cache directory. It is not created here.

### set_benchmark_cache(path: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [PathLike](https://docs.python.org/3/library/os.html#os.PathLike)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None)) → [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path) | [None](https://docs.python.org/3/builtins/constants.html#None)

Sets or clears the directory downloaded benchmarks are cached in.

Applies process-wide and is intended to be called once during setup; it is
not thread-safe.

* **Parameters:**
  **path** – The directory to use, or `None` to clear a previous override and
  fall back to the environment variable and the platform default.
* **Returns:**
  The resolved directory, or `None` if the override was cleared.

### DEFAULT_REVISION *= '82d8cc6910419298e713a46644ed59fd3df53038'*

### EPFL_ARITHMETIC *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

### EPFL_BENCHMARKS *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

### EPFL_RANDOM_CONTROL *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]*

### epfl(name: [str](https://docs.python.org/3/builtins/stdtypes.html#str), , revision: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = DEFAULT_REVISION, cache_dir: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [PathLike](https://docs.python.org/3/library/os.html#os.PathLike)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None) = None, timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 60.0) → [NamedAig](../networks/index.html.md#aigverse.networks.NamedAig)

Loads an EPFL benchmark as a network.

The result is a [`NamedAig`](../networks/index.html.md#aigverse.networks.NamedAig), which is an
[`Aig`](../networks/index.html.md#aigverse.networks.Aig) carrying the input and output names from the
AIGER symbol table. It is accepted anywhere an `Aig` is, so the names come
along at no cost to the caller.

* **Parameters:**
  * **name** – The benchmark name, e.g. `"adder"`. See [`epfl_names()`](#aigverse.benchmarks.epfl_names).
  * **revision** – Git revision of the benchmark repository to fetch from.
    Defaults to a pinned commit, so results are reproducible; pass
    `"master"` to follow the branch instead.
  * **cache_dir** – Directory to cache into, overriding the configured one.
  * **timeout** – Seconds to wait for the download.
* **Returns:**
  The benchmark network, with its I/O names.
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `name` is not part of the suite, or `revision` is not
    usable as a path component.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#OSError) – If the benchmark could not be downloaded.
  * [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If the downloaded file could not be parsed.

### epfl_names(category: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]

Lists the available benchmark names.

* **Parameters:**
  **category** – `"arithmetic"` or `"random_control"`, or `None` for all.
* **Returns:**
  The names, sorted.
* **Raises:**
  [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `category` is not a known category.

### epfl_path(name: [str](https://docs.python.org/3/builtins/stdtypes.html#str), , revision: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = DEFAULT_REVISION, cache_dir: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [PathLike](https://docs.python.org/3/library/os.html#os.PathLike)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None) = None, timeout: [float](https://docs.python.org/3/builtins/functions.html#float) = 60.0) → [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path)

Downloads an EPFL benchmark and returns the local file.

The download is cached, so repeated calls cost nothing after the first. Use
this when the AIGER file itself is wanted; [`epfl()`](#aigverse.benchmarks.epfl) parses it for you.

* **Parameters:**
  * **name** – The benchmark name, e.g. `"adder"`. See [`epfl_names()`](#aigverse.benchmarks.epfl_names).
  * **revision** – Git revision of the benchmark repository to fetch from.
    Defaults to a pinned commit, so results are reproducible; pass
    `"master"` to follow the branch instead.
  * **cache_dir** – Directory to cache into, overriding the configured one.
  * **timeout** – Seconds to wait for the download.
* **Returns:**
  Path to the local AIGER file.
* **Raises:**
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If `name` is not part of the suite, or `revision` is not
    usable as a path component.
  * [**OSError**](https://docs.python.org/3/builtins/exceptions.html#OSError) – If the benchmark could not be downloaded.