qualia_core_db/specialized_libs/engineering_analysis/

mechanical.rs

use super::*;

/// Mechanical analyzer for mechanical engineering analysis
pub struct MechanicalAnalyzer {
    kinematics: Kinematics,
    dynamics: Dynamics,
    mechanism_analysis: MechanismAnalysis,
    machine_design: MachineDesign,
    /// Phase 2 physics-simulation library for coupled mechanical dynamics.
    physics_simulation: Option<Arc<Mutex<PhysicsSimulationLibrary>>>,
}

/// Results of a kinematic time-history analysis (constant acceleration).
/// Positions, velocities and accelerations are evaluated at each requested time
/// step using the standard SUVAT equations.
#[derive(Debug, Clone, PartialEq)]
pub struct KinematicsResults {
    /// Position x(t) = x₀ + v₀·t + ½·a·t² at each time step.
    pub positions: Vec<f64>,
    /// Velocity v(t) = v₀ + a·t at each time step.
    pub velocities: Vec<f64>,
    /// Acceleration a(t) = a (constant) at each time step.
    pub accelerations: Vec<f64>,
    /// The time steps the analysis was evaluated at.
    pub time_steps: Vec<f64>,
}

/// Results of a dynamics time-history analysis (Newton's second law, F = m·a).
/// Energy is reported in the constant-applied-force potential convention so that
/// total mechanical energy is conserved: `PE = −F·x` and
/// `KE + PE = ½·m·v₀²` (constant).
#[derive(Debug, Clone, PartialEq)]
pub struct DynamicsResults {
    /// Position x(t) = ½·a·t² + v₀·t at each time step.
    pub positions: Vec<f64>,
    /// Velocity v(t) = v₀ + a·t at each time step.
    pub velocities: Vec<f64>,
    /// Acceleration a = F/m (constant) at each time step.
    pub accelerations: Vec<f64>,
    /// Kinetic energy ½·m·v² at the final time step (J).
    pub kinetic_energy: f64,
    /// Potential energy −F·x at the final time step (J), in the constant-force
    /// field convention so that KE + PE is conserved.
    pub potential_energy: f64,
    /// Total mechanical energy = KE + PE (J), conserved across the history.
    pub total_energy: f64,
    /// The time steps the analysis was evaluated at.
    pub time_steps: Vec<f64>,
}

/// Kinematics
pub struct Kinematics {
    position_analysis: PositionAnalysis,
    velocity_analysis: VelocityAnalysis,
    acceleration_analysis: AccelerationAnalysis,
}

/// Position analysis
#[derive(Debug, Clone)]
pub struct PositionAnalysis {
    pub mechanism_type: MechanismType,
    pub joint_coordinates: Vec<f64>,
    pub link_lengths: Vec<f64>,
}

/// Mechanism types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum MechanismType {
    FourBar,
    SliderCrank,
    CamFollower,
    GearTrain,
    Custom(String),
}

/// Velocity analysis
#[derive(Debug, Clone)]
pub struct VelocityAnalysis {
    pub angular_velocities: Vec<f64>,
    pub linear_velocities: Vec<f64>,
    pub velocity_ratios: Vec<f64>,
}

/// Acceleration analysis
#[derive(Debug, Clone)]
pub struct AccelerationAnalysis {
    pub angular_accelerations: Vec<f64>,
    pub linear_accelerations: Vec<f64>,
    pub jerk: Vec<f64>,
}

/// Dynamics
pub struct Dynamics {
    force_analysis: ForceAnalysis,
    inertia_analysis: InertiaAnalysis,
    energy_analysis: EnergyAnalysis,
}

/// Force analysis
#[derive(Debug, Clone)]
pub struct ForceAnalysis {
    pub applied_forces: Vec<f64>,
    pub reaction_forces: Vec<f64>,
    pub internal_forces: Vec<f64>,
}

/// Inertia analysis
#[derive(Debug, Clone)]
pub struct InertiaAnalysis {
    pub masses: Vec<f64>,
    pub moments_of_inertia: Vec<f64>,
    pub products_of_inertia: Vec<f64>,
}

