Release v3.0.0

.github/workflows_bak/publish.yaml

@@ -5,35 +5,52 @@ name: Documentation
 # events but only for the master branch
 on:
   push:
-    branches: [ main ]
+    branches: [ develop-weekly ]
 
 jobs:
   build-documentation:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
 
-    - name: Create folders
+    - name: Get appimage to generate config docs
+      uses: actions/checkout@v4
+      with:
+        ref: develop-weekly-appimage
+
+    - name: Generate config markdown doc from appimage
+      run: |
+        sudo apt-get install fuse
+        ./Ginan-x86_64.AppImage -Y 3
+        mkdir Docs
+        mv defaultConfiguration.md Docs
+
+    - name: Checkout the updated branch
+      uses: actions/checkout@v3
+      with:
+        clean: false
+
+    - name: Create folders and move readme
       run: |
-        rm Docs/markdown/readme.md
-        cp README.md Docs/markdown/readme.md
+        cp README.md Docs/readme.md
         mkdir -p src/build
-    
-    # Build the HTML documentation
-    - name: Doxygen Action
+
+    - name: List everything as debug
+      run: |
+        find
+
+    - name: Build doxygen docs from code
       uses: mattnotmitt/[email protected]
       with:
           doxyfile-path: ../doc_templates/Doxyfile.in
           working-directory: ./src/build
-
-    # Deploy the HTML documentation to GitHub Pages
-    - name: GH Pages Deployment
+
+    - name: Deploy the HTML documentation to GitHub Pages
       uses: peaceiris/actions-gh-pages@v3
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ./Docs/
         enable_jekyll: false
         allow_empty_commit: false
         force_orphan: true
-        publish_branch: gh-pages 
+        publish_branch: gh-pages-staging

CHANGELOG.md

@@ -3,6 +3,41 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
+# [3.0] 2024-02-05
+
+### Added
+IERS 2010 standard tide models implemeted and validated including:
+- Solid Earth (SE) Tide, 
+- SE Pole Tide, 
+- Ocean Tide Loading (OTL) 
+- Ocean Pole Tide
+- Atmosphere Tide Loading (ATL)
+
+Compact SSR standard correction output encoding/decoding implemented
+
+### Changed
+Reorganisation of the YAML configuration file to make it more logical
+
+Improved Satellite attitude models implemented for (GPS/GAL/GLO/BDS/QZS)
+
+Improved Receiver (antenna) attitude model implemented
+
+New standard IERS linear mean pole model implemented
+
+Use case examples updated
+
+EDA improvements
+
+Improved documentation
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+### Security
+
 # [2.1] 2023-07-04
 
 ### Added

Docs/ambiguities.md

@@ -19,12 +19,12 @@ As with any integer estimation process the ambiguity resolution for GNSS signals
 * The validity of integer ambiguities is tested using statistical tests.
 * Ambiguity states are constrained to the resolved ambiguity
 
-Ginan can be set to solve ambiguities in GPS, Galileo, Beidou and QZSS measurements. Ambiguity resolution are not supported for the GLONASS FDMA signals.
+Ginan can be set to solve ambiguities in GPS, Galileo, Beidou and QZSS measurements. Ambiguity resolution is not supported for the GLONASS FDMA signals.
 
 
 ## Real-valued ambiguity estimation
 
-Carrier phase ambiguities and phase biases are estimated as real numbers using carrier phase measurments 
+Carrier phase ambiguities and phase biases are estimated as real numbers using carrier phase measurements 
 \begin{equation}
 E(L_{r,c}^s) 
 = \rho_{r}^s 
@@ -42,15 +42,15 @@ The range $\rho_{r}^s$, clock offsets $dt_{r}^q$ and $dt^s$, atmospheric delays
 However this still leaves the rank deficiency produced by correlations between ambiguities $z_{r,c}^s$ and phase biases $b_{r,c}^q$ and $b_{c}^s$.
 Thus, without using extra pseudo-observations, the real valued ambiguities are expected to be contaminated by these phase biases $A_{r,c}^s = \lambda_{f} z_{r,c}^s + b_{r,c}^q - b_{c}^s$
 
