json_serializer.cpp

Go to the documentation of this file.

// SPDX-License-Identifier: GPL-2.0-only
// Copyright (c) 2025-present FERS Contributors (see AUTHORS.md).
 
/**
 * @file json_serializer.cpp
 * @brief Implements JSON serialization and deserialization for FERS objects.
 *
 * This file leverages the `nlohmann/json` library's support for automatic
 * serialization via `to_json` and `from_json` free functions. By placing these
 * functions within the namespaces of the objects they serialize, we enable
 * Argument-Dependent Lookup (ADL). This design choice allows the library to
 * automatically find the correct conversion functions, keeping the serialization
 * logic decoupled from the core object definitions and improving modularity.
 */
 
#include "serial/json_serializer.h"
 
#include <algorithm>
#include <cmath>
#include <format>
#include <initializer_list>
#include <nlohmann/json.hpp>
#include <optional>
#include <random>
#include <stdexcept>
#include <string_view>
#include <unordered_map>
 
#include "antenna/antenna_factory.h"
#include "core/parameters.h"
#include "core/sim_id.h"
#include "core/world.h"
#include "math/coord.h"
#include "math/path.h"
#include "math/rotation_path.h"
#include "radar/platform.h"
#include "radar/receiver.h"
#include "radar/target.h"
#include "radar/transmitter.h"
#include "serial/fmcw_validation.h"
#include "serial/rotation_angle_utils.h"
#include "serial/rotation_warning_utils.h"
#include "signal/radar_signal.h"
#include "timing/prototype_timing.h"
#include "timing/timing.h"
#include "waveform_factory.h"
 
// TODO: Add file path validation and error handling as needed.
 
namespace
{
    /// Map from timing prototype SimId to shared runtime timing instance.
    using TimingInstanceMap = std::unordered_map<SimId, std::shared_ptr<timing::Timing>>;
 
    /// Serializes a SimId as a JSON string.
    nlohmann::json sim_id_to_json(const SimId id) { return std::to_string(id); }
 
    /// Parses a required SimId from a JSON object.
    SimId parse_json_id(const nlohmann::json& j, const std::string& key, const std::string& owner)
    {
        if (!j.contains(key))
        {
            throw std::runtime_error("Missing required '" + key + "' for " + owner + ".");
        }
        try
        {
            if (j.at(key).is_number_unsigned())
            {
                return j.at(key).get<SimId>();
            }
            if (j.at(key).is_number_integer())
            {
                const auto value = j.at(key).get<long long>();
                if (value < 0)
                {
                    throw std::runtime_error("negative id");
                }
                return static_cast<SimId>(value);
            }
            if (j.at(key).is_string())
            {
                const auto str = j.at(key).get<std::string>();
                size_t idx = 0;
                const unsigned long long parsed = std::stoull(str, &idx, 10);
                if (idx != str.size())
                {
                    throw std::runtime_error("trailing characters");
                }
                return static_cast<SimId>(parsed);
            }
        }
        catch (const std::exception& e)
        {
            throw std::runtime_error("Invalid '" + key + "' for " + owner + ": " + e.what());
        }
        throw std::runtime_error("Invalid '" + key + "' type for " + owner + ".");
    }
 
    /// Resolves or instantiates a shared timing instance by prototype SimId.
    std::shared_ptr<timing::Timing> resolve_timing_instance(core::World& world, std::mt19937& masterSeeder,
                                                            TimingInstanceMap& timing_instances, const SimId timing_id)
    {
        if (const auto it = timing_instances.find(timing_id); it != timing_instances.end())
        {
            return it->second;
        }
 
        auto* const timing_proto = world.findTiming(timing_id);
        if (timing_proto == nullptr)
        {
            return nullptr;
        }
 
        auto timing = std::make_shared<timing::Timing>(timing_proto->getName(), static_cast<unsigned>(masterSeeder()),
                                                       timing_proto->getId());
        timing->initializeModel(timing_proto);
        timing_instances.emplace(timing_id, timing);
        return timing;
    }
 
    /// Formats a JSON field for warnings without assuming the field type.
    std::string json_field_for_log(const nlohmann::json& j, const char* key)
    {
        if (!j.contains(key) || j.at(key).is_null())
        {
            return "";
        }
        if (j.at(key).is_string())
        {
            return j.at(key).get<std::string>();
        }
        return j.at(key).dump();
    }
 
    /// Throws a JSON validation error with the provided message.
    void throw_json_validation_error(const std::string& message) { throw std::runtime_error(message); }
 
    /// Validates an FMCW waveform while adapting validation errors to std::runtime_error.
    void validate_fmcw_waveform(const fers_signal::RadarSignal& wave, const std::string& owner)
    {
        serial::fmcw_validation::validateWaveform(wave, owner, throw_json_validation_error);
    }
 
    /// Validates waveform/mode compatibility while adapting validation errors to std::runtime_error.
    void validate_waveform_mode_match(const fers_signal::RadarSignal& wave, const radar::OperationMode mode,
                                      const std::string& owner)
    {
        serial::fmcw_validation::validateWaveformModeMatch(wave, mode, owner, throw_json_validation_error);
    }
 
    /// Validates an FMCW schedule while adapting validation errors to std::runtime_error.
    void validate_fmcw_schedule(const std::vector<radar::SchedulePeriod>& schedule,
                                const fers_signal::RadarSignal& wave, const std::string& owner)
    {
        serial::fmcw_validation::validateSchedule(schedule, wave, owner, throw_json_validation_error);
    }
 
    /// Throws if a JSON object contains keys outside a strict whitelist.
    void reject_unknown_keys(const nlohmann::json& object, const std::string& owner, const std::string_view object_name,
                             const std::initializer_list<std::string_view> allowed_keys)
    {
        for (const auto& [key, value] : object.items())
        {
            (void)value;
            bool allowed = false;
            for (const auto allowed_key : allowed_keys)
            {
                if (key == allowed_key)
                {
                    allowed = true;
                    break;
                }
            }
            if (!allowed)
            {
                std::string message = owner;
                message += ' ';
                message += object_name;
                message += " contains unsupported key '";
                message += key;
                message += "'.";
                throw std::runtime_error(message);
            }
        }
    }
 
    /// Returns true when a JSON FMCW mode object carries receiver-side FMCW fields.
    bool has_dechirp_fields(const nlohmann::json& mode_json)
    {
        return mode_json.contains("dechirp_mode") || mode_json.contains("dechirp_reference") ||
            mode_json.contains("if_sample_rate") || mode_json.contains("if_filter_bandwidth") ||
            mode_json.contains("if_filter_transition_width");
    }
 
    std::optional<RealType> get_optional_positive_real(const nlohmann::json& object, const std::string_view key,
                                                       const std::string& owner)
    {
        const std::string key_string(key);
        if (!object.contains(key_string))
        {
            return std::nullopt;
        }
        const RealType value = object.at(key_string).get<RealType>();
        if (value <= 0.0 || !std::isfinite(value))
        {
            throw std::runtime_error(owner + " " + key_string + " must be a finite positive value.");
        }
        return value;
    }
 
    bool has_if_chain_fields(const radar::Receiver::FmcwIfChainRequest& if_chain) noexcept
    {
        return if_chain.sample_rate_hz.has_value() || if_chain.filter_bandwidth_hz.has_value() ||
            if_chain.filter_transition_width_hz.has_value();
    }
 
    void reject_disabled_json_dechirp_fields(const nlohmann::json& mode_json,
                                             const radar::Receiver::FmcwIfChainRequest& if_chain,
                                             const std::string& owner)
    {
        if (mode_json.contains("dechirp_reference"))
        {
            throw std::runtime_error(owner + " declares dechirp_reference while dechirp_mode is 'none'.");
        }
        if (has_if_chain_fields(if_chain))
        {
            throw std::runtime_error(owner + " declares IF-chain fields while dechirp_mode is 'none'.");
        }
    }
 
    void validate_json_if_chain_request(const radar::Receiver::FmcwIfChainRequest& if_chain, const std::string& owner)
    {
        if ((if_chain.filter_bandwidth_hz.has_value() || if_chain.filter_transition_width_hz.has_value()) &&
            !if_chain.sample_rate_hz.has_value())
        {
            throw std::runtime_error(owner + " IF filter fields require if_sample_rate.");
        }
        if (if_chain.sample_rate_hz.has_value())
        {
            const RealType sim_rate = params::rate() * params::oversampleRatio();
            if (*if_chain.sample_rate_hz > sim_rate)
            {
                throw std::runtime_error(owner + " if_sample_rate must not exceed the simulation sample rate.");
            }
        }
        if (if_chain.sample_rate_hz.has_value() && if_chain.filter_bandwidth_hz.has_value() &&
            *if_chain.filter_bandwidth_hz >= *if_chain.sample_rate_hz / 2.0)
        {
            throw std::runtime_error(owner + " if_filter_bandwidth must be less than half if_sample_rate.");
        }
    }
 
    std::string required_non_empty_json_string(const nlohmann::json& object, const std::string_view key,
                                               const std::string& owner, const std::string_view context)
    {
        const std::string key_string(key);
        auto value = object.at(key_string).get<std::string>();
        if (value.empty())
        {
            throw std::runtime_error(owner + " " + std::string(context) + " has an empty " + key_string + ".");
        }
        return value;
    }
 
