serial Namespace Reference

Namespaces
namespace	kml_generator_utils
namespace	rotation_angle_utils
namespace	rotation_warning_utils
namespace	xml_parser_utils
namespace	xml_serializer_utils

Classes
class	KmlGenerator
	Generates KML files from FERS simulation scenarios for geographical visualization. More...
class	Response
	Manages radar signal responses from a transmitter. More...

Functions
std::vector< std::vector< RealType > >	readPattern (const std::string &name, const std::string &datasetName)
	Reads a 2D pattern dataset from an HDF5 file.
void	writeOutputFileMetadataAttributes (HighFive::File &file, const core::OutputFileMetadata &metadata)
	Writes additive FERS output metadata attributes to an open HDF5 file.
void	readPulseData (const std::string &name, std::vector< ComplexType > &data)
	Reads pulse data from an HDF5 file.
void	addChunkToFile (HighFive::File &file, const std::vector< ComplexType > &data, RealType time, RealType fullscale, unsigned count, const core::PulseChunkMetadata *metadata=nullptr)
	Adds a chunk of data to an HDF5 file.
std::unique_ptr< antenna::Antenna >	parse_antenna_from_json (const nlohmann::json &j)
	Parses an Antenna from JSON.
std::unique_ptr< fers_signal::RadarSignal >	parse_waveform_from_json (const nlohmann::json &j)
	Parses a Waveform from JSON.
std::unique_ptr< timing::PrototypeTiming >	parse_timing_from_json (const nlohmann::json &j, SimId id)
	Parses a timing prototype from JSON.
void	update_parameters_from_json (const nlohmann::json &j, std::mt19937 &masterSeeder)
	Updates global simulation parameters from JSON.
void	update_antenna_from_json (const nlohmann::json &j, antenna::Antenna *ant, core::World &world)
	Updates an antenna from JSON without full context recreation.
void	update_platform_paths_from_json (const nlohmann::json &j, radar::Platform *plat)
	Updates a platform's motion and rotation paths from JSON.
void	update_transmitter_from_json (const nlohmann::json &j, radar::Transmitter *tx, core::World &world, std::mt19937 &masterSeeder)
	Updates a transmitter from JSON without full context recreation.
void	update_receiver_from_json (const nlohmann::json &j, radar::Receiver *rx, core::World &world, std::mt19937 &masterSeeder)
	Updates a receiver from JSON without full context recreation.
void	update_monostatic_from_json (const nlohmann::json &j, radar::Transmitter *tx, radar::Receiver *rx, core::World &world, std::mt19937 &masterSeeder)
	Updates a monostatic radar from JSON without full context recreation.
void	update_target_from_json (const nlohmann::json &j, radar::Target *tgt, core::World &world, std::mt19937 &masterSeeder)
	Updates a target from JSON without full context recreation.
void	update_timing_from_json (const nlohmann::json &j, core::World &world, SimId id)
	Updates a timing source from JSON without full context recreation.
nlohmann::json	world_to_json (const core::World &world)
	Serializes the entire simulation world into a nlohmann::json object.
void	json_to_world (const nlohmann::json &j, core::World &world, std::mt19937 &masterSeeder)
	Deserializes a nlohmann::json object and reconstructs the simulation world.
std::unique_ptr< RadarSignal >	loadWaveformFromFile (const std::string &name, const std::string &filename, RealType power, RealType carrierFreq, const SimId id=0)
	Loads a radar waveform from a file and returns a RadarSignal object.
void	parseSimulation (const std::string &filename, core::World *world, bool validate, std::mt19937 &masterSeeder)
	Parses a simulation configuration from an XML file.
void	parseSimulationFromString (const std::string &xmlContent, core::World *world, bool validate, std::mt19937 &masterSeeder)
	Parses a simulation configuration directly from an XML string in memory.
std::string	world_to_xml_string (const core::World &world)
	Serializes the entire simulation world into an XML formatted string.

Variables
std::mutex	hdf5_global_mutex
	Global mutex to protect all HDF5 C-library calls, which are not thread-safe.

Function Documentation

addChunkToFile()

void serial::addChunkToFile	(	HighFive::File &	file,
		const std::vector< ComplexType > &	data,
		RealType	time,
		RealType	fullscale,
		unsigned	count,
		const core::PulseChunkMetadata *	metadata = nullptr
	)

Adds a chunk of data to an HDF5 file.

Parameters

file	The HDF5 file where the chunk is written.
data	A vector of complex data to be written.
time	The time attribute associated with the chunk.
fullscale	The fullscale attribute for the chunk.
count	The sequential count number for chunk naming.

Exceptions

std::runtime_error

If there is an error writing data or setting attributes.

Definition at line 92 of file hdf5_handler.cpp.

    {
        std::scoped_lock lock(hdf5_global_mutex);
 
        const std::size_t size = data.size();
 
        const std::string base_chunk_name = "chunk_" + std::format("{:06}", count);
        const std::string i_chunk_name = base_chunk_name + "_I";
        const std::string q_chunk_name = base_chunk_name + "_Q";
 
        std::vector<RealType> i(size), q(size);
        std::ranges::transform(data, i.begin(), [](const ComplexType& c) { return c.real(); });
        std::ranges::transform(data, q.begin(), [](const ComplexType& c) { return c.imag(); });
 
        auto write_chunk = [&](const std::string& chunkName, const std::vector<RealType>& chunkData)
        {
            try
            {
                HighFive::DataSet dataset =
                    file.createDataSet<RealType>(chunkName, HighFive::DataSpace::From(chunkData));
                dataset.write(chunkData);
            }
            catch (const HighFive::Exception& err)
            {
                LOG(Level::FATAL, "Error while writing data to HDF5 file: {}", err.what());
                throw std::runtime_error("Error while writing data to HDF5 file: " + chunkName + " - " + err.what());
            }
        };
 
        auto set_chunk_attributes = [&](const std::string& chunkName)
        {
            try
            {
                HighFive::DataSet dataset = file.getDataSet(chunkName);
                dataset.createAttribute("time", time);
                dataset.createAttribute("rate", params::rate());
                dataset.createAttribute("fullscale", fullscale);
                if (metadata != nullptr)
                {
                    dataset.createAttribute("chunk_index", metadata->chunk_index);
                    dataset.createAttribute("sample_count", static_cast<unsigned long long>(metadata->sample_count));
                    dataset.createAttribute("sample_start", static_cast<unsigned long long>(metadata->sample_start));
                    dataset.createAttribute("sample_end_exclusive",
                                            static_cast<unsigned long long>(metadata->sample_end_exclusive));
                }
            }
            catch (const HighFive::Exception& err)
            {
                LOG(Level::FATAL, "Error while setting attributes on chunk: {}", err.what());
                throw std::runtime_error("Error while setting attributes on chunk: " + chunkName + " - " + err.what());
            }
        };
 
        write_chunk(i_chunk_name, i);
        write_chunk(q_chunk_name, q);
 
        set_chunk_attributes(i_chunk_name);
        set_chunk_attributes(q_chunk_name);
    }

References core::PulseChunkMetadata::chunk_index, hdf5_global_mutex, LOG, params::rate(), core::PulseChunkMetadata::sample_count, core::PulseChunkMetadata::sample_end_exclusive, and core::PulseChunkMetadata::sample_start.

Referenced by processing::runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

json_to_world()

void serial::json_to_world	(	const nlohmann::json &	j,
		core::World &	world,
		std::mt19937 &	masterSeeder
	)

Deserializes a nlohmann::json object and reconstructs the simulation world.

This function is the counterpart to world_to_json. It performs a full state replacement by clearing the existing world and rebuilding it from the provided JSON. This "replace" strategy simplifies state management, guaranteeing that the C++ core is always perfectly synchronized with the state provided by the UI without requiring complex diffing or patching logic. It also handles re-seeding the master random number generator to ensure that loading a state also restores its deterministic behavior.

Parameters

j	The json object to deserialize.
world	The world object to populate.
masterSeeder	A reference to the master random number generator, which will be re-seeded.

Definition at line 1574 of file json_serializer.cpp.

    {
        // 1. Clear the existing world state. This function always performs a full
        //    replacement to ensure the C++ state is a perfect mirror of the UI state.
        world.clear();
 
        const auto& sim = j.at("simulation");
 
        parse_parameters(sim, masterSeeder);
        parse_assets(sim, world);
 
        // 3. Restore platforms and their components.
        if (sim.contains("platforms"))
        {
            for (const auto& plat_json : sim.at("platforms"))
            {
                parse_platform(plat_json, world, masterSeeder);
            }
        }
 
        // 4. Finalize world state after all objects are loaded.
 
        // Prepare CW receiver buffers before starting simulation
        const RealType start_time = params::startTime();
        const RealType end_time = params::endTime();
        const RealType dt_sim = 1.0 / (params::rate() * params::oversampleRatio());
        const auto num_samples = static_cast<size_t>(std::ceil((end_time - start_time) / dt_sim));
 
        for (const auto& receiver : world.getReceivers())
        {
            if (receiver->getMode() == radar::OperationMode::CW_MODE)
            {
                receiver->prepareCwData(num_samples);
            }
        }
 
        // Schedule initial events after all objects are loaded.
        world.scheduleInitialEvents();
    }

References core::World::clear(), radar::CW_MODE, params::endTime(), core::World::getReceivers(), params::oversampleRatio(), params::rate(), core::World::scheduleInitialEvents(), and params::startTime().

Referenced by fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

loadWaveformFromFile()

std::unique_ptr< fers_signal::RadarSignal > serial::loadWaveformFromFile	(	const std::string &	name,
		const std::string &	filename,
		RealType	power,
		RealType	carrierFreq,
		const SimId	id = 0
	)

Loads a radar waveform from a file and returns a RadarSignal object.

Parameters

name	The name of the radar signal.
filename	The path to the file containing the waveform data.
power	The power of the radar signal in the waveform.
carrierFreq	The carrier frequency of the radar signal.

Returns

A unique pointer to a RadarSignal object loaded with the waveform data.

Exceptions

std::runtime_error

If the file cannot be opened or the file format is unrecognized.

Definition at line 155 of file waveform_factory.cpp.

    {
        const std::filesystem::path filepath = filename;
        const auto extension = filepath.extension().string();
 
        if (hasExtension(extension, ".csv"))
        {
            auto wave = loadWaveformFromCsvFile(name, filepath, power, carrierFreq, id);
            wave->setFilename(filename);
            return wave;
        }
        if (hasExtension(extension, ".h5"))
        {
            auto wave = loadWaveformFromHdf5File(name, filepath, power, carrierFreq, id);
            wave->setFilename(filename);
            return wave;
        }
 
        LOG(logging::Level::FATAL, "Unrecognized file extension '{}' for file: '{}'", extension, filename);
        throw std::runtime_error("Unrecognized file extension '" + extension + "' for file: " + filename);
    }

References logging::FATAL, and LOG.

Referenced by serial::xml_parser_utils::createDefaultAssetLoaders(), and fers_signal::from_json().

Here is the caller graph for this function:

parse_antenna_from_json()

std::unique_ptr< antenna::Antenna > serial::parse_antenna_from_json

(

const nlohmann::json &

j

)

Parses an Antenna from JSON.

Definition at line 1113 of file json_serializer.cpp.

    {
        std::unique_ptr<antenna::Antenna> ant;
        antenna::from_json(j, ant);
        return ant;
    }

References antenna::from_json().

Referenced by update_antenna_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

parse_timing_from_json()

std::unique_ptr< timing::PrototypeTiming > serial::parse_timing_from_json	(	const nlohmann::json &	j,
		const SimId	id
	)

Parses a timing prototype from JSON.

Definition at line 1127 of file json_serializer.cpp.

    {
        auto timing = std::make_unique<timing::PrototypeTiming>(j.at("name").get<std::string>(), id);
        j.get_to(*timing);
        return timing;
    }

Referenced by update_timing_from_json().

Here is the caller graph for this function:

parse_waveform_from_json()

std::unique_ptr< fers_signal::RadarSignal > serial::parse_waveform_from_json

(

const nlohmann::json &

j

)

Parses a Waveform from JSON.

Definition at line 1120 of file json_serializer.cpp.

    {
        std::unique_ptr<fers_signal::RadarSignal> wf;
        fers_signal::from_json(j, wf);
        return wf;
    }

References fers_signal::from_json().

Referenced by fers_update_waveform_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

parseSimulation()

void serial::parseSimulation	(	const std::string &	filename,
		core::World *	world,
		bool	validate,
		std::mt19937 &	masterSeeder
	)

Parses a simulation configuration from an XML file.

This function acts as the primary facade for the simulator's XML loading pipeline. It performs the following steps:

1. Resets the target World and global parameters (params::params).
2. Loads the main XML file.
3. Recursively finds and merges any <include> files into the main document.
4. Optionally validates the combined document against the built-in DTD and XSD schemas.
5. Uses the internal parser utilities to instantiate simulation objects.
6. Updates the global params::params with the parsed context parameters.

Parameters

filename	The filesystem path to the main XML simulation script.
world	A pointer to the World object to be populated with parsed components.
validate	A boolean indicating whether to perform strict XML schema validation.
masterSeeder	A reference to the master random number generator used for assigning independent seeds to components.

Exceptions

XmlException	if the XML is malformed, fails schema validation, or contains invalid scenario logic.
std::runtime_error	for file I/O errors or other critical setup issues.

Definition at line 25 of file xml_parser.cpp.

    {
        world->clear();
        params::params.reset();
 
        XmlDocument main_doc;
        if (!main_doc.loadFile(filename))
        {
            throw XmlException("Failed to load main XML file: " + filename);
        }
 
        const std::filesystem::path main_dir = std::filesystem::path(filename).parent_path();
        const bool did_combine = xml_parser_utils::addIncludeFilesToMainDocument(main_doc, main_dir);
 
        if (validate)
        {
            xml_parser_utils::validateXml(did_combine, main_doc);
        }
        else
        {
            LOG(logging::Level::DEBUG, "Skipping XML validation.");
        }
 
        xml_parser_utils::ParserContext ctx;
        ctx.world = world;
        ctx.master_seeder = &masterSeeder;
        ctx.base_dir = main_dir;
        ctx.loaders = xml_parser_utils::createDefaultAssetLoaders();
 
        xml_parser_utils::processParsedDocument(main_doc, ctx);
 
        // Push the isolated context parameters into global application parameters
        params::params = ctx.parameters;
    }

References serial::xml_parser_utils::addIncludeFilesToMainDocument(), serial::xml_parser_utils::ParserContext::base_dir, core::World::clear(), serial::xml_parser_utils::createDefaultAssetLoaders(), logging::DEBUG, serial::xml_parser_utils::ParserContext::loaders, XmlDocument::loadFile(), LOG, serial::xml_parser_utils::ParserContext::master_seeder, serial::xml_parser_utils::ParserContext::parameters, params::params, serial::xml_parser_utils::processParsedDocument(), params::Parameters::reset(), serial::xml_parser_utils::validateXml(), and serial::xml_parser_utils::ParserContext::world.

Referenced by fers_load_scenario_from_xml_file().

Here is the call graph for this function:

Here is the caller graph for this function:

parseSimulationFromString()

void serial::parseSimulationFromString	(	const std::string &	xmlContent,
		core::World *	world,
		bool	validate,
		std::mt19937 &	masterSeeder
	)

Parses a simulation configuration directly from an XML string in memory.

Similar to parseSimulation, but operates on a raw string instead of a file. Because it does not load from the filesystem, <include> tags are ignored, and any relative paths for file-backed assets (like waveforms or antennas) will be resolved against the current working directory (.).

Parameters

xmlContent	The raw XML string containing the scenario definition.
world	A pointer to the World object to be populated with parsed components.
validate	A boolean indicating whether to perform strict XML schema validation.
masterSeeder	A reference to the master random number generator used for assigning independent seeds to components.

Exceptions

XmlException

if the XML string is malformed, fails schema validation, or contains invalid scenario logic.

Definition at line 61 of file xml_parser.cpp.

    {
        world->clear();
        params::params.reset();
 
        XmlDocument doc;
        if (!doc.loadString(xmlContent))
        {
            throw XmlException("Failed to parse XML from memory string.");
        }
 
        if (validate)
        {
            // Note: <include> tags are not processed when loading from a string.
            xml_parser_utils::validateXml(false, doc);
        }
        else
        {
            LOG(logging::Level::DEBUG, "Skipping XML validation.");
        }
 
        // When loading from a string, there's no base directory for relative asset paths.
        // The UI/caller is responsible for ensuring any paths in the XML are absolute or resolvable.
        const std::filesystem::path base_dir = ".";
 
        xml_parser_utils::ParserContext ctx;
        ctx.world = world;
        ctx.master_seeder = &masterSeeder;
        ctx.base_dir = base_dir;
        ctx.loaders = xml_parser_utils::createDefaultAssetLoaders();
 
        xml_parser_utils::processParsedDocument(doc, ctx);
 
        // Push the isolated context parameters into global application parameters
        params::params = ctx.parameters;
    }

References serial::xml_parser_utils::ParserContext::base_dir, core::World::clear(), serial::xml_parser_utils::createDefaultAssetLoaders(), logging::DEBUG, serial::xml_parser_utils::ParserContext::loaders, XmlDocument::loadString(), LOG, serial::xml_parser_utils::ParserContext::master_seeder, serial::xml_parser_utils::ParserContext::parameters, params::params, serial::xml_parser_utils::processParsedDocument(), params::Parameters::reset(), serial::xml_parser_utils::validateXml(), and serial::xml_parser_utils::ParserContext::world.

Referenced by fers_load_scenario_from_xml_string().

Here is the call graph for this function:

Here is the caller graph for this function:

readPattern()

std::vector< std::vector< RealType > > serial::readPattern	(	const std::string &	name,
		const std::string &	datasetName
	)

Reads a 2D pattern dataset from an HDF5 file.

Parameters

name	The name of the HDF5 file.
datasetName	The name of the dataset to be read.

Returns

A 2D vector containing the pattern data.

Exceptions

std::runtime_error

If there is an error handling the file or if the dataset dimensions are invalid.

Definition at line 153 of file hdf5_handler.cpp.

    {
        std::scoped_lock lock(hdf5_global_mutex);
        try
        {
            LOG(Level::TRACE, "Reading dataset '{}' from file '{}'", datasetName, name);
            const HighFive::File file(name, HighFive::File::ReadOnly);
 
            const auto dataset = file.getDataSet(datasetName);
 
            const auto dataspace = dataset.getSpace();
            const auto dims = dataspace.getDimensions();
 
            if (dims.size() != 2)
            {
                LOG(Level::FATAL, "Invalid dataset dimensions for '{}' in file '{}'", datasetName, name);
                throw std::runtime_error(
                    std::format(R"(Invalid dataset dimensions for "{}" in file "{}")", datasetName, name));
            }
 
            LOG(Level::TRACE, "Reading dataset with dimensions {}x{}", dims[0], dims[1]);
 
            std::vector data(dims[0], std::vector<RealType>(dims[1]));
            dataset.read(data);
 
            LOG(Level::TRACE, "Read dataset successfully");
 
            return data;
        }
        catch (const HighFive::Exception& err)
        {
            LOG(Level::FATAL, "Error handling HDF5 file: {}", err.what());
            throw std::runtime_error("Error handling HDF5 file: " + std::string(err.what()));
        }
    }

References hdf5_global_mutex, and LOG.

readPulseData()

void serial::readPulseData	(	const std::string &	name,
		std::vector< ComplexType > &	data
	)

Reads pulse data from an HDF5 file.

Parameters

name	The name of the HDF5 file.
data	A reference to a vector where the complex data will be stored.

Exceptions

std::runtime_error

If the file does not exist or the datasets "I" and "Q" have mismatched sizes.

Definition at line 43 of file hdf5_handler.cpp.

    {
        std::scoped_lock lock(hdf5_global_mutex);
 
        if (!std::filesystem::exists(name))
        {
            LOG(Level::FATAL, "File '{}' not found", name);
            throw std::runtime_error("File " + name + " not found.");
        }
 
        LOG(Level::TRACE, "Opening file '{}'", name);
        const HighFive::File file(name, HighFive::File::ReadOnly);
 
        // Helper lambda to open group and read dataset
        auto read_dataset = [&file](const std::string& groupName, std::vector<double>& buffer) -> size_t
        {
            const auto group = file.getGroup("/" + groupName);
 
            const auto dataset = group.getDataSet("value");
 
            const auto dimensions = dataset.getSpace().getDimensions();
            const auto size = dimensions[0];
 
            buffer.resize(size);
            dataset.read(buffer);
 
            return size;
        };
 
        LOG(Level::TRACE, "Reading dataset 'I' from file '{}'", name);
        std::vector<double> buffer_i;
        const auto size = read_dataset("I", buffer_i);
 
        std::vector<double> buffer_q;
        LOG(Level::TRACE, "Reading dataset 'Q' from file '{}'", name);
        if (read_dataset("Q", buffer_q) != size)
        {
            LOG(Level::FATAL, "Dataset 'Q' is not the same size as dataset 'I' in file '{}'", name);
            throw std::runtime_error(R"(Dataset "Q" is not the same size as dataset "I" in file )" + name);
        }
 
        data.resize(size);
        for (size_t i = 0; i < size; ++i)
        {
            data[i] = ComplexType(buffer_i[i], buffer_q[i]);
        }
        LOG(Level::TRACE, "Read dataset successfully");
    }

References hdf5_global_mutex, and LOG.

update_antenna_from_json()

void serial::update_antenna_from_json	(	const nlohmann::json &	j,
		antenna::Antenna *	ant,
		core::World &	world
	)

Updates an antenna from JSON without full context recreation.

Definition at line 1141 of file json_serializer.cpp.

    {
        auto new_pattern = j.value("pattern", "isotropic");
        bool type_changed = false;
 
        const auto parse_required_antenna = [&j]()
        {
            auto parsed = parse_antenna_from_json(j);
            if (parsed == nullptr)
            {
                const auto name = j.value("name", std::string{});
                const auto pattern = j.value("pattern", "isotropic");
                throw std::runtime_error("Cannot update antenna '" + name + "' to pattern '" + pattern +
                                         "' without a filename.");
            }
            return parsed;
        };
 
        if (new_pattern == "isotropic" && (dynamic_cast<antenna::Isotropic*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "sinc" && (dynamic_cast<antenna::Sinc*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "gaussian" && (dynamic_cast<antenna::Gaussian*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "squarehorn" && (dynamic_cast<antenna::SquareHorn*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "parabolic" && (dynamic_cast<antenna::Parabolic*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "xml" && (dynamic_cast<antenna::XmlAntenna*>(ant) == nullptr))
            type_changed = true;
        else if (new_pattern == "file" && (dynamic_cast<antenna::H5Antenna*>(ant) == nullptr))
            type_changed = true;
 
        if (type_changed)
        {
            world.replace(parse_required_antenna());
            return;
        }
 
        ant->setName(j.at("name").get<std::string>());
        ant->setEfficiencyFactor(j.value("efficiency", 1.0));
 
        if (auto* sinc = dynamic_cast<antenna::Sinc*>(ant))
        {
            sinc->setAlpha(j.value("alpha", 1.0));
            sinc->setBeta(j.value("beta", 1.0));
            sinc->setGamma(j.value("gamma", 2.0));
        }
        else if (auto* gauss = dynamic_cast<antenna::Gaussian*>(ant))
        {
            gauss->setAzimuthScale(j.value("azscale", 1.0));
            gauss->setElevationScale(j.value("elscale", 1.0));
        }
        else if (auto* horn = dynamic_cast<antenna::SquareHorn*>(ant))
        {
            horn->setDimension(j.value("diameter", 0.5));
        }
        else if (auto* para = dynamic_cast<antenna::Parabolic*>(ant))
        {
            para->setDiameter(j.value("diameter", 0.5));
        }
        else if (auto* xml = dynamic_cast<antenna::XmlAntenna*>(ant))
        {
            if (xml->getFilename() != j.value("filename", ""))
            {
                world.replace(parse_required_antenna());
            }
        }
        else if (auto* h5 = dynamic_cast<antenna::H5Antenna*>(ant))
        {
            if (h5->getFilename() != j.value("filename", ""))
            {
                world.replace(parse_required_antenna());
            }
        }
    }

References parse_antenna_from_json(), core::World::replace(), antenna::Antenna::setEfficiencyFactor(), and antenna::Antenna::setName().

Referenced by fers_update_antenna_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_monostatic_from_json()

void serial::update_monostatic_from_json	(	const nlohmann::json &	j,
		radar::Transmitter *	tx,
		radar::Receiver *	rx,
		core::World &	world,
		std::mt19937 &	masterSeeder
	)

Updates a monostatic radar from JSON without full context recreation.

Definition at line 1418 of file json_serializer.cpp.

    {
        update_transmitter_from_json(j, tx, world, masterSeeder);
 
        if (j.contains("name"))
            rx->setName(j.at("name").get<std::string>());
        rx->setMode(tx->getMode());
        if (rx->getMode() == radar::OperationMode::PULSED_MODE && j.contains("pulsed_mode"))
        {
            const auto& mode_json = j.at("pulsed_mode");
            rx->setWindowProperties(mode_json.value("window_length", 0.0), tx->getPrf(),
                                    mode_json.value("window_skip", 0.0));
        }
        if (j.contains("noise_temp"))
            rx->setNoiseTemperature(j.value("noise_temp", 0.0));
        if (j.contains("nodirect"))
        {
            if (j.value("nodirect", false))
                rx->setFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
            else
                rx->clearFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
        }
        if (j.contains("nopropagationloss"))
        {
            if (j.value("nopropagationloss", false))
                rx->setFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
            else
                rx->clearFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
        }
        if (j.contains("antenna"))
            rx->setAntenna(world.findAntenna(parse_json_id(j, "antenna", "Monostatic")));
        if (j.contains("timing"))
        {
            auto timing_id = parse_json_id(j, "timing", "Monostatic");
            if (auto* const timing_proto = world.findTiming(timing_id))
            {
                unsigned seed = rx->getTiming() ? rx->getTiming()->getSeed() : 0;
                auto rx_timing = std::make_shared<timing::Timing>(timing_proto->getName(), seed, timing_proto->getId());
                rx_timing->initializeModel(timing_proto);
                rx->setTiming(rx_timing);
            }
            else
            {
                rx->setTiming(nullptr);
            }
        }
        if (j.contains("schedule"))
        {
            auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
            RealType pri = 0.0;
            if (tx->getMode() == radar::OperationMode::PULSED_MODE)
                pri = 1.0 / tx->getPrf();
            auto processed_schedule = radar::processRawSchedule(
                std::move(raw), tx->getName(), tx->getMode() == radar::OperationMode::PULSED_MODE, pri);
            tx->setSchedule(processed_schedule);
            rx->setSchedule(processed_schedule);
        }
    }

References radar::Receiver::clearFlag(), core::World::findAntenna(), core::World::findTiming(), radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, radar::Receiver::getMode(), radar::Transmitter::getMode(), radar::Object::getName(), radar::Transmitter::getPrf(), radar::Radar::getTiming(), radar::processRawSchedule(), radar::PULSED_MODE, radar::Radar::setAntenna(), radar::Receiver::setFlag(), radar::Receiver::setMode(), radar::Object::setName(), radar::Receiver::setNoiseTemperature(), radar::Receiver::setSchedule(), radar::Transmitter::setSchedule(), radar::Radar::setTiming(), radar::Receiver::setWindowProperties(), and update_transmitter_from_json().

Referenced by fers_update_monostatic_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_parameters_from_json()

void serial::update_parameters_from_json	(	const nlohmann::json &	j,
		std::mt19937 &	masterSeeder
	)

Updates global simulation parameters from JSON.

Definition at line 1134 of file json_serializer.cpp.

    {
        nlohmann::json sim;
        sim["parameters"] = j;
        parse_parameters(sim, masterSeeder);
    }

Referenced by fers_update_parameters_from_json().

Here is the caller graph for this function:

update_platform_paths_from_json()

void serial::update_platform_paths_from_json	(	const nlohmann::json &	j,
		radar::Platform *	plat
	)

Updates a platform's motion and rotation paths from JSON.

Definition at line 1218 of file json_serializer.cpp.

    {
        if (j.contains("motionpath"))
        {
            auto path = std::make_unique<math::Path>();
            j.at("motionpath").get_to(*path);
            plat->setMotionPath(std::move(path));
        }
        if (j.contains("rotationpath"))
        {
            auto rot_path = std::make_unique<math::RotationPath>();
            const auto& rotation_json = j.at("rotationpath");
            rot_path->setInterp(rotation_json.at("interpolation").get<math::RotationPath::InterpType>());
            unsigned waypoint_index = 0;
            for (const auto& waypoint_json : rotation_json.at("rotationwaypoints"))
            {
                const RealType azimuth = waypoint_json.at("azimuth").get<RealType>();
                const RealType elevation = waypoint_json.at("elevation").get<RealType>();
                const RealType time = waypoint_json.at("time").get<RealType>();
                const std::string owner =
                    std::format("platform '{}' rotation waypoint {}", plat->getName(), waypoint_index);
 
                rotation_warning_utils::maybe_warn_about_rotation_value(azimuth, params::rotationAngleUnit(),
                                                                        rotation_warning_utils::ValueKind::Angle,
                                                                        "JSON", owner, "azimuth");
                rotation_warning_utils::maybe_warn_about_rotation_value(elevation, params::rotationAngleUnit(),
                                                                        rotation_warning_utils::ValueKind::Angle,
                                                                        "JSON", owner, "elevation");
 
                rot_path->addCoord(rotation_angle_utils::external_rotation_to_internal(azimuth, elevation, time,
                                                                                       params::rotationAngleUnit()));
                ++waypoint_index;
            }
            rot_path->finalize();
            plat->setRotationPath(std::move(rot_path));
        }
        else if (j.contains("fixedrotation"))
        {
            auto rot_path = std::make_unique<math::RotationPath>();
            const auto& fixed_json = j.at("fixedrotation");
            const RealType start_az_deg = fixed_json.at("startazimuth").get<RealType>();
            const RealType start_el_deg = fixed_json.at("startelevation").get<RealType>();
            const RealType rate_az_deg_s = fixed_json.at("azimuthrate").get<RealType>();
            const RealType rate_el_deg_s = fixed_json.at("elevationrate").get<RealType>();
            const std::string owner = std::format("platform '{}' fixedrotation", plat->getName());
 
            rotation_warning_utils::maybe_warn_about_rotation_value(start_az_deg, params::rotationAngleUnit(),
                                                                    rotation_warning_utils::ValueKind::Angle, "JSON",
                                                                    owner, "startazimuth");
            rotation_warning_utils::maybe_warn_about_rotation_value(start_el_deg, params::rotationAngleUnit(),
                                                                    rotation_warning_utils::ValueKind::Angle, "JSON",
                                                                    owner, "startelevation");
            rotation_warning_utils::maybe_warn_about_rotation_value(rate_az_deg_s, params::rotationAngleUnit(),
                                                                    rotation_warning_utils::ValueKind::Rate, "JSON",
                                                                    owner, "azimuthrate");
            rotation_warning_utils::maybe_warn_about_rotation_value(rate_el_deg_s, params::rotationAngleUnit(),
                                                                    rotation_warning_utils::ValueKind::Rate, "JSON",
                                                                    owner, "elevationrate");
 
            const auto start = serial::rotation_angle_utils::external_rotation_to_internal(
                start_az_deg, start_el_deg, 0.0, params::rotationAngleUnit());
            const auto rate = serial::rotation_angle_utils::external_rotation_rate_to_internal(
                rate_az_deg_s, rate_el_deg_s, 0.0, params::rotationAngleUnit());
            rot_path->setConstantRate(start, rate);
            rot_path->finalize();
            plat->setRotationPath(std::move(rot_path));
        }
    }

References serial::rotation_warning_utils::Angle, serial::rotation_angle_utils::external_rotation_rate_to_internal(), serial::rotation_angle_utils::external_rotation_to_internal(), radar::Platform::getName(), serial::rotation_warning_utils::maybe_warn_about_rotation_value(), serial::rotation_warning_utils::Rate, params::rotationAngleUnit(), radar::Platform::setMotionPath(), and radar::Platform::setRotationPath().

Referenced by fers_update_platform_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_receiver_from_json()

void serial::update_receiver_from_json	(	const nlohmann::json &	j,
		radar::Receiver *	rx,
		core::World &	world,
		std::mt19937 &
	)

Updates a receiver from JSON without full context recreation.

Definition at line 1347 of file json_serializer.cpp.

    {
        if (j.contains("name"))
            rx->setName(j.at("name").get<std::string>());
 
        if (j.contains("pulsed_mode"))
        {
            rx->setMode(radar::OperationMode::PULSED_MODE);
            const auto& mode_json = j.at("pulsed_mode");
            rx->setWindowProperties(mode_json.value("window_length", 0.0), mode_json.value("prf", 0.0),
                                    mode_json.value("window_skip", 0.0));
        }
        else if (j.contains("cw_mode"))
        {
            rx->setMode(radar::OperationMode::CW_MODE);
        }
 
        if (j.contains("noise_temp"))
            rx->setNoiseTemperature(j.value("noise_temp", 0.0));
 
        if (j.contains("nodirect"))
        {
            if (j.value("nodirect", false))
                rx->setFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
            else
                rx->clearFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
        }
        if (j.contains("nopropagationloss"))
        {
            if (j.value("nopropagationloss", false))
                rx->setFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
            else
                rx->clearFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
        }
 
        if (j.contains("antenna"))
        {
            auto id = parse_json_id(j, "antenna", "Receiver");
            auto* ant = world.findAntenna(id);
            if (ant == nullptr)
                throw std::runtime_error("Antenna ID " + std::to_string(id) + " not found.");
            rx->setAntenna(ant);
        }
 
        if (j.contains("timing"))
        {
            auto timing_id = parse_json_id(j, "timing", "Receiver");
            if (auto* const timing_proto = world.findTiming(timing_id))
            {
                unsigned seed = rx->getTiming() ? rx->getTiming()->getSeed() : 0;
                auto timing = std::make_shared<timing::Timing>(timing_proto->getName(), seed, timing_proto->getId());
                timing->initializeModel(timing_proto);
                rx->setTiming(timing);
            }
            else
            {
                throw std::runtime_error("Timing ID " + std::to_string(timing_id) + " not found.");
            }
        }
        if (j.contains("schedule"))
        {
            auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
            RealType pri = 0.0;
            if (rx->getMode() == radar::OperationMode::PULSED_MODE)
                pri = 1.0 / rx->getWindowPrf();
            rx->setSchedule(radar::processRawSchedule(std::move(raw), rx->getName(),
                                                      rx->getMode() == radar::OperationMode::PULSED_MODE, pri));
        }
    }

References radar::Receiver::clearFlag(), radar::CW_MODE, core::World::findAntenna(), core::World::findTiming(), radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, radar::Receiver::getMode(), radar::Object::getName(), radar::Radar::getTiming(), radar::Receiver::getWindowPrf(), radar::processRawSchedule(), radar::PULSED_MODE, radar::Radar::setAntenna(), radar::Receiver::setFlag(), radar::Receiver::setMode(), radar::Object::setName(), radar::Receiver::setNoiseTemperature(), radar::Receiver::setSchedule(), radar::Radar::setTiming(), and radar::Receiver::setWindowProperties().

Referenced by fers_update_receiver_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_target_from_json()

void serial::update_target_from_json	(	const nlohmann::json &	j,
		radar::Target *	existing_tgt,
		core::World &	world,
		std::mt19937 &
	)

Updates a target from JSON without full context recreation.

Definition at line 1478 of file json_serializer.cpp.

    {
        auto* plat = existing_tgt->getPlatform();
        const auto& rcs_json = j.at("rcs");
        const auto rcs_type = rcs_json.at("type").get<std::string>();
        std::unique_ptr<radar::Target> target_obj;
 
        const auto target_id = existing_tgt->getId();
        const auto name = j.value("name", existing_tgt->getName());
        unsigned seed = existing_tgt->getSeed();
 
        if (rcs_type == "isotropic")
        {
            target_obj = radar::createIsoTarget(plat, name, rcs_json.value("value", 1.0), seed, target_id);
        }
        else if (rcs_type == "file")
        {
            const auto filename = rcs_json.value("filename", "");
            target_obj = radar::createFileTarget(plat, name, filename, seed, target_id);
        }
        else
        {
            throw std::runtime_error("Unsupported target RCS type: " + rcs_type);
        }
 
        if (j.contains("model"))
        {
            const auto& model_json = j.at("model");
            const auto model_type = model_json.at("type").get<std::string>();
            if (model_type == "chisquare" || model_type == "gamma")
            {
                auto model =
                    std::make_unique<radar::RcsChiSquare>(target_obj->getRngEngine(), model_json.value("k", 1.0));
                target_obj->setFluctuationModel(std::move(model));
            }
            else if (model_type == "constant")
            {
                target_obj->setFluctuationModel(std::make_unique<radar::RcsConst>());
            }
        }
 
        world.replace(std::move(target_obj));
    }

References radar::createFileTarget(), radar::createIsoTarget(), radar::Target::getId(), radar::Object::getName(), radar::Object::getPlatform(), radar::Target::getSeed(), and core::World::replace().

Referenced by fers_update_target_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_timing_from_json()

void serial::update_timing_from_json	(	const nlohmann::json &	j,
		core::World &	world,
		const SimId	id
	)

Updates a timing source from JSON without full context recreation.

Definition at line 1523 of file json_serializer.cpp.

    {
        auto* existing = world.findTiming(id);
        if (existing == nullptr)
        {
            throw std::runtime_error("Timing ID " + std::to_string(id) + " not found.");
        }
 
        auto patched = j;
        if (!patched.contains("name"))
        {
            patched["name"] = existing->getName();
        }
 
        world.replace(parse_timing_from_json(patched, id));
    }

References core::World::findTiming(), parse_timing_from_json(), and core::World::replace().

Referenced by fers_update_timing_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

update_transmitter_from_json()

void serial::update_transmitter_from_json	(	const nlohmann::json &	j,
		radar::Transmitter *	tx,
		core::World &	world,
		std::mt19937 &
	)

Updates a transmitter from JSON without full context recreation.

Definition at line 1287 of file json_serializer.cpp.

    {
        if (j.contains("name"))
            tx->setName(j.at("name").get<std::string>());
 
        if (j.contains("pulsed_mode"))
        {
            tx->setMode(radar::OperationMode::PULSED_MODE);
            tx->setPrf(j.at("pulsed_mode").value("prf", 0.0));
        }
        else if (j.contains("cw_mode"))
        {
            tx->setMode(radar::OperationMode::CW_MODE);
        }
 
        if (j.contains("waveform"))
        {
            auto id = parse_json_id(j, "waveform", "Transmitter");
            auto* wf = world.findWaveform(id);
            if (wf == nullptr)
                throw std::runtime_error("Waveform ID " + std::to_string(id) + " not found.");
            tx->setWave(wf);
        }
 
        if (j.contains("antenna"))
        {
            auto id = parse_json_id(j, "antenna", "Transmitter");
            auto* ant = world.findAntenna(id);
            if (ant == nullptr)
                throw std::runtime_error("Antenna ID " + std::to_string(id) + " not found.");
            tx->setAntenna(ant);
        }
 
        if (j.contains("timing"))
        {
            auto timing_id = parse_json_id(j, "timing", "Transmitter");
            if (auto* const timing_proto = world.findTiming(timing_id))
            {
                unsigned seed = tx->getTiming() ? tx->getTiming()->getSeed() : 0;
                auto timing = std::make_shared<timing::Timing>(timing_proto->getName(), seed, timing_proto->getId());
                timing->initializeModel(timing_proto);
                tx->setTiming(timing);
            }
            else
            {
                throw std::runtime_error("Timing ID " + std::to_string(timing_id) + " not found.");
            }
        }
        if (j.contains("schedule"))
        {
            auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
            RealType pri = 0.0;
            if (tx->getMode() == radar::OperationMode::PULSED_MODE)
                pri = 1.0 / tx->getPrf();
            tx->setSchedule(radar::processRawSchedule(std::move(raw), tx->getName(),
                                                      tx->getMode() == radar::OperationMode::PULSED_MODE, pri));
        }
    }

References radar::CW_MODE, core::World::findAntenna(), core::World::findTiming(), core::World::findWaveform(), radar::Transmitter::getMode(), radar::Object::getName(), radar::Transmitter::getPrf(), radar::Radar::getTiming(), radar::processRawSchedule(), radar::PULSED_MODE, radar::Radar::setAntenna(), radar::Transmitter::setMode(), radar::Object::setName(), radar::Transmitter::setPrf(), radar::Transmitter::setSchedule(), radar::Radar::setTiming(), and radar::Transmitter::setWave().

Referenced by fers_update_transmitter_from_json(), and update_monostatic_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

world_to_json()

nlohmann::json serial::world_to_json

(

const core::World &

world

)

Serializes the entire simulation world into a nlohmann::json object.

This function traverses the core::World object model and constructs a JSON representation. It is designed to produce a format that is convenient for the frontend to consume. This involves translating internal data formats (e.g., angles in radians) to a more UI-friendly format (e.g., compass degrees) and restructuring complex object relationships (like monostatic radars) into simpler representations.

Parameters

world

The world object to serialize.

Returns

A nlohmann::json object representing the world.

Definition at line 1540 of file json_serializer.cpp.

    {
        nlohmann::json sim_json;
 
        sim_json["name"] = params::params.simulation_name;
        sim_json["parameters"] = params::params;
 
        sim_json["waveforms"] = nlohmann::json::array();
        for (const auto& waveform : world.getWaveforms() | std::views::values)
        {
            sim_json["waveforms"].push_back(*waveform);
        }
 
        sim_json["antennas"] = nlohmann::json::array();
        for (const auto& antenna : world.getAntennas() | std::views::values)
        {
            sim_json["antennas"].push_back(*antenna);
        }
 
        sim_json["timings"] = nlohmann::json::array();
        for (const auto& timing : world.getTimings() | std::views::values)
        {
            sim_json["timings"].push_back(*timing);
        }
 
        sim_json["platforms"] = nlohmann::json::array();
        for (const auto& p : world.getPlatforms())
        {
            sim_json["platforms"].push_back(serialize_platform(p.get(), world));
        }
 
        return {{"simulation", sim_json}};
    }

References core::World::getAntennas(), core::World::getPlatforms(), core::World::getTimings(), core::World::getWaveforms(), params::params, and params::Parameters::simulation_name.

Referenced by fers_get_scenario_as_json().

Here is the call graph for this function:

Here is the caller graph for this function:

world_to_xml_string()

std::string serial::world_to_xml_string

(

const core::World &

world

)

Serializes the entire simulation world into an XML formatted string.

This function serves as the reverse of the XML parser. It is essential for allowing users to modify a scenario in a UI and then export their changes back into a valid FERS XML file that can be used by the CLI or shared. It iterates through the in-memory core::World object and reconstructs the corresponding XML structure.

Parameters

world

The world object to serialize.

Returns

A string containing the XML representation of the world.

Definition at line 26 of file xml_serializer.cpp.

    {
        XmlDocument doc;
        xmlNodePtr sim_node = xmlNewNode(nullptr, reinterpret_cast<const xmlChar*>("simulation"));
        XmlElement root(sim_node);
        doc.setRootElement(root);
 
        const auto& p = params::params;
 
        if (!p.simulation_name.empty())
        {
            root.setAttribute("name", p.simulation_name);
        }
        else
        {
            root.setAttribute("name", "FERS Scenario");
        }
 
        const XmlElement params_elem = root.addChild("parameters");
        xml_serializer_utils::serializeParameters(params_elem, p);
 
        for (const auto& waveform : world.getWaveforms() | std::views::values)
        {
            XmlElement waveform_elem = root.addChild("waveform");
            xml_serializer_utils::serializeWaveform(*waveform, waveform_elem);
        }
        for (const auto& timing : world.getTimings() | std::views::values)
        {
            XmlElement timing_elem = root.addChild("timing");
            xml_serializer_utils::serializeTiming(*timing, timing_elem);
        }
        for (const auto& antenna : world.getAntennas() | std::views::values)
        {
            XmlElement antenna_elem = root.addChild("antenna");
            xml_serializer_utils::serializeAntenna(*antenna, antenna_elem);
        }
        for (const auto& platform : world.getPlatforms())
        {
            XmlElement plat_elem = root.addChild("platform");
            xml_serializer_utils::serializePlatform(*platform, world, plat_elem);
        }
 
        return doc.dumpToString();
    }

References XmlElement::addChild(), XmlDocument::dumpToString(), core::World::getAntennas(), core::World::getPlatforms(), core::World::getTimings(), core::World::getWaveforms(), params::params, serial::xml_serializer_utils::serializeAntenna(), serial::xml_serializer_utils::serializeParameters(), serial::xml_serializer_utils::serializePlatform(), serial::xml_serializer_utils::serializeTiming(), serial::xml_serializer_utils::serializeWaveform(), XmlElement::setAttribute(), and XmlDocument::setRootElement().

Referenced by fers_get_scenario_as_xml().

Here is the call graph for this function:

Here is the caller graph for this function:

writeOutputFileMetadataAttributes()

void serial::writeOutputFileMetadataAttributes	(	HighFive::File &	file,
		const core::OutputFileMetadata &	metadata
	)

Writes additive FERS output metadata attributes to an open HDF5 file.

The caller must hold hdf5_global_mutex.

Definition at line 31 of file hdf5_handler.cpp.

    {
        file.createAttribute("fers_metadata_schema_version", 1U);
        file.createAttribute("fers_metadata_json", core::outputFileMetadataToJsonString(metadata));
        file.createAttribute("receiver_id", static_cast<unsigned long long>(metadata.receiver_id));
        file.createAttribute("receiver_name", metadata.receiver_name);
        file.createAttribute("data_mode", metadata.mode);
        file.createAttribute("total_samples", static_cast<unsigned long long>(metadata.total_samples));
        file.createAttribute("sample_start", static_cast<unsigned long long>(metadata.sample_start));
        file.createAttribute("sample_end_exclusive", static_cast<unsigned long long>(metadata.sample_end_exclusive));
    }

References core::OutputFileMetadata::mode, core::outputFileMetadataToJsonString(), core::OutputFileMetadata::receiver_id, core::OutputFileMetadata::receiver_name, core::OutputFileMetadata::sample_end_exclusive, core::OutputFileMetadata::sample_start, and core::OutputFileMetadata::total_samples.

Referenced by processing::pipeline::exportCwToHdf5(), and processing::runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

hdf5_global_mutex

std::mutex serial::hdf5_global_mutex

Global mutex to protect all HDF5 C-library calls, which are not thread-safe.

Definition at line 29 of file hdf5_handler.cpp.

Referenced by addChunkToFile(), processing::pipeline::exportCwToHdf5(), readPattern(), readPulseData(), and processing::runPulsedFinalizer().