core Namespace Reference

Classes
struct	ActiveStreamingSource
	Cached description of an active streaming transmitter segment. More...
struct	ByteProjection
	Describes a projected byte count and whether it saturated during arithmetic. More...
class	Config
	Configuration structure for the application. More...
struct	Event
	Represents a single event in the simulation's time-ordered queue. More...
struct	EventComparator
	A custom comparator for the event priority queue. More...
struct	FmcwChirpBoundaryTracker
	Tracks the current FMCW chirp boundary for a streaming path. More...
struct	FmcwMetadata
	FMCW waveform metadata captured for a streaming output file. More...
struct	FmcwSourceMetadata
	Metadata for one FMCW illuminator represented in a streaming output file. More...
struct	FmcwSourceSegmentMetadata
	Metadata for one active FMCW transmitter schedule segment. More...
struct	FmcwTriangleBoundaryTracker
	Tracks the current FMCW triangle leg boundary for a streaming path. More...
struct	OutputConfig
struct	OutputFileMetadata
	Metadata for one receiver output file. More...
struct	OutputMetadata
	Metadata summary for the full simulation output set. More...
class	OutputMetadataCollector
	Thread-safe collector for simulation output metadata. More...
struct	OutputStats
class	ProgressReporter
	A thread-safe wrapper for the simulation progress callback. More...
struct	PulseChunkMetadata
	Metadata for one pulsed output chunk written to HDF5. More...
struct	ReceiverOutputPacketTrace
class	ReceiverOutputSink
struct	ReceiverSampleBlock
struct	ReceiverStreamDescriptor
struct	ReceiverStreamStats
struct	ReceiverTrackerCache
	Per-receiver FMCW tracker state for direct and reflected streaming paths. More...
struct	RenderingJob
	A data packet containing all information needed to process one receive window. More...
class	SimulationEngine
	Encapsulates the state and logic of the event-driven simulation loop. More...
struct	SimulationMemoryProjection
	Captures startup memory and rendered-output projections for a simulation. More...
struct	SimulationState
	Holds the dynamic global state of the simulation. More...
struct	StreamingSegmentMetadata
	Metadata for one contiguous streaming output segment. More...
struct	StreamingWaveformTracker
	Tracks the current streaming waveform boundary for a path. More...
struct	Vita49OutputConfig
struct	Vita49OutputMetadata
	Metadata for the VITA 49.2 UDP output backend. More...
struct	Vita49StreamMetadata
	Metadata for one VITA 49.2 receiver stream. More...
struct	Vita49Timestamp
class	World
	The World class manages the simulator environment. More...

Typedefs
using	ReceiverOutputTelemetryCallback = std::function< void(const std::optional< OutputStats > &, std::span< const ReceiverOutputPacketTrace >)>

Enumerations
enum class	OutputMode : std::uint8_t { Hdf5 , Vita49Udp }
enum class	EventType : std::uint8_t {   TX_PULSED_START , RX_PULSED_WINDOW_START , RX_PULSED_WINDOW_END , TX_STREAMING_START ,   TX_STREAMING_END , RX_STREAMING_START , RX_STREAMING_END }
	Enumerates the types of events that can occur in the simulation. More...
enum class	StreamingWaveformKind : std::uint8_t { Cw , FmcwLinear , FmcwTriangle }
	Streaming waveform shape cached for a currently active source. More...

Functions
std::vector< std::shared_ptr< timing::Timing > >	collectCwPhaseNoiseTimings (const World &world)
	Collects unique timing sources used by CW/FMCW transmitters and receivers.
void	addStreamingReceiverProjection (SimulationMemoryProjection &projection, const radar::Receiver &receiver, const bool sample_count_overflowed)
void	addPulsedReceiverProjection (SimulationMemoryProjection &projection, const radar::Receiver &receiver)
SimulationMemoryProjection	projectSimulationMemory (const World &world)
	Projects startup memory and rendered-output sizes for a simulation world.
std::string	formatByteSize (std::uint64_t bytes)
	Formats a byte count using binary units.
std::string	memoryProjectionToJsonString (const SimulationMemoryProjection &projection)
	Serializes a simulation memory projection as JSON.
void	logSimulationMemoryProjection (const World &world)
	Logs the projected simulation memory footprint for the provided world.
bool	isVita49Enabled (const OutputConfig &config) noexcept
std::string	outputFileMetadataToJsonString (const OutputFileMetadata &metadata)
	Serializes one output-file metadata entry to JSON.
std::string	outputMetadataToJsonString (const OutputMetadata &metadata)
	Serializes a full simulation output metadata snapshot to JSON.
Vita49OutputMetadata	vita49MetadataFromConfig (const Vita49OutputConfig &config)
	Builds the static VITA metadata section from runtime output configuration.
RealType	besselJ1 (const RealType x) noexcept
	Computes the Bessel function of the first kind (order 1) for a given value.
unsigned	countProcessors () noexcept
	Detects the number of CPUs on the machine.
std::string	toString (const EventType type)
	Converts an EventType enum to its string representation.
