Skip to main content

Crate raig

Crate raig 

Source
Expand description

raig (pronounced “rage”) is a dependency-free library for working with AIGs in Rust, developed at Cornell’s Capra Lab. AIGs represent Boolean logic using only AND nodes and NOT edges. This simple structure makes them smaller and faster for computer tools to process than other logic representations.

One of raig’s key advantages is its use of compact graph::NodeId values instead of pointers.

§Tutorial

§1.0 Start With an AIGER File

The most common starting point is an AIGER file (a digital file format for storing AIGs) from another tool, such as py-aiger or aiger. Internal generation of AIGER files is not yet supported, but you can bypass the parser and build a graph::AigGraph (our intenral representation of AIGs) directly using graph::AigBuilder.

As of 0.1.0, raig’s AIGER parser accepts anything that implements std::io::BufRead, so the same parser works for local files, stdin, network responses, and uploaded file bytes.

§1.1 More about AIGER files

Here is a small example demonstrating some of AIGER’s invariants, but you can (and should!) read more about the invariants of AIGER files (i.e., .aag and .aig files) here.

This is an example ASCII AIGER circuit that has one input and one output. The output is exactly the input, so it behaves like an identity function.

aag 1 1 0 1 0
2
2

The header is:

aag M I L O A

In this example, M = 1, I = 1, L = 0, O = 1, and A = 0: one input, no latches, one output, and no AND gates. The first body line declares input literal 2; the second body line says the output is also literal 2.

§1.2 Parse Uploaded Bytes

If an application receives uploaded AIGER bytes, wrap those bytes in a std::io::BufReader and call aiger::run_parser_with_options.

use raig::aiger::run_parser_with_options;
use std::io::BufReader;

let uploaded_aiger = b"aag 1 1 0 1 0\n2\n2\n";
let mut reader = BufReader::new(&uploaded_aiger[..]);
let (graph, _, _) = run_parser_with_options(&mut reader, true)?;

§1.3 Parse a File From Disk

Local files use the same API. Open the file, wrap it in a buffered reader, and parse it.

use raig::aiger::run_parser_with_options;
use std::fs::File;
use std::io::BufReader;

let file = File::open("circuit.aag")?;
let mut reader = BufReader::new(file);
let (graph, _, _) = run_parser_with_options(&mut reader, true)?;

§2.0 Work With the Parsed graph::AigGraph

After parsing, you now have an internal AIG representation! Congrats! From there, the most common next steps are simulation and visualization (AIGER conversions and local rewriting and upcoming features).

§2.1 Simulate the Circuit

Simulation inputs are vectors of graph::Value. Use 0 for false and graph::Value::MAX for true.

use raig::aiger::run_parser_with_options;
use raig::graph::Value;
use std::io::BufReader;

let uploaded_aiger = b"aag 1 1 0 1 0\n2\n2\n";
let mut reader = BufReader::new(&uploaded_aiger[..]);
let (graph, _, _) = run_parser_with_options(&mut reader, true)?;

let stimulus = vec![
    vec![0],
    vec![Value::MAX],
];
let trace = graph.simulate(stimulus.as_slice());

assert_eq!(trace[0].outputs[0], 0);
assert_eq!(trace[1].outputs[0], Value::MAX);

Value is a packed Boolean value. Other bit patterns can be used to evaluate many independent Boolean lanes in parallel with bitwise operations.

§2.2 Render Graphviz DOT

Once parsed, an graph::AigGraph can be rendered as Graphviz DOT for inspection.

use raig::aiger::run_parser_with_options;
use std::io::BufReader;

let uploaded_aiger = b"aag 1 1 0 1 0\n2\n2\n";
let mut reader = BufReader::new(&uploaded_aiger[..]);
let (graph, _, _) = run_parser_with_options(&mut reader, true)?;

let dot = graph.to_dot();
assert!(dot.contains("digraph AIG"));

It should be noted that this feature is only especially helpful for AIG graphs on the smaller side, and is not so efficient for larger graphs.

§3.0 Use the CLI

Install the CLI with:

cargo install raig-cli

Then parse, render, or simulate AIGER files:

raig parse circuit.aag
raig dot circuit.aag --output circuit.dot
raig simulate circuit.aag stimulus.txt

Stimulus files contain one input vector per line and may end with .:

0
1
.

§4.0 Build Graphs Directly

You can also build AIGs directly in Rust with graph::AigBuilder. This is useful for generating circuits, writing tests, or integrating with another frontend.

§4.1 Build an AND Gate

use raig::graph::{AigBuilder, Value};

let mut builder = AigBuilder::new();
let a = builder.add_input();
let b = builder.add_input();
let output = builder.add_and_optimized(a, b);
builder.add_output(output);

let graph = builder.build();
let inputs = vec![
    vec![Value::MAX, Value::MAX],
    vec![Value::MAX, 0],
];
let trace = graph.simulate(inputs.as_slice());

assert_eq!(trace[0].outputs[0], Value::MAX);
assert_eq!(trace[1].outputs[0], 0);

§4.2 Use Inverted Edges

AIGs do not store NOT gates as separate edges. Instead, a graph::NodeId can refer to either a regular signal or its inverted form:

use raig::graph::{AigBuilder, Value};

let mut builder = AigBuilder::new();
let a = builder.add_input();
let b = builder.add_input();

// OR via De Morgan's law:
// a | b = !(!a & !b)
let not_a_and_not_b = builder.add_and_optimized(a.invert(), b.invert());
builder.add_output(not_a_and_not_b.invert());

let graph = builder.build();
let inputs = vec![
    vec![0, 0],
    vec![Value::MAX, 0],
    vec![0, Value::MAX],
];
let trace = graph.simulate(inputs.as_slice());

assert_eq!(trace[0].outputs[0], 0);
assert_eq!(trace[1].outputs[0], Value::MAX);
assert_eq!(trace[2].outputs[0], Value::MAX);

Modules§

aiger
AIGER parsing support.
graph
Graph data structures and simulation utilities for AIGs.