ApprenticeFoundryMentorModeler 24.0.0

Foundry Mentor Modeler

Advanced knowledge modeling framework with intelligent unit system for engineering applications

🚀 What is Foundry Mentor Modeler?

Foundry Mentor Modeler is a powerful .NET library that provides intelligent parameter modeling, formula evaluation, and unit-aware calculations for engineering and scientific applications. It enables developers to create sophisticated models with automatic unit handling, dependency tracking, and dynamic formula evaluation.

✨ Key Features

🧮 Intelligent Parameter System

• Dynamic Formula Evaluation: Create parameters with complex formulas that automatically resolve dependencies
• Unit-Aware Calculations: Built-in support for 15+ unit families with automatic type safety
• Dependency Tracking: Automatic detection and management of parameter relationships
• Circular Reference Detection: Built-in protection against infinite evaluation loops

📐 Advanced Unit System Integration

• 39+ Unit Families: Length, Distance, Angle, Bearing, Time, Duration, Mass, Force, Temperature, Voltage, and more
• Dual Family Pattern: Scale-optimized families (Length/Distance, Angle/Bearing, Time/Duration)
• Mixed Unit Support: Imperial, Metric, and specialized engineering units across 6 unit systems
• Type-Safe Operations: Prevents invalid unit conversions (e.g., adding angles to lengths)
• Dynamic Unit Detection: Automatically creates correct MeasuredValue types

🔗 Knowledge Modeling

• Hierarchical Instances: Create complex models with parent-child relationships
• Component Systems: Build reusable components with subcomponent relationships
• Reference Resolution: Sophisticated reference system for accessing model data
• Persistence Support: Save and load model states

📦 Installation

NuGet Package Manager

Install-Package FoundryMentorModeler

.NET CLI

dotnet add package FoundryMentorModeler

PackageReference

<PackageReference Include="FoundryMentorModeler" Version="1.0.0" />

🏃‍♂️ Quick Start

Basic Parameter Creation

using FoundryMentorModeler.Model;

// Create a model instance
var robot = new KnInstance("Robot");

// Add parameters with units
var speed = robot.Parameter("maxSpeed", 2.5, "m/s");
var weight = robot.Parameter("weight", 15.0, "kg"); 
var angle = robot.Parameter("heading", 45.0, "deg");

Formula-Based Parameters

// Create calculated parameters
var distance = robot.Parameter("distance", 0.0, "m");
var time = robot.Parameter("time", 0.0, "s");

// Add formula that references other parameters
var avgSpeed = robot.Parameter("avgSpeed", 0.0, "m/s");
avgSpeed.ApplyFormula("distance / time", UnitSystem.Default);

// Set values and watch automatic calculation
distance.SetValue(100.0); // 100 meters
time.SetValue(40.0);      // 40 seconds
// avgSpeed automatically becomes 2.5 m/s

Dual Family Pattern Usage

// Use appropriate family for scale context
var robot = new KnInstance("AutonomousRobot");

// Engineering measurements (Length family - meter base)
var sensorRange = robot.Parameter("sensorRange", 5.0, "m");      // → Length family
var wheelDiameter = robot.Parameter("wheelDiameter", 15.0, "cm"); // → Length family

// Navigation measurements (Distance family - kilometer base)  
robot.ApplyFormula("missionDistance", "ASDISTANCE(25, 'km')");    // → Distance family
robot.ApplyFormula("waypointGap", "ASDISTANCE(500, 'm')");       // → Distance family

// Same input units, different optimized scales:
Console.WriteLine(sensorRange.BaseValue());    // 5.0 (meters - engineering scale)
Console.WriteLine(missionDistance.BaseValue()); // 25.0 (kilometers - geographic scale)

Hierarchical Models

// Create a complex system
var droneSystem = new KnInstance("DroneSystem");

// Add subsystems
var propulsion = droneSystem.AddMember(new KnInstance("Propulsion"));
var navigation = droneSystem.AddMember(new KnInstance("Navigation"));

// Add parameters to subsystems
propulsion.Parameter("thrust", 50.0, "N");
navigation.Parameter("altitude", 100.0, "m");
navigation.Parameter("gpsAccuracy", 2.0, "m");

// Compute all values recursively
droneSystem.ComputeAll<KnInstance>(deep: true);

🔧 Advanced Usage

Custom Formulas

var circle = new KnInstance("Circle");
circle.Parameter("radius", 5.0, "m");
circle.Parameter("area", 0.0, "m²");

// Complex formula with built-in functions
var area = circle.FindParameter("area");
area.ApplyFormula("3.14159 * radius * radius", UnitSystem.Default);

Unit System Integration

// Works with FoundryRulesAndUnits
var unitSystem = new UnitSystem();
unitSystem.Apply(UnitSystemType.SI);

// Parameters automatically use proper unit system
var force = new KnParameter("force", 9.8, "N");
var acceleration = new KnParameter("acceleration", 9.8, "m/s²");

Dependency Management

var circuit = new KnInstance("Circuit");
var voltage = circuit.Parameter("voltage", 12.0, "V");
var current = circuit.Parameter("current", 2.0, "A");
var power = circuit.Parameter("power", 0.0, "W");

