Skip to content

Element Reference

Jump to bottom
Jgocunha edited this page Apr 10, 2026 · 6 revisions

Element Reference

All elements are created through ElementFactory::createElement(label, commonParams, specificParams). See the Elements page for the factory and common parameter details.

NeuralField

The core DNF element. Integrates its inputs over continuous time using a first-order differential equation governed by a time constant tau. The output is the activation passed through a non-linear activation function.

Label: NEURAL_FIELD

Parameters

NeuralFieldParameters{
    double tau,                              // time constant (default: 25.0)
    double startingRestingLevel,             // resting activation level (default: -5.0)
    const ActivationFunction& activationFunction  // transfer function (default: SigmoidFunction(0, 10))
}
Parameter Type Default Description
tau double 25.0 Time constant — larger values slow field dynamics
startingRestingLevel double -5.0 Activation level when no input is present
activationFunction ActivationFunction SigmoidFunction(0, 10) Non-linear transfer function applied to compute output

Activation functions

Type Parameters Description
SigmoidFunction(x_shift, steepness) x_shift=0.0, steepness=10.0 Smooth sigmoidal transfer function
HeavisideFunction(x_shift) x_shift=0.0 Binary threshold function

Components

Name Description
"activation" Current membrane activation level at each position
"output" Activation passed through the activation function
"input" Summed input from all connected elements

State & metrics

// Bump detection
std::vector<NeuralFieldBump> bumps = field->getBumps();

// Per-bump data
bump.centroid;        // center position of the bump
bump.amplitude;       // peak activation
bump.width;           // spatial extent
bump.startPosition;   // left edge
bump.endPosition;     // right edge
bump.velocity;        // centroid change rate
bump.acceleration;    // velocity change rate

// Field-level state
bool stable = field->isStable();
double lo   = field->getLowestActivation();
double hi   = field->getHighestActivation();
double thr  = field->getStabilityThreshold();

field->setThresholdForStability(0.9);

GaussKernel

A Gaussian lateral interaction kernel. Typically provides local excitation (positive amplitude) and a uniform global inhibition (amplitudeGlobal).

Label: GAUSS_KERNEL

Parameters

GaussKernelParameters{
    double width           = 3.0,
    double amplitude       = 3.0,
    double amplitudeGlobal = -0.01,
    bool   circular        = true,
    bool   normalized      = true
}
Parameter Default Description
width 3.0 Width (sigma) of the Gaussian excitatory peak
amplitude 3.0 Amplitude of the local excitation
amplitudeGlobal -0.01 Uniform global inhibition added to every position
circular true Whether the field wraps around at the boundaries
normalized true Whether the Gaussian is area-normalized

Components

Name Description
"output" Convolved lateral interaction signal
"input" Raw input from connected field

MexicanHatKernel

A Mexican Hat (difference-of-Gaussians) kernel providing short-range excitation and long-range inhibition. This is the classic kernel for producing stable localized activity bumps.

Label: MEXICAN_HAT_KERNEL

Parameters

MexicanHatKernelParameters{
    double widthExc        = 2.5,
    double amplitudeExc    = 11.0,
    double widthInh        = 5.0,
    double amplitudeInh    = 15.0,
    double amplitudeGlobal = -0.1,
    bool   circular        = true,
    bool   normalized      = true
}
Parameter Default Description
widthExc 2.5 Width of the excitatory Gaussian
amplitudeExc 11.0 Amplitude of excitation
widthInh 5.0 Width of the inhibitory Gaussian
amplitudeInh 15.0 Amplitude of inhibition
amplitudeGlobal -0.1 Uniform global inhibition
circular true Boundary wrapping
normalized true Area normalization

Components

Name Description
"output" Convolved lateral interaction signal
"input" Raw input from connected field

OscillatoryKernel

A kernel with an oscillatory (damped cosine) lateral interaction pattern. Useful for modelling travelling waves or rhythmic activity.

Label: OSCILLATORY_KERNEL

Parameters

OscillatoryKernelParameters{
    double amplitude       = 1.0,
    double decay           = 0.08,    // must be > 0
    double zeroCrossings   = 0.3,     // clamped to [0, 1]
    double amplitudeGlobal = -0.01,
    bool   circular        = true,
    bool   normalized      = false
}
Parameter Default Description
amplitude 1.0 Peak amplitude of the oscillatory kernel
decay 0.08 Exponential decay rate (must be positive)
zeroCrossings 0.3 Frequency of oscillations — controls how many zero crossings occur (clamped to [0, 1])
amplitudeGlobal -0.01 Uniform global inhibition
circular true Boundary wrapping
normalized false Area normalization

Components

Name Description
"output" Convolved oscillatory signal
"input" Raw input from connected field

AsymmetricGaussKernel

A Gaussian kernel with an asymmetric component, combining a standard Gaussian and its derivative. The asymmetry introduces a directional bias in lateral interactions, enabling travelling-wave-like dynamics.

Label: ASYMMETRIC_GAUSS_KERNEL

Parameters

AsymmetricGaussKernelParameters{
    double width           = 3.0,
    double amplitude       = 3.0,
    double amplitudeGlobal = 0.0,
    double timeShift       = 0.0,
    bool   circular        = true,
    bool   normalized      = true
}
Parameter Default Description
width 3.0 Width (sigma) of the underlying Gaussian
amplitude 3.0 Amplitude of the symmetric component
amplitudeGlobal 0.0 Uniform global inhibition
timeShift 0.0 Controls the strength of the asymmetric (derivative) component
circular true Boundary wrapping
normalized true Area normalization

Components

Name Description
"output" Convolved asymmetric signal
"input" Raw input from connected field

GaussStimulus

A static external input with a Gaussian spatial profile. Provides a fixed driving input at a specified position in the field.

Label: GAUSS_STIMULUS

Parameters

GaussStimulusParameters{
    double width      = 5.0,
    double amplitude  = 15.0,
    double position   = 50.0,
    bool   circular   = true,
    bool   normalized = false
}
Parameter Default Description
width 5.0 Width (sigma) of the Gaussian
amplitude 15.0 Peak amplitude of the stimulus
position 50.0 Center position of the Gaussian in field coordinates
circular true Boundary wrapping
normalized false Area normalization

Components

Name Description
"output" Gaussian stimulus profile (same every time step)

NormalNoise

Adds zero-mean Gaussian white noise to the field at every time step.

Label: NORMAL_NOISE

Parameters

NormalNoiseParameters{
    double amplitude = 0.2
}
Parameter Default Description
amplitude 0.2 Standard deviation of the noise distribution

Components

Name Description
"output" Random noise vector, resampled every time step

FieldCoupling

A full weight-matrix coupling between two fields of potentially different sizes. The weight matrix is initialized to zero and updated online using one of three learning rules. Weights can be saved to and loaded from disk.

Label: FIELD_COUPLING

Parameters

FieldCouplingParameters{
    ElementDimensions inputFieldDimensions,          // dimensions of the source field
    LearningRule      learningRule  = LearningRule::HEBB,
    double            scalar        = 1.0,
    double            learningRate  = 0.01
}
Parameter Default Description
inputFieldDimensions — Spatial dimensions of the source field
learningRule HEBB Learning rule used to update the weight matrix
scalar 1.0 Multiplicative scaling of the coupling output
learningRate 0.01 Step size for weight updates

Learning rules

Rule Enum Description
Hebbian LearningRule::HEBB Weights grow when pre- and post-synaptic activity co-occur
Oja's rule LearningRule::OJA Normalized Hebbian — prevents unbounded weight growth
Delta rule LearningRule::DELTA Error-correcting — drives weights toward a target

Runtime control

coupling->setLearning(true);              // enable / disable weight updates
coupling->setLearningRate(0.005);         // change learning rate on the fly
coupling->setParameters(newParams);

coupling->writeWeights();                 // save weights to disk
coupling->readWeights();                  // load weights from disk
coupling->clearWeights();                 // reset weight matrix to zero

coupling->setWeightsDirectory("path/");
std::string dir = coupling->getWeightsDirectory();

Components

Name Description
"weights" Flattened 2D weight matrix (rows = output positions, cols = input positions)
"output" Weighted sum of the source field output

GaussFieldCoupling

A coupling between two fields using a fixed set of Gaussian basis functions. Unlike FieldCoupling, the coupling profile is specified analytically and does not learn.

Label: GAUSS_FIELD_COUPLING

Parameters

GaussFieldCouplingParameters{
    ElementDimensions inputFieldDimensions,
    bool normalized = true,
    bool circular   = false,
    std::vector<GaussCoupling> couplings = {}
}

Each GaussCoupling defines one Gaussian link between positions in the two fields:

GaussCoupling{
    double x_i,        // position in the input field
    double x_j,        // position in the output field
    double amplitude,  // strength of the coupling
    double width       // width of the Gaussian
}
GaussFieldCouplingParameters params{ inputDims };
params.addCoupling(GaussCoupling{ 50.0, 50.0, 1.0, 5.0 });
params.addCoupling(GaussCoupling{ 80.0, 80.0, 1.0, 5.0 });

Components

Name Description
"weights" Flattened coupling weight matrix
"output" Weighted projection from the source field

Clone this wiki locally