docstring

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

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.

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,21 +77,21 @@ 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 (Ω).
         - **baseband_gain** (*float*): Baseband gain in decibels (dB).
         - **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*):

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.

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:

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²).