計算モデル¶

Graphcal プログラムは、計算の 有向非巡回グラフ (DAG) を記述します。このページでは、宣言の種類、@ シジル、評価セマンティクス、命名規約という中核となるモデルを扱います。

宣言の種類¶

すべてのトップレベル宣言は、4 つの種類のいずれかに属します。

種類	キーワード	セマンティクス	DAG に含まれる?
パラメーター	`param`	名前付きの DAG 入力ポート。省略可能なデフォルト値を持つ	はい
ノード	`node`	他の値から導出される計算値	はい
定数	`const node`	コンパイル時の不変値	いいえ
アサーション	`assert`	評価後のブール検査	いいえ

パラメーター¶

param dry_mass: Mass = 1200.0 kg;  // optional param (has default)
param fuel_mass: Mass;              // required param (no default)

param は、計算グラフ内の名前付き入力ポートを宣言します。これは、暗黙的に公開になる通常の非公開宣言ではありません。宣言の種類そのものが外部入力の役割を与えるため、 params が pub や pub(bind) を取ることはありません。

エントリー DAG の param は、--param、--params-json、または --params-json-file で供給できます。
呼び出し可能な DAG の param は、include 束縛またはインライン DAG 呼び出しで名前によって供給できます。
その有効値は、外部からも読み取り可能です。呼び出し側は include からそれを選択したり、インライン呼び出しから射影したりできます。結果は供給された束縛、または束縛が供給されなかった場合はデフォルトです。
デフォルト(= expr)を持つ param は、呼び出し側がポートを供給しない場合にその式を評価します。デフォルトは通常のランタイムグラフ式であり、 @ で params、ノード、const node を参照できます。
デフォルトのない param は必須です。必須ポートを未充足のままにするとコンパイルエラーになります。

デフォルトは、ノードと同じ依存関係グラフに参加します。これらはソース順ではなくトポロジカルな依存関係順で評価され、param のデフォルトを通る循環は、他のグラフ循環と同様に拒否されます。依存関係を上書きすると、供給されていないすべての依存デフォルトが上書きされた値から評価されます。デフォルト付きの param 自体を供給すると、その DAG インスタンスにおいてデフォルト式が置き換えられます。

param base_thrust: Dimensionless = 10.0;
param margin: Dimensionless = @base_thrust * 2.0;
node total: Dimensionless = @margin + 1.0;

ここで、base_thrust を 100.0 で上書きすると、供給されていない margin は 200.0 になります。margin 自体を上書きすると、@base_thrust * 2.0 は迂回されます。

内部の計算値には非公開の node を、内部の固定値には非公開の const node を使用してください。サブ計算に内部のパラメーター化が必要な場合は、「内部 param」という命名規約を使うのではなく、非公開の DAG またはモジュール境界の背後に置いてください。

パラメーター(およびノード)は、有効な値の範囲を宣言する ドメイン制約 を持つことができ、ランタイムで検査されます。

param bus_mass: Mass(min: 100.0 kg, max: 2000.0 kg) = 500.0 kg;

詳細は型システム — ドメイン制約を参照してください。

ノード¶

node total_mass: Dimensionless = @dry_mass + @fuel_mass;

ノードは計算値です。その式は、パラメーター、他のノード、定数を参照できます。Graphcal は、依存関係グラフによって決まるトポロジカル順序でノードを評価します。

未完成のノード¶

式を書く前に依存関係グラフを設計するには、ノード全体を todo で定義します。

param isp: Time = 320.0 s;
const node g0: Acceleration = 9.80665 m/s^2;
node v_exhaust: Velocity = todo { @isp, @g0 };
node mass_ratio: Dimensionless = 3.0;
node delta_v: Velocity = @v_exhaust * ln(@mass_ratio);

型の明示は必須です。波括弧には、そのノードが未完成である間に直接依存する可能性のある宣言をすべて列挙します。間接的な依存先を列挙する必要はありません。依存先がない場合は todo {} と明示します。参照には通常の名前解決、可視性、循環の検査が適用されます。定数も参照できますが、定数がランタイム DAG のノードになるわけではありません。

この例では mass_ratio は評価され、v_exhaust は TODO、delta_v は BLOCKED になります。ブロックは静的な依存関係グラフに従うため、選択されない分岐内の参照も対象です。これらの状態は値でも null でも評価エラーでもありません。todo はノード全体の定義形式であり、関数や式の一部を埋める穴ではありません。

ノードを完成させるには todo { … } を式で置き換えます。以後はその式が依存関係を決め、以前の依存関係の契約は残りません。check は、それ以外に問題のない未完成モデルを受け入れて概要を表示します（--deny-todo を指定すると拒否します）。eval は部分的な結果を表示しますが、--allow-incomplete がなければ失敗の終了コードを返します。このフラグで実際の評価エラーやアサーションの失敗が無視されることはありません。

定数¶

const node g0: Acceleration = 9.80665 m/s^2;

