ogun/lib.rs
1//! # Ogun
2//!
3//! Spatial layout generation via sequential logit dynamics on potential games.
4//!
5//! Given a weighted graph and a 2D spatial domain, Ogun places nodes and
6//! routes edges at a controllable optimization level. The inverse temperature
7//! β governs output character — from near-random (low β) to near-optimal (high β).
8//!
9//! ## Algorithm
10//!
11//! ```text
12//! for each agent in arrival order:
13//! 1. EVAL_UTILITY — score every valid grid position via potential Φ
14//! 2. CHOOSE — Boltzmann sample: P(p) ∝ exp(β · Φ(p))
15//! 3. COMMIT — place irrevocably, block footprint
16//! 4. ROUTE — BFS (Lee) to already-placed neighbors
17//! score the completed layout
18//! ```
19//!
20//! ## Quick start
21//!
22//! ```rust
23//! use ogun::*;
24//!
25//! let graph = Graph {
26//! nodes: vec![
27//! Node { id: NodeId(0), radius: 1 },
28//! Node { id: NodeId(1), radius: 1 },
29//! ],
30//! edges: vec![Edge {
31//! id: EdgeId(0),
32//! src: NodeId(0),
33//! dst: NodeId(1),
34//! weight: 1.0,
35//! }],
36//! };
37//! let space = Space { width: 20, height: 20, obstacles: vec![], routing_costs: None };
38//! let config = OgunConfig { seed: 42, ..OgunConfig::default() };
39//!
40//! let layout = generate(&graph, &space, &config);
41//! assert!(layout.score.composite > 0.0);
42//! ```
43
44mod generate;
45mod graph;
46mod grid;
47mod layout;
48mod placement;
49mod potential;
50mod routing;
51mod scoring;
52mod types;
53
54// Public API: input types, output type, and the generate function.
55pub use generate::generate;
56pub use graph::{Edge, Graph, Node, OgunConfig, PotentialKernel, Rect, Space};
57pub use grid::Grid;
58pub use layout::Layout;
59pub use scoring::ScoreBreakdown;
60pub use types::{EdgeId, NodeId, Pos};