Improved advisers

Author: AlfVII

.gitignore

@@ -125,3 +125,7 @@ website/package-lock.json
 
 *.csv
 *.Identifier
+
+docs/
+tests/testData
+src/tools

src/advisers/CoilAdviser.h

@@ -10,6 +10,70 @@ using namespace MAS;
 
 namespace OpenMagnetics {
 
+/**
+ * @class CoilAdviser
+ * @brief Recommends complete coil configurations including winding patterns, wire selection, and insulation.
+ *
+ * ## Overview
+ * CoilAdviser extends WireAdviser to recommend complete coil designs. It handles:
+ * - Winding pattern selection (interleaved vs. non-interleaved)
+ * - Wire selection per winding (using WireAdviser)
+ * - Section proportion calculation based on power handling
+ * - Insulation coordination per safety standards
+ *
+ * ## Design Process
+ * 1. Calculate winding window proportions based on average power per winding
+ * 2. Generate candidate patterns (winding order permutations)
+ * 3. For each pattern, determine insulation requirements
+ * 4. Select optimal wires for each winding using WireAdviser
+ * 5. Score complete coil configurations and return ranked results
+ *
+ * ## Scoring System
+ * The default scoring filters (configurable via `load_filter_flow()`):
+ * - **EFFECTIVE_RESISTANCE**: AC resistance of windings (lower = better)
+ * - **EFFECTIVE_CURRENT_DENSITY**: Current density in conductors (lower = better)
+ * - **MAGNETOMOTIVE_FORCE**: MMF distribution quality (lower = better)
+ *
+ * Each filter uses:
+ * - `invert=true`: Lower raw values get higher scores
+ * - `log=true`: Logarithmic normalization (compresses large differences)
+ * - `weight=1.0`: Equal weight for all criteria
+ *
+ * ## Winding Patterns
+ * For a 2-winding transformer, patterns include:
+ * - `{0, 1}`: Primary then Secondary (non-interleaved)
+ * - `{1, 0}`: Secondary then Primary
+ * - With `repetitions > 1`: Interleaved sections (P-S-P-S, etc.)
+ *
+ * ## Insulation Coordination
+ * Based on IEC 60664-1 and IEC 61558, determines:
+ * - Required creepage/clearance distances
+ * - Wire insulation grade requirements
+ * - Whether margin tape or insulated wire is needed
+ *
+ * ## Planar vs. Wound Coils
+ * - **Wound**: Traditional bobbin-wound coils with round/litz/foil wire
+ * - **Planar**: PCB-based windings with copper traces
+ *
+ * ## Key Configuration
+ * - `set_allow_margin_tape(bool)`: Allow/disallow margin tape insulation
+ * - `set_allow_insulated_wire(bool)`: Allow/disallow triple-insulated wire
+ * - `set_common_wire_standard(WireStandard)`: Restrict to specific wire standards
+ * - `set_maximum_effective_current_density(double)`: Max current density
+ * - `set_maximum_number_parallels(int)`: Max parallel conductors
+ *
+ * ## Usage Example
+ * ```cpp
+ * CoilAdviser coilAdviser;
+ * coilAdviser.set_maximum_effective_current_density(5e6);
+ * coilAdviser.set_allow_margin_tape(true);
+ * auto results = coilAdviser.get_advised_coil(mas, 5);  // Top 5 configurations
+ * ```
+ *
+ * ## References
+ * - IEC 60664-1: Insulation coordination for low-voltage equipment
+ * - IEC 61558: Safety of transformers
+ */
 class CoilAdviser : public WireAdviser {
     private:
         bool _allowMarginTape = true;

src/advisers/CoreAdviser.cpp

@@ -622,10 +622,10 @@ std::vector<std::pair<Mas, double>> CoreAdviser::get_advised_core(Inputs inputs,
 
     size_t maximumMagneticsAfterFiltering = defaults.coreAdviserMaximumMagneticsAfterFiltering;
     if (get_application() == Application::POWER) {
-        return filter_standard_cores_power_application(&magnetics, inputs, maximumMagneticsAfterFiltering, maximumNumberResults);
+        return filter_standard_cores_power_application(&magnetics, inputs, _weights, maximumMagneticsAfterFiltering, maximumNumberResults);
     }
     else {
-        return filter_standard_cores_interference_suppression_application(&magnetics, inputs, maximumMagneticsAfterFiltering, maximumNumberResults);
+        return filter_standard_cores_interference_suppression_application(&magnetics, inputs, _weights, maximumMagneticsAfterFiltering, maximumNumberResults);
     }
 }
 
@@ -1359,15 +1359,15 @@ std::vector<std::pair<Mas, double>> CoreAdviser::filter_available_cores_power_ap
     filterDimensions.set_filter_configuration(&_filterConfiguration);
 
     std::vector<std::pair<Magnetic, double>> magneticsWithScoring = *magnetics;
-    magneticsWithScoring = filterAreaProduct.filter_magnetics(&magneticsWithScoring, inputs, 1.0, true);
+    magneticsWithScoring = filterAreaProduct.filter_magnetics(&magneticsWithScoring, inputs, 1.0, true);  // Fixed weight: pre-filtering criterion, not efficiency scoring
     logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " magnetics after the Area Product filter.", "CoreAdviser");
 
     if (magneticsWithScoring.size() > maximumMagneticsAfterFiltering) {
         magneticsWithScoring = std::vector<std::pair<Magnetic, double>>(magneticsWithScoring.begin(), magneticsWithScoring.end() - (magneticsWithScoring.size() - maximumMagneticsAfterFiltering));
         logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " after culling by the score on the first filter.", "CoreAdviser");
     }
 
-    magneticsWithScoring = filterEnergyStored.filter_magnetics(&magneticsWithScoring, inputs, 1.0, true);
+    magneticsWithScoring = filterEnergyStored.filter_magnetics(&magneticsWithScoring, inputs, 1.0, true);  // Fixed weight: pre-filtering criterion, not efficiency scoring
     logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " magnetics after the Energy Stored filter.", "CoreAdviser");
 
     add_initial_turns_by_inductance(&magneticsWithScoring, inputs);
@@ -1446,8 +1446,8 @@ std::vector<std::pair<Mas, double>> CoreAdviser::filter_available_cores_suppress
     magneticsWithScoring = filterMagneticInductance.filter_magnetics(&magneticsWithScoring, inputs, weights[CoreAdviserFilters::EFFICIENCY], true);
     logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " magnetics after the Magnetizing Inductance.", "CoreAdviser");
 
-    // magneticsWithScoring = filterLosses.filter_magnetics(&magneticsWithScoring, inputs, weights[CoreAdviserFilters::EFFICIENCY], true);
-    // logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " magnetics after the Core Losses filter.", "CoreAdviser");
+    magneticsWithScoring = filterLosses.filter_magnetics(&magneticsWithScoring, inputs, weights[CoreAdviserFilters::EFFICIENCY], true);
+    logEntry("There are " + std::to_string(magneticsWithScoring.size()) + " magnetics after the Core Losses filter.", "CoreAdviser");
 
     if (magneticsWithScoring.size() == 0) {
         return {};
@@ -1474,7 +1474,7 @@ std::vector<std::pair<Mas, double>> CoreAdviser::filter_available_cores_suppress
     return masWithScoring;
 }
 
-std::vector<std::pair<Mas, double>> CoreAdviser::filter_standard_cores_power_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults){
+std::vector<std::pair<Mas, double>> CoreAdviser::filter_standard_cores_power_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults){
     inputs = pre_process_inputs(inputs);
 
     MagneticCoreFilterAreaProduct filterAreaProduct(inputs);
@@ -1580,7 +1580,7 @@ std::vector<std::pair<Mas, double>> CoreAdviser::filter_standard_cores_power_app
     return masWithScoring;
 }
 
-std::vector<std::pair<Mas, double>> CoreAdviser::filter_standard_cores_interference_suppression_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults){
+std::vector<std::pair<Mas, double>> CoreAdviser::filter_standard_cores_interference_suppression_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults){
     inputs = pre_process_inputs(inputs);
 
     MagneticCoreFilterLosses filterLosses(inputs, _models);

src/advisers/CoreAdviser.h

@@ -20,6 +20,80 @@ using namespace MAS;
 
 namespace OpenMagnetics {
 
+/**
+ * @class CoreAdviser
+ * @brief Multi-criteria magnetic core recommendation system.
+ *
+ * ## Overview
+ * CoreAdviser selects optimal magnetic cores for power electronics applications based on
+ * user-defined priorities. It evaluates cores from a database using multiple criteria and
+ * returns ranked recommendations with normalized scores.
+ *
+ * ## Scoring System
+ * The adviser uses three main filter categories, each with configurable weights (0.0-1.0):
+ * - **COST**: Estimated manufacturing/purchasing cost (lower is better)
+ * - **EFFICIENCY**: Power losses (core + DC winding losses, lower is better)
+ * - **DIMENSIONS**: Physical size/volume (smaller is better)
+ *
+ * ### Score Calculation
+ * 1. Each filter computes a raw score for each core candidate
+ * 2. Scores are normalized using `normalize_scoring()`:
+ *    - `invert=true`: Lower raw values get higher scores (used for cost, losses, size)
+ *    - `log=true`: Logarithmic normalization (compresses large differences)
+ *    - `log=false`: Linear normalization (preserves proportional differences)
+ * 3. Final score = Σ(normalized_score × weight) for all filters
+ *
+ * ## Filter Pipeline
+ *
+ * ### Power Application (filter_available_cores_power_application)
+ * The filter chain for power inductors/transformers:
+ * 1. **filterAreaProduct**: Pre-filter using Area Product (AP = Aw × Ac)
+ *    - Fixed weight 1.0 (binary pass/fail, not scored)
+ *    - Eliminates cores too small for required energy storage
+ * 2. **filterEnergyStored**: Validates energy storage capacity (L×I²/2)
+ *    - Fixed weight 1.0 (binary pass/fail, not scored)
+ *    - Checks if core can store required energy without saturation
+ * 3. **filterCost**: Scores by estimated cost
+ *    - Weight: COST user weight
+ * 4. **filterDimensions**: Scores by physical volume
+ *    - Weight: DIMENSIONS user weight
+ *    - Uses linear normalization to preserve size differences
+ * 5. **filterLosses**: Scores by total losses (core + winding DC)
+ *    - Weight: EFFICIENCY user weight
+ *
+ * ### Suppression Application (filter_available_cores_suppression_application)
+ * The filter chain for EMI/RFI suppression:
+ * 1. **filterMinimumImpedance**: Pre-filter by impedance at operating frequency
+ * 2. **filterCost**: Scores by estimated cost
+ * 3. **filterDimensions**: Scores by physical volume
+ * 4. **filterMagneticInductance**: Scores by magnetizing inductance
+ * 5. **filterLosses**: Scores by total losses
+ *
+ * ## Operating Modes
+ * - **AVAILABLE_CORES**: Uses manufacturer stock database (fastest)
+ * - **STANDARD_CORES**: Uses standard core shapes with material optimization
+ * - **CUSTOM_CORES**: Uses user-provided core list
+ *
+ * ## Toroid Handling
+ * Toroidal cores use geometry-based bobbin filling factor calculation:
+ *   fillingFactor = 0.55 + 0.15 × (innerRadius / outerRadius)
+ * This accounts for the reduced winding area in toroid centers (range: 0.55-0.70).
+ *
+ * ## Usage Example
+ * ```cpp
+ * std::map<CoreAdviserFilters, double> weights = {
+ *     {CoreAdviserFilters::COST, 0.3},
+ *     {CoreAdviserFilters::EFFICIENCY, 0.5},
+ *     {CoreAdviserFilters::DIMENSIONS, 0.2}
+ * };
+ * CoreAdviser adviser;
+ * auto results = adviser.get_advised_core(inputs, weights, 5);  // Top 5 cores
+ * ```
+ *
+ * ## References
+ * - Industry practice: LI² (energy storage), Area Product method
+ * - Colonel Wm. T. McLyman, "Transformer and Inductor Design Handbook"
+ */
 class CoreAdviser {
     public: 
         enum class CoreAdviserFilters : int {
@@ -45,6 +119,21 @@ class CoreAdviser {
 
     public:
 
+        /**
+         * @brief Filter normalization configuration for each scoring category.
+         *
+         * Each filter category has two configuration options:
+         * - **invert**: If true, lower raw values result in higher normalized scores.
+         *   Used when "less is better" (cost, losses, size).
+         * - **log**: If true, uses logarithmic normalization; if false, linear.
+         *   Linear normalization preserves proportional differences between cores.
+         *
+         * Configuration rationale:
+         * - COST: inverted (cheaper=better), logarithmic (diminishing returns on savings)
+         * - EFFICIENCY: inverted (lower losses=better), logarithmic (diminishing returns)
+         * - DIMENSIONS: inverted (smaller=better), LINEAR (size differences should be
+         *   proportionally reflected; a core 2× larger should score proportionally worse)
+         */
         std::map<CoreAdviserFilters, std::map<std::string, bool>> _filterConfiguration{
                 { CoreAdviserFilters::COST,                  { {"invert", true}, {"log", true} } },
                 { CoreAdviserFilters::EFFICIENCY,            { {"invert", true}, {"log", true} } },
@@ -63,6 +152,11 @@ class CoreAdviser {
             _models["coreLosses"] = to_string(defaults.coreLossesModelDefault);
             _models["coreTemperature"] = to_string(defaults.coreTemperatureModelDefault);
         }
+        /**
+         * @brief Get per-core scoring breakdown for debugging/analysis.
+         * @param weighted If true, returns weighted scores; otherwise raw normalized scores.
+         * @return Map of core names to their per-filter scores.
+         */
         std::map<std::string, std::map<CoreAdviserFilters, double>> get_scorings(bool weighted = false);
 
         void set_unique_core_shapes(bool value);
@@ -72,7 +166,21 @@ class CoreAdviser {
         void set_mode(CoreAdviserModes value);
         CoreAdviserModes get_mode();
 
+        /**
+         * @brief Main entry point for core recommendation.
+         * @param inputs Operating conditions (voltage, current, frequency, etc.)
+         * @param maximumNumberResults Maximum number of cores to return.
+         * @return Vector of (Mas, score) pairs, sorted by descending score.
+         */
         std::vector<std::pair<Mas, double>> get_advised_core(Inputs inputs, size_t maximumNumberResults=1);
+        
+        /**
+         * @brief Core recommendation with custom weights.
+         * @param inputs Operating conditions.
+         * @param weights Map of filter weights (COST, EFFICIENCY, DIMENSIONS). Values 0.0-1.0.
+         * @param maximumNumberResults Maximum number of cores to return.
+         * @return Vector of (Mas, score) pairs, sorted by descending score.
+         */
         std::vector<std::pair<Mas, double>> get_advised_core(Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumNumberResults=1);
         std::vector<std::pair<Mas, double>> get_advised_core(Inputs inputs, std::vector<Core>* cores, size_t maximumNumberResults=1);
         std::vector<std::pair<Mas, double>> get_advised_core(Inputs inputs, std::map<CoreAdviserFilters, double> weights, std::vector<Core>* cores, size_t maximumNumberResults=1);
@@ -81,10 +189,49 @@ class CoreAdviser {
         std::vector<std::pair<Mas, double>> get_advised_core(Inputs inputs, std::vector<CoreShape>* shapes, size_t maximumNumberResults=1);
 
         Mas post_process_core(Magnetic magnetic, Inputs inputs);
+        
+        /**
+         * @brief Filter pipeline for power inductor/transformer applications.
+         *
+         * Applies filters in order: AreaProduct → EnergyStored → Cost → Dimensions → Losses.
+         * - AreaProduct and EnergyStored use fixed weight 1.0 (pre-filtering, not scoring)
+         * - Cost, Dimensions, Losses use user-provided weights for scoring
+         *
+         * @param magnetics Input list of candidate magnetics with initial scores.
+         * @param inputs Operating conditions.
+         * @param weights User-defined weights for COST, EFFICIENCY, DIMENSIONS.
+         * @param maximumMagneticsAfterFiltering Max candidates to keep after filtering.
+         * @param maximumNumberResults Max results to return.
+         * @return Filtered and scored list of (Mas, score) pairs.
+         */
         std::vector<std::pair<Mas, double>> filter_available_cores_power_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
+        
+        /**
+         * @brief Filter pipeline for EMI/RFI suppression applications.
+         *
+         * Applies filters: MinimumImpedance → Cost → Dimensions → MagneticInductance → Losses.
+         *
+         * @param magnetics Input list of candidate magnetics with initial scores.
+         * @param inputs Operating conditions (includes required impedance at frequency).
+         * @param weights User-defined weights for COST, EFFICIENCY, DIMENSIONS.
+         * @param maximumMagneticsAfterFiltering Max candidates to keep after filtering.
+         * @param maximumNumberResults Max results to return.
+         * @return Filtered and scored list of (Mas, score) pairs.
+         */
         std::vector<std::pair<Mas, double>> filter_available_cores_suppression_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
-        std::vector<std::pair<Mas, double>> filter_standard_cores_power_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
-        std::vector<std::pair<Mas, double>> filter_standard_cores_interference_suppression_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
+        
+        /**
+         * @brief Filter pipeline for standard core shapes (with material selection).
+         *
+         * Similar to filter_available_cores_power_application but works with
+         * parametric core shapes rather than specific stock cores.
+         */
+        std::vector<std::pair<Mas, double>> filter_standard_cores_power_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
+        
+        /**
+         * @brief Filter pipeline for standard core shapes in suppression applications.
+         */
+        std::vector<std::pair<Mas, double>> filter_standard_cores_interference_suppression_application(std::vector<std::pair<Magnetic, double>>* magnetics, Inputs inputs, std::map<CoreAdviserFilters, double> weights, size_t maximumMagneticsAfterFiltering, size_t maximumNumberResults);
         std::vector<std::pair<Magnetic, double>> create_magnetic_dataset(Inputs inputs, std::vector<Core>* cores, bool includeStacks);
         std::vector<std::pair<Magnetic, double>> create_magnetic_dataset(Inputs inputs, std::vector<CoreShape>* shapes, bool includeStacks);
         void expand_magnetic_dataset_with_stacks(Inputs inputs, std::vector<Core>* cores, std::vector<std::pair<Magnetic, double>>* magnetics);