Merge pull request #72 from ut-issl/develop

Merge main for v6.0.0 update

Author: 200km

.github/workflows/labeler.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v3
 
       - name: Run Labeler
-        uses: crazy-max/ghaction-github-labeler@v3
+        uses: crazy-max/ghaction-github-labeler@v4
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           yaml-file: .github/labels.yml

.github/workflows/mdbook.yml

@@ -16,7 +16,7 @@ jobs:
           fetch-depth: 0
 
       - name: setup mdbook
-        uses: peaceiris/actions-mdbook@v1.1.14
+        uses: peaceiris/actions-mdbook@v1.2.0
         with:
           mdbook-version: 'latest'
 

General/CodingConvention.md

@@ -10,9 +10,11 @@
 - Now discussing
   - The following rules are follows until the new naming rule is decided.
   - Several old files do not follow the rules.
+  - We are discussing follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with small modifications.
 
 - File and directory Name
-  - `CamelCase`
+  - `snake_case`
+  - C++ files should end in `.cpp`, and header files should end in `.hpp`.
 
 - Macro (define)
   - Snake case with capital case
@@ -36,6 +38,9 @@
 - Methods (functions) in the class
   - `CamelCase`
 
+- The #define Guard
+  - Apply [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
+  - `#pragma once` is prohibited
 
 ## Documentation
 - Use Doxygen
@@ -47,3 +52,37 @@
 ## Initialization files (`.ini` files)
 - Comments
   - Use //
+
+## Abbreviations 
+- Basically, we follows the [Naming Rules in the Google Style Guide](https://google.github.io/styleguide/cppguide.html#General_Naming_Rules)
+- Single character abbreviations are prohibited.
+  - Examples: `q = quaternion`, `v = velocity` are prohibited.
+- We do not recommend to use abbreviations for one word cutting the word.
+  - Examples: `pos = position`, `quat = quaternion` are not recommended.
+  - The following abbreviations are available as exceptions since they are widely used in the math, science, and technology field.
+    - `max`: maximum
+    - `min`: minimum
+    - `init`: initial, initialize
+    - `calc`: calculate, calculation
+- Abbreviation only file name is not recommended.
+  - Examples
+    - `ode.hpp` should be written as `ordinary_differential_equation.hpp`
+    - `gnssr.hpp` is not recommended, but `gnss_receiver.hpp` is available since we can guess the abbreviation meaning from the context.
+- Write the full words in the comment when you use abbreviations.
+- Available abbreviations are decided during review processes.
+  - Examples of available abbreviations with comments
+    - `EKF`: Extended Kalman Filter
+    - `GNSS`: Global Navigation Satellite System
+- Abbreviations to show the frame and the unit are available.
+  - Examples of frame
+    - `i`: Inertial frame
+    - `b`: Body fixed frame
+    - `c`: Component fixed frame
+    - `ecef`: Earth Centered Earth Fixed frame
+    - `lvlh`: Local Vertical Local Horizontal
+    - `rtn`: Radial-Transverse-Normal
+  - Examples of unit: `Nm`, `rad/s`, `m/s2`, `degC`
+- Available abbreviations 
+  - `S2E`: Spacecraft Simulation Environment
+  - `AOCS`: Attitude and Orbit Control System
+  - `CDH`: Command and Data Handling

General/DocumentFormat.md

@@ -3,10 +3,7 @@
 ## 0. General rule
 - The file name should be `Spec_CamelCase.md` in the Specifications directory. 
 - Please use the markdown format.
-- The markdown files are converted to a book with [mdBook](https://rust-lang.github.io/mdBook/) and published in Github Pages.
-  - The equations are rendered with [MathJax](https://www.mathjax.org/)
-    - e.g., Please use `\boldsymbol` for bold characters instead of `\bm`.
-- So, please follow the writing rules of mdBook and MathJax.
+- Because GitHub started to support math description ([link](https://github.blog/2022-05-19-math-support-in-markdown/)), we need to describe equations suit with the rule of GitHub and [MathJax](https://www.mathjax.org/).
 
 ## 1.  Overview
 1. Functions
@@ -28,21 +25,14 @@
    2. Inputs and Outputs
 
    3. Algorithm
-      - MathJax description
-        - please use equations as
-
-          \\[
+      - Math description
+        - please use equations as  
+          $$\dot{\boldsymbol{x}}=f(\boldsymbol{x},t)$$
+          or 
+          ```math
           \dot{\boldsymbol{x}}=f(\boldsymbol{x},t)
-          \\]
-        - you can also use inline equation as \\( x=y \\)
-
-      - Following description is automatically converted to the above style, but do not use this for new files.
-      
-        ```math
-        \dot{\boldsymbol{x}}=f(\boldsymbol{x},t)
-        ```
-        - inline equation: $`x=y`$
-
+          ```
+        - you can also use inline equation as $x=y$
 
    4. Note
 

General/HowToCompileWithVisualStudio.md

@@ -42,15 +42,16 @@ This document explains how to build and execute the Visual Studio environment wi
       <pre>
       ├─ExtLibraries
       │  └─cspice
-      │  └─nrlmsise00 
+      │  └─GeoPotential
+      |  └─nrlmsise00
       └─s2e-core
       </pre>
 
 ## 3. The flow of building and execution in Visual Studio 2022
 1. Launch VS 2022
 
 2. Open the S2E project
-   - Click `Files/Open/CMake`.
+   - Click `File/Open/CMake`.
    - Select `s2e-core/CMakeLists.txt` at the top directory of the cloned S2E.
    - Wait a moment until the `CMake generation` is finished.
 

General/HowToDownloadNRLMSISE00library.md

@@ -4,7 +4,7 @@
 - [NRLMSISE00](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2002JA009430) is an atmosphere model to calculate an air density, considering the solar activity.
 - [C language version of NRLMSISE00](https://git.linta.de/?p=~brodo/nrlmsise-00.git;a=summary) is a mandatory library for S2E to calculate the atmosphere density around the Earth.
 - How to use NRLMSISE00 is written in the [Specification of Atmosphere model](../Specifications/Environment/Spec_Atmosphere.md).
-- **Note** The [s2e-core v5.0.0](https://github.com/ut-issl/s2e-core/releases/tag/v5.0.0) provides the CMake file to download and install the external libraries, and we recommend to use it since it is simpler. So users do not need to execute the following process.
+- **Note** From the [s2e-core v5.0.0](https://github.com/ut-issl/s2e-core/releases/tag/v5.0.0) we provide the CMake file to download and install the external libraries and recommend to use it since it is simpler. So users do not need to execute the following process.
 
 
 ## 2. How to set up NRLMSISE00 for S2E [OLD Descriptions]

General/HowToDwnloadCSPCElibrary.md

@@ -3,7 +3,7 @@
 ## 1.  Overview
 - [SPICE](https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/info/intrdctn.html) is a system to combine the most accurate space geometry and event data with space mission analysis, observation planning, or science data processing software developed by NASA.
 - [CSPICE](https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/index.html) is the C language version of SPICE and mandatory library for S2E to get planet information.
-- **Note** The [s2e-core v5.0.0](https://github.com/ut-issl/s2e-core/releases/tag/v5.0.0) provides the CMake file to download and install the external libraries, and we recommend to use it since it is simpler. So users do not need to execute the following process.
+- **Note** From the [s2e-core v5.0.0](https://github.com/ut-issl/s2e-core/releases/tag/v5.0.0), we provide the CMake file to download and install the external libraries and recommend to use it since it is simpler. So users do not need to execute the following process.
 
 
 ## 2. How to set up CSPICE Library for S2E [OLD Descriptions]

General/HowToVisualizeSimulationResults.md

@@ -0,0 +1,49 @@
+# How to Visualize Simulation Results
+
+## 1.  Overview
+The S2E generates the CSV format log file as the simulation results at the `data/log` directory. Users can use them to check the result of thier simulation with the following methods.  
+- Open the CSV file with a spreadsheet application like Excel, and make charts to analyze and/or visualize the results.
+- Open the CSV file with user's handmaded programs to analyze and/or visualize the resutls.
+- Use the `Plot Scripts` provided by the `S2E-CORE` to visualize the results.
+
+We are trying to increase the `Plot Scripts` to share the analysis method with many users and to improve the usability of S2E. We are welcome to add new `Plot Scripts` by users.
+
+
+## 2. How to use `Plot Scripts`
+- Overview
+  - Users can find the scripts at the `s2e-core/scripts/Plot` directory.
+  - They are written in [Python](https://www.python.org/).
+- Environment to execute Python
+  - We use [Pipenv](https://pypi.org/project/pipenv/) to manage the environment.  
+  - In the `s2e-core/scripts/Plot` directory, you can also find the `Pipfile` which defines the version of Python and other libraries used in the scripts.
+  - By using the `Pipenv`, users can easily construct the virtual environment to execute the scripts provided by the S2E
+  - Users can create a virtual environment by running following commands after changing directory to ```scripts/Plot```
+    ```
+    # Windows
+    pip install pipenv
+    pipenv sync
+    ```
+  - Then users can run scripts by following commands.
+    ```
+    # Windows
+    pipenv run python <path to scripts> --file-tag <log file tag>
+    ```
+    Example
+    ```
+    pipenv run python .\plot_orbit_eci.py --file-tag 230213_003054
+    ``` 
+- Example of the Visualization
+  - Satellite trajectory on the earth map and ground station visibility analysis
+    - The red star means the ground station.
+    - The blue line shows the satellite trajectory and it turns red when the satellite is visible from the ground station.
+    <div align="center">
+      <img src="./figs/plot_gs_visibility.JPG" alt="plot_gs_visibility" style="zoom:50%;" />
+    </div>
+  - Direction information at the satellite body fixed frame
+    - Users can see the direction vector of the sun, earth, moon, and the velocity of the satellite at the body fixed frame to check the attitude control works well.
+    <div align="center">
+      <img src="./figs/plot_body_frame_info.JPG" alt="plot_gs_visibility" style="zoom:100%;" />
+    </div>
+
+## 4. References
+- NA

General/NamingRuleForUserInterface.md

@@ -0,0 +1,50 @@
+# Naming Rule for User Interface
+
+## Overview
+This document describes the naming rule for user interface layer which includes `parameters in initialize files` and `variable names in CSV log files`. Since users directly access to the values, we need to care the readability more than the name of variables in codes.
+
+### Common rules
+- The names has following structure
+  - Scalar values: `[name]_[unit]`
+  - Vector or matrix values: `[name]_[frame]_[unit]`
+  - If the value has no unit, we can remove the `[unit]` information.
+- Variable name field: `[name]` 
+  - It should be written as `snake_case`.
+  - Single character abbreviations are prohibited.
+    - Examples: `q = quaternion`, `v = velocity` are prohibited.
+  - We do not recommend to use unfamiliar abbreviations.
+    - Examples: `pos = position`, `quat = quaternion` are not recommended.
+  - Available abbreviations are decided during review processes.
+- Unit field: `[unit]`
+  - For readability, we recommend to use general unit description in the SI unit system, and we do not need to follow the `snake_case` description in the unit field.
+  - Examples: `Nm`, `rad/s`, `m/s2`, `degC`
+- Frames
+  - For readability, we recommend to use the following abbreviation in the unit field. When new abbreviation is needed for the frame description, please add it into the following list.
+    - `i`: Inertial frame
+    - `b`: Body fixed frame
+    - `c`: Component fixed frame
+    - `ecef`: Earth Centered Earth Fixed frame
+    - `lvlh`: Local Vertical Local Horizontal
+    - `rtn`: Radial-Transverse-Normal
+  - To express the frame conversion, we can use `i2b` as `frame conversion from the inertial frame to the body-fixed frame`.
+  - Note: The definition of origin of inertial frame is defined by the user settings. So sometimes we cannot use `eci = Earth Centered Inertial`.
+  - The axis of the frame is described as `i_x, i_y, i_z`.
+
+## Initialize files
+- S2E uses `INI` format initialize files.
+- `INI` has `Section` and `key` fields as follows
+  ```
+  [SECTION]
+  key = value
+  ```
+- The `SECTION` field should be written as `SNAKE_CASE`
+- The `key` fields should be written to follow the above `Common rules`.
+- The axis of the frame is described as `(0), (1), (2)`, and they mean `X, Y, Z`
+  - For quaternion `(0), (1), (2), (3)` is used as `X, Y, Z, W`.
+  - TODO: Modify to use `X, Y, Z` directory?
+
+## CSV log files
+- S2E generates `CSV` format log files.
+- The output file has the `variable names` in the first rows.
+- The `variable names` should be written to follow the above `Common rules`.
+- The unit is written in the brackets `[ ]` as `[N]`