hdl_cat/
lib.rs

1//! # hdl-cat
2//!
3//! A hardware description library re-architected around
4//! [`comp_cat_rs`](https://github.com/MavenRain/comp-cat-rs)'s
5//! categorical effect system.
6//!
7//! This umbrella crate re-exports the full workspace so a single
8//! `use hdl_cat::*;` (or a trimmed [`prelude`]) is enough to get
9//! going.
10//!
11//! ## Layers
12//!
13//! | Concept | Crate |
14//! |---|---|
15//! | Errors | `hdl_cat_error` |
16//! | Bit-precise ints | `hdl_cat_bits` |
17//! | Hardware-typable types | `hdl_cat_kind` |
18//! | Domain-indexed signals | `hdl_cat_signal` |
19//! | IR (free-category graph) | `hdl_cat_ir` |
20//! | Circuit category | `hdl_cat_circuit` |
21//! | Sync machines | `hdl_cat_sync` |
22//! | Simulator | `hdl_cat_sim` |
23//! | Verilog emitter | `hdl_cat_verilog` |
24//! | Circom emitter | `hdl_cat_circom` |
25//! | Standard components | `hdl_cat_std` |
26//!
27//! ## End-to-end example — stateful counter
28//!
29//! Build → simulate → emit Verilog.
30//!
31//! ```
32//! # fn main() -> Result<(), hdl_cat::Error> {
33//! use hdl_cat::prelude::*;
34//! use hdl_cat_kind::BitSeq;
35//!
36//! let c = std_lib::counter::<4>()?;
37//! let inputs: Vec<BitSeq> = (0..4).map(|_| BitSeq::new()).collect();
38//! let samples = Testbench::new(c).run(inputs).run()?;
39//! let values: Vec<u128> = samples
40//!     .iter()
41//!     .map(|s| Bits::<4>::from_bits_seq(s.value()).map(Bits::to_u128))
42//!     .collect::<Result<Vec<_>, _>>()?;
43//! assert_eq!(values, vec![0, 1, 2, 3]);
44//!
45//! let c = std_lib::counter::<4>()?;
46//! let module = verilog::emit_sync_graph(
47//!     c.graph(), "counter4",
48//!     c.state_wire_count(), c.input_wires(), c.output_wires(),
49//!     c.initial_state(),
50//! ).run()?;
51//! let text = module.render().run()?;
52//! assert!(text.contains("always_ff @(posedge clk)"));
53//! # Ok(()) }
54//! ```
55//!
56//! ## End-to-end example — combinational half-adder
57//!
58//! ```
59//! # fn main() -> Result<(), hdl_cat::Error> {
60//! use hdl_cat::prelude::*;
61//!
62//! let ha = std_lib::half_adder()?;
63//! let module = verilog::emit_graph(
64//!     ha.graph(),
65//!     "half_adder",
66//!     ha.inputs(),
67//!     ha.outputs(),
68//! ).run()?;
69//! let text = module.render().run()?;
70//! assert!(text.contains("module half_adder"));
71//! assert!(text.contains("assign"));
72//! # Ok(()) }
73//! ```
74//!
75//! ## End-to-end example — combinational Circom emission
76//!
77//! Lower a 4-bit bitwise inverter to a self-contained `circom 2.0.0`
78//! template.
79//!
80//! ```
81//! # fn main() -> Result<(), hdl_cat::Error> {
82//! use hdl_cat::circom::emit_template;
83//! use hdl_cat::ir::{HdlGraphBuilder, Op, WireTy};
84//!
85//! let (b, a) = HdlGraphBuilder::new().with_wire(WireTy::Bits(4));
86//! let (b, out) = b.with_wire(WireTy::Bits(4));
87//! let b = b.with_instruction(Op::Not, vec![a], out)?;
88//! let graph = b.build();
89//!
90//! let template = emit_template(&graph, "inv4", &[a], &[out], &[]).run()?;
91//! let text = template.render().run()?;
92//! assert!(text.starts_with("pragma circom 2.0.0;"));
93//! assert!(text.contains("template inv4()"));
94//! assert!(text.contains("component main = inv4();"));
95//! # Ok(()) }
96//! ```
97
98pub use hdl_cat_bits as bits;
99pub use hdl_cat_circom as circom;
100pub use hdl_cat_macros::kernel;
101pub use hdl_cat_circuit as circuit;
102pub use hdl_cat_error::{Cycle, Error, SignalName, TypeName, Width};
103pub use hdl_cat_ir as ir;
104pub use hdl_cat_kind as kind;
105pub use hdl_cat_sim as sim;
106pub use hdl_cat_signal as signal;
107pub use hdl_cat_std as std_lib;
108pub use hdl_cat_sync as sync;
109pub use hdl_cat_verilog as verilog;
110
111/// Curated re-exports for quick imports.
112pub mod prelude {
113    pub use crate::{bits, circom, circuit, ir, kind, sim, signal, std_lib, sync, verilog};
114    pub use crate::{Cycle, Error, SignalName, TypeName, Width};
115    pub use hdl_cat_bits::{Bits, SignedBits};
116    pub use hdl_cat_circuit::{
117        gates, Circuit, CircuitArrow, CircuitTensor, CircuitUnit, Obj, Object,
118    };
119    pub use hdl_cat_kind::{BitSeq, Hw, TypeDesc};
120    pub use hdl_cat_sim::Testbench;
121    pub use hdl_cat_sync::Sync;
122}
hdl_cat/lib.rs

hdl_cat/
lib.rs
