Merge pull request #36 from ut-issl/feature/fix-math-for-github-md

Modify math description for GitHub markdown update
ut-issl · Nov 18, 2022 · cb1c066 · cb1c066
2 parents 8a70b7f + 6877714
commit cb1c066
Show file tree

Hide file tree

Showing 25 changed files with 466 additions and 410 deletions.
diff --git a/General/DocumentFormat.md b/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
 

diff --git a/README.md b/README.md
@@ -13,14 +13,13 @@
     - This version is only for s2e-core developers
   - feature/branch-name
     - Writing documents before merge with the `develop`
-- You can read the documents in the [GitHub Pages of this repository](https://ut-issl.github.io/s2e-documents).
 - If you have any questions or comments for S2E, feel free to ask us on the [discussions page of s2e-core](https://github.com/ut-issl/s2e-core/discussions).
 
 ## Index
 
 1. General Information
-   1. [Coding Convention](./General/CodingConvention.md)
-   2. [Format of Documents](./General/DocumentFormat.md)
+   1. [Coding Convention of S2E](./General/CodingConvention.md)
+   2. [Format of S2E Documents](./General/DocumentFormat.md)
    3. Mandatory set up and How to Build the S2E  
 	   1. [How to build with Visual Studio](./General/HowToCompileWithVisualStudio.md)
 	   2. [How to build with Ubuntu in Docker](./General/HowToCompileWithUbuntuInDocker.md) for **both Windows and Mac** users
@@ -58,7 +57,7 @@
       3. CDH
       4. Logic
       5. Mission
-         1. [Telescope](./Specifications/Component/Mission/Spec_Telescope_en.md)
+         1. [Telescope](./Specifications/Component/Mission/Spec_Telescope_en.md) ([Japanese version](./Specifications/Component/Mission/Spec_Telescope_ja.md))
       6. Power
          1. [PCU](./Specifications/Component/Power/Spec_PCU.md)
       7. Propulsion
@@ -79,7 +78,11 @@
          1. [Attitude Dynamics](./Specifications/Dynamics/Spec_AttitudeDynamics.md)
          2. [Controlled Attitude](./Specifications/Dynamics/Spec_ControlledAttitude.md)
       2. [Orbit](./Specifications/Dynamics/Spec_Orbit.md)
-         1. [Relative Orbit](./Specifications/Dynamics/Spec_RelativeOrbit.md)
+         1. [Kepler Orbit](./Specifications/Dynamics/Spec_KeplerOrbit.md)
+         2. [RK4 Orbit Propagation](./Specifications/Dynamics/Spec_Rk4Orbit.md)
+         3. [SGP4 Orbit Propagation with TLE](./Specifications/Dynamics/Spec_Sgp4.md)
+         4. [ENCKE method](./Specifications/Dynamics/Spec_EnckeMethod.md)
+         5. [Relative Orbit](./Specifications/Dynamics/Spec_RelativeOrbit.md)
       3. Thermal
 
    4. Environment

diff --git a/Specifications/Component/AOCS/Spec_RWJitter.md b/Specifications/Component/AOCS/Spec_RWJitter.md
@@ -22,15 +22,15 @@
 
 3. how to use
    - Set the harmonics coefficients in `radial_force_harmonics_coef.csv` and `radial_torque_harmonics_coef.csv`
-   - The first column is an array of the $`h_i`$($`i`$-th harmonic number). The second column is an array of the $`C_i`$(amplitude of the $`i`$-th harmonic).
+   - The first column is an array of the $h_i$( $i$-th harmonic number). The second column is an array of the $C_i$ (amplitude of the $i$-th harmonic).
    - Set parameters in `RW.ini`
-   - When only the static imbalance and dynamic imbalance(correspond to $`C_i`$ at $`h_i`$≒1) is known according to the spec sheet, edit the files as follows.
+   - When only the static imbalance and dynamic imbalance(correspond to $C_i$ at $h_i\ne1$) is known according to the spec sheet, edit the files as follows.
      + `radial_force_harmonics_coef.csv`
-       * Set $`h_1`$(the line 1 of the first column) as $`1.0`$.
-       * Set $`C_1`$(the line 1 of the second column) as the static imbalance on the spec sheet.
+       * Set $h_1$(the line 1 of the first column) as $1.0$.
+       * Set $C_1$(the line 1 of the second column) as the static imbalance on the spec sheet.
      + `radial_torque_harmonics_coef.csv`
-       * Set $`h_1`$(the line 1 of the first column) as $`1.0`$.
-       * Set $`C_1`$(the line 1 of the second column) as the dynamic imbalance on the spec sheet.
+       * Set $h_1$(the line 1 of the first column) as $1.0$.
+       * Set $C_1$(the line 1 of the second column) as the dynamic imbalance on the spec sheet.
      + `RW.ini`
        * Set `harmonics_degree = 1`.
     - Set the jitter update period to an appropriate value.
@@ -57,8 +57,8 @@
         u(t)=\sum_{i=1}^n C_i\Omega^2\sin(2\pi h_i\Omega t+\alpha_i)
         ```
         
-        -  where $`u(t)`$ is the disturbance force and torque in Newton (N) or Newton-meters (Nm), $`n`$ is the number of harmonics included in the model, $`C_i`$ is the amplitude of the $`i`$th harmonic in $`\mathrm{N^2/Hz}`$ (or $`\mathrm{(Nm)^2/Hz}`$), $`\Omega`$ is the wheel speed in Hz, $`h_i`$ is the $`i`$th harmonic number and $`\alpha_i`$ is a random phase (assumed to be uniform over $`[0, 2\pi]`$) [1].
-        - $`\alpha_i`$ is generated as a uniform random number in the constructor.
+        -  where $u(t)$ is the disturbance force and torque in Newton (N) or Newton-meters (Nm), $n$ is the number of harmonics included in the model, $C_i$ is the amplitude of the $i$ th harmonic in $\mathrm{N^2/Hz}$ (or $\mathrm{(Nm)^2/Hz}$), $\Omega$ is the wheel speed in Hz, $h_i$ is the $i$ th harmonic number and $\alpha_i$ is a random phase (assumed to be uniform over $[0, 2\pi]$) [1].
+        - $\alpha_i$ is generated as a uniform random number in the constructor.
         - When users want to use a more precise model, set `considers_structural_resonance` to ENABLE in `RW.ini` and use a model that takes structural resonance inside the RW into account.
             + If structural resonances are not taken into account, the RW disturbance will be underestimated, but it is not a significant change in general.
             + See the description of `AddStructuralResonance()` for the algorithm to calculate the structural resonance.
@@ -72,15 +72,15 @@
         - output:
             + jitter force and torque with structural resonance in component frame
     3. algorithm
-        - The transfer function from disturbance by harmonics of RW without resonance ($`u(t)`$) to disturbance with resonance ($`y(t)`$) is modeled as following equation: 
+        - The transfer function from disturbance by harmonics of RW without resonance ( $u(t)$ ) to disturbance with resonance ( $y(t)$ ) is modeled as following equation: 
         ```math
         G(s)=\frac{s^2+2\zeta\omega_ns+\omega_n^2}{s^2+2d\zeta\omega_ns+\omega_n^2}
         ```
         ```math
         Y(s)=G(s)U(s)
         ```
-        - where $`\omega_n`$ is the angular frequency on the structural resonance. Other parameters such as $`\zeta`$, $`d`$ are determined by the result of experiments.
-        - To perform the simulation in discrete time, A bi-linear transformation $`G(s)\rightarrow H(z)`$ is applied. $`T`$ is the jitter update period. 
+        - where $\omega_n$ is the angular frequency on the structural resonance. Other parameters such as $\zeta$, $d$ are determined by the result of experiments.
+        - To perform the simulation in discrete time, A bi-linear transformation $G(s)\rightarrow H(z)$ is applied. $T$ is the jitter update period. 
 
         ```math
         \begin{aligned}
@@ -91,13 +91,13 @@
         \end{aligned}
         ```
 
-        - The $`\omega_n`$ should be the fixed value by pre-warping because there is frequency distortion due to bilinear transformation. The formula for calculating $`\omega_n`$ for the true resonant frequency $`\omega_d`$ is as follows:
+        - The $\omega_n$ should be the fixed value by pre-warping because there is frequency distortion due to bilinear transformation. The formula for calculating $\omega_n$ for the true resonant frequency $\omega_d$ is as follows:
 
         ```math
         \omega_n=\frac{2}{T}\tan(\frac{T\omega_d}{2})
         ```
 
-        - The bi-linear transformation transforms the relationship between input $`u`$ and output $`y`$ as follows:
+        - The bi-linear transformation transforms the relationship between input $u$ and output $y$ as follows:
 
         ```math
         \begin{aligned}
@@ -106,12 +106,12 @@
         \end{aligned}
         ```
 
-        - By applying the inverse z-transform, the continuous relationship between $`y(t)`$ and $`u(t)`$ can be expressed as a  discrete relationship of a difference equation between $`y[n]`$ and $`u[n]`$, where $`[n]`$ is the current simulation time step. The difference equation is as follows:
+        - By applying the inverse z-transform, the continuous relationship between $y(t)$ and $u(t)$ can be expressed as a  discrete relationship of a difference equation between $y[n]$ and $u[n]$, where $[n]$ is the current simulation time step. The difference equation is as follows:
         ```math
         c_0y[n]+c_1y[n-1]+c_2y[n-2]=c_3u[n]+c_4u[n-1]+c_5u[n-2]
         ```
 
-        - Therefore, $`y[n]`$ is calculated as follows.
+        - Therefore, $y[n]$ is calculated as follows.
         ```math
         y[n]=\frac{(-c_1y[n-1]-c_2y[n-2]+c_3u[n]+c_4u[n-1]+c_5u[n-2])}{c_0}
         ```
@@ -166,7 +166,7 @@
             <img src="./figs/rw_waterfall_sim.jpg" width=80% alt="Simulated RW jitter in time domain">
             </div>
             
-            - Both the first-order mode and the structural resonance ($`\omega_n=585\mathrm{Hz}`$) are approximately simulated.
+            - Both the first-order mode and the structural resonance ($\omega_n=585\mathrm{Hz}$) are approximately simulated.
 
 ## 4. References
     1. Masterson, R. A. (1999). Development and validation of empirical and analytical reaction wheel disturbance models (Doctoral dissertation, Massachusetts Institute of Technology).

diff --git a/Specifications/Component/AOCS/Spec_STT.md b/Specifications/Component/AOCS/Spec_STT.md
@@ -21,18 +21,18 @@
    - TBW
 2. `Judgement`
     1. `EarthJudgement`     
-      - Calculate the angle $`\theta_{ce}`$ between the earth's center direction $`\boldsymbol{r_{sc}}`$ and the earth's edge direction $`\boldsymbol{r_{se}}`$. $`R_e`$ is the earth's radius.
-      - Calculate the angle $`\theta_{es}`$ between the sight direction $`\boldsymbol{r_{sight}}`$ and the earth's edge direction $`\boldsymbol{r_{se}}`$.
-      - Judge the STT error flag by comparing $`\theta_{es}`$ with the earth forbidden angle $`\theta_{efa}`$. If $`\theta_{es} > \theta_{efa}`$, the earth is completely outside the earth forbidden angle.
+      - Calculate the angle $\theta_{ce}$ between the earth's center direction $\boldsymbol{r_{sc}}$ and the earth's edge direction $\boldsymbol{r_{se}}$. $R_e$ is the earth's radius.
+      - Calculate the angle $\theta_{es}$ between the sight direction $\boldsymbol{r_{sight}}$ and the earth's edge direction $\boldsymbol{r_{se}}$.
+      - Judge the STT error flag by comparing $\theta_{es}$ with the earth forbidden angle $\theta_{efa}$. If $\theta_{es} > \theta_{efa}$, the earth is completely outside the earth forbidden angle.
 
 
       ```math
-        \theta_{ce} = \arctan{\left(\frac{|\boldsymbol{r_{se}}|}{R_e}\right)}
-        \\
-        \theta_{cs} = \arccos{(\boldsymbol{r_{se}}*\boldsymbol{r_{sight}})}
-        \\
+      \begin{align}
+        \theta_{ce} = \arctan{\left(\frac{|\boldsymbol{r_{se}}|}{R_e}\right)}\\
+        \theta_{cs} = \arccos{(\boldsymbol{r_{se}}*\boldsymbol{r_{sight}})}\\
         \theta_{es} = \theta_{ce} - \theta_{cs}
         \tag{1}
+      \end{align}
       ```
 
       ![](./figs/stt_earth_judgement.png)
@@ -58,15 +58,15 @@
 
    3. results
       - The angle between pointing direction and earth center = 15deg
-        - STT flag is always 1, since the angle $`\theta_{es}`$ between the sight direction and the earth's edge direction is 15 - 8.6 = 6.4deg < 10deg. 
+        - STT flag is always 1, since the angle $\theta_{es}$ between the sight direction and the earth's edge direction is 15 - 8.6 = 6.4deg < 10deg. 
 
          ![](./figs/stt_flag_15.png)
 
       - The angle between pointing direction and earth center = 20deg
-        - STT flag is always 0, since the angle $`\theta_{es}`$ between the sight direction and the earth's edge direction is 20 - 8.6 = 11.4deg > 10deg.
+        - STT flag is always 0, since the angle $\theta_{es}$ between the sight direction and the earth's edge direction is 20 - 8.6 = 11.4deg > 10deg.
 
          ![](./figs/stt_flag_20.png)
 
       - The angle between pointing direction and earth center = 30deg
-        - STT flag is always 0, since the angle $`\theta_{es}`$ between the sight direction and the earth's edge direction is 30 - 8.6 = 21.4deg > 10deg.
+        - STT flag is always 0, since the angle $\theta_{es}$ between the sight direction and the earth's edge direction is 30 - 8.6 = 21.4deg > 10deg.
          ![](./figs/stt_flag_30.png)
diff --git a/Specifications/Component/Abstract/Spec_ComponentBase.md b/Specifications/Component/Abstract/Spec_ComponentBase.md
@@ -21,15 +21,15 @@
     2. inputs
        - `prescaler`
          + `prescaler` determines the execution cycle of the `MainRoutine` function.
-         + The period of `MainRoutine` equals to `SimTime::compo_update_interval_sec` $`\times`$ `prescaler`.
+         + The period of `MainRoutine` equals to `SimTime::compo_update_interval_sec` $\times$ `prescaler`.
        - `clock_gen`
          + `clock_gen` is an instance that simulates the clock of a component.
          + Users do not need to care about this.
        - `power_port`
          + `power_port` is an instance that simulates the power supply
        - `fast_prescaler`
          + `fast_prescaler` determines the execution cycle of the `FastUpdate` function.
-         + The period of `FastUpdate` equals to `SimTime::compo_update_interval_sec` $`\times`$ `fast_prescaler`.
+         + The period of `FastUpdate` equals to `SimTime::compo_update_interval_sec` $\times$ `fast_prescaler`.
          + If you don't need to use `FastUpdate`, you don't need to specify this (it is set to 1 by default).
     3. algorithm
        - N/A