OutputMetadata	runEventDrivenSim (World *world, pool::ThreadPool &pool, const std::function< void(const std::string &, int, int)> &progress_callback, const std::string &output_dir, const OutputConfig &output_config=OutputConfig{}, std::function< bool()> cancel_callback=nullptr, bool *cancelled=nullptr, ReceiverOutputTelemetryCallback telemetry_callback=nullptr)
	Runs the unified, event-driven radar simulation.
ActiveStreamingSource	makeActiveSource (const radar::Transmitter *tx, RealType segment_start, RealType segment_end)
	Builds an active-source cache from a streaming transmitter and segment bounds.
ActiveStreamingSource	makeActiveSourceFromWaveform (const fers_signal::RadarSignal *signal, RealType segment_start, RealType segment_end)
	Builds an active-source cache directly from a waveform for receiver-local LO references.
std::optional< RealType >	firstFmcwChirpStart (const ActiveStreamingSource &source, RealType active_start, RealType active_end)
	Returns the first FMCW chirp start inside the absolute interval, if one exists.
std::uint64_t	countFmcwChirpStarts (const ActiveStreamingSource &source, RealType active_start, RealType active_end)
	Counts FMCW chirps that start inside the absolute interval.
std::optional< RealType >	firstFmcwTriangleStart (const ActiveStreamingSource &source, RealType active_start, RealType active_end)
	Returns the first FMCW triangle start inside the absolute interval, if one exists.
std::uint64_t	countFmcwTriangleStarts (const ActiveStreamingSource &source, RealType active_start, RealType active_end)
	Counts FMCW triangles that start inside the absolute interval.
void	showHelp (const char *programName) noexcept
	Displays the help message.
void	showVersion () noexcept
	Displays the version information.
std::expected< Config, std::string >	parseArguments (int argc, char *argv[]) noexcept
	Parses command-line arguments.
std::filesystem::path	resolveOutputDir (const std::string &script_file, const std::optional< std::string > &output_dir) noexcept
	Resolves the final simulation output directory from CLI arguments.
std::filesystem::path	resolveKmlOutputPath (const std::string &script_file, const std::filesystem::path &final_output_dir, const std::optional< std::string > &kml_file) noexcept
	Resolves the KML output file path from CLI arguments and output directory.

Typedef Documentation

ReceiverOutputTelemetryCallback

using core::ReceiverOutputTelemetryCallback = typedef std::function<void(const std::optional<OutputStats>&, std::span<const ReceiverOutputPacketTrace>)>

Definition at line 173 of file receiver_output.h.

Enumeration Type Documentation

EventType

enum class core::EventType : std::uint8_t

strong

Enumerates the types of events that can occur in the simulation.

Enumerator
TX_PULSED_START	A pulsed transmitter begins emitting a pulse.
RX_PULSED_WINDOW_START	A pulsed receiver opens its listening window.
RX_PULSED_WINDOW_END	A pulsed receiver closes its listening window.
TX_STREAMING_START	A streaming transmitter starts transmitting.
TX_STREAMING_END	A streaming transmitter stops transmitting.
RX_STREAMING_START	A streaming receiver starts listening.
RX_STREAMING_END	A streaming receiver stops listening.

Definition at line 29 of file sim_events.h.

    {
        TX_PULSED_START, ///< A pulsed transmitter begins emitting a pulse.
        RX_PULSED_WINDOW_START, ///< A pulsed receiver opens its listening window.
        RX_PULSED_WINDOW_END, ///< A pulsed receiver closes its listening window.
        TX_STREAMING_START, ///< A streaming transmitter starts transmitting.
        TX_STREAMING_END, ///< A streaming transmitter stops transmitting.
        RX_STREAMING_START, ///< A streaming receiver starts listening.
        RX_STREAMING_END, ///< A streaming receiver stops listening.
    };

OutputMode

enum class core::OutputMode : std::uint8_t

strong

Enumerator
Hdf5
Vita49Udp

Definition at line 17 of file output_config.h.

    {
        Hdf5,
        Vita49Udp
    };

StreamingWaveformKind

enum class core::StreamingWaveformKind : std::uint8_t

strong

Streaming waveform shape cached for a currently active source.

Enumerator
Cw
FmcwLinear
FmcwTriangle

Definition at line 32 of file simulation_state.h.

    {
        Cw,
        FmcwLinear,
        FmcwTriangle
    };

Function Documentation

addPulsedReceiverProjection()

void core::addPulsedReceiverProjection	(	SimulationMemoryProjection &	projection,
		const radar::Receiver &	receiver
	)

Definition at line 365 of file memory_projection.cpp.

    {
        ++projection.pulsed_receiver_count;
        bool window_count_overflowed = false;
        const auto windows = countPulsedWindows(receiver, window_count_overflowed);
        projection.pulsed_window_count = addBytes({.bytes = projection.pulsed_window_count},
                                                  {.bytes = windows, .overflowed = window_count_overflowed})
                                             .bytes;
 
        bool pulsed_sample_count_overflowed = false;
        const auto raw_window_samples = countSamplesForDuration(
            receiver.getWindowLength(), projection.simulation_sample_rate_hz, pulsed_sample_count_overflowed);
        const auto rendered_window_samples = downsampledSampleCount(raw_window_samples);
        const auto rendered_samples =
            multiplyBytes(windows, rendered_window_samples, window_count_overflowed || pulsed_sample_count_overflowed);
        projection.rendered_hdf5_sample_count =
            addBytes({.bytes = projection.rendered_hdf5_sample_count}, rendered_samples).bytes;
    }