    radar::Receiver::DechirpReference parse_json_dechirp_reference(const nlohmann::json& mode_json,
                                                                   const std::string& owner)
    {
        if (!mode_json.contains("dechirp_reference") || !mode_json.at("dechirp_reference").is_object())
        {
            throw std::runtime_error(owner + " enables dechirping but does not declare dechirp_reference.");
        }
 
        const auto& ref_json = mode_json.at("dechirp_reference");
        reject_unknown_keys(ref_json, owner, "dechirp_reference", {"source", "transmitter_name", "waveform_name"});
        if (!ref_json.contains("source"))
        {
            throw std::runtime_error(owner + " dechirp_reference requires source.");
        }
 
        radar::Receiver::DechirpReference reference;
        reference.source = radar::parseDechirpReferenceSourceToken(ref_json.at("source").get<std::string>());
        const bool has_transmitter_name = ref_json.contains("transmitter_name");
        const bool has_waveform_name = ref_json.contains("waveform_name");
 
        switch (reference.source)
        {
        case radar::Receiver::DechirpReferenceSource::Attached:
            if (has_transmitter_name || has_waveform_name)
            {
                throw std::runtime_error(owner +
                                         " attached dechirp_reference must not set transmitter_name or waveform_name.");
            }
            break;
        case radar::Receiver::DechirpReferenceSource::Transmitter:
            if (!has_transmitter_name || has_waveform_name)
            {
                throw std::runtime_error(owner + " transmitter dechirp_reference requires transmitter_name only.");
            }
            reference.name =
                required_non_empty_json_string(ref_json, "transmitter_name", owner, "transmitter dechirp_reference");
            break;
        case radar::Receiver::DechirpReferenceSource::Custom:
            if (!has_waveform_name || has_transmitter_name)
            {
                throw std::runtime_error(owner + " custom dechirp_reference requires waveform_name only.");
            }
            reference.name =
                required_non_empty_json_string(ref_json, "waveform_name", owner, "custom dechirp_reference");
            break;
        case radar::Receiver::DechirpReferenceSource::None:
            throw std::runtime_error(owner + " dechirp_reference source must be attached, transmitter, or custom.");
        }
 
        return reference;
    }
 
    /// Parses receiver-side dechirp settings from a JSON component.
    void parse_receiver_dechirp_config(const nlohmann::json& comp_json, radar::Receiver& receiver,
                                       const std::string& owner)
    {
        if (receiver.getMode() != radar::OperationMode::FMCW_MODE)
        {
            receiver.setDechirpMode(radar::Receiver::DechirpMode::None);
            return;
        }
 
        const auto& mode_json = comp_json.contains("fmcw_mode") ? comp_json.at("fmcw_mode") : nlohmann::json::object();
        if (!mode_json.is_object())
        {
            throw std::runtime_error(owner + " fmcw_mode must be an object.");
        }
        reject_unknown_keys(mode_json, owner, "fmcw_mode",
                            {"dechirp_mode", "dechirp_reference", "if_sample_rate", "if_filter_bandwidth",
                             "if_filter_transition_width"});
 
        radar::Receiver::DechirpMode mode = radar::Receiver::DechirpMode::None;
        if (mode_json.contains("dechirp_mode"))
        {
            mode = radar::parseDechirpModeToken(mode_json.at("dechirp_mode").get<std::string>());
        }
 
        radar::Receiver::FmcwIfChainRequest if_chain{
            .sample_rate_hz = get_optional_positive_real(mode_json, "if_sample_rate", owner),
            .filter_bandwidth_hz = get_optional_positive_real(mode_json, "if_filter_bandwidth", owner),
            .filter_transition_width_hz = get_optional_positive_real(mode_json, "if_filter_transition_width", owner)};
 
        if (mode == radar::Receiver::DechirpMode::None)
        {
            reject_disabled_json_dechirp_fields(mode_json, if_chain, owner);
            receiver.setDechirpMode(mode);
            return;
        }
 
        validate_json_if_chain_request(if_chain, owner);
        auto reference = parse_json_dechirp_reference(mode_json, owner);
 
        receiver.setDechirpMode(mode);
        receiver.setDechirpReference(std::move(reference));
        receiver.setFmcwIfChainRequest(if_chain);
    }
 
    /// Serializes receiver-side FMCW mode settings.
    nlohmann::json receiver_fmcw_mode_to_json(const radar::Receiver& receiver)
    {
        nlohmann::json mode_json = nlohmann::json::object();
        if (!receiver.isDechirpEnabled())
        {
            return mode_json;
        }
 
        const auto& reference = receiver.getDechirpReference();
        mode_json["dechirp_mode"] = std::string(radar::dechirpModeToken(receiver.getDechirpMode()));
        const auto& if_chain = receiver.getFmcwIfChainRequest();
        if (if_chain.sample_rate_hz.has_value())
        {
            mode_json["if_sample_rate"] = *if_chain.sample_rate_hz;
        }
        if (if_chain.filter_bandwidth_hz.has_value())
        {
            mode_json["if_filter_bandwidth"] = *if_chain.filter_bandwidth_hz;
        }
        if (if_chain.filter_transition_width_hz.has_value())
        {
            mode_json["if_filter_transition_width"] = *if_chain.filter_transition_width_hz;
        }
        nlohmann::json ref_json = {{"source", std::string(radar::dechirpReferenceSourceToken(reference.source))}};
        if (reference.source == radar::Receiver::DechirpReferenceSource::Transmitter)
        {
            ref_json["transmitter_name"] =
                !reference.transmitter_name.empty() ? reference.transmitter_name : reference.name;
        }
        else if (reference.source == radar::Receiver::DechirpReferenceSource::Custom)
        {
            ref_json["waveform_name"] = !reference.waveform_name.empty() ? reference.waveform_name : reference.name;
        }
        mode_json["dechirp_reference"] = std::move(ref_json);
        return mode_json;
    }
}
 
namespace math
{
    void to_json(nlohmann::json& j, const Vec3& v) // NOLINT(*-use-internal-linkage)
    {
        j = {{"x", v.x}, {"y", v.y}, {"z", v.z}};
    } // NOLINT(*-use-internal-linkage)
 
    void from_json(const nlohmann::json& j, Vec3& v) // NOLINT(*-use-internal-linkage)
    {
        j.at("x").get_to(v.x);
        j.at("y").get_to(v.y);
        j.at("z").get_to(v.z);
    }
 
    void to_json(nlohmann::json& j, const Coord& c) // NOLINT(*-use-internal-linkage)
    {
        j = {{"time", c.t}, {"x", c.pos.x}, {"y", c.pos.y}, {"altitude", c.pos.z}};
    }
 
    void from_json(const nlohmann::json& j, Coord& c) // NOLINT(*-use-internal-linkage)
    {
        j.at("time").get_to(c.t);
        j.at("x").get_to(c.pos.x);
        j.at("y").get_to(c.pos.y);
        j.at("altitude").get_to(c.pos.z);
    }
 
    void to_json(nlohmann::json& j, const RotationCoord& rc) // NOLINT(*-use-internal-linkage)
    {
        const auto unit = params::rotationAngleUnit();
        j = {{"time", rc.t},
             {"azimuth", serial::rotation_angle_utils::internal_azimuth_to_external(rc.azimuth, unit)},
             {"elevation", serial::rotation_angle_utils::internal_elevation_to_external(rc.elevation, unit)}};
    }
 
    void from_json(const nlohmann::json& j, RotationCoord& rc) // NOLINT(*-use-internal-linkage)
    {
        j.at("time").get_to(rc.t);
        const auto external = serial::rotation_angle_utils::external_rotation_to_internal(
            j.at("azimuth").get<RealType>(), j.at("elevation").get<RealType>(), rc.t, params::rotationAngleUnit());
        rc.azimuth = external.azimuth;
        rc.elevation = external.elevation;
    }
 
    NLOHMANN_JSON_SERIALIZE_ENUM(Path::InterpType,
                                 {{Path::InterpType::INTERP_STATIC, "static"},
                                  {Path::InterpType::INTERP_LINEAR, "linear"},
                                  {Path::InterpType::INTERP_CUBIC, "cubic"}})
 
    void to_json(nlohmann::json& j, const Path& p) // NOLINT(*-use-internal-linkage)
    {
        j = {{"interpolation", p.getType()}, {"positionwaypoints", p.getCoords()}};
    }
 
    void from_json(const nlohmann::json& j, Path& p) // NOLINT(*-use-internal-linkage)
    {
        p.setInterp(j.at("interpolation").get<Path::InterpType>());
        for (const auto waypoints = j.at("positionwaypoints").get<std::vector<Coord>>(); const auto& wp : waypoints)
        {
            p.addCoord(wp);
        }
        p.finalize();
    }
 
    NLOHMANN_JSON_SERIALIZE_ENUM(RotationPath::InterpType,
                                 {{RotationPath::InterpType::INTERP_STATIC, "static"},
                                  {RotationPath::InterpType::INTERP_CONSTANT,
                                   "constant"}, // Not used in xml_parser or UI yet, but for completeness
                                  {RotationPath::InterpType::INTERP_LINEAR, "linear"},
                                  {RotationPath::InterpType::INTERP_CUBIC, "cubic"}})
 
    void to_json(nlohmann::json& j, const RotationPath& p) // NOLINT(*-use-internal-linkage)
    {
        j["interpolation"] = p.getType();
        // This logic exists to map the two different rotation definitions from the
        // XML schema (<fixedrotation> and <rotationpath>) into a unified JSON
        // structure that the frontend can more easily handle.
        if (p.getType() == RotationPath::InterpType::INTERP_CONSTANT)
        {
            // A constant-rate rotation path corresponds to the <fixedrotation> XML element.
            // The start and rate values are converted to compass degrees per second.
            // No normalization is applied to preserve negative start angles.
            const auto unit = params::rotationAngleUnit();
            j["startazimuth"] = serial::rotation_angle_utils::internal_azimuth_to_external(p.getStart().azimuth, unit);
            j["startelevation"] =
                serial::rotation_angle_utils::internal_elevation_to_external(p.getStart().elevation, unit);
            j["azimuthrate"] =
                serial::rotation_angle_utils::internal_azimuth_rate_to_external(p.getRate().azimuth, unit);
            j["elevationrate"] =
                serial::rotation_angle_utils::internal_elevation_rate_to_external(p.getRate().elevation, unit);
        }
        else
        {
            j["rotationwaypoints"] = p.getCoords();
        }
    }
 
    void from_json(const nlohmann::json& j, RotationPath& p) // NOLINT(*-use-internal-linkage)
    {
        p.setInterp(j.at("interpolation").get<RotationPath::InterpType>());
        for (const auto waypoints = j.at("rotationwaypoints").get<std::vector<RotationCoord>>();
             const auto& wp : waypoints)
        {
            p.addCoord(wp);
        }
        p.finalize();
    }
 
}
 
namespace timing
{
    void to_json(nlohmann::json& j, const PrototypeTiming& pt) // NOLINT(*-use-internal-linkage)
    {
        j = nlohmann::json{{"id", sim_id_to_json(pt.getId())},
                           {"name", pt.getName()},
                           {"frequency", pt.getFrequency()},
                           {"synconpulse", pt.getSyncOnPulse()}};
 
        if (pt.getFreqOffset().has_value())
        {
            j["freq_offset"] = pt.getFreqOffset().value();
        }
        if (pt.getRandomFreqOffsetStdev().has_value())
        {
            j["random_freq_offset_stdev"] = pt.getRandomFreqOffsetStdev().value();
        }
        if (pt.getPhaseOffset().has_value())
        {
            j["phase_offset"] = pt.getPhaseOffset().value();
        }
        if (pt.getRandomPhaseOffsetStdev().has_value())
        {
            j["random_phase_offset_stdev"] = pt.getRandomPhaseOffsetStdev().value();
        }
 
        std::vector<RealType> alphas;
        std::vector<RealType> weights;
        pt.copyAlphas(alphas, weights);
        if (!alphas.empty())
        {
            nlohmann::json noise_entries = nlohmann::json::array();
            for (size_t i = 0; i < alphas.size(); ++i)
            {
                noise_entries.push_back({{"alpha", alphas[i]}, {"weight", weights[i]}});
            }
            j["noise_entries"] = noise_entries;
        }
    }
 
    void from_json(const nlohmann::json& j, PrototypeTiming& pt) // NOLINT(*-use-internal-linkage)
    {
        pt.setFrequency(j.at("frequency").get<RealType>());
        if (j.value("synconpulse", false))
        {
            pt.setSyncOnPulse();
        }
        else
        {
            pt.clearSyncOnPulse();
        }
 
        if (j.contains("freq_offset"))
        {
            pt.setFreqOffset(j.at("freq_offset").get<RealType>());
        }
        else
            pt.clearFreqOffset();
        if (j.contains("random_freq_offset_stdev"))
        {
            pt.setRandomFreqOffsetStdev(j.at("random_freq_offset_stdev").get<RealType>());
        }
        else
            pt.clearRandomFreqOffsetStdev();
        if (j.contains("phase_offset"))
        {
            pt.setPhaseOffset(j.at("phase_offset").get<RealType>());
        }
        else
            pt.clearPhaseOffset();
        if (j.contains("random_phase_offset_stdev"))
        {
            pt.setRandomPhaseOffsetStdev(j.at("random_phase_offset_stdev").get<RealType>());
        }
        else
            pt.clearRandomPhaseOffsetStdev();
 
        pt.clearNoiseEntries();
        if (j.contains("noise_entries"))
        {
            for (const auto& entry : j.at("noise_entries"))
            {
                pt.setAlpha(entry.at("alpha").get<RealType>(), entry.at("weight").get<RealType>());
            }
        }
    }
}
 
namespace fers_signal
{
    void to_json(nlohmann::json& j, const RadarSignal& rs) // NOLINT(*-use-internal-linkage)
    {
        j = nlohmann::json{{"id", sim_id_to_json(rs.getId())},
                           {"name", rs.getName()},
                           {"power", rs.getPower()},
                           {"carrier_frequency", rs.getCarrier()}};
        if (dynamic_cast<const CwSignal*>(rs.getSignal()) != nullptr)
        {
            j["cw"] = nlohmann::json::object();
        }
        else if (const auto* fmcw = rs.getFmcwChirpSignal(); fmcw != nullptr)
        {
            j["fmcw_linear_chirp"] = {{"direction", std::string(fmcwChirpDirectionToken(fmcw->getDirection()))},
                                      {"chirp_bandwidth", fmcw->getChirpBandwidth()},
                                      {"chirp_duration", fmcw->getChirpDuration()},
                                      {"chirp_period", fmcw->getChirpPeriod()}};
            if (std::abs(fmcw->getStartFrequencyOffset()) > EPSILON)
            {
                j["fmcw_linear_chirp"]["start_frequency_offset"] = fmcw->getStartFrequencyOffset();
            }
            if (fmcw->getChirpCount().has_value())
            {
                j["fmcw_linear_chirp"]["chirp_count"] = *fmcw->getChirpCount();
            }
        }
        else if (const auto* triangle = rs.getFmcwTriangleSignal(); triangle != nullptr)
        {
            j["fmcw_triangle"] = {{"chirp_bandwidth", triangle->getChirpBandwidth()},
                                  {"chirp_duration", triangle->getChirpDuration()}};
            if (std::abs(triangle->getStartFrequencyOffset()) > EPSILON)
            {
                j["fmcw_triangle"]["start_frequency_offset"] = triangle->getStartFrequencyOffset();
            }
            if (triangle->getTriangleCount().has_value())
            {
                j["fmcw_triangle"]["triangle_count"] = *triangle->getTriangleCount();
            }
        }
        else
        {
            if (const auto& filename = rs.getFilename(); filename.has_value())
            {
                j["pulsed_from_file"] = {{"filename", *filename}};
            }
            else
            {
                throw std::logic_error("Attempted to serialize a file-based waveform named '" + rs.getName() +
                                       "' without a source filename.");
            }
        }
    }
 
    void from_json(const nlohmann::json& j, std::unique_ptr<RadarSignal>& rs) // NOLINT(*-use-internal-linkage)
    {
        const auto name = j.at("name").get<std::string>();
        const auto id = parse_json_id(j, "id", "waveform");
        const auto power = j.at("power").get<RealType>();
        const auto carrier = j.at("carrier_frequency").get<RealType>();
 
        if (j.contains("cw"))
        {
            auto cw_signal = std::make_unique<CwSignal>();
            rs = std::make_unique<RadarSignal>(name, power, carrier, params::endTime() - params::startTime(),
                                               std::move(cw_signal), id);
        }
        else if (j.contains("fmcw_linear_chirp"))
        {
            const auto& fmcw_json = j.at("fmcw_linear_chirp");
            const auto direction = parseFmcwChirpDirection(fmcw_json.at("direction").get<std::string>());
            std::optional<std::size_t> chirp_count;
            if (fmcw_json.contains("chirp_count"))
            {
                const auto parsed_count = fmcw_json.at("chirp_count").get<long long>();
                if (parsed_count <= 0)
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid chirp_count.");
                }
                chirp_count = static_cast<std::size_t>(parsed_count);
            }
 
            auto fmcw_signal = std::make_unique<FmcwChirpSignal>(
                fmcw_json.at("chirp_bandwidth").get<RealType>(), fmcw_json.at("chirp_duration").get<RealType>(),
                fmcw_json.at("chirp_period").get<RealType>(), fmcw_json.value("start_frequency_offset", 0.0),
                chirp_count, direction);
            rs = std::make_unique<RadarSignal>(name, power, carrier, fmcw_signal->getChirpDuration(),
                                               std::move(fmcw_signal), id);
            validate_fmcw_waveform(*rs, "Waveform '" + name + "'");
        }
        else if (j.contains("fmcw_triangle"))
        {
            const auto& fmcw_json = j.at("fmcw_triangle");
            std::optional<std::size_t> triangle_count;
            if (fmcw_json.contains("triangle_count"))
            {
                const auto& count_json = fmcw_json.at("triangle_count");
                if (!count_json.is_number_integer() && !count_json.is_number_unsigned())
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid triangle_count.");
                }
                const auto parsed_count = count_json.get<long long>();
                if (parsed_count <= 0)
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid triangle_count.");
                }
                triangle_count = static_cast<std::size_t>(parsed_count);
            }
 
            auto fmcw_signal = std::make_unique<FmcwTriangleSignal>(
                fmcw_json.at("chirp_bandwidth").get<RealType>(), fmcw_json.at("chirp_duration").get<RealType>(),
                fmcw_json.value("start_frequency_offset", 0.0), triangle_count);
            rs = std::make_unique<RadarSignal>(name, power, carrier, fmcw_signal->getTrianglePeriod(),
                                               std::move(fmcw_signal), id);
            validate_fmcw_waveform(*rs, "Waveform '" + name + "'");
        }
        else if (j.contains("pulsed_from_file"))
        {
            const auto& pulsed_file = j.at("pulsed_from_file");
            const auto filename = pulsed_file.value("filename", "");
            if (filename.empty())
            {
                LOG(logging::Level::WARNING, "Skipping load of file-based waveform '{}': filename is empty.", name);
                return; // rs remains nullptr
            }
            rs = serial::loadWaveformFromFile(name, filename, power, carrier, id);
        }
        else
        {
            throw std::runtime_error("Unsupported waveform type in from_json for '" + name + "'");
        }
    }
}
 
namespace antenna
{
    void to_json(nlohmann::json& j, const Antenna& a) // NOLINT(*-use-internal-linkage)
    {
        j = {{"id", sim_id_to_json(a.getId())}, {"name", a.getName()}, {"efficiency", a.getEfficiencyFactor()}};
 
        if (const auto* sinc = dynamic_cast<const Sinc*>(&a))
        {
            j["pattern"] = "sinc";
            j["alpha"] = sinc->getAlpha();
            j["beta"] = sinc->getBeta();
            j["gamma"] = sinc->getGamma();
        }
        else if (const auto* gaussian = dynamic_cast<const Gaussian*>(&a))
        {
            j["pattern"] = "gaussian";
            j["azscale"] = gaussian->getAzimuthScale();
            j["elscale"] = gaussian->getElevationScale();
        }
        else if (const auto* sh = dynamic_cast<const SquareHorn*>(&a))
        {
            j["pattern"] = "squarehorn";
            j["diameter"] = sh->getDimension();
        }
        else if (const auto* parabolic = dynamic_cast<const Parabolic*>(&a))
        {
            j["pattern"] = "parabolic";
            j["diameter"] = parabolic->getDiameter();
        }
        else if (const auto* xml = dynamic_cast<const XmlAntenna*>(&a))
        {
            j["pattern"] = "xml";
            j["filename"] = xml->getFilename();
        }
        else if (const auto* h5 = dynamic_cast<const H5Antenna*>(&a))
        {
            j["pattern"] = "file";
            j["filename"] = h5->getFilename();
        }
        else
        {
            j["pattern"] = "isotropic";
        }
    }
 
    void from_json(const nlohmann::json& j, std::unique_ptr<Antenna>& ant) // NOLINT(*-use-internal-linkage)
    {
        const auto name = j.at("name").get<std::string>();
        const auto id = parse_json_id(j, "id", "Antenna");
        const auto pattern = j.value("pattern", "isotropic");
 
        if (pattern == "isotropic")
        {
            ant = std::make_unique<Isotropic>(name, id);
        }
        else if (pattern == "sinc")
        {
            ant = std::make_unique<Sinc>(name, j.at("alpha").get<RealType>(), j.at("beta").get<RealType>(),
                                         j.at("gamma").get<RealType>(), id);
        }
        else if (pattern == "gaussian")
        {
            ant =
                std::make_unique<Gaussian>(name, j.at("azscale").get<RealType>(), j.at("elscale").get<RealType>(), id);
        }
        else if (pattern == "squarehorn")
        {
            ant = std::make_unique<SquareHorn>(name, j.at("diameter").get<RealType>(), id);
        }
        else if (pattern == "parabolic")
        {
            ant = std::make_unique<Parabolic>(name, j.at("diameter").get<RealType>(), id);
        }
        else if (pattern == "xml")
        {
            const auto filename = j.value("filename", "");
            if (filename.empty())
            {
                LOG(logging::Level::WARNING, "Skipping load of XML antenna '{}': filename is empty.", name);
                return; // ant remains nullptr
            }
            ant = std::make_unique<XmlAntenna>(name, filename, id);
        }
        else if (pattern == "file")
        {
            const auto filename = j.value("filename", "");
            if (filename.empty())
            {
                LOG(logging::Level::WARNING, "Skipping load of H5 antenna '{}': filename is empty.", name);
                return; // ant remains nullptr
            }
            ant = std::make_unique<H5Antenna>(name, filename, id);
        }
        else
        {
            throw std::runtime_error("Unsupported antenna pattern in from_json: " + pattern);
        }
 
        ant->setEfficiencyFactor(j.value("efficiency", 1.0));
    }
}
 
namespace radar
{
    void to_json(nlohmann::json& j, const SchedulePeriod& p) // NOLINT(*-use-internal-linkage)
    {
        j = {{"start", p.start}, {"end", p.end}};
    } // NOLINT(*-use-internal-linkage)
 
    void from_json(const nlohmann::json& j, SchedulePeriod& p) // NOLINT(*-use-internal-linkage)
    {
        j.at("start").get_to(p.start);
        j.at("end").get_to(p.end);
    }
 
    void to_json(nlohmann::json& j, const Transmitter& t) // NOLINT(*-use-internal-linkage)
    {
        j = nlohmann::json{{"id", sim_id_to_json(t.getId())},
                           {"name", t.getName()},
                           {"waveform", sim_id_to_json((t.getSignal() != nullptr) ? t.getSignal()->getId() : 0)},
                           {"antenna", sim_id_to_json((t.getAntenna() != nullptr) ? t.getAntenna()->getId() : 0)},
                           {"timing", sim_id_to_json(t.getTiming() ? t.getTiming()->getId() : 0)}};
 
        if (t.getMode() == OperationMode::PULSED_MODE)
        {
            j["pulsed_mode"] = {{"prf", t.getPrf()}};
        }
        else if (t.getMode() == OperationMode::FMCW_MODE)
        {
            j["fmcw_mode"] = nlohmann::json::object();
        }
        else
        {
            j["cw_mode"] = nlohmann::json::object();
        }
        if (!t.getSchedule().empty())
        {
            j["schedule"] = t.getSchedule();
        }
    }
 
    void to_json(nlohmann::json& j, const Receiver& r) // NOLINT(*-use-internal-linkage)
    {
        j = nlohmann::json{{"id", sim_id_to_json(r.getId())},
                           {"name", r.getName()},
                           {"noise_temp", r.getNoiseTemperature()},
                           {"antenna", sim_id_to_json((r.getAntenna() != nullptr) ? r.getAntenna()->getId() : 0)},
                           {"timing", sim_id_to_json(r.getTiming() ? r.getTiming()->getId() : 0)},
                           {"nodirect", r.checkFlag(Receiver::RecvFlag::FLAG_NODIRECT)},
                           {"nopropagationloss", r.checkFlag(Receiver::RecvFlag::FLAG_NOPROPLOSS)}};
 
        if (r.getMode() == OperationMode::PULSED_MODE)
        {
            j["pulsed_mode"] = {
                {"prf", r.getWindowPrf()}, {"window_skip", r.getWindowSkip()}, {"window_length", r.getWindowLength()}};
        }
        else if (r.getMode() == OperationMode::FMCW_MODE)
        {
            j["fmcw_mode"] = receiver_fmcw_mode_to_json(r);
        }
        else
        {
            j["cw_mode"] = nlohmann::json::object();
        }
        if (!r.getSchedule().empty())
        {
            j["schedule"] = r.getSchedule();
        }
    }
 
    void to_json(nlohmann::json& j, const Target& t) // NOLINT(*-use-internal-linkage)
    {
        j["id"] = sim_id_to_json(t.getId());
        j["name"] = t.getName();
        nlohmann::json rcs_json;
        if (const auto* iso = dynamic_cast<const IsoTarget*>(&t))
        {
            rcs_json["type"] = "isotropic";
            rcs_json["value"] = iso->getConstRcs();
        }
        else if (const auto* file = dynamic_cast<const FileTarget*>(&t))
        {
            rcs_json["type"] = "file";
            rcs_json["filename"] = file->getFilename();
        }
        j["rcs"] = rcs_json;
 
        // Serialize the fluctuation model if it exists.
        if (const auto* model_base = t.getFluctuationModel())
        {
            nlohmann::json model_json;
            if (const auto* chi_model = dynamic_cast<const RcsChiSquare*>(model_base))
            {
                model_json["type"] = "chisquare";
                model_json["k"] = chi_model->getK();
            }
            else // Default to constant if it's not a recognized type (e.g., RcsConst)
            {
                model_json["type"] = "constant";
            }
            j["model"] = model_json;
        }
    }
 
    void to_json(nlohmann::json& j, const Platform& p) // NOLINT(*-use-internal-linkage)
    {
        j = {{"id", sim_id_to_json(p.getId())}, {"name", p.getName()}, {"motionpath", *p.getMotionPath()}};
 
        if (p.getRotationPath()->getType() == math::RotationPath::InterpType::INTERP_CONSTANT)
        {
            j["fixedrotation"] = *p.getRotationPath();
        }
        else
        {
            j["rotationpath"] = *p.getRotationPath();
        }
    }
 
}
 
namespace params
{
    NLOHMANN_JSON_SERIALIZE_ENUM(CoordinateFrame,
                                 {{CoordinateFrame::ENU, "ENU"},
                                  {CoordinateFrame::UTM, "UTM"},
                                  {CoordinateFrame::ECEF, "ECEF"}})
    NLOHMANN_JSON_SERIALIZE_ENUM(RotationAngleUnit,
                                 {{RotationAngleUnit::Degrees, "deg"}, {RotationAngleUnit::Radians, "rad"}})
 
    void to_json(nlohmann::json& j, const Parameters& p) // NOLINT(*-use-internal-linkage)
    {
        j = nlohmann::json{{"starttime", p.start},
                           {"endtime", p.end},
                           {"rate", p.rate},
                           {"c", p.c},
                           {"simSamplingRate", p.sim_sampling_rate},
                           {"adc_bits", p.adc_bits},
                           {"oversample", p.oversample_ratio},
                           {"rotationangleunit", p.rotation_angle_unit}};
 
        if (p.random_seed.has_value())
        {
            j["randomseed"] = p.random_seed.value();
        }
 
        j["origin"] = {
            {"latitude", p.origin_latitude}, {"longitude", p.origin_longitude}, {"altitude", p.origin_altitude}};
 
        j["coordinatesystem"] = {{"frame", p.coordinate_frame}};
        if (p.coordinate_frame == CoordinateFrame::UTM)
        {
            j["coordinatesystem"]["zone"] = p.utm_zone;
            j["coordinatesystem"]["hemisphere"] = p.utm_north_hemisphere ? "N" : "S";
        }
    }
 
    void from_json(const nlohmann::json& j, Parameters& p) // NOLINT(*-use-internal-linkage)
    {
        p.start = j.at("starttime").get<RealType>();
        p.end = j.at("endtime").get<RealType>();
        p.rate = j.at("rate").get<RealType>();
        p.c = j.value("c", Parameters::DEFAULT_C);
        p.sim_sampling_rate = j.value("simSamplingRate", 1000.0);
        p.adc_bits = j.value("adc_bits", 0u);
        p.oversample_ratio = j.value("oversample", 1u);
        params::validateOversampleRatio(p.oversample_ratio);
        p.rotation_angle_unit = j.value("rotationangleunit", RotationAngleUnit::Degrees);
        p.random_seed = j.value<std::optional<unsigned>>("randomseed", std::nullopt);
 
        const auto& origin = j.at("origin");
        p.origin_latitude = origin.at("latitude").get<double>();
        p.origin_longitude = origin.at("longitude").get<double>();
        p.origin_altitude = origin.at("altitude").get<double>();
 
        const auto& cs = j.at("coordinatesystem");
        p.coordinate_frame = cs.at("frame").get<CoordinateFrame>();
        if (p.coordinate_frame == CoordinateFrame::UTM)
        {
            p.utm_zone = cs.at("zone").get<int>();
            p.utm_north_hemisphere = cs.at("hemisphere").get<std::string>() == "N";
        }
    }
}
 
namespace
{
    void addMonostaticReceiverFields(nlohmann::json& monostatic_comp, const radar::Transmitter& transmitter,
                                     const radar::Receiver& receiver)
    {
        monostatic_comp["noise_temp"] = receiver.getNoiseTemperature();
        monostatic_comp["nodirect"] = receiver.checkFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT);
        monostatic_comp["nopropagationloss"] = receiver.checkFlag(radar::Receiver::RecvFlag::FLAG_NOPROPLOSS);
 
        if (!transmitter.getSchedule().empty())
        {
            monostatic_comp["schedule"] = transmitter.getSchedule();
        }
 
        if (transmitter.getMode() == radar::OperationMode::PULSED_MODE)
        {
            monostatic_comp["pulsed_mode"] = {{"prf", transmitter.getPrf()},
                                              {"window_skip", receiver.getWindowSkip()},
                                              {"window_length", receiver.getWindowLength()}};
        }
        else if (transmitter.getMode() == radar::OperationMode::FMCW_MODE)
        {
            monostatic_comp["fmcw_mode"] = receiver_fmcw_mode_to_json(receiver);
        }
        else
        {
            monostatic_comp["cw_mode"] = nlohmann::json::object();
        }
    }
 
    nlohmann::json monostaticComponentToJson(const radar::Transmitter& transmitter)
    {
        const auto* attached = transmitter.getAttached();
        nlohmann::json monostatic_comp;
        monostatic_comp["name"] = transmitter.getName();
        monostatic_comp["tx_id"] = sim_id_to_json(transmitter.getId());
        monostatic_comp["rx_id"] = sim_id_to_json(attached->getId());
        monostatic_comp["waveform"] =
            sim_id_to_json((transmitter.getSignal() != nullptr) ? transmitter.getSignal()->getId() : 0);
        monostatic_comp["antenna"] =
            sim_id_to_json((transmitter.getAntenna() != nullptr) ? transmitter.getAntenna()->getId() : 0);
        monostatic_comp["timing"] = sim_id_to_json(transmitter.getTiming() ? transmitter.getTiming()->getId() : 0);
 
        if (const auto* receiver = dynamic_cast<const radar::Receiver*>(attached))
        {
            addMonostaticReceiverFields(monostatic_comp, transmitter, *receiver);
        }
        return nlohmann::json{{"monostatic", monostatic_comp}};
    }
 
    void appendTransmitterComponents(nlohmann::json& components, const radar::Platform* platform,
                                     const core::World& world)
    {
        for (const auto& transmitter : world.getTransmitters())
        {
            if (transmitter->getPlatform() != platform)
            {
                continue;
            }
            if (transmitter->getAttached() != nullptr)
            {
                components.push_back(monostaticComponentToJson(*transmitter));
            }
            else
            {
                components.push_back(nlohmann::json{{"transmitter", *transmitter}});
            }
        }
    }
 
    void appendReceiverComponents(nlohmann::json& components, const radar::Platform* platform, const core::World& world)
    {
        for (const auto& receiver : world.getReceivers())
        {
            if (receiver->getPlatform() == platform && receiver->getAttached() == nullptr)
            {
                components.push_back(nlohmann::json{{"receiver", *receiver}});
            }
        }
    }
 
    void appendTargetComponents(nlohmann::json& components, const radar::Platform* platform, const core::World& world)
    {
        for (const auto& target : world.getTargets())
        {
            if (target->getPlatform() == platform)
            {
                components.push_back(nlohmann::json{{"target", *target}});
            }
        }
    }
 
    /// Serializes a platform and its attached components to JSON.
    nlohmann::json serialize_platform(const radar::Platform* p, const core::World& world)
    {
        nlohmann::json plat_json = *p;
        plat_json["components"] = nlohmann::json::array();
        auto& components = plat_json["components"];
 
        appendTransmitterComponents(components, p, world);
        appendReceiverComponents(components, p, world);
        appendTargetComponents(components, p, world);
 
        return plat_json;
    }
 
    /// Parses simulation parameters from JSON and updates the master seeder.
    void parse_parameters(const nlohmann::json& sim, std::mt19937& masterSeeder)
    {
        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", "");
    }
 
    /// Parses top-level reusable assets from JSON into the world.
    void parse_assets(const nlohmann::json& sim, core::World& world)
    {
        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>();
                const auto timing_id = parse_json_id(timing_json, "id", "Timing");
                auto timing_obj = std::make_unique<timing::PrototypeTiming>(name, timing_id);
                timing_json.get_to(*timing_obj);
                world.add(std::move(timing_obj));
            }
        }
    }
 
    using JsonNameRegistry = std::unordered_map<std::string, std::string>;
 
    void register_json_name(JsonNameRegistry& name_registry, const nlohmann::json& element, const std::string_view kind)
    {
        if (!element.is_object() || !element.contains("name"))
        {
            return;
        }
 
        const auto name = element.at("name").get<std::string>();
        const auto [iter, inserted] = name_registry.emplace(name, std::string(kind));
        if (!inserted)
        {
            throw std::runtime_error("Duplicate name '" + name + "' found for " + std::string(kind) +
                                     "; previously used by " + iter->second + ".");
        }
    }
 
    void register_json_name_array(JsonNameRegistry& name_registry, const nlohmann::json& sim,
                                  const std::string_view key, const std::string_view kind)
    {
        const std::string key_string(key);
        if (!sim.contains(key_string))
        {
            return;
        }
        for (const auto& element : sim.at(key_string))
        {
            register_json_name(name_registry, element, kind);
        }
    }
 
    void register_platform_component_names(JsonNameRegistry& name_registry, const nlohmann::json& platform)
    {
        if (!platform.contains("components") || !platform.at("components").is_array())
        {
            return;
        }
 
        for (const auto& component_wrapper : platform.at("components"))
        {
            if (!component_wrapper.is_object())
            {
                continue;
            }
            for (const auto& [kind, component] : component_wrapper.items())
            {
                register_json_name(name_registry, component, kind);
            }
        }
    }
 
    void register_platform_names(JsonNameRegistry& name_registry, const nlohmann::json& sim)
    {
        if (!sim.contains("platforms"))
        {
            return;
        }
 
        for (const auto& platform : sim.at("platforms"))
        {
            register_json_name(name_registry, platform, "platform");
            register_platform_component_names(name_registry, platform);
        }
    }
 
    void validate_unique_names(const nlohmann::json& sim)
    {
        JsonNameRegistry name_registry;
        name_registry.reserve(64);
        register_json_name_array(name_registry, sim, "waveforms", "waveform");
        register_json_name_array(name_registry, sim, "timings", "timing");
        register_json_name_array(name_registry, sim, "antennas", "antenna");
        register_platform_names(name_registry, sim);
    }
 
    /// Counts operation mode blocks on a component.
    std::size_t mode_block_count(const nlohmann::json& comp_json)
    {
        return static_cast<std::size_t>(comp_json.contains("pulsed_mode")) +
            static_cast<std::size_t>(comp_json.contains("fmcw_mode")) +
            static_cast<std::size_t>(comp_json.contains("cw_mode"));
    }
 
    /// Throws when a partial update or full component declares conflicting modes.
    void reject_conflicting_mode_blocks(const nlohmann::json& comp_json, const std::string& error_context)
    {
        if (mode_block_count(comp_json) > 1)
        {
            throw std::runtime_error(error_context +
                                     " must have at most one of 'pulsed_mode', 'cw_mode', or 'fmcw_mode'.");
        }
    }
 
    /// Parses the mutually exclusive operation mode block for a component.
    radar::OperationMode parse_mode(const nlohmann::json& comp_json, const std::string& error_context)
    {
        reject_conflicting_mode_blocks(comp_json, error_context);
        if (comp_json.contains("pulsed_mode"))
        {
            return radar::OperationMode::PULSED_MODE;
        }
        if (comp_json.contains("fmcw_mode"))
        {
            return radar::OperationMode::FMCW_MODE;
        }
        if (comp_json.contains("cw_mode"))
        {
            return radar::OperationMode::CW_MODE;
        }
        throw std::runtime_error(error_context + " must have a 'pulsed_mode', 'cw_mode', or 'fmcw_mode' block.");
    }
 
    /// Parses a transmitter component from JSON into the world.
    void parse_transmitter(const nlohmann::json& comp_json, radar::Platform* plat, core::World& world,
                           std::mt19937& masterSeeder, TimingInstanceMap& timing_instances)
    {
        // --- Dependency Check ---
        // Validate Waveform and Timing existence before creation to prevent core crashes.
        const auto wave_id = parse_json_id(comp_json, "waveform", "Transmitter");
        const auto timing_id = parse_json_id(comp_json, "timing", "Transmitter");
        const auto antenna_id = parse_json_id(comp_json, "antenna", "Transmitter");
 
        if (world.findWaveform(wave_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Transmitter '{}': Missing or invalid waveform '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "waveform"));
            return;
        }
        if (world.findTiming(timing_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Transmitter '{}': Missing or invalid timing source '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "timing"));
            return;
        }
        if (world.findAntenna(antenna_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Transmitter '{}': Missing or invalid antenna '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "antenna"));
            return;
        }
 
        radar::OperationMode const mode =
            parse_mode(comp_json, "Transmitter component '" + comp_json.value("name", "Unnamed") + "'");
        if (mode == radar::OperationMode::FMCW_MODE && comp_json.contains("fmcw_mode") &&
            has_dechirp_fields(comp_json.at("fmcw_mode")))
        {
            throw std::runtime_error("Transmitter component '" + comp_json.value("name", "Unnamed") +
                                     "' fmcw_mode must not contain dechirp configuration.");
        }
 
        const auto trans_id = parse_json_id(comp_json, "id", "Transmitter");
        auto trans = std::make_unique<radar::Transmitter>(plat, comp_json.value("name", "Unnamed"), mode, trans_id);
        if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
        {
            trans->setPrf(comp_json.at("pulsed_mode").value("prf", 0.0));
        }
 
        auto* const waveform = world.findWaveform(wave_id);
        validate_fmcw_waveform(*waveform, "Waveform '" + waveform->getName() + "'");
        validate_waveform_mode_match(*waveform, mode,
                                     "Transmitter component '" + comp_json.value("name", "Unnamed") + "'");
        trans->setWave(waveform);
        trans->setAntenna(world.findAntenna(antenna_id));
 
        if (const auto timing = resolve_timing_instance(world, masterSeeder, timing_instances, timing_id))
        {
            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();
            }
            auto schedule =
                radar::processRawSchedule(raw, trans->getName(), mode == radar::OperationMode::PULSED_MODE, pri);
            if (waveform->isFmcwFamily())
            {
                validate_fmcw_schedule(schedule, *waveform, "Transmitter component '" + trans->getName() + "'");
            }
            trans->setSchedule(std::move(schedule));
        }
        else if (waveform->isFmcwFamily())
        {
            validate_fmcw_schedule(trans->getSchedule(), *waveform, "Transmitter component '" + trans->getName() + "'");
        }
 
        world.add(std::move(trans));
    }
 
    /// Parses a receiver component from JSON into the world.
    void parse_receiver(const nlohmann::json& comp_json, radar::Platform* plat, core::World& world,
                        std::mt19937& masterSeeder, TimingInstanceMap& timing_instances)
    {
        // --- Dependency Check ---
        // Receiver strictly requires a Timing source.
        const auto timing_id = parse_json_id(comp_json, "timing", "Receiver");
        const auto antenna_id = parse_json_id(comp_json, "antenna", "Receiver");
 
        if (world.findTiming(timing_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Receiver '{}': Missing or invalid timing source '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "timing"));
            return;
        }
 
        if (world.findAntenna(antenna_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Receiver '{}': Missing or invalid antenna '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "antenna"));
            return;
        }
 
        radar::OperationMode const mode =
            parse_mode(comp_json, "Receiver component '" + comp_json.value("name", "Unnamed") + "'");
 
        const auto recv_id = parse_json_id(comp_json, "id", "Receiver");
        auto recv =
            std::make_unique<radar::Receiver>(plat, comp_json.value("name", "Unnamed"), masterSeeder(), mode, recv_id);
        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_id));
 
        if (const auto timing = resolve_timing_instance(world, masterSeeder, timing_instances, timing_id))
        {
            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(raw, recv->getName(), mode == radar::OperationMode::PULSED_MODE, pri));
        }
 
        parse_receiver_dechirp_config(comp_json, *recv,
                                      "Receiver component '" + comp_json.value("name", "Unnamed") + "'");
        world.add(std::move(recv));
    }
 
    /// Parses a target component from JSON into the world.
    void parse_target(const nlohmann::json& comp_json, radar::Platform* plat, core::World& world,
                      std::mt19937& masterSeeder)
    {
        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")
        {
            const auto target_id = parse_json_id(comp_json, "id", "Target");
            target_obj = radar::createIsoTarget(plat, comp_json.at("name").get<std::string>(),
                                                rcs_json.at("value").get<RealType>(),
                                                static_cast<unsigned>(masterSeeder()), target_id);
        }
        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"));
                return;
            }
            const auto target_id = parse_json_id(comp_json, "id", "Target");
            target_obj = radar::createFileTarget(plat, comp_json.at("name").get<std::string>(), filename,
                                                 static_cast<unsigned>(masterSeeder()), target_id);
        }
        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");
            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>(world.getTargets().back()->getRngEngine(),
                                                                   model_json.at("k").get<RealType>());
                world.getTargets().back()->setFluctuationModel(std::move(model));
            }
            else if (model_type == "constant")
            {
                world.getTargets().back()->setFluctuationModel(std::make_unique<radar::RcsConst>());
            }
            else
            {
                throw std::runtime_error("Unsupported fluctuation model type: " + model_type);
            }
        }
    }
 
    /// Parses a monostatic component into linked transmitter and receiver objects.
    void parse_monostatic(const nlohmann::json& comp_json, radar::Platform* plat, core::World& world,
                          std::mt19937& masterSeeder, TimingInstanceMap& timing_instances)
    {
        // This block reconstructs the internal C++ representation of a
        // monostatic radar (a linked Transmitter and Receiver) from the
        // single 'monostatic' component in the JSON.
        // --- Dependency Check ---
        const auto wave_id = parse_json_id(comp_json, "waveform", "Monostatic");
        const auto timing_id = parse_json_id(comp_json, "timing", "Monostatic");
        const auto antenna_id = parse_json_id(comp_json, "antenna", "Monostatic");
 
        if (world.findWaveform(wave_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Monostatic '{}': Missing or invalid waveform '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "waveform"));
            return;
        }
        if (world.findTiming(timing_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Monostatic '{}': Missing or invalid timing source '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "timing"));
            return;
        }
        if (world.findAntenna(antenna_id) == nullptr)
        {
            LOG(logging::Level::WARNING, "Skipping Monostatic '{}': Missing or invalid antenna '{}'.",
                comp_json.value("name", "Unnamed"), json_field_for_log(comp_json, "antenna"));
            return;
        }
 
        radar::OperationMode const mode =
            parse_mode(comp_json, "Monostatic component '" + comp_json.value("name", "Unnamed") + "'");
 
        // Transmitter part
        const auto tx_id = parse_json_id(comp_json, "tx_id", "Monostatic");
        auto trans = std::make_unique<radar::Transmitter>(plat, comp_json.value("name", "Unnamed"), mode, tx_id);
        if (mode == radar::OperationMode::PULSED_MODE && comp_json.contains("pulsed_mode"))
        {
            trans->setPrf(comp_json.at("pulsed_mode").value("prf", 0.0));
        }
 
        auto* const waveform = world.findWaveform(wave_id);
        validate_fmcw_waveform(*waveform, "Waveform '" + waveform->getName() + "'");
        validate_waveform_mode_match(*waveform, mode,
                                     "Monostatic component '" + comp_json.value("name", "Unnamed") + "'");
        trans->setWave(waveform);
        trans->setAntenna(world.findAntenna(antenna_id));
        if (const auto shared_timing = resolve_timing_instance(world, masterSeeder, timing_instances, timing_id))
        {
            trans->setTiming(shared_timing);
        }
 
        // Receiver part
        const auto rx_id = parse_json_id(comp_json, "rx_id", "Monostatic");
        auto recv =
            std::make_unique<radar::Receiver>(plat, comp_json.value("name", "Unnamed"), masterSeeder(), mode, rx_id);
        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_id));
        if (const auto shared_timing = resolve_timing_instance(world, masterSeeder, timing_instances, timing_id))
        {
            recv->setTiming(shared_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(raw, trans->getName(), mode == radar::OperationMode::PULSED_MODE, pri);
            if (waveform->isFmcwFamily())
            {
                validate_fmcw_schedule(processed_schedule, *waveform,
                                       "Monostatic component '" + comp_json.value("name", "Unnamed") + "'");
            }
 
            trans->setSchedule(processed_schedule);
            recv->setSchedule(processed_schedule);
        }
        else if (waveform->isFmcwFamily())
        {
            validate_fmcw_schedule(trans->getSchedule(), *waveform,
                                   "Monostatic component '" + comp_json.value("name", "Unnamed") + "'");
        }
 
        // Link them and add to world
        trans->setAttached(recv.get());
        recv->setAttached(trans.get());
        parse_receiver_dechirp_config(comp_json, *recv,
                                      "Monostatic component '" + comp_json.value("name", "Unnamed") + "'");
        world.add(std::move(trans));
        world.add(std::move(recv));
    }
 
    /// Parses a platform and its component list from JSON into the world.
    void parse_platform(const nlohmann::json& plat_json, core::World& world, std::mt19937& masterSeeder,
                        TimingInstanceMap& timing_instances)
    {
        auto name = plat_json.at("name").get<std::string>();
        const auto platform_id = parse_json_id(plat_json, "id", "Platform");
        auto plat = std::make_unique<radar::Platform>(name, platform_id);
 
        serial::update_platform_paths_from_json(plat_json, plat.get());
 
        // 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"))
                {
                    parse_transmitter(comp_json_outer.at("transmitter"), plat.get(), world, masterSeeder,
                                      timing_instances);
                }
                else if (comp_json_outer.contains("receiver"))
                {
                    parse_receiver(comp_json_outer.at("receiver"), plat.get(), world, masterSeeder, timing_instances);
                }
                else if (comp_json_outer.contains("target"))
                {
                    parse_target(comp_json_outer.at("target"), plat.get(), world, masterSeeder);
                }
                else if (comp_json_outer.contains("monostatic"))
                {
                    parse_monostatic(comp_json_outer.at("monostatic"), plat.get(), world, masterSeeder,
                                     timing_instances);
                }
            }
        }
 
        world.add(std::move(plat));
    }
 
    void populate_world_from_json(const nlohmann::json& j, core::World& world, std::mt19937& masterSeeder)
    {
        world.clear();
 
        const auto& sim = j.at("simulation");
        validate_unique_names(sim);
 
        parse_parameters(sim, masterSeeder);
        parse_assets(sim, world);
 
        if (sim.contains("platforms"))
        {
            TimingInstanceMap timing_instances;
            for (const auto& plat_json : sim.at("platforms"))
            {
                parse_platform(plat_json, world, masterSeeder, timing_instances);
            }
        }
        world.resolveReceiverDechirpReferences();
 
        world.scheduleInitialEvents();
    }
}
 
