npe_graph/lib.rs
1//! # npe-graph
2//!
3//! A **node–port–edge** graph for engineering schematics: circuit diagrams,
4//! control-flow / block diagrams, hydraulic and pneumatic schematics.
5//!
6//! ## The data model
7//!
8//! ```text
9//! ┌─────────── Node ───────────┐ ┌────────── Node ──────────┐
10//! │ N (component data) │ │ N │
11//! │ │ │ │
12//! │ ○ Port (P) ○ Port (P) ───┼─Edge───┼─ ○ Port (P) ○ Port (P) │
13//! └────────────────────────────┘ (E) └──────────────────────────┘
14//! ```
15//!
16//! * A **node** is a component (op-amp, valve, PID block). Carries user data `N`.
17//! * A **port** is a connection point *owned by exactly one node* (pin, flange,
18//! signal input). Carries user data `P`. Ports have an identity of their own:
19//! they can be looked up, iterated, and referenced by edges directly.
20//! * An **edge** connects two *ports* (never two nodes directly). Carries user
21//! data `E` (wire gauge, pipe diameter, signal type, GUI spline route...).
22//!
23//! ## Quick example
24//!
25//! ```
26//! use npe_graph::Graph;
27//!
28//! // N = component, P = pin, E = wire — use your own rich types.
29//! let mut g: Graph<&str, &str, &str> = Graph::new();
30//!
31//! let r1 = g.add_node("R1: resistor 10k");
32//! let r1_a = g.add_port(r1, "a").unwrap();
33//! let r1_b = g.add_port(r1, "b").unwrap();
34//!
35//! let c1 = g.add_node("C1: cap 100n");
36//! let c1_pos = g.add_port(c1, "+").unwrap();
37//!
38//! let w = g.connect(r1_b, c1_pos, "wire").unwrap();
39//!
40//! assert_eq!(g.port_node(r1_b), Some(r1));
41//! assert_eq!(g.edge_endpoints(w), Some((r1_b, c1_pos)));
42//! assert!(g.neighbors(r1).any(|n| n == c1));
43//!
44//! // Removing a node cascades: its ports and their edges go too.
45//! g.remove_node(c1);
46//! assert!(!g.contains_edge(w));
47//! assert!(g.contains_port(r1_a)); // unrelated IDs unaffected
48//! ```
49
50mod graph;
51mod id;
52mod library;
53mod net;
54
55#[cfg(feature = "petgraph")]
56mod interop;
57
58pub use graph::{ConnectError, Graph, NodeMissing};
59pub use id::{EdgeId, NodeId, PortId};
60pub use library::{KeyedNodeTemplate, NodeProto, NodeTemplate};
61pub use net::Net;