References max, and receiver.

Referenced by projectSimulationMemory().

Here is the caller graph for this function:

addStreamingReceiverProjection()

void core::addStreamingReceiverProjection	(	SimulationMemoryProjection &	projection,
		const radar::Receiver &	receiver,
		const bool	sample_count_overflowed
	)

Definition at line 340 of file memory_projection.cpp.

    {
        ++projection.streaming_receiver_count;
        bool if_count_overflowed = false;
        const auto if_sample_rate = receiver.getIfSampleRate();
        const bool if_rate_dechirped = receiver.isDechirpEnabled() && if_sample_rate.has_value();
        const auto if_sample_count = if_rate_dechirped
            ? countSamplesForDuration(projection.duration_seconds, if_sample_rate.value_or(0.0), if_count_overflowed)
            : std::uint64_t{0};
        const auto rendered_samples = if_rate_dechirped
            ? if_sample_count
            : (receiver.isDechirpEnabled() ? projection.streaming_sample_count
                                           : downsampledSampleCount(projection.streaming_sample_count));
        projection.rendered_hdf5_sample_count =
            addBytes({.bytes = projection.rendered_hdf5_sample_count},
                     {.bytes = rendered_samples, .overflowed = sample_count_overflowed || if_count_overflowed})
                .bytes;
        const auto resident_samples = if_rate_dechirped ? if_sample_count : projection.streaming_sample_count;
        projection.streaming_iq_buffers =
            addBytes(projection.streaming_iq_buffers,
                     multiplyBytes(resident_samples, static_cast<std::uint64_t>(sizeof(ComplexType)),
                                   sample_count_overflowed || if_count_overflowed));
    }

References max, and receiver.

Referenced by projectSimulationMemory().

Here is the caller graph for this function:

besselJ1()

RealType core::besselJ1 ( const RealType  x )

noexcept

Computes the Bessel function of the first kind (order 1) for a given value.

Parameters

x	The value for which the Bessel function is to be computed.

Returns

The computed value of the Bessel function of the first kind (order 1).

Definition at line 28 of file portable_utils.h.

    {
#ifdef _MSC_VER
        return _j1(x);
#else
        return j1(x);
#endif
    }

References max.

collectCwPhaseNoiseTimings()

std::vector< std::shared_ptr< timing::Timing > > core::collectCwPhaseNoiseTimings

(

const World &

world

)

Collects unique timing sources used by CW/FMCW transmitters and receivers.

Parameters

world

The simulation world to inspect.

Returns

A vector of unique timing sources that may need phase-noise lookup tables.

Definition at line 309 of file memory_projection.cpp.

    {
        std::unordered_map<SimId, std::shared_ptr<timing::Timing>> unique_timings;
 
        for (const auto& transmitter_ptr : world.getTransmitters())
        {
            if (!transmitter_ptr->isStreamingMode())
            {
                continue;
            }
            unique_timings.try_emplace(transmitter_ptr->getTiming()->getId(), transmitter_ptr->getTiming());
        }
 
        for (const auto& receiver_ptr : world.getReceivers())
        {
            if (!isStreamingReceiver(*receiver_ptr))
            {
                continue;
            }
            unique_timings.try_emplace(receiver_ptr->getTiming()->getId(), receiver_ptr->getTiming());
        }
 
        std::vector<std::shared_ptr<timing::Timing>> timings;
        timings.reserve(unique_timings.size());
        for (const auto& entry : unique_timings)
        {
            timings.push_back(entry.second);
        }
        return timings;
    }

References core::World::getReceivers(), core::World::getTransmitters(), and max.

Referenced by projectSimulationMemory().

Here is the call graph for this function:

Here is the caller graph for this function:

countFmcwChirpStarts()

std::uint64_t core::countFmcwChirpStarts	(	const ActiveStreamingSource &	source,
		const RealType	active_start,
		const RealType	active_end
	)

Counts FMCW chirps that start inside the absolute interval.

Definition at line 249 of file simulation_state.cpp.

    {
        const auto first_index = firstFmcwChirpIndex(source, active_start, active_end);
        if (!first_index.has_value())
        {
            return 0;
        }
 
        const RealType clipped_end = std::min(active_end, source.segment_end);
        const RealType first_start = source.segment_start + static_cast<RealType>(*first_index) * source.chirp_period;
        const auto starts_in_interval = ceilToUint((clipped_end - first_start) / source.chirp_period);
        if (!source.chirp_count.has_value())
        {
            return starts_in_interval;
        }
 
        const auto configured = static_cast<std::uint64_t>(*source.chirp_count);
        return std::min(starts_in_interval, configured - *first_index);
    }

References core::ActiveStreamingSource::chirp_count, core::ActiveStreamingSource::chirp_period, max, core::ActiveStreamingSource::segment_end, and core::ActiveStreamingSource::segment_start.

countFmcwTriangleStarts()

std::uint64_t core::countFmcwTriangleStarts	(	const ActiveStreamingSource &	source,
		const RealType	active_start,
		const RealType	active_end
	)

Counts FMCW triangles that start inside the absolute interval.

Definition at line 281 of file simulation_state.cpp.

    {
        const auto first_index = firstFmcwTriangleIndex(source, active_start, active_end);
        if (!first_index.has_value())
        {
            return 0;
        }
 
        const RealType clipped_end = std::min(active_end, source.segment_end);
        const RealType first_start =
            source.segment_start + static_cast<RealType>(*first_index) * source.triangle_period;
        const auto starts_in_interval = ceilToUint((clipped_end - first_start) / source.triangle_period);
        if (!source.triangle_count.has_value())
        {
            return starts_in_interval;
        }
 
        const auto configured = static_cast<std::uint64_t>(*source.triangle_count);
        return std::min(starts_in_interval, configured - *first_index);
    }

References max, core::ActiveStreamingSource::segment_end, core::ActiveStreamingSource::segment_start, core::ActiveStreamingSource::triangle_count, and core::ActiveStreamingSource::triangle_period.

countProcessors()

unsigned core::countProcessors ( )

noexcept

Detects the number of CPUs on the machine.

Returns

The number of CPUs detected, or 1 if detection fails.

Definition at line 42 of file portable_utils.h.

    {
        if (const unsigned hardware_threads = std::thread::hardware_concurrency(); hardware_threads > 0)
        {
            return hardware_threads;
        }
        LOG(logging::Level::ERROR, "Unable to get CPU count, assuming 1.");
        return 1;
    }

References logging::ERROR, LOG, and max.

firstFmcwChirpStart()

std::optional< RealType > core::firstFmcwChirpStart	(	const ActiveStreamingSource &	source,
		const RealType	active_start,
		const RealType	active_end
	)

Returns the first FMCW chirp start inside the absolute interval, if one exists.

Definition at line 238 of file simulation_state.cpp.

    {
        const auto first_index = firstFmcwChirpIndex(source, active_start, active_end);
        if (!first_index.has_value())
        {
            return std::nullopt;
        }
        return source.segment_start + static_cast<RealType>(*first_index) * source.chirp_period;
    }

References core::ActiveStreamingSource::chirp_period, max, and core::ActiveStreamingSource::segment_start.

firstFmcwTriangleStart()

std::optional< RealType > core::firstFmcwTriangleStart	(	const ActiveStreamingSource &	source,
		const RealType	active_start,
		const RealType	active_end
	)

Returns the first FMCW triangle start inside the absolute interval, if one exists.

Definition at line 270 of file simulation_state.cpp.

    {
        const auto first_index = firstFmcwTriangleIndex(source, active_start, active_end);
        if (!first_index.has_value())
        {
            return std::nullopt;
        }
        return source.segment_start + static_cast<RealType>(*first_index) * source.triangle_period;
    }

References max, core::ActiveStreamingSource::segment_start, and core::ActiveStreamingSource::triangle_period.

formatByteSize()

std::string core::formatByteSize

(

std::uint64_t

bytes

)

Formats a byte count using binary units.

Parameters

bytes

The byte count to format.

Returns

A human-readable string such as 512 B or 1.50 MiB.

Definition at line 455 of file memory_projection.cpp.

    {
        constexpr std::array units = {"B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"};
        auto value = static_cast<long double>(bytes);
        std::size_t unit_index = 0;
        while (value >= 1024.0L && unit_index + 1 < units.size())
        {
            value /= 1024.0L;
            ++unit_index;
        }
        if (unit_index == 0)
        {
            return std::format("{} {}", bytes, units.at(unit_index));
        }
        return std::format("{:.2f} {}", static_cast<double>(value), units.at(unit_index));
    }

References max.

Referenced by logSimulationMemoryProjection(), and memoryProjectionToJsonString().

Here is the caller graph for this function:

isVita49Enabled()

bool core::isVita49Enabled ( const OutputConfig &  config )

noexcept

Definition at line 40 of file output_config.h.

    {
        return config.mode == OutputMode::Vita49Udp;
    }

References max, and Vita49Udp.

Referenced by runEventDrivenSim().

Here is the caller graph for this function:

logSimulationMemoryProjection()

void core::logSimulationMemoryProjection

(

const World &

world

)

Logs the projected simulation memory footprint for the provided world.

Parameters

world

The simulation world to inspect and report.