namespace serial
{
    std::unique_ptr<antenna::Antenna> parse_antenna_from_json(const nlohmann::json& j)
    {
        std::unique_ptr<antenna::Antenna> ant;
        antenna::from_json(j, ant);
        return ant;
    }
 
    std::unique_ptr<fers_signal::RadarSignal> parse_waveform_from_json(const nlohmann::json& j)
    {
        std::unique_ptr<fers_signal::RadarSignal> wf;
        fers_signal::from_json(j, wf);
        return wf;
    }
 
    std::unique_ptr<timing::PrototypeTiming> parse_timing_from_json(const nlohmann::json& j, const SimId id)
    {
        auto timing = std::make_unique<timing::PrototypeTiming>(j.at("name").get<std::string>(), id);
        j.get_to(*timing);
        return timing;
    }
 
    void update_parameters_from_json(const nlohmann::json& j, std::mt19937& masterSeeder)
    {
        nlohmann::json sim;
        sim["parameters"] = j;
        parse_parameters(sim, masterSeeder);
    }
 
    std::unique_ptr<antenna::Antenna> parse_required_update_antenna(const nlohmann::json& 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;
    }
 
    bool antenna_pattern_requires_replacement(const std::string_view pattern, const antenna::Antenna* ant) noexcept
    {
        if (pattern == "isotropic")
        {
            return dynamic_cast<const antenna::Isotropic*>(ant) == nullptr;
        }
        if (pattern == "sinc")
        {
            return dynamic_cast<const antenna::Sinc*>(ant) == nullptr;
        }
        if (pattern == "gaussian")
        {
            return dynamic_cast<const antenna::Gaussian*>(ant) == nullptr;
        }
        if (pattern == "squarehorn")
        {
            return dynamic_cast<const antenna::SquareHorn*>(ant) == nullptr;
        }
        if (pattern == "parabolic")
        {
            return dynamic_cast<const antenna::Parabolic*>(ant) == nullptr;
        }
        if (pattern == "xml")
        {
            return dynamic_cast<const antenna::XmlAntenna*>(ant) == nullptr;
        }
        if (pattern == "file")
        {
            return dynamic_cast<const antenna::H5Antenna*>(ant) == nullptr;
        }
        return false;
    }
 
    void update_existing_antenna_pattern_fields(const nlohmann::json& j, antenna::Antenna* ant, core::World& world)
    {
        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_update_antenna(j));
            }
        }
        else if (auto* h5 = dynamic_cast<antenna::H5Antenna*>(ant))
        {
            if (h5->getFilename() != j.value("filename", ""))
            {
                world.replace(parse_required_update_antenna(j));
            }
        }
    }
 
    void update_antenna_from_json(const nlohmann::json& j, antenna::Antenna* ant, core::World& world)
    {
        const auto new_pattern = j.value("pattern", "isotropic");
        if (antenna_pattern_requires_replacement(new_pattern, ant))
        {
            world.replace(parse_required_update_antenna(j));
            return;
        }
 
        ant->setName(j.at("name").get<std::string>());
        ant->setEfficiencyFactor(j.value("efficiency", 1.0));
        update_existing_antenna_pattern_fields(j, ant, world);
    }
 
    void update_platform_paths_from_json(const nlohmann::json& j, radar::Platform* plat)
    {
        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));
        }
    }
 
    void update_transmitter_mode_from_json(const nlohmann::json& j, radar::Transmitter& tx)
    {
        reject_conflicting_mode_blocks(j, "Transmitter '" + tx.getName() + "'");
        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("fmcw_mode"))
        {
            if (has_dechirp_fields(j.at("fmcw_mode")))
            {
                throw std::runtime_error("Transmitter '" + tx.getName() +
                                         "' fmcw_mode must not contain dechirp configuration.");
            }
            tx.setMode(radar::OperationMode::FMCW_MODE);
        }
        else if (j.contains("cw_mode"))
        {
            tx.setMode(radar::OperationMode::CW_MODE);
        }
    }
 
    void update_transmitter_waveform_from_json(const nlohmann::json& j, radar::Transmitter& tx, core::World& world)
    {
        if (!j.contains("waveform"))
        {
            return;
        }
        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.");
        }
        validate_fmcw_waveform(*wf, "Waveform '" + wf->getName() + "'");
        validate_waveform_mode_match(*wf, tx.getMode(), "Transmitter '" + tx.getName() + "'");
        tx.setWave(wf);
    }
 
    void update_transmitter_antenna_from_json(const nlohmann::json& j, radar::Transmitter& tx, core::World& world)
    {
        if (!j.contains("antenna"))
        {
            return;
        }
        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);
    }
 
    void update_transmitter_timing_from_json(const nlohmann::json& j, radar::Transmitter& tx, core::World& world)
    {
        if (!j.contains("timing"))
        {
            return;
        }
        auto timing_id = parse_json_id(j, "timing", "Transmitter");
        auto* const timing_proto = world.findTiming(timing_id);
        if (timing_proto == nullptr)
        {
            throw std::runtime_error("Timing ID " + std::to_string(timing_id) + " not found.");
        }
        unsigned const 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);
    }
 
    void validate_transmitter_signal_state(const radar::Transmitter& tx, const std::string& owner)
    {
        if (tx.getSignal() == nullptr)
        {
            return;
        }
        validate_fmcw_waveform(*tx.getSignal(), "Waveform '" + tx.getSignal()->getName() + "'");
        validate_waveform_mode_match(*tx.getSignal(), tx.getMode(), owner);
        if (tx.getSignal()->isFmcwFamily())
        {
            validate_fmcw_schedule(tx.getSchedule(), *tx.getSignal(), owner);
        }
    }
 
    void update_transmitter_schedule_from_json(const nlohmann::json& j, radar::Transmitter& tx,
                                               const std::string& owner)
    {
        if (!j.contains("schedule"))
        {
            return;
        }
        auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
        const bool pulsed = tx.getMode() == radar::OperationMode::PULSED_MODE;
        const RealType pri = pulsed ? 1.0 / tx.getPrf() : 0.0;
        auto schedule = radar::processRawSchedule(raw, tx.getName(), pulsed, pri);
        if (tx.getSignal() != nullptr && tx.getSignal()->isFmcwFamily())
        {
            validate_fmcw_schedule(schedule, *tx.getSignal(), owner);
        }
        tx.setSchedule(std::move(schedule));
    }
 
    void update_transmitter_from_json(const nlohmann::json& j, radar::Transmitter* tx, core::World& world,
                                      std::mt19937& /*masterSeeder*/)
    {
        if (j.contains("name"))
            tx->setName(j.at("name").get<std::string>());
 
        const std::string owner = "Transmitter '" + tx->getName() + "'";
        update_transmitter_mode_from_json(j, *tx);
        update_transmitter_waveform_from_json(j, *tx, world);
        update_transmitter_antenna_from_json(j, *tx, world);
        update_transmitter_timing_from_json(j, *tx, world);
        update_transmitter_schedule_from_json(j, *tx, owner);
        validate_transmitter_signal_state(*tx, owner);
    }
 
    void update_receiver_mode_from_json(const nlohmann::json& j, radar::Receiver& rx)
    {
        reject_conflicting_mode_blocks(j, "Receiver '" + rx.getName() + "'");
        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("fmcw_mode"))
        {
            rx.setMode(radar::OperationMode::FMCW_MODE);
        }
        else if (j.contains("cw_mode"))
        {
            rx.setMode(radar::OperationMode::CW_MODE);
        }
    }
 
    void update_receiver_noise_and_flags_from_json(const nlohmann::json& j, radar::Receiver& rx)
    {
        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);
        }
    }
 
    void update_receiver_antenna_from_json(const nlohmann::json& j, radar::Receiver& rx, core::World& world)
    {
        if (!j.contains("antenna"))
        {
            return;
        }
        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);
    }
 
    void update_receiver_timing_from_json(const nlohmann::json& j, radar::Receiver& rx, core::World& world)
    {
        if (!j.contains("timing"))
        {
            return;
        }
        auto timing_id = parse_json_id(j, "timing", "Receiver");
        auto* const timing_proto = world.findTiming(timing_id);
        if (timing_proto == nullptr)
        {
            throw std::runtime_error("Timing ID " + std::to_string(timing_id) + " not found.");
        }
        unsigned const 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);
    }
 
    void update_receiver_schedule_from_json(const nlohmann::json& j, radar::Receiver& rx)
    {
        if (!j.contains("schedule"))
        {
            return;
        }
        auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
        const bool pulsed = rx.getMode() == radar::OperationMode::PULSED_MODE;
        const RealType pri = pulsed ? 1.0 / rx.getWindowPrf() : 0.0;
        rx.setSchedule(radar::processRawSchedule(raw, rx.getName(), pulsed, pri));
    }
 
    void update_receiver_from_json(const nlohmann::json& j, radar::Receiver* rx, core::World& world,
                                   std::mt19937& /*masterSeeder*/)
    {
        if (j.contains("name"))
            rx->setName(j.at("name").get<std::string>());
 
        update_receiver_mode_from_json(j, *rx);
        update_receiver_noise_and_flags_from_json(j, *rx);
        update_receiver_antenna_from_json(j, *rx, world);
        update_receiver_timing_from_json(j, *rx, world);
        update_receiver_schedule_from_json(j, *rx);
        if (j.contains("fmcw_mode"))
        {
            parse_receiver_dechirp_config(j, *rx, "Receiver '" + rx->getName() + "'");
        }
        world.resolveReceiverDechirpReferences();
    }
 
    nlohmann::json monostatic_transmitter_json(const nlohmann::json& j)
    {
        auto transmitter_json = j;
        if (transmitter_json.contains("fmcw_mode") && transmitter_json.at("fmcw_mode").is_object())
        {
            transmitter_json["fmcw_mode"].erase("dechirp_mode");
            transmitter_json["fmcw_mode"].erase("dechirp_reference");
            transmitter_json["fmcw_mode"].erase("if_sample_rate");
            transmitter_json["fmcw_mode"].erase("if_filter_bandwidth");
            transmitter_json["fmcw_mode"].erase("if_filter_transition_width");
        }
        return transmitter_json;
    }
 
    void update_monostatic_receiver_basics(const nlohmann::json& j, const radar::Transmitter& tx, radar::Receiver& rx,
                                           core::World& world)
    {
        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));
        }
        update_receiver_noise_and_flags_from_json(j, rx);
        if (j.contains("antenna"))
        {
            rx.setAntenna(world.findAntenna(parse_json_id(j, "antenna", "Monostatic")));
        }
    }
 
    void update_monostatic_timing_from_json(const nlohmann::json& j, radar::Transmitter& tx, radar::Receiver& rx,
                                            core::World& world)
    {
        if (!j.contains("timing"))
        {
            return;
        }
        auto timing_id = parse_json_id(j, "timing", "Monostatic");
        auto* const timing_proto = world.findTiming(timing_id);
        if (timing_proto == nullptr)
        {
            throw std::runtime_error("Timing ID " + std::to_string(timing_id) + " not found.");
        }
        unsigned const seed = rx.getTiming() ? rx.getTiming()->getSeed() : 0;
        auto shared_timing = std::make_shared<timing::Timing>(timing_proto->getName(), seed, timing_proto->getId());
        shared_timing->initializeModel(timing_proto);
        tx.setTiming(shared_timing);
        rx.setTiming(shared_timing);
    }
 
    void update_monostatic_schedule_from_json(const nlohmann::json& j, radar::Transmitter& tx, radar::Receiver& rx)
    {
        if (!j.contains("schedule"))
        {
            return;
        }
        auto raw = j.at("schedule").get<std::vector<radar::SchedulePeriod>>();
        const bool pulsed = tx.getMode() == radar::OperationMode::PULSED_MODE;
        const RealType pri = pulsed ? 1.0 / tx.getPrf() : 0.0;
        auto processed_schedule = radar::processRawSchedule(raw, tx.getName(), pulsed, pri);
        if (tx.getSignal() != nullptr && tx.getSignal()->isFmcwFamily())
        {
            validate_fmcw_schedule(processed_schedule, *tx.getSignal(), "Monostatic '" + tx.getName() + "'");
        }
        tx.setSchedule(processed_schedule);
        rx.setSchedule(processed_schedule);
    }
 
    void update_monostatic_from_json(const nlohmann::json& j, radar::Transmitter* tx, radar::Receiver* rx,
                                     core::World& world, std::mt19937& masterSeeder)
    {
        auto transmitter_json = monostatic_transmitter_json(j);
        update_transmitter_from_json(transmitter_json, tx, world, masterSeeder);
 
        update_monostatic_receiver_basics(j, *tx, *rx, world);
        update_monostatic_timing_from_json(j, *tx, *rx, world);
        update_monostatic_schedule_from_json(j, *tx, *rx);
        validate_transmitter_signal_state(*tx, "Monostatic '" + tx->getName() + "'");
        if (j.contains("fmcw_mode"))
        {
            parse_receiver_dechirp_config(j, *rx, "Monostatic '" + tx->getName() + "'");
        }
        world.resolveReceiverDechirpReferences();
    }
 
    void update_target_from_json(const nlohmann::json& j, radar::Target* existing_tgt, core::World& world,
                                 std::mt19937& /*masterSeeder*/)
    {
        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 const 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));
    }
 
    void update_timing_from_json(const nlohmann::json& j, core::World& world, const SimId id)
    {
        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));
    }
 
    nlohmann::json world_to_json(const core::World& world)
    {
        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}};
    }
 
    void json_to_world(const nlohmann::json& j, core::World& world, std::mt19937& masterSeeder)
    {
        core::World parsed_world;
        populate_world_from_json(j, parsed_world, masterSeeder);
        world.swap(parsed_world);
    }
}