Skip to content

Element Reference

Jump to bottom
Jgocunha edited this page May 8, 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
AbsSigmoidFunction(x_shift, beta) x_shift=0.0, beta=10.0 Algebraic sigmoid — avoids exp; smoother than Heaviside, faster than the exponential sigmoid at very high steepness

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,
    std::optional<ElementDimensions> outputFieldDimensions = std::nullopt
}
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
outputFieldDimensions nullopt When set, the convolution output is resampled to this size — enables cross-dimension connections (see Cross-dimension kernels)

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,
    std::optional<ElementDimensions> outputFieldDimensions = std::nullopt
}
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
outputFieldDimensions nullopt When set, the convolution output is resampled to this size — enables cross-dimension connections (see Cross-dimension kernels)

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,
    std::optional<ElementDimensions> outputFieldDimensions = std::nullopt
}
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
outputFieldDimensions nullopt When set, the convolution output is resampled to this size — enables cross-dimension connections (see Cross-dimension kernels)

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,
    std::optional<ElementDimensions> outputFieldDimensions = std::nullopt
}
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 — positive values bias activity toward higher positions
circular true Boundary wrapping
normalized true Area normalization
outputFieldDimensions nullopt When set, the convolution output is resampled to this size — enables cross-dimension connections (see Cross-dimension kernels)

Components

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

Cross-dimension kernels

By default, a kernel's output is the same size as its input. Setting outputFieldDimensions in any kernel's parameters changes this: after convolution, the result is resampled to the specified size using linear interpolation. This lets a kernel act as a bridge between two neural fields that have different spatial resolutions.

When to use it

  • Downsampling: a high-resolution perceptual field (e.g., 200 positions) feeding a lower-resolution decision field (e.g., 100 positions).
  • Upsampling: a compact motor-command field projecting back onto a larger sensory field.
  • Resolution mismatch: any architecture where two fields operate at different spatial scales.

Code example

// Field 200 → GaussKernel (in=200, out=100) → Field 100
GaussKernelParameters gkp{ 3.0, 3.0, -0.01, true, true,
                            ElementDimensions{ 100 } };   // output size

auto fieldSrc = makeField("src", 200);
auto kernel   = std::make_shared<GaussKernel>(ElementCommonParameters{"k", 200}, gkp);
auto fieldDst = makeField("dst", 100);

kernel->addInput(fieldSrc);    // src output (size 200) → kernel input (size 200)
fieldDst->addInput(kernel);    // kernel output (size 100) → dst input (size 100)

The same outputFieldDimensions parameter is available on MexicanHatKernel, OscillatoryKernel, and AsymmetricGaussKernel.

Square mode (default)

When outputFieldDimensions is nullopt (the default), the kernel output is the same size as its input — no resampling occurs. Setting outputFieldDimensions to a size equal to the input size is equivalent to leaving it unset.

Changing output size at runtime

In the Element Control panel, select a kernel and edit the Output Size and Output Step fields. Committing the value (Enter or focus-loss) rebuilds the kernel and severs any existing connections, since the element graph's dimension contract changes. Reconnect the kernel to fields of the correct sizes afterwards.

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

BoostStimulus

A spatially uniform external input — the same constant value is added to every position of a connected field. Unlike GaussStimulus (which is spatially localized), BoostStimulus raises or lowers the entire field's activation level, making it useful for global gain control, resting-level shifts, or task-condition gating.

Label: BOOST_STIMULUS

Parameters

BoostStimulusParameters{
    double amplitude = 5.0,
    bool   isActive  = true
}
Parameter Default Description
amplitude 5.0 Constant value broadcast to all field positions
isActive true When false the output is zeroed — acts as an on/off gate

Components

Name Description
"output" Uniform vector of amplitude (or zeros when inactive)

Usage note

setParameters() calls init() internally, so the output vector is updated immediately — no need to wait for the next step() call.

MemoryTrace

A second-layer dynamics element that accumulates a persistent trace of supra-threshold neural field activity. It builds up slowly where the connected field is active and decays slowly everywhere else, producing a representation of the history of peak activations.

Label: MEMORY_TRACE

Dynamics

At each time step the trace follows a dual-rate Euler integration:

if input[i] > threshold:
    output[i] += deltaT * (1/tauBuild) * (-output[i] + input[i])   // builds toward input
else:
    output[i] += deltaT * (1/tauDecay) * (-output[i])              // decays toward 0

The trace should receive the sigmoid output ("output" component) of a NeuralField as its input, not the raw activation, so that the threshold check operates on an already-thresholded signal.

Parameters

MemoryTraceParameters{
    double tauBuild  = 100.0,
    double tauDecay  = 1000.0,
    double threshold = 0.5
}
Parameter Default Description
tauBuild 100.0 Time constant for building the trace at active locations — smaller values make the trace grow faster
tauDecay 1000.0 Time constant for decay at inactive locations — larger values make the trace persist longer
threshold 0.5 Input level above which a location is considered active and the trace builds; below it the trace decays

Both time constants should be much larger than the neural field's tau (typically 20–100) so that the trace evolves on a slower, learning timescale.

Components

Name Description
"output" Accumulated memory trace at each field position (values in [0, 1] when driven by sigmoid output)
"input" Summed input from connected elements

Typical wiring

// Field output drives the trace; trace feeds back into the field as a weak excitatory input
memTrace->addInput(field, "output");   // trace reads sigmoid output of the field
field->addInput(memTrace);             // field receives the trace as input (scaled by a coupling)

Usage note

setParameters() does not call init() — the accumulated trace is preserved when parameters are changed at runtime. Call init() explicitly if you want to reset the trace to zero.

Clone this wiki locally