Stimulus propagation

RODENT separates three questions that are easy to confuse:

1. Is a source configured and active at this simulation step?
2. What reaches the rat after distance, walls, doors, material, and time are taken into account?
3. What does the selected controller do with that observation?

Source configuration and protocol
                |
                v
Propagation field at fixed step
                |
                v
Local samples at the rat
                |
                v
Built-in or researcher controller
                |
                v
Collision-limited movement and recorded result

This separation lets the built-in rat, a Python model, and a browser ONNX model receive the same local environment without requiring the same behaviour.

Source and schedule contract

Every source has a stable ID, type, floor-plane position, radius, intensity, enabled state, and active state. Protocol entries switch a source at an exact simulation step. The stimulus plugin runs before the controller, so the controller sees the field for the current step. The recorder runs afterward and stores the observation, response, and resulting movement.

Calculations use fixed simulated time rather than browser frame time. A run at 1x and one at 100x therefore use the same source schedule and field values at a given step.

Shared observation

For every source, the observation contains:

• source ID and type;
• configured position, radius, level, and source intensity;
• distance from the rat;
• normalized exposure from 0 to 1;
• distance and geometry falloff;
• direct and reflected shares where applicable;
• number of walls crossed and whether line of sight is clear;
• direction from which the stimulus appears to arrive; and
• the current door-state map.

Per-type light, sound, and odour totals combine multiple source exposures as:

combined = 1 - (1 - source A) × (1 - source B) × ...

This grows as sources are added but remains between zero and one. Arrival directions are exposure-weighted. The observation schema is versioned so a research model can refuse an incompatible release instead of silently reading values in the wrong order.

Light propagation

Floor lights

Floor-light direct intensity decreases with travelled distance and reaches zero at the configured radius. Every crossed wall multiplies that path by the wall material's light-transmission value. An open doorway is a gap, so it does not attenuate the path.

The engine also considers one reflection from reachable wall faces. The reflected share is weighted by path length, the reflecting material's reflectance, and transmission along both parts of the path. Direct and reflected shares add together and are capped at one.

Configured lux is normalized against properties.response_reference, which is 1000 lux by default. This gives the controller a stable zero-to-one response value. It is not a claim that a display, virtual lamp, or uncalibrated arena matches laboratory lux measurements.

Overhead lights

An overhead light uses height_cm and beam_angle. The current defaults are 40 cm and 120 degrees. It is brightest directly below the lamp and fades with distance, the cone edge, and approximately the cube of the cosine of the angle from vertical. This represents longer travel and light spreading across more floor at an angle.

The visibility check uses a 2 cm eye height and the configured wall height. A wall shades a point only when the line from lamp to eye intersects the wall below its top. A covered room blocks light through its roof. Overhead light does not use the one-bounce floor-light reflection path.

The 3D lamp and field overlay communicate placement and approximate spread. The simulation value comes from the propagation calculation, not pixel brightness or a screenshot.

Sound attenuation

Sound gain fades with path distance to zero at its radius. Each crossed wall multiplies the remaining value by that material's sound-transmission factor. Open doorway gaps do not attenuate the direct route. The source direction is reported to the controller.

This is a deterministic attenuation model. It does not simulate frequency bands, diffraction, interference, reverberation, or a measured acoustic transfer function. A researcher should calibrate or replace it before making acoustic claims.

Odour diffusion

Odour is a time-dependent gas field rather than an instant distance circle. Each source creates a grid over the arena floor, with about 40 cells along the longer arena dimension. Concentration is stored per square centimetre so changing grid resolution does not redefine the amount of gas.

At each fixed step:

1. An active source adds gas to its cell.
2. Concentration flows between neighbouring cells according to the local difference and diffusion coefficient.
3. Walls reduce transfer according to material transmission; open doorways let it flow freely.
4. Exponential decay removes gas over simulated time.

The default parameters are:

Property	Default	Meaning
intensity	0.5	Normalized source strength when no release rate is supplied.
release_rate	intensity × 20	Gas released per simulated second.
gas_density	1.0	Density relative to air.
diffusion	12 cm²/s	Base spread rate.
decay_per_second	0.02	Base loss rate.
detection_reference	0.3	Concentration used to normalize exposure.

Heavy gas increases floor-plane diffusion and reduces loss. Light gas keeps the base diffusion but gains an extra loss term because it rises away from the floor. To keep the explicit numerical method stable, a long fixed step is split into short substeps internally.

The conductance through a wall is:

0.08 × material odour transmission

Outer walls retain gas. Opening a door changes subsequent flow, but it does not teleport gas that has already accumulated. That is why two heat maps with the same source but different simulation times can look different.

The rat's normalized odour exposure is:

1 - exp(-concentration / detection_reference)

Exposure is about 0.63 at the reference concentration and approaches one in a thicker cloud. The controller also receives the uphill concentration direction, calculated from nearby field samples, so a model can follow a gradient around walls and through doors.

Material effects

These are the built-in propagation defaults. An experiment can override them in its material data.

Material	Light reflection	Light transmission	Sound transmission	Odour transmission
Solid floor	0.35	0.00	0.30	0.40
Rubber	0.05	0.00	0.15	0.35
Wire mesh	0.15	0.60	0.90	0.95
Wood chip	0.25	0.00	0.40	0.50
Painted steel	0.60	0.00	0.20	0.30
Clear acrylic	0.08	0.85	0.35	0.30

The values are software assumptions chosen to produce distinguishable, repeatable paths. They are not certified measurements of real specimens.

From exposure to built-in behaviour

The built-in baseline uses visible default preferences:

Type	Preference	Steering gain	Speed change
Light	-0.45	0.55	+0.10
Odour	+0.55	0.55	+0.05
Sound	-0.35	0.45	+0.15

A positive preference attracts the baseline toward the apparent source; a negative preference steers away. Per-source signed steering is:

exposure × preference × steering gain

The contributions are combined into a response vector. Steering is capped, speed is adjusted, and the complete contribution map and dominant source are recorded. Researchers may override the values or disable this response in controller.stimulus_response.

These rules make stimulus effects measurable and testable. They are not a model of universal rat behaviour. A researcher-supplied controller may respond differently or ignore a field entirely.

Model observation

The training and browser-model observation has 31 ordered values:

• six body values;
• eight wall and closed-door distance rays plus wall contact;
• five values each for light, sound, and odour: centre intensity, left sample, right sample, and sine/cosine of arrival direction relative to heading; and
• episode progress.

Left and right samples are taken 2 cm from the rat. Wall rays extend up to 50 cm. The same schema is used by the Python environment and website ONNX driver.

Recording and researcher metrics

The full recorder keeps the exact source observation and controller response for each step. It also calculates:

• total distance and mean movement speed;
• region dwell steps and seconds;
• first exposure step for each source;
• steps exposed, mean exposure, maximum exposure, and exposure area under the time curve;
• number of affected steps;
• mean, maximum, and cumulative response magnitude; and
• how often each source was dominant.

JSON retains nested source detail. CSV includes source exposure, response magnitude, dominant stimulus, treatment events, and interventions in each row. Headless summary_only mode retains aggregate metrics without storing every replay frame.

Visual overlays

The 3D spread overlays help a researcher understand configured reach, shadows, wall transmission, and odour development. They are inspection aids. Analysis must use recorded field values rather than measuring colours or pixels from the render.

Automated evidence

The merged application contains headless tests for:

• scheduled activation at the intended fixed step;
• light distance falloff, reflection, material transmission, overhead cones, wall shadows, and covered rooms;
• sound and odour transmission through different wall materials and door states;
• odour release, diffusion, decay, density, concentration, and gradient;
• local left, centre, and right model samples;
• built-in steering and speed response;
• exposure and response summary metrics;
• JSON and CSV recording; and
• deterministic fingerprints for the supplied baseline.

See Automated testing, Results, and the Complete feature reference.

AI Attribution: This page was prepared with OpenAI Codex assistance by tracing the merged propagation, odour field, controller, recorder, renderer, and automated tests. Scientific calibration remains the researcher's responsibility.