group-planner 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Core types for competitor partitioning algorithms
+ */
+/** Built-in IFAA catalogue. Callers can supply any other labels through SolutionSpace. */
+type EquipmentClass = 'HB' | 'LB' | 'TR' | 'BHR' | 'BBR' | 'FSR' | 'BBC' | 'BL' | 'BU' | 'FSC' | 'FU';
+type AgeGroup = 'C' | 'J' | 'YA' | 'A' | 'V' | 'S';
+type Gender = 'F' | 'M';
+type Algorithm = 'mip' | 'mip-lp' | 'clustering' | 'auto';
+/**
+ * Labels the solver is allowed to see. When omitted, the built-in IFAA lists are used.
+ * Pass the host application's own age, gender, and bowstyle ids here.
+ */
+interface SolutionSpace {
+    equipmentClasses: readonly string[];
+    ageCategories: readonly string[];
+    genders: readonly string[];
+}
+interface Competitor {
+    id: string;
+    equipmentClass: string;
+    ageCategory: string;
+    gender: string;
+    guardianId?: string;
+}
+interface PartitionOptions {
+    /** Algorithm to use for partitioning (default: 'auto') */
+    algorithm?: Algorithm;
+    /** Prefer grouping competitors of same equipment class together vs distributing evenly */
+    groupByEquipmentClass: boolean;
+    /** Maximum number of subsets allowed (default: 28) */
+    maxSubsets?: number;
+    /** Minimum subset size. Values below 3 are raised to 3. Size 1 and 2 are never a target. */
+    minSubsetSize?: number;
+    /** Maximum subset size (default: 6) */
+    maxSubsetSize?: number;
+    /** Preferred subset size (default: 4) */
+    preferredSubsetSize?: number;
+    /** Weight for same gender preference (default: 1.0) */
+    genderWeight?: number;
+    /** Weight for same age category preference (default: 1.0) */
+    ageCategoryWeight?: number;
+    /** Weight for equipment class grouping preference (default: 1.0) */
+    equipmentClassWeight?: number;
+    /**
+     * Extra weight for subsets whose size equals preferredSubsetSize.
+     * Zero keeps the historical size score. Raise it when full groups should outrank mix.
+     */
+    closedGroupWeight?: number;
+    /** When set, competitor labels are checked against these lists instead of the IFAA defaults. */
+    solutionSpace?: SolutionSpace;
+}
+interface PartitionResult {
+    subsets: Competitor[][];
+    score: number;
+    metadata: {
+        totalCompetitors: number;
+        totalSubsets: number;
+        averageSubsetSize: number;
+        scoreBreakdown: {
+            sizeScore: number;
+            closedGroupScore: number;
+            genderScore: number;
+            ageCategoryScore: number;
+            equipmentClassScore: number;
+        };
+    };
+}
+interface AlgorithmResult {
+    result: PartitionResult;
+    executionTime: number;
+    algorithmUsed: string;
+}
+
+/**
+ * Utility functions for competitor partitioning
+ */
+
+type ResolvedPartitionOptions = Omit<Required<PartitionOptions>, 'solutionSpace'> & {
+    solutionSpace?: SolutionSpace;
+};
+/**
+ * Default partition options
+ */
+declare const DEFAULT_OPTIONS: ResolvedPartitionOptions;
+/**
+ * Validates that a partition solution meets all constraints
+ */
+declare function validatePartition(competitors: Competitor[], subsets: Competitor[][], options?: Partial<PartitionOptions>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Calculates the quality score for a partition solution
+ */
+declare function calculateScore(subsets: Competitor[][], options?: Partial<PartitionOptions>): {
+    score: number;
+    breakdown: PartitionResult['metadata']['scoreBreakdown'];
+};
+/**
+ * Creates a partition result with metadata
+ */
+declare function createPartitionResult(subsets: Competitor[][], options?: Partial<PartitionOptions>): PartitionResult;
+/**
+ * Helper to get competitors by guardian relationship
+ */
+declare function getGuardianGroups(competitors: Competitor[]): Map<string, Competitor[]>;
+/**
+ * Groups competitors into guardian families (guardian + their dependents)
+ * Returns an array where each element is either a single competitor or a guardian family
+ */
+declare function createGuardianFamilies(competitors: Competitor[]): Competitor[][];
+/**
+ * Validates that guardian constraints are satisfied in the partition
+ */
+declare function validateGuardianConstraints(competitors: Competitor[], subsets: Competitor[][]): {
+    valid: boolean;
+    errors: string[];
+};
+declare function isValidCompetitor(competitor: unknown, space?: SolutionSpace): competitor is Competitor;
+/**
+ * Validates an array of competitors
+ */
+declare function validateCompetitors(competitors: any[], space?: SolutionSpace): {
+    valid: boolean;
+    errors: string[];
+};
+
+/** A target smaller than this is not a group. Size 1 and size 2 are never emitted. */
+declare const MINIMUM_SUBSET_SIZE = 3;
+declare function smallestAllowedSubset(requestedMin: number): number;
+/**
+ * Drops or repairs targets of size 1 or 2.
+ * A short group is filled from donors, merged into another group, or removed.
+ * Removed archers are not given a target.
+ */
+declare function retainLegalSubsets(subsets: Competitor[][], min: number, max: number): Competitor[][];
+
+/**
+ * Constants for competitor categories and validation
+ */
+
+/**
+ * Valid equipment classes
+ */
+declare const EQUIPMENT_CLASSES: readonly EquipmentClass[];
+/**
+ * Valid age groups (ordered from youngest to oldest)
+ */
+declare const AGE_GROUPS: readonly AgeGroup[];
+/**
+ * Valid genders
+ */
+declare const GENDERS: readonly Gender[];
+/**
+ * Equipment class descriptions for documentation
+ */
+declare const EQUIPMENT_CLASS_DESCRIPTIONS: Record<EquipmentClass, string>;
+/**
+ * Age group descriptions for documentation
+ */
+declare const AGE_GROUP_DESCRIPTIONS: Record<AgeGroup, string>;
+/**
+ * Gender descriptions for documentation
+ */
+declare const GENDER_DESCRIPTIONS: Record<Gender, string>;
+/**
+ * Checks if a value is a valid equipment class
+ */
+declare function isValidEquipmentClass(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Checks if a value is a valid age group
+ */
+declare function isValidAgeGroup(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Checks if a value is a valid gender
+ */
+declare function isValidGender(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Gets the age group order for comparison (lower number = younger)
+ */
+declare function getAgeGroupOrder(ageGroup: AgeGroup): number;
+/**
+ * Compares two age groups (-1 if a is younger, 0 if same, 1 if a is older)
+ */
+declare function compareAgeGroups(a: AgeGroup, b: AgeGroup): number;
+
+/**
+ * Mixed Integer Programming approach for competitor partitioning
+ *
+ * This algorithm formulates the partitioning problem as a MIP problem where:
+ * - Binary variables x[i][j] indicate if competitor i is in subset j
+ * - Objective function maximizes the quality score based on preferences
+ * - Constraints ensure valid partitioning
+ */
+
+/**
+ * Solves the competitor partitioning problem using Mixed Integer Programming
+ */
+declare function solveMIP(competitors: Competitor[], options?: Partial<PartitionOptions>): AlgorithmResult;
+
+/**
+ * Mixed Integer Programming approach using HiGHS solver
+ *
+ * This algorithm formulates the partitioning problem as a proper MIP problem where:
+ * - Binary variables x[i][j] indicate if competitor i is in subset j
+ * - Objective function maximizes the quality score based on preferences
+ * - Constraints ensure valid partitioning and guardian relationships
+ */
+
+/**
+ * Solves the competitor partitioning problem using HiGHS MIP solver
+ */
+declare function solveMIPWithLP(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<AlgorithmResult>;
+
+/**
+ * Clustering approach for competitor partitioning
+ *
+ * This algorithm uses a modified K-means clustering approach where:
+ * - Competitors are represented as feature vectors
+ * - Distance metric considers gender, age category, and equipment class
+ * - Clusters are formed and then adjusted to meet size constraints
+ * - Post-processing ensures all constraints are satisfied
+ */
+
+/**
+ * Solves the competitor partitioning problem using clustering with guardian constraints
+ */
+declare function solveClustering(competitors: Competitor[], options?: Partial<PartitionOptions>): AlgorithmResult;
+
+/**
+ * Group Planner Library
+ *
+ * A TypeScript library for competitor partitioning algorithms.
+ * Provides three different approaches: Mixed Integer Programming,
+ * K-means Clustering, and Branch-and-bound.
+ */
+
+/**
+ * Main solver function - single API entry point for all algorithms
+ *
+ * @param competitors - Array of competitor objects to partition
+ * @param options - Configuration options including algorithm selection
+ * @returns Algorithm result with partitioned subsets
+ *
+ * @example
+ * ```typescript
+ * // Use specific algorithm
+ * const result = solve(competitors, { algorithm: 'mip' });
+ *
+ * // Use auto-selection (runs all algorithms, returns best)
+ * const result = solve(competitors, { algorithm: 'auto' });
+ *
+ * // Use default algorithm (auto)
+ * const result = solve(competitors);
+ * ```
+ */
+declare function solve(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<AlgorithmResult>;
+/**
+ * Runs all algorithms and returns detailed results for comparison
+ *
+ * @param competitors - Array of competitor objects to partition
+ * @param options - Configuration options (algorithm option is ignored)
+ * @returns Object with best result and all algorithm results
+ *
+ * @example
+ * ```typescript
+ * const { bestResult, allResults } = compareAlgorithms(competitors);
+ * console.log('Best:', bestResult.algorithmUsed);
+ * allResults.forEach(r => console.log(`${r.algorithmUsed}: ${r.result.score}`));
+ * ```
+ */
+declare function compareAlgorithms(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<{
+    bestResult: AlgorithmResult;
+    allResults: AlgorithmResult[];
+}>;
+declare const version = "0.1.0";
+
+export { AGE_GROUPS, AGE_GROUP_DESCRIPTIONS, type AgeGroup, type Algorithm, type AlgorithmResult, type Competitor, DEFAULT_OPTIONS, EQUIPMENT_CLASSES, EQUIPMENT_CLASS_DESCRIPTIONS, type EquipmentClass, GENDERS, GENDER_DESCRIPTIONS, type Gender, MINIMUM_SUBSET_SIZE, type PartitionOptions, type PartitionResult, type SolutionSpace, calculateScore, compareAgeGroups, compareAlgorithms, createGuardianFamilies, createPartitionResult, getAgeGroupOrder, getGuardianGroups, isValidAgeGroup, isValidCompetitor, isValidEquipmentClass, isValidGender, retainLegalSubsets, smallestAllowedSubset, solve, solveClustering, solveMIP, solveMIPWithLP, validateCompetitors, validateGuardianConstraints, validatePartition, version };