-This make it difficult to solve the ambiguites directly. 
-Ginan choses instead to make and solve combinations of ambiguities, e.g.:
+This make it difficult to solve the ambiguities directly. 
+Ginan chooses instead to make and solve combinations of ambiguities, e.g.:
 \begin{equation}
 A_{r1,r2,  c}^{s1,s2} = A_{r1,c}^{s1} - A_{r1,c}^{s2} - A_{r2,c}^{s1} - A_{r2,c}^{s2} = \lambda_{f} (z_{r1,c}^{s1} - z_{r1,c}^{s2} - z_{r2,c}^{s1} - z_{r2,c}^{s2}).
 \end{equation}
-Ginan forms these combination by using the LAMBDA Z-transform/decorrelation, thus only algorithms using the Z-transform are effective in ambiguity resolution without using pivots.
+Ginan forms these combinations by using the LAMBDA Z-transform/decorrelation, thus only algorithms using the Z-transform are effective in ambiguity resolution without using pivots.
 
-For end user processing, where the satellite phase bias $b_{c}^{s1}$ is known, a **receiver ambiguity pivot** can be applied to separate the receiver phase bias from the embiguities.
-By setting the ambiguity for one satellite $s1$ to an arbitrary valuse $\tilde{z_{r,c}^{s1}}$ the receiver phase bias will be se to 
+For end user processing, where the satellite phase bias $b_{c}^{s1}$ is known, a **receiver ambiguity pivot** can be applied to separate the receiver phase bias from the ambiguities.
+By setting the ambiguity for one satellite $s1$ to an arbitrary value $\tilde{z_{r,c}^{s1}}$ the receiver phase bias will be se to 
 $\tilde{b_{r,c}^q}=b_{r,c}^q+\lambda_{f} (\tilde{z_{r,c}^{s1}}-z_{r,c}^{s1})$.
 This in turn will make other ambiguity estimate into solvable integers:
 \begin{equation}
