Instinct JCAS

A configurable simulator for Joint Communication and Sensing (JCAS) networks on a toroidal domain — stochastic-geometry deployments, mobility, physical channel models, and Kalman-filter object tracking.

Link to the Github repo. The simulator runs from the notebook main.ipynb or as a Streamlit web app (simulator_interface.py). Developed within the EU-funded INSTINCT project.

This project provides a configurable simulator for Joint Communication and Sensing (JCAS) networks defined on a periodic (toroidal) spatial domain. Base stations, mobile user equipments and sensing objects are placed on a rectangular flat torus, where a Voronoi tessellation defines cell coverage; the periodic geometry removes boundary effects and yields unbiased spatial statistics. Deployments are drawn from Poisson or Binomial point processes, with users and targets placed either uniformly or as a Gaussian cluster around the serving base station.

JCAS network realization and Voronoi tessellation
A single network realization on the flat torus — BS, UE and SO — with the induced Voronoi tessellation that defines cell coverage.

Communication is modelled through Lindley queues with SINR-dependent service rates, over either a ray-traced channel parameterised from a University of Oulu ray-tracing campaign or a Rayleigh-fading power-law model. User equipments and sensing objects move under stationary, Gauss–Markov, or ρ-persistent random-walk motion, and targets are tracked with Kalman / Extended Kalman filters for linear and radar-style (range, bearing, range rate) observations. Optional sector beamforming and a cyclic TDD communication/sensing schedule are supported.

The simulator reports coupling metrics — an association ratio A(X, Y) = E[XY] / (E[X]·E[Y]) and the Pearson correlation, for the interference, SINR and queue-versus-covariance pairs — that quantify the trade-off between the communication and sensing functions sharing the same infrastructure. Two operation modes are available: the full large-scale simulator, and a non-captive toy model — a simplified single-track experiment that benchmarks JCAS tracking against a sensing-only baseline [3]. Every run is fully determined by a master_seed driving a per-stream seeded random-number manager, so results are exactly reproducible.

Features

  • Network generation via Poisson or Binomial point processes; UEs and sensing objects placed uniformly or as a Gaussian cluster.
  • Toroidal geometry with Voronoi cell coverage; mobility, filtering, beamforming and handover logic are all periodic.
  • Mobility models: stationary, Gauss–Markov, and ρ-persistent random walk.
  • Two physical channel models: ray-traced (rt, Oulu campaign) and Rayleigh-fading power-law (exponential); more can be registered at run time.
  • Communication over Lindley queues with SINR-dependent service rates.
  • Sensing and tracking with Kalman / Extended Kalman filters; one-way or two-way (monostatic-radar) sensing gain.
  • Optional sector beamforming and TDD scheduling.
  • Communication–sensing coupling metrics (association ratios, Pearson correlations).
  • Configured through a single immutable SimulationConfig dataclass tree, validated on construction; jcas_simulator/config.py documents every field and default, main.ipynb has worked examples.
  • The Streamlit app exports a run as a ZIP of every figure (with the trajectory animation) or as a ready-to-compile LaTeX table of the run’s parameters.

Example output

Figures from a single large-scale-simulator run under the ray-traced (rt) channel configuration, produced by jcas_simulator.visualization.

Steady-state distributions

Communication and sensing SINR KDE
Filter covariance-trace KDE
Queue-workload KDE
Kernel density estimates pooled across entities in the steady-state window: per-link communication and sensing SINR (the monostatic sensing return is far weaker than the communication link), the KF/EKF error-covariance trace Tr(Σ) used as the sensing-uncertainty metric, and the per-cell Lindley-queue workload.

Queue–covariance association

Queue workload versus filter covariance trace, with association ratio
Per-base-station mean queue workload against mean filter covariance trace. The association ratio A(W, Tr Σ) ≈ 1.006 > 1: communication congestion and sensing uncertainty co-increase weakly across the network.

Trajectory animations

Captive Gauss–Markov entity trajectories
ρ-persistent random-walk entity trajectories
Captive Gauss–Markov (captive_gauss_markov, top): each entity is contracted toward its serving base station and stays within its cell — the no-handover regime. ρ-persistent random walk (rho_random_walk, bottom): entities carry momentum and roam across cell boundaries, the regime in which handover applies.

Usage

Requires Python 3.10+.

git clone https://github.com/emanuelemengoli/instinct-jcas-simulator.git
cd instinct-jcas-simulator
./setup.sh
source .venv/bin/activate

Then either launch the web app with streamlit run simulator_interface.py, or open main.ipynb.

Released under the MIT License.

References

[1] J. Pyhtilä, J. Kokkoniemi, P. Sangi, N. Vaara and M. Juntti, “Ray Tracing Based Radio Channel Modelling Applied to RIS,” in WSA & SCC 2023; 26th International ITG Workshop on Smart Antennas and 13th Conference on Systems, Communications, and Coding, 2023, pp. 1–6.

[2] INSTINCT — Joint Sensing and Communication for Future Connectivity, Barkhausen Institut.

[3] A. Balakrishnan, N. Soprano-Loto and F. Baccelli, “Kalman Filtering for Sensing Aided Communication to Mobile Users in Large Cellular Networks.” 2026.