api.cpp File Reference

Implementation of the C-style FFI for the libfers core library. More...

#include <algorithm>
#include <cmath>
#include <core/logging.h>
#include <core/parameters.h>
#include <core/sim_id.h>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <format>
#include <functional>
#include <iterator>
#include <libfers/api.h>
#include <limits>
#include <math/path.h>
#include <math/rotation_path.h>
#include <mutex>
#include <nlohmann/json.hpp>
#include <optional>
#include <span>
#include <string>
#include <utility>
#include <vector>
#include "antenna/antenna_factory.h"
#include "core/fers_context.h"
#include "core/memory_projection.h"
#include "core/sim_threading.h"
#include "core/thread_pool.h"
#include "fers_version.h"
#include "serial/json_serializer.h"
#include "serial/kml_generator.h"
#include "serial/rotation_angle_utils.h"
#include "serial/rotation_warning_utils.h"
#include "serial/xml_parser.h"
#include "serial/xml_serializer.h"
#include "signal/radar_signal.h"
#include "simulation/channel_model.h"

Include dependency graph for api.cpp:

Go to the source code of this file.

Classes
struct	fers_context

Functions
static void	handle_api_exception (const std::exception &e, const std::string &function_name)
	Centralized exception handler for the C-API boundary.
static void	begin_warning_capture () noexcept
static void	complete_warning_capture ()
static void	discard_warning_capture () noexcept
fers_context_t *	fers_context_create ()
	Creates a new FERS simulation context.
void	fers_context_destroy (fers_context_t *context)
	Destroys a FERS simulation context and releases all associated memory.
static logging::Level	map_api_log_level (fers_log_level_t level)
static fers_log_level_t	map_internal_log_level (logging::Level level)
int	fers_configure_logging (fers_log_level_t level, const char *log_file_path)
	Configures the internal logger.
const char *	fers_get_version (void)
	Returns the library version string.
fers_log_level_t	fers_get_log_level ()
	Returns the current internal logger level.
void	fers_set_log_callback (fers_log_callback_t callback, void *user_data)
	Registers a callback for formatted log lines.
void	fers_log (fers_log_level_t level, const char *message)
	Submits a log message to the library's unified logging system.
int	fers_set_thread_count (unsigned num_threads)
	Sets the number of worker threads for the simulation.
int	fers_set_output_directory (fers_context_t *context, const char *out_dir)
	Sets the output directory for simulation results.
int	fers_use_hdf5_output (fers_context_t *context)
	Resets the context output mode to the default HDF5 output.
int	fers_enable_vita49_udp_output (fers_context_t *context, const char *host, const std::uint16_t port)
int	fers_set_vita49_fullscale (fers_context_t *context, const double fullscale)
	Sets the fixed ADC full-scale value used by the FERS VITA 49.2 int16 IQ profile.
int	fers_set_vita49_epoch_unix_nanoseconds (fers_context_t *context, const std::uint64_t epoch_unix_nanoseconds)
int	fers_set_vita49_max_udp_payload (fers_context_t *context, const std::uint16_t max_udp_payload)
int	fers_set_vita49_queue_depth (fers_context_t *context, const std::uint32_t queue_depth)
int	fers_set_vita49_packet_trace_enabled (fers_context_t *context, const int enabled)
	Enables or disables FERS VITA 49.2 packet trace telemetry.
int	fers_load_scenario_from_xml_file (fers_context_t *context, const char *xml_filepath, const int validate)
	Loads a scenario into the context from a FERS XML file.
int	fers_load_scenario_from_xml_string (fers_context_t *context, const char *xml_content, const int validate)
	Loads a scenario into the context from a FERS XML string.
char *	fers_get_scenario_as_json (fers_context_t *context)
	Serializes the current simulation scenario into a JSON string.
char *	fers_get_scenario_as_xml (fers_context_t *context)
	Serializes the current simulation scenario into a FERS XML string.
char *	fers_get_last_output_metadata_json (fers_context_t *context)
	Returns JSON metadata for the most recent simulation output files.
char *	fers_get_memory_projection_json (fers_context_t *context)
	Returns a JSON projection of simulation startup memory and HDF5 payload size.
int	fers_update_platform_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single platform's paths and name from JSON without full context recreation.
int	fers_update_parameters_from_json (fers_context_t *context, const char *json)
	Updates the global simulation parameters from JSON without full context recreation.
int	fers_update_antenna_from_json (fers_context_t *context, const char *json)
	Updates a single antenna from JSON without full context recreation.
int	fers_update_waveform_from_json (fers_context_t *context, const char *json)
	Updates a single waveform from JSON without full context recreation.
int	fers_update_transmitter_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single transmitter from JSON without full context recreation.
int	fers_update_receiver_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single receiver from JSON without full context recreation.
int	fers_update_target_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single target from JSON without full context recreation.
int	fers_update_monostatic_from_json (fers_context_t *context, const char *json)
	Updates a monostatic radar from JSON without full context recreation.
int	fers_update_timing_from_json (fers_context_t *context, uint64_t id, const char *json)
	Updates a single timing source from JSON without full context recreation.
int	fers_update_scenario_from_json (fers_context_t *context, const char *scenario_json)
	Updates the simulation scenario from a JSON string.
char *	fers_get_last_error_message ()
	Retrieves the last error message that occurred on the current thread.
char *	fers_get_last_warning_messages_json ()
	Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.
void	fers_free_string (char *str)
	Frees a string that was allocated and returned by the libfers API.
int	fers_run_simulation (fers_context_t *context, fers_progress_callback_t callback, void *user_data)
	Runs the simulation defined in the provided context.
int	fers_run_simulation_ex (fers_context_t *context, fers_progress_callback_t progress_callback, void *progress_user_data, fers_cancel_callback_t cancel_callback, void *cancel_user_data, fers_vita49_telemetry_callback_t vita49_telemetry_callback, void *vita49_telemetry_user_data)
	Runs the simulation with optional progress, cancellation, and VITA telemetry callbacks.
int	fers_generate_kml (const fers_context_t *context, const char *output_kml_filepath)
	Generates a KML file for visualizing the scenario in the context.
math::Path::InterpType	to_cpp_interp_type (const fers_interp_type_t type)
math::RotationPath::InterpType	to_cpp_rot_interp_type (const fers_interp_type_t type)
fers_interpolated_path_t *	fers_get_interpolated_motion_path (const fers_motion_waypoint_t *waypoints, const size_t waypoint_count, const fers_interp_type_t interp_type, const size_t num_points)
	Calculates an interpolated motion path from a set of waypoints.
void	fers_free_interpolated_motion_path (fers_interpolated_path_t *path)
	Frees the memory allocated for an interpolated motion path.
fers_interpolated_rotation_path_t *	fers_get_interpolated_rotation_path (const fers_rotation_waypoint_t *waypoints, const size_t waypoint_count, const fers_interp_type_t interp_type, const fers_angle_unit_t angle_unit, const size_t num_points)
	Calculates an interpolated rotation path from a set of waypoints.
void	fers_free_interpolated_rotation_path (fers_interpolated_rotation_path_t *path)
	Frees the memory allocated for an interpolated rotation path.
fers_antenna_pattern_data_t *	fers_get_antenna_pattern (const fers_context_t *context, const uint64_t antenna_id, const size_t az_samples, const size_t el_samples, const double frequency_hz)
	Samples the gain pattern of a specified antenna and provides the data.
void	fers_free_antenna_pattern_data (fers_antenna_pattern_data_t *data)
	Frees the memory allocated for an antenna pattern data structure.
fers_visual_link_list_t *	fers_calculate_preview_links (const fers_context_t *context, const double time)
	Calculates visual links for a specific simulation time.
void	fers_free_preview_links (fers_visual_link_list_t *list)
	Frees the memory allocated for a preview link list.

Variables
thread_local std::string	last_error_message
thread_local std::vector< std::string >	last_warning_messages

Detailed Description

Implementation of the C-style FFI for the libfers core library.

This file provides the C implementations for the functions declared in api.h. It acts as the bridge between the C ABI and the C++ core, handling object creation/destruction, exception catching, error reporting, and type casting.

Definition in file api.cpp.

Function Documentation

begin_warning_capture()

