aigverse.abc

Bridge to the external ABC logic synthesis system.

aigverse does not ship ABC. This module drives an ABC executable that is already installed on the machine, transferring networks as binary AIGER files. Point it at an executable with the AIGVERSE_ABC environment variable or set_abc_binary(), or put abc on PATH.

Importing this module always succeeds, whether or not ABC is installed. Use is_available() to check, and expect AbcNotFoundError from any call that needs the executable.

The ABC9 (&-space) commands live in the gia namespace, mirroring ABC’s own prefix: abc.dc2 runs ABC’s dc2 while abc.gia.dc2 runs its &dc2.

Example

>>> from aigverse import abc
>>> from aigverse.generators import ripple_carry_adder
>>> aig = ripple_carry_adder(4)
>>> if abc.is_available():
...     optimized = abc.resyn2(aig)
...     alternative = abc.gia.dc2(aig)

Submodules

Package Contents

ABC_ENV_VAR = 'AIGVERSE_ABC'
ABC_RC_ENV_VAR = 'AIGVERSE_ABC_RC'
abc_binary() → Path[source]

Resolves the ABC executable.

Returns:

The resolved absolute path to the ABC executable.

Raises:

AbcNotFoundError – If no ABC executable could be located.

abc_rc() → Path | None[source]

Resolves the ABC resource file loaded before every command.

Resolution order: an explicit path set via set_abc_rc(), then the AIGVERSE_ABC_RC environment variable.

Returns:

The resolved absolute path, or None if no resource file is configured.

abc_version(*, timeout: float | None = 10.0) → str[source]

Queries the version banner of the resolved ABC executable.

Useful to confirm that whatever was discovered really is Berkeley ABC, since discovery itself deliberately does not start a process.

Parameters:

timeout – Seconds to wait for ABC to respond, or None to wait forever.

Returns:

The trimmed output of ABC’s version command.

Raises:

  • AbcNotFoundError – If no ABC executable could be located.

  • AbcTimeoutError – If ABC did not terminate within timeout seconds.

  • AbcExecutionError – If the executable did not accept the version command, which means whatever was discovered is not ABC.

find_abc_binary() → Path | None[source]

Resolves the ABC executable without raising.

Resolution order: an explicit override set via set_abc_binary(), then the AIGVERSE_ABC environment variable, then a PATH lookup for abc and berkeley-abc.

Returns:

The resolved absolute path, or None if no candidate was found.

is_available() → bool[source]

Reports whether an ABC executable can be located.

This never raises and never starts a process, so it is safe to call in a module guard or a test skip condition.

Returns:

True if an ABC executable was found, False otherwise.

set_abc_binary(path: str | PathLike[str] | None) → Path | None[source]

Sets or clears an explicit path to the ABC executable.

The explicit override takes precedence over the AIGVERSE_ABC environment variable and over a PATH lookup. It applies process-wide and is intended to be called once during setup; it is not thread-safe.

Parameters:

path – Path to the ABC executable, or None to clear a previously set override and fall back to environment and PATH discovery.

Returns:

The resolved absolute path, or None if the override was cleared.

Raises:

AbcNotFoundError – If path does not exist or is not executable.

set_abc_rc(path: str | PathLike[str] | None) → Path | None[source]

Sets or clears an ABC resource file to load before every command.

The bridge normally runs ABC with -s so that no abc.rc is read and results do not depend on the local installation. Registering a resource file here keeps that isolation – the file given is the only one loaded – while making its aliases available to run_script() and run_commands().

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

Parameters:

path – Path to an ABC resource file, or None to clear a previously set one and go back to running without any.

Returns:

The resolved absolute path, or None if the resource file was cleared.

Raises:

AbcNotFoundError – If path does not exist or is not a file.

balance(ntk: aigverse.abc._runner.AigT, *, minimize_levels: bool = True, exor: bool = False, duplicate: bool = False, duplicate_critical: bool = False, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s balance command on a network.

Restructures the AND trees of the network to reduce its depth.

Parameters:

  • ntk – The combinational network to optimize.

  • minimize_levels – If True (ABC’s default), balance for minimal depth.

  • exor – If True, balance multi-input EXOR structures as well.

  • duplicate – If True, allow logic to be duplicated.

  • duplicate_critical – If True, duplicate logic on the critical paths only, which buys depth for less area than duplicate does.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

orchestrate(ntk: aigverse.abc._runner.AigT, *, max_cut_size: int | None = None, max_inserts: int | None = None, odc_levels: int | None = None, preserve_levels: bool = True, zero_cost_rewrite: bool = True, zero_cost_refactor: bool = True, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s orchestrate command on a network.

Interleaves rewriting, refactoring and resubstitution rather than running them one after another, choosing per node which of the three to apply. It is a single command doing the job of a whole schedule.

Note that ABC enables zero-cost replacements here by default, unlike in the standalone rewrite() and refactor() commands.

Parameters:

  • ntk – The combinational network to optimize.

  • max_cut_size – Resubstitution cut size (ABC’s -K, 4 to 16), or None for ABC’s default of 8.

  • max_inserts – Nodes resubstitution may add (ABC’s -N, 0 to 3), or None for ABC’s default of 1.

  • odc_levels – Fanout levels used for don’t-care computation (ABC’s -F), or None for ABC’s default of 0.

  • preserve_levels – If True (ABC’s default), never increase the depth.

  • zero_cost_rewrite – If True (ABC’s default here), let the rewriting part apply replacements that do not reduce the size.

  • zero_cost_refactor – If True (ABC’s default here), the same for the refactoring part.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

Raises:

ValueError – If an option is outside the range ABC accepts.

refactor(ntk: aigverse.abc._runner.AigT, *, max_support: int | None = None, min_saved: int | None = None, preserve_levels: bool = True, zero_cost: bool = False, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s refactor command on a network.

Collapses a cone into a single node and resynthesizes it from its truth table, which reaches larger cuts than rewrite() does.

Parameters:

  • ntk – The combinational network to optimize.

  • max_support – Maximum support of a collapsed node (ABC’s -N, 1 to 15), or None for ABC’s default of 10. Larger values are slower. ABC documents no range but rejects anything above 15.

  • min_saved – Minimum number of nodes a single step must save to be applied (ABC’s -M, at least 0), or None for ABC’s default of 1. Setting it to 0 accepts steps that save nothing.

  • preserve_levels – If True (ABC’s default), never increase the depth.

  • zero_cost – If True, also apply replacements that do not reduce the size, which perturbs the structure and can unlock later gains.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

Raises:

ValueError – If max_support is outside the range ABC accepts.

resub(ntk: aigverse.abc._runner.AigT, *, max_cut_size: int | None = None, max_inserts: int | None = None, min_saved: int | None = None, odc_levels: int | None = None, preserve_levels: bool = True, zero_cost: bool = False, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s resub command on a network.

Re-expresses a node in terms of other nodes already present, which removes logic that rewriting and refactoring cannot reach because it is not local.

Parameters:

  • ntk – The combinational network to optimize.

  • max_cut_size – Maximum cut size (ABC’s -K, 4 to 16), or None for ABC’s default of 8. The canonical scripts sweep this from 6 to 12.

  • max_inserts – Maximum number of nodes to add (ABC’s -N, 0 to 3), or None for ABC’s default of 1.

  • min_saved – Minimum number of nodes a single step must save to be applied (ABC’s -M, at least 0), or None for ABC’s default of 1.

  • odc_levels – Fanout levels used for observability-don’t-care computation (ABC’s -F, at least 0), or None for ABC’s default of 0, which disables it. Don’t-cares find substitutions that are only valid in context, at the cost of a more expensive analysis.

  • preserve_levels – If True (ABC’s default), never increase the depth.

  • zero_cost – If True, also apply replacements that do not reduce the size, which perturbs the structure and can unlock later gains.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

Raises:

ValueError – If max_cut_size or max_inserts is outside the range ABC accepts.

rewrite(ntk: aigverse.abc._runner.AigT, *, preserve_levels: bool = True, zero_cost: bool = False, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s rewrite command on a network.

Replaces 4-input subgraphs with smaller pre-computed equivalents.

Parameters:

  • ntk – The combinational network to optimize.

  • preserve_levels – If True (ABC’s default), never increase the depth.

  • zero_cost – If True, also apply replacements that do not reduce the size, which perturbs the structure and can unlock later gains.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

exception AbcError[source]

Bases: RuntimeError

Base class for every failure raised by the ABC bridge.

exception AbcExecutionError(message: str, *, binary: str, command: str, output: str)[source]

Bases: AbcError

Raised when ABC ran but did not produce a usable result.

ABC exits with status 0 even for unknown commands and unreadable files, and writes everything to standard output, so the captured output is the only diagnostic available. It is attached to the exception as output, next to the binary that was invoked and the command it was given.

binary
command
output
exception AbcNotFoundError[source]

Bases: AbcError

Raised when no usable ABC executable could be located.

exception AbcTimeoutError(message: str, *, binary: str, command: str, output: str)[source]

Bases: AbcExecutionError

Raised when ABC did not terminate within the requested timeout.

run_commands(commands: str | Sequence[str], *, timeout: float | None = None, use_init_file: bool = False, cwd: str | PathLike[str] | None = None, binary: str | PathLike[str] | None = None) → str[source]

Runs raw ABC commands and returns their combined output.

No network is transferred; this is the escape hatch for commands such as version or print_stats on files the caller manages themselves.

Parameters:

  • commands – A single ;-separated command string, or a sequence of individual commands.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • use_init_file – If False (default), ABC is invoked with -s so that no abc.rc is read and behaviour does not depend on the local install. Set to True to let ABC pick up an abc.rc from the working directory. Prefer set_abc_rc(), which loads one specific file and keeps the isolation.

  • cwd – Working directory for the ABC process. Defaults to a fresh temporary directory, because ABC writes an abc.history file into wherever it runs. Pass a directory explicitly if the commands refer to files by relative path.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

Everything ABC wrote to its output.

Raises:
run_script(ntk: AigT, commands: str | Sequence[str], *, timeout: float | None = None, use_init_file: bool = False, gia: bool = False, verbose: bool = False, binary: str | PathLike[str] | None = None) → AigT[source]

Optimizes a network by piping it through an external ABC process.

The network is written to a temporary binary AIGER file, ABC is invoked with a read command, the given commands, and a write command, and the result is read back. The returned network has the same type as ntk: an Aig yields an Aig, a NamedAig yields a NamedAig with its input and output names preserved.

ABC keeps two independent network stores, and a command only ever sees the one it belongs to. By default the network is loaded with read_aiger into the classic store, where the commands without a & prefix operate (balance, rewrite, refactor, resub, and hence every script in SCRIPTS). The &-prefixed commands of ABC9 operate on a separate store, the GIA, which stays empty in that mode – a script such as "&syn2" fails with there is no AIG unless it starts with &get. Set gia=True to load the network straight into the GIA with &read instead, which is the cheaper and lossless way to run a & script.

commands must not contain the read and write steps; they are added automatically. Only commands the resolved ABC binary knows are valid – resyn2 and friends are abc.rc aliases rather than builtins, so use the wrappers in this module or SCRIPTS.

Parameters:

  • ntk – The combinational network to optimize.

  • commands – A single ;-separated ABC command string, or a sequence of individual commands.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • use_init_file – If False (default), ABC is invoked with -s so that no abc.rc is read and results do not depend on the local install. A resource file registered with set_abc_rc() is loaded regardless, making its aliases available.

  • gia – If True, transfer the network through &read/&write so it lands in ABC9’s GIA store and &-prefixed commands can be used directly. The classic commands then see nothing instead. Mixing the two within one script is possible with &get/&put, but those do not carry I/O names across, whereas &read/&write do.

  • verbose – If True, print everything ABC wrote. This is the captured output, not ABC’s own -v reporting – that differs per command and is left to the caller to add to commands.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

Raises:
SCRIPTS: Final[Mapping[str, tuple[str, Ellipsis]]]
expand_script(name: str) → tuple[str, Ellipsis][source]

Expands a canonical ABC script name into builtin commands.

Parameters:

name – The script name, e.g. "resyn2". See SCRIPTS for the available names.

Returns:

The commands the script consists of, all of them ABC builtins.

Raises:

KeyError – If name is not a known script.

class AbcStats[source]

What ABC reports about a network.

ABC’s own network name is deliberately absent: the bridge transfers through a temporary file, so it is always that file’s stem and never says anything about the network. It survives verbatim in raw.

num_pis: int
num_pos: int
num_gates: int
num_levels: int
num_registers: int | None = None
average_level: float | None = None
memory_mb: float | None = None
raw: str = ''
stats(ntk: Aig, *, timeout: float | None = None, binary: str | PathLike[str] | None = None) → AbcStats[source]

Reports ABC’s print_stats for a network.

Warning

These are ABC’s counts, not aigverse’s, and the two can differ for the very same network. ABC structurally hashes as it reads, so any structural redundancy the network carried is gone before print_stats sees it: a 16-bit carry-lookahead adder that aigverse reports as 186 gates comes back from here as 182. Use num_gates to describe the network you hold, and this to describe what ABC worked on.

Parameters:

  • ntk – The combinational network to measure.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

What ABC reports about the network.

Raises:
compress(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s compress script on a network.

Like resyn, but every command is given -l, which turns ABC’s default level preservation off and lets it trade depth for size.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

compress2(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s compress2 script on a network.

Like resyn2, but every command is given -l, which turns ABC’s default level preservation off and lets it trade depth for size.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

compress2rs(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s compress2rs script on a network.

resyn2rs with level preservation turned off; the strongest of these scripts, and the slowest.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

dc2(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s dc2 script on a network.

ABC’s builtin combinational don’t-care-based optimization.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

resyn(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s resyn script on a network.

A short balance/rewrite loop; the lightest of the standard scripts.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

resyn2(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s resyn2 script on a network.

The most widely used ABC size-reduction script.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

resyn2rs(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s resyn2rs script on a network.

resyn2 extended with resubstitution passes; slower and usually smaller.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

resyn3(ntk: aigverse.abc._runner.AigT, *, timeout: float | None = None, verbose: bool = False, binary: str | PathLike[str] | None = None) → aigverse.abc._runner.AigT[source]

Runs ABC’s resyn3 script on a network.

A resubstitution-driven variant of resyn.

The script is expanded into builtin ABC commands, so it does not depend on an abc.rc being present. See SCRIPTS for the exact expansion. Errors are reported the same way as by run_script().

Parameters:

  • ntk – The combinational network to optimize.

  • timeout – Seconds to wait for ABC to terminate, or None for no limit.

  • verbose – If True, print everything ABC wrote.

  • binary – Overrides the resolved ABC executable for this call only.

Returns:

The optimized network, of the same type as ntk.

class CecStatus(*args, **kwds)[source]

Bases: enum.Enum

The outcome of an equivalence check.

Deliberately not usable as a boolean: if cec(a, b): would read as “equivalent” while quietly also firing for UNDECIDED and TIMEOUT, which are not the same claim at all. Compare explicitly:

if abc.gia.cec(a, b) is abc.gia.CecStatus.EQUIVALENT:
    ...
EQUIVALENT = 'equivalent'
NOT_EQUIVALENT = 'not equivalent'
UNDECIDED = 'undecided'
TIMEOUT = 'timeout'
__bool__() → bool[source]

Refuses truth testing.

Raises:

TypeError – Always. Compare against a member instead.