1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
//! `raig` (pronounced “rage”) is a dependency-free library for working with
//! [AIGs](https://en.wikipedia.org/wiki/And-inverter_graph)
//! in Rust, developed at
//! [Cornell's Capra Lab](https://capra.cs.cornell.edu/).
//! 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](https://fmv.jku.at/aiger/FORMAT.aiger)
//! (a digital file format for storing AIGs)
//! from another tool, such as
//! [py-aiger](https://github.com/mvcisback/py-aiger)
//! or
//! [aiger](https://github.com/arminbiere/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](https://github.com/arminbiere/aiger).
//!
//! 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.
//!
//! ```text
//! aag 1 1 0 1 0
//! 2
//! 2
//! ```
//!
//! The header is:
//!
//! ```text
//! 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)?;
//!
//! # let _ = graph;
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! ### 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.
//!
//! ```no_run
//! 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)?;
//!
//! # let _ = graph;
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! ## 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);
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! `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"));
//! # Ok::<(), std::io::Error>(())
//! ```
//! 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:
//!
//! ```sh
//! cargo install raig-cli
//! ```
//!
//! Then parse, render, or simulate AIGER files:
//!
//! ```sh
//! 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 `.`:
//!
//! ```text
//! 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);
//! ```