dragonfly

type AlgorithmRecommendation struct {
	// Variant is the recommended variant.
	Variant AlgorithmVariant

	// Reason explains, in one line, why this variant scored as it did.
	Reason string

	// Preset names the configuration factory to start from. It reflects the
	// problem's shape, not the variant, so every recommendation for a given
	// problem carries the same preset -- except that a discrete problem always
	// gets PresetBinary.
	Preset ConfigPreset

	// Score is the fit in [0,1], from AlgorithmVariant.ApplicableTo.
	Score float64

	// Confidence is how much weight to put on Score, in [0,1]. It is lower
	// where the heuristics are guessing: a variant scored outside the problem
	// class it was written for, or a high-overhead variant on an expensive
	// objective.
	Confidence float64
}

type AlgorithmSelector struct {
	// contains filtered or unexported fields
}

type AlgorithmStatistics struct {
	Mean   float64 `json:"mean"`
	Median float64 `json:"median"`
	StdDev float64 `json:"stddev"`
	Best   float64 `json:"best"`
	Worst  float64 `json:"worst"`

	// SuccessRate is the percentage of runs that reached the target cost. It is
	// zero when no target was configured.
	SuccessRate  float64 `json:"success_rate"`
	AvgFuncEvals float64 `json:"avg_function_evaluations"`
	AvgTime      float64 `json:"avg_execution_seconds"`
}

type AlgorithmVariant interface {
	// Name returns the short canonical name of the variant: "DA", "BDA" or
	// "MODA".
	Name() string

	// FullName returns the full descriptive name of the variant.
	FullName() string

	// Description returns a one-line summary of what the variant changes.
	Description() string

	// GetConfig returns a freshly allocated default configuration for this
	// variant. You must still set ObjectiveFunc and ProblemSize, and for the
	// continuous variants LowerBound and UpperBound.
	GetConfig() *Config

	// IsMultiObjective reports whether this variant optimizes several
	// objectives at once, and therefore whether Run can honor its contract.
	IsMultiObjective() bool

	// Run executes the variant's single-objective entry point. A variant whose
	// IsMultiObjective reports true returns ErrMultiObjectiveVariant.
	Run(ctx context.Context, config *Config, options ...RunOption) (*Result, error)

	// ApplicableTo scores how well this variant suits the given problem, in
	// [0,1]. Higher is a better fit.
	ApplicableTo(characteristics ProblemCharacteristics) float64

	// EstimatedOverhead returns the approximate per-iteration cost relative to
	// standard DA, as a multiplier. 1.0 is the baseline.
	EstimatedOverhead() float64

	// RecommendedFor returns the problem classes this variant excels at.
	RecommendedFor() []string
}

type BDAVariant struct{}

type Best struct {
	Position            []float64
	Cost                float64
	ConstraintViolation float64
}

type BoundaryMethod string

type CandidateEvaluation struct {
	Cost                float64
	ConstraintViolation float64
}

type ComparisonResult struct {
	// FriedmanResult is nil when fewer than two variants were compared.
	FriedmanResult *FriedmanTestResult `json:"friedman,omitempty"`

	BenchmarkName  string                `json:"benchmark"`
	AlgorithmNames []string              `json:"algorithms"`
	RunResults     [][]RunResult         `json:"runs"`
	Statistics     []AlgorithmStatistics `json:"statistics"`

	// Rankings[i] is variant i's rank by mean cost, 1 being best.
	Rankings []int `json:"rankings"`

	// WilcoxonTests[i][j] is the pairwise test between variants i and j. The
	// diagonal is left zero.
	WilcoxonTests [][]WilcoxonResult `json:"wilcoxon"`

	// BestAlgorithm indexes the rank-1 variant, or -1 when the comparison
	// failed before producing statistics.
	BestAlgorithm int `json:"best_algorithm"`

	// BaseSeed is the seed run 0 used. Run k of every variant used
	// BaseSeed + k, so the whole comparison is reproducible from this number.
	BaseSeed int64 `json:"base_seed"`
}

type ComparisonRunner struct {
	// Variants defaults to SingleObjectiveVariants(). A multi-objective
	// variant is rejected: every statistic here is defined over a scalar cost.
	Variants []AlgorithmVariant

	Runs          int
	MaxIterations int

	// TargetCost is the success threshold used for SuccessRate and
	// ConvergenceAt. Zero disables both.
	TargetCost float64

	// MaxWorkers bounds concurrent runs when Parallel is set. Zero means
	// runtime.NumCPU().
	MaxWorkers int

	// Seed is the base seed run 0 uses.
	Seed int64

	Verbose  bool
	Parallel bool
}

