Struct NewtonRaphsonSolver 

pub struct NewtonRaphsonSolver { /* private fields */ }

Newton-Raphson solver for systems of nonlinear equations

This solver can handle:

• Square systems (equations == variables)
• Under-constrained systems (equations < variables) - uses least squares
• Over-constrained systems (equations > variables) - uses least squares

The solver uses adaptive damping and regularization for numerical stability.

Implementations

impl NewtonRaphsonSolver

pub fn new(compiled: CompiledSystem) -> Self

Create a new Newton-Raphson solver with adaptive parameters

Parameters are automatically adjusted based on system type:

• Over-constrained systems get more iterations, relaxed tolerance, conservative damping
• Normal systems use standard parameters for fast convergence

Arguments

• compiled - Compiled system of equations (each should evaluate to 0 at solution)

Examples found in repository

examples/cad_circle_intersection.rs (line 46)

fn main() {
    // Two circles with radius 3 centered at (0, 0) and (4, 0).
    let x = Exp::var("x");
    let y = Exp::var("y");

    let eq1 = circle_eq(&x, &y, 0.0, 0.0, 3.0);
    let eq2 = circle_eq(&x, &y, 4.0, 0.0, 3.0);

    let compiled = Compiler::compile(&[eq1, eq2]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("x".to_string(), 2.0);
    initial.insert("y".to_string(), 1.0);

    let solution = solver.solve(initial).expect("solve failed");
    let x_sol = solution.values.get("x").copied().unwrap();
    let y_sol = solution.values.get("y").copied().unwrap();

    println!("intersection: x={:.6}, y={:.6}", x_sol, y_sol);
}

examples/circuit_voltage_divider.rs (line 49)

fn main() {
    // Simple resistive divider with explicit currents.
    let vout = Exp::var("vout");
    let i1 = Exp::var("i1");
    let i2 = Exp::var("i2");

    let vin = 12.0;
    let r1 = 1_000.0;
    let r2 = 2_000.0;

    // (Vin - Vout) / R1 = I1
    let eq1 = Exp::sub(
        Exp::div(Exp::sub(Exp::val(vin), vout.clone()), Exp::val(r1)),
        i1.clone(),
    );
    // Vout / R2 = I2
    let eq2 = Exp::sub(Exp::div(vout.clone(), Exp::val(r2)), i2.clone());
    // KCL: I1 = I2
    let eq3 = Exp::sub(i1.clone(), i2.clone());

    let compiled = Compiler::compile(&[eq1, eq2, eq3]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("vout".to_string(), 8.0);
    initial.insert("i1".to_string(), 0.004);
    initial.insert("i2".to_string(), 0.004);

    let solution = solver.solve(initial).expect("solve failed");
    let vout_sol = solution.values.get("vout").copied().unwrap();
    let i_sol = solution.values.get("i1").copied().unwrap();

    println!("vout={:.6} V, current={:.6} A", vout_sol, i_sol);
}

examples/circuit_diode.rs (line 51)

fn main() {
    // Series resistor + diode with Shockley equation.
    let i = Exp::var("i");
    let vd = Exp::var("vd");

    let vs = 5.0;
    let r = 1_000.0;
    let isat = 1e-12;
    let n = 1.0;
    let vt = 0.02585;

    // KVL: Vs - I*R - Vd = 0
    let kvl = Exp::sub(Exp::sub(Exp::val(vs), Exp::mul(i.clone(), Exp::val(r))), vd.clone());

    // I - Is * (exp(Vd / (n*Vt)) - 1) = 0
    let exp_arg = Exp::div(vd.clone(), Exp::val(n * vt));
    let diode_i = Exp::mul(
        Exp::val(isat),
        Exp::sub(Exp::exp(exp_arg), Exp::val(1.0)),
    );
    let diode_eq = Exp::sub(i.clone(), diode_i);

    let compiled = Compiler::compile(&[kvl, diode_eq]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("i".to_string(), 0.005);
    initial.insert("vd".to_string(), 0.7);

    let solution = solver.solve(initial).expect("solve failed");
    let i_sol = solution.values.get("i").copied().unwrap();
    let vd_sol = solution.values.get("vd").copied().unwrap();

    println!("diode: i={:.6} A, vd={:.6} V", i_sol, vd_sol);
}

pub fn new_with_variables( compiled: CompiledSystem, variables: &[&str], ) -> Result<Self, SolverError>

Create a solver while specifying which variables to solve for.

Variables not listed here are treated as fixed parameters and must be provided in the initial guess.

Examples found in repository

examples/cad_segment_horizontal.rs (line 47)

fn main() {
    // Find point B given fixed A, fixed length, and horizontal constraint.
    let ax = Exp::var("ax");
    let ay = Exp::var("ay");
    let bx = Exp::var("bx");
    let by = Exp::var("by");

    let length = 5.0;
    let y_target = 2.0;

    let dx = Exp::sub(bx.clone(), ax.clone());
    let dy = Exp::sub(by.clone(), ay.clone());
    let length_eq = Exp::sub(
        Exp::add(Exp::power(dx, 2.0), Exp::power(dy, 2.0)),
        Exp::val(length * length),
    );
    let horizontal_eq = Exp::sub(by.clone(), Exp::val(y_target));

    let compiled = Compiler::compile(&[length_eq, horizontal_eq]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new_with_variables(compiled, &["bx", "by"])
        .expect("solver init failed");

    let mut initial = HashMap::new();
    initial.insert("ax".to_string(), 1.0);
    initial.insert("ay".to_string(), 2.0);
    initial.insert("bx".to_string(), 6.0);
    initial.insert("by".to_string(), 2.0);

    let solution = solver.solve(initial).expect("solve failed");
    let bx_sol = solution.values.get("bx").copied().unwrap();
    let by_sol = solution.values.get("by").copied().unwrap();

    println!("B = ({:.6}, {:.6})", bx_sol, by_sol);
}

pub fn try_with_equation_traces( self, traces: Vec<Option<EquationTrace>>, ) -> Result<Self, SolverError>

Attach metadata describing the origin of each equation in the system

pub fn with_equation_traces(self, traces: Vec<Option<EquationTrace>>) -> Self

Attach metadata describing the origin of each equation in the system

pub fn trace_for_equation( &self, equation_index: usize, ) -> Option<&EquationTrace>

Fetch trace metadata for a specific equation, if available

pub fn with_max_iterations(self, max_iterations: usize) -> Self

Override the maximum number of iterations

pub fn with_tolerance(self, tolerance: f64) -> Self

Override the convergence tolerance

pub fn with_damping(self, damping_factor: f64) -> Self

Override the damping factor (clamped to [0.1, 1.0] for stability)

pub fn with_regularization(self, regularization: f64) -> Self

Override the base regularization parameter used when the system is ill-conditioned

pub fn solve( &self, initial_guess: HashMap<String, f64>, ) -> Result<Solution, SolverError>

Solve the system using standard Newton-Raphson method

Examples found in repository

examples/cad_circle_intersection.rs (line 52)

fn main() {
    // Two circles with radius 3 centered at (0, 0) and (4, 0).
    let x = Exp::var("x");
    let y = Exp::var("y");

    let eq1 = circle_eq(&x, &y, 0.0, 0.0, 3.0);
    let eq2 = circle_eq(&x, &y, 4.0, 0.0, 3.0);

    let compiled = Compiler::compile(&[eq1, eq2]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("x".to_string(), 2.0);
    initial.insert("y".to_string(), 1.0);

    let solution = solver.solve(initial).expect("solve failed");
    let x_sol = solution.values.get("x").copied().unwrap();
    let y_sol = solution.values.get("y").copied().unwrap();

    println!("intersection: x={:.6}, y={:.6}", x_sol, y_sol);
}

examples/circuit_voltage_divider.rs (line 56)

fn main() {
    // Simple resistive divider with explicit currents.
    let vout = Exp::var("vout");
    let i1 = Exp::var("i1");
    let i2 = Exp::var("i2");

    let vin = 12.0;
    let r1 = 1_000.0;
    let r2 = 2_000.0;

    // (Vin - Vout) / R1 = I1
    let eq1 = Exp::sub(
        Exp::div(Exp::sub(Exp::val(vin), vout.clone()), Exp::val(r1)),
        i1.clone(),
    );
    // Vout / R2 = I2
    let eq2 = Exp::sub(Exp::div(vout.clone(), Exp::val(r2)), i2.clone());
    // KCL: I1 = I2
    let eq3 = Exp::sub(i1.clone(), i2.clone());

    let compiled = Compiler::compile(&[eq1, eq2, eq3]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("vout".to_string(), 8.0);
    initial.insert("i1".to_string(), 0.004);
    initial.insert("i2".to_string(), 0.004);

    let solution = solver.solve(initial).expect("solve failed");
    let vout_sol = solution.values.get("vout").copied().unwrap();
    let i_sol = solution.values.get("i1").copied().unwrap();

    println!("vout={:.6} V, current={:.6} A", vout_sol, i_sol);
}

examples/circuit_diode.rs (line 57)

fn main() {
    // Series resistor + diode with Shockley equation.
    let i = Exp::var("i");
    let vd = Exp::var("vd");

    let vs = 5.0;
    let r = 1_000.0;
    let isat = 1e-12;
    let n = 1.0;
    let vt = 0.02585;

    // KVL: Vs - I*R - Vd = 0
    let kvl = Exp::sub(Exp::sub(Exp::val(vs), Exp::mul(i.clone(), Exp::val(r))), vd.clone());

    // I - Is * (exp(Vd / (n*Vt)) - 1) = 0
    let exp_arg = Exp::div(vd.clone(), Exp::val(n * vt));
    let diode_i = Exp::mul(
        Exp::val(isat),
        Exp::sub(Exp::exp(exp_arg), Exp::val(1.0)),
    );
    let diode_eq = Exp::sub(i.clone(), diode_i);

    let compiled = Compiler::compile(&[kvl, diode_eq]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new(compiled);

    let mut initial = HashMap::new();
    initial.insert("i".to_string(), 0.005);
    initial.insert("vd".to_string(), 0.7);

    let solution = solver.solve(initial).expect("solve failed");
    let i_sol = solution.values.get("i").copied().unwrap();
    let vd_sol = solution.values.get("vd").copied().unwrap();

    println!("diode: i={:.6} A, vd={:.6} V", i_sol, vd_sol);
}

examples/cad_segment_horizontal.rs (line 56)

fn main() {
    // Find point B given fixed A, fixed length, and horizontal constraint.
    let ax = Exp::var("ax");
    let ay = Exp::var("ay");
    let bx = Exp::var("bx");
    let by = Exp::var("by");

    let length = 5.0;
    let y_target = 2.0;

    let dx = Exp::sub(bx.clone(), ax.clone());
    let dy = Exp::sub(by.clone(), ay.clone());
    let length_eq = Exp::sub(
        Exp::add(Exp::power(dx, 2.0), Exp::power(dy, 2.0)),
        Exp::val(length * length),
    );
    let horizontal_eq = Exp::sub(by.clone(), Exp::val(y_target));

    let compiled = Compiler::compile(&[length_eq, horizontal_eq]).expect("compile failed");
    let solver = NewtonRaphsonSolver::new_with_variables(compiled, &["bx", "by"])
        .expect("solver init failed");

    let mut initial = HashMap::new();
    initial.insert("ax".to_string(), 1.0);
    initial.insert("ay".to_string(), 2.0);
    initial.insert("bx".to_string(), 6.0);
    initial.insert("by".to_string(), 2.0);

    let solution = solver.solve(initial).expect("solve failed");
    let bx_sol = solution.values.get("bx").copied().unwrap();
    let by_sol = solution.values.get("by").copied().unwrap();

    println!("B = ({:.6}, {:.6})", bx_sol, by_sol);
}

pub fn solve_with_line_search( &self, initial_guess: HashMap<String, f64>, ) -> Result<Solution, SolverError>

Solve the system using Newton-Raphson with line search

Line search helps improve convergence robustness by automatically finding good step sizes, especially useful for difficult systems.