Getting started

This guide takes a model from source text to validation and GPU execution. Run commands from the root of the Cognia distribution or the Sensory repository.

Requirements

The reference GPU runtime currently requires:

• Windows 10 or 11;
• an NVIDIA GPU and a compatible driver;
• CUDA Toolkit 13.2;
• MSVC from Visual Studio 2022;
• CMake and Ninja;
• OpenCV 4.12 only for the full Sensory GUI application.

The cognia validator itself is pure C++ and does not require CUDA or OpenCV at runtime.

Validate an existing model

Build the lightweight validator and inspect the minimal example:

.\make.ps1 cognia
.\cmake-build-debug\cognia.exe .\Cognia\tests\01\minimal.cognia

A successful run prints a topology summary. Syntax errors include a source location; semantic errors report invalid references, incompatible ports or unsupported combinations.

Run the topology on a GPU

.\make.ps1 cognia_run
.\cmake-build-debug\cognia_run.exe .\Cognia\tests\01\minimal.cognia

cognia_run builds the concrete graph, uploads it to a real NeuralGraph, configures its runtime properties and performs propagation. Use it to distinguish a valid source model from a GPU integration problem.

Run the full application

.\make.ps1 run -- .\Cognia\examples\hierarchy\hierarchy.cognia Hierarchy

Useful display options are --headless, --no-preview, --no-wave, --no-network and --no-text. The model file and network name can also be supplied with --file and --network.

A small model

cognia "0.2";
seed 42;

source SensorSource {
    kind: external;
    publish Input : signal;
}

neuron SensorUnit {
    state {
        activation: signal = 0.0;
        leak: float = 0.0;
        bias: float = 0.0;
        gain: float = 1.0;
    }
    input net = sum(weighted);
    output { activation = (1.0 - leak) * tanh(gain * net + bias)
                          + leak * activation; }
    emit activation;
}

neuron CoreUnit {
    state {
        activation: signal = 0.0;
        leak: float = 0.2;
        bias: float = 0.0;
        gain: float = 1.0;
    }
    input net = sum(weighted);
    output { activation = (1.0 - leak) * tanh(gain * net + bias)
                          + leak * activation; }
    emit activation;
}

module Input {
    subscribe { Input; }
    neurons { cells: SensorUnit[2]; }
}

module Readout {
    neurons { cells: CoreUnit[1]; }
}

network Minimal {
    use module Input as input;
    use module Readout as readout;
    connect input.cells -> readout.cells {
        pattern: full;
        weight: 0.5;
        plasticity: none;
    }
    output signal from readout.cells as result;
}

The version string records the language generation expected by the model. seed makes random topology expansion reproducible. The source publishes a signal consumed by the sensory module. The two modules are instantiated inside Minimal; a full connection creates two edges into the readout, and the output declaration exposes the readout to the host application.

Select a network

A file may contain several networks. If the tool cannot infer the intended one, pass its name explicitly:

.\cmake-build-debug\cognia_run.exe model.cognia MyNetwork

Common problems

• The model falls back to the legacy substrate. Use an absolute path or run from the repository root. Relative model paths are resolved from the process working directory.
• CUDA cannot find cl.exe. Build through make.ps1; it loads the Visual Studio compiler environment.
• A valid declaration has no runtime effect. Check the implementation-status page. Parsing and semantic validity do not guarantee that a feature is bridged to the runtime.
• A hierarchy appears as one layer. Runtime layers are currently inferred from distinct neuron leak values, not from graph connectivity.
• Inference forgets context. /evaluate is intentionally stateless. Use /perceive plus /step, or /feed, for a continuing sequence.

Next steps

Read the Language guide before designing a larger topology. Then use the Examples page to choose the nearest working model and change one mechanism at a time.