/// Energy analysis
#[derive(Debug, Clone)]
pub struct EnergyAnalysis {
    pub kinetic_energy: f64,
    pub potential_energy: f64,
    pub total_energy: f64,
    pub power: f64,
}

/// Mechanism analysis
pub struct MechanismAnalysis {
    synthesis: MechanismSynthesis,
    analysis: MechanismAnalysisEngine,
    optimization: MechanismOptimization,
}

/// Mechanism synthesis
#[derive(Debug, Clone)]
pub struct MechanismSynthesis {
    pub synthesis_type: SynthesisType,
    pub design_parameters: Vec<f64>,
    pub constraints: Vec<Constraint>,
}

/// Synthesis types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum SynthesisType {
    FunctionGeneration,
    PathGeneration,
    MotionGeneration,
}

/// Mechanism analysis engine
#[derive(Debug, Clone)]
pub struct MechanismAnalysisEngine {
    pub analysis_type: AnalysisType,
    pub analysis_method: AnalysisMethod,
}

/// Analysis methods
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum AnalysisMethod {
    Graphical,
    Analytical,
    Numerical,
}

/// Mechanism optimization
#[derive(Debug, Clone)]
pub struct MechanismOptimization {
    pub optimization_algorithm: OptimizationAlgorithm,
    pub objective_function: ObjectiveFunction,
    pub design_variables: Vec<DesignVariable>,
}

/// Optimization algorithms
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum OptimizationAlgorithm {
    GeneticAlgorithm,
    ParticleSwarm,
    SimulatedAnnealing,
    GradientDescent,
}

/// Objective functions
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ObjectiveFunction {
    MinimizeError,
    MaximizeEfficiency,
    MinimizeWeight,
    MaximizeStiffness,
}

/// Design variables
#[derive(Debug, Clone)]
pub struct DesignVariable {
    pub variable_name: String,
    pub variable_type: VariableType,
    pub bounds: (f64, f64),
}

/// Variable types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum VariableType {
    Length,
    Angle,
    Mass,
    Stiffness,
}

/// Machine design
pub struct MachineDesign {
    component_design: ComponentDesign,
    assembly_design: AssemblyDesign,
    tolerance_analysis: ToleranceAnalysis,
}

/// Component design
#[derive(Debug, Clone)]
pub struct ComponentDesign {
    pub component_type: ComponentType,
    pub design_parameters: HashMap<String, f64>,
    pub material_selection: MaterialSelection,
}

/// Component types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ComponentType {
    Shaft,
    Bearing,
    Gear,
    Spring,
    Fastener,
    Custom(String),
}

/// Material selection
#[derive(Debug, Clone)]
pub struct MaterialSelection {
    pub material_id: String,
    pub material_name: String,
    pub selection_criteria: Vec<SelectionCriterion>,
}

/// Selection criteria
#[derive(Debug, Clone)]
pub struct SelectionCriterion {
    pub criterion_name: String,
    pub criterion_weight: f64,
    pub required_value: f64,
}

/// Assembly design
#[derive(Debug, Clone)]
pub struct AssemblyDesign {
    pub assembly_type: AssemblyType,
    pub components: Vec<Component>,
    pub assembly_constraints: Vec<AssemblyConstraint>,
}

/// Assembly types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum AssemblyType {
    Fixed,
    Floating,
    Kinematic,
    Overconstrained,
}

/// Components
#[derive(Debug, Clone)]
pub struct Component {
    pub component_id: String,
    pub component_name: String,
    pub component_type: ComponentType,
    pub position: Vec<f64>,
    pub orientation: Vec<f64>,
}

/// Assembly constraints
#[derive(Debug, Clone)]
pub struct AssemblyConstraint {
    pub constraint_id: String,
    pub constraint_type: ConstraintType,
    pub constraint_parameters: HashMap<String, f64>,
}

/// Tolerance analysis
pub struct ToleranceAnalysis {
    pub tolerance_stackup: ToleranceStackup,
    pub statistical_tolerance: StatisticalTolerance,
    pub geometric_tolerance: GeometricTolerance,
}

/// Tolerance stackup
#[derive(Debug, Clone)]
pub struct ToleranceStackup {
    pub tolerance_type: ToleranceType,
    pub tolerance_values: Vec<f64>,
    pub stackup_result: f64,
}

/// Tolerance types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ToleranceType {
    WorstCase,
    Statistical,
    RootSumSquare,
}

/// Statistical tolerance
#[derive(Debug, Clone)]
pub struct StatisticalTolerance {
    pub distribution_type: DistributionType,
    pub mean: f64,
    pub standard_deviation: f64,
}

/// Distribution types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum DistributionType {
    Normal,
    Uniform,
    Triangular,
}

/// Geometric tolerance
#[derive(Debug, Clone)]
pub struct GeometricTolerance {
    pub tolerance_type: GeometricToleranceType,
    pub tolerance_value: f64,
    pub reference_features: Vec<String>,
}

/// Geometric tolerance types
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum GeometricToleranceType {
    Flatness,
    Straightness,
    Circularity,
    Cylindricity,
    Perpendicularity,
    Angularity,
    Parallelism,
    Position,
    Concentricity,
    Symmetry,
}
impl MechanicalAnalyzer {
    pub fn new() -> Self {
        Self {
            kinematics: Kinematics::new(),
            dynamics: Dynamics::new(),
            mechanism_analysis: MechanismAnalysis::new(),
            machine_design: MachineDesign::new(),
            physics_simulation: None,
        }
    }

    /// Attach the Phase 2 physics-simulation library for coupled dynamics.
    pub fn attach_physics_simulation(&mut self, lib: Option<Arc<Mutex<PhysicsSimulationLibrary>>>) {
        self.physics_simulation = lib;
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        self.kinematics.initialize()?;
        self.dynamics.initialize()?;
        self.mechanism_analysis.initialize()?;
        self.machine_design.initialize()?;
        Ok(())
    }

    pub fn validate_model(&self, model: &EngineeringModel) -> Result<(), EngineeringError> {
        if model.geometry.dimensions.is_empty() {
            return Err(EngineeringError::ValidationError(
                "Model must have dimensions".to_string(),
            ));
        }
        Ok(())
    }

    pub fn analyze(
        &mut self,
        _model: &EngineeringModel,
        _analysis_type: AnalysisType,
    ) -> Result<AnalysisResults, EngineeringError> {
        // NOT IMPLEMENTED — it must say so, never fabricate. The previous body returned a default
        // AnalysisResults (empty fields + a hardcoded safety_factor) while ignoring the model.
        // Real mechanical / thermal / fluid analysis over an arbitrary model needs a finite-element
        // / finite-volume solver (mesh assembly + solve), not yet built. (Axial structural analysis
        // IS implemented — see StructuralAnalyzer::analyze.)
        Err(EngineeringError::NotImplemented(
            "this analysis requires a finite-element/finite-volume solver over the model \
             (mesh assembly + solve), which is not implemented"
                .to_string(),
        ))
    }

    /// Basic kinematic time-history analysis with constant acceleration.
    ///
    /// For each time step `t`:
    /// - position(t) = x₀ + v₀·t + ½·a·t²
    /// - velocity(t) = v₀ + a·t
    /// - acceleration(t) = a (constant)
    pub fn analyze_kinematics(
        &mut self,
        initial_position: f64,
        initial_velocity: f64,
        acceleration: f64,
        time_steps: &[f64],
    ) -> Result<KinematicsResults, EngineeringError> {
        if time_steps.is_empty() {
            return Err(EngineeringError::InsufficientData(
                "time_steps must contain at least one value".to_string(),
            ));
        }

        let mut positions = Vec::with_capacity(time_steps.len());
        let mut velocities = Vec::with_capacity(time_steps.len());
        let mut accelerations = Vec::with_capacity(time_steps.len());

        for &t in time_steps {
            positions.push(initial_position + initial_velocity * t + 0.5 * acceleration * t * t);
            velocities.push(initial_velocity + acceleration * t);
            accelerations.push(acceleration);
        }

        Ok(KinematicsResults {
            positions,
            velocities,
            accelerations,
            time_steps: time_steps.to_vec(),
        })
    }

    /// Dynamics time-history analysis from Newton's second law (F = m·a).
    ///
    /// - acceleration a = force / mass (constant)
    /// - velocity(t) = v₀ + a·t
    /// - position(t) = ½·a·t² + v₀·t
    ///
    /// Energy is reported in the constant-applied-force potential convention
    /// (`PE = −F·x`) so that the total mechanical energy `KE + PE = ½·m·v₀²` is
    /// conserved across the whole history (verifiable in tests).
    pub fn analyze_dynamics(
        &mut self,
        mass: f64,
        force: f64,
        initial_velocity: f64,
        time_steps: &[f64],
    ) -> Result<DynamicsResults, EngineeringError> {
        if mass <= 0.0 {
            return Err(EngineeringError::ValidationError(
                "mass must be positive".to_string(),
            ));
        }
        if time_steps.is_empty() {
            return Err(EngineeringError::InsufficientData(
                "time_steps must contain at least one value".to_string(),
            ));
        }

        let acceleration = force / mass;
        let mut positions = Vec::with_capacity(time_steps.len());
        let mut velocities = Vec::with_capacity(time_steps.len());
        let mut accelerations = Vec::with_capacity(time_steps.len());

        for &t in time_steps {
            positions.push(0.5 * acceleration * t * t + initial_velocity * t);
            velocities.push(initial_velocity + acceleration * t);
            accelerations.push(acceleration);
        }

        // Final-step energies. With PE = −F·x, KE + PE = ½·m·v₀² (conserved).
        let v_final = *velocities.last().unwrap();
        let x_final = *positions.last().unwrap();
        let kinetic_energy = 0.5 * mass * v_final * v_final;
        let potential_energy = -force * x_final;
        let total_energy = kinetic_energy + potential_energy;

        Ok(DynamicsResults {
            positions,
            velocities,
            accelerations,
            kinetic_energy,
            potential_energy,
            total_energy,
            time_steps: time_steps.to_vec(),
        })
    }
}

impl Kinematics {
    pub fn new() -> Self {
        Self {
            position_analysis: PositionAnalysis::new(),
            velocity_analysis: VelocityAnalysis::new(),
            acceleration_analysis: AccelerationAnalysis::new(),
        }
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        Ok(())
    }

    /// Borrow the position-analysis sub-component.
    pub fn position_analysis(&self) -> &PositionAnalysis {
        &self.position_analysis
    }

    /// Mutably borrow the position-analysis sub-component.
    pub fn position_analysis_mut(&mut self) -> &mut PositionAnalysis {
        &mut self.position_analysis
    }

    /// Borrow the velocity-analysis sub-component.
    pub fn velocity_analysis(&self) -> &VelocityAnalysis {
        &self.velocity_analysis
    }

    /// Mutably borrow the velocity-analysis sub-component.
    pub fn velocity_analysis_mut(&mut self) -> &mut VelocityAnalysis {
        &mut self.velocity_analysis
    }

    /// Borrow the acceleration-analysis sub-component.
    pub fn acceleration_analysis(&self) -> &AccelerationAnalysis {
        &self.acceleration_analysis
    }

    /// Mutably borrow the acceleration-analysis sub-component.
    pub fn acceleration_analysis_mut(&mut self) -> &mut AccelerationAnalysis {
        &mut self.acceleration_analysis
    }
}

impl PositionAnalysis {
    pub fn new() -> Self {
        Self {
            mechanism_type: MechanismType::FourBar,
            joint_coordinates: Vec::new(),
            link_lengths: Vec::new(),
        }
    }
}

impl VelocityAnalysis {
    pub fn new() -> Self {
        Self {
            angular_velocities: Vec::new(),
            linear_velocities: Vec::new(),
            velocity_ratios: Vec::new(),
        }
    }
}

impl AccelerationAnalysis {
    pub fn new() -> Self {
        Self {
            angular_accelerations: Vec::new(),
            linear_accelerations: Vec::new(),
            jerk: Vec::new(),
        }
    }
}

impl Dynamics {
    pub fn new() -> Self {
        Self {
            force_analysis: ForceAnalysis::new(),
            inertia_analysis: InertiaAnalysis::new(),
            energy_analysis: EnergyAnalysis::new(),
        }
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        Ok(())
    }

    /// Borrow the force-analysis sub-component.
    pub fn force_analysis(&self) -> &ForceAnalysis {
        &self.force_analysis
    }

    /// Mutably borrow the force-analysis sub-component.
    pub fn force_analysis_mut(&mut self) -> &mut ForceAnalysis {
        &mut self.force_analysis
    }

    /// Borrow the inertia-analysis sub-component.
    pub fn inertia_analysis(&self) -> &InertiaAnalysis {
        &self.inertia_analysis
    }

    /// Mutably borrow the inertia-analysis sub-component.
    pub fn inertia_analysis_mut(&mut self) -> &mut InertiaAnalysis {
        &mut self.inertia_analysis
    }

    /// Borrow the energy-analysis sub-component.
    pub fn energy_analysis(&self) -> &EnergyAnalysis {
        &self.energy_analysis
    }

    /// Mutably borrow the energy-analysis sub-component.
    pub fn energy_analysis_mut(&mut self) -> &mut EnergyAnalysis {
        &mut self.energy_analysis
    }
}

impl ForceAnalysis {
    pub fn new() -> Self {
        Self {
            applied_forces: Vec::new(),
            reaction_forces: Vec::new(),
            internal_forces: Vec::new(),
        }
    }
}

impl InertiaAnalysis {
    pub fn new() -> Self {
        Self {
            masses: Vec::new(),
            moments_of_inertia: Vec::new(),
            products_of_inertia: Vec::new(),
        }
    }
}

impl EnergyAnalysis {
    pub fn new() -> Self {
        Self {
            kinetic_energy: 0.0,
            potential_energy: 0.0,
            total_energy: 0.0,
            power: 0.0,
        }
    }
}

impl MechanismAnalysis {
    pub fn new() -> Self {
        Self {
            synthesis: MechanismSynthesis::new(),
            analysis: MechanismAnalysisEngine::new(),
            optimization: MechanismOptimization::new(),
        }
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        Ok(())
    }

    /// Borrow the mechanism-synthesis sub-component.
    pub fn synthesis(&self) -> &MechanismSynthesis {
        &self.synthesis
    }

    /// Mutably borrow the mechanism-synthesis sub-component.
    pub fn synthesis_mut(&mut self) -> &mut MechanismSynthesis {
        &mut self.synthesis
    }

    /// Borrow the mechanism-analysis-engine sub-component.
    pub fn analysis(&self) -> &MechanismAnalysisEngine {
        &self.analysis
    }

    /// Mutably borrow the mechanism-analysis-engine sub-component.
    pub fn analysis_mut(&mut self) -> &mut MechanismAnalysisEngine {
        &mut self.analysis
    }

    /// Borrow the mechanism-optimization sub-component.
    pub fn optimization(&self) -> &MechanismOptimization {
        &self.optimization
    }

    /// Mutably borrow the mechanism-optimization sub-component.
    pub fn optimization_mut(&mut self) -> &mut MechanismOptimization {
        &mut self.optimization
    }
}

impl MechanismSynthesis {
    pub fn new() -> Self {
        Self {
            synthesis_type: SynthesisType::FunctionGeneration,
            design_parameters: Vec::new(),
            constraints: Vec::new(),
        }
    }
}

impl MechanismAnalysisEngine {
    pub fn new() -> Self {
        Self {
            analysis_type: AnalysisType::LinearStatic,
            analysis_method: AnalysisMethod::Numerical,
        }
    }
}

impl MechanismOptimization {
    pub fn new() -> Self {
        Self {
            optimization_algorithm: OptimizationAlgorithm::GeneticAlgorithm,
            objective_function: ObjectiveFunction::MinimizeError,
            design_variables: Vec::new(),
        }
    }
}

impl DesignVariable {
    pub fn new() -> Self {
        Self {
            variable_name: "length".to_string(),
            variable_type: VariableType::Length,
            bounds: (0.1, 10.0),
        }
    }
}

impl MachineDesign {
    pub fn new() -> Self {
        Self {
            component_design: ComponentDesign::new(),
            assembly_design: AssemblyDesign::new(),
            tolerance_analysis: ToleranceAnalysis::new(),
        }
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        Ok(())
    }

    /// Borrow the component-design sub-component.
    pub fn component_design(&self) -> &ComponentDesign {
        &self.component_design
    }

    /// Mutably borrow the component-design sub-component.
    pub fn component_design_mut(&mut self) -> &mut ComponentDesign {
        &mut self.component_design
    }

    /// Borrow the assembly-design sub-component.
    pub fn assembly_design(&self) -> &AssemblyDesign {
        &self.assembly_design
    }

    /// Mutably borrow the assembly-design sub-component.
    pub fn assembly_design_mut(&mut self) -> &mut AssemblyDesign {
        &mut self.assembly_design
    }

    /// Borrow the tolerance-analysis sub-component.
    pub fn tolerance_analysis(&self) -> &ToleranceAnalysis {
        &self.tolerance_analysis
    }

    /// Mutably borrow the tolerance-analysis sub-component.
    pub fn tolerance_analysis_mut(&mut self) -> &mut ToleranceAnalysis {
        &mut self.tolerance_analysis
    }
}

impl ComponentDesign {
    pub fn new() -> Self {
        Self {
            component_type: ComponentType::Shaft,
            design_parameters: HashMap::new(),
            material_selection: MaterialSelection::new(),
        }
    }
}

impl MaterialSelection {
    pub fn new() -> Self {
        Self {
            material_id: "steel_1".to_string(),
            material_name: "Steel".to_string(),
            selection_criteria: Vec::new(),
        }
    }
}

impl AssemblyDesign {
    pub fn new() -> Self {
        Self {
            assembly_type: AssemblyType::Fixed,
            components: Vec::new(),
            assembly_constraints: Vec::new(),
        }
    }
}

impl Component {
    pub fn new() -> Self {
        Self {
            component_id: "comp_1".to_string(),
            component_name: "Component".to_string(),
            component_type: ComponentType::Shaft,
            position: vec![0.0; 3],
            orientation: vec![0.0; 3],
        }
    }
}

impl AssemblyConstraint {
    pub fn new() -> Self {
        Self {
            constraint_id: "constraint_1".to_string(),
            constraint_type: ConstraintType::Fixed,
            constraint_parameters: HashMap::new(),
        }
    }
}

impl ToleranceAnalysis {
    pub fn new() -> Self {
        Self {
            tolerance_stackup: ToleranceStackup::new(),
            statistical_tolerance: StatisticalTolerance::new(),
            geometric_tolerance: GeometricTolerance::new(),
        }
    }

    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
        Ok(())
    }
}

impl ToleranceStackup {
    pub fn new() -> Self {
        Self {
            tolerance_type: ToleranceType::WorstCase,
            tolerance_values: Vec::new(),
            stackup_result: 0.0,
        }
    }
}

impl StatisticalTolerance {
    pub fn new() -> Self {
        Self {
            distribution_type: DistributionType::Normal,
            mean: 0.0,
            standard_deviation: 0.1,
        }
    }
}

impl GeometricTolerance {
    pub fn new() -> Self {
        Self {
            tolerance_type: GeometricToleranceType::Flatness,
            tolerance_value: 0.01,
            reference_features: Vec::new(),
        }
    }
}