設計方針¶
SOPRANの公開APIと内部実装を決めるときの基準です。新しい機能やデータ源を加えるときは、この方針に沿っているかを確かめてください。 ここにある規則は現在の実装が守っているもので、決まっている予定と未実装の構想は最後の2節に分けています。
目指す使い心地¶
- データに詳しくなくても、使ううちに構造と意味が分かる。
spn.kaguya.esa1.energy_fluxはミッション・機器・物理量の順に並び、 型・補完・info()・単位・座標系・時間とエネルギーと視線のビンも同じ構造にそろえます。 ファイル形式や配布サーバー、Rust実装の都合を物理量の名前に持ち込みません。 - 標準の入口から図まで一続きに進める。
plot(time)のような短い入口で、取得・校正・保存・再読み込みを経て、 軸とカラーバーに物理量と単位のある図にたどり着けるようにします。自動化しても、適用した補正・入力ファイル・設定・処理履歴は後から確かめられるようにし、 欠測やモデルの不適合を別の値に置き換えません。 - 元ファイルと元の観測ビンへ戻れる。 加工した結果だけに閉じ込めず、出典ファイル（
files）と、 校正・再ビン化・時間積分の前の記録（PACEのpaceなど）を読み込み結果に残します。
APIの契約¶
- 属性を取り出すのは探索だけ。 ミッション・機器・変数・月面マップの属性は軽いオブジェクトを返し、 ダウンロード・デコード・スキャン・計算を起こしません。
- 処理が始まる点を限る。
load()はデータを読み、compute()は入力から派生量を作り、plot()は図を作ります。 Pipelineではrun()・collect()・scan()・stream()です。エンドポイントのplot(time)は読み込みを伴う便利な入口で、 条件を記録して残す成果物にはquicklook()を使います。 - どの階層でも同じ探索の手段を持つ。
info()（短い説明）、guide()（詳しい説明）、schema()（機械可読な定義）、plan()（実行前の計画）、example()（試せる例）です。 - 意味の分かる名前を正式名にする。
energy_flux、magnetic_fieldのような名前をドキュメント・図のラベル・スキーマの主表記にし、eflux、bなどの短い名前は別名としてinfo()に示します。仕様に無い別名は増やしません。 - 型・単位・座標系・時刻・ビンを付けて返す。 外部ライブラリとの型の境界を明確にし、
Anyを連鎖させません。 - 設定は一か所で解決する。 プロセスの既定は
spn.config.use()、一時的な変更はspn.config.using()で、 それ以外は既存の設定・Project・Viewを通して解決します。Storeのルートはresolve_store_roots()、ダウンロード方針はresolve_download_mode()だけが決め、どの入口から使っても同じ結果になります。Storeを作っただけでグローバルな設定を変えたり、 機器ごとに別のグローバルな状態を作ったりしません。 - データ源は登録で増やす。 ミッションと天体はそれぞれのパッケージで
register_source()により登録し、coreはミッションをimportしません（データ源を追加する）。
スキーマをコードに持つ¶
変数の名前・次元・単位・データ型・座標系・別名はInstrumentSchema・VariableSchemaとしてコードに書きます。
info()、検証（validate_schema）、Storeのschema.json、図の軸ラベルと既定の対数表示（log_scale・log_dims）、
スキーマのページはすべてここから作り、手書きの表や変数名ごとの特別扱いとのずれを防ぎます。
保存と再現性¶
- 加工したデータは既存のプロダクトとキャッシュの仕組みで保存・再読み込みします。キャッシュのキーは設定と入力の内容から作り、 設定の違う結果を同じ項目として再利用しません。
- ファイルの探索はStore・レイアウト・取得元を経由し、計算機固有の絶対パスをパッケージに埋め込みません。
- Storeは
rsyncで運べる形に保ちます。マニフェストとカタログにはルートからの相対パスだけを書き、シャードの付属JSONを正本にします （Storeを別マシンへ運ぶ）。 - 欠測・ゼロ・未取得・校正の状態・品質フラグを区別して返します。
- 保存したデータセットのスキーマは、公開API以上に慎重に変えます。互換性を壊す変更ではスキーマの版を上げます。
依存関係¶
import sopranに必要なのはnumpyとpandasだけです。ミッション・地図・可視化の依存は用途別のextraに分け、
その経路に入ったときに遅延importします。各extraにはSOPRANが実際にimportするパッケージだけを入れ、
この一致をtests/test_project_metadata.pyで確かめます。依存とビルドの設定はpyproject.tomlが正本です。
既存のライブラリを使う¶
時刻系の変換、天体暦と姿勢、標準的な座標変換、CDF・PDSなどの汎用の読み込み、単位の換算は自作しません。
| 領域 | 使うライブラリ |
|---|---|
| 天体・探査機の幾何、座標変換 | spiceypy |
| 地球周辺の座標系（GSE・GSM・SM） | spacepy（予定） |
| CDF | cdflib |
| 地図・DEM | rasterio |
| 表・Parquet | polars、pyarrow |
| 多次元配列 | xarray |
| 図 | matplotlib、panel |
自作してよいのは、ミッション固有のバイナリのデコード、配布元のメタデータの不具合の補正、既存ライブラリに無い機器の校正、 性能のためのRustへの移植です。その場合も、外部ライブラリか公式仕様と比べるテストを置きます。 SPEDASの挙動に合わせる場合は、出典・単位・補正条件を記録します（ライセンスと移植）。
Rust拡張の境界¶
重い決定的な処理（PACEのデコード、ピッチ角の集計、ERの当てはめ、磁力線の追跡）は、同梱のRust拡張sopran._nativeに任せます。
- 記録やビンごとにPythonとRustを往復せず、ファイル群・配列・問題・バッチの単位でまとめて渡します。
- 結果は通常のPythonの型で返し、日常のAPIで利用者にFFIを意識させません。
- 再現性と不具合の調査のため、使ったバックエンドの名前と設定を記録します。
- Rust化の前にPythonの参照実装か公式仕様と小さなgolden出力で一致を確かめ、黙ってPython版へ切り替わらないようにします。
試作の隔離¶
未確定のモデルや解析手順はsopran.experimentalに置き、通常APIから依存しません。試作にも型・単位・テストを付け、
Storeのキーを通常のプロダクトと分けます。未公開APIの互換の別名や移行用のshimは作りません。
個別の研究の計算・比較の図・考察はworking/に置き、公開ドキュメントには入れません（試作API）。
パッケージの構成¶
| 場所 | 役割 |
|---|---|
src/sopran/core/ |
Store、設定、Project・Case・View、データ型、Pipeline、作図、時刻合わせ |
src/sopran/missions/ |
KAGUYA・ARTEMIS・Lunar Prospector・OMNIの読み込み、機器、プロダクトのAPI |
src/sopran/bodies/moon/ |
DEM・影・SVMなどの月面のプロダクト |
src/sopran/frames/、src/sopran/maps/ |
座標・時刻の変換、地図の共通の型 |
src/sopran/experimental/ |
明示的にimportする試作 |
crates/sopran-native/ |
Rust拡張sopran._native |
tests/ |
合成データとfixtureを中心にした回帰テスト |
scripts/hpc/ |
スーパーコンピューター用の環境構築とジョブの雛形 |
docs/ |
公開ドキュメント（ドキュメントの書き方） |
例外とエラーメッセージ¶
例外はすべてSopranErrorの下にあり、標準の例外も継承しています。
| 例外 | 継承 | 場面 |
|---|---|---|
ConfigError |
ValueError |
設定の値が不正 |
DatasetNotFoundError |
LookupError |
データセットや元ファイルが見つからない |
DownloadError |
OSError |
取得に失敗した |
DecodeError |
ValueError |
ファイルを解読できない |
SchemaError |
ValueError |
次元・データ型・単位・座標系がスキーマと合わない |
FrameTransformError |
ValueError |
座標変換の条件が足りない、または未対応 |
PipelineError |
RuntimeError |
Pipelineの実行部が無い、または対応しない操作 |
BackendError |
RuntimeError |
バックエンドを使えない |
エラーメッセージには、失敗したエンドポイントやデータセットID、使える候補、次に試す呼び出し（info()やplan()）、
取得・デコード・スキーマ・座標変換のどの段階で失敗したかを、分かる範囲で含めます。
今後の予定¶
次の項目は追加することが決まっています。着手するときは、この方針に沿って設計を決めます。
| 項目 | 内容 | 主な作業 |
|---|---|---|
| Chandrayaan-1 SARA（SWIM・CENA） | ESA PSAのPDS3。2008〜2009年でKAGUYAと期間が重なり、同時期の比較ができる | 公開されているのは生の計数（EDR）なので、校正を自前で用意する |
| Wind SWE・MFI | CDAWebのCDF。OMNIの元になっている上流の太陽風の観測 | ARTEMISと同じ取得の仕組み（SPDFの一覧から最新版を選ぶ）を使う |
| LRO DivinerのGCP | PDSの地方時ごとの表面輝度温度（ボロメトリック）。表面帯電や外気圏の解析に使う | 月面マップの一つとして、地方時を持つ格子で返す |
| Lunar Prospector ERの拡張 | ピッチ角と、高時間分解能のER（ER_HI_TS） |
ピッチ角は視線方向の符号の約束を文献で確認してから加える |
| ARTEMISの拡張 | 品質フラグと月中心の位置 | 品質フラグは*_data_qualityを読む |
構想¶
次の項目は構想の段階で、実装を約束していません。
- 対話的な作図（HoloViews・hvPlot・Datashader）と、長期間のクイックルック。
spacepy・astropyによる座標変換のバックエンド。- 月面マップの投影変換、半影を含む影、
terrain_rayの高速化。 - ミッションに依存しない汎用のPipelineの実行部と、Rustの処理段の接続。
- PACEの視線方向とエネルギーの座標情報の保存。