static void begin_warning_capture ( )

staticnoexcept

Definition at line 78 of file api.cpp.

{
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
}

References serial::rotation_warning_utils::clear_captured_warnings(), and last_warning_messages.

Referenced by fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

complete_warning_capture()

static void complete_warning_capture ( )

static

Definition at line 84 of file api.cpp.

{
    last_warning_messages = serial::rotation_warning_utils::take_captured_warnings();
}

References last_warning_messages, and serial::rotation_warning_utils::take_captured_warnings().

Referenced by fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

discard_warning_capture()

static void discard_warning_capture ( )

staticnoexcept

Definition at line 89 of file api.cpp.

{
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
}

References serial::rotation_warning_utils::clear_captured_warnings(), and last_warning_messages.

Referenced by fers_context_create(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_update_parameters_from_json(), fers_update_platform_from_json(), and fers_update_scenario_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

fers_calculate_preview_links()

fers_visual_link_list_t * fers_calculate_preview_links	(	const fers_context_t *	context,
		double	time
	)

Calculates visual links for a specific simulation time.

Parameters

context	The simulation context.
time	The simulation time in seconds.

Returns

A pointer to a link list. Caller must free with fers_free_preview_links.

Definition at line 1596 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context passed to fers_calculate_preview_links";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = context;
        // Call the core physics logic in channel_model.cpp
        const auto cpp_links = simulation::calculatePreviewLinks(*ctx->getWorld(), time);
 
        // Convert C++ vector to C-API struct
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API returns owned preview-link lists.
        auto* result = new fers_visual_link_list_t();
        result->count = cpp_links.size();
 
        if (!cpp_links.empty())
        {
            // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API frees this array with the parent list.
            result->links = new fers_visual_link_t[result->count];
            for (size_t i = 0; i < result->count; ++i)
            {
                const auto& src = cpp_links[i];
                auto& dst = result->links[i];
 
                // Map enums
                switch (src.type)
                {
                case simulation::LinkType::Monostatic:
                    dst.type = FERS_LINK_MONOSTATIC;
                    break;
                case simulation::LinkType::BistaticTxTgt:
                    dst.type = FERS_LINK_BISTATIC_TX_TGT;
                    break;
                case simulation::LinkType::BistaticTgtRx:
                    dst.type = FERS_LINK_BISTATIC_TGT_RX;
                    break;
                case simulation::LinkType::DirectTxRx:
                    dst.type = FERS_LINK_DIRECT_TX_RX;
                    break;
                }
 
                dst.quality = (src.quality == simulation::LinkQuality::Strong) ? FERS_LINK_STRONG : FERS_LINK_WEAK;
 
                copy_visual_link_label(dst, src.label);
 
                dst.source_id = static_cast<uint64_t>(src.source_id);
                dst.dest_id = static_cast<uint64_t>(src.dest_id);
                dst.origin_id = static_cast<uint64_t>(src.origin_id);
                dst.rcs = src.rcs;
                dst.actual_power_dbm = src.actual_power_dbm;
                dst.display_value = src.display_value;
            }
        }
        else
        {
            result->links = nullptr;
        }
        return result;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_calculate_preview_links");
        return nullptr;
    }
}

References simulation::BistaticTgtRx, simulation::BistaticTxTgt, simulation::calculatePreviewLinks(), simulation::DirectTxRx, logging::ERROR, FERS_LINK_BISTATIC_TGT_RX, FERS_LINK_BISTATIC_TX_TGT, FERS_LINK_DIRECT_TX_RX, FERS_LINK_MONOSTATIC, FERS_LINK_STRONG, FERS_LINK_WEAK, handle_api_exception(), last_error_message, LOG, simulation::Monostatic, simulation::Strong, and fers_visual_link_t::type.

Here is the call graph for this function:

fers_configure_logging()

int fers_configure_logging	(	fers_log_level_t	level,
		const char *	log_file_path
	)

Configures the internal logger.

Parameters

level	The minimum severity level to log.
log_file_path	Optional path to a log file. Pass NULL to disable file logging.

Returns

0 on success, non-zero on error.

Definition at line 354 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        logging::logger.setLevel(map_api_log_level(level));
        if ((log_file_path != nullptr) && ((*log_file_path) != 0))
        {
            auto result = logging::logger.logToFile(log_file_path);
            if (!result)
            {
                last_error_message = result.error();
                return 1;
            }
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_configure_logging");
        return 1;
    }
}

References handle_api_exception(), last_error_message, logging::logger, logging::Logger::logToFile(), map_api_log_level(), and logging::Logger::setLevel().

Here is the call graph for this function:

fers_context_create()

fers_context_t * fers_context_create

(

)

Creates a new FERS simulation context.

Allocates and initializes a new, empty simulation context in memory. This context serves as the container for a scenario loaded via one of the fers_load_... or fers_update_... functions.

Note

In a C API, RAII is not available. The caller is responsible for destroying the returned context using fers_context_destroy() to prevent resource leaks.

Returns

A non-null opaque pointer (handle) to the simulation context on success. Returns NULL on failure (e.g., out of memory).

Definition at line 97 of file api.cpp.

{
    last_error_message.clear();
    discard_warning_capture();
    try
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API returns an owned handle.
        return new fers_context_t();
    }
    catch (const std::bad_alloc& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_context_create");
        return nullptr;
    }
}

References discard_warning_capture(), handle_api_exception(), and last_error_message.

Here is the call graph for this function:

fers_context_destroy()

void fers_context_destroy

(

fers_context_t *

context

)

Destroys a FERS simulation context and releases all associated memory.

This function must be called for every context created by fers_context_create() to ensure proper cleanup of the underlying C++ objects. Accessing the context handle after calling this function results in undefined behavior.

Parameters

context

A valid pointer to a fers_context_t handle. If context is NULL, the function performs no action for safety and does not set an error.

Definition at line 118 of file api.cpp.

{
    if (context == nullptr)
    {
        return;
    }
    // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees handles allocated by `fers_context_create`.
    delete context;
}

fers_enable_vita49_udp_output()

int fers_enable_vita49_udp_output	(	fers_context_t *	context,
		const char *	host,
		const std::uint16_t	port
	)

Definition at line 465 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
    if (host == nullptr)
    {
        set_api_error("Invalid VITA49 endpoint: host is NULL.");
        return -1;
    }
    if (*host == '\0')
    {
        set_api_error("Invalid VITA49 endpoint: host must be non-empty.");
        return 1;
    }
    if (port == 0)
    {
        set_api_error("Invalid VITA49 endpoint: port must be in the range 1..65535.");
        return 1;
    }
 
    auto* ctx = context;
    try
    {
        core::OutputConfig config = ctx->getOutputConfig();
        config.mode = core::OutputMode::Vita49Udp;
        config.vita49.host = host;
        config.vita49.port = port;
        ctx->setOutputConfig(std::move(config));
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_enable_vita49_udp_output");
        return 1;
    }
}

References handle_api_exception(), core::Vita49OutputConfig::host, last_error_message, core::OutputConfig::mode, core::Vita49OutputConfig::port, core::OutputConfig::vita49, and core::Vita49Udp.

Here is the call graph for this function:

fers_free_antenna_pattern_data()

void fers_free_antenna_pattern_data

(

fers_antenna_pattern_data_t *

data

)

Frees the memory allocated for an antenna pattern data structure.

Parameters

data	A pointer to the fers_antenna_pattern_data_t struct to free.

Definition at line 1583 of file api.cpp.

{
    if (data != nullptr)
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees arrays owned by C API pattern structs.
        delete[] data->gains;
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees structs allocated by `fers_get_antenna_pattern`.
        delete data;
    }
}

References fers_antenna_pattern_data_t::gains.

fers_free_interpolated_motion_path()

void fers_free_interpolated_motion_path

(

fers_interpolated_path_t *

path

)

Frees the memory allocated for an interpolated motion path.

Parameters

path	A pointer to the fers_interpolated_path_t struct to free.

Definition at line 1380 of file api.cpp.

{
    if (path != nullptr)
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees arrays owned by C API path structs.
        delete[] path->points;
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees structs allocated by
        // `fers_get_interpolated_motion_path`.
        delete path;
    }
}

References fers_interpolated_path_t::points.

fers_free_interpolated_rotation_path()

void fers_free_interpolated_rotation_path

(

fers_interpolated_rotation_path_t *

path

)

Frees the memory allocated for an interpolated rotation path.

Parameters

path	A pointer to the fers_interpolated_rotation_path_t struct to free.

Definition at line 1481 of file api.cpp.

{
    if (path != nullptr)
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees arrays owned by C API path structs.
        delete[] path->points;
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees structs allocated by
        // `fers_get_interpolated_rotation_path`.
        delete path;
    }
}

References fers_interpolated_rotation_path_t::points.

fers_free_preview_links()

void fers_free_preview_links

(

fers_visual_link_list_t *

list

)

Frees the memory allocated for a preview link list.

Parameters

list	The list to free.

Definition at line 1668 of file api.cpp.

{
    if (list != nullptr)
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees arrays owned by C API preview-link lists.
        delete[] list->links;
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Frees structs allocated by `fers_calculate_preview_links`.
        delete list;
    }
}

References fers_visual_link_list_t::links.

fers_free_string()

void fers_free_string

(

char *

str

)

Frees a string that was allocated and returned by the libfers API.

This function must be used to release memory for any string returned by functions like fers_get_scenario_as_json or fers_get_last_error_message. It exists to ensure that the memory deallocation mechanism (free) matches the allocation mechanism (strdup/malloc) used within the C++ library, preventing potential crashes from mismatched allocators across language boundaries.

Parameters

str	A pointer to the string to be freed. If str is NULL, no action is taken.

Definition at line 1110 of file api.cpp.

{
    if (str != nullptr)
    {
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API frees strings returned by this library.
        free(str);
    }
}

fers_generate_kml()

int fers_generate_kml	(	const fers_context_t *	context,
		const char *	output_kml_filepath
	)

Generates a KML file for visualizing the scenario in the context.

This utility exists to provide a simple, out-of-the-box method for users to validate and visualize the geographic layout and motion paths of their scenarios in common external tools like Google Earth.

Parameters

context	A valid fers_context_t handle containing a loaded scenario.
output_kml_filepath	A null-terminated UTF-8 string for the output KML file path.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve KML generation details.

Definition at line 1242 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (output_kml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or output_kml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        return -1;
    }
 
    const auto* ctx = context;
 
    try
    {
        const auto result = serial::KmlGenerator::generateKml(*ctx->getWorld(), output_kml_filepath);
        if (result)
        {
            return 0; // Success
        }
 
        last_error_message = result.error();
        LOG(logging::Level::ERROR, last_error_message);
        return 2; // Generation failed
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_generate_kml");
        return 1; // Exception thrown
    }
}

References logging::ERROR, serial::KmlGenerator::generateKml(), handle_api_exception(), last_error_message, and LOG.

Here is the call graph for this function:

fers_get_antenna_pattern()

fers_antenna_pattern_data_t * fers_get_antenna_pattern	(	const fers_context_t *	context,
		uint64_t	antenna_id,
		size_t	az_samples,
		size_t	el_samples,
		double	frequency_hz
	)

Samples the gain pattern of a specified antenna and provides the data.

This function calculates the antenna's far-field gain at a specified resolution over the full sphere of directions (azimuth and elevation). The resulting gain values are linear (not in dB) and normalized relative to the pattern's peak gain. This is a stateless utility useful for UI previews and analysis.

Parameters

context	A valid fers_context_t handle containing a loaded scenario with the antenna.
antenna_id	The unique ID of the antenna asset to sample.
az_samples	The desired number of sample points along the azimuth axis. Must be at least 2 to span the full azimuth range.
el_samples	The desired number of sample points along the elevation axis. Must be at least 2 to span the full elevation range.
frequency_hz	The frequency in Hz to use for gain calculation (affects aperture antennas).

Returns

A pointer to a fers_antenna_pattern_data_t struct containing the results. Returns NULL on failure (e.g., antenna not found). The caller owns the returned struct and must free it with fers_free_antenna_pattern_data.

Definition at line 1495 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || az_samples < 2 || el_samples < 2)
    {
        last_error_message = "Invalid arguments: context must be non-null and sample counts must be >= 2.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto* ctx = context;
        antenna::Antenna const* ant = ctx->getWorld()->findAntenna(static_cast<SimId>(antenna_id));
 
        if (ant == nullptr)
        {
            last_error_message = "Antenna ID '" + std::to_string(antenna_id) + "' not found in the world.";
            LOG(logging::Level::ERROR, last_error_message);
            return nullptr;
        }
 
        // TODO: Currently only using the first-found waveform. This is incorrect but also difficult to represent
        //       correctly in scenarios with multiple waveforms as the gain for squarehorn and parabolic antennas
        // depends on        the wavelength. Hence a decision needs to be made about whether to return multiple patterns
        // per waveform or       have the user specify a representative wavelength in the UI per antenna.
        // Calculate wavelength from the provided frequency.
        // Default to 1GHz (0.3m) if frequency is invalid/zero, though the UI should prevent this
        // for antennas that strictly require it (Horn/Parabolic).
        RealType wavelength = 0.3;
        if (frequency_hz > 0.0)
        {
            wavelength = params::c() / frequency_hz;
        }
 
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API returns owned antenna pattern data.
        auto* data = new fers_antenna_pattern_data_t();
        data->az_count = az_samples;
        data->el_count = el_samples;
        const size_t total_samples = az_samples * el_samples;
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API frees this array with the parent data.
        data->gains = new double[total_samples];
 
        // The reference angle (boresight) is implicitly the local X-axis in the FERS engine.
        // We pass a zero rotation to get the gain relative to this boresight.
        const math::SVec3 ref_angle(1.0, 0.0, 0.0);
        double max_gain = 0.0;
 
        const auto az_denominator = static_cast<RealType>(az_samples - 1);
        const auto el_denominator = static_cast<RealType>(el_samples - 1);
 
        for (size_t i = 0; i < el_samples; ++i)
        {
            // Elevation from -PI/2 to PI/2
            const RealType elevation = (static_cast<RealType>(i) / el_denominator) * PI - (PI / 2.0);
            for (size_t j = 0; j < az_samples; ++j)
            {
                // Azimuth from -PI to PI
                const RealType azimuth = (static_cast<RealType>(j) / az_denominator) * 2.0 * PI - PI;
                const math::SVec3 sample_angle(1.0, azimuth, elevation);
                const RealType gain = ant->getGain(sample_angle, ref_angle, wavelength);
                data->gains[i * az_samples + j] = gain;
                max_gain = std::max(gain, max_gain);
            }
        }
 
        data->max_gain = max_gain;
 
        // Normalize the gains
        if (max_gain > 0)
        {
            for (size_t i = 0; i < total_samples; ++i)
            {
                data->gains[i] /= max_gain;
            }
        }
 
        return data;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_antenna_pattern");
        return nullptr;
    }
}

References params::c(), logging::ERROR, antenna::Antenna::getGain(), handle_api_exception(), last_error_message, LOG, and PI.

Here is the call graph for this function:

fers_get_interpolated_motion_path()

fers_interpolated_path_t * fers_get_interpolated_motion_path	(	const fers_motion_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		size_t	num_points
	)

Calculates an interpolated motion path from a set of waypoints.

This function is a stateless utility that computes the path without needing a full simulation context. It is useful for UI previews.

Parameters

waypoints	An array of fers_motion_waypoint_t structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use.
num_points	The desired number of points in the output interpolated path.

Returns

A pointer to a fers_interpolated_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_motion_path.

Definition at line 1303 of file api.cpp.

{
    last_error_message.clear();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        math::Path path;
        path.setInterp(to_cpp_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            math::Coord c;
            c.t = waypoints[i].time;
            c.pos.x = waypoints[i].x;
            c.pos.y = waypoints[i].y;
            c.pos.z = waypoints[i].z;
            path.addCoord(c);
        }
 
        path.finalize();
 
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API returns an owned path struct.
        auto* result_path = new fers_interpolated_path_t();
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API frees this array with the parent path.
        result_path->points = new fers_interpolated_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::Vec3 pos = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = {pos.x, pos.y, pos.z, 0.0, 0.0, 0.0};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::Vec3 pos = path.getPosition(t);
            const math::Vec3 vel = path.getVelocity(t);
            result_path->points[i] = {pos.x, pos.y, pos.z, vel.x, vel.y, vel.z};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_interpolated_motion_path");
        return nullptr;
    }
}