Definition at line 501 of file memory_projection.cpp.

    {
        const auto projection = projectSimulationMemory(world);
        const std::string resident_baseline =
            projection.resident_baseline.has_value() ? formatByteSize(projection.resident_baseline->bytes) : "unknown";
        const std::string total = projection.projected_total_footprint.has_value()
            ? formatByteSize(projection.projected_total_footprint->bytes)
            : "unknown";
 
        LOG(logging::Level::DEBUG,
            "Projected simulation footprint: phase_noise_lookup_memory={} ({} enabled timing sources x {} samples), "
            "streaming_output_buffer_memory={} ({} streaming receivers, IF-rate receivers use IF sample counts), "
            "rendered_hdf5_dataset_payload={} "
            "({} output samples), resident_baseline={} (current RSS before projected run allocations), "
            "projected_total_footprint={}.",
            formatByteSize(projection.phase_noise_lookup.bytes), projection.enabled_phase_noise_timing_count,
            projection.phase_noise_sample_count, formatByteSize(projection.streaming_iq_buffers.bytes),
            projection.streaming_receiver_count, formatByteSize(projection.rendered_hdf5_payload.bytes),
            projection.rendered_hdf5_sample_count, resident_baseline, total);
 
        constexpr std::uint64_t one_gib = 1024ULL * 1024ULL * 1024ULL;
        for (const auto& receiver_ptr : world.getReceivers())
        {
            const auto& receiver = *receiver_ptr;
            if (!receiver.isDechirpEnabled())
            {
                continue;
            }
            if (receiver.hasFmcwIfSampleRate())
            {
                continue;
            }
            const auto projected_payload =
                multiplyBytes(projection.streaming_sample_count, 2ULL * static_cast<std::uint64_t>(sizeof(RealType)));
            if (projected_payload.bytes > one_gib || projected_payload.overflowed)
            {
                const auto gib = static_cast<long double>(projected_payload.bytes) / static_cast<long double>(one_gib);
                // TODO: UI workflows should have disk+memory usage stats on the SimulationView page (shows before user
                // runs the sim)
                LOG(logging::Level::WARNING,
                    "Receiver {} is outputting RF-rate IF data. Projected file size is {:.2f} GiB. This is expected "
                    "for V1 native dechirping, but ensure you have sufficient disk space. Future versions will support "
                    "IF-rate decimation.",
                    receiver.getName(), static_cast<double>(gib));
            }
        }
    }

References logging::DEBUG, formatByteSize(), core::World::getReceivers(), LOG, max, projectSimulationMemory(), receiver, and logging::WARNING.

Referenced by core::SimulationEngine::run().

Here is the call graph for this function:

Here is the caller graph for this function:

makeActiveSource()

ActiveStreamingSource core::makeActiveSource	(	const radar::Transmitter *const	tx,
		const RealType	segment_start,
		const RealType	segment_end
	)

Builds an active-source cache from a streaming transmitter and segment bounds.

Definition at line 195 of file simulation_state.cpp.

    {
        ActiveStreamingSource source{};
        source.transmitter = tx;
        source.segment_start = segment_start;
        source.segment_end = segment_end;
        if (tx == nullptr)
        {
            return source;
        }
 
        const auto* const signal = tx->getSignal();
        if (signal == nullptr)
        {
            return source;
        }
 
        const RealType raw_segment_end = segment_end;
        populateWaveformCache(source, signal, segment_start);
        if (source.kind == StreamingWaveformKind::FmcwTriangle &&
            source.segment_end + kWaveformBoundaryTimeToleranceSeconds < raw_segment_end)
        {
            const auto emitted_triangles = static_cast<std::uint64_t>(
                std::max<RealType>(0.0, (source.segment_end - segment_start) / source.triangle_period));
            LOG(logging::Level::WARNING,
                "FMCW triangle transmitter '{}' segment [{}, {}] emits {} complete triangles and drops {} s of "
                "leftover active time.",
                tx->getName(), segment_start, raw_segment_end, emitted_triangles, raw_segment_end - source.segment_end);
        }
        return source;
    }

References FmcwTriangle, LOG, max, core::ActiveStreamingSource::transmitter, and logging::WARNING.

makeActiveSourceFromWaveform()

ActiveStreamingSource core::makeActiveSourceFromWaveform	(	const fers_signal::RadarSignal *const	signal,
		const RealType	segment_start,
		const RealType	segment_end
	)

Builds an active-source cache directly from a waveform for receiver-local LO references.

Definition at line 228 of file simulation_state.cpp.

    {
        ActiveStreamingSource source{};
        source.segment_start = segment_start;
        source.segment_end = segment_end;
        populateWaveformCache(source, signal, segment_start);
        return source;
    }

References max, and core::ActiveStreamingSource::segment_start.

memoryProjectionToJsonString()

std::string core::memoryProjectionToJsonString

(

const SimulationMemoryProjection &

projection

)

Serializes a simulation memory projection as JSON.

Parameters

projection

The projection to serialize.

Returns

A formatted JSON string suitable for API responses and diagnostics.

Definition at line 472 of file memory_projection.cpp.

    {
        const nlohmann::json result = {
            {"duration_seconds", projection.duration_seconds},
            {"simulation_sample_rate_hz", projection.simulation_sample_rate_hz},
            {"oversample_ratio", projection.oversample_ratio},
            {"sample_counts",
             {{"streaming_samples", projection.streaming_sample_count},
              {"phase_noise_samples_per_enabled_timing", projection.phase_noise_sample_count},
              {"rendered_hdf5_samples", projection.rendered_hdf5_sample_count},
              {"pulsed_windows", projection.pulsed_window_count}}},
            {"object_counts",
             {{"phase_noise_timing_sources", projection.phase_noise_timing_count},
              {"enabled_phase_noise_timing_sources", projection.enabled_phase_noise_timing_count},
              {"streaming_receivers", projection.streaming_receiver_count},
              {"pulsed_receivers", projection.pulsed_receiver_count}}},
            {"phase_noise_lookups", byteProjectionToJson(projection.phase_noise_lookup)},
            {"streaming_iq_buffers", byteProjectionToJson(projection.streaming_iq_buffers)},
            {"rendered_hdf5_dataset_payload", byteProjectionToJson(projection.rendered_hdf5_payload)},
            {"current_resident_set",
             projection.current_resident_set.has_value()
                 ? nlohmann::json{{"bytes", *projection.current_resident_set},
                                  {"human", formatByteSize(*projection.current_resident_set)}}
                 : nlohmann::json{{"bytes", nullptr}, {"human", "unknown"}}},
            {"resident_baseline", optionalByteProjectionToJson(projection.resident_baseline)},
            {"projected_total_footprint", optionalByteProjectionToJson(projection.projected_total_footprint)}};
        return result.dump(2);
    }

References formatByteSize(), and max.

Referenced by fers_get_memory_projection_json().

Here is the call graph for this function:

Here is the caller graph for this function:

outputFileMetadataToJsonString()

std::string core::outputFileMetadataToJsonString

(

const OutputFileMetadata &

metadata

)

Serializes one output-file metadata entry to JSON.

Definition at line 360 of file output_metadata.cpp.

    {
        return fileToJson(metadata).dump(2);
    }

References max, and outputFileMetadataToJsonString().

Referenced by outputFileMetadataToJsonString().

Here is the call graph for this function:

Here is the caller graph for this function:

outputMetadataToJsonString()

std::string core::outputMetadataToJsonString

(

const OutputMetadata &

metadata

)

Serializes a full simulation output metadata snapshot to JSON.

Definition at line 365 of file output_metadata.cpp.

{ return metadataToJson(metadata).dump(2); }

References max, and outputMetadataToJsonString().

Referenced by FersContext::getLastOutputMetadataJson(), and outputMetadataToJsonString().

Here is the call graph for this function:

Here is the caller graph for this function:

parseArguments()

std::expected< Config, std::string > core::parseArguments ( int  argc, char *  argv[]  )

noexcept

Parses command-line arguments.

Processes the command-line arguments, validating them and extracting configurations like script file, logging level, and thread count.

Parameters

argc	The argument count.
argv	The argument vector.

Returns

std::expected<Config, std::string> Parsed configuration or an error message.

Definition at line 425 of file arg_parser.cpp.

         :
  <scriptfile>            Path to the simulation script file (XML)
 
Example:
  )" << programName
                  << R"( simulation.fersxml --out-dir=./results --log-level=DEBUG -n=4
 
