serial Namespace Reference

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	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)
	Adds a chunk of data to an HDF5 file.
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)
	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, World *world, const bool validate, std::mt19937 &masterSeeder)
std::string	world_to_xml_string (const core::World &world)
	Serializes the entire simulation world into an XML formatted string.

Function Documentation

addChunkToFile()

void serial::addChunkToFile	(	HighFive::File &	file,
		const std::vector< ComplexType > &	data,
		RealType	time,
		RealType	fullscale,
		unsigned	count
	)

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 76 of file hdf5_handler.cpp.

    {
        const unsigned 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);
            }
            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 LOG, and params::rate().

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 650 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");
 
        auto new_params = sim.at("parameters").get<params::Parameters>();
 
        // If a random seed is present in the incoming JSON, it is used to re-seed
        // the master generator. This is crucial for allowing the UI to control
        // simulation reproducibility.
        if (sim.at("parameters").contains("randomseed"))
        {
            params::params.random_seed = new_params.random_seed;
            if (params::params.random_seed)
            {
                LOG(logging::Level::INFO, "Master seed updated from JSON to: {}", *params::params.random_seed);
                masterSeeder.seed(*params::params.random_seed);
            }
        }
 
        new_params.random_seed = params::params.random_seed;
        params::params = new_params;
 
        params::params.simulation_name = sim.value("name", "");
 
        // 2. Restore assets (Waveforms, Antennas, Timings). This order is critical
        //    because platforms, which are restored next, will reference these
        //    assets by name. The assets must exist before they can be linked.
        if (sim.contains("waveforms"))
        {
            for (auto waveforms = sim.at("waveforms").get<std::vector<std::unique_ptr<fers_signal::RadarSignal>>>();
                 auto& waveform : waveforms)
            {
                // Only add valid waveforms. If filename was empty, waveform is nullptr.
                if (waveform)
                {
                    world.add(std::move(waveform));
                }
            }
        }
 
        if (sim.contains("antennas"))
        {
            for (auto antennas = sim.at("antennas").get<std::vector<std::unique_ptr<antenna::Antenna>>>();
                 auto& antenna : antennas)
            {
                // Only add valid antennas.
                if (antenna)
                {
                    world.add(std::move(antenna));
                }
            }
        }
 
        if (sim.contains("timings"))
        {
            for (const auto& timing_json : sim.at("timings"))
            {
                auto name = timing_json.at("name").get<std::string>();
                auto timing_obj = std::make_unique<timing::PrototypeTiming>(name);
                from_json(timing_json, *timing_obj);
                world.add(std::move(timing_obj));
            }
        }
 
        // 3. Restore platforms and their components.
        if (sim.contains("platforms"))
        {
            for (const auto& plat_json : sim.at("platforms"))
            {
                auto name = plat_json.at("name").get<std::string>();
                auto plat = std::make_unique<radar::Platform>(name);
 
                // Paths
                if (plat_json.contains("motionpath"))
                {
                    auto path = std::make_unique<math::Path>();
                    from_json(plat_json.at("motionpath"), *path);
                    plat->setMotionPath(std::move(path));
                }
                if (plat_json.contains("rotationpath"))
                {
                    auto rot_path = std::make_unique<math::RotationPath>();
                    from_json(plat_json.at("rotationpath"), *rot_path);
                    plat->setRotationPath(std::move(rot_path));
                }
                else if (plat_json.contains("fixedrotation"))
                {
                    // This logic reconstructs a constant-rate rotation path from the
                    // JSON representation that corresponds to the <fixedrotation> XML element.
                    auto rot_path = std::make_unique<math::RotationPath>();
                    const auto& fixed_json = plat_json.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>();
 
                    math::RotationCoord start, rate;
                    start.azimuth = (90.0 - start_az_deg) * (PI / 180.0);
                    start.elevation = start_el_deg * (PI / 180.0);
                    rate.azimuth = -rate_az_deg_s * (PI / 180.0);
                    rate.elevation = rate_el_deg_s * (PI / 180.0);
                    rot_path->setConstantRate(start, rate);
                    rot_path->finalize();
                    plat->setRotationPath(std::move(rot_path));
                }
 
                // Components - Strict array format
                if (plat_json.contains("components"))
                {
                    for (const auto& comp_json_outer : plat_json.at("components"))
                    {
                        if (comp_json_outer.contains("transmitter"))
                        {
                            const auto& comp_json = comp_json_outer.at("transmitter");
 
                            // --- Dependency Check ---
                            // Validate Waveform and Timing existence before creation to prevent core crashes.
                            const auto wave_name = comp_json.value("waveform", "");
                            const auto timing_name = comp_json.value("timing", "");
                            const auto antenna_name = comp_json.value("antenna", "");
 
                            if (wave_name.empty() || !world.findWaveform(wave_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Transmitter '{}': Missing or invalid waveform '{}'.",
                                    comp_json.value("name", "Unnamed"), wave_name);
                                continue;
                            }
                            if (timing_name.empty() || !world.findTiming(timing_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Transmitter '{}': Missing or invalid timing source '{}'.",
                                    comp_json.value("name", "Unnamed"), timing_name);
                                continue;
                            }
                            if (antenna_name.empty() || !world.findAntenna(antenna_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Transmitter '{}': Missing or invalid antenna '{}'.",
                                    comp_json.value("name", "Unnamed"), antenna_name);
                                continue;
                            }
 
                            radar::OperationMode mode;
                            if (comp_json.contains("pulsed_mode"))
                            {
                                mode = radar::OperationMode::PULSED_MODE;
                            }
                            else if (comp_json.contains("cw_mode"))
                            {
                                mode = radar::OperationMode::CW_MODE;
                            }
                            else
                            {
                                throw std::runtime_error("Transmitter component '" +
                                                         comp_json.value("name", "Unnamed") +
                                                         "' must have a 'pulsed_mode' or 'cw_mode' block.");
                            }
 
                            auto trans = std::make_unique<radar::Transmitter>(plat.get(),
                                                                              comp_json.value("name", "Unnamed"), mode);
                            if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
                            {
                                trans->setPrf(comp_json.at("pulsed_mode").value("prf", 0.0));
                            }
 
                            trans->setWave(world.findWaveform(wave_name));
                            trans->setAntenna(world.findAntenna(antenna_name));
 
                            if (const auto timing_proto = world.findTiming(timing_name))
                            {
                                const auto timing = std::make_shared<timing::Timing>(timing_name, masterSeeder());
                                timing->initializeModel(timing_proto);
                                trans->setTiming(timing);
                            }
 
                            if (comp_json.contains("schedule"))
                            {
                                auto raw = comp_json.at("schedule").get<std::vector<radar::SchedulePeriod>>();
                                RealType pri = 0.0;
                                if (mode == radar::OperationMode::PULSED_MODE)
                                {
                                    pri = 1.0 / trans->getPrf();
                                }
                                trans->setSchedule(radar::processRawSchedule(
                                    std::move(raw), trans->getName(), mode == radar::OperationMode::PULSED_MODE, pri));
                            }
 
                            world.add(std::move(trans));
                        }
                        else if (comp_json_outer.contains("receiver"))
                        {
                            const auto& comp_json = comp_json_outer.at("receiver");
 
                            // --- Dependency Check ---
                            // Receiver strictly requires a Timing source.
                            const auto timing_name = comp_json.value("timing", "");
                            const auto antenna_name = comp_json.value("antenna", "");
 
                            if (timing_name.empty() || !world.findTiming(timing_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Receiver '{}': Missing or invalid timing source '{}'.",
                                    comp_json.value("name", "Unnamed"), timing_name);
                                continue;
                            }
 
                            if (!antenna_name.empty() && !world.findAntenna(antenna_name))
                            {
                                LOG(logging::Level::WARNING, "Skipping Receiver '{}': Missing or invalid antenna '{}'.",
                                    comp_json.value("name", "Unnamed"), antenna_name);
                                continue;
                            }
 
                            radar::OperationMode mode;
                            if (comp_json.contains("pulsed_mode"))
                            {
                                mode = radar::OperationMode::PULSED_MODE;
                            }
                            else if (comp_json.contains("cw_mode"))
                            {
                                mode = radar::OperationMode::CW_MODE;
                            }
                            else
                            {
                                throw std::runtime_error("Receiver component '" + comp_json.value("name", "Unnamed") +
                                                         "' must have a 'pulsed_mode' or 'cw_mode' block.");
                            }
 
                            auto recv = std::make_unique<radar::Receiver>(
                                plat.get(), comp_json.value("name", "Unnamed"), masterSeeder(), mode);
                            if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
                            {
                                const auto& mode_json = comp_json.at("pulsed_mode");
                                recv->setWindowProperties(mode_json.value("window_length", 0.0),
                                                          mode_json.value("prf", 0.0),
                                                          mode_json.value("window_skip", 0.0));
                            }
 
                            recv->setNoiseTemperature(comp_json.value("noise_temp", 0.0));
 
                            recv->setAntenna(world.findAntenna(antenna_name));
 
                            if (const auto timing_proto = world.findTiming(timing_name))
                            {
                                const auto timing = std::make_shared<timing::Timing>(timing_name, masterSeeder());
                                timing->initializeModel(timing_proto);
                                recv->setTiming(timing);
                            }
 
                            if (comp_json.value("nodirect", false))
                            {
                                recv->setFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
                            }
                            if (comp_json.value("nopropagationloss", false))
                            {
                                recv->setFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
                            }
 
                            if (comp_json.contains("schedule"))
                            {
                                auto raw = comp_json.at("schedule").get<std::vector<radar::SchedulePeriod>>();
                                RealType pri = 0.0;
                                if (mode == radar::OperationMode::PULSED_MODE)
                                {
                                    pri = 1.0 / recv->getWindowPrf();
                                }
                                recv->setSchedule(radar::processRawSchedule(
                                    std::move(raw), recv->getName(), mode == radar::OperationMode::PULSED_MODE, pri));
                            }
 
                            world.add(std::move(recv));
                        }
                        if (comp_json_outer.contains("target"))
                        {
                            const auto& comp_json = comp_json_outer.at("target");
                            const auto& rcs_json = comp_json.at("rcs");
                            const auto rcs_type = rcs_json.at("type").get<std::string>();
                            std::unique_ptr<radar::Target> target_obj;
 
                            if (rcs_type == "isotropic")
                            {
                                target_obj =
                                    radar::createIsoTarget(plat.get(), comp_json.at("name").get<std::string>(),
                                                           rcs_json.at("value").get<RealType>(), masterSeeder());
                            }
                            else if (rcs_type == "file")
                            {
                                const auto filename = rcs_json.value("filename", "");
                                if (filename.empty())
                                {
                                    LOG(logging::Level::WARNING,
                                        "Skipping load of file target '{}': RCS filename is empty.",
                                        comp_json.value("name", "Unknown"));
                                    continue;
                                }
                                target_obj = radar::createFileTarget(
                                    plat.get(), comp_json.at("name").get<std::string>(), filename, masterSeeder());
                            }
                            else
                            {
                                throw std::runtime_error("Unsupported target RCS type: " + rcs_type);
                            }
                            world.add(std::move(target_obj));
 
                            // After creating the target, check for and apply the fluctuation model.
                            if (comp_json.contains("model"))
                            {
                                const auto& model_json = comp_json.at("model");
                                if (const auto model_type = model_json.at("type").get<std::string>();
                                    model_type == "chisquare" || model_type == "gamma")
                                {
                                    auto model = std::make_unique<radar::RcsChiSquare>(
                                        world.getTargets().back()->getRngEngine(), model_json.at("k").get<RealType>());
                                    world.getTargets().back()->setFluctuationModel(std::move(model));
                                }
                                // "constant" is the default, so no action is needed if that's the type.
                            }
                        }
                        else if (comp_json_outer.contains("monostatic"))
                        {
                            // This block reconstructs the internal C++ representation of a
                            // monostatic radar (a linked Transmitter and Receiver) from the
                            // single 'monostatic' component in the JSON.
                            const auto& comp_json = comp_json_outer.at("monostatic");
 
                            // --- Dependency Check ---
                            const auto wave_name = comp_json.value("waveform", "");
                            const auto timing_name = comp_json.value("timing", "");
                            const auto antenna_name = comp_json.value("antenna", "");
 
                            if (wave_name.empty() || !world.findWaveform(wave_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Monostatic '{}': Missing or invalid waveform '{}'.",
                                    comp_json.value("name", "Unnamed"), wave_name);
                                continue;
                            }
                            if (timing_name.empty() || !world.findTiming(timing_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Monostatic '{}': Missing or invalid timing source '{}'.",
                                    comp_json.value("name", "Unnamed"), timing_name);
                                continue;
                            }
                            if (antenna_name.empty() || !world.findAntenna(antenna_name))
                            {
                                LOG(logging::Level::WARNING,
                                    "Skipping Monostatic '{}': Missing or invalid antenna '{}'.",
                                    comp_json.value("name", "Unnamed"), antenna_name);
                                continue;
                            }
 
                            radar::OperationMode mode;
                            if (comp_json.contains("pulsed_mode"))
                            {
                                mode = radar::OperationMode::PULSED_MODE;
                            }
                            else if (comp_json.contains("cw_mode"))
                            {
                                mode = radar::OperationMode::CW_MODE;
                            }
                            else
                            {
                                throw std::runtime_error("Monostatic component '" + comp_json.value("name", "Unnamed") +
                                                         "' must have a 'pulsed_mode' or 'cw_mode' block.");
                            }
 
                            // Transmitter part
                            auto trans = std::make_unique<radar::Transmitter>(plat.get(),
                                                                              comp_json.value("name", "Unnamed"), mode);
                            if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
                            {
                                trans->setPrf(comp_json.at("pulsed_mode").value("prf", 0.0));
                            }
 
                            trans->setWave(world.findWaveform(wave_name));
                            trans->setAntenna(world.findAntenna(antenna_name));
                            const auto tx_timing_proto = world.findTiming(timing_name);
                            if (tx_timing_proto)
                            {
                                const auto tx_timing = std::make_shared<timing::Timing>(timing_name, masterSeeder());
                                tx_timing->initializeModel(tx_timing_proto);
                                trans->setTiming(tx_timing);
                            }
 
                            // Receiver part
                            auto recv = std::make_unique<radar::Receiver>(
                                plat.get(), comp_json.value("name", "Unnamed"), masterSeeder(), mode);
                            if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
                            {
                                const auto& mode_json = comp_json.at("pulsed_mode");
                                recv->setWindowProperties(mode_json.value("window_length", 0.0),
                                                          trans->getPrf(), // Use transmitter's PRF
                                                          mode_json.value("window_skip", 0.0));
                            }
                            recv->setNoiseTemperature(comp_json.value("noise_temp", 0.0));
 
                            recv->setAntenna(world.findAntenna(antenna_name));
                            const auto rx_timing_proto = world.findTiming(timing_name);
                            if (rx_timing_proto)
                            {
                                const auto rx_timing = std::make_shared<timing::Timing>(timing_name, masterSeeder());
                                rx_timing->initializeModel(rx_timing_proto);
                                recv->setTiming(rx_timing);
                            }
 
                            if (comp_json.value("nodirect", false))
                            {
                                recv->setFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
                            }
                            if (comp_json.value("nopropagationloss", false))
                            {
                                recv->setFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
                            }
                            if (comp_json.contains("schedule"))
                            {
                                auto raw = comp_json.at("schedule").get<std::vector<radar::SchedulePeriod>>();
                                RealType pri = 0.0;
                                if (mode == radar::OperationMode::PULSED_MODE)
                                {
                                    pri = 1.0 / trans->getPrf();
                                }
 
                                // Process once, apply to both
                                auto processed_schedule = radar::processRawSchedule(
                                    std::move(raw), trans->getName(), mode == radar::OperationMode::PULSED_MODE, pri);
 
                                trans->setSchedule(processed_schedule);
                                recv->setSchedule(processed_schedule);
                            }
 
                            // Link them and add to world
                            trans->setAttached(recv.get());
                            recv->setAttached(trans.get());
                            world.add(std::move(trans));
                            world.add(std::move(recv));
                        }
                    }
                }
 
                world.add(std::move(plat));
            }
        }
 
        // 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::add(), core::World::clear(), radar::createFileTarget(), radar::createIsoTarget(), radar::CW_MODE, params::endTime(), core::World::findAntenna(), core::World::findTiming(), core::World::findWaveform(), radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, core::World::getReceivers(), core::World::getTargets(), logging::INFO, LOG, params::oversampleRatio(), params::params, PI, radar::processRawSchedule(), radar::PULSED_MODE, params::Parameters::random_seed, params::rate(), core::World::scheduleInitialEvents(), params::Parameters::simulation_name, params::startTime(), and logging::WARNING.

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
	)

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 115 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);
            wave->setFilename(filename);
            return wave;
        }
        if (hasExtension(extension, ".h5"))
        {
            auto wave = loadWaveformFromHdf5File(name, filepath, power, carrierFreq);
            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 fers_signal::from_json().

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 loads an XML file, merges any included files, validates it against the FERS DTD and XSD schemas, and then populates the simulation World object with the parsed parameters and components.

Parameters

filename	The path to the main XML simulation script.
world	A pointer to the World object to be populated.
validate	A boolean indicating whether to perform XML validation.
masterSeeder	A reference to the master random number generator used for seeding components.

Exceptions

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

Definition at line 1106 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 fs::path main_dir = fs::path(filename).parent_path();
        const bool did_combine = addIncludeFilesToMainDocument(main_doc, main_dir);
 
        if (validate)
        {
            validateXml(did_combine, main_doc);
        }
        else
        {
            LOG(Level::DEBUG, "Skipping XML validation.");
        }
 
        processParsedDocument(main_doc, world, main_dir, masterSeeder);
    }

References core::World::clear(), XmlDocument::loadFile(), LOG, params::params, and params::Parameters::reset().

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,
		World *	world,
		const bool	validate,
		std::mt19937 &	masterSeeder
	)

Definition at line 1131 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.
            validateXml(false, doc);
        }
        else
        {
            LOG(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 fs::path base_dir = ".";
 
        processParsedDocument(doc, world, base_dir, masterSeeder);
    }

References core::World::clear(), XmlDocument::loadString(), LOG, params::params, and params::Parameters::reset().

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 127 of file hdf5_handler.cpp.

    {
        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 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 29 of file hdf5_handler.cpp.

    {
        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 LOG.

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 544 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())
        {
            nlohmann::json plat_json = *p;
 
            // Initialize components array to ensure it exists even if empty
            plat_json["components"] = nlohmann::json::array();
 
            // Add Transmitters and Monostatic Radars
            for (const auto& t : world.getTransmitters())
            {
                if (t->getPlatform() == p.get())
                {
                    if (t->getAttached() != nullptr)
                    {
                        nlohmann::json monostatic_comp;
                        monostatic_comp["name"] = t->getName();
                        monostatic_comp["waveform"] = t->getSignal() ? t->getSignal()->getName() : "";
                        monostatic_comp["antenna"] = t->getAntenna() ? t->getAntenna()->getName() : "";
                        monostatic_comp["timing"] = t->getTiming() ? t->getTiming()->getName() : "";
 
                        if (const auto* recv = dynamic_cast<const radar::Receiver*>(t->getAttached()))
                        {
                            monostatic_comp["noise_temp"] = recv->getNoiseTemperature();
                            monostatic_comp["nodirect"] = recv->checkFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
                            monostatic_comp["nopropagationloss"] =
                                recv->checkFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
 
                            if (!t->getSchedule().empty())
                            {
                                monostatic_comp["schedule"] = t->getSchedule();
                            }
 
                            if (t->getMode() == radar::OperationMode::PULSED_MODE)
                            {
                                monostatic_comp["pulsed_mode"] = {{"prf", t->getPrf()},
                                                                  {"window_skip", recv->getWindowSkip()},
                                                                  {"window_length", recv->getWindowLength()}};
                            }
                            else
                            {
                                monostatic_comp["cw_mode"] = nlohmann::json::object();
                            }
                        }
                        plat_json["components"].push_back({{"monostatic", monostatic_comp}});
                    }
                    else
                    {
                        plat_json["components"].push_back({{"transmitter", *t}});
                    }
                }
            }
 
            // Add Standalone Receivers
            for (const auto& r : world.getReceivers())
            {
                if (r->getPlatform() == p.get())
                {
                    // This must be a standalone receiver, as monostatic cases were handled above.
                    if (r->getAttached() == nullptr)
                    {
                        plat_json["components"].push_back({{"receiver", *r}});
                    }
                }
            }
 
            // Add Targets
            for (const auto& target : world.getTargets())
            {
                if (target->getPlatform() == p.get())
                {
                    plat_json["components"].push_back({{"target", *target}});
                }
            }
 
            sim_json["platforms"].push_back(plat_json);
        }
 
        return {{"simulation", sim_json}};
    }

References radar::Receiver::FLAG_NODIRECT, radar::Receiver::FLAG_NOPROPLOSS, core::World::getAntennas(), core::World::getPlatforms(), core::World::getReceivers(), core::World::getTargets(), core::World::getTimings(), core::World::getTransmitters(), core::World::getWaveforms(), params::params, radar::PULSED_MODE, 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 489 of file xml_serializer.cpp.

    {
        XmlDocument doc;
        xmlNodePtr sim_node = xmlNewNode(nullptr, reinterpret_cast<const xmlChar*>("simulation"));
        XmlElement root(sim_node);
        doc.setRootElement(root);
 
        if (!params::params.simulation_name.empty())
        {
            root.setAttribute("name", params::params.simulation_name);
        }
        else
        {
            root.setAttribute("name", "FERS Scenario");
        }
 
        const XmlElement params_elem = root.addChild("parameters");
        serializeParameters(params_elem);
 
        // Assets (waveforms, timings, antennas) are serialized first. This is
        // necessary because platforms reference these assets by name. By defining
        // them at the top of the document, we ensure that any XML parser can
        // resolve these references when it later encounters the platform definitions.
        for (const auto& waveform : world.getWaveforms() | std::views::values)
        {
            XmlElement waveform_elem = root.addChild("waveform");
            serializeWaveform(*waveform, waveform_elem);
        }
        for (const auto& timing : world.getTimings() | std::views::values)
        {
            XmlElement timing_elem = root.addChild("timing");
            serializeTiming(*timing, timing_elem);
        }
        for (const auto& antenna : world.getAntennas() | std::views::values)
        {
            XmlElement antenna_elem = root.addChild("antenna");
            serializeAntenna(*antenna, antenna_elem);
        }
        for (const auto& platform : world.getPlatforms())
        {
            XmlElement plat_elem = root.addChild("platform");
            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, 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: