PRESTUS Telemetry¶

PRESTUS can optionally send anonymous usage statistics to help the developers understand which features and platforms are in active use. Participation is entirely voluntary. No data is ever sent without an explicit opt-in.

Opt-in / opt-out¶

On each pipeline run PRESTUS prints a short notice and asks whether to enable telemetry. The prompt repeats every run until you give an explicit answer. Your decision is stored in:

~/.prestus/telemetry.json

You can change your decision at any time:

Opt out: set "opt_in": false in that file, or run telemetry_setup_reset() in MATLAB to be asked again on the next run.
Opt in: set "opt_in": true in the same file.

Non-interactive environments (HPC batch jobs)¶

In non-interactive sessions PRESTUS cannot prompt for input. The full notice is printed to stdout (visible in job logs) on every run, but no decision is recorded and no data is sent. The message will reappear on every run until you make an explicit decision.

To opt in from an HPC environment, either:

Run PRESTUS once interactively (e.g. on a login node) and answer y, or

Create ~/.prestus/telemetry.json manually:

{"opt_in": true, "decided_on": "YYYY-MM-DD", "prestus_ver": ""}

What is collected¶

Each pipeline run emits up to two events: run_start (before any module runs) and run_end (on clean exit) or run_error (if the pipeline throws an unhandled exception). The table below lists every field that may be sent.

System resources¶

Field	Description
`os_version`	OS version string (macOS: `sw_vers -productVersion`; Linux: kernel release; Windows: `ver` output). Returns `'unknown'` on error.
`cpu_model`	CPU model name (e.g. `Apple M2 Pro`). Returns `'unknown'` on error.
`n_cpu_cores`	Number of logical CPU cores via `feature('numcores')`.
`ram_gb`	Total physical RAM in GB (rounded). Returns `NaN` on error.
`gpu_model`	GPU device name from `gpuDevice()`. Returns `'no_pct'` when the Parallel Computing Toolbox is not licensed; `'none'` when no GPU is found; otherwise the device name string.
`toolboxes`	Cell array of installed MATLAB toolbox names (MATLAB itself excluded).

All system resource fields are collected inside try/catch blocks and fall back to 'unknown' or NaN on any error, so they never cause the telemetry payload to fail.

Identity¶

Field	Description
`event`	Event type: `run_start`, `run_end`, or `run_error`
`timestamp_utc`	POSIX timestamp (seconds since epoch, UTC)
`uuid`	Random UUID generated locally on first run; stored in `~/.prestus/uuid.txt`. Not linked to your identity or machine.
`prestus_ver`	Version string of the running PRESTUS checkout (from `git describe` or the `VERSION` file, e.g. `v0.5.1`)
`prestus_hash`	Short git commit hash of the running PRESTUS checkout (e.g. `628edd0`)
`matlab_ver`	MATLAB release string (e.g. `R2024a`)
`kwave_ver`	k-Wave toolbox version string as reported by `getComputerInfo`
`platform`	CPU architecture string from `computer('arch')` (e.g. `maci64`, `glnxa64`)

Execution environment¶

Field	Description
`sim_platform`	Execution platform: `matlab`, `slurm`, `qsub`, etc.
`code_type`	k-Wave code variant: `matlab_cpu`, `matlab_gpu`, `cpp_cpu`, `cpp_gpu`
`precision`	Floating-point precision: `single` or `double`
`hpc_name`	HPC cluster name if running on a known cluster; `unknown` otherwise
`use_gpu`	Boolean — whether a GPU device is configured

Simulation configuration¶

Field	Description
`medium`	Medium type: `water` or `layered`
`layers`	List of tissue layer names (e.g. `["skin","skull","brain"]`)
`pct_enabled`	Boolean — whether pseudo-CT is enabled
`pct_density`	Name of the density mapping used for pCT (string, not values)
`pct_speed`	Name of the sound-speed mapping used for pCT
`pct_atten`	Name of the attenuation mapping used for pCT
`modules_enabled`	List of module names that are switched on (e.g. `["acoustic_sim","thermal_sim"]`)

Transducer¶

Field	Description
`transducer_type`	Transducer geometry type (e.g. `focused_bowl`)
`transducer_name`	Transducer model name from the config
`freq_hz`	Nominal operating frequency in Hz
`n_transducer_elements`	Number of transducer elements (`elem_n` from the transducer config)

Outcome (run_end / run_error only)¶

Field	Description
`duration_s`	Total pipeline wall-clock time in seconds
`status`	`"success"` or `"error"`
`error_id`	MATLAB error identifier string (e.g. `MATLAB:badsubscript`) — no message text is transmitted

Subject IDs, file paths, or directory names that carries a risk of containing identifiable information is not collected.

Usage statistics¶

See the Usage Statistics page for live charts populated from the anonymised telemetry database.