Position Estimation

This package is used for estimating the location of a device using 5G Networks. 5G has standardized the positioning reference signal (PRS), methods and procedures to localize a node in either uplink or downlink based on power, angle or time/delay measurements as illustrated in table-1.

Table 38 Positioning in 5G Networks

Method

Measurements

positioningMethod

optimizationMethod

DL-TDoA

TDOA

TDOA

NewtonRaphson, GradientDescent

UL-TDoA

TDOA

TDOA

NewtonRaphson, GradientDescent

DL-AoD

RSRP, AoD

DOA

NewtonRaphson, GradientDescent

UL-AoA

RSRP, AoD, RToA

DOA

NewtonRaphson, GradientDescent

m-RTT

RSRP, RToA

TOA

LeastSquare

ECID

RSRP

Not supported

Not supported

Position Estimation

Code example: Position Estimation using Time of Arrival Estimates

posEstimator = Position_Estimation(positioningMethod = "TOA", optimizationMethod = "LeastSquare")
# Position Estimation Object:
    # Positioning based on: ToA
    # Optimization Method: Least Square
    # txPosition: (numTranmitter, 3)
    # ToAe: (numTranmitter, )

posEstimate, errorEstimate = posEstimator(refPosition=txPosition, toa=ToAe)

posEstimator.display()
Alternative text

Code example: Position Estimation using Time Difference of Arrival Estimates

numIterations = 10000
numEpochs     = 10
tolerance     = 0.00000001
stepsize      = 0.1
isd           = 100
posEstimator  = PositionEstimation(positioningMethod = "TDOA", optimizationMethod = "NewtonRaphson",
                                   numIterationPerEpoch = numIterations, numEpochs = numEpochs,
                                   tolerance = tolerance, stepsize = stepsize, isd = isd)
# Position Estimation Object:
    # Positioning based on: TDOA
    # Optimization Method: NewtonRaphson
    # txPosition: (numTranmitter, 3)
    # tdoaEst: (numTranmitter-1,)

posEstimate   = posEstimator(refPosition=txPosition, tdoa = tdoaEst)

Code example: Position Estimation using Direction of Arrival Estimates

numIterations = 10000
numEpochs     = 10
tolerance     = 0.00000001
stepsize      = 0.1
isd           = 100
posEstimator  = PositionEstimation(positioningMethod = "DOA", optimizationMethod = "GradientDescent",
                                   numIterationPerEpoch = numIterations, numEpochs = numEpochs,
                                   tolerance = tolerance, stepsize = stepsize, isd = isd)
# Position Estimation Object:
    # Positioning based on: DOA
    # Optimization Method: Gradient Descent
    # txPosition: (numTranmitter, 3)
    # doaEst: (numTranmitter, 2)

posEstimate   = posEstimator(refPosition=txPosition, doa = doaEst)

API Documentation

The following section provides the details about the input and output interface for Position Estimator.

class toolkit5G.Positioning.PositionEstimation(positioningMethod='TOA', optimizationMethod='LeastSquare', numIterationPerEpoch=10000, numEpochs=10, tolerance=1e-06, stepsize=0.1, isd=100)[source]

This module provides a high level API to estimate the location of node/device based on the delay or time of arrival (ToA), time difference of arrival (TDoA) estimates.

Parameters:

  • positioningMethod (str) – Defines the positioning measurement \(\{\)“TOA”, “TDOA”, “DOA” :math:’}’. The default value is “TOA”.

  • optimizationMethod (str) – Defines the method used for estimating the location of a node \(\in \{\)“LeastSquare”, “NewtonRaphson”, “GradientDescent” \(\}\). The default value is “LeastSquare”.

  • numIterationPerEpoch (int) – Number of iteration for gradient descent optimizations. Default value is 10000. \(\textcolor{blue}{\text{Only}}\) \(\textcolor{blue}{\text{relevant}}\) \(\textcolor{blue}{\text{when}}\) ‘\(\textcolor{blue}{\text{optimizationMethod}}\)’ \(\textcolor{blue}{\text{is}}\) ‘\(\textcolor{blue}{\text{NewtonRaphson}}\)’ \(\textcolor{blue}{\text{or}}\) ‘\(\textcolor{blue}{\text{GradientDescent}}\)’.

  • numEpochs (int) – Number of epoches used in gradient descent optimizations. Default value is 10. \(\textcolor{blue}{\text{Only}}\) \(\textcolor{blue}{\text{relevant}}\) \(\textcolor{blue}{\text{when}}\) ‘\(\textcolor{blue}{\text{optimizationMethod}}\)’ \(\textcolor{blue}{\text{is}}\) ‘\(\textcolor{blue}{\text{NewtonRaphson}}\)’ \(\textcolor{blue}{\text{or}}\) ‘\(\textcolor{blue}{\text{GradientDescent}}\)’.

  • tolerance (float) – Error tolerance values. The optimization stops when the optimization error reduces below tolerance value. \(\textcolor{blue}{\text{Only}}\) \(\textcolor{blue}{\text{relevant}}\) \(\textcolor{blue}{\text{when}}\) ‘\(\textcolor{blue}{\text{optimizationMethod}}\)’ \(\textcolor{blue}{\text{is}}\) ‘\(\textcolor{blue}{\text{NewtonRaphson}}\)’ \(\textcolor{blue}{\text{or}}\) ‘\(\textcolor{blue}{\text{GradientDescent}}\)’.

  • stepsize (float) – Optimization step size. The Newton Raphson algorithms iterates using this step-size to converge towards the global solutions. \(\textcolor{blue}{\text{Only}}\) \(\textcolor{blue}{\text{relevant}}\) \(\textcolor{blue}{\text{when}}\) ‘\(\textcolor{blue}{\text{optimizationMethod}}\)’ \(\textcolor{blue}{\text{is}}\) ‘\(\textcolor{blue}{\text{NewtonRaphson}}\)’ \(\textcolor{blue}{\text{or}}\) ‘\(\textcolor{blue}{\text{GradientDescent}}\)’.

  • isd (float) – Defines the intersite distance (m). Its equal to \(2 \times\) cell-size. \(\textcolor{blue}{\text{Only}}\) \(\textcolor{blue}{\text{relevant}}\) \(\textcolor{blue}{\text{when}}\) ‘\(\textcolor{blue}{\text{optimizationMethod}}\)’ \(\textcolor{blue}{\text{is}}\) ‘\(\textcolor{blue}{\text{NewtonRaphson}}\)’ \(\textcolor{blue}{\text{or}}\) ‘\(\textcolor{blue}{\text{GradientDescent}}\)’.

Input:

  • refPosition ((\(\text{N}_\text{ref}\),3), np.float) – Defines the location of the reference nodes used for positioning where \(\text{N}_\text{ref}\) defines the number of reference nodes.

  • toa ((\(\text{N}_\text{ref}\),), np.float) – Defines the time of arrival measurements used for positioning where \(\text{N}_\text{ref}\) defines the number of reference nodes. \(\textcolor{blue}{\text{Only relevant when 'positioningMethod' is 'TOA'}}\).

  • tdoa ((\(\text{N}_\text{ref}\)-1,), np.float) – Defines the time difference of arrival measurements used for positioning where \(\text{N}_\text{ref}\) defines the number of reference nodes. \(\textcolor{blue}{\text{Only relevant when 'positioningMethod' is 'TDOA'}}\)

  • doa ((\(\text{N}_\text{ref}\),2), np.float) – Defines the direction of arrival measurements used for positioning where \(\text{N}_\text{ref}\) defines the number of reference nodes. \(\textcolor{blue}{\text{Only relevant when 'positioningMethod' is 'DOA'}}\)

Output:

[k,3], np.float – returns the position Estimate. The value of k is 2 for the Least square estimator. The Least square estimator returns 2 position estimates, one above the reference locations and other below due to GDoP when the height of the ref nodes is same. For the remaining methods k is 1.

Attributes:

error (np.float) – return the uncertainty in the position estimates.

Important

The optimizationMethod parameter should be passed in accordance with positioningMethod as detailed in Table-34.

  • For optimizationMethod = “TOA”, only “LeastSquare” is supported.

  • For optimizationMethod = “TDOA”, “GradientDescent” and “NewtonRaphson” is supported.

  • For optimizationMethod = “DOA”, “GradientDescent” and “NewtonRaphson” is supported.

Note

For ToA and AoA methods, the number of measurements must match the number of reference locations. On the other hand, for TDoA method, the number of measurements should be equal to \(\text{N}_\text{ref}-1\) and first location in refPosition should indicate the location of the node whose ToA measurement is taken as reference for computing TDoAs. The time difference of arrival is computed as \(\{ \Delta \tau_{i,r} = \tau_i - \tau_r\}_{i=0}^{i=\text{N}_\text{ref}-1} s.t. i \neq r\) where \(r\) is the reference measurement used for difference in TDoA. The location of node-r must be the at the first place in refPosition followed by the locations of the remaining nodes from the set \(\zeta = \{i | i \neq r\}_{i=0}^{i=\text{N}_\text{ref}-1}\).

  • refPosition[:,0] = location of node-r

  • refPosition[:,i] = location of node-\(\zeta[i]\)

Note

The large value of numIterationPerEpoch improves the optimization performance but increases the complexity of the method.

Note

The large value of numEpochs helps reduce the odds of getting stuck in the local optima but increases the complexity of the method.

Note

The lower value of tolerance improves the optimization performance but increases the complexity of the method. The method iterative longer to reduces the optimization error below the tolerance limit.

Note

The selection of step-size mu plays crucial role in performance of the method. Small step-size results in good performance but requires large number of iteration numIterationPerEpoch to converge. Large step-size improves the convergence rate but are suceptible to local minimas.

Important

The Hybrid Positioning Methods are not released yet.

Raises:

  • ValueError – [Warning-PositionEstimation]: Currently not supported! Defaulting to ‘GradientDescent’!

  • ValueError – [Error-PositionEstimation]: ‘refPosition’ must be a numpy array!

  • ValueError – [Error-PositionEstimation]: ‘refPosition’ must be an numpy array of size (numRefnode x 3)!

  • ValueError – [Error-PositionEstimation]: ‘toa’ must be a numpy array!

  • ValueError – [Error-PositionEstimation]: size of ‘toa’ must be equal to ‘num of reference nodes’(refPosition.shape[0])!

  • ValueError – [Error-PositionEstimation]: ‘tdoa’ must be a numpy array!

  • ValueError – [Error-PositionEstimation]: size of ‘tdoa’ must be equal to ‘num of reference nodes’ - 1 (refPosition.shape[0]-1)!

  • ValueError – [Error-PositionEstimation]: ‘doa’ must be a numpy array!

  • ValueError – [Error-PositionEstimation]: shape of ‘doa’ must be equal to (refPosition.shape[0],2)!

  • ValueError – [Error-PositionEstimation]: ‘positioningMethod’ must be one of ‘TOA’, ‘TDOA’, ‘DOA’!

  • ValueError – [Error-PositionEstimation]: ‘optimizationMethod’ must be ‘ESPRIT’, ‘MUSIC’, ‘PDP’!

  • ValueError – [Error-PositionEstimation]: TOA positioning method support only ‘LeastSquare’ optimization methods!

  • ValueError – [Error-PositionEstimation]: TOA positioning method support only ‘LS’, ‘Newton’, and ‘Gradients’ optimization methods!

  • ValueError – [Error-PositionEstimation]: fig_ax_tuple must be a tuple!

  • ValueError – [Error-PositionEstimation]: fig_ax_tuple[0] must be a ‘plt.Figure’ type object!

  • ValueError – [Error-PositionEstimation]: fig_ax_tuple[1] must be a ‘plt.Axes’ type object!

  • ValueError – [Warning-PositionEstimation]: Currently visualization supported only for ‘TOA’ method!

display(circlelw=0.4, circlels='--', estLocSize=100, estLocMarker='.', estLocColor='r', refLocSize=125, refLocMarker='P', refLocColor='b', fig_ax_tuple=None, displayLegends=True)[source]

Display the locus of the time of arrival circles to check the optimization performance of the position estimation method. :Parameters: * circlelw (float) – Defines the line-width of the plotted ToA locus circle. Default value is 0.4.

  • circlels (str) – Defines the line-style of the plotted ToA locus circle. Default value is “–“.

  • estLocSize (float) – Defines the size of the marker of the estimated node location. Default value is 100.

  • estLocMarker (str) – Defines the type of the marker of the estimated node location. Default value is “.” (dot sign).

  • estLocColor (str) – Defines the color of the marker of the estimated node location. Default value is “r” (red color).

  • refLocSize (float) – Defines the size of the marker of the reference node location. Default value is 100..

  • refLocMarker (str) – Defines the type of the marker of the reference node location. Default value is “P” (Plus sign).

  • refLocColor (str) – Defines the color of the marker of the reference node location. Default value is “b” (blue color).

  • fig_ax_tuple ((2,), tuple) –

    tuple containing 2 values. If passed, the plot will be appended to the inputted (fig, ax) object.

    • fig_ax_tuple[0] is the plt.Figure type object and,

    • fig_ax_tuple[1] is the plt.Axes type object.

  • displayLegends (bool) – Flag allows to user to enable/disble the visibility of the new legends to the (fig, ax) object.

Submodules