Shore up uncertainty testing.

.gitignore

@@ -1,3 +1,5 @@
+.DS_Store
+
 # Generated by Cargo
 # will have compiled files and executables
 debug/

DEMO-EXAMPLES.md

@@ -0,0 +1,309 @@
+# Goth Demo Examples - Planned Simulation & Numerical Methods
+
+This document outlines a comprehensive list of example/demo code that would showcase Goth's capabilities for scientific computing, numerical simulation, and computational mathematics.
+
+## Category 1: Classic Numerical Methods
+
+### 1.1 Newton-Raphson Method
+- **Purpose**: Root-finding algorithm showcase
+- **Key Features**:
+  - First-order derivative computation
+  - Iterative convergence criteria
+  - Float precision handling
+  - Error tolerance checking
+- **Example Use Cases**: 
+  - Finding cube roots
+  - Solving nonlinear equations
+  - Demonstrating uncertainty propagation in numerical methods
+
+### 1.2 Runge-Kutta Integration (RK4)
+- **Purpose**: Ordinary Differential Equation (ODE) solver
+- **Key Features**:
+  - Four-stage explicit integration
+  - Step size adaptive behavior
+  - State vector management
+  - Temporal evolution
+- **Example Use Cases**:
+  - Projectile motion with drag
+  - Pendulum dynamics
+  - Population growth models
+  - Spring-mass systems
+
+### 1.3 Monte Carlo Methods
+- **Purpose**: Probabilistic simulation and numerical integration
+- **Key Features**:
+  - Random sampling
+  - Statistical aggregation
+  - Uncertainty quantification
+  - Convergence monitoring
+- **Example Use Cases**:
+  - Integration by random sampling
+  - Pi estimation
+  - Portfolio risk analysis
+  - Particle transport simulation
+
+### 1.4 Quadrature Methods (Numerical Integration)
+- **Purpose**: Computing definite integrals numerically
+- **Key Features**:
+  - Simpson's rule
+  - Gaussian quadrature
+  - Adaptive refinement
+- **Example Use Cases**:
+  - Arc length calculation
+  - Work integrals
+  - Probability distributions
+
+## Category 2: Partial Differential Equations (PDEs)
+
+### 2.1 Finite Difference Methods
+- **Purpose**: Discretizing and solving PDEs
+- **Key Features**:
+  - Grid-based computation
+  - Boundary condition handling
+  - Stencil operations
+  - Iterative solvers
+
+#### 2.1.1 Laplace Equation (Electrostatics/Heat Diffusion)
+- **Purpose**: Classic boundary value problem
+- **Key Features**:
+  - 2D grid iteration
+  - Relaxation methods (Jacobi, Gauss-Seidel)
+  - Convergence criteria
+- **Physics**: Electric potential, steady-state heat distribution
+
+#### 2.1.2 Poisson Equation (Inhomogeneous)
+- **Purpose**: Extension of Laplace with source terms
+- **Key Features**:
+  - Source term evaluation
+  - Iterative refinement
+  - Boundary conditions
+- **Physics**: Gravitational potential, steady-state heat with sources
+
+#### 2.1.3 Advection Equation
+- **Purpose**: Transport phenomena
+- **Key Features**:
+  - First-order hyperbolic PDE
+  - Characteristic-based methods
+  - Flux limiters for stability
+- **Physics**: Scalar transport, pollutant diffusion, flow advection
+
+#### 2.1.4 Wave Equation
+- **Purpose**: Hyperbolic wave propagation
+- **Key Features**:
+  - Second-order temporal integration
+  - Stability conditions (CFL)
+  - Boundary reflections
+- **Physics**: Acoustic waves, electromagnetic waves, vibrating strings
+
+#### 2.1.5 Burgers' Equation
+- **Purpose**: Nonlinear convection + diffusion
+- **Key Features**:
+  - Shock formation
+  - Cole-Hopf transformation
+  - Artificial diffusion
+- **Physics**: Shock waves, traffic flow, turbulence modeling
+
+### 2.2 Finite Element Method (FEA)
+- **Purpose**: Variational approach to PDEs
+- **Key Features**:
+  - Basis function construction
+  - Assembly of stiffness matrix
+  - Sparse linear system solving
+  - Post-processing (stress/strain)
+- **Example Problems**:
+  - 1D bar under load (tension/compression)
+  - 2D plate bending
+  - Thermal analysis
+  - Modal analysis (eigenvalues)
+
+### 2.3 Computational Fluid Dynamics (CFD)
+- **Purpose**: Simulating fluid flow
+- **Key Features**:
+  - Navier-Stokes equation discretization
+  - Pressure-velocity coupling (SIMPLE algorithm)
+  - Turbulence modeling (k-ε models)
+  - Incompressible flow assumptions
+
+#### 2.3.1 Incompressible Flow Examples
+- Lid-driven cavity flow
+- Channel flow with obstacles
+- Flow around a cylinder
+- Thermal convection
+
+#### 2.3.2 Shallow Water Equations
+- **Purpose**: Simplified 2D fluid equations
+- **Features**:
+  - Surface height tracking
+  - Velocity fields
+  - Reduced dimensionality
+- **Applications**: Dam break simulation, tsunami modeling
+
+## Category 3: Linear Algebra & Eigenvalue Problems
+
+### 3.1 Eigenvalue/Eigenvector Computation
+- **Purpose**: Finding characteristic modes and values
+- **Key Features**:
+  - Power iteration method
+  - Inverse iteration
+  - QR algorithm
+  - Rayleigh quotient
+- **Example Use Cases**:
+  - Structural natural frequencies
+  - Stability analysis
+  - Principal component analysis
+  - Graph spectral methods
+
+### 3.2 Linear System Solvers
+- **Purpose**: Solving Ax = b
+- **Key Features**:
+  - Gaussian elimination
+  - LU decomposition
+  - Iterative methods (CG, GMRES)
+  - Sparse matrix handling
+- **Example Use Cases**:
+  - FEA system assembly
+  - CFD pressure correction
+  - Circuit analysis
+
+## Category 4: Optimization
+
+### 4.1 Gradient Descent Variants
+- **Purpose**: Unconstrained optimization
+- **Key Features**:
+  - Steepest descent
+  - Conjugate gradient
+  - BFGS quasi-Newton method
+  - Learning rate scheduling
+- **Example Use Cases**:
+  - Function minimization
+  - Machine learning parameter fitting
+  - Inverse problems
+
+### 4.2 Constrained Optimization
+- **Purpose**: Optimization with constraints
+- **Key Features**:
+  - Penalty methods
+  - Lagrange multipliers
+  - Sequential quadratic programming
+- **Example Use Cases**:
+  - Portfolio optimization
+  - Shape optimization
+  - Control problems
+
+## Category 5: Interpolation & Approximation
+
+### 5.1 Polynomial Interpolation
+- **Purpose**: Function reconstruction from points
+- **Key Features**:
+  - Lagrange interpolation
+  - Newton divided differences
+  - Spline interpolation (cubic, B-splines)
+- **Example Use Cases**:
+  - Data smoothing
+  - Function approximation
+  - Mesh refinement
+
+### 5.2 Least Squares Fitting
+- **Purpose**: Finding best-fit functions
+- **Key Features**:
+  - Linear least squares
+  - Nonlinear fitting
+  - Regularization (Ridge, LASSO)
+- **Example Use Cases**:
+  - Curve fitting
+  - Inverse problems
+  - Data analysis
+
+## Category 6: Statistical Methods
+
+### 6.1 Bayesian Inference
+- **Purpose**: Probabilistic inference
+- **Key Features**:
+  - Prior/likelihood/posterior
+  - MCMC sampling
+  - Variational inference
+- **Example Use Cases**:
+  - Parameter estimation
+  - Model selection
+  - Uncertainty quantification
+
+### 6.2 Uncertainty Propagation
+- **Purpose**: Tracking error through computations
+- **Key Features**:
+  - Dual number arithmetic
+  - Adjoint methods
+  - Sensitivity analysis
+  - Forward/reverse mode AD
+- **Example Use Cases**:
+  - Measurement error analysis
+  - Model parameter sensitivity
+  - Risk assessment
+
+## Category 7: Specialized Simulation
+
+### 7.1 N-Body Simulations
+- **Purpose**: Particle dynamics
+- **Key Features**:
+  - Pairwise force computation
+  - Time stepping
+  - Spatial acceleration structures
+  - Energy conservation monitoring
+- **Example Use Cases**:
+  - Gravitational N-body
+  - Molecular dynamics
+  - Particle systems
+
+### 7.2 Finite Difference Time Domain (FDTD)
+- **Purpose**: Electromagnetic wave simulation
+- **Key Features**:
+  - Yee grid discretization
+  - Staggered grids
+  - PML boundary conditions
+- **Example Use Cases**:
+  - Antenna design
+  - Photonic devices
+  - Waveguide analysis
+
+### 7.3 Lattice Boltzmann Method (LBM)
+- **Purpose**: Alternative to direct PDE solving
+- **Key Features**:
+  - Distribution functions
+  - Collision operators
+  - Streaming step
+- **Example Use Cases**:
+  - Complex flow geometry
+  - Multiphase flows
+  - Reactive transport
+
+## Suggested Priority Examples (Tier 1)
+
+These would be the best starting points to showcase Goth's capabilities:
+
+1. **Newton-Raphson for Square Root** - Simple, demonstrates iterative methods and error handling
+2. **Simple ODE with Runge-Kutta** - Projectile motion or pendulum
+3. **2D Laplace Solver** - Heat diffusion on a 2D grid
+4. **Monte Carlo Pi Estimation** - Shows randomness and aggregation
+5. **Simple Linear System Solver** - 3x3 or 5x5 system with Gaussian elimination
+6. **1D Wave Equation** - Shows spatiotemporal discretization
+7. **Eigenvalue Power Iteration** - Simple symmetric matrix case
+8. **Gradient Descent Optimization** - Minimize a simple 2D function
+
+## Key Technical Requirements for Examples
+
+- Clear variable naming showing Goth's type system
+- Uncertainty/dual number demonstrations (AD support)
+- Performance characteristics (iteration counts, convergence rates)
+- Comparison with analytical solutions where available
+- Comments explaining the numerical method
+- Output formatting for visualization-ready data
+- Memory-efficient handling of arrays/vectors
+- Floating-point precision considerations
+
+## Platform Considerations
+
+- Performance benchmarks (C vs interpreted)
+- Memory usage patterns
+- Compilation time
+- Ease of visualization (CSV/JSON output)
+- Integration with Python/plotting tools (matplotlib, Paraview)
+