mlcomm.channels
Adaptive Communication Decision and Information Systems (ACDIS) - User License https://bloch.ece.gatech.edu/researchgroup/
Copyright (c) 2024-2025 Georgia Institute of Technology
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. Users shall cite ACDIS publications regarding this work.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER INANACTION OF CONTRACT TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- class mlcomm.channels.AWGN(params)
Description
Additive White Gaussian Noise Channel
Attributes
- Mint
Number of elements in the array.
- anglefloat
Angle of arrival/departure in radians, converted from degrees. Main path.
- htnumpy ndarray of complex float
Channel response
- fluctuation(*args, **kwargs)
- class mlcomm.channels.BasicChannel(params)
A base class to represent a communication channel. Transmit power assumed to be unitary.
Attributes
- cb_graphobject
Type instance of BinaryHierarchicalCodebook or TrinaryPointedHierarchicalCodebook. See description of class types in mlcomm.codebooks.
- snrfloat
Signal-to-noise ratio.
- sigma_vfloat
Noise standard deviation, calculated from SNR.
- htnumpy array of complex float
Channel reponse placeholder
- seedint
Seed for random number generation.
Methods
- array_reponse
Generates the noisy channel response with respect to specified snr.
- class mlcomm.channels.Channel(params)
A base class to represent a communication channel. scenario dependent parameters dictate transmit power. Designate noise variance by the attribute sigma_v.
Attributes
- cb_graphobject
Type instance of BinaryHierarchicalCodebook or TrinaryPointedHierarchicalCodebook. See description of class types in mlcomm.codebooks.
- sigma_vfloat
Noise standard deviation.
- htnumpy array of complex float
Channel reponse placeholder
- seedint
Seed for random number generation.
Methods
- array_reponse
Generates the noisy channel response with respect to specified snr.
- array_response(transmit_power_dbm=0, with_noise=True)
- class mlcomm.channels.DynamicMotion(params)
DynamicMotion is a class to represent various parameters and computations for a communication channel with a uniform linear array (ULA) along the x-axis.
Attributes
- Mint
Number of elements in the array.
- sigma_ufloat
Standard deviation of the kinematic motion.
- initial_anglefloat
Initial angle in radians, converted from degrees.
- Lint
Number of signal paths.
- channel_modestr
Mode of the channel (‘WGNA’, ‘FixedV’, ‘GaussianJumps’).
- seedint
Seed for random number generation.
- anglesnp.ndarray
Array of angles for the signal paths.
- alphasnp.ndarray
Array of complex gains for the signal paths.
- x_knp.ndarray
State vector containing initial angle, angular velocity, and real/imaginary parts of the first path’s gain.
- htnp.ndarray
Array representing the sum of the channel responses for all paths.
- Fnp.ndarray
State transition matrix.
- Qunp.ndarray
Kinematic motion covariance matrix.
- Gnp.ndarray
Mode-dependent matrix used in the state transition.
- Qvnp.ndarray
Observation covariance matrix.
- rhofloat
Fading parameter.
- taufloat
Time step for state transitions.
Methods
- fluctuation(self):
Updates the channel state to simulate fluctuations in movement and fading.
Notes
Multi-path effects tend to take place around the maain path, we choose this value to be .35 radians (~20 degrees). More detail available in [2] - [1] Akdeniz, Mustafa Riza, et al. “Millimeter wave channel modeling and cellular capacity evaluation.” IEEE journal on selected areas in communications 32.6 (2014): 1164-1179. - [2] Rappaport, Theodore S., et al. “Millimeter wave mobile communications for 5G cellular: It will work!.” IEEE access 1 (2013): 335-349.
The attribute sigma_u is used as the initial angular velocity for the fixed velocity case and the WGNA case.
- class Path(params)
- class mlcomm.channels.NYU1(params)
Description
Channel model based on Table 1 in [1] for a uniform linear array (ULA) along the x-axis. For our purposes, we consider the outage probability to be zero. We maintain the same path angles along with the slow time fading stochastic value governed by sigma_dB. When initialized, a value is selected and held. We also assume zero Doppler.
[1] Akdeniz, Mustafa Riza, et al. “Millimeter wave channel modeling and cellular capacity evaluation.” IEEE journal on selected areas in communications 32.6 (2014): 1164-1179.
Attributes
- Mint
Number of elements in the array.
- anglefloat
Main path angle in degrees.
- environmentstr
Line-of-sight condition (‘LOS’ or ‘NLOS’).
- scenariostr
Scenario (‘Rural’ or ‘Urban’).
- center_frequency_ghzfloat
Center frequency in GHz (valid choices are 28 and 72).
- propagation_distancefloat
Propagation distance in meters.
- sigma_vfloat
Noise standard deviation.
- wavelengthfloat
Wavelength corresponding to the center frequency.
- alpha_dBfloat
Path loss coefficient in dB.
- betafloat
Path loss exponent.
- sigma_dBfloat
Standard deviation of shadow fading in dB.
- lamfloat
Mean number of clusters (Poisson distributed).
- r_taufloat
Decay factor for cluster powers.
- zetafloat
Shadow fading factor for clusters.
- cluster_path_rmsfloat
RMS of cluster path angles.
- num_paths_per_clusterint
Number of paths per cluster.
- slow_time_fade_factorfloat
Slow time fading factor.
- Kint
Number of clusters.
- gamma_plist
Cluster powers.
- gammanp.ndarray
Normalized cluster powers.
- cluster_anglesnp.ndarray
Cluster angles.
- cluster_path_angleslist
Path angles within each cluster.
- PL_dBfloat
Path loss in dB.
- htnp.ndarray
Channel impulse response.
- gsnp.ndarray
Scaling factors for the clusters.
Methods
- __init__(self, params)
Initializes the channel model with the given parameters.
Notes
We reorganize the paths such that the strongest path is always the first indexed path.
Our model has some minor additions from the paper, we incorporate the notion of ‘Rural’ and ‘Urban’ modes to distinguish between scenarios where there is either one dominant path with at most one cluster or the specified number of paths/clusters as denoted in [1].
We also make the assumption that the RF front end of the receiver has some type of automatic gain control (AGC) in which the received signal is normalized.
- fluctuation(*args)
- class mlcomm.channels.NYU2(params)
Description
Channel model based on the publications from NYU Wireless, many functions are derived directly from the NYU source code (https://wireless.engineering.nyu.edu/nyusim/)
[1] Introduces the model and how to construct it, [2] introduces NYU Sim, and [3] adds the spatial consistency effects on top of [1] into the utility in [2] with additional data/effects from [4,5].
Generates a grid for correlated spatial variables (encompassing both LOS and NLOS environments) that is of size 400 x 400 meters. The array is placed at the center of the 400 meters and is assumed at (x,y) = (0,0).
[1] Samimi, Mathew K., and Theodore S. Rappaport. “3-D millimeter-wave statistical channel model for 5G wireless system design.” IEEE Transactions on Microwave Theory and Techniques 64.7 (2016): 2207-2225.
[2] Sun, Shu, George R. MacCartney, and Theodore S. Rappaport. “A novel millimeter-wave channel simulator and applications for 5G wireless communications.” 2017 IEEE international conference on communications (ICC). IEEE, 2017.
[3] Ju, Shihao, and Theodore S. Rappaport. “Simulating motion-incorporating spatial consistency into NYUSIM channel model.” 2018 IEEE 88th vehicular technology conference (VTC-Fall). IEEE, 2018.
[4] S. Ju, O. Kanhere, Y. Xing and T. S. Rappaport, “A Millimeter-Wave Channel Simulator NYUSIM with Spatial Consistency and Human Blockage” in IEEE 2019 Global Communications Conference, pp. 1–7, Dec. 2019.
[5] S. Sun et al., “Investigation of Prediction Accuracy, Sensitivity, and Parameter Stability of Large-Scale Propagation Path Loss Models for 5G Wireless Communications,” in IEEE Transactions on Vehicular Technology, vol. 65, no. 5, pp. 2843-2860, May 2016.
The channel has granularity of squares 1x1 meter for characterizing channel fading effects in a 400mx400m grid. When the Mobile Entity (ME) translates from one grid square to another,
Many functions are directly translated from the NYU Sim MATLAB Source Code, including
get_los_map,get_sf_map,get_delay_info.Attributes
Methods
- set_environment
Sets the object instance environment variables, i.e., environment ‘LOS’, ‘NLOS’, with specified scenario according to the ME position triple passed to the method as an arg.
- fluctuation
Adjusts the channel based on ME motion, if the ME changes environment (i.e., ‘NLOS’ to ‘LOS’), the channel reinitializes path variables.
Notes
This implementation does not consider polarization, human blockage, or indoor-outdoor penetration loss factors
- class SpatiallyCoherentPosition(params)
Description
Used with the NYU2 channel class to organize the grid of spatially correlated values.
Parameters
params - dict
Notes
Careful with units, some parameters are derived in dB, but calculations are in mW.
- build_h()
- fluctuation(nn=0, min_max_angles=(0, 3.14159), tau=1, mode='normal')
Description
Channel fluctuation, the ME undergoes motion and the environment is checked to be changed (i.e., from LOS to NLOS). If so we reinitialize the angles in the respective way. The first angle in the ‘LOS’ environment is always the ME relative to the BS.
Parameters
- modestr
valid choices are ‘normal’ and ‘intialization’, defaults to ‘normal’. Set to ‘initialization’ in the __init__ method to get initial conditions for ME position.
- get_d_az_el(x, y, z)
Description
Translates x,y,z position into spherical coordinates relative to the origin
Parameters
- xfloat
Position in x-coordinate
- yfloat
Position in y-coordinate
- zfloat
Position in z-coordinate
Returns
- dfloat
Distance between origin and x,y,z
- azfloat
Azimuth angle
- elfloat
Elevation/Zenith angle
- get_delay_info(DelayList, nSP)
- get_grid_index(x, y, z)
Description
Returns index of grid position based on position coordinates (x,y,z). Used in cross-referencing position with SF map and LOS map.
Parameters
- xfloat
Position in x-coordinate
- yfloat
Position in y-coordinate
- zfloat
Position in z-coordinate
- get_los_map(area)
Generate the map of spatially correlated LOS/NLOS condition.
Parameters
- areaint
The size of the area (grid size).
Returns
- los_mapndarray
The map of spatially correlated LOS/NLOS condition.
- get_sf_map(area)
Obtain the map of spatially correlated shadow fading.
Parameters
- areaint
The size of the area (grid size).
Returns
- sf_mapndarray
The map of spatially correlated shadow fading.
- set_environment()
Description
Based on the current location of the ME, stored as attribute triple, ‘me_position’, the position is cross-referenced with being LOS or NLOS and then paramters corresponding to the particular environment are assigned to change the state of the channel.
The position is changed over time by calling the ‘update_me’ method, which applies a White Gaussian Accleration transition.
Parameters
Returns
None.
- class mlcomm.channels.NYU_preset(params)
Description
Preset channel responses with spatial consistency used in DBZ simulations. Generated from NYU Sim 4.0:
https://wireless.engineering.nyu.edu/nyusim/
Each scenario Rural Macro (‘RMa’), Urban Macro (‘UMa’), and Urban Micro (‘UMi’) has two profiles, ‘Linear’ and ‘Hexagon’, each with 100 different sets of 600 time “snapshots” or time steps by our nomenclature.
IMPORTANT: The folder ‘preset_nyu_sim’ must be in the same directory as channels.py. This >8GB folder with all preset channel conditions is available from the author at nblinn6@gatech.edu
Alternatively, the parameters for how we generated this are available in our work and may be generated by the user.
Parameters
- paramsdict
A dictionary of parameters used to initialize the channel.
- ‘profile’str
The profile to be used in the simulation. Valid options are ‘Linear’ and ‘Hexagon’.
- ‘scenario’str
The scenario to be used in the simulation. Valid options are ‘RMa’, ‘UMa’, and ‘UMi’.
- ‘num_elements’int
The number of elements in the MIMO array.
- ‘set_number’int
The specific set number within the profile and scenario to be used. Must be between 1 and 100.
Attributes
- Mint
Number of elements in the MIMO array.
- set_numberint
The selected set number within the chosen profile and scenario.
- profilestr
The selected profile (‘Linear’ or ‘Hexagon’).
- scenariostr
The selected scenario (‘RMa’, ‘UMa’, or ‘UMi’).
- Hslist of np.ndarray
A list of normalized channel matrices for each time snapshot.
- htnp.ndarray
The channel matrix at the current time step.
Methods
- channel_fluctuation(nn):
Updates the channel matrix to the nth time snapshot. If nn is out of bounds, prints an error message.
- class mlcomm.channels.RicianAR1(params)
Description
Class object governing and containing parameters for a RicianAR1 channel model for a uniform linear array (ULA) along the x-axis. Parameter scenarios are set as in [1] [2].
[1] Chiu, Sung-En, Nancy Ronquillo, and Tara Javidi. “Active learning and CSI acquisition for mmWave initial alignment.” IEEE Journal on Selected Areas in Communications 37.11 (2019): 2474-2489. [2] Blinn, Nathan, Jana Boerger, and Matthieu Bloch. “mmWave Beam Steering with Hierarchical Optimal Sampling for Unimodal Bandits.” ICC 2021-IEEE International Conference on Communications. IEEE, 2021.
Attributes
- Mint
Number of elements in the array.
- anglefloat
Angle of arrival/departure in radians, converted from degrees. Main path.
- mufloat
First fading parameter.
- Krfloat
Second fading parameter.
- gfloat
Correlation parameter.
- Lint
Number of signal paths.
- snrfloat
Signal-to-noise ratio.
- angles: numpy ndarray of floats
angle of arrival/departure of all L paths.
- alphasnumpy ndarray of complex float
Dynamically updated fading coefficients for each path.
- htnumpy ndarray of complex float
Channel response with fading
Methods
- channel_fluctuation(self):
Updates the channel state to simulate fluctuations in dynamic fading.
Notes
Multi-path effects tend to take place around the maain path, we choose this value to be .35 radians (~20 degrees). More detail available in
Rappaport, Theodore S., et al. “Millimeter wave mobile communications for 5G cellular: It will work!.” IEEE access 1 (2013): 335-349.
Akdeniz, Mustafa Riza, et al. “Millimeter wave channel modeling and cellular capacity evaluation.” IEEE journal on selected areas in communications 32.6 (2014): 1164-1179.
- fluctuation(nn, *args)