This program runs radar simulations based on an XML script file.
Make sure the script file follows the correct format to avoid errors.
)";
    }
 
    void showVersion() noexcept
    {
        const char* version = fers_get_version();
 
        std::cout << '\n'
                  << "/------------------------------------------------\\\n"
                  << "| FERS - The Flexible Extensible Radar Simulator |\n"
                  << std::format("| Version {:<40}|\n", version)
                  << "| Authors: Marc Brooker, Michael Inggs,         |\n"
                  << "|          and FERS Contributors                |\n"
                  << "\\------------------------------------------------/\n\n";
    }
 
    std::expected<Config, std::string> parseArguments(const int argc, char* argv[]) noexcept
    {
        Config config;
        bool script_file_set = false;
 
        if (argc < 2)
        {
            showHelp(argv[0]);
            return std::unexpected("No arguments provided.");
        }
 
        for (int i = 1; i < argc; ++i)
        {
            const std::string arg = argv[i];
            const auto require_value = [&](const std::string& option) -> std::expected<std::string, std::string>
            {
                if (i + 1 >= argc)
                {
                    return std::unexpected(option + " requires a value");
                }
                ++i;
                return std::string{argv[i]};
            };
 

projectSimulationMemory()

SimulationMemoryProjection core::projectSimulationMemory

(

const World &

world

)

Projects startup memory and rendered-output sizes for a simulation world.

Parameters

world

The simulation world to inspect.

Returns

A populated memory projection for the current simulation parameters.

Definition at line 384 of file memory_projection.cpp.

    {
        SimulationMemoryProjection projection{};
        projection.duration_seconds = std::max<RealType>(0.0, params::endTime() - params::startTime());
        projection.oversample_ratio = params::oversampleRatio();
        projection.simulation_sample_rate_hz = params::rate() * static_cast<RealType>(projection.oversample_ratio);
 
        bool sample_count_overflowed = false;
        projection.streaming_sample_count = countSamplesForDuration(
            projection.duration_seconds, projection.simulation_sample_rate_hz, sample_count_overflowed);
 
        const RealType phase_noise_lookup_start = world.earliestPhaseNoiseLookupStart();
        bool phase_noise_count_overflowed = false;
        projection.phase_noise_sample_count =
            countSamplesForDuration(std::max<RealType>(0.0, params::endTime() - phase_noise_lookup_start),
                                    projection.simulation_sample_rate_hz, phase_noise_count_overflowed);
        if (projection.phase_noise_sample_count != max_uint64)
        {
            ++projection.phase_noise_sample_count;
        }
        if (phase_noise_count_overflowed)
        {
            projection.phase_noise_sample_count = max_uint64;
        }
 
        const auto timings = collectCwPhaseNoiseTimings(world);
        projection.phase_noise_timing_count = static_cast<std::uint64_t>(timings.size());
        for (const auto& timing : timings)
        {
            if (timing && timing->isEnabled())
            {
                ++projection.enabled_phase_noise_timing_count;
            }
        }
 
        projection.phase_noise_lookup =
            multiplyBytes(projection.phase_noise_sample_count,
                          projection.enabled_phase_noise_timing_count * static_cast<std::uint64_t>(sizeof(RealType)),
                          sample_count_overflowed);
 
        for (const auto& receiver_ptr : world.getReceivers())
        {
            const auto& receiver = *receiver_ptr;
            if (isStreamingReceiver(receiver))
            {
                addStreamingReceiverProjection(projection, receiver, sample_count_overflowed);
                continue;
            }
 
            if (receiver.getMode() == OperationMode::PULSED_MODE)
            {
                addPulsedReceiverProjection(projection, receiver);
            }
        }
 
        projection.rendered_hdf5_payload =
            multiplyBytes(projection.rendered_hdf5_sample_count, 2ULL * static_cast<std::uint64_t>(sizeof(RealType)));
 
        projection.current_resident_set = currentResidentSetBytes();
        if (projection.current_resident_set.has_value())
        {
            projection.resident_baseline = ByteProjection{.bytes = *projection.current_resident_set};
            projection.projected_total_footprint =
                addBytes(addBytes(addBytes(projection.phase_noise_lookup, projection.streaming_iq_buffers),
                                  projection.rendered_hdf5_payload),
                         *projection.resident_baseline);
        }
 
        return projection;
    }

References addPulsedReceiverProjection(), addStreamingReceiverProjection(), core::ByteProjection::bytes, collectCwPhaseNoiseTimings(), core::World::earliestPhaseNoiseLookupStart(), params::endTime(), core::World::getReceivers(), max, params::oversampleRatio(), params::rate(), receiver, and params::startTime().

Referenced by fers_get_memory_projection_json(), and logSimulationMemoryProjection().

Here is the call graph for this function:

Here is the caller graph for this function:

resolveKmlOutputPath()

std::filesystem::path core::resolveKmlOutputPath ( const std::string &  script_file, const std::filesystem::path &  final_output_dir, const std::optional< std::string > &  kml_file  )

noexcept

Resolves the KML output file path from CLI arguments and output directory.

Definition at line 25 of file cli_paths.cpp.

    {
        if (kml_file && !kml_file->empty())
        {
            std::filesystem::path provided_kml_path(*kml_file);
            if (provided_kml_path.has_parent_path() || provided_kml_path.is_absolute())
            {
                return provided_kml_path;
            }
 
            return final_output_dir / provided_kml_path;
        }
 
        std::filesystem::path kml_output_path = final_output_dir / std::filesystem::path(script_file).filename();
        kml_output_path.replace_extension(".kml");
        return kml_output_path;
    }

resolveOutputDir()

std::filesystem::path core::resolveOutputDir ( const std::string &  script_file, const std::optional< std::string > &  output_dir  )

noexcept

Resolves the final simulation output directory from CLI arguments.

Definition at line 8 of file cli_paths.cpp.

    {
        if (output_dir)
        {
            return std::filesystem::path(*output_dir);
        }
 
        std::filesystem::path default_out_dir = std::filesystem::path(script_file).parent_path();
        if (default_out_dir.empty())
        {
            default_out_dir = ".";
        }
 
        return default_out_dir;
    }

runEventDrivenSim()

OutputMetadata core::runEventDrivenSim	(	World *	world,
		pool::ThreadPool &	pool,
		const std::function< void(const std::string &, int, int)> &	progress_callback,
		const std::string &	output_dir,
		const OutputConfig &	output_config = OutputConfig{},
		std::function< bool()>	cancel_callback = nullptr,
		bool *	cancelled = nullptr,
		ReceiverOutputTelemetryCallback	telemetry_callback = nullptr
	)

Runs the unified, event-driven radar simulation.

This function is the core entry point of the simulator. It advances time by processing events from a global priority queue. It handles both pulsed and continuous-wave (CW) physics, dispatching finalization tasks to worker threads for asynchronous processing.

Parameters

world	A pointer to the simulation world containing all entities and state.
pool	A reference to the thread pool for executing tasks.
progress_callback	An optional callback function for reporting progress.
output_dir	Output directory for the simulation files.

Definition at line 2009 of file sim_threading.cpp.

    {
        if (cancelled != nullptr)
        {
            *cancelled = false;
        }
        auto reporter = std::make_shared<ProgressReporter>(progress_callback);
        auto metadata_collector = std::make_shared<OutputMetadataCollector>(output_dir);
        std::unique_ptr<ReceiverOutputSink> output_sink;
        if (isVita49Enabled(output_config))
        {
            output_sink = serial::vita49::makeVita49OutputSink(std::move(telemetry_callback));
            output_sink->initializeRun(output_config, params::params.simulation_name);
        }
        else
        {
            output_sink = serial::makeHdf5OutputSink(output_dir, metadata_collector);
            output_sink->initializeRun(output_config, params::params.simulation_name);
        }
 
        SimulationEngine engine(world, pool, reporter, output_dir, metadata_collector, output_sink.get(),
                                std::move(cancel_callback), isVita49Enabled(output_config));
        engine.run();
        if (cancelled != nullptr)
        {
            *cancelled = engine.cancelled();
        }
        if (isVita49Enabled(output_config))
        {
            LOG(Level::INFO, "Waiting for VITA output stream drain...");
            reporter->report("Waiting for VITA output stream drain...", 100, 100);
        }
        const auto stats = output_sink->finalize();
        reporter->report(engine.cancelled() ? "Simulation cancelled" : "Simulation complete", 100, 100);
        LOG(Level::INFO, "Event-driven simulation loop finished.");
        auto metadata = metadata_collector->snapshot();
        if (output_sink)
        {
            if (isVita49Enabled(output_config))
            {
                auto vita49_metadata = vita49MetadataFromConfig(output_config.vita49);
                if (stats.epoch_unix_nanoseconds.has_value())
                {
                    vita49_metadata.epoch_unix_nanoseconds = stats.epoch_unix_nanoseconds;
                }
                for (const auto& stream : stats.streams)
                {
                    vita49_metadata.streams.push_back(streamStatsToMetadata(stream));
                }
                metadata.vita49 = std::move(vita49_metadata);
            }
        }
        return metadata;
    }

References isVita49Enabled(), LOG, serial::makeHdf5OutputSink(), serial::vita49::makeVita49OutputSink(), max, params::params, and vita49MetadataFromConfig().

Here is the call graph for this function:

showHelp()

void core::showHelp ( const char *  programName )

noexcept

Displays the help message.

Parameters

programName

The name of the program.

Definition at line 400 of file arg_parser.cpp.

    {
        const char* version = fers_get_version();
 
        std::cout << "/------------------------------------------------\\\n"
                  << "| FERS - The Flexible Extensible Radar Simulator |\n"
                  << std::format("| Version {:<40}|\n", version)
                  << "\\------------------------------------------------/\n"
                  << "Usage: " << programName << R"( <scriptfile> [options]
 
Options:

References fers_get_version().

Here is the call graph for this function:

showVersion()

void core::showVersion ( )

noexcept

Displays the version information.

Definition at line 412 of file arg_parser.cpp.

               :port      Stream receiver output as the FERS VITA 49.2 UDP profile.
  --vita49-fullscale <x>  Set required positive fixed ADC full-scale for VITA int16 IQ output.
  --vita49-epoch <ns>     Set optional deterministic VITA epoch as Unix nanoseconds.
  --vita49-max-udp-payload <bytes>
                          Set optional VITA UDP payload cap, 64..65507 bytes.

toString()

std::string core::toString

(

const EventType

type

)

Converts an EventType enum to its string representation.

Parameters

type	The event type.

Returns

A string representing the event type.

Definition at line 74 of file sim_events.h.

    {
        switch (type)
        {
        case EventType::TX_PULSED_START:
            return "TxPulsedStart";
        case EventType::RX_PULSED_WINDOW_START:
            return "RxPulsedWindowStart";
        case EventType::RX_PULSED_WINDOW_END:
            return "RxPulsedWindowEnd";
        case EventType::TX_STREAMING_START:
            return "TxStreamingStart";
        case EventType::TX_STREAMING_END:
            return "TxStreamingEnd";
        case EventType::RX_STREAMING_START:
            return "RxStreamingStart";
        case EventType::RX_STREAMING_END:
            return "RxStreamingEnd";
        default:
            return "UnknownEvent";
        }
    }

References RX_PULSED_WINDOW_END, RX_PULSED_WINDOW_START, RX_STREAMING_END, RX_STREAMING_START, TX_PULSED_START, TX_STREAMING_END, and TX_STREAMING_START.

Referenced by core::World::dumpEventQueue().

Here is the caller graph for this function:

vita49MetadataFromConfig()

Vita49OutputMetadata core::vita49MetadataFromConfig

(

const Vita49OutputConfig &

config

)

Builds the static VITA metadata section from runtime output configuration.

Definition at line 367 of file output_metadata.cpp.

    {
        return Vita49OutputMetadata{.endpoint_host = config.host,
                                    .endpoint_port = config.port,
                                    .epoch_unix_nanoseconds = config.epoch_unix_nanoseconds,
                                    .adc_fullscale = config.adc_fullscale,
                                    .max_udp_payload = config.max_udp_payload,
                                    .queue_depth = config.queue_depth};
    }

References core::Vita49OutputMetadata::endpoint_host, max, and vita49MetadataFromConfig().

Referenced by runEventDrivenSim(), and vita49MetadataFromConfig().

Here is the call graph for this function:

Here is the caller graph for this function: