feat(std): Sign and Select cells — the Bool→F64 bridge pair

First half of the #281 clock-enable set: Sign promotes the private
sign0() semantics to vocabulary (strict comparisons; NaN and -0.0
fall to 0.0), Select is the stateless 2:1 mux that consumes Bool
back into the F64 plane. Both zero-arg, Firing::Any, rostered
(count pins 29→31); an engine E2E drives both through the real
GraphBuilder→compile→run seam.

refs #281
This commit is contained in:
2026-07-17 19:49:13 +02:00
parent b5c82f5d16
commit 40e962db89
6 changed files with 342 additions and 5 deletions
+4
View File
@@ -44,8 +44,10 @@ mod resample;
mod rolling_max;
mod rolling_min;
mod scale;
mod select;
mod series_reducer;
mod session;
mod sign;
mod sim_broker;
mod sizer;
mod sma;
@@ -88,8 +90,10 @@ pub use resample::Resample;
pub use rolling_max::RollingMax;
pub use rolling_min::RollingMin;
pub use scale::Scale;
pub use select::Select;
pub use series_reducer::SeriesReducer;
pub use session::{Session, SessionFrankfurt};
pub use sign::Sign;
pub use sim_broker::SimBroker;
pub use sizer::Sizer;
pub use sma::Sma;
+126
View File
@@ -0,0 +1,126 @@
//! `Select` — the stateless 2:1 mux `bool × f64 × f64 -> f64`: forwards
//! `then` when `cond` is true, `otherwise` when it is false.
//!
//! The missing RTL standard cell (#281): the generic consumer of the Bool
//! plane back into F64. Until it existed, conditional values required
//! arithmetic contortions; with it, `count_true` composes as
//! `CumSum(Select(cond, 1.0, 0.0))` — no Counter primitive needed.
//!
//! Three inputs (`cond: Bool`, `then: F64`, `otherwise: F64`, each
//! `Firing::Any`), one `f64` output, no params, stateless. Emits `None`
//! until **all three** legs are warm — the mux reads both data inputs, as
//! [`Gt`](crate::Gt) requires both of its legs.
use aura_core::{Cell, Ctx, FieldSpec, Firing, Node, NodeSchema, PortSpec, PrimitiveBuilder, ScalarKind};
/// Stateless 2:1 mux: `out = if cond { then } else { otherwise }`, decided
/// fresh each fired cycle. Emits `None` until all three legs are warm (C8).
pub struct Select {
out: [Cell; 1],
}
impl Select {
/// Build a `Select` node.
pub fn new() -> Self {
Self { out: [Cell::from_f64(0.0)] }
}
/// The param-generic recipe for a blueprint primitive: paramless, builds
/// through `Select::new`.
pub fn builder() -> PrimitiveBuilder {
PrimitiveBuilder::new(
"Select",
NodeSchema {
inputs: vec![
PortSpec { kind: ScalarKind::Bool, firing: Firing::Any, name: "cond".into() },
PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "then".into() },
PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "otherwise".into() },
],
output: vec![FieldSpec { name: "value".into(), kind: ScalarKind::F64 }],
params: vec![],
},
|_| Box::new(Select::new()),
)
}
}
impl Default for Select {
fn default() -> Self {
Self::new()
}
}
impl Node for Select {
fn lookbacks(&self) -> Vec<usize> {
vec![1, 1, 1]
}
fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Cell]> {
let cond = ctx.bool_in(0);
let then = ctx.f64_in(1);
let otherwise = ctx.f64_in(2);
if cond.is_empty() || then.is_empty() || otherwise.is_empty() {
return None; // all three legs required (C8 warm-up gate)
}
let c = cond.get(0).unwrap_or(false);
self.out[0] = Cell::from_f64(if c { then[0] } else { otherwise[0] });
Some(&self.out)
}
fn label(&self) -> String {
"Select".to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
use aura_core::{AnyColumn, Scalar, Timestamp};
fn mux_inputs() -> Vec<AnyColumn> {
vec![
AnyColumn::with_capacity(ScalarKind::Bool, 1),
AnyColumn::with_capacity(ScalarKind::F64, 1),
AnyColumn::with_capacity(ScalarKind::F64, 1),
]
}
#[test]
fn select_muxes_per_cycle_by_cond() {
// PROPERTY: out = if cond { then } else { otherwise }, re-decided each
// cycle (stateless) — the 2:1 mux, both branches exercised plus a flip.
let mut node = Select::new();
let mut inputs = mux_inputs();
let cases = [((true, 1.0, 9.0), 1.0), ((false, 1.0, 9.0), 9.0), ((true, 5.0, 7.0), 5.0)];
for ((c, t, o), want) in cases {
inputs[0].push(Scalar::bool(c)).unwrap();
inputs[1].push(Scalar::f64(t)).unwrap();
inputs[2].push(Scalar::f64(o)).unwrap();
let got = node.eval(Ctx::new(&inputs, Timestamp(0)));
assert_eq!(got, Some([Cell::from_f64(want)].as_slice()));
}
}
#[test]
fn select_is_none_until_all_three_legs_warm() {
// The mux reads BOTH data inputs: a cold otherwise-leg gates the output
// even while cond is true and then is present.
let mut node = Select::new();
let mut inputs = mux_inputs();
inputs[0].push(Scalar::bool(true)).unwrap();
inputs[1].push(Scalar::f64(1.0)).unwrap();
assert_eq!(node.eval(Ctx::new(&inputs, Timestamp(0))), None);
inputs[2].push(Scalar::f64(9.0)).unwrap();
assert_eq!(
node.eval(Ctx::new(&inputs, Timestamp(0))),
Some([Cell::from_f64(1.0)].as_slice())
);
}
#[test]
fn input_slots_are_named_cond_then_otherwise() {
let names: Vec<String> =
Select::builder().schema().inputs.iter().map(|p| p.name.clone()).collect();
assert_eq!(names, ["cond", "then", "otherwise"]);
}
}
+113
View File
@@ -0,0 +1,113 @@
//! `Sign` — a stateless `f64 -> f64` sign extractor emitting exactly `+1.0`,
//! `-1.0`, or `0.0` by strict comparison.
//!
//! The `sign0()` semantics already private in
//! [`PositionManagement`](crate::PositionManagement)
//! (`position_management.rs`), promoted to vocabulary (#281): `> 0 -> +1.0`,
//! `< 0 -> -1.0`, else `0.0` — so `NaN` (which compares false on both sides)
//! and `-0.0` both fall to `0.0`. The private helper itself stays untouched;
//! this cell is the roster-eligible twin, the generic bridge the Bool/F64
//! conditional plane was missing.
//!
//! One `f64` input (`Firing::Any`), one `f64` output, no params, stateless,
//! allocation-free on the hot path (the single-cell output buffer is sized
//! once at construction, C7).
use aura_core::{Cell, Ctx, FieldSpec, Firing, Node, NodeSchema, PortSpec, PrimitiveBuilder, ScalarKind};
/// Stateless sign extractor: `+1.0` / `-1.0` / `0.0` by strict comparison
/// (`NaN` falls to `0.0`). Emits `None` until the input is warm (C8).
pub struct Sign {
out: [Cell; 1],
}
impl Sign {
/// Build a `Sign` node.
pub fn new() -> Self {
Self { out: [Cell::from_f64(0.0)] }
}
/// The param-generic recipe for a blueprint primitive: paramless, builds
/// through `Sign::new`.
pub fn builder() -> PrimitiveBuilder {
PrimitiveBuilder::new(
"Sign",
NodeSchema {
inputs: vec![PortSpec { kind: ScalarKind::F64, firing: Firing::Any, name: "value".into() }],
output: vec![FieldSpec { name: "value".into(), kind: ScalarKind::F64 }],
params: vec![],
},
|_| Box::new(Sign::new()),
)
}
}
impl Default for Sign {
fn default() -> Self {
Self::new()
}
}
impl Node for Sign {
fn lookbacks(&self) -> Vec<usize> {
vec![1]
}
fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Cell]> {
let v = ctx.f64_in(0);
if v.is_empty() {
return None; // warm-up gate (C8)
}
let x = v[0];
// strict comparisons: NaN and -0.0 both fall to 0.0, as sign0 does
let s = if x > 0.0 {
1.0
} else if x < 0.0 {
-1.0
} else {
0.0
};
self.out[0] = Cell::from_f64(s);
Some(&self.out)
}
fn label(&self) -> String {
"Sign".to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
use aura_core::{AnyColumn, Scalar, Timestamp};
#[test]
fn sign_maps_the_three_regions_and_nan_to_zero() {
// PROPERTY: out = +1.0 / -1.0 / 0.0 by strict comparison — the sign0()
// semantics promoted to vocabulary. NaN compares false on both sides,
// so it falls to 0.0, exactly as sign0 does; -0.0 likewise.
let mut node = Sign::new();
let mut inputs = vec![AnyColumn::with_capacity(ScalarKind::F64, 1)];
let cases = [(2.5, 1.0), (-0.1, -1.0), (0.0, 0.0), (f64::NAN, 0.0), (-0.0, 0.0)];
for (x, want) in cases {
inputs[0].push(Scalar::f64(x)).unwrap();
let got = node.eval(Ctx::new(&inputs, Timestamp(0)));
assert_eq!(got, Some([Cell::from_f64(want)].as_slice()), "sign({x})");
}
}
#[test]
fn sign_is_none_until_warm() {
// Cold input -> None (C8 warm-up gate), like every std cell.
let mut node = Sign::new();
let inputs = vec![AnyColumn::with_capacity(ScalarKind::F64, 1)];
assert_eq!(node.eval(Ctx::new(&inputs, Timestamp(0))), None);
}
#[test]
fn input_slot_is_named_value() {
let names: Vec<String> =
Sign::builder().schema().inputs.iter().map(|p| p.name.clone()).collect();
assert_eq!(names, ["value"]);
}
}
+5 -3
View File
@@ -20,7 +20,7 @@
use crate::{
Abs, Add, And, Bias, CarryCost, Const, ConstantCost, Delay, Div, Ema, EqConst, FixedStop, Gt,
Latch, LongOnly, Max, Min, Mul, PositionManagement, Resample, RollingMax, RollingMin, Scale,
SessionFrankfurt, Sizer, Sma, Sqrt, Sub, VolSlippageCost,
Select, SessionFrankfurt, Sign, Sizer, Sma, Sqrt, Sub, VolSlippageCost,
};
use aura_core::PrimitiveBuilder;
@@ -81,7 +81,9 @@ std_vocabulary_roster! {
"RollingMax" => RollingMax,
"RollingMin" => RollingMin,
"Scale" => Scale,
"Select" => Select,
"SessionFrankfurt" => SessionFrankfurt,
"Sign" => Sign,
"Sizer" => Sizer,
"SMA" => Sma,
"Sqrt" => Sqrt,
@@ -130,7 +132,7 @@ mod tests {
assert!(!std_vocabulary_types().contains(&"LinComb")); // construction-arg node
assert!(!std_vocabulary_types().contains(&"Recorder")); // sink
assert!(!std_vocabulary_types().contains(&"nope"));
// count guard: pins the roster at exactly 29 entries
assert_eq!(std_vocabulary_types().len(), 29);
// count guard: pins the roster at exactly 31 entries
assert_eq!(std_vocabulary_types().len(), 31);
}
}