References math::Path::addCoord(), c, logging::ERROR, FERS_INTERP_CUBIC, math::Path::finalize(), math::Path::getPosition(), math::Path::getVelocity(), handle_api_exception(), last_error_message, LOG, math::Path::setInterp(), math::Coord::t, fers_motion_waypoint_t::time, to_cpp_interp_type(), fers_motion_waypoint_t::x, math::Vec3::x, fers_motion_waypoint_t::y, math::Vec3::y, fers_motion_waypoint_t::z, and math::Vec3::z.

Here is the call graph for this function:

fers_get_interpolated_rotation_path()

fers_interpolated_rotation_path_t * fers_get_interpolated_rotation_path	(	const fers_rotation_waypoint_t *	waypoints,
		size_t	waypoint_count,
		fers_interp_type_t	interp_type,
		fers_angle_unit_t	angle_unit,
		size_t	num_points
	)

Calculates an interpolated rotation path from a set of waypoints.

This function is a stateless utility for UI previews.

Parameters

waypoints	An array of fers_rotation_waypoint_t structs.
waypoint_count	The number of waypoints in the array.
interp_type	The interpolation algorithm to use (STATIC, LINEAR, CUBIC).
angle_unit	The unit used by the waypoint angles and desired output angles.
num_points	The desired number of points in the output interpolated path.

Returns

A pointer to a fers_interpolated_rotation_path_t struct containing the results. Returns NULL on failure. The caller owns the returned struct and must free it with fers_free_interpolated_rotation_path.

Definition at line 1392 of file api.cpp.

{
    last_error_message.clear();
    last_warning_messages.clear();
    serial::rotation_warning_utils::clear_captured_warnings();
    if ((waypoints == nullptr) || waypoint_count == 0 || num_points == 0)
    {
        last_error_message = "Invalid arguments: waypoints cannot be null and counts must be > 0.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
    if (interp_type == FERS_INTERP_CUBIC && waypoint_count < 2)
    {
        last_error_message = "Cubic interpolation requires at least 2 waypoints.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    try
    {
        const auto unit =
            angle_unit == FERS_ANGLE_UNIT_RAD ? params::RotationAngleUnit::Radians : params::RotationAngleUnit::Degrees;
        math::RotationPath path;
        path.setInterp(to_cpp_rot_interp_type(interp_type));
 
        for (size_t i = 0; i < waypoint_count; ++i)
        {
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].azimuth, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "azimuth");
            serial::rotation_warning_utils::maybe_warn_about_rotation_value(
                waypoints[i].elevation, unit, serial::rotation_warning_utils::ValueKind::Angle, "C-API",
                std::format("rotation waypoint {}", i), "elevation");
            path.addCoord(serial::rotation_angle_utils::external_rotation_to_internal(
                waypoints[i].azimuth, waypoints[i].elevation, waypoints[i].time, unit));
        }
 
        path.finalize();
 
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API returns an owned path struct.
        auto* result_path = new fers_interpolated_rotation_path_t();
        // NOLINTNEXTLINE(cppcoreguidelines-owning-memory): Public C API frees this array with the parent path.
        result_path->points = new fers_interpolated_rotation_point_t[num_points];
        result_path->count = num_points;
 
        const double start_time = waypoints[0].time;
        const double end_time = waypoints[waypoint_count - 1].time;
        const double duration = end_time - start_time;
 
        // Handle static case separately
        if (waypoint_count < 2 || duration <= 0)
        {
            const math::SVec3 rot = path.getPosition(start_time);
            for (size_t i = 0; i < num_points; ++i)
            {
                result_path->points[i] = fers_interpolated_rotation_point_t{
                    serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                    serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
            }
            return result_path;
        }
 
        const double time_step =
            duration / static_cast<double>(num_points > 1 ? num_points - 1 : static_cast<size_t>(1));
 
        for (size_t i = 0; i < num_points; ++i)
        {
            const double t = start_time + static_cast<double>(i) * time_step;
            const math::SVec3 rot = path.getPosition(t);
 
            result_path->points[i] = fers_interpolated_rotation_point_t{
                serial::rotation_angle_utils::internal_azimuth_to_external(rot.azimuth, unit),
                serial::rotation_angle_utils::internal_elevation_to_external(rot.elevation, unit)};
        }
 
        return result_path;
    }
    catch (const std::exception& e)
    {
        serial::rotation_warning_utils::clear_captured_warnings();
        handle_api_exception(e, "fers_get_interpolated_rotation_path");
        return nullptr;
    }
}

References math::RotationPath::addCoord(), serial::rotation_warning_utils::Angle, math::SVec3::azimuth, serial::rotation_warning_utils::clear_captured_warnings(), params::Degrees, math::SVec3::elevation, logging::ERROR, serial::rotation_angle_utils::external_rotation_to_internal(), FERS_ANGLE_UNIT_RAD, FERS_INTERP_CUBIC, math::RotationPath::finalize(), math::RotationPath::getPosition(), handle_api_exception(), serial::rotation_angle_utils::internal_azimuth_to_external(), serial::rotation_angle_utils::internal_elevation_to_external(), last_error_message, last_warning_messages, LOG, serial::rotation_warning_utils::maybe_warn_about_rotation_value(), params::Radians, math::RotationPath::setInterp(), fers_rotation_waypoint_t::time, and to_cpp_rot_interp_type().

Here is the call graph for this function:

fers_get_last_error_message()

char * fers_get_last_error_message

(

)

Retrieves the last error message that occurred on the current thread.

Because C++ exceptions cannot safely propagate across the FFI boundary into other languages, this function provides the standard C-style error reporting mechanism. The error state is stored in a thread-local variable to ensure that concurrent API calls from different threads do not overwrite each other's error messages. The error is cleared at the start of each fallible API call.

Note

Memory Management: The returned string's ownership is transferred to the caller. It MUST be freed using fers_free_string() to prevent memory leaks.

Returns

A dynamically allocated, null-terminated C-string containing the last error message, or NULL if no error has occurred.

Definition at line 1085 of file api.cpp.

{
    if (last_error_message.empty())
    {
        return nullptr; // No error to report
    }
    // `strdup` allocates with `malloc`, which is part of the C standard ABI,
    // making it safe to transfer ownership across the FFI boundary. The caller
    // must then free this memory using `fers_free_string`.
    // NOLINTNEXTLINE(cppcoreguidelines-no-malloc): C ABI string ownership is freed by `fers_free_string`.
    return strdup(last_error_message.c_str());
}

References last_error_message.

fers_get_last_output_metadata_json()

char * fers_get_last_output_metadata_json

(

fers_context_t *

context

)

Returns JSON metadata for the most recent simulation output files.

The returned JSON describes generated HDF5 file structure and sample ranges. The caller owns the returned string and must free it with fers_free_string. If no simulation has completed yet, the returned JSON contains an empty files array.

Parameters

context

A valid fers_context_t handle.

Returns

A heap-allocated JSON string, or NULL on error.

Definition at line 759 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_last_output_metadata_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = context;
    try
    {
        const std::string json_str = ctx->getLastOutputMetadataJson();
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_last_output_metadata_json");
        return nullptr;
    }
}

References logging::ERROR, FersContext::getLastOutputMetadataJson(), handle_api_exception(), last_error_message, and LOG.

Here is the call graph for this function:

fers_get_last_warning_messages_json()

char * fers_get_last_warning_messages_json

(

)

Returns the last deduplicated rotation-unit warning list for the calling thread as JSON.

The returned value is a JSON array of strings. It is populated by successful XML/JSON load and update calls that detect suspicious rotation values. The caller owns the string and must free it with fers_free_string().

Returns

A dynamically allocated JSON array string, or NULL if no warnings are available.

Definition at line 1098 of file api.cpp.

{
    if (last_warning_messages.empty())
    {
        return nullptr;
    }
 
    const std::string warning_json = nlohmann::json(last_warning_messages).dump();
    last_warning_messages.clear();
    return strdup(warning_json.c_str());
}

