deepbox 0.1.0

package/dist/chunk-PR647I7R.js

@@ -0,0 +1,1898 @@
+import { __export, DataValidationError, InvalidParameterError, DeepboxError, NotFittedError, DTypeError, ShapeError, IndexError } from './chunk-4S73VUBD.js';
+
+// src/optim/index.ts
+var optim_exports = {};
+__export(optim_exports, {
+  AdaDelta: () => AdaDelta,
+  Adagrad: () => Adagrad,
+  Adam: () => Adam,
+  AdamW: () => AdamW,
+  CosineAnnealingLR: () => CosineAnnealingLR,
+  ExponentialLR: () => ExponentialLR,
+  LRScheduler: () => LRScheduler,
+  LinearLR: () => LinearLR,
+  MultiStepLR: () => MultiStepLR,
+  Nadam: () => Nadam,
+  OneCycleLR: () => OneCycleLR,
+  Optimizer: () => Optimizer,
+  RMSprop: () => RMSprop,
+  ReduceLROnPlateau: () => ReduceLROnPlateau,
+  SGD: () => SGD,
+  StepLR: () => StepLR,
+  WarmupLR: () => WarmupLR
+});
+
+// src/optim/Optimizer.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function ensureRecord(value, context) {
+  if (!isRecord(value)) {
+    throw new DataValidationError(`${context} must be an object`);
+  }
+  return value;
+}
+function isStateRecord(value) {
+  return isRecord(value);
+}
+function ensureIntegerArray(value, context) {
+  if (!Array.isArray(value)) {
+    throw new DataValidationError(`${context} must be an array of integers`);
+  }
+  const output = [];
+  for (const entry of value) {
+    if (!Number.isInteger(entry)) {
+      throw new DataValidationError(`${context} must contain integers only`);
+    }
+    output.push(entry);
+  }
+  return output;
+}
+function isParamGroupArray(params) {
+  if (!Array.isArray(params)) return false;
+  if (params.length === 0) return true;
+  const first = params[0];
+  if (!first || typeof first !== "object") return false;
+  return "params" in first;
+}
+var Optimizer = class {
+  /**
+   * Create a new optimizer.
+   *
+   * Initializes the optimizer with either a simple list of parameters or
+   * multiple parameter groups with per-group hyperparameters.
+   *
+   * @param params - Either an iterable of parameters or array of parameter groups
+   * @param defaults - Default hyperparameters applied to all groups
+   */
+  constructor(params, defaults) {
+    this.defaults = defaults;
+    this.paramGroups = [];
+    if (!isParamGroupArray(params)) {
+      this.paramGroups.push({
+        params: Array.from(params),
+        // Convert iterable to array for efficient access
+        options: { ...defaults }
+        // Clone defaults to avoid mutation
+      });
+    } else {
+      for (const group of params) {
+        const { params: groupParams, ...groupOptions } = group;
+        this.paramGroups.push({
+          params: Array.from(groupParams),
+          // Convert to array
+          options: { ...defaults, ...groupOptions }
+          // Merge defaults with group options
+        });
+      }
+    }
+  }
+  /**
+   * Groups of parameters with their associated hyperparameters.
+   * Each group can have different options (e.g., learning rates).
+   * Exposed publicly to enable scheduler integrations.
+   */
+  paramGroups;
+  /**
+   * Per-parameter state storage.
+   * Maps each parameter to its optimizer-specific state (momentum, adaptive rates, etc.).
+   */
+  state = /* @__PURE__ */ new Map();
+  /**
+   * Zero out the gradients of all optimized parameters.
+   *
+   * This method should be called at the beginning of each training iteration,
+   * before computing new gradients. Without this call, gradients would accumulate
+   * across iterations, leading to incorrect updates.
+   *
+   * **Implementation Note:**
+   * For parameters wrapped in GradTensor, this calls zeroGrad() on each parameter,
+   * which either sets the gradient to zero or initializes it if not yet created.
+   *
+   * @example
+   * ```ts
+   * // Typical training loop
+   * optimizer.zeroGrad();              // Clear previous gradients
+   * const output = model.forward(input);
+   * const loss = criterion(output, target);
+   * loss.backward();                   // Compute new gradients
+   * optimizer.step();                  // Update parameters
+   * ```
+   */
+  zeroGrad() {
+    for (const group of this.paramGroups) {
+      for (const param of group.params) {
+        param.zeroGrad();
+      }
+    }
+  }
+  /**
+   * Add a parameter group to the optimizer.
+   *
+   * This method allows adding new parameters to optimize after the optimizer
+   * has been created. This is particularly useful for:
+   * - Fine-tuning: adding pre-trained layers with different learning rates
+   * - Progressive training: gradually unfreezing layers
+   * - Dynamic architectures: adding parameters while the model grows
+   *
+   * @param paramGroup - Parameter group to add with optional per-group options
+   *
+   * @example
+   * ```ts
+   * const optimizer = new SGD(model.backbone.parameters(), { lr: 0.001 });
+   * // Later, add classifier with higher learning rate
+   * optimizer.addParamGroup({
+   *   params: model.classifier.parameters(),
+   *   lr: 0.01
+   * });
+   * ```
+   */
+  addParamGroup(paramGroup) {
+    const { params, ...options } = paramGroup;
+    this.paramGroups.push({
+      params: Array.from(params),
+      // Convert iterable to array
+      options: { ...this.defaults, ...options }
+      // Merge with defaults
+    });
+  }
+  /**
+   * Get the current state of the optimizer.
+   *
+   * Returns a dictionary containing all optimizer state that needs to be
+   * saved for checkpointing. This includes per-parameter state (momentum buffers,
+   * adaptive learning rates, etc.) and parameter group configurations.
+   *
+   * **Note:** In a production implementation, parameters would be identified by
+   * unique IDs rather than object references for proper serialization.
+   *
+   * @returns Optimizer state dictionary containing state and parameter groups
+   *
+   * @example
+   * ```ts
+   * // Save checkpoint
+   * const checkpoint = {
+   *   model: model.stateDict(),
+   *   optimizer: optimizer.stateDict(),
+   *   epoch: currentEpoch
+   * };
+   * ```
+   */
+  stateDict() {
+    const paramIdMap = /* @__PURE__ */ new Map();
+    const orderedParams = [];
+    const getParamId = (param) => {
+      const existing = paramIdMap.get(param);
+      if (existing !== void 0) return existing;
+      const id = orderedParams.length;
+      orderedParams.push(param);
+      paramIdMap.set(param, id);
+      return id;
+    };
+    return {
+      // Serialize per-parameter state
+      state: Array.from(this.state.entries()).map(([param, state]) => ({
+        paramId: getParamId(param),
+        param,
+        // Backward-compatible references
+        state
+        // Optimizer-specific state (momentum, etc.)
+      })),
+      // Serialize parameter groups and their options
+      paramGroups: this.paramGroups.map((group) => ({
+        params: group.params,
+        // Backward-compatible references
+        paramIds: group.params.map((param) => getParamId(param)),
+        options: group.options
+        // Hyperparameters for this group
+      }))
+    };
+  }
+  /**
+   * Load optimizer state from a state dictionary.
+   *
+   * Restores the optimizer to a previously saved state, including all
+   * per-parameter state and parameter group configurations. This is essential
+   * for resuming training from checkpoints.
+   *
+   * **Important:** The loaded state must be compatible with the current
+   * optimizer configuration (same parameters, same optimizer type).
+   *
+   * @param stateDict - State dictionary previously returned by stateDict()
+   *
+   * @example
+   * ```ts
+   * // Resume from checkpoint
+   * const checkpoint = loadCheckpoint('checkpoint.json');
+   * model.loadStateDict(checkpoint.model);
+   * optimizer.loadStateDict(checkpoint.optimizer);
+   * ```
+   */
+  loadStateDict(stateDict) {
+    const currentParams = this.paramGroups.flatMap((group) => group.params);
+    const currentParamCount = currentParams.length;
+    const paramLookup = /* @__PURE__ */ new Map();
+    for (let i = 0; i < currentParams.length; i++) {
+      paramLookup.set(currentParams[i], i);
+    }
+    if (Object.hasOwn(stateDict, "paramGroups")) {
+      const rawGroups = stateDict["paramGroups"];
+      if (!Array.isArray(rawGroups)) {
+        throw new DataValidationError("paramGroups must be an array");
+      }
+      const groupsArray = rawGroups;
+      if (groupsArray.length === 0) {
+        if (this.paramGroups.length !== 0) {
+          throw new DataValidationError("paramGroups cannot be empty");
+        }
+        this.paramGroups = [];
+      } else {
+        if (groupsArray.length !== this.paramGroups.length) {
+          throw new DataValidationError("paramGroups count mismatch");
+        }
+        const seenParamIds = /* @__PURE__ */ new Set();
+        let totalParamCount = 0;
+        let sawParamIds = false;
+        let sawNoParamIds = false;
+        const nextGroups = [];
+        groupsArray.forEach((rawGroup, index) => {
+          const groupRecord = ensureRecord(rawGroup, `paramGroups[${index}]`);
+          const optionsRaw = ensureRecord(groupRecord["options"], `paramGroups[${index}].options`);
+          const options = { ...this.defaults };
+          const optionsRecord = options;
+          const defaultsRecord = { ...this.defaults };
+          for (const [key, value] of Object.entries(optionsRaw)) {
+            if (Object.hasOwn(defaultsRecord, key)) {
+              const defaultVal = defaultsRecord[key];
+              const expectedType = typeof defaultVal;
+              const actualType = typeof value;
+              if (actualType !== expectedType) {
+                throw new DataValidationError(
+                  `Type mismatch for option '${key}' in paramGroups[${index}]: expected ${expectedType}, got ${actualType}`
+                );
+              }
+              optionsRecord[key] = value;
+            }
+          }
+          const paramIdsRaw = groupRecord["paramIds"];
+          const paramsRaw = groupRecord["params"];
+          let paramIds;
+          if (paramIdsRaw !== void 0) {
+            paramIds = ensureIntegerArray(paramIdsRaw, `paramGroups[${index}].paramIds`);
+            sawParamIds = true;
+          } else {
+            sawNoParamIds = true;
+          }
+          let resolvedParams;
+          if (paramIds) {
+            for (const id of paramIds) {
+              if (id < 0 || id >= currentParamCount) {
+                throw new DataValidationError(`Invalid paramId ${id} in paramGroups`);
+              }
+              if (seenParamIds.has(id)) {
+                throw new DataValidationError(`Duplicate paramId ${id} in paramGroups`);
+              }
+              seenParamIds.add(id);
+            }
+            totalParamCount += paramIds.length;
+            resolvedParams = paramIds.map((id) => {
+              const param = currentParams[id];
+              if (!param) {
+                throw new DataValidationError(`Invalid paramId ${id} in paramGroups`);
+              }
+              return param;
+            });
+          }
+          if (paramsRaw !== void 0) {
+            if (!Array.isArray(paramsRaw)) {
+              throw new DataValidationError(`paramGroups[${index}].params must be an array`);
+            }
+            const resolvedFromParams = [];
+            let hasUnknown = false;
+            for (const paramRef of paramsRaw) {
+              const paramIndex = paramLookup.get(paramRef);
+              if (paramIndex === void 0) {
+                hasUnknown = true;
+                continue;
+              }
+              const param = currentParams[paramIndex];
+              if (!param) {
+                hasUnknown = true;
+                continue;
+              }
+              resolvedFromParams.push(param);
+            }
+            if (!hasUnknown) {
+              if (paramIds && paramIds.length !== resolvedFromParams.length) {
+                throw new DataValidationError("paramIds length does not match params length");
+              }
+              if (!resolvedParams) {
+                resolvedParams = resolvedFromParams;
+              }
+            }
+          }
+          if (!resolvedParams) {
+            throw new DataValidationError(`paramGroups[${index}] must include params or paramIds`);
+          }
+          if (paramIds === void 0) {
+            nextGroups.push({ params: resolvedParams, options });
+          } else {
+            nextGroups.push({ params: resolvedParams, options, paramIds });
+          }
+        });
+        if (sawParamIds && sawNoParamIds) {
+          throw new DataValidationError("paramIds must be provided for all parameter groups");
+        }
+        if (sawParamIds && totalParamCount !== currentParamCount) {
+          throw new DataValidationError(
+            `Parameter count mismatch: expected ${currentParamCount}, got ${totalParamCount}`
+          );
+        }
+        this.paramGroups = nextGroups.map((group) => ({
+          params: group.params,
+          options: group.options
+        }));
+      }
+    }
+    if (Object.hasOwn(stateDict, "state")) {
+      const rawState = stateDict["state"];
+      if (!Array.isArray(rawState)) {
+        throw new DataValidationError("state must be an array");
+      }
+      const stateArray = rawState;
+      this.state.clear();
+      stateArray.forEach((rawEntry, index) => {
+        const entryRecord = ensureRecord(rawEntry, `state[${index}]`);
+        if (!Object.hasOwn(entryRecord, "state")) {
+          throw new DataValidationError(`state[${index}].state is required`);
+        }
+        const entryStateValue = ensureRecord(entryRecord["state"], `state[${index}].state`);
+        if (!isStateRecord(entryStateValue)) {
+          throw new DataValidationError(`state[${index}].state must be an object`);
+        }
+        const paramIdRaw = entryRecord["paramId"];
+        const paramRaw = entryRecord["param"];
+        let resolvedParam;
+        if (paramIdRaw !== void 0) {
+          if (paramIdRaw === null || typeof paramIdRaw !== "number" || !Number.isInteger(paramIdRaw)) {
+            throw new DataValidationError(`Invalid paramId ${String(paramIdRaw)} in state`);
+          }
+          if (paramIdRaw < 0 || paramIdRaw >= currentParamCount) {
+            throw new DataValidationError(`Invalid paramId ${paramIdRaw} in state`);
+          }
+          const param = currentParams[paramIdRaw];
+          if (!param) {
+            throw new DataValidationError(`Invalid paramId ${paramIdRaw} in state`);
+          }
+          if (paramRaw !== void 0) {
+            const paramIndex = paramLookup.get(paramRaw);
+            if (paramIndex === void 0 || paramIndex !== paramIdRaw) {
+              throw new DataValidationError(`paramId ${paramIdRaw} does not match provided param`);
+            }
+          }
+          resolvedParam = param;
+        } else {
+          if (paramRaw === void 0) {
+            throw new DataValidationError("Missing param reference in state entry");
+          }
+          const paramIndex = paramLookup.get(paramRaw);
+          if (paramIndex === void 0) {
+            throw new DataValidationError("Unknown param reference in state entry");
+          }
+          const param = currentParams[paramIndex];
+          if (!param) {
+            throw new DataValidationError("Unknown param reference in state entry");
+          }
+          resolvedParam = param;
+        }
+        if (!resolvedParam) {
+          throw new DataValidationError(`Unable to resolve parameter for state[${index}]`);
+        }
+        if (!this.isState(entryStateValue)) {
+          throw new DataValidationError(`state[${index}].state has invalid structure`);
+        }
+        this.state.set(resolvedParam, entryStateValue);
+      });
+    }
+  }
+};
+
+// src/optim/_internal.ts
+function isFloatTypedArray(value) {
+  return value instanceof Float32Array || value instanceof Float64Array;
+}
+function safeArrayAccess(array, index, context) {
+  if (index < 0 || index >= array.length) {
+    throw new IndexError(`Index ${index} out of bounds [0, ${array.length}) in ${context}`, {
+      index,
+      validRange: [0, array.length - 1]
+    });
+  }
+  const value = array[index];
+  if (value === void 0) {
+    throw new DeepboxError(`Unexpected undefined at index ${index} in ${context}`);
+  }
+  return value;
+}
+function assertFiniteNonNegative(name, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new InvalidParameterError(`Invalid ${name}: ${value}`, name, value);
+  }
+}
+function assertFinitePositive(name, value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new InvalidParameterError(`Invalid ${name}: ${value} (must be > 0)`, name, value);
+  }
+}
+function assertFinite(name, value) {
+  if (!Number.isFinite(value)) {
+    throw new InvalidParameterError(`Invalid ${name}: ${value}`, name, value);
+  }
+}
+function assertInRange(name, value, min, max) {
+  if (!Number.isFinite(value) || value < min || value >= max) {
+    throw new InvalidParameterError(
+      `Invalid ${name}: ${value} (must be in range [${min}, ${max}))`,
+      name,
+      value
+    );
+  }
+}
+function assertHasGradFloat(param, optimizerName) {
+  if (!param.requiresGrad) {
+    throw new InvalidParameterError(
+      "Cannot optimize a parameter with requiresGrad=false",
+      "requiresGrad",
+      false
+    );
+  }
+  const g = param.grad;
+  if (!g) {
+    throw new NotFittedError(
+      "Cannot optimize a parameter without a gradient. Did you forget backward()?"
+    );
+  }
+  const paramData = param.tensor.data;
+  const gradData = g.data;
+  if (!isFloatTypedArray(paramData) || !isFloatTypedArray(gradData)) {
+    throw new DTypeError(
+      `${optimizerName} optimizer supports float32 and float64 parameters and gradients only`
+    );
+  }
+  if (paramData.constructor !== gradData.constructor) {
+    throw new DTypeError(
+      `${optimizerName} optimizer requires parameter and gradient dtypes to match`
+    );
+  }
+  if (param.tensor.size !== g.size) {
+    throw new ShapeError(
+      `Gradient shape must match parameter shape (param: ${param.tensor.size}, grad: ${g.size})`
+    );
+  }
+  return {
+    grad: gradData,
+    gradOffset: g.offset,
+    param: paramData,
+    paramOffset: param.tensor.offset
+  };
+}
+function assertBufferSize(buffer, expectedSize, bufferName) {
+  if (buffer.length !== expectedSize) {
+    throw new DeepboxError(
+      `State buffer size mismatch for ${bufferName}: expected ${expectedSize}, got ${buffer.length}`
+    );
+  }
+}
+
+// src/optim/optimizers/adadelta.ts
+var AdaDelta = class extends Optimizer {
+  _stepCount = 0;
+  get stepCount() {
+    return this._stepCount;
+  }
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 1,
+      rho: options.rho ?? 0.9,
+      eps: options.eps ?? 1e-6,
+      weightDecay: options.weightDecay ?? 0
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertInRange("rho", defaults.rho, 0, 1);
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  isState(state) {
+    return state["squareAvg"] instanceof Float64Array && state["accDelta"] instanceof Float64Array;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, rho, eps, weightDecay } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertInRange("rho", rho, 0, 1);
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset: gOff,
+          param: pData,
+          paramOffset: pOff
+        } = assertHasGradFloat(param, "AdaDelta");
+        const size = param.tensor.size;
+        let state = this.state.get(param);
+        if (!state) {
+          state = {
+            squareAvg: new Float64Array(size),
+            accDelta: new Float64Array(size)
+          };
+          this.state.set(param, state);
+        }
+        assertBufferSize(state.squareAvg, size, "AdaDelta squareAvg");
+        assertBufferSize(state.accDelta, size, "AdaDelta accDelta");
+        for (let i = 0; i < size; i++) {
+          const gi0 = safeArrayAccess(gradData, gOff + i, "AdaDelta gradient");
+          const pi = safeArrayAccess(pData, pOff + i, "AdaDelta parameter");
+          assertFinite("gradient", gi0);
+          assertFinite("parameter", pi);
+          const gi = weightDecay !== 0 ? gi0 + weightDecay * pi : gi0;
+          const sq = safeArrayAccess(state.squareAvg, i, "AdaDelta squareAvg");
+          const sqNew = rho * sq + (1 - rho) * gi * gi;
+          state.squareAvg[i] = sqNew;
+          const std = Math.sqrt(sqNew + eps);
+          const accD = safeArrayAccess(state.accDelta, i, "AdaDelta accDelta");
+          const rmsUpdate = Math.sqrt(accD + eps);
+          const delta = rmsUpdate / std * gi;
+          state.accDelta[i] = rho * accD + (1 - rho) * delta * delta;
+          pData[pOff + i] = pi - lr * delta;
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/adagrad.ts
+var Adagrad = class extends Optimizer {
+  _stepCount = 0;
+  get stepCount() {
+    return this._stepCount;
+  }
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 0.01,
+      eps: options.eps ?? 1e-10,
+      weightDecay: options.weightDecay ?? 0,
+      lrDecay: options.lrDecay ?? 0
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+    assertFiniteNonNegative("lr_decay", defaults.lrDecay);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  isState(state) {
+    return typeof state["step"] === "number" && state["sum"] instanceof Float64Array;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, eps, weightDecay, lrDecay } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      assertFiniteNonNegative("lr_decay", lrDecay);
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset: gOff,
+          param: pData,
+          paramOffset: pOff
+        } = assertHasGradFloat(param, "Adagrad");
+        const size = param.tensor.size;
+        const existing = this.state.get(param);
+        const state = existing ?? (() => {
+          const next = {
+            step: 0,
+            sum: new Float64Array(size)
+          };
+          this.state.set(param, next);
+          return next;
+        })();
+        assertBufferSize(state.sum, size, "Adagrad sum");
+        state.step += 1;
+        const clr = lr / (1 + (state.step - 1) * lrDecay);
+        for (let i = 0; i < size; i++) {
+          const gi0 = safeArrayAccess(gradData, gOff + i, "Adagrad gradient");
+          const pi = safeArrayAccess(pData, pOff + i, "Adagrad parameter");
+          assertFinite("gradient", gi0);
+          assertFinite("parameter", pi);
+          const gi = weightDecay !== 0 ? gi0 + weightDecay * pi : gi0;
+          const sumVal = safeArrayAccess(state.sum, i, "Adagrad sum");
+          const sumNew = sumVal + gi * gi;
+          state.sum[i] = sumNew;
+          const std = Math.sqrt(sumNew) + eps;
+          pData[pOff + i] = pi - clr * (gi / std);
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/adam.ts
+var Adam = class extends Optimizer {
+  _stepCount = 0;
+  get stepCount() {
+    return this._stepCount;
+  }
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 1e-3,
+      beta1: options.beta1 ?? 0.9,
+      beta2: options.beta2 ?? 0.999,
+      eps: options.eps ?? 1e-8,
+      weightDecay: options.weightDecay ?? 0,
+      amsgrad: options.amsgrad ?? false
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertInRange("beta1", defaults.beta1, 0, 1);
+    assertInRange("beta2", defaults.beta2, 0, 1);
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  isState(state) {
+    const hasRequired = typeof state["step"] === "number" && state["expAvg"] instanceof Float64Array && state["expAvgSq"] instanceof Float64Array;
+    if (!hasRequired) return false;
+    if (state["maxExpAvgSq"] !== void 0 && !(state["maxExpAvgSq"] instanceof Float64Array)) {
+      return false;
+    }
+    return true;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, beta1, beta2, eps, weightDecay, amsgrad } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertInRange("beta1", beta1, 0, 1);
+      assertInRange("beta2", beta2, 0, 1);
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset,
+          param: paramData,
+          paramOffset
+        } = assertHasGradFloat(param, "Adam");
+        const size = param.tensor.size;
+        const existing = this.state.get(param);
+        const state = existing ?? (() => {
+          const next = {
+            step: 0,
+            expAvg: new Float64Array(size),
+            expAvgSq: new Float64Array(size),
+            ...amsgrad ? { maxExpAvgSq: new Float64Array(size) } : {}
+          };
+          this.state.set(param, next);
+          return next;
+        })();
+        assertBufferSize(state.expAvg, size, "Adam expAvg");
+        assertBufferSize(state.expAvgSq, size, "Adam expAvgSq");
+        if (amsgrad && state.maxExpAvgSq) {
+          assertBufferSize(state.maxExpAvgSq, size, "Adam maxExpAvgSq");
+        }
+        state.step += 1;
+        const biasCorrection1 = 1 - beta1 ** state.step;
+        const biasCorrection2 = 1 - beta2 ** state.step;
+        const stepSize = lr / biasCorrection1;
+        for (let i = 0; i < size; i++) {
+          const gi0 = safeArrayAccess(gradData, gradOffset + i, "Adam gradient");
+          const pi = safeArrayAccess(paramData, paramOffset + i, "Adam parameter");
+          assertFinite("gradient", gi0);
+          assertFinite("parameter", pi);
+          const gi = weightDecay !== 0 ? gi0 + weightDecay * pi : gi0;
+          const m = safeArrayAccess(state.expAvg, i, "Adam expAvg");
+          const v = safeArrayAccess(state.expAvgSq, i, "Adam expAvgSq");
+          const mNew = beta1 * m + (1 - beta1) * gi;
+          const vNew = beta2 * v + (1 - beta2) * gi * gi;
+          state.expAvg[i] = mNew;
+          state.expAvgSq[i] = vNew;
+          let denomSq = vNew;
+          if (amsgrad) {
+            const maxBuf = state.maxExpAvgSq;
+            if (!maxBuf) {
+              throw new DeepboxError("Internal error: AMSGrad enabled but maxExpAvgSq is missing");
+            }
+            const maxV = Math.max(safeArrayAccess(maxBuf, i, "Adam maxExpAvgSq"), vNew);
+            maxBuf[i] = maxV;
+            denomSq = maxV;
+          }
+          const denom = Math.sqrt(denomSq / biasCorrection2) + eps;
+          paramData[paramOffset + i] = pi - stepSize * (mNew / denom);
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/adamw.ts
+var AdamW = class extends Optimizer {
+  /** Internal counter tracking total number of optimization steps */
+  _stepCount = 0;
+  /**
+   * Get the total number of optimization steps performed.
+   *
+   * @returns Number of steps taken
+   */
+  get stepCount() {
+    return this._stepCount;
+  }
+  /**
+   * Create a new AdamW optimizer.
+   *
+   * @param params - Iterable of parameters or parameter groups to optimize
+   * @param options - Optimization options
+   * @param options.lr - Learning rate (default: 0.001)
+   * @param options.beta1 - First moment decay rate (default: 0.9)
+   * @param options.beta2 - Second moment decay rate (default: 0.999)
+   * @param options.eps - Numerical stability constant (default: 1e-8)
+   * @param options.weightDecay - Weight decay coefficient (default: 0.01)
+   * @param options.amsgrad - Enable AMSGrad variant (default: false)
+   * @throws {InvalidParameterError} If a parameter is invalid
+   */
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 1e-3,
+      beta1: options.beta1 ?? 0.9,
+      beta2: options.beta2 ?? 0.999,
+      eps: options.eps ?? 1e-8,
+      weightDecay: options.weightDecay ?? 0.01,
+      // Higher default than Adam
+      amsgrad: options.amsgrad ?? false
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertInRange("beta1", defaults.beta1, 0, 1);
+    assertInRange("beta2", defaults.beta2, 0, 1);
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  /**
+   * Perform a single optimization step (parameter update).
+   *
+   * Implements the AdamW update rule with decoupled weight decay.
+   *
+   * @param closure - Optional closure that reevaluates the model and returns the loss
+   * @returns Loss value if closure is provided, undefined otherwise
+   */
+  isState(state) {
+    const hasRequired = typeof state["step"] === "number" && state["expAvg"] instanceof Float64Array && state["expAvgSq"] instanceof Float64Array;
+    if (!hasRequired) return false;
+    if (state["maxExpAvgSq"] !== void 0 && !(state["maxExpAvgSq"] instanceof Float64Array)) {
+      return false;
+    }
+    return true;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, beta1, beta2, eps, weightDecay, amsgrad } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertInRange("beta1", beta1, 0, 1);
+      assertInRange("beta2", beta2, 0, 1);
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      for (const param of group.params) {
+        const {
+          grad,
+          gradOffset,
+          param: pData,
+          paramOffset: pOff
+        } = assertHasGradFloat(param, "AdamW");
+        const size = param.tensor.size;
+        const existing = this.state.get(param);
+        const state = existing ?? (() => {
+          const next = {
+            step: 0,
+            expAvg: new Float64Array(size),
+            // First moment
+            expAvgSq: new Float64Array(size),
+            // Second moment
+            ...amsgrad ? { maxExpAvgSq: new Float64Array(size) } : {}
+            // AMSGrad buffer
+          };
+          this.state.set(param, next);
+          return next;
+        })();
+        assertBufferSize(state.expAvg, size, "AdamW expAvg");
+        assertBufferSize(state.expAvgSq, size, "AdamW expAvgSq");
+        if (amsgrad && state.maxExpAvgSq) {
+          assertBufferSize(state.maxExpAvgSq, size, "AdamW maxExpAvgSq");
+        }
+        state.step += 1;
+        const biasCorrection1 = 1 - beta1 ** state.step;
+        const biasCorrection2 = 1 - beta2 ** state.step;
+        const stepSize = lr / biasCorrection1;
+        for (let i = 0; i < size; i++) {
+          const gi = safeArrayAccess(grad, gradOffset + i, "AdamW gradient");
+          const pi = safeArrayAccess(pData, pOff + i, "AdamW parameter");
+          assertFinite("gradient", gi);
+          assertFinite("parameter", pi);
+          const m = safeArrayAccess(state.expAvg, i, "AdamW expAvg");
+          const v = safeArrayAccess(state.expAvgSq, i, "AdamW expAvgSq");
+          const mNew = beta1 * m + (1 - beta1) * gi;
+          const vNew = beta2 * v + (1 - beta2) * gi * gi;
+          state.expAvg[i] = mNew;
+          state.expAvgSq[i] = vNew;
+          let denomSq = vNew;
+          if (amsgrad) {
+            const maxBuf = state.maxExpAvgSq;
+            if (!maxBuf) {
+              throw new DeepboxError("Internal error: AMSGrad enabled but maxExpAvgSq is missing");
+            }
+            const maxV = Math.max(safeArrayAccess(maxBuf, i, "AdamW maxExpAvgSq"), vNew);
+            maxBuf[i] = maxV;
+            denomSq = maxV;
+          }
+          const denom = Math.sqrt(denomSq / biasCorrection2) + eps;
+          pData[pOff + i] = pi - stepSize * (mNew / denom) - lr * weightDecay * pi;
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/nadam.ts
+var Nadam = class extends Optimizer {
+  _stepCount = 0;
+  get stepCount() {
+    return this._stepCount;
+  }
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 2e-3,
+      beta1: options.beta1 ?? 0.9,
+      beta2: options.beta2 ?? 0.999,
+      eps: options.eps ?? 1e-8,
+      weightDecay: options.weightDecay ?? 0,
+      momentumDecay: options.momentumDecay ?? 4e-3
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertInRange("beta1", defaults.beta1, 0, 1);
+    assertInRange("beta2", defaults.beta2, 0, 1);
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+    assertFiniteNonNegative("momentum_decay", defaults.momentumDecay);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  isState(state) {
+    return typeof state["step"] === "number" && state["expAvg"] instanceof Float64Array && state["expAvgSq"] instanceof Float64Array && typeof state["muProduct"] === "number";
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, beta1, beta2, eps, weightDecay, momentumDecay } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertInRange("beta1", beta1, 0, 1);
+      assertInRange("beta2", beta2, 0, 1);
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      assertFiniteNonNegative("momentum_decay", momentumDecay);
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset: gOff,
+          param: pData,
+          paramOffset: pOff
+        } = assertHasGradFloat(param, "Nadam");
+        const size = param.tensor.size;
+        let state = this.state.get(param);
+        if (!state) {
+          state = {
+            step: 0,
+            expAvg: new Float64Array(size),
+            expAvgSq: new Float64Array(size),
+            muProduct: 1
+          };
+          this.state.set(param, state);
+        }
+        assertBufferSize(state.expAvg, size, "Nadam expAvg");
+        assertBufferSize(state.expAvgSq, size, "Nadam expAvgSq");
+        state.step++;
+        const t = state.step;
+        const biasCorrection2 = 1 - beta2 ** t;
+        const mu = beta1 * (1 - 0.5 * 0.96 ** (t * momentumDecay));
+        const muNext = beta1 * (1 - 0.5 * 0.96 ** ((t + 1) * momentumDecay));
+        const muProduct = state.muProduct * mu;
+        const muProductNext = muProduct * muNext;
+        state.muProduct = muProduct;
+        for (let i = 0; i < size; i++) {
+          const gi0 = safeArrayAccess(gradData, gOff + i, "Nadam gradient");
+          const pi = safeArrayAccess(pData, pOff + i, "Nadam parameter");
+          assertFinite("gradient", gi0);
+          assertFinite("parameter", pi);
+          const gi = weightDecay !== 0 ? gi0 + weightDecay * pi : gi0;
+          const m = safeArrayAccess(state.expAvg, i, "Nadam expAvg");
+          const mNew = beta1 * m + (1 - beta1) * gi;
+          state.expAvg[i] = mNew;
+          const v = safeArrayAccess(state.expAvgSq, i, "Nadam expAvgSq");
+          const vNew = beta2 * v + (1 - beta2) * gi * gi;
+          state.expAvgSq[i] = vNew;
+          const denom = Math.sqrt(vNew / biasCorrection2) + eps;
+          const mHatNext = mNew / (1 - muProductNext);
+          const gHat = gi / (1 - muProduct);
+          const mNesterov = muNext * mHatNext + (1 - mu) * gHat;
+          pData[pOff + i] = pi - lr * mNesterov / denom;
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/rmsprop.ts
+var RMSprop = class extends Optimizer {
+  /** Internal counter tracking total number of optimization steps */
+  _stepCount = 0;
+  /**
+   * Get the total number of optimization steps performed.
+   *
+   * @returns Number of steps taken
+   */
+  get stepCount() {
+    return this._stepCount;
+  }
+  /**
+   * Create a new RMSprop optimizer.
+   *
+   * @param params - Iterable of parameters or parameter groups to optimize
+   * @param options - Optimization options
+   * @param options.lr - Learning rate (default: 0.01)
+   * @param options.alpha - Smoothing constant (default: 0.99)
+   * @param options.eps - Numerical stability constant (default: 1e-8)
+   * @param options.weightDecay - Weight decay coefficient (default: 0)
+   * @param options.momentum - Momentum factor (default: 0)
+   * @param options.centered - Use centered variant (default: false)
+   * @throws {InvalidParameterError} If a parameter is invalid
+   */
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 0.01,
+      alpha: options.alpha ?? 0.99,
+      eps: options.eps ?? 1e-8,
+      weightDecay: options.weightDecay ?? 0,
+      momentum: options.momentum ?? 0,
+      centered: options.centered ?? false
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    if (!Number.isFinite(defaults.alpha) || defaults.alpha < 0 || defaults.alpha > 1) {
+      throw new InvalidParameterError(
+        `Invalid alpha: ${defaults.alpha} (must be in range [0, 1])`,
+        "alpha",
+        defaults.alpha
+      );
+    }
+    assertFinitePositive("epsilon", defaults.eps);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+    assertFiniteNonNegative("momentum value", defaults.momentum);
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+  isState(state) {
+    if (!(state["squareAvg"] instanceof Float64Array)) return false;
+    if (state["momentumBuffer"] !== void 0 && !(state["momentumBuffer"] instanceof Float64Array)) {
+      return false;
+    }
+    if (state["gradAvg"] !== void 0 && !(state["gradAvg"] instanceof Float64Array)) {
+      return false;
+    }
+    return true;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, alpha, eps, weightDecay, momentum, centered } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1) {
+        throw new InvalidParameterError(
+          `Invalid alpha: ${alpha} (must be in range [0, 1])`,
+          "alpha",
+          alpha
+        );
+      }
+      assertFinitePositive("epsilon", eps);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      assertFiniteNonNegative("momentum value", momentum);
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset: gOff,
+          param: pData,
+          paramOffset: pOff
+        } = assertHasGradFloat(param, "RMSprop");
+        const size = param.tensor.size;
+        let state = this.state.get(param);
+        if (!state) {
+          state = {
+            squareAvg: new Float64Array(size)
+          };
+          this.state.set(param, state);
+        }
+        if (momentum > 0 && !state.momentumBuffer) {
+          state.momentumBuffer = new Float64Array(size);
+        }
+        if (centered && !state.gradAvg) {
+          state.gradAvg = new Float64Array(size);
+        }
+        assertBufferSize(state.squareAvg, size, "RMSprop squareAvg");
+        if (momentum > 0 && state.momentumBuffer) {
+          assertBufferSize(state.momentumBuffer, size, "RMSprop momentumBuffer");
+        }
+        if (centered && state.gradAvg) {
+          assertBufferSize(state.gradAvg, size, "RMSprop gradAvg");
+        }
+        for (let i = 0; i < size; i++) {
+          const gi = safeArrayAccess(gradData, gOff + i, "RMSprop gradient");
+          const pi = safeArrayAccess(pData, pOff + i, "RMSprop parameter");
+          assertFinite("gradient", gi);
+          assertFinite("parameter", pi);
+          let grad = gi;
+          if (weightDecay !== 0) {
+            grad = grad + weightDecay * pi;
+          }
+          const sqAvg = safeArrayAccess(state.squareAvg, i, "RMSprop squareAvg");
+          const sqAvgNew = alpha * sqAvg + (1 - alpha) * grad * grad;
+          state.squareAvg[i] = sqAvgNew;
+          let avg = sqAvgNew;
+          if (centered) {
+            const gAvg = state.gradAvg ? safeArrayAccess(state.gradAvg, i, "RMSprop gradAvg") : 0;
+            const gAvgNew = alpha * gAvg + (1 - alpha) * grad;
+            if (state.gradAvg) state.gradAvg[i] = gAvgNew;
+            avg = sqAvgNew - gAvgNew * gAvgNew;
+          }
+          const denom = centered ? Math.sqrt(Math.max(avg, 0) + eps) : Math.sqrt(avg) + eps;
+          const normalizedGrad = grad / denom;
+          if (momentum > 0) {
+            const buf = state.momentumBuffer ? safeArrayAccess(state.momentumBuffer, i, "RMSprop momentumBuffer") : 0;
+            const bufNew = momentum * buf + normalizedGrad;
+            if (state.momentumBuffer) state.momentumBuffer[i] = bufNew;
+            pData[pOff + i] = pi - lr * bufNew;
+          } else {
+            pData[pOff + i] = pi - lr * normalizedGrad;
+          }
+        }
+      }
+    }
+    return loss;
+  }
+};
+
+// src/optim/optimizers/sgd.ts
+var SGD = class extends Optimizer {
+  /** Internal counter tracking total number of optimization steps */
+  _stepCount = 0;
+  get stepCount() {
+    return this._stepCount;
+  }
+  /**
+   * Create a new SGD optimizer.
+   *
+   * @param params - Iterable of parameters or parameter groups to optimize
+   * @param options - Optimization options
+   * @param options.lr - Learning rate (default: 0.01)
+   * @param options.momentum - Momentum factor (default: 0)
+   * @param options.dampening - Dampening for momentum (default: 0)
+   * @param options.weightDecay - Weight decay (L2 penalty) (default: 0)
+   * @param options.nesterov - Enable Nesterov momentum (default: false)
+   */
+  constructor(params, options = {}) {
+    const defaults = {
+      lr: options.lr ?? 0.01,
+      momentum: options.momentum ?? 0,
+      dampening: options.dampening ?? 0,
+      weightDecay: options.weightDecay ?? 0,
+      nesterov: options.nesterov ?? false
+    };
+    super(params, defaults);
+    assertFiniteNonNegative("learning rate", defaults.lr);
+    assertFiniteNonNegative("momentum value", defaults.momentum);
+    assertFiniteNonNegative("dampening", defaults.dampening);
+    assertFiniteNonNegative("weight_decay value", defaults.weightDecay);
+    if (defaults.nesterov && (defaults.momentum <= 0 || defaults.dampening !== 0)) {
+      throw new InvalidParameterError(
+        "Nesterov momentum requires a momentum and zero dampening",
+        "nesterov",
+        {
+          momentum: defaults.momentum,
+          dampening: defaults.dampening,
+          nesterov: defaults.nesterov
+        }
+      );
+    }
+  }
+  /**
+   * Perform a single optimization step.
+   *
+   * Implements the SGD update rule with optional momentum and weight decay.
+   *
+   * @param closure - Optional closure that reevaluates the model and returns the loss
+   * @returns Loss value if closure is provided
+   */
+  isState(state) {
+    if (state["momentumBuffer"] !== void 0 && !(state["momentumBuffer"] instanceof Float64Array)) {
+      return false;
+    }
+    return true;
+  }
+  step(closure) {
+    let loss;
+    if (closure) {
+      loss = closure();
+    }
+    this._stepCount++;
+    for (const group of this.paramGroups) {
+      const { lr, momentum, dampening, weightDecay, nesterov } = group.options;
+      assertFiniteNonNegative("learning rate", lr);
+      assertFiniteNonNegative("momentum value", momentum);
+      assertFiniteNonNegative("dampening", dampening);
+      assertFiniteNonNegative("weight_decay value", weightDecay);
+      if (nesterov && (momentum <= 0 || dampening !== 0)) {
+        throw new InvalidParameterError(
+          "Nesterov momentum requires a momentum and zero dampening",
+          "nesterov",
+          { momentum, dampening, nesterov }
+        );
+      }
+      for (const param of group.params) {
+        const {
+          grad: gradData,
+          gradOffset,
+          param: paramData,
+          paramOffset
+        } = assertHasGradFloat(param, "SGD");
+        const size = param.tensor.size;
+        let state = this.state.get(param);
+        if (!state) {
+          state = {};
+          this.state.set(param, state);
+        }
+        let momentumBuffer;
+        if (momentum !== 0) {
+          if (!state.momentumBuffer) {
+            state.momentumBuffer = new Float64Array(size);
+          }
+          momentumBuffer = state.momentumBuffer;
+        }
+        for (let i = 0; i < size; i++) {
+          const gi = safeArrayAccess(gradData, gradOffset + i, "SGD gradient");
+          const pi = safeArrayAccess(paramData, paramOffset + i, "SGD parameter");
+          assertFinite("gradient", gi);
+          assertFinite("parameter", pi);
+          let d = gi;
+          if (weightDecay !== 0) {
+            d = d + weightDecay * pi;
+          }
+          if (momentumBuffer) {
+            const bPrev = safeArrayAccess(momentumBuffer, i, "SGD momentum buffer");
+            const bNew = momentum * bPrev + (1 - dampening) * d;
+            momentumBuffer[i] = bNew;
+            d = nesterov ? d + momentum * bNew : bNew;
+          }
+          paramData[paramOffset + i] = pi - lr * d;
+        }
+      }
+    }
+    return loss;
+  }
+  /**
+   * Get the current learning rate.
+   *
+   * @param groupIdx - Parameter group index (default: 0)
+   * @returns Current learning rate
+   */
+  getLearningRate(groupIdx = 0) {
+    const group = this.paramGroups[groupIdx];
+    if (!group) {
+      throw new InvalidParameterError(
+        `Invalid group index: ${groupIdx} (valid range: [0, ${this.paramGroups.length}))`,
+        "groupIdx",
+        groupIdx
+      );
+    }
+    return group.options.lr;
+  }
+  /**
+   * Set the learning rate for all parameter groups.
+   *
+   * @param lr - New learning rate
+   */
+  setLearningRate(lr) {
+    assertFiniteNonNegative("learning rate", lr);
+    for (const group of this.paramGroups) {
+      group.options.lr = lr;
+    }
+  }
+};
+
+// src/optim/schedulers.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function resolveGroupLr(group, index) {
+  const options = isRecord2(group.options) ? group.options : void 0;
+  const lrValue = group.lr ?? options?.["lr"];
+  if (typeof lrValue !== "number" || !Number.isFinite(lrValue) || lrValue < 0) {
+    throw new InvalidParameterError(
+      `optimizer.paramGroups[${index}].lr must be finite and >= 0`,
+      `optimizer.paramGroups[${index}].lr`,
+      lrValue
+    );
+  }
+  return lrValue;
+}
+function setGroupLr(group, lr) {
+  if (isRecord2(group.options)) {
+    group.options["lr"] = lr;
+  }
+  if ("lr" in group) {
+    group.lr = lr;
+  }
+  if (!("lr" in group) && !isRecord2(group.options)) {
+    group.lr = lr;
+  }
+}
+function validateLastEpoch(value) {
+  if (!Number.isInteger(value) || value < -1) {
+    throw new InvalidParameterError("lastEpoch must be an integer >= -1", "lastEpoch", value);
+  }
+  return value;
+}
+function validateFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new InvalidParameterError(`${name} must be finite`, name, value);
+  }
+  return value;
+}
+function validatePositiveNumber(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new InvalidParameterError(`${name} must be > 0`, name, value);
+  }
+  return value;
+}
+function validatePositiveInteger(value, name) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new InvalidParameterError(`${name} must be a positive integer`, name, value);
+  }
+  return value;
+}
+function validateNonNegativeNumber(value, name) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new InvalidParameterError(`${name} must be >= 0`, name, value);
+  }
+  return value;
+}
+function validateNonNegativeInteger(value, name) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new InvalidParameterError(`${name} must be a non-negative integer`, name, value);
+  }
+  return value;
+}
+function validateOptimizer(optimizer) {
+  if (!optimizer || typeof optimizer !== "object" || !Array.isArray(optimizer.paramGroups)) {
+    throw new InvalidParameterError(
+      "optimizer must expose paramGroups array",
+      "optimizer",
+      optimizer
+    );
+  }
+  if (optimizer.paramGroups.length === 0) {
+    throw new InvalidParameterError(
+      "optimizer.paramGroups must contain at least one group",
+      "optimizer.paramGroups",
+      optimizer.paramGroups
+    );
+  }
+  for (let i = 0; i < optimizer.paramGroups.length; i++) {
+    const group = optimizer.paramGroups[i];
+    if (!group || typeof group !== "object") {
+      throw new InvalidParameterError(
+        `optimizer.paramGroups[${i}] must be an object`,
+        "optimizer.paramGroups",
+        group
+      );
+    }
+    if (!Array.isArray(group.params)) {
+      throw new InvalidParameterError(
+        `optimizer.paramGroups[${i}].params must be an array`,
+        `optimizer.paramGroups[${i}].params`,
+        group.params
+      );
+    }
+    resolveGroupLr(group, i);
+  }
+}
+function validateMilestones(milestones) {
+  if (!Array.isArray(milestones) || milestones.length === 0) {
+    throw new InvalidParameterError(
+      "milestones must be a non-empty array of non-negative integers",
+      "milestones",
+      milestones
+    );
+  }
+  const sorted = [...milestones].sort((a, b) => a - b);
+  for (let i = 0; i < sorted.length; i++) {
+    const value = sorted[i];
+    if (value === void 0 || !Number.isInteger(value) || value < 0) {
+      throw new InvalidParameterError(
+        "milestones must contain non-negative integers only",
+        "milestones",
+        milestones
+      );
+    }
+    if (i > 0) {
+      const prev = sorted[i - 1];
+      if (prev !== void 0 && value <= prev) {
+        throw new InvalidParameterError(
+          "milestones must be strictly increasing",
+          "milestones",
+          milestones
+        );
+      }
+    }
+  }
+  return sorted;
+}
+var LRScheduler = class {
+  optimizer;
+  lastEpoch;
+  baseLrs;
+  constructor(optimizer, lastEpoch = -1) {
+    validateOptimizer(optimizer);
+    this.lastEpoch = validateLastEpoch(lastEpoch);
+    this.optimizer = optimizer;
+    this.baseLrs = optimizer.paramGroups.map((group, index) => resolveGroupLr(group, index));
+  }
+  initializeFromLastEpoch(lastEpoch) {
+    const validated = validateLastEpoch(lastEpoch);
+    if (validated < 0) {
+      return;
+    }
+    this.lastEpoch = -1;
+    for (let i = 0; i <= validated; i++) {
+      this.step();
+    }
+  }
+  /**
+   * Perform a scheduler step, updating learning rates.
+   *
+   * Should be called once per epoch after the optimizer step.
+   */
+  step() {
+    this.lastEpoch++;
+    const newLrs = this.getLr();
+    for (let i = 0; i < this.optimizer.paramGroups.length; i++) {
+      const group = this.optimizer.paramGroups[i];
+      if (group) {
+        const next = newLrs[i];
+        if (next !== void 0) {
+          setGroupLr(group, next);
+        }
+      }
+    }
+  }
+  /**
+   * Get the current learning rates for all parameter groups.
+   */
+  getLastLr() {
+    return this.optimizer.paramGroups.map((group, index) => resolveGroupLr(group, index));
+  }
+  /**
+   * Get current epoch number.
+   */
+  get epoch() {
+    return this.lastEpoch;
+  }
+};
+var StepLR = class extends LRScheduler {
+  stepSize;
+  gamma;
+  constructor(optimizer, options) {
+    const stepSize = validatePositiveInteger(options.stepSize, "stepSize");
+    const gamma = validatePositiveNumber(options.gamma ?? 0.1, "gamma");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.stepSize = stepSize;
+    this.gamma = gamma;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    const factor = this.gamma ** Math.floor(this.lastEpoch / this.stepSize);
+    return this.baseLrs.map((lr) => lr * factor);
+  }
+};
+var ExponentialLR = class extends LRScheduler {
+  gamma;
+  constructor(optimizer, options) {
+    const gamma = validatePositiveNumber(options.gamma, "gamma");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.gamma = gamma;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    return this.baseLrs.map((lr) => lr * this.gamma ** this.lastEpoch);
+  }
+};
+var CosineAnnealingLR = class extends LRScheduler {
+  T_max;
+  etaMin;
+  constructor(optimizer, options) {
+    const tMax = validatePositiveInteger(options.T_max, "T_max");
+    const etaMin = validateNonNegativeNumber(options.etaMin ?? 0, "etaMin");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.T_max = tMax;
+    this.etaMin = etaMin;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    return this.baseLrs.map((baseLr) => {
+      return this.etaMin + (baseLr - this.etaMin) * (1 + Math.cos(Math.PI * this.lastEpoch / this.T_max)) / 2;
+    });
+  }
+};
+var MultiStepLR = class extends LRScheduler {
+  sortedMilestones;
+  gamma;
+  constructor(optimizer, options) {
+    const milestones = validateMilestones(options.milestones);
+    const gamma = validatePositiveNumber(options.gamma ?? 0.1, "gamma");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.sortedMilestones = milestones;
+    this.gamma = gamma;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    let numDecays = 0;
+    for (const milestone of this.sortedMilestones) {
+      if (this.lastEpoch >= milestone) {
+        numDecays++;
+      }
+    }
+    const factor = this.gamma ** numDecays;
+    return this.baseLrs.map((lr) => lr * factor);
+  }
+};
+var LinearLR = class extends LRScheduler {
+  startFactor;
+  endFactor;
+  totalIters;
+  constructor(optimizer, options) {
+    const startFactor = validatePositiveNumber(options.startFactor ?? 1 / 3, "startFactor");
+    const endFactor = validatePositiveNumber(options.endFactor ?? 1, "endFactor");
+    const totalIters = validatePositiveInteger(options.totalIters, "totalIters");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.startFactor = startFactor;
+    this.endFactor = endFactor;
+    this.totalIters = totalIters;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    if (this.lastEpoch >= this.totalIters) {
+      return this.baseLrs.map((lr) => lr * this.endFactor);
+    }
+    const factor = this.startFactor + (this.endFactor - this.startFactor) * (this.lastEpoch / this.totalIters);
+    return this.baseLrs.map((lr) => lr * factor);
+  }
+};
+var ReduceLROnPlateau = class {
+  optimizer;
+  mode;
+  factor;
+  patience;
+  threshold;
+  cooldown;
+  minLr;
+  best;
+  numBadEpochs;
+  cooldownCounter;
+  constructor(optimizer, options = {}) {
+    this.optimizer = optimizer;
+    validateOptimizer(optimizer);
+    this.mode = options.mode ?? "min";
+    if (this.mode !== "min" && this.mode !== "max") {
+      throw new InvalidParameterError("mode must be 'min' or 'max'", "mode", options.mode);
+    }
+    this.factor = validateFiniteNumber(options.factor ?? 0.1, "factor");
+    if (this.factor <= 0 || this.factor >= 1) {
+      throw new InvalidParameterError(
+        "factor must be in the interval (0, 1)",
+        "factor",
+        this.factor
+      );
+    }
+    this.patience = validateNonNegativeInteger(options.patience ?? 10, "patience");
+    this.threshold = validateNonNegativeNumber(options.threshold ?? 1e-4, "threshold");
+    this.cooldown = validateNonNegativeInteger(options.cooldown ?? 0, "cooldown");
+    this.minLr = validateNonNegativeNumber(options.minLr ?? 0, "minLr");
+    this.best = this.mode === "min" ? Infinity : -Infinity;
+    this.numBadEpochs = 0;
+    this.cooldownCounter = 0;
+  }
+  /**
+   * Check if metric improved.
+   */
+  isBetter(current) {
+    if (this.mode === "min") {
+      return current < this.best - this.threshold;
+    }
+    return current > this.best + this.threshold;
+  }
+  /**
+   * Perform a scheduler step based on the metric value.
+   *
+   * @param metric - Current value of the metric being monitored
+   */
+  step(metric) {
+    if (!Number.isFinite(metric)) {
+      throw new InvalidParameterError("metric must be finite", "metric", metric);
+    }
+    if (this.cooldownCounter > 0) {
+      this.cooldownCounter--;
+      this.numBadEpochs = 0;
+    }
+    if (this.isBetter(metric)) {
+      this.best = metric;
+      this.numBadEpochs = 0;
+    } else if (this.cooldownCounter === 0) {
+      this.numBadEpochs++;
+    }
+    if (this.numBadEpochs > this.patience) {
+      this.reduceLr();
+      this.cooldownCounter = this.cooldown;
+      this.numBadEpochs = 0;
+    }
+  }
+  /**
+   * Reduce learning rate for all parameter groups.
+   */
+  reduceLr() {
+    for (let i = 0; i < this.optimizer.paramGroups.length; i++) {
+      const group = this.optimizer.paramGroups[i];
+      if (!group) {
+        throw new InvalidParameterError(
+          `optimizer.paramGroups[${i}] is missing`,
+          "optimizer.paramGroups",
+          group
+        );
+      }
+      const currentLr = resolveGroupLr(group, i);
+      const newLr = Math.max(currentLr * this.factor, this.minLr);
+      setGroupLr(group, newLr);
+    }
+  }
+  /**
+   * Get the current learning rates for all parameter groups.
+   */
+  getLastLr() {
+    return this.optimizer.paramGroups.map((group, index) => resolveGroupLr(group, index));
+  }
+};
+var WarmupLR = class extends LRScheduler {
+  warmupEpochs;
+  afterScheduler;
+  constructor(optimizer, afterScheduler, options) {
+    const warmupEpochs = validatePositiveInteger(options.warmupEpochs, "warmupEpochs");
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.warmupEpochs = warmupEpochs;
+    this.afterScheduler = afterScheduler;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    if (this.lastEpoch < this.warmupEpochs) {
+      const factor = (this.lastEpoch + 1) / this.warmupEpochs;
+      return this.baseLrs.map((lr) => lr * factor);
+    }
+    if (this.afterScheduler) {
+      return this.afterScheduler.getLr();
+    }
+    return this.baseLrs;
+  }
+  step() {
+    super.step();
+    if (this.lastEpoch >= this.warmupEpochs && this.afterScheduler) {
+      this.afterScheduler.step();
+    }
+  }
+};
+var OneCycleLR = class extends LRScheduler {
+  maxLr;
+  totalSteps;
+  pctStart;
+  divFactor;
+  finalDivFactor;
+  annealStrategy;
+  constructor(optimizer, options) {
+    const maxLr = validatePositiveNumber(options.maxLr, "maxLr");
+    const totalSteps = validatePositiveInteger(options.totalSteps, "totalSteps");
+    const pctStart = validateFiniteNumber(options.pctStart ?? 0.3, "pctStart");
+    if (pctStart <= 0 || pctStart >= 1) {
+      throw new InvalidParameterError(
+        "pctStart must be in the interval (0, 1)",
+        "pctStart",
+        pctStart
+      );
+    }
+    const divFactor = validatePositiveNumber(options.divFactor ?? 25, "divFactor");
+    const finalDivFactor = validatePositiveNumber(options.finalDivFactor ?? 1e4, "finalDivFactor");
+    const annealStrategy = options.annealStrategy ?? "cos";
+    if (annealStrategy !== "cos" && annealStrategy !== "linear") {
+      throw new InvalidParameterError(
+        "annealStrategy must be 'cos' or 'linear'",
+        "annealStrategy",
+        annealStrategy
+      );
+    }
+    const lastEpoch = validateLastEpoch(options.lastEpoch ?? -1);
+    super(optimizer, -1);
+    this.maxLr = maxLr;
+    this.totalSteps = totalSteps;
+    this.pctStart = pctStart;
+    this.divFactor = divFactor;
+    this.finalDivFactor = finalDivFactor;
+    this.annealStrategy = annealStrategy;
+    this.initializeFromLastEpoch(lastEpoch);
+  }
+  getLr() {
+    const stepNum = this.lastEpoch;
+    const upSteps = Math.max(1, Math.floor(this.totalSteps * this.pctStart));
+    const downSteps = Math.max(1, this.totalSteps - upSteps);
+    const initialLr = this.maxLr / this.divFactor;
+    const minLr = this.maxLr / this.finalDivFactor;
+    let lr;
+    if (stepNum >= this.totalSteps) {
+      lr = minLr;
+    } else if (stepNum < upSteps) {
+      const pct = stepNum / upSteps;
+      lr = initialLr + (this.maxLr - initialLr) * pct;
+    } else {
+      const pct = (stepNum - upSteps) / downSteps;
+      if (this.annealStrategy === "cos") {
+        lr = minLr + (this.maxLr - minLr) * (1 + Math.cos(Math.PI * pct)) / 2;
+      } else {
+        lr = this.maxLr - (this.maxLr - minLr) * pct;
+      }
+    }
+    const baseRef = this.baseLrs[0] ?? 0;
+    return this.baseLrs.map((baseLr) => {
+      if (baseRef === 0) {
+        return baseLr === 0 ? 0 : lr;
+      }
+      return lr * (baseLr / baseRef);
+    });
+  }
+};
+
+export { AdaDelta, Adagrad, Adam, AdamW, CosineAnnealingLR, ExponentialLR, LRScheduler, LinearLR, MultiStepLR, Nadam, OneCycleLR, Optimizer, RMSprop, ReduceLROnPlateau, SGD, StepLR, WarmupLR, optim_exports };
+//# sourceMappingURL=chunk-PR647I7R.js.map
+//# sourceMappingURL=chunk-PR647I7R.js.map