power.ApplyFormula("voltage * current", UnitSystem.Default);

// Changing voltage automatically updates power
voltage.SetValue(24.0); // Power becomes 48W automatically

🔍 Architecture

Core Components

• KnInstance: Base knowledge instance with hierarchical capabilities
• KnParameter: Unit-aware parameter with formula evaluation
• Operator: Expression evaluation system with unit support
• OPResult: Type-safe result container with status tracking

Unit System Integration

Foundry Mentor Modeler integrates seamlessly with FoundryRulesAndUnits to provide:

• Automatic unit family detection
• Type-safe MeasuredValue creation
• Cross-unit conversion prevention
• Engineering-grade precision

📚 Documentation

Comprehensive Guides

• Unit System Documentation - Complete technical reference
• Parameter Unit Preservation - Unit handling best practices
• Migration Guide - Upgrading from older versions

API Reference

• Extension Methods - Helper method documentation
• Mathematical Functions - Built-in formula functions

🎯 Use Cases

Engineering Applications

• Robotics: Model robot parameters with unit-aware calculations
• Mechanical Design: Create assemblies with dimensional relationships
• Control Systems: Model feedback loops with parameter dependencies

Scientific Computing

• Physics Simulations: Unit-safe calculations across measurement types
• Data Analysis: Parameter relationships with automatic computation
• Experimental Design: Model experimental setups with validation

Industrial Systems

• Process Control: Model industrial processes with interconnected parameters
• Quality Assurance: Create measurement systems with tolerance checking
• System Integration: Build complex multi-component systems

🛠️ Requirements

• .NET 8.0 or later
• FoundryRulesAndUnits (automatically included)
• FoundryCore (automatically included)

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/SteveStrong/FoundryMentorModeler.git
cd FoundryMentorModeler
dotnet restore
dotnet build
dotnet test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆕 Recent Updates (October 2025)

🏗️ Dual Family Pattern - Complete Implementation

• ✅ Distance Family Fix: Resolved critical bug where Distance family couldn't accept 'm' units
• ✅ Cross-System Support: All 6 unit systems (SI, MKS, CGS, FPS, IPS, mmNs) now support dual families
• ✅ Scale-Optimized Architecture: Length/Distance, Angle/Bearing, Time/Duration dual families complete
• ✅ Parser Integration: Made Distance parser-accessible across all unit system specifications

🔧 Unit System Enhancements

• ✅ Comprehensive Validation: All Distance tests passing (7/7) with robust cross-system validation
• ✅ Base Unit Optimization: Engineering-scale (meters) vs Geographic-scale (kilometers) mathematics
• ✅ AS Function Support: ASDISTANCE(5, 'm'), ASBEARING(45, 'deg') for explicit family assignment
• ✅ Backward Compatibility: Existing code unchanged, new dual family features available

📋 Implementation Scope

• Distance Family: Now accepts all Length units (m, cm, ft, in, km, mi, etc.) in all 6 systems
• Dual Family Benefits: Context-appropriate base units (Length→meters, Distance→kilometers)
• Testing Framework: Comprehensive validation ensuring consistent behavior across all specifications

🆕 Recent Updates (September 2025)

🚀 Major Performance Optimization - 5-10x Faster Expression Evaluation

• ✅ TokenID-Based Dispatch: Replaced string comparisons with enum switching for 5-10x performance gain
• ✅ Unified Function Registry: Single source of truth for 50+ functions (Math, String, Date, Engineering)
• ✅ Token-Based Architecture: All operators now use consistent Operator(Token) constructor pattern
• ✅ Pure Evaluation: Clean separation between parsing and evaluation phases

🏗️ Architectural Transformation

• ✅ FunctionOperator Cleanup: Eliminated hundreds of lines of legacy code, removed "hard-to-read" patterns
• ✅ IUnitSystem Dependency Removal: Pure evaluation operators using static methods
• ✅ Parser-Evaluator Separation: Dedicated FunctionParser for clean architectural boundaries
• ✅ Memory Optimization: Eliminated Name.ToUpper() calls and string allocations in hot paths

📊 Proven Performance Improvements

• BinaryOperator: 8-10x faster arithmetic dispatch (+, -, *, /)
• CompareOperator: 6-8x faster comparison operations (==, >, <, etc.)
• LogicalBinaryOperator: 5-7x faster logical operations (AND, OR)
• FunctionOperator: 3-5x faster function lookup with unified registry

🔧 Enhanced Unit System

• ✅ Dimensionless Default Strategy: Safe handling of unknown units
• ✅ 15+ Unit Families: Complete engineering unit coverage
• ✅ Cross-Family Protection: Prevents invalid unit conversions
• ✅ API Consistency: Full integration with FoundryRulesAndUnits

📚 Comprehensive Documentation

• ✅ Optimization Success Documentation: Complete transformation details
• ✅ Architecture Quick Reference: Updated usage patterns and guidelines
• ✅ Token-Based Architecture Plan: Technical implementation details

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• NuGet: Package Page