定数は、DAG が構築される前にコンパイル時に評価されます。パラメーターやノードを参照することはできません。DAG 呼び出しは匿名のランタイム include であるため、const node 式およびコンパイル時のドメイン境界でも禁止されています。

アサーション¶

assert fuel_positive = @fuel_mass > 0.0 kg;

アサーションは評価後の検査です。パラメーターとノードを参照できますが、DAG の一部ではありません。他のどの宣言も assert を参照できません。アサーションは常に、グラフ全体の後に最後に評価されます。詳細はアサーションと属性を参照してください。

`@` シジル¶

@ プレフィックスは、中心的なスコープ機構です。

参照	意味	使用可能な場所
`@name`	グラフ内のパラメーター、ノード、または const node	`node` 式、param のデフォルト、`dag` ブロック本体
`@dag(args)::out`	1 つの出力を射影するランタイム DAG インスタンス化	param のデフォルトを含むランタイム式
`NAME`	組み込み定数(`PI`、`E`、`TAU` など)	あらゆる場所
`name`	ローカル変数(ループ変数、match 束縛)	式本体

すべてのユーザーグラフ宣言は、const node の値を含め、@ を必要とします。マーカーのない識別子が param、node、const node を指すことは決してなく、シジルの省略はコンパイルエラーです。これにより、すべてのランタイムおよびコンパイル時の依存関係エッジが明示的に保たれ、スケジューリングと循環検出は、ソースが表現するのと同じグラフを見ることになります。

UTC や TT のような時間スケールの綴りは、別個の静的名前空間に存在します。グラフ宣言はそれらを再利用できます。@UTC はグラフ値を選択し、 Datetime<UTC> と epoch<UTC>(...) は時間スケールを選択します。通常の値式におけるマーカーなしの UTC は、引き続き型エラーです。E や PI のような組み込み数値定数は異なります。これらの綴りはグラフ名前空間で予約されたままです。そうでなければ、 @ の欠落が有効な数値を黙って選択してしまう可能性があるためです。

`@` が許可される場所¶

コンテキスト	`@` 使用可能?
`node` 式	はい
`param` のデフォルト値	はい
`const node` 式	いいえ
`dag` ブロック本体(`node` 式の内部)	はい

評価順序¶

パース -- ソースファイルが AST にパースされます
解決 -- インポートが読み込まれ、参照が解決されます
次元検査 -- すべての式の次元整合性が検査されます
定数評価 -- 定数が依存関係順に評価されます
DAG 構築 -- param のデフォルトと node 宣言から依存関係グラフが構築されます
トポロジカル評価 -- 供給されていない param のデフォルトとノードが依存関係順に評価されます
アサーション検査 -- assert 宣言が評価され、報告されます

循環検出¶

ノードと param のデフォルトの間の循環依存は、コンパイル時に検出されます。

node a: Dimensionless = @b + 1.0;
node b: Dimensionless = @a + 1.0;  // ERROR: cycle detected

呼び出し箇所の同一性¶

dag がインスタンス化されるとき、トップレベルの include によるか、インラインの @dag(args)::out 式形式によるかにかかわらず、各 構文上の呼び出し箇所 は新しいインスタンス化です。同一の引数を持つテキスト上異なる 2 つの出現は、基盤となる DAG において共有されたサブグラフではなく、2 つの別個のサブグラフを表します。プログラムは、呼び出し箇所をまたぐ共有に依存してはなりません。

障害の分離¶

ノードの評価が失敗した場合(例: ゼロ除算)、影響を受けるのはそのノードと、それに依存するノードだけです。独立したノードは引き続き正常に評価されます。

命名規約¶

Graphcal は、以下の命名規約を推奨します。

宣言	推奨される規約	例
`param`	`lower_snake_case`	`dry_mass`
`node`	`lower_snake_case`	`total_dv`
`const node`	`lower_snake_case`	`g0`、`margin_factor`
`assert`	`lower_snake_case`	`fuel_positive`
`dag`	`lower_snake_case`	`orbital_velocity`
`type`	`PascalCase`	`TransferResult`
`dim`	`PascalCase`	`Velocity`
`index`	`PascalCase`	`Maneuver`
`unit`	(さまざま)	`km`、`kN`、`MPa`

これらの規約はコンパイラーによって強制されませんが、一貫性と可読性のために従うことを強く推奨します。

コメント¶

Graphcal は行コメントをサポートします。

// This is a comment
param mass: Mass = 100.0 kg;  // inline comment

/// ドキュメントコメントは、それに続く宣言を文書化します。ドキュメントブロックは、宣言の直上に置かれた連続する /// 行の並びです(間に空行や // コメントを挟みません)。先頭の属性があっても、それを越えて宣言に付加されます。ドキュメントコメントはプログラムのセマンティクスを決して変更しません。エディターのホバー (LSP) や、生成された出力のキャプションとして表示されます。

/// Specific impulse of the qualified engine.
param isp: Time = 320.0 s;

////(4 つ以上のスラッシュ)は通常の行コメントであり、コード行の末尾に置かれた /// コメントは何も文書化しないことに注意してください。