type Config struct {
	ObjectiveFunc  ObjectiveFunction  `json:"-"`
	Rand           *rand.Rand         `json:"-"`
	Convergence    *ConvergenceConfig `json:"convergence,omitempty"`
	Constraints    *ConstraintConfig  `json:"constraints,omitempty"`
	BoundaryMethod BoundaryMethod     `json:"boundary_method"`

	// TransferFunc names the transfer function the binary variant turns a step
	// component into a bit-flip probability with. An empty value means
	// DefaultTransferFunction, the paper's v3. It is ignored by the continuous
	// entry points.
	TransferFunc TransferFunction `json:"transfer_function,omitempty"`

	LowerBound float64 `json:"lower_bound"`
	UpperBound float64 `json:"upper_bound"`

	// InertiaWeightStart and InertiaWeightEnd bracket the linearly decreasing
	// inertia weight w = start - t*(start-end)/T.
	InertiaWeightStart float64 `json:"inertia_weight_start"`
	InertiaWeightEnd   float64 `json:"inertia_weight_end"`

	// The five swarming weights. At WeightAuto each follows the paper's
	// schedule; any other finite value is used literally for the whole run.
	SeparationWeight float64 `json:"separation_weight"`
	AlignmentWeight  float64 `json:"alignment_weight"`
	CohesionWeight   float64 `json:"cohesion_weight"`
	FoodWeight       float64 `json:"food_weight"`
	EnemyWeight      float64 `json:"enemy_weight"`

	// RadiusInitialDivisor and RadiusGrowth shape the neighborhood radius
	// r = (ub-lb)/divisor + (ub-lb)*(t/T)*growth.
	RadiusInitialDivisor float64 `json:"radius_initial_divisor"`
	RadiusGrowth         float64 `json:"radius_growth"`

	// MaxStepRatio sets the step clamp ΔX_max = MaxStepRatio*(ub-lb).
	MaxStepRatio float64 `json:"max_step_ratio"`

	// EnemyCutoffFraction is the fraction of the run after which the enemy
	// weight is forced to zero. The paper uses three quarters.
	EnemyCutoffFraction float64 `json:"enemy_cutoff_fraction"`

	// LevyBeta and LevyScale parameterize Mantegna's algorithm.
	LevyBeta  float64 `json:"levy_beta"`
	LevyScale float64 `json:"levy_scale"`

	ProblemSize   int `json:"problem_size"`
	NPop          int `json:"npop"`
	MaxIterations int `json:"max_iterations"`
	MaxWorkers    int `json:"max_workers"`

	// UseLevyWalk selects the paper's Lévy random walk for a dragonfly with no
	// neighbors and no food in range. Disabling it keeps such a dragonfly
	// still for that iteration.
	UseLevyWalk    bool `json:"use_levy_walk"`
	EnableParallel bool `json:"enable_parallel"`

	// UseBinary marks a configuration as belonging to the binary variant: 0/1
	// positions, the bit-flip position update, and the transfer function in
	// TransferFunc. It is what NewBinaryConfig sets and what the variant
	// registry dispatches on; OptimizeBinary and OptimizeBinaryContext run the
	// binary variant regardless of it, and Optimize ignores it.
	UseBinary bool `json:"use_binary"`
}

type ConfigPreset string

type ConstraintConfig struct {
	Handling          ConstraintHandlingMethod `json:"handling,omitempty"`
	PenaltyMethod     PenaltyMethod            `json:"penalty_method,omitempty"`
	Inequalities      []ConstraintFunction     `json:"-"`
	Equalities        []ConstraintFunction     `json:"-"`
	PenaltyFactor     float64                  `json:"penalty_factor,omitempty"`
	EqualityTolerance float64                  `json:"equality_tolerance,omitempty"`
}

type ConstraintEvaluation struct {
	Violation float64
	Feasible  bool
}

type ConstraintFunction func([]float64) float64

type ConstraintHandlingMethod string

type ConvergenceConfig struct {
	// TargetCost stops the run when the best cost is less than or equal to the
	// pointed-to value. A pointer distinguishes a disabled target from a target
	// of zero.
	TargetCost *float64 `json:"target_cost,omitempty"`

	// MinImprovement is the absolute cost, penalty score, or constraint-
	// violation reduction required to reset the stagnation counter. It must be
	// non-negative.
	MinImprovement float64 `json:"min_improvement"`

	// StagnationIterations stops the run after this many consecutive iterations
	// without a sufficient improvement. Zero disables stagnation detection.
	StagnationIterations int `json:"stagnation_iterations"`

	// MinIterations is the minimum number of iterations completed before either
	// stopping criterion can terminate the run. Zero behaves as one because
	// convergence is checked at iteration boundaries.
	MinIterations int `json:"min_iterations"`
}

type ConvergenceExport struct {
	TerminationReason        TerminationReason  `json:"termination_reason,omitempty"`
	BestPosition             []float64          `json:"best_position,omitempty"`
	WorstPosition            []float64          `json:"worst_position,omitempty"`
	Convergence              []ConvergencePoint `json:"convergence"`
	BestCost                 float64            `json:"best_cost"`
	BestConstraintViolation  float64            `json:"best_constraint_violation"`
	WorstCost                float64            `json:"worst_cost"`
	WorstConstraintViolation float64            `json:"worst_constraint_violation"`
	Seed                     int64              `json:"seed"`
	FuncEvalCount            int                `json:"func_eval_count"`
	IterationCount           int                `json:"iteration_count"`
}

type ConvergencePoint struct {
	Iteration int     `json:"iteration"`
	BestCost  float64 `json:"best_cost"`
}

type DAVariant struct{}

type Dragonfly struct {
	Position            []float64
	Step                []float64
	Cost                float64
	ConstraintViolation float64
}

type FriedmanTestResult struct {
	ChiSquare        float64 `json:"chi_square"`
	PValue           float64 `json:"p_value"`
	DegreesOfFreedom int     `json:"degrees_of_freedom"`
	Significant      bool    `json:"significant"`
}

type Landscape int

type Logger interface {
	Log(ctx context.Context, level slog.Level, message string, args ...any)
}

type MODAVariant struct{}

type Modality int

type MultiObjectiveConfig struct {
	ObjectiveFunc MultiObjectiveFunction `json:"-"`
	Swarm         *Config                `json:"swarm"`

	// Beta, Gamma and Delta are the hypercube roulette exponents. See the
	// UNVERIFIED note on DefaultArchiveBeta before treating the defaults as
	// paper values.
	Beta  float64 `json:"beta"`
	Gamma float64 `json:"gamma"`
	Delta float64 `json:"delta"`

	ArchiveSize int `json:"archive_size"`
	NGrid       int `json:"n_grid"`
}

type MultiObjectiveFunction func([]float64) []float64

type MultiObjectiveResult struct {
	// Only the iteration cap ends a MODA run today, so this is always
	// TerminationMaxIterations; it is reported anyway so that a caller can read
	// a MODA result the same way it reads a single-objective one.
	TerminationReason TerminationReason

	Archive *ParetoArchive

	// ArchiveSizeCurve records the archive's size after each completed
	// iteration, the multi-objective analog of Result.ConvergenceCurve. A
	// curve that stops growing early is the usual sign of a run that has
	// stagnated.
	ArchiveSizeCurve []int

	FuncEvalCount  int
	IterationCount int
	Seed           int64
}

type ObjectiveFunction func([]float64) float64

type ParetoArchive struct {
	// Solutions is the archive contents, in insertion order. Every member is
	// mutually non-dominated with every other; that invariant is restored by
	// each mutation, not merely at the end of a run.
	Solutions []*ParetoSolution

	// Beta, Gamma and Delta are the roulette exponents; see the UNVERIFIED note
	// on DefaultArchiveBeta.
	Beta  float64
	Gamma float64
	Delta float64

	// MaxSize is the capacity. A successful insert past capacity evicts a member
	// of the most crowded hypercube, so the archive never exceeds it.
	MaxSize int
	// NGrid is the number of hypercubes per objective.
	NGrid int
	// contains filtered or unexported fields
}

type ParetoExport struct {
	TerminationReason TerminationReason `json:"termination_reason,omitempty"`
	Front             []ParetoPoint     `json:"front"`
	ArchiveSizeCurve  []int             `json:"archive_size_curve,omitempty"`
	Seed              int64             `json:"seed"`
	ArchiveSize       int               `json:"archive_size"`
	FuncEvalCount     int               `json:"func_eval_count"`
	IterationCount    int               `json:"iteration_count"`
}

type ParetoPoint struct {
	Position   []float64 `json:"position"`
	Objectives []float64 `json:"objectives"`
	Index      int       `json:"index"`
}

type ParetoSolution struct {
	Position           []float64
	ObjectiveValues    []float64
	DominatedSolutions []int
	// GridIndex is the solution's hypercube coordinate, one component per
	// objective, each in [0, NGrid-1].
	GridIndex        []int
	CrowdingDistance float64
	Rank             int
	DominationCount  int
	// GridKey flattens GridIndex into a single integer in base NGrid, so that
	// occupancy can be counted with one map lookup rather than a slice compare.
	GridKey int
}

type PenaltyMethod string

type PopulationObserver func(PopulationSnapshot)

type PopulationSnapshot struct {
	Swarm           []Dragonfly
	Best            Best
	Worst           Best
	Iteration       int
	EvaluationCount int
}

type ProblemCharacteristics struct {
	// Dimensionality is the number of decision variables.
	Dimensionality int

	// Modality describes how many optima the landscape has.
	Modality Modality

	// Landscape describes the terrain between them.
	Landscape Landscape

	// Discrete marks a search space whose variables are binary or otherwise
	// discrete. It is what routes a problem to BDA.
	Discrete bool

	// ExpensiveEvaluations marks an objective whose evaluation dominates the
	// run time, so that a variant's overhead matters.
	ExpensiveEvaluations bool

	// RequiresFastConvergence marks a run with a wall-clock or budget limit,
	// where a good answer soon beats the best answer eventually.
	RequiresFastConvergence bool

	// RequiresStableConvergence marks a run whose variance across seeds
	// matters as much as its mean.
	RequiresStableConvergence bool

	// MultiObjective marks a problem with several objectives to trade off. It
	// is what routes a problem to MODA.
	MultiObjective bool
}

type Progress struct {
	Best            Best
	Iteration       int
	EvaluationCount int
}

type ProgressObserver func(Progress)

type Result struct {
	// ConvergenceCurve holds the best cost known at the end of each completed
	// iteration, so it has IterationCount entries. It is non-increasing for
	// unconstrained optimization; a constrained incumbent's raw cost may rise
	// when feasibility or lower violation takes priority. Without early
	// stopping, IterationCount equals MaxIterations. It is a history of costs,
	// not a point in the search space.
	//
	// The solution itself is GlobalBest.Position.
	ConvergenceCurve []float64

	TerminationReason TerminationReason
	GlobalBest        Best

	// Worst is the enemy: the worst position seen during the run, which the
	// enemy term of every step is computed against. It is reported for
	// inspection -- it is specific to this algorithm and has no counterpart in
	// Mayfly's Result.
	Worst Best

	FuncEvalCount  int
	IterationCount int
	Seed           int64 // Random seed used for reproducibility
}

type RunOption struct {
	// contains filtered or unexported fields
}

type RunResult struct {
	// Error is the run's error message, empty when the run succeeded. It is a
	// string rather than an error so the result document serializes.
	Error string `json:"error,omitempty"`

	BestCost      float64 `json:"best_cost"`
	ExecutionTime float64 `json:"execution_seconds"`
	Seed          int64   `json:"seed"`
	FuncEvals     int     `json:"function_evaluations"`
	Iterations    int     `json:"iterations"`

	// ConvergenceAt is the one-based iteration at which the run first reached
	// ComparisonRunner.TargetCost, or zero if it never did or no target was set.
	ConvergenceAt int `json:"convergence_at"`
}

type TerminationReason string

type TransferFunction string

type VariantBuilder struct {
	// contains filtered or unexported fields
}

type WilcoxonResult struct {
	Algorithm1 string `json:"algorithm_1"`
	Algorithm2 string `json:"algorithm_2"`

	// Winner is the variant with the lower costs when the difference is
	// significant, and wilcoxonTie otherwise.
	Winner string `json:"winner"`

	// WStatistic is min(W+, W-), the smaller of the positive and negative
	// signed-rank sums.
	WStatistic float64 `json:"w_statistic"`

	// PValue is two-tailed, from the normal approximation to W. It is
	// unreliable below roughly ten non-tied pairs, where an exact table is
	// needed; the approximation is reported anyway rather than withheld,
	// because it is the number a reader can check against a table.
	PValue      float64 `json:"p_value"`
	Significant bool    `json:"significant"`
}