# シミュレータ（SILS）内部設計根拠 (Simulation Subsystem Rationale)

> [!NOTE]
> **ドキュメントのスコープ**
> 本資料は、実機衛星がない環境でも姿勢制御アルゴリズムや物理運動モデルの検証を可能にする「SILS（Software-in-the-Loop Simulation）」の必要性、およびシミュレータ内部における「プラント（物理モデル）とコントローラ（制御モデル）の分離設計」の根拠についてまとめたものです。シミュレータと地上局とのネットワーク接続やフライトコードへの具体的なコード移植設計については、[SILS 統合・接続設計根拠](../system/sils_integration) を参照してください。

---

## 1. 一般論・基本原理の提示 (解空間の起源)

### ① シミュレーション検証方式 (No Simulation vs HILS vs SILS)
宇宙機開発や高度な制御システムにおいて、実機が完成する前や物理的に稼働させられない環境でソフトウェアをデバッグするアプローチには、全くシミュレータを作らない方式、実機マイコンに模擬入力を与える **HILS (Hardware-in-the-Loop)**、PCの純粋なソフトウェアのみで完結させる **SILS (Software-in-the-Loop)** の3つがあります。

### ② プラント・コントローラ（P/C）の機能分離
制御工学の基本原則は、制御対象である物理力学系（**Plant**）と、その状態を計測して制御出力を与える制御プログラム（**Controller**）を論理的・構造的に切り分けることです。この分離ができていないシミュレータは、シミュレーション専用のコードとフライトソフトウェア（FSW）用のコードが混ざり合い、実機への移植時にバグを誘発します。

---

## 2. 候補の列挙とトレードオフ分析

### 【検証シミュレーション方式】候補の比較
*   **候補A（実機一発テスト）**: シミュレータを作らず、直接実機 Pico W にプログラムを書き込んで調整する。
*   **候補B（HILS 方式）**: 実機 Pico W を用い、センサ値やモータ出力をPC等の電気信号変換機経由でテストする。
*   **候補C（SILS 方式） [採用]**: 物理方程式も制御ロジックもすべてPC上のソフトウェア（Python）で閉じてシミュレーションする。

| 評価項目 | 候補A (実機一発テスト) | 候補B (HILS) | 候補C (SILS) [採用] |
| :--- | :--- | :--- | :--- |
| **ハードウェア破損リスク**| **極めて高い** (モータ暴走等) | 低 (電気的保護は必要) | **ゼロ (ソフトウェアのみのため安全)** |
| **環境構築コスト** | **極めて低い** (実機のみ) | 極めて高い (変換基板や信号同期が必要) | **低 (個人PC上の Python のみ)** |
| **開発の並行性（実機待ち）**| 不可 (実機組立完了まで開発停止) | 不可 (配線接続が必要) | **高 (実機完成前でも開発・テスト可能)** |
| **エラー注入（障害模擬）** | 困難 (過電流やセンサ断線の再現不可)| 中 (信号エミュレーション) | **極めて容易 (コード上の数値変更のみ)** |

---

### 【シミュレータ内部構造】候補の比較
*   **候補A（モノリシック・シミュレータ）**: 物理計算、制御ループ、通信処理が1つの巨大なファイルで実行される。
*   **候補B（プラント・コントローラ分離） [採用]**: `plant.py` が物理演算、`controller.py` が純粋な制御ロジック（状態遷移）をそれぞれ実行し、内部ループで結合する。

| 比較項目 | 候補A (モノリシック) | 候補B (プラント・コントローラ分離) [採用] |
| :--- | :--- | :--- |
| **移植時（C++化）のバグ発生率**| **極めて高い** (シミュレータ用コードの除去ミス) | **低い (controller.py をそのまま C++ に写すだけ)** |
| **コードの短さ・単純さ（初期）**| 高 (ファイル1つで完結) | 低 (オブジェクトの定義や受け渡しが必要) |
| **物理環境モデルの拡張性** | 低 (制御ロジックと絡み合う) | **高 (プラント内の物理方程式のみ変更可能)** |

---

## 3. 意思決定と選定根拠 (Justifications)

### ① 実機破損の「防御的回避」と開発の民主化 (検証性の確保)
*   **根拠**: 合宿開発中のサーボモータのギア破損や発熱といった物理的ハングアップを回避し、かつ「実機が手元になくとも、受講生各自のPC上でいつでも制御ロジックと地上局の動作検証を進められる」ようにするため、SILS方式（候補C）を採用しました。ゲインを100倍にして暴走させたり、センサ断線による制御停止を確認したりする「高リスクテスト」が極めて安全かつ迅速に行えます。

### ② 実機フライトコードへの移植バグを根絶する「関心の分離」
*   **シミュレータ構造の設計根拠**:
    物理演算（Plant）と制御ロジック（Controller）を同一のプログラムスペースに混ぜてしまうと、実機マイコンへのポーティング時に「シミュレータ用の時刻更新」や「状態ロギング」のコードを取り除く手間が発生し、バグの温床となります。
    候補Bを採用し、`plant.py` と `controller.py` を論理的に分離することで、`controller.py` のコード構造を実機 C++ の `main.cpp`/`control.cpp` と完全に一致（対称）させ、安全かつ速やかな移植を保証する「型」を提供しています。

---

## 4. 合理的なブラックボックス化 (Rational Black-Boxing)

### ① 物理数値積分ソルバー（差分方程式計算）のブラックボックス化
*   SILS 物理モデル（Plant）の一軸角運動方程式の計算には、ルンゲ＝クッタ法などの高度な数値積分ソルバーは自作せず、タイムステップ `dt = 5ms` に基づくシンプルな前進オイラー法（Euler integration）で近似計算を行っています。
*   **割り切りの根拠**: CanSat の姿勢制御（〜200Hz）の時間スケールに対して、5ms刻みのオイラー積分で十分な精度が得られることが事前に検証されています。ソルバーの数学的厳密性を追求するために開発資源を割くのを避け、プラントとコントローラの間のロジック検証に焦点を当てるための合理的ブラックボックス化です。

### ② 太陽の相対位置幾何計算の抽象化
*   宇宙の正確な軌道上幾何（太陽の位置ベクトル）の算出には、地球の公転軌道（ケプラー要素）や衛星の３軸軌道力学計算は導入せず、２次元平面上の「単純な光源（ライト）の角度」としてプラント内部で計算を抽象化・擬似化しています。