@reicek/neataptic-ts 0.1.21 → 0.1.23

package/src/architecture/network.ts

@@ -49,12 +49,76 @@ import type {
   NetworkArchitectureDescriptor,
   ConnectionWeightNoiseProps,
   MutationMethod,
+  NetworkConstructorOptions,
   NetworkRuntimeProps,
+  NetworkTopologyIntent,
   RNGSnapshot,
   SerializedConnection,
   TrainingOptions,
 } from './network/network.types';
 
+/**
+ * Resolves the public topology intent for one constructor call.
+ *
+ * @param options Optional constructor options.
+ * @returns Resolved topology intent.
+ */
+function resolveTopologyIntent(
+  options?: NetworkConstructorOptions,
+): NetworkTopologyIntent {
+  if (options?.topologyIntent) {
+    return options.topologyIntent;
+  }
+
+  return options?.enforceAcyclic ? 'feed-forward' : 'unconstrained';
+}
+
+/**
+ * Validates that legacy acyclic flags do not contradict public topology intent.
+ *
+ * @param options Optional constructor options.
+ * @returns Nothing.
+ */
+function validateTopologyIntentConfiguration(
+  options?: NetworkConstructorOptions,
+): void {
+  if (
+    options?.topologyIntent === 'feed-forward' &&
+    options.enforceAcyclic === false
+  ) {
+    throw new Error(
+      'Conflicting topology options: feed-forward intent cannot disable acyclic enforcement.',
+    );
+  }
+
+  if (
+    options?.topologyIntent === 'unconstrained' &&
+    options.enforceAcyclic === true
+  ) {
+    throw new Error(
+      'Conflicting topology options: unconstrained intent cannot enable acyclic enforcement.',
+    );
+  }
+}
+
+/**
+ * Resolves whether acyclic enforcement should be enabled for one constructor call.
+ *
+ * @param options Optional constructor options.
+ * @param topologyIntent Resolved public topology intent.
+ * @returns True when acyclic enforcement should be enabled.
+ */
+function resolveAcyclicEnforcement(
+  options: NetworkConstructorOptions | undefined,
+  topologyIntent: NetworkTopologyIntent,
+): boolean {
+  if (typeof options?.enforceAcyclic === 'boolean') {
+    return options.enforceAcyclic;
+  }
+
+  return topologyIntent === 'feed-forward';
+}
+
 /**
  * Network (Evolvable / Trainable Graph)
  * =====================================
@@ -182,6 +246,8 @@ export default class Network implements NetworkView {
   private _initialConnectionCount?: number;
   /** Whether to enforce acyclic connectivity. */
   private _enforceAcyclic: boolean = false;
+  /** Public topology intent used to preserve semantic API choices. */
+  private _topologyIntent: NetworkTopologyIntent = 'unconstrained';
   /** Cached topological order. */
   private _topoOrder: Node[] | null = null;
   /** Topology dirty marker. */
@@ -254,20 +320,20 @@ export default class Network implements NetworkView {
   constructor(
     input: number,
     output: number,
-    options?: {
-      minHidden?: number;
-      seed?: number;
-      enforceAcyclic?: boolean;
-      activationPrecision?: 'f32' | 'f64';
-      reuseActivationArrays?: boolean;
-      returnTypedActivations?: boolean;
-    },
+    options?: NetworkConstructorOptions,
   ) {
     // Validate that input and output sizes are provided.
     if (typeof input === 'undefined' || typeof output === 'undefined') {
       throw new Error('No input or output size given');
     }
 
+    // Step 1: Validate constructor topology semantics before mutating runtime state.
+    validateTopologyIntentConfiguration(options);
+
+    // Step 2: Resolve the public topology contract and the low-level acyclic flag.
+    const topologyIntent = resolveTopologyIntent(options);
+    const enforceAcyclic = resolveAcyclicEnforcement(options, topologyIntent);
+
     // Initialize network properties
     this.input = input;
     this.output = output;
@@ -276,7 +342,8 @@ export default class Network implements NetworkView {
     this.gates = [];
     this.selfconns = [];
     this.dropout = 0;
-    this._enforceAcyclic = options?.enforceAcyclic || false;
+    this._topologyIntent = topologyIntent;
+    this._enforceAcyclic = enforceAcyclic;
     if (options?.activationPrecision) {
       this._activationPrecision = options.activationPrecision;
     } else if (config.float32Mode) {
@@ -467,13 +534,46 @@ export default class Network implements NetworkView {
     this._dropConnectProb = 0;
   }
 
+  /**
+   * Returns the public topology intent for this network.
+   *
+   * @returns Current topology intent.
+   */
+  getTopologyIntent(): NetworkTopologyIntent {
+    return this._topologyIntent;
+  }
+
+  /**
+   * Sets the public topology intent and keeps acyclic enforcement aligned.
+   *
+   * @param topologyIntent Desired topology intent.
+   * @returns Nothing.
+   */
+  setTopologyIntent(topologyIntent: NetworkTopologyIntent): void {
+    // Step 1: Persist the public topology contract.
+    this._topologyIntent = topologyIntent;
+
+    // Step 2: Keep the low-level acyclic guard aligned with the public contract.
+    this._enforceAcyclic = topologyIntent === 'feed-forward';
+
+    // Step 3: Mark topology caches dirty so later activation rebuilds coherent state.
+    this._topoDirty = true;
+  }
+
   /**
    * Enable or disable acyclic topology enforcement.
    *
    * @param flag Whether to enforce acyclic connectivity.
    */
-  setEnforceAcyclic(flag: boolean) {
+  setEnforceAcyclic(flag: boolean): void {
+    // Step 1: Preserve backward compatibility for callers using the legacy toggle.
     this._enforceAcyclic = !!flag;
+
+    // Step 2: Keep the public topology intent synchronized with the active runtime contract.
+    this._topologyIntent = flag ? 'feed-forward' : 'unconstrained';
+
+    // Step 3: Mark topology caches dirty so acyclic mode changes rebuild ordering safely.
+    this._topoDirty = true;
   }
 
   /**
@@ -1618,6 +1718,10 @@ export default class Network implements NetworkView {
     // Rebuild net.connections from all per-node connections
     net.connections = net.nodes.flatMap((n) => n.connections.out);
     net._topoDirty = true;
+
+    // Step 1: Preserve the public feed-forward contract for layered MLP builders.
+    net.setTopologyIntent('feed-forward');
+
     return net;
   }
 

package/src/methods/README.md

@@ -28,10 +28,6 @@ rounded network outputs (thresholded at 0.5) against the target labels.
 It assumes target values are 0 or 1, and outputs are probabilities between 0 and 1.
 Note: This is equivalent to `1 - accuracy` for binary classification.
 
-Parameters:
-- `` - - An array of target values, expected to be 0 or 1.
-- `` - - An array of output values from the network, typically probabilities between 0 and 1.
-
 Returns: The proportion of misclassified samples (error rate, between 0 and 1).
 
 #### crossEntropy
@@ -47,10 +43,6 @@ predicted probability diverges from the actual label.
 It uses a small epsilon (PROB_EPSILON = 1e-15) to prevent `log(0)` which would result in `NaN`.
 Output values are clamped to the range `[epsilon, 1 - epsilon]` for numerical stability.
 
-Parameters:
-- `` - - An array of target values, typically 0 or 1 for binary classification, or probabilities for soft labels.
-- `` - - An array of output values from the network, representing probabilities (expected to be between 0 and 1).
-
 Returns: The mean cross-entropy error over all samples.
 
 #### focalLoss
@@ -60,12 +52,6 @@ Returns: The mean cross-entropy error over all samples.
 Calculates the Focal Loss, which is useful for addressing class imbalance in classification tasks.
 Focal loss down-weights easy examples and focuses training on hard negatives.
 
-Parameters:
-- `` - - Array of target values (0 or 1 for binary, or probabilities for soft labels).
-- `` - - Array of predicted probabilities (between 0 and 1).
-- `` - - Focusing parameter (default 2).
-- `` - - Balancing parameter (default 0.25).
-
 Returns: The mean focal loss.
 
 #### hinge
@@ -79,10 +65,6 @@ Hinge loss is used for training classifiers. It penalizes predictions that are
 not only incorrect but also those that are correct but not confident (i.e., close to the decision boundary).
 Assumes target values are encoded as -1 or 1.
 
-Parameters:
-- `` - - An array of target values, expected to be -1 or 1.
-- `` - - An array of output values from the network (raw scores, not necessarily probabilities).
-
 Returns: The mean hinge loss.
 
 #### labelSmoothing
@@ -92,11 +74,6 @@ Returns: The mean hinge loss.
 Calculates the Cross Entropy with Label Smoothing.
 Label smoothing prevents the model from becoming overconfident by softening the targets.
 
-Parameters:
-- `` - - Array of target values (0 or 1 for binary, or probabilities for soft labels).
-- `` - - Array of predicted probabilities (between 0 and 1).
-- `` - - Smoothing factor (between 0 and 1, e.g., 0.1).
-
 Returns: The mean cross-entropy loss with label smoothing.
 
 #### mae
@@ -108,10 +85,6 @@ Calculates the Mean Absolute Error (MAE), another common loss function for regre
 MAE measures the average of the absolute differences between predictions and actual values.
 Compared to MSE, it is less sensitive to outliers because errors are not squared.
 
-Parameters:
-- `` - - An array of target numerical values.
-- `` - - An array of output values from the network.
-
 Returns: The mean absolute error.
 
 #### mape
@@ -125,10 +98,6 @@ for understanding the error relative to the magnitude of the target values.
 However, it has limitations: it's undefined when the target value is zero and
 can be skewed by target values close to zero.
 
-Parameters:
-- `` - - An array of target numerical values. Should not contain zeros for standard MAPE.
-- `` - - An array of output values from the network.
-
 Returns: The mean absolute percentage error, expressed as a proportion (e.g., 0.1 for 10%).
 
 #### mse
@@ -141,10 +110,6 @@ MSE measures the average of the squares of the errors—that is, the average
 squared difference between the estimated values and the actual value.
 It is sensitive to outliers due to the squaring of the error terms.
 
-Parameters:
-- `` - - An array of target numerical values.
-- `` - - An array of output values from the network.
-
 Returns: The mean squared error.
 
 #### msle
@@ -159,10 +124,6 @@ It measures the squared difference between the logarithms of the predicted and a
 Uses `log(1 + x)` instead of `log(x)` for numerical stability and to handle inputs of 0.
 Assumes both targets and outputs are non-negative.
 
-Parameters:
-- `` - - An array of target numerical values (assumed >= 0).
-- `` - - An array of output values from the network (assumed >= 0).
-
 Returns: The mean squared logarithmic error.
 
 #### softmaxCrossEntropy
@@ -382,10 +343,6 @@ rounded network outputs (thresholded at 0.5) against the target labels.
 It assumes target values are 0 or 1, and outputs are probabilities between 0 and 1.
 Note: This is equivalent to `1 - accuracy` for binary classification.
 
-Parameters:
-- `` - - An array of target values, expected to be 0 or 1.
-- `` - - An array of output values from the network, typically probabilities between 0 and 1.
-
 Returns: The proportion of misclassified samples (error rate, between 0 and 1).
 
 #### cosineAnnealing
@@ -434,10 +391,6 @@ predicted probability diverges from the actual label.
 It uses a small epsilon (PROB_EPSILON = 1e-15) to prevent `log(0)` which would result in `NaN`.
 Output values are clamped to the range `[epsilon, 1 - epsilon]` for numerical stability.
 
-Parameters:
-- `` - - An array of target values, typically 0 or 1 for binary classification, or probabilities for soft labels.
-- `` - - An array of output values from the network, representing probabilities (expected to be between 0 and 1).
-
 Returns: The mean cross-entropy error over all samples.
 
 #### exp
@@ -482,12 +435,6 @@ Returns: A function that takes the base learning rate and the current iteration
 Calculates the Focal Loss, which is useful for addressing class imbalance in classification tasks.
 Focal loss down-weights easy examples and focuses training on hard negatives.
 
-Parameters:
-- `` - - Array of target values (0 or 1 for binary, or probabilities for soft labels).
-- `` - - Array of predicted probabilities (between 0 and 1).
-- `` - - Focusing parameter (default 2).
-- `` - - Balancing parameter (default 0.25).
-
 Returns: The mean focal loss.
 
 #### hinge
@@ -501,10 +448,6 @@ Hinge loss is used for training classifiers. It penalizes predictions that are
 not only incorrect but also those that are correct but not confident (i.e., close to the decision boundary).
 Assumes target values are encoded as -1 or 1.
 
-Parameters:
-- `` - - An array of target values, expected to be -1 or 1.
-- `` - - An array of output values from the network (raw scores, not necessarily probabilities).
-
 Returns: The mean hinge loss.
 
 #### inv
@@ -534,11 +477,6 @@ Returns: A function that calculates the inversely decayed learning rate for a gi
 Calculates the Cross Entropy with Label Smoothing.
 Label smoothing prevents the model from becoming overconfident by softening the targets.
 
-Parameters:
-- `` - - Array of target values (0 or 1 for binary, or probabilities for soft labels).
-- `` - - Array of predicted probabilities (between 0 and 1).
-- `` - - Smoothing factor (between 0 and 1, e.g., 0.1).
-
 Returns: The mean cross-entropy loss with label smoothing.
 
 #### linearWarmupDecay
@@ -563,10 +501,6 @@ Calculates the Mean Absolute Error (MAE), another common loss function for regre
 MAE measures the average of the absolute differences between predictions and actual values.
 Compared to MSE, it is less sensitive to outliers because errors are not squared.
 
-Parameters:
-- `` - - An array of target numerical values.
-- `` - - An array of output values from the network.
-
 Returns: The mean absolute error.
 
 #### mape
@@ -580,10 +514,6 @@ for understanding the error relative to the magnitude of the target values.
 However, it has limitations: it's undefined when the target value is zero and
 can be skewed by target values close to zero.
 
-Parameters:
-- `` - - An array of target numerical values. Should not contain zeros for standard MAPE.
-- `` - - An array of output values from the network.
-
 Returns: The mean absolute percentage error, expressed as a proportion (e.g., 0.1 for 10%).
 
 #### mse
@@ -596,10 +526,6 @@ MSE measures the average of the squares of the errors—that is, the average
 squared difference between the estimated values and the actual value.
 It is sensitive to outliers due to the squaring of the error terms.
 
-Parameters:
-- `` - - An array of target numerical values.
-- `` - - An array of output values from the network.
-
 Returns: The mean squared error.
 
 #### msle
@@ -614,10 +540,6 @@ It measures the squared difference between the logarithms of the predicted and a
 Uses `log(1 + x)` instead of `log(x)` for numerical stability and to handle inputs of 0.
 Assumes both targets and outputs are non-negative.
 
-Parameters:
-- `` - - An array of target numerical values (assumed >= 0).
-- `` - - An array of output values from the network (assumed >= 0).
-
 Returns: The mean squared logarithmic error.
 
 #### reduceOnPlateau
@@ -703,7 +625,7 @@ but can slow down the search process.
 
 ### registerCustomActivation
 
-`(activationName: string, activationFunction: import("C:/NeatapticTS/src/methods/activation.utils").ActivationFunction) => void`
+`(activationName: string, activationFunction: import("src/methods/activation.utils").ActivationFunction) => void`
 
 ## methods/connection.ts
 
@@ -935,7 +857,7 @@ Useful for any stateless schedule strategy.
 
 ### createCosineAnnealingRateSchedule
 
-`(period: number, minimumRate: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(period: number, minimumRate: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns a cosine annealing learning rate schedule.
 
@@ -947,7 +869,7 @@ Returns: A learning rate schedule implementing cosine annealing.
 
 ### createCosineAnnealingWarmRestartsSchedule
 
-`(initialPeriod: number, minimumRate: number, periodGrowthMultiplier: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(initialPeriod: number, minimumRate: number, periodGrowthMultiplier: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns a cosine annealing schedule with warm restarts and growing cycles.
 
@@ -960,7 +882,7 @@ Returns: A learning rate schedule implementing SGDR-style warm restarts.
 
 ### createExponentialRateSchedule
 
-`(decayFactor: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(decayFactor: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns an exponential decay learning rate schedule.
 
@@ -971,7 +893,7 @@ Returns: A learning rate schedule implementing exponential decay.
 
 ### createFixedRateSchedule
 
-`() => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`() => import("src/methods/rate.utils").RateSchedule`
 
 Returns a schedule that always yields the base learning rate.
 
@@ -979,7 +901,7 @@ Returns: A learning rate schedule that ignores iteration and returns baseRate.
 
 ### createInverseRateSchedule
 
-`(decayFactor: number, decayPower: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(decayFactor: number, decayPower: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns an inverse decay learning rate schedule.
 
@@ -991,7 +913,7 @@ Returns: A learning rate schedule implementing inverse decay.
 
 ### createLinearWarmupDecaySchedule
 
-`(totalStepCount: number, warmupStepCount: number | undefined, endRate: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(totalStepCount: number, warmupStepCount: number | undefined, endRate: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns a linear warmup followed by linear decay schedule.
 
@@ -1004,7 +926,7 @@ Returns: A learning rate schedule implementing warmup then decay.
 
 ### createReduceOnPlateauSchedule
 
-`(options: { factor?: number | undefined; patience?: number | undefined; minDelta?: number | undefined; cooldown?: number | undefined; minRate?: number | undefined; verbose?: boolean | undefined; } | undefined) => import("C:/NeatapticTS/src/methods/rate.utils").ReduceOnPlateauSchedule`
+`(options: { factor?: number | undefined; patience?: number | undefined; minDelta?: number | undefined; cooldown?: number | undefined; minRate?: number | undefined; verbose?: boolean | undefined; } | undefined) => import("src/methods/rate.utils").ReduceOnPlateauSchedule`
 
 Returns a ReduceLROnPlateau-style schedule that lowers the rate when no improvement is seen.
 
@@ -1015,7 +937,7 @@ Returns: A stateful schedule that reacts to lack of improvement.
 
 ### createStepRateSchedule
 
-`(decayFactor: number, decayStepSize: number) => import("C:/NeatapticTS/src/methods/rate.utils").RateSchedule`
+`(decayFactor: number, decayStepSize: number) => import("src/methods/rate.utils").RateSchedule`
 
 Returns a step decay learning rate schedule.