From 8d8e1f108b57fcba915fe35af96bb06d67b206d6 Mon Sep 17 00:00:00 2001 From: Zhengyu Peng Date: Mon, 16 Dec 2024 08:00:33 -0500 Subject: [PATCH] docstring --- gen_docs/tools.rst | 2 +- src/radarsimpy/radar.py | 28 ++++++++-------- src/radarsimpy/receiver.py | 24 +++++++------- src/radarsimpy/simulator_lidar.pyx | 26 +++++++-------- src/radarsimpy/simulator_radar.pyx | 28 ++++++++-------- src/radarsimpy/simulator_rcs.pyx | 52 +++++++++++++++--------------- src/radarsimpy/transmitter.py | 30 ++++++++--------- 7 files changed, 95 insertions(+), 95 deletions(-) diff --git a/gen_docs/tools.rst b/gen_docs/tools.rst index 2c37e82..511e91e 100644 --- a/gen_docs/tools.rst +++ b/gen_docs/tools.rst @@ -6,4 +6,4 @@ Tools :undoc-members: :inherited-members: :show-inheritance: - :exclude-members: log_factorial, threshold, marcumq + :exclude-members: log_factorial, threshold, marcumq, pd_swerling0, pd_swerling1, pd_swerling2, pd_swerling3, pd_swerling4 diff --git a/src/radarsimpy/radar.py b/src/radarsimpy/radar.py index b30e9c4..aa13734 100644 --- a/src/radarsimpy/radar.py +++ b/src/radarsimpy/radar.py @@ -266,23 +266,23 @@ class Radar: :param Transmitter transmitter: The radar transmitter instance. :param Receiver receiver: The radar receiver instance. :param list location: - The 3D location of the radar relative to a global coordinate system [x, y, z] in meters (m). - Default: ``[0, 0, 0]``. + The 3D location of the radar relative to a global coordinate system [x, y, z] in meters (m). + Default: ``[0, 0, 0]``. :param list speed: - The velocity of the radar in meters per second (m/s), specified as [vx, vy, vz]. - Default: ``[0, 0, 0]``. + The velocity of the radar in meters per second (m/s), specified as [vx, vy, vz]. + Default: ``[0, 0, 0]``. :param list rotation: - The radar's orientation in degrees (°), specified as [yaw, pitch, roll]. - Default: ``[0, 0, 0]``. + The radar's orientation in degrees (°), specified as [yaw, pitch, roll]. + Default: ``[0, 0, 0]``. :param list rotation_rate: - The radar's angular velocity in degrees per second (°/s), - specified as [yaw rate, pitch rate, roll rate]. - Default: ``[0, 0, 0]``. + The radar's angular velocity in degrees per second (°/s), + specified as [yaw rate, pitch rate, roll rate]. + Default: ``[0, 0, 0]``. :param int seed: - Seed for the random noise generator to ensure reproducibility. + Seed for the random noise generator to ensure reproducibility. :ivar dict time_prop: - Time-related properties of the radar system: + Time-related properties of the radar system: - **timestamp_shape** (*tuple*): The shape of the timestamp array. - **timestamp** (*numpy.ndarray*): The timestamp for each sample in a frame, @@ -298,21 +298,21 @@ class Radar: - [MN-1, :, :]: ``Tx[M-1] → Rx[N-1]`` :ivar dict sample_prop: - Sample-related properties: + Sample-related properties: - **samples_per_pulse** (*int*): Number of samples in a single pulse. - **noise** (*float*): Noise amplitude. - **phase_noise** (*numpy.ndarray*): Phase noise matrix for pulse samples. :ivar dict array_prop: - Metadata related to the radar's virtual array: + Metadata related to the radar's virtual array: - **size** (*int*): Total number of virtual array elements. - **virtual_array** (*numpy.ndarray*): 3D locations of each virtual array element, structured as ``[channel_size, 3]`` where each row corresponds to an [x, y, z] position. :ivar dict radar_prop: - Radar system properties: + Radar system properties: - **transmitter** (*Transmitter*): Instance of the radar transmitter. - **receiver** (*Receiver*): Instance of the radar receiver. diff --git a/src/radarsimpy/receiver.py b/src/radarsimpy/receiver.py index 569fd9f..af2e478 100644 --- a/src/radarsimpy/receiver.py +++ b/src/radarsimpy/receiver.py @@ -35,21 +35,21 @@ class Receiver: along with the characteristics of its receiver channels. :param float fs: - Sampling rate in samples per second (sps). + Sampling rate in samples per second (sps). :param float noise_figure: - Noise figure of the receiver in decibels (dB). + Noise figure of the receiver in decibels (dB). :param float rf_gain: - Total RF gain of the receiver in decibels (dB). + Total RF gain of the receiver in decibels (dB). :param float load_resistor: - Load resistance to convert power to voltage, in ohms (Ω). + Load resistance to convert power to voltage, in ohms (Ω). :param float baseband_gain: - Total baseband gain in decibels (dB). + Total baseband gain in decibels (dB). :param str bb_type: - Baseband data type, either ``complex`` or ``real``. - Defaults to ``complex``. + Baseband data type, either ``complex`` or ``real``. + Defaults to ``complex``. :param list[dict] channels: - A list of dictionaries defining the properties of receiver channels, - where each dictionary contains the following keys: + A list of dictionaries defining the properties of receiver channels, + where each dictionary contains the following keys: - **location** (*numpy.ndarray*): 3D location of the channel relative to the radar's position [x, y, z] in meters. @@ -77,13 +77,13 @@ class Receiver: Defaults to ``[0, 0]``. :ivar dict rf_prop: - RF properties of the receiver: + RF properties of the receiver: - **rf_gain** (*float*): RF gain in decibels (dB). - **noise_figure** (*float*): Noise figure in decibels (dB). :ivar dict bb_prop: - Baseband properties of the receiver: + Baseband properties of the receiver: - **fs** (*float*): Sampling rate in samples per second (sps). - **load_resistor** (*float*): Load resistance in ohms (Ω). @@ -91,7 +91,7 @@ class Receiver: - **bb_type** (*str*): Baseband data type, either ``real`` or ``complex``. :ivar dict rxchannel_prop: - Properties of the receiver channels: + Properties of the receiver channels: - **size** (*int*): Number of receiver channels. - **locations** (*numpy.ndarray*): diff --git a/src/radarsimpy/simulator_lidar.pyx b/src/radarsimpy/simulator_lidar.pyx index 2cdf6b2..1fa10ca 100644 --- a/src/radarsimpy/simulator_lidar.pyx +++ b/src/radarsimpy/simulator_lidar.pyx @@ -50,44 +50,44 @@ cpdef sim_lidar(lidar, targets, frame_time=0): This function simulates a Lidar scanning scene in a 3D environment, calculating the interaction of Lidar rays with the provided targets. It handles both static and dynamic targets, allowing for customizable positions, velocities, and orientations of objects in the scene. The simulation produces a set of rays representing the Lidar's perception of the environment. :param dict lidar: - Lidar configuration parameters. The following keys are required: + Lidar configuration parameters. The following keys are required: - - **position** (*numpy.1darray*): + - **position** (*numpy.ndarray*): The 3D position of the Lidar in meters (m), specified as [x, y, z]. - - **phi** (*numpy.1darray*): + - **phi** (*numpy.ndarray*): Array of phi scanning angles in degrees (°). Phi represents the horizontal scanning angles in the Lidar's field of view. The total number of scanning directions is determined by the combination of phi and theta angles. - - **theta** (*numpy.1darray*): + - **theta** (*numpy.ndarray*): Array of theta scanning angles in degrees (°). Theta represents the vertical scanning angles in the Lidar's field of view. The total number of scanning directions is computed as: ``len(phi) * len(theta)``. :param list[dict] targets: - A list of target objects in the scene. Each target is represented as a dictionary containing the following keys: + A list of target objects in the scene. Each target is represented as a dictionary containing the following keys: - **model** (*str*): File path to the target model (3D object) in the scene. - - **origin** (*numpy.1darray*, optional): + - **origin** (*numpy.ndarray*): The origin position of the target model in meters (m), specified as [x, y, z]. Default: ``[0, 0, 0]``. - - **location** (*numpy.1darray*, optional): + - **location** (*numpy.ndarray*): The 3D location of the target in meters (m), specified as [x, y, z]. Default: ``[0, 0, 0]``. - - **speed** (*numpy.1darray*, optional): + - **speed** (*numpy.ndarray*): Speed vector of the target in meters per second (m/s), specified as [vx, vy, vz]. Default: ``[0, 0, 0]``. - - **rotation** (*numpy.1darray*, optional): + - **rotation** (*numpy.ndarray*): The angular orientation of the target in degrees (°), specified as [yaw, pitch, roll]. Default: ``[0, 0, 0]``. - - **rotation_rate** (*numpy.1darray*, optional): + - **rotation_rate** (*numpy.ndarray*): The angular rotation rate of the target in degrees per second (°/s), specified as [yaw rate, pitch rate, roll rate]. Default: ``[0, 0, 0]``. - - **unit** (*str*, optional): + - **unit** (*str*): The unit system for the target model's geometry. Supported values: ``mm``, ``cm``, ``m``. Default: ``m``. :param float frame_time: - Simulation timestamp in seconds (s). This parameter determines the time reference for the Lidar's scanning operation and target positions. - Default: ``0``. + Simulation timestamp in seconds (s). This parameter determines the time reference for the Lidar's scanning operation and target positions. + Default: ``0``. :return: Simulated Lidar rays based on the provided configuration and targets. diff --git a/src/radarsimpy/simulator_radar.pyx b/src/radarsimpy/simulator_radar.pyx index 44f2fb1..dad6f16 100644 --- a/src/radarsimpy/simulator_radar.pyx +++ b/src/radarsimpy/simulator_radar.pyx @@ -67,9 +67,9 @@ cpdef sim_radar(radar, targets, frame_time=0, density=1, level=None, log_path=No This function generates the radar's baseband response using the provided radar configuration and target data. It supports both ideal point targets and 3D mesh objects, and allows for varying levels of fidelity in the simulation. Additional options include interference modeling, ray density specification, and logging of simulation data. :param Radar radar: - The radar object to be used for the simulation. + The radar object to be used for the simulation. :param list targets: - The list of targets in the scene. Targets can be either ideal point targets or 3D mesh objects. + The list of targets in the scene. Targets can be either ideal point targets or 3D mesh objects. - **3D Mesh Target**: A target represented as a 3D model. Each target is defined as a dictionary with the following keys: @@ -91,31 +91,31 @@ cpdef sim_radar(radar, targets, frame_time=0, density=1, level=None, log_path=No - **speed** (*numpy.ndarray*): Target velocity in meters per second [vx, vy, vz]. Default: ``[0, 0, 0]``. - **phase** (*float*): Target phase in degrees. Default: ``0``. - *Note*: Target parameters can be time-varying by using ``Radar.timestamp``. For example: - ``location = (1e-3 * np.sin(2 * np.pi * 1 * radar.timestamp), 0, 0)`` + *Note*: Target parameters can be time-varying by using ``Radar.timestamp``. For example: + ``location = (1e-3 * np.sin(2 * np.pi * 1 * radar.timestamp), 0, 0)`` :param float or list frame_time: - Radar firing times or frame instances, specified as a float or a list of time values. Default: ``0``. + Radar firing times or frame instances, specified as a float or a list of time values. Default: ``0``. :param float density: - Ray density, defined as the number of rays per wavelength. Default: ``1.0``. + Ray density, defined as the number of rays per wavelength. Default: ``1.0``. :param str or None level: - Fidelity level of the simulation. Default: ``None``. + Fidelity level of the simulation. Default: ``None``. - ``None``: Perform one ray-tracing simulation for the entire frame. - ``pulse``: Perform ray-tracing for each pulse. - ``sample``: Perform ray-tracing for each sample. :param str or None log_path: - Path to save ray-tracing data. Default: ``None`` (does not save data). + Path to save ray-tracing data. Default: ``None`` (does not save data). :param list or None ray_filter: - Filters rays based on the number of reflections. - Only rays with the number of reflections between ``ray_filter[0]`` - and ``ray_filter[1]`` are included in the calculations. - Default: ``None`` (no filtering). + Filters rays based on the number of reflections. + Only rays with the number of reflections between ``ray_filter[0]`` + and ``ray_filter[1]`` are included in the calculations. + Default: ``None`` (no filtering). :param bool debug: - Whether to enable debug mode. Default: ``False``. + Whether to enable debug mode. Default: ``False``. :param Radar or None interf: - Interference radar object. Default: ``None``. + Interference radar object. Default: ``None``. :return: A dictionary containing the simulated baseband response and related data: diff --git a/src/radarsimpy/simulator_rcs.pyx b/src/radarsimpy/simulator_rcs.pyx index b22c059..6e683c8 100644 --- a/src/radarsimpy/simulator_rcs.pyx +++ b/src/radarsimpy/simulator_rcs.pyx @@ -60,53 +60,53 @@ cpdef sim_rcs(targets, This function computes the RCS of one or more targets by simulating how electromagnetic waves interact with the target models. The simulation uses the SBR technique, which accurately models wave scattering by tracing rays that shoot at the target and bounce off its surfaces. :param list[dict] targets: - A list of target dictionaries specifying the properties of each target. Each dictionary contains the following keys: + A list of target dictionaries specifying the properties of each target. Each dictionary contains the following keys: - **model** (*str*): File path to the 3D target model. - - **origin** (*numpy.1darray*, optional): + - **origin** (*numpy.ndarray*): The origin position of the target model in meters (m), specified as [x, y, z]. Default: ``[0, 0, 0]``. - - **location** (*numpy.1darray*, optional): + - **location** (*numpy.ndarray*): The 3D location of the target in meters (m), specified as [x, y, z]. Default: ``[0, 0, 0]``. - - **rotation** (*numpy.1darray*, optional): + - **rotation** (*numpy.ndarray*): The target's orientation in degrees (°), specified as [yaw, pitch, roll]. Default: ``[0, 0, 0]``. - - **permittivity** (*complex*, optional): + - **permittivity** (*complex*): The target's permittivity, which represents its electromagnetic material properties. Default: Perfect Electric Conductor (PEC). - - **unit** (*str*, optional): + - **unit** (*str*): Unit of measurement for the target model's geometry. Supported values: ``mm``, ``cm``, ``m``. Default: ``m``. :param float f: - Center frequency of the incident wave in Hertz (Hz). + The center frequency of the incident electromagnetic wave in Hertz (Hz). :param float inc_phi: - Incidence angle (phi) in degrees (°). - This is the azimuth angle of the incoming wave relative to the target. + The horizontal incidence angle (phi) of the incoming wave in degrees (°). + This angle is measured relative to the target at the transmitter's point of view. :param float inc_theta: - Incidence angle (theta) in degrees (°). - This is the elevation angle of the incoming wave relative to the target. - :param list inc_pol: - Polarization of the incident wave, specified as a 3D vector [x, y, z]. - Default: ``[0, 0, 1]`` (vertical polarization). + The vertical incidence angle (theta) of the incoming wave in degrees (°). + This angle is measured relative to the target at the transmitter's point of view. + :param list[float] inc_pol: + The polarization of the incident wave, specified as a 3D vector [x, y, z]. + Default: ``[0, 0, 1]`` (vertical polarization). :param float obs_phi: - Observation angle (phi) in degrees (°). - This is the azimuth angle at which the RCS is observed. - Default: ``None`` (if not specified, it is set to the same value as `inc_phi`). + The horizontal observation angle (phi) in degrees (°). + This is the angle at which the RCS is observed from the observer's point of view. + Default: ``None`` (if not specified, it is set to the same value as `inc_phi`). :param float obs_theta: - Observation angle (theta) in degrees (°). - This is the elevation angle at which the RCS is observed. - Default: ``None`` (if not specified, it is set to the same value as `inc_theta`). - :param list obs_pol: - Polarization of the observer, specified as a 3D vector [x, y, z]. - Default: ``None`` (if not specified, it is set to the same value as `inc_pol`). + The vertical observation angle (theta) in degrees (°). + This is the angle at which the RCS is observed from the observer's point of view. + Default: ``None`` (if not specified, it is set to the same value as `inc_theta`). + :param list[float] obs_pol: + The polarization of the observer, specified as a 3D vector [x, y, z]. + Default: ``None`` (if not specified, it is set to the same value as `inc_pol`). :param float density: - Ray density, defined as the number of rays per wavelength. - Higher values improve accuracy but increase computational cost. - Default: ``1``. + The ray density, defined as the number of rays per wavelength. + Higher ray density improves accuracy but increases computational cost. + Default: ``1.0``. :return: The Radar Cross Section (RCS) of the target(s) in square meters (m²). diff --git a/src/radarsimpy/transmitter.py b/src/radarsimpy/transmitter.py index fb86164..1c43562 100644 --- a/src/radarsimpy/transmitter.py +++ b/src/radarsimpy/transmitter.py @@ -35,7 +35,7 @@ class Transmitter: and properties of the transmitter channels. :param f: Waveform frequency in Hertz (Hz). - The value can be: + The value can be: - A single number: For a single-tone waveform. - A list ``[f_start, f_stop]``: For linear frequency modulation. @@ -43,16 +43,16 @@ class Transmitter: :type f: float or numpy.ndarray :param t: - Timing of the pulse(s) in seconds (s). - Used when ``f`` is a 1D array to specify an arbitrary waveform. + Timing of the pulse(s) in seconds (s). + Used when ``f`` is a 1D array to specify an arbitrary waveform. :type t: float or numpy.ndarray :param float tx_power: - Transmitter power in decibels-milliwatts (dBm). + Transmitter power in decibels-milliwatts (dBm). :param int pulses: - Total number of pulses. + Total number of pulses. :param prp: - Pulse repetition period (PRP) in seconds (s). - Must satisfy ``prp >= pulse_length``. + Pulse repetition period (PRP) in seconds (s). + Must satisfy ``prp >= pulse_length``. - If ``prp`` is ``None``, it defaults to ``pulse_length``. - Can also be a 1D array to specify different PRPs for each pulse. @@ -60,14 +60,14 @@ class Transmitter: :type prp: float or numpy.ndarray :param numpy.ndarray f_offset: - Frequency offset for each pulse in Hertz (Hz). The length must match ``pulses``. + Frequency offset for each pulse in Hertz (Hz). The length must match ``pulses``. :param numpy.ndarray pn_f: - Frequencies associated with phase noise in Hertz (Hz). + Frequencies associated with phase noise in Hertz (Hz). :param numpy.ndarray pn_power: - Power of phase noise in dB/Hz. + Power of phase noise in dB/Hz. :param list[dict] channels: - Properties of transmitter channels. - Each channel is represented as a dictionary with the following keys: + Properties of transmitter channels. + Each channel is represented as a dictionary with the following keys: - **location** (*numpy.ndarray*): 3D location of the channel relative to the radar [x, y, z] in meters. @@ -104,14 +104,14 @@ class Transmitter: Default: ``None``. :ivar dict rf_prop: - RF properties of the transmitter: + RF properties of the transmitter: - **tx_power** (*float*): Transmitter power in dBm. - **pn_f** (*numpy.ndarray*): Frequencies associated with phase noise (Hz). - **pn_power** (*numpy.ndarray*): Power of phase noise (dB/Hz). :ivar dict waveform_prop: - Waveform properties: + Waveform properties: - **f** (*float or numpy.ndarray*): Waveform frequency (Hz). - **t** (*float or numpy.ndarray*): Timing of each pulse (s). @@ -123,7 +123,7 @@ class Transmitter: - **pulse_start_time** (*numpy.ndarray*): Start times of each pulse (s). :ivar dict txchannel_prop: - Properties of the transmitter channels: + Properties of the transmitter channels: - **size** (*int*): Number of transmitter channels. - **delay** (*numpy.ndarray*): Transmitter start delay (s).