References last_warning_messages.

fers_get_log_level()

fers_log_level_t fers_get_log_level

(

)

Returns the current internal logger level.

Definition at line 380 of file api.cpp.

{ return map_internal_log_level(logging::logger.getLevel()); }

References logging::logger, and map_internal_log_level().

Here is the call graph for this function:

fers_get_memory_projection_json()

char * fers_get_memory_projection_json

(

fers_context_t *

context

)

Returns a JSON projection of simulation startup memory and HDF5 payload size.

The projection includes phase-noise lookup memory, streaming I/Q buffer memory, rendered HDF5 payload size, current resident memory not attributed to streaming I/Q buffers where available, and an aggregate projected total. The caller owns the returned string and must free it with fers_free_string.

Parameters

context

A valid fers_context_t handle.

Returns

A heap-allocated JSON string, or NULL on error.

Definition at line 782 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_memory_projection_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    auto* ctx = context;
 
    try
    {
        const auto projection = core::projectSimulationMemory(*ctx->getWorld());
        const std::string json_str = core::memoryProjectionToJsonString(projection);
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_memory_projection_json");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, core::memoryProjectionToJsonString(), and core::projectSimulationMemory().

Here is the call graph for this function:

fers_get_scenario_as_json()

char * fers_get_scenario_as_json

(

fers_context_t *

context

)

Serializes the current simulation scenario into a JSON string.

This function is the primary method for the UI to retrieve the full state of the simulation. JSON is used as the interchange format because it is lightweight, human-readable, and natively supported by web technologies, making it trivial to parse and use in the React/TypeScript frontend.

Note

Memory Management: The returned string is allocated by this library and its ownership is transferred to the caller. It is crucial to free this string using fers_free_string() to prevent memory leaks.

Parameters

context

A valid fers_context_t handle.

Returns

A dynamically allocated, null-terminated C-string containing the JSON representation of the scenario. Returns NULL on failure.

Definition at line 702 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_json.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = context;
    try
    {
        const nlohmann::json j = serial::world_to_json(*ctx->getWorld());
        const std::string json_str = j.dump(2);
        // A heap-allocated copy of the string is returned. This is necessary
        // to transfer ownership of the memory across the FFI boundary to a
        // client that will free it using `fers_free_string`.
        return strdup(json_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_json");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_json().

Here is the call graph for this function:

fers_get_scenario_as_xml()

char * fers_get_scenario_as_xml

(

fers_context_t *

context

)

Serializes the current simulation scenario into a FERS XML string.

This function enables exporting the in-memory state back into the standard FERS XML file format. This is essential for interoperability with legacy tools and for allowing a user to save a scenario that was created or modified in the UI.

Note

Memory Management: The returned string is dynamically allocated and its ownership is transferred to the caller. It must be freed using fers_free_string() to prevent memory leaks.

Parameters

context

A valid fers_context_t handle.

Returns

A dynamically allocated, null-terminated C-string containing the XML representation of the scenario. Returns NULL on failure.

Definition at line 729 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        last_error_message = "Invalid context provided to fers_get_scenario_as_xml.";
        LOG(logging::Level::ERROR, last_error_message);
        return nullptr;
    }
 
    const auto* ctx = context;
    try
    {
        const std::string xml_str = serial::world_to_xml_string(*ctx->getWorld());
        if (xml_str.empty())
        {
            throw std::runtime_error("XML serialization resulted in an empty string.");
        }
        // `strdup` is used to create a heap-allocated string that can be safely
        // passed across the FFI boundary. The client is responsible for freeing
        // this memory with `fers_free_string`.
        return strdup(xml_str.c_str());
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_get_scenario_as_xml");
        return nullptr;
    }
}

References logging::ERROR, handle_api_exception(), last_error_message, LOG, and serial::world_to_xml_string().

Here is the call graph for this function:

fers_get_version()

const char * fers_get_version

(

void

)

Returns the library version string.

The returned pointer remains valid for the lifetime of the process and must not be freed by the caller.

Definition at line 378 of file api.cpp.

{ return FERS_VERSION_STRING; }

Referenced by core::showHelp().

Here is the caller graph for this function:

fers_load_scenario_from_xml_file()

int fers_load_scenario_from_xml_file	(	fers_context_t *	context,
		const char *	xml_filepath,
		int	validate
	)

Loads a scenario into the context from a FERS XML file.

This is the standard method for initializing a simulation context from a file on disk. It is essential for interoperability with the CLI and legacy workflows that rely on the FERS XML format.

Parameters

context	A valid fers_context_t handle.
xml_filepath	A null-terminated UTF-8 string for the input XML file path.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema. Validation is recommended to ensure scenario correctness.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 606 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_filepath == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_filepath is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = context;
    try
    {
        // Set default output directory to the scenario file's directory
        std::filesystem::path const p(xml_filepath);
        auto parent = p.parent_path();
        if (parent.empty())
            parent = ".";
        ctx->setOutputDir(parent.string());
 
        serial::parseSimulation(xml_filepath, ctx->getWorld(), static_cast<bool>(validate), ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This is done
        // to ensure simulation reproducibility. If the scenario specifies a seed,
        // it is used; otherwise, a non-deterministic seed is generated so that
        // subsequent runs are unique by default.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario file: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_file");
        return 1; // Error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulation(), and params::Parameters::random_seed.

Here is the call graph for this function:

fers_load_scenario_from_xml_string()

int fers_load_scenario_from_xml_string	(	fers_context_t *	context,
		const char *	xml_content,
		int	validate
	)

Loads a scenario into the context from a FERS XML string.

This function provides a way to load a scenario from an in-memory string, avoiding file I/O. It is useful for test harnesses or for UIs that manage scenarios as text content before parsing.

Parameters

context	A valid fers_context_t handle.
xml_content	A null-terminated UTF-8 string containing the FERS scenario in XML format.
validate	A boolean (0 or 1) indicating whether to validate the XML against the embedded FERS schema.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 657 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (xml_content == nullptr))
    {
        last_error_message = "Invalid arguments: context or xml_content is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = context;
    try
    {
        serial::parseSimulationFromString(xml_content, ctx->getWorld(), static_cast<bool>(validate),
                                          ctx->getMasterSeeder());
 
        // After parsing, seed the master random number generator. This ensures
        // that if the scenario provides a seed, the simulation will be
        // reproducible. If not, a random seed is used to ensure unique runs.
        if (params::params.random_seed)
        {
            LOG(logging::Level::INFO, "Using master seed from scenario string: {}", *params::params.random_seed);
            ctx->getMasterSeeder().seed(*params::params.random_seed);
        }
        else
        {
            const auto seed = std::random_device{}();
            LOG(logging::Level::INFO, "No master seed provided in scenario. Using random_device seed: {}", seed);
            params::params.random_seed = seed;
            ctx->getMasterSeeder().seed(seed);
        }
 
        complete_warning_capture();
        return 0; // Success
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_load_scenario_from_xml_string");
        return 1; // Parsing or logic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), logging::INFO, last_error_message, LOG, params::params, serial::parseSimulationFromString(), and params::Parameters::random_seed.

Here is the call graph for this function:

fers_log()

void fers_log	(	fers_log_level_t	level,
		const char *	message
	)

Submits a log message to the library's unified logging system.

This ensures CLI messages match the format (timestamps, alignment) of library messages.

Definition at line 393 of file api.cpp.

{
    if (message == nullptr)
        return;
    // We pass a default source_location because C-API calls don't provide C++ source info
    logging::logger.log(map_api_log_level(level), message, std::source_location::current());
}

References logging::Logger::log(), logging::logger, and map_api_log_level().

Here is the call graph for this function:

fers_run_simulation()

int fers_run_simulation	(	fers_context_t *	context,
		fers_progress_callback_t	callback,
		void *	user_data
	)

Runs the simulation defined in the provided context.

This function is synchronous and will block the calling thread until the simulation is complete. This design keeps the API simple. For use in a responsive UI, it is the responsibility of the caller (e.g., the Tauri backend) to invoke this function on a separate worker thread to avoid freezing the user interface.

Parameters

context	A valid fers_context_t handle containing a loaded scenario.
callback	A function pointer to a progress callback. Can be NULL.
user_data	An opaque pointer passed to the callback function.

Returns

0 on success, a non-zero error code on failure. Use fers_get_last_error_message() to retrieve error details.

Definition at line 1212 of file api.cpp.

{
    return run_simulation_common(
        SimulationRunRequest{.context = context,
                             .progress_callback = callback,
                             .progress_user_data = user_data,
                             .cancel_callback = nullptr,
                             .cancel_user_data = nullptr,
                             .vita49_telemetry_callback = nullptr,
                             .vita49_telemetry_user_data = nullptr,
                             .function_name = "fers_run_simulation",
                             .invalid_context_message = "Invalid context provided to fers_run_simulation."});
}

fers_run_simulation_ex()

int fers_run_simulation_ex	(	fers_context_t *	context,
		fers_progress_callback_t	progress_callback,
		void *	progress_user_data,
		fers_cancel_callback_t	cancel_callback,
		void *	cancel_user_data,
		fers_vita49_telemetry_callback_t	vita49_telemetry_callback,
		void *	vita49_telemetry_user_data
	)

Runs the simulation with optional progress, cancellation, and VITA telemetry callbacks.

Return values match fers_run_simulation, except 2 means the run was cooperatively cancelled after output finalization and metadata collection.

Parameters

context	A valid fers_context_t handle containing a loaded scenario.
progress_callback	Optional progress callback. Can be NULL.
progress_user_data	Opaque pointer passed to the progress callback.
cancel_callback	Optional cancellation callback. Can be NULL.
cancel_user_data	Opaque pointer passed to the cancellation callback.
vita49_telemetry_callback	Optional VITA live telemetry callback. Can be NULL.
vita49_telemetry_user_data	Opaque pointer passed to the VITA telemetry callback.

Returns

0 on success, 2 on cancellation, a non-zero error code on failure.

Definition at line 1226 of file api.cpp.

{
    return run_simulation_common(
        SimulationRunRequest{.context = context,
                             .progress_callback = progress_callback,
                             .progress_user_data = progress_user_data,
                             .cancel_callback = cancel_callback,
                             .cancel_user_data = cancel_user_data,
                             .vita49_telemetry_callback = vita49_telemetry_callback,
                             .vita49_telemetry_user_data = vita49_telemetry_user_data,
                             .function_name = "fers_run_simulation_ex",
                             .invalid_context_message = "Invalid context provided to fers_run_simulation_ex."});
}

fers_set_log_callback()

void fers_set_log_callback	(	fers_log_callback_t	callback,
		void *	user_data
	)

Registers a callback for formatted log lines.

Pass NULL as callback to disable log callbacks.

Definition at line 382 of file api.cpp.

{
    {
        std::scoped_lock const lock(log_callback_mutex);
        log_callback = callback;
        log_callback_user_data = user_data;
    }
 
    logging::logger.setCallback(callback == nullptr ? nullptr : forward_log_callback, nullptr);
}

References logging::logger, and logging::Logger::setCallback().

Here is the call graph for this function:

fers_set_output_directory()

int fers_set_output_directory	(	fers_context_t *	context,
		const char *	out_dir
	)

Sets the output directory for simulation results.

Parameters

context	A valid fers_context_t handle.
out_dir	A null-terminated UTF-8 string for the output directory path.

Returns

0 on success, non-zero on error.

Definition at line 420 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (out_dir == nullptr))
    {
        set_api_error("Invalid arguments: context or out_dir is NULL.");
        return -1;
    }
    auto* ctx = context;
    try
    {
        ctx->setOutputDir(out_dir);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_output_directory");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and FersContext::setOutputDir().

Here is the call graph for this function:

fers_set_thread_count()

int fers_set_thread_count

(

unsigned

num_threads

)

Sets the number of worker threads for the simulation.

Parameters

num_threads

The number of threads to use.

Returns

0 on success, non-zero on error. This function clears any previous thread-local error message at entry, like the other fallible API calls.

Definition at line 401 of file api.cpp.

{
    last_error_message.clear();
    try
    {
        if (auto res = params::setThreads(num_threads); !res)
        {
            last_error_message = res.error();
            return 1;
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_set_thread_count");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and params::setThreads().

Here is the call graph for this function:

fers_set_vita49_epoch_unix_nanoseconds()

int fers_set_vita49_epoch_unix_nanoseconds	(	fers_context_t *	context,
		const std::uint64_t	epoch_unix_nanoseconds
	)

Definition at line 527 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
    if (!is_valid_vita49_epoch(epoch_unix_nanoseconds))
    {
        set_api_error("Invalid VITA49 epoch: value must fit the VRT 32-bit UTC seconds timestamp field.");
        return 1;
    }
 
    auto* ctx = context;
    core::OutputConfig config = ctx->getOutputConfig();
    config.vita49.epoch_unix_nanoseconds = epoch_unix_nanoseconds;
    ctx->setOutputConfig(std::move(config));
    return 0;
}

References core::Vita49OutputConfig::epoch_unix_nanoseconds, last_error_message, and core::OutputConfig::vita49.

fers_set_vita49_fullscale()

int fers_set_vita49_fullscale	(	fers_context_t *	context,
		double	fullscale
	)

Sets the fixed ADC full-scale value used by the FERS VITA 49.2 int16 IQ profile.

VITA mode requires a positive finite full-scale before simulation starts. HDF5 output keeps its existing full-buffer scaling behavior.

Parameters

context	A valid fers_context_t handle.
fullscale	Positive finite full-scale value.

Returns

0 on success, non-zero on error.

Definition at line 506 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
    if (!is_valid_vita49_fullscale(fullscale))
    {
        set_api_error("Invalid VITA49 fullscale: value must be positive and finite.");
        return 1;
    }
 
    auto* ctx = context;
    core::OutputConfig config = ctx->getOutputConfig();
    config.vita49.adc_fullscale = static_cast<RealType>(fullscale);
    ctx->setOutputConfig(std::move(config));
    return 0;
}

References core::Vita49OutputConfig::adc_fullscale, last_error_message, and core::OutputConfig::vita49.

fers_set_vita49_max_udp_payload()

int fers_set_vita49_max_udp_payload	(	fers_context_t *	context,
		const std::uint16_t	max_udp_payload
	)

Definition at line 548 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
    if (!is_valid_vita49_max_payload(max_udp_payload))
    {
        set_api_error("Invalid VITA49 max UDP payload: value must be between 64 and 65507 bytes.");
        return 1;
    }
 
    auto* ctx = context;
    core::OutputConfig config = ctx->getOutputConfig();
    config.vita49.max_udp_payload = max_udp_payload;
    ctx->setOutputConfig(std::move(config));
    return 0;
}

References last_error_message, core::Vita49OutputConfig::max_udp_payload, and core::OutputConfig::vita49.

fers_set_vita49_packet_trace_enabled()

int fers_set_vita49_packet_trace_enabled	(	fers_context_t *	context,
		int	enabled
	)

Enables or disables FERS VITA 49.2 packet trace telemetry.

Stream counter telemetry is unaffected. Disabling packet trace telemetry avoids per-packet diagnostic record creation for UI runs that only need live counters.

Parameters

context	A valid fers_context_t handle.
enabled	Non-zero to enable packet trace telemetry, zero to disable it.

Returns

0 on success, non-zero on error.

Definition at line 590 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
 
    auto* ctx = context;
    core::OutputConfig config = ctx->getOutputConfig();
    config.vita49.packet_trace_enabled = enabled != 0;
    ctx->setOutputConfig(std::move(config));
    return 0;
}

References last_error_message, core::Vita49OutputConfig::packet_trace_enabled, and core::OutputConfig::vita49.

fers_set_vita49_queue_depth()

int fers_set_vita49_queue_depth	(	fers_context_t *	context,
		const std::uint32_t	queue_depth
	)

Definition at line 569 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
    if (queue_depth == 0)
    {
        set_api_error("Invalid VITA49 queue depth: value must be greater than zero.");
        return 1;
    }
 
    auto* ctx = context;
    core::OutputConfig config = ctx->getOutputConfig();
    config.vita49.queue_depth = queue_depth;
    ctx->setOutputConfig(std::move(config));
    return 0;
}

References last_error_message, core::Vita49OutputConfig::queue_depth, and core::OutputConfig::vita49.

fers_update_antenna_from_json()

int fers_update_antenna_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single antenna from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the antenna.

Returns

0 on success, non-zero on failure.

Definition at line 868 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto j = nlohmann::json::parse(json);
        auto id = j.at("id").is_string() ? std::stoull(j.at("id").get<std::string>()) : j.at("id").get<uint64_t>();
        auto* ant = ctx->getWorld()->findAntenna(id);
        if (ant == nullptr)
        {
            last_error_message = "Antenna not found";
            return 1;
        }
        serial::update_antenna_from_json(j, ant, *ctx->getWorld());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_antenna_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_antenna_from_json().

Here is the call graph for this function:

fers_update_monostatic_from_json()

int fers_update_monostatic_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a monostatic radar from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the monostatic component.

Returns

0 on success, non-zero on failure.

Definition at line 992 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto j = nlohmann::json::parse(json);
        uint64_t const tx_id =
            j.at("tx_id").is_string() ? std::stoull(j.at("tx_id").get<std::string>()) : j.at("tx_id").get<uint64_t>();
        uint64_t const rx_id =
            j.at("rx_id").is_string() ? std::stoull(j.at("rx_id").get<std::string>()) : j.at("rx_id").get<uint64_t>();
        auto* tx = ctx->getWorld()->findTransmitter(tx_id);
        auto* rx = ctx->getWorld()->findReceiver(rx_id);
        if ((tx == nullptr) || (rx == nullptr))
        {
            last_error_message = "Monostatic components not found";
            return 1;
        }
        serial::update_monostatic_from_json(j, tx, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_monostatic_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_monostatic_from_json().

Here is the call graph for this function:

fers_update_parameters_from_json()

int fers_update_parameters_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates the global simulation parameters from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the parameters.

Returns

0 on success, non-zero on failure.

Definition at line 843 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = context;
    try
    {
        auto j = nlohmann::json::parse(json);
        serial::update_parameters_from_json(j, ctx->getMasterSeeder());
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_parameters_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), handle_api_exception(), last_error_message, and serial::update_parameters_from_json().

Here is the call graph for this function:

fers_update_platform_from_json()

int fers_update_platform_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single platform's paths and name from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the platform.
json	The JSON string for the platform.

Returns

0 on success, non-zero on failure.

Definition at line 807 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (json == nullptr))
    {
        discard_warning_capture();
        return -1;
    }
    auto* ctx = context;
    try
    {
        auto* p = ctx->getWorld()->findPlatform(id);
        if (p == nullptr)
        {
            last_error_message = "Platform not found";
            discard_warning_capture();
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_platform_paths_from_json(j, p);
        if (j.contains("name"))
        {
            p->setName(j.at("name").get<std::string>());
        }
        complete_warning_capture();
        return 0;
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_platform_from_json");
        return 1;
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), core::World::findPlatform(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_platform_paths_from_json().

Here is the call graph for this function:

fers_update_receiver_from_json()

int fers_update_receiver_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single receiver from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the receiver.
json	The JSON string for the receiver.

Returns

0 on success, non-zero on failure.

Definition at line 942 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto* rx = ctx->getWorld()->findReceiver(id);
        if (rx == nullptr)
        {
            last_error_message = "Receiver not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_receiver_from_json(j, rx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_receiver_from_json");
        return 1;
    }
}

References core::World::findReceiver(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_receiver_from_json().

Here is the call graph for this function:

fers_update_scenario_from_json()

int fers_update_scenario_from_json	(	fers_context_t *	context,
		const char *	scenario_json
	)

Updates the simulation scenario from a JSON string.

This is the primary method for the UI to push its state back to the C++ core. It performs a full replacement of the existing scenario.

Parameters

context	A valid fers_context_t handle.
scenario_json	A null-terminated UTF-8 string containing the FERS scenario in JSON format.

Returns

0 on success. 1 on generic logic error. 2 on JSON parsing/schema validation error. Use fers_get_last_error_message() to retrieve error details.

Definition at line 1046 of file api.cpp.

{
    last_error_message.clear();
    begin_warning_capture();
    if ((context == nullptr) || (scenario_json == nullptr))
    {
        last_error_message = "Invalid arguments: context or scenario_json is NULL.";
        LOG(logging::Level::ERROR, last_error_message);
        discard_warning_capture();
        return -1;
    }
 
    auto* ctx = context;
    try
    {
        const nlohmann::json j = nlohmann::json::parse(scenario_json);
        serial::json_to_world(j, *ctx->getWorld(), ctx->getMasterSeeder());
        complete_warning_capture();
 
        return 0; // Success
    }
    catch (const nlohmann::json::exception& e)
    {
        // A specific catch block for JSON errors is used to provide more
        // detailed feedback to the client (e.g., the UI), which can help
        // developers diagnose schema or data format issues more easily.
        last_error_message = "JSON parsing/deserialization error: " + std::string(e.what());
        LOG(logging::Level::ERROR, "API Error in {}: {}", "fers_update_scenario_from_json", last_error_message);
        discard_warning_capture();
        return 2; // JSON error
    }
    catch (const std::exception& e)
    {
        discard_warning_capture();
        handle_api_exception(e, "fers_update_scenario_from_json");
        return 1; // Generic error
    }
}

References begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), logging::ERROR, handle_api_exception(), serial::json_to_world(), last_error_message, and LOG.

Here is the call graph for this function:

fers_update_target_from_json()

int fers_update_target_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single target from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the target.
json	The JSON string for the target.

Returns

0 on success, non-zero on failure.

Definition at line 967 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto* tgt = ctx->getWorld()->findTarget(id);
        if (tgt == nullptr)
        {
            last_error_message = "Target not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_target_from_json(j, tgt, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_target_from_json");
        return 1;
    }
}

References core::World::findTarget(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_target_from_json().

Here is the call graph for this function:

fers_update_timing_from_json()

int fers_update_timing_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single timing source from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the timing source.
json	The JSON string for the timing source.

Returns

0 on success, non-zero on failure.

Definition at line 1022 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        if (ctx->getWorld()->findTiming(id) == nullptr)
        {
            last_error_message = "Timing not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_timing_from_json(j, *ctx->getWorld(), id);
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_timing_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::update_timing_from_json().

Here is the call graph for this function:

fers_update_transmitter_from_json()

int fers_update_transmitter_from_json	(	fers_context_t *	context,
		uint64_t	id,
		const char *	json
	)

Updates a single transmitter from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
id	The unique ID of the transmitter.
json	The JSON string for the transmitter.

Returns

0 on success, non-zero on failure.

Definition at line 917 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto* tx = ctx->getWorld()->findTransmitter(id);
        if (tx == nullptr)
        {
            last_error_message = "Transmitter not found";
            return 1;
        }
        auto j = nlohmann::json::parse(json);
        serial::update_transmitter_from_json(j, tx, *ctx->getWorld(), ctx->getMasterSeeder());
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_transmitter_from_json");
        return 1;
    }
}

References core::World::findTransmitter(), FersContext::getWorld(), handle_api_exception(), last_error_message, and serial::update_transmitter_from_json().

Here is the call graph for this function:

fers_update_waveform_from_json()

int fers_update_waveform_from_json	(	fers_context_t *	context,
		const char *	json
	)

Updates a single waveform from JSON without full context recreation.

Parameters

context	A valid fers_context_t handle.
json	The JSON string for the waveform.

Returns

0 on success, non-zero on failure.

Definition at line 894 of file api.cpp.

{
    last_error_message.clear();
    if ((context == nullptr) || (json == nullptr))
        return -1;
    auto* ctx = context;
    try
    {
        auto j = nlohmann::json::parse(json);
        auto wf = serial::parse_waveform_from_json(j);
        if (wf)
        {
            ctx->getWorld()->replace(std::move(wf));
        }
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_update_waveform_from_json");
        return 1;
    }
}

References handle_api_exception(), last_error_message, and serial::parse_waveform_from_json().

Here is the call graph for this function:

fers_use_hdf5_output()

int fers_use_hdf5_output

(

fers_context_t *

context

)

Resets the context output mode to the default HDF5 output.

Runtime-only VITA 49.2 endpoint settings are retained for later VITA runs, but the selected output mode is changed back to HDF5.

Parameters

context

A valid fers_context_t handle.

Returns

0 on success, non-zero on error.

Definition at line 441 of file api.cpp.

