#differentiable_ecs

#Install

moon add mizchi/differentiable_ecs

#Quick Start

fn simulate(params : Array[Double], seed : Int) -> @dec.Metrics {
  let speed = params[0]
  let hp = params[1]
  // ... run your simulation ...
  let m = @dec.Metrics::new()
  m.set("survival_time", 120.0)
  m.set("kill_rate", 3.5)
  m
}

fn main {
  let specs : Array[@dec.ParamSpec] = [
    { name: "speed", initial: 2.0, min: 0.5, max: 5.0 },
    { name: "hp",    initial: 100.0, min: 10.0, max: 500.0 },
  ]
  let targets : Array[@dec.BalanceTarget] = [
    { metric: "survival_time", target: 180.0, weight: 1.0 },
    { metric: "kill_rate",     target: 5.0,   weight: 1.5 },
  ]
  let config = { ..@dec.TuneConfig::default(specs, targets), max_generations: 50 }
  let result = @dec.tune(config, simulate)
  println("Loss: " + result.loss.to_string())
}

#How It Works

1. Define parameters (ParamSpec): name, initial value, min/max bounds
2. Write a simulation function: (Array[Double], Int) -> Metrics — takes parameter values and a seed, returns named metrics
3. Set targets (BalanceTarget): which metrics to optimize, target values, and weights
4. Call tune(): CMA-ES finds parameters that minimize weighted squared error between actual and target metrics

#API

#Types

#Functions

#TuneConfig Defaults

seeds:           [42, 137, 256, 512]  (4 seeds for robustness)
max_generations: 40
sigma:           0.3                  (initial step size)
rng_seed:        42
log_interval:    10                   (0 to disable)

#When to Use CMA-ES

#Effective (use this library)

• Non-separable problems: parameters interact with each other (game balance, physics tuning)
• Ill-conditioned landscapes: different parameters have vastly different sensitivities
• Moderate dimensions: 5–100 parameters
• Black-box functions: no gradient available (simulations, game loops)
• Noisy evaluations: multi-seed averaging handles stochastic simulations

#Less effective (consider alternatives)

• Highly multimodal: many local minima (Rastrigin-like) — needs restart strategies (IPOP-CMA-ES)
• Deceptive landscapes: global optimum far from initial guess (Schwefel-like)
• Very high dimensions: >200 parameters — use diagonal CMA-ES or other methods
• Budget < 10n evaluations: too few to learn the covariance structure

#Benchmark Results

#Examples

• examples/benchmark/ — Standard optimization benchmarks (Sphere, Rosenbrock, Rastrigin, Ackley, Schwefel, Griewank)
• examples/hacknslash/ — Hack-and-slash game balance (player speed, enemy HP, spawn rate)
• examples/tower_defense/ — Tower defense wave balancing (enemy scaling, tower stats)
• examples/deckbuilder/ — Card game archetype balance (3 archetypes, ~50% win rates)
• examples/sim_game/ — Economy simulation (tax, production, growth)

#Performance

#References

• Hansen, N. (2016). The CMA Evolution Strategy: A Tutorial. arXiv:1604.00772.
• Hansen, N. & Ostermeier, A. (2001). Completely Derandomized Self-Adaptation in Evolution Strategies. Evolutionary Computation, 9(2), 159-195.

#License