@@ -63,14 +63,14 @@ A_{r,c}^{s2} + b_{c}^{s2} - \tilde{b_{r,c}^q} = \lambda_{f} (z_{r,c}^{s2}-\tilde
 A_{r,c}^{s3} + b_{c}^{s3} - \tilde{b_{r,c}^q} = \lambda_{f} (z_{r,c}^{s3}-\tilde{z_{r,c}^{s1}}+z_{r,c}^{s1})
 \end{equation}
 
-The **network ambiguity pivot** performs a similar function for nework processing, where both receiver and satelite biases are defined using a small set of arbitrarily set ambiguities:
+The **network ambiguity pivot** performs a similar function for network processing, where both receiver and satellite biases are defined using a small set of arbitrarily set ambiguities:
 1. Assign a station as anchor, and define the receiver bias $b_{r0,c}^q=0$
 1. At each epoch, scan all ambiguity estimates $z_{r,c}^{s}$ 
 	1. If the phase bias for receiver $b_{r,c}^q$ is defined but the satellite phase bias $b_{c}^{s}$ is not, define $b_{c}^{s}$ by setting $z_{r,c}^{s}$ to an arbitrary value
 	1. If the phase bias for satellite $b_{c}^{s}$ is defined but the receiver phase bias $b_{r,c}^q$ is not, define $b_{r,c}^q$ by setting $z_{r,c}^{s}$ to an arbitrary value
 1. Repeat until all phase biases are defined 
 
-Using the ambiguity pivots allows real-value estimate of ambiguity to become close to integer values and thus use ambiguity resolution techniques without Z-transform/decorrelation 
+Using the ambiguity pivots allows real-value ambiguity estimates to become close to integer values and thus use ambiguity resolution techniques without Z-transform/decorrelation.
 
 ## Integer ambiguity estimation and validation
 Once the real-valued ambiguity estimates have been calculated, they can be solved into integers. Ginan implements various methods for to perform ambiguity resolution, namely:
@@ -94,9 +94,9 @@ and the success rate test:
 where $R_{thres}$ and $S_{thres}$ are user defined thresholds, $erfc$ is the complementary error function and $Q_{zz}$ is the covariance matrix of ambiguities. 
 
 The `round` method consider the ambiguities to be independent of each other. 
-In reality the ambiguituities are highly correlated with each other, even after eliminating rank deficiencies using abiguity pivots. 
+In reality the ambiguities are highly correlated with each other, even after eliminating rank deficiencies using ambiguity pivots. 
 The `iter_rnd` method attempts to mitigate the effect of these correlations by iterating the integer rounding process. 
-After solving the subset ${\bf j}\subset {\bf i}$ of amiguities, the estimated ambiguities and its covariance are updated as:
+After solving the subset ${\bf j}\subset {\bf i}$ of ambiguities, the estimated ambiguities and its covariance are updated as:
 \begin{equation}
 {\bf K}={\bf Q_{zz}}({\bf i},{\bf j}) {\bf Q_{zz}}({\bf j},{\bf j})
 \end{equation}
@@ -119,22 +119,22 @@ where
 \begin{equation}
 {\bf Z_{ij}} = {\bf I} - n_{ij}{\bf e_i}{\bf e_j^{T}}
 \end{equation}
-with $n_{ij} \in \Bbb Z$ and ${\bf e_i}$ a column vector with 1 in positin $i$ and 0 elsewere.
+with $n_{ij} \in \Bbb Z$ and ${\bf e_i}$ a column vector with 1 in position $i$ and 0 elsewhere.
 The ${\bf Z_{ij}}$ transformation is equivalent to substituting $z(i)$ with $z(i)-n_{ij}z(j)$, and has the effect of changing the covariance matrix as:
 \begin{equation}
 {\bf L''} = {\bf L} - n_{ij}{\bf L}{\bf e_i}{\bf e_j^{T}}
 \end{equation}
 where ${\bf L}$ is lower triangular matrix product of the $L^TDL$ decomposition of $Q_{zz}$.
-${\bf L''}$ s preseved by the transformation with the exception of:
+${\bf L''}$ s preserved by the transformation with the exception of:
 \begin{equation}
 l''_{kj} = l_{kj} - n_{ij}l_{ki} \forall k \ge i
 \end{equation}
-by chosing $n_{ij}$ such that $|l''_{kj}|<0.5$, the correlation between transformed ambiguities $z''$ are minimized 
+by choosing $n_{ij}$ such that $|l''_{kj}|<0.5$, the correlation between transformed ambiguities $z''$ are minimized 
 The `bootst` method applies the same process as `iter_rnd` on the transformed ambiguities $z''$.
 
-The lambda methods on the other hand use a iterative fix and adjust process to select a set of ambigities with minimum distance to the real-valued estimates.
+The lambda methods on the other hand use an iterative fix and adjust process to select a set of ambiguities with minimum distance to the real-valued estimates.
 The $R_{thres}$ and $S_{thres}$ thresholds are used in different ways. First the success rate threshold $S_{thres}$ is used to discard ambiguities that has too high an uncertainty to resolve.
-The reduction process used for lambda algorithms use a reordering process alongside the de-correlation whic tends to order the $z''$ ambiguity in descending ordr of variance.
+The reduction process used for lambda algorithms use a reordering process alongside the de-correlation which tends to order the $z''$ ambiguity in descending order of variance.
 Relying on this, the last $J$ ambiguities are selected for resolutions, with $J$ selected in such a way as to fulfill 
 \begin{equation}
 \coprod_{n-J}^n erf(sqrt{\frac{1}{8{\bf D''}(j)}}) \ge S_{thres}
@@ -144,14 +144,14 @@ The potential integer set candidates ${\bf \hat{z''}_k}$ candidates are selected
 \begin{equation}
 \|{\bf z''}-{\bf \hat{z''}_k}\|<R_{thres}\|{\bf z''}-{\bf \hat{z''}_0}\|
 \end{equation}
-where ${\bf \hat{z''}_0}$ is the integer set at minimum (weighted) distance from the real-valued estmate ${\bf z''}$.
+where ${\bf \hat{z''}_0}$ is the integer set at minimum (weighted) distance from the real-valued estimate ${\bf z''}$.
 There is also a maximum number of candidate sets set by the user.
 
-The difference between lambda methods  implemented in Ginan is the ambiguity validatio/selection process. 
+The difference between lambda methods implemented in Ginan is the ambiguity validation/selection process. 
 - The `lambda` method does not make further selection (beyond the application of $S_{thres}$), it returns the full ${\bf \hat{z''}_0}$ set as resolved ambiguities.
-- The `lambda_alt` method perform full ambiguity validation, it return ${\bf \hat{z''}_0}$ if and only if there are no alternative set that passes the $R_{thres}$ test.
-- The `lambda_al2` method perform partial ambiguity validation, it returns only integer ambiguities that have common values among all candidates ${\bf \hat{z''}_k}$
-- The `lambda_bie` method returns a weighted summ of all candidate sets candidates ${\bf \hat{z''}_k}$:
+- The `lambda_alt` method performs full ambiguity validation, it returns ${\bf \hat{z''}_0}$ if and only if there is no alternative set that passes the $R_{thres}$ test.
+- The `lambda_al2` method performs partial ambiguity validation, it returns only integer ambiguities that have common values among all candidates ${\bf \hat{z''}_k}$
+- The `lambda_bie` method returns a weighted sum of all candidate sets candidates ${\bf \hat{z''}_k}$:
 \begin{equation}
 {\bf z''_{bie}}=\sum_k (\frac {exp^{-0.5{\|{\bf z''}-{\bf \hat{z''}_k}\|}^2}}{\sum_k exp^{-0.5{\|{\bf z''}-{\bf \hat{z''}_k}\|}^2}}{\bf \hat{z''}_k})
 \end{equation}

Docs/announcements.md

@@ -1,17 +1,18 @@
 
-> **5 Jul 2023** - the Ginan team is pleased to release v2.1 of the toolkit. 
-> 
+> **5 Feb 2024** - the Ginan team is pleased to release v3.0.0 of the toolkit.
+>
 > The improvements delivered by this version include:
-> 
+>
 > * Unified User and Network operation modes (One Observation Model & Filter),
+> * Box-wing solar radiation modelling
+> * Increased configurability and streamlining of configuration files
+> * Grid-based model estimation
 > * Full Multi-Constellation capability,
 > * Better internal frequency indexing (complete multi-frequency capability),
-> * UnCombined / UnDifferenced (UDUC) processing (v1.5.3 is Ionosphere-free only),
+> * UnCombined / UnDifferenced (UDUC) processing
 > * Integrated and coupled Precise Orbit Determination capability (POD),
 > * More robust data handling in the filter for cycle slip and outlier detection and removal,
 > * Complete RTCM3 phase 1 and Phase 2 message decoding and encoding,
 > * Satellite Laser Ranging data handling fully implemented,
 > * Performance improvements,
-> * Numerous bug fixes.
-
-> **11 May 2023** - Dr Simon McClusky's [presentation](resources/Locate23_S_McClusky_final.pdf) on Ginan from Locate 23.
+> * Many bug fixes.

Docs/attitudes.md

@@ -0,0 +1,43 @@
+
+
+# Attitude Modelling
+A satellite's attitude is its orientation in space. Satellite attitude affects both the position and orientation of antenna arrays, as well as the spacecraft profile with respect to solar radiation or drag.
+
+
+## Nominal Yaw
+GNSS satellite attitudes are mainly dictated by their mission and operational requirements. In order to transmit GNSS signals, the antenna array (located on the satellite -Z axis) must point toward Earth. Secondly, in order to maximise solar power, satellites rotate around their Z axis (yaw) and rotate their solar panels around the Y axis to point toward the Sun.
+The optimal yaw $\psi$ which allows solar panels to point directly at the Sun is given by:
+
+\begin{equation}
+	\psi = atan2(-tan(\beta), sin(\mu)) + \pi
+\end{equation}
+
+where $\beta$ is the Sun elevation angle with respect to the orbital plane and $\mu$ is the angle of the satellite from orbital 'midnight' - i.e. when satellite is at the furthest point from the Sun in its orbit.
+
+
+## Modelled Yaw
+At low $\beta$ angles as the satellite passes through orbital noon or midnight, satellites experience 'gimbal lock' where the rate of yaw change required by the nominal yaw equation approaches $\pm\infty$ . Each constellation block has different modified yaw steering strategies to handle this problem, summarised below.
+
+| Block			| Yaw steering strategy																						|
+| -				| -																											|
+| GPS-IIA		| Noon: catch up steering at max yaw rate; Midnight: max yaw rate steering during eclipse					|
+| GPS-IIF		| Noon: catch up steering at max yaw rate; Midnight: constant yaw rate steering during eclipse				|
+| GPS-IIR		| Catch up steering at max yaw rate																			|
+| GPS-III		| Smoothed yaw steering																						|
+| GAL-IOV		| Smoothed yaw steering via auxiliary Sun vector															|
+| GAL-FOC		| Smoothed yaw steering																						|
+| GLO			| Noon: centered yaw steering at max yaw rate; Midnight: max yaw rate steering upon eclipse entry then stop	|
+| GLO-K			| Unknown																									|
+| QZSS-1		| Orbit-normal (yaw = 0) during specified periods															|
+| QZSS-2A/2I	| Centered yaw steering at max yaw rate, with orbit-normal during specified periods							|
+| QZSS-2G		| Orbit-normal																								|
+| BDS-2I/2M		| Orbit-normal at low beta angles																			|
+| BDS-2G		| Orbit normal																								|
+| BDS-3I/3M		| Smoothed yaw steering																						|
+| BDS-3M-SECM	| Smoothed yaw steering using auxiliary beta angle															|
+
+
+## Precise Attitudes
+
+Ginan is also able to use a-priori satellite attitudes, in place of the models above, in cases where GNSS satellite attitudes have already been precomputed or when a non-GNSS satellite has attitude data.
+

Docs/autoDownload.md

@@ -3,7 +3,7 @@
 
 The auto download script available in the `scripts` directory is a python tool that will automatically download various inputs needed to run Ginan
 
-The detailed feautures of each option can be found by changing to the `scripts` directory and running
+The detailed features of each option can be found by changing to the `scripts` directory and running
 
     python3 auto_download_PPP.py --help
 

Docs/codingStandard.md

@@ -12,7 +12,7 @@ Overall we are aiming to
 * Use short, descriptive variable names
 * Use aliases to reduce clutter.
 
-### Inconcise code - Not recommended
+### Unconcise code - Not recommended
 
 	//check first letter of satellite type against something
 
@@ -180,7 +180,7 @@ bool found = false;         //these have to be declared early so they can be use
 
 for (int i = 0; i < 10; i++)
 {
-    bool pass = someTestFunction();    //this pass variable isnt declared until it's used - good
+    bool pass = someTestFunction();    //this pass variable isn't declared until it's used - good
     if (pass)
     {
         type  = typeMap[i];
@@ -219,7 +219,7 @@ void function(
 * For config parameters, use `lowercase_with_underscores`
 * Use suffixes (`_ptr`, `_arr`, `Map`, `List` etc.) to describe the type of container for complex types.
 * Be sure to provide default values for member variables.
-* Use heirarchical objects where applicable.
+* Use hierarchical objects where applicable.
 
 ```
 struct SubStruct
@@ -256,7 +256,7 @@ if (acsConfig.some_parameter)
 * Do not use 'magic numbers', which require knowledge of other code fragments for comprehension. If a comment is required for explaining what a value means, the code should be rewritten with enums or defined constants. 
 * Do not append `.0` to integer valued doubles unless they are required.
 * Never use `free()`, `malloc()`, or `new` unless it cannot be avoided.
-* Threads create synchronisation issues, they should not be used unless manual synchronisation is never required.
+* Threads create synchronisation issues; they should not be used unless manual synchronisation is never required.
 
 ## Testing
 
@@ -397,7 +397,7 @@ Commonly used std containers may be included with `using`
 ## Code sequencing
 
 The software is to be kept largely sequential - using threads sparingly to limit the overhead of collision avoidance.
-Where possible tasks are completed in parallel using parallelisation libraries to take advantage of all cpu cores in multi-processor systems while still retaining a linear flow through the execution.
+Where possible tasks are completed in parallel using parallelisation libraries to take advantage of all CPU cores in multi-processor systems while still retaining a linear flow through the execution.
 
 Sections of the software that create and modify global objects, such as while reading ephemeris data, will be executed on a single core only. 
 This will ensure that collisions are avoided and the debugging of these functions is deterministic.

Docs/conventions.md

@@ -39,6 +39,7 @@ In this manual we will be adhering to the following conventions:
 |$\rho_i^j$  | Geometric distance between satellite and receiver|
 |$L_i^j$  | Carrier phase observable (times c) [m]|
 |$P_i^j$ |  Pseudo range observable [m]|
+|$\psi$ |  Satellite yaw [rad]|
 
 
 Example: for an undifferenced, uncombined float solution, the linearized observation equations for pseudorange and phase observations from satellite $s$ to receiver $r$ can be described as: