ApprenticeFoundryMentorModeler 23.4.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

• 15+ Unit Families: Angle, Length, Mass, Time, Force, Temperature, Voltage, Current, Power, and more
• Mixed Unit Support: Imperial, Metric, and specialized engineering units
• 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

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 (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