{
    last_error_message.clear();
    if (context == nullptr)
    {
        set_api_error("Invalid arguments: context is NULL.");
        return -1;
    }
 
    auto* ctx = context;
    try
    {
        core::OutputConfig config = ctx->getOutputConfig();
        config.mode = core::OutputMode::Hdf5;
        ctx->setOutputConfig(std::move(config));
        return 0;
    }
    catch (const std::exception& e)
    {
        handle_api_exception(e, "fers_use_hdf5_output");
        return 1;
    }
}

References handle_api_exception(), core::Hdf5, last_error_message, and core::OutputConfig::mode.

Here is the call graph for this function:

handle_api_exception()

static void handle_api_exception ( const std::exception &  e, const std::string &  function_name  )

static

Centralized exception handler for the C-API boundary.

This function catches standard C++ exceptions, records their what() message into the thread-local error storage, and logs the error. This prevents C++ exceptions from propagating across the FFI boundary, which would be undefined behavior.

Parameters

e	The exception that was caught.
function_name	The name of the API function where the error occurred.

Definition at line 72 of file api.cpp.

{
    last_error_message = e.what();
    LOG(logging::Level::ERROR, "API Error in {}: {}", function_name, last_error_message);
}

References logging::ERROR, last_error_message, and LOG.

Referenced by fers_calculate_preview_links(), fers_configure_logging(), fers_context_create(), fers_enable_vita49_udp_output(), fers_generate_kml(), fers_get_antenna_pattern(), fers_get_interpolated_motion_path(), fers_get_interpolated_rotation_path(), fers_get_last_output_metadata_json(), fers_get_memory_projection_json(), fers_get_scenario_as_json(), fers_get_scenario_as_xml(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_set_output_directory(), fers_set_thread_count(), fers_update_antenna_from_json(), fers_update_monostatic_from_json(), fers_update_parameters_from_json(), fers_update_platform_from_json(), fers_update_receiver_from_json(), fers_update_scenario_from_json(), fers_update_target_from_json(), fers_update_timing_from_json(), fers_update_transmitter_from_json(), fers_update_waveform_from_json(), and fers_use_hdf5_output().

Here is the caller graph for this function:

map_api_log_level()

static logging::Level map_api_log_level ( fers_log_level_t  level )

static

Definition at line 129 of file api.cpp.

{
    switch (level)
    {
    case FERS_LOG_TRACE:
        return logging::Level::TRACE;
    case FERS_LOG_DEBUG:
        return logging::Level::DEBUG;
    case FERS_LOG_INFO:
        return logging::Level::INFO;
    case FERS_LOG_WARNING:
        return logging::Level::WARNING;
    case FERS_LOG_ERROR:
        return logging::Level::ERROR;
    case FERS_LOG_FATAL:
        return logging::Level::FATAL;
    case FERS_LOG_OFF:
        return logging::Level::OFF;
    default:
        return logging::Level::INFO;
    }
}

References logging::DEBUG, logging::ERROR, logging::FATAL, FERS_LOG_DEBUG, FERS_LOG_ERROR, FERS_LOG_FATAL, FERS_LOG_INFO, FERS_LOG_OFF, FERS_LOG_TRACE, FERS_LOG_WARNING, logging::INFO, logging::OFF, logging::TRACE, and logging::WARNING.

Referenced by fers_configure_logging(), and fers_log().

Here is the caller graph for this function:

map_internal_log_level()

static fers_log_level_t map_internal_log_level ( logging::Level  level )

static

Definition at line 152 of file api.cpp.

{
    switch (level)
    {
    case logging::Level::TRACE:
        return FERS_LOG_TRACE;
    case logging::Level::DEBUG:
        return FERS_LOG_DEBUG;
    case logging::Level::INFO:
        return FERS_LOG_INFO;
    case logging::Level::WARNING:
        return FERS_LOG_WARNING;
    case logging::Level::ERROR:
        return FERS_LOG_ERROR;
    case logging::Level::FATAL:
        return FERS_LOG_FATAL;
    case logging::Level::OFF:
        return FERS_LOG_OFF;
    default:
        return FERS_LOG_INFO;
    }
}

References logging::DEBUG, logging::ERROR, logging::FATAL, FERS_LOG_DEBUG, FERS_LOG_ERROR, FERS_LOG_FATAL, FERS_LOG_INFO, FERS_LOG_OFF, FERS_LOG_TRACE, FERS_LOG_WARNING, logging::INFO, logging::OFF, logging::TRACE, and logging::WARNING.

Referenced by fers_get_log_level().

Here is the caller graph for this function:

to_cpp_interp_type()

math::Path::InterpType to_cpp_interp_type

(

const fers_interp_type_t

type

)

Definition at line 1274 of file api.cpp.

{
    switch (type)
    {
    case FERS_INTERP_LINEAR:
        return math::Path::InterpType::INTERP_LINEAR;
    case FERS_INTERP_CUBIC:
        return math::Path::InterpType::INTERP_CUBIC;
    case FERS_INTERP_STATIC:
    default:
        return math::Path::InterpType::INTERP_STATIC;
    }
}

References FERS_INTERP_CUBIC, FERS_INTERP_LINEAR, FERS_INTERP_STATIC, math::Path::INTERP_CUBIC, math::Path::INTERP_LINEAR, and math::Path::INTERP_STATIC.

Referenced by fers_get_interpolated_motion_path().

Here is the caller graph for this function:

to_cpp_rot_interp_type()

math::RotationPath::InterpType to_cpp_rot_interp_type

(

const fers_interp_type_t

type

)

Definition at line 1288 of file api.cpp.

{
    switch (type)
    {
    case FERS_INTERP_LINEAR:
        return math::RotationPath::InterpType::INTERP_LINEAR;
    case FERS_INTERP_CUBIC:
        return math::RotationPath::InterpType::INTERP_CUBIC;
    case FERS_INTERP_STATIC:
    default:
        return math::RotationPath::InterpType::INTERP_STATIC;
    }
}

References FERS_INTERP_CUBIC, FERS_INTERP_LINEAR, FERS_INTERP_STATIC, math::RotationPath::INTERP_CUBIC, math::RotationPath::INTERP_LINEAR, and math::RotationPath::INTERP_STATIC.

Referenced by fers_get_interpolated_rotation_path().

Here is the caller graph for this function:

Variable Documentation

last_error_message

thread_local std::string last_error_message

Definition at line 60 of file api.cpp.

Referenced by fers_calculate_preview_links(), fers_configure_logging(), fers_context_create(), fers_enable_vita49_udp_output(), fers_generate_kml(), fers_get_antenna_pattern(), fers_get_interpolated_motion_path(), fers_get_interpolated_rotation_path(), fers_get_last_error_message(), fers_get_last_output_metadata_json(), fers_get_memory_projection_json(), fers_get_scenario_as_json(), fers_get_scenario_as_xml(), fers_load_scenario_from_xml_file(), fers_load_scenario_from_xml_string(), fers_set_output_directory(), fers_set_thread_count(), fers_set_vita49_epoch_unix_nanoseconds(), fers_set_vita49_fullscale(), fers_set_vita49_max_udp_payload(), fers_set_vita49_packet_trace_enabled(), fers_set_vita49_queue_depth(), fers_update_antenna_from_json(), fers_update_monostatic_from_json(), fers_update_parameters_from_json(), fers_update_platform_from_json(), fers_update_receiver_from_json(), fers_update_scenario_from_json(), fers_update_target_from_json(), fers_update_timing_from_json(), fers_update_transmitter_from_json(), fers_update_waveform_from_json(), fers_use_hdf5_output(), and handle_api_exception().

last_warning_messages

thread_local std::vector<std::string> last_warning_messages

Definition at line 61 of file api.cpp.

Referenced by begin_warning_capture(), complete_warning_capture(), discard_warning_capture(), fers_get_interpolated_rotation_path(), and fers_get_last_warning_messages_json().