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 guide for a runnable example.

Package Contents

CACHE_ENV_VAR = 'AIGVERSE_BENCHMARK_CACHE'
benchmark_cache() → Path[source]

Resolves the directory downloaded benchmarks are cached in.

Resolution order: an explicit override set via 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 | PathLike[str] | None) → Path | None[source]

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 = '0060e156826e733d69bf5b3322d1bdd0d03a1f9a'
EPFL_ARITHMETIC: frozenset[str]
EPFL_BENCHMARKS: frozenset[str]
EPFL_RANDOM_CONTROL: frozenset[str]
epfl(name: str, *, revision: str = DEFAULT_REVISION, cache_dir: str | PathLike[str] | None = None, timeout: float = 60.0) → NamedAig[source]

Loads an EPFL benchmark as a network.

The result is a NamedAig, which is an 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().

  • 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 – If name is not part of the suite, or revision is not usable as a path component.

  • OSError – If the benchmark could not be downloaded.

  • RuntimeError – If the downloaded file could not be parsed.

epfl_names(category: str | None = None) → tuple[str, Ellipsis][source]

Lists the available benchmark names.

Parameters:

category – "arithmetic" or "random_control", or None for all.

Returns:

The names, sorted.

Raises:

ValueError – If category is not a known category.

epfl_path(name: str, *, revision: str = DEFAULT_REVISION, cache_dir: str | PathLike[str] | None = None, timeout: float = 60.0) → Path[source]

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() parses it for you.

Parameters:

  • name – The benchmark name, e.g. "adder". See 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 – If name is not part of the suite, or revision is not usable as a path component.

  • OSError – If the benchmark could not be downloaded.