# 機能設計書 135-sqrt

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Math 名前空間における `sqrt` 関数の機能設計書である。この関数は、与えられた非負の数値の平方根を計算して返す。

### 本機能の処理概要

**業務上の目的・背景**：
平方根は数学・科学・工学において基本的な演算の一つである。距離計算（ユークリッド距離）、標準偏差の計算、物理シミュレーション、グラフィックス処理など、様々な場面で必要とされる。`Math\sqrt` 関数は、Hack 言語において型安全かつ安全なインターフェースで平方根計算を提供する。負の数が入力された場合には例外をスローすることで、数学的に不正な操作を防止している。

**機能の利用シーン**：
- 2D/3D 空間における距離計算（ピタゴラスの定理）
- 統計計算における標準偏差・分散の計算
- 物理シミュレーションにおける速度・加速度の計算
- グラフィックス処理における法線ベクトルの正規化
- 機械学習における L2 正則化

**主要な処理内容**：
1. 入力値（num 型）を受け取る
2. 入力値が非負であることを検証する
3. 組み込みの `\sqrt` 関数を呼び出して平方根を計算する
4. 計算結果（float 型）を返す

**関連システム・外部連携**：
本機能は純粋な数学演算関数であり、外部システムとの連携はない。HHVM ランタイムの組み込み `\sqrt` 関数に依存する。

**権限による制御**：
本機能は純粋関数（pure function）として実装されており、副作用がなく、権限による実行制御は不要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本プロジェクト（Hack Standard Library）はUIを持たないライブラリプロジェクトのため、画面機能マッピングは該当しない |

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $arg | num | Yes | 平方根を計算する非負の数値 | $arg >= 0 であること（違反時に InvariantException） |

### 入力データソース

関数呼び出し時の引数として直接指定される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | float | 入力値の平方根（非負の値） |

### 出力先

関数の戻り値として呼び出し元に返される。

## 処理フロー

### 処理シーケンス

```
1. 引数 $arg を受け取る
   └─ num 型（int または float）の値を受け取る
2. バリデーション
   └─ $arg >= 0 でない場合、InvariantException をスロー
3. float 型へのキャスト
   └─ (float)$arg で明示的に float に変換
4. 組み込み \sqrt 関数の呼び出し
   └─ HHVM の組み込み平方根関数で計算を実行
5. 計算結果を返す
   └─ float 型の平方根を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数 $arg を受け取る]
    B --> C{$arg >= 0?}
    C -->|No| D[InvariantException をスロー]
    C -->|Yes| E[$arg を float にキャスト]
    E --> F[組み込み \sqrt 関数を呼び出し]
    F --> G[平方根を返す]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 非負入力 | 入力値は 0 以上の数値のみ有効 | 常に適用 |
| BR-002 | 純粋関数 | 同じ入力に対して常に同じ出力を返す | 常に適用 |
| BR-003 | 型変換 | int 型の入力も自動的に float に変換される | 常に適用 |
| BR-004 | 非負出力 | 出力値は常に 0 以上 | 常に適用 |

### 計算ロジック

平方根関数は以下の数学的定義に基づく：
- sqrt(0) = 0
- sqrt(1) = 1
- sqrt(4) = 2
- sqrt(x) = y の場合、y^2 = x
- sqrt(2) = M_SQRT2 ≈ 1.41421356
- sqrt(3) = M_SQRT3 ≈ 1.73205081

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない純粋な計算関数である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | $arg < 0 の場合 | 非負の数値を入力する |

### リトライ仕様

該当なし（入力値を修正することで解決）

## トランザクション仕様

該当なし（データベース操作を行わないため）

## パフォーマンス要件

HHVM 組み込みの `\sqrt` 関数をラップしているため、オーバーヘッドは最小限である。バリデーション処理が含まれるが、計算量は O(1) であり、入力値のサイズに関係なく一定時間で処理が完了する。

## セキュリティ考慮事項

純粋関数として実装されており、副作用がないため、セキュリティ上のリスクはない。入力値のバリデーションが含まれており、負の数が入力された場合は InvariantException がスローされる。

## 備考

- 定数 `M_SQRT2`（√2）、`M_SQRT3`（√3）が PHP/HHVM で定義されており、テストで使用されている
- 複素数の平方根は本関数ではサポートされていない
- 距離計算など複数の二乗和の平方根が必要な場合は、`Math\sqrt($x*$x + $y*$y)` のように使用する

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: sqrt 関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | sqrt 関数の実装（233-239行目）を確認。バリデーションとラッパー実装を理解する |

**主要処理フロー**:
1. **233-235行目**: 関数のドキュメントコメント - シンプルな説明
2. **236行目**: 関数シグネチャ `function sqrt(num $arg)[]: float` - num 型を受け取り float を返す純粋関数として定義
3. **237行目**: バリデーション `invariant($arg >= 0, ...)` - 非負値チェック
4. **238行目**: `return \sqrt((float)$arg);` - 入力を float にキャストして組み込み関数を呼び出し

**読解のコツ**: `invariant()` は Hack の組み込み関数で、条件が false の場合に InvariantException をスローする。

#### Step 2: テストケースを確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | MathComputeTest.php | `tests/math/MathComputeTest.php` | provideTestSqrt メソッド（446-454行目）とtestSqrt メソッド（456-460行目）を確認。期待される動作を理解する |
| 2-2 | MathComputeTest.php | `tests/math/MathComputeTest.php` | testSqrtException メソッド（462-464行目）を確認。エラーケースのテストを理解する |

**主要処理フロー**:
- **447-453行目**: テストケースの定義 - sqrt(16)=4, sqrt(2)=M_SQRT2, sqrt(3)=M_SQRT3, sqrt(0)=0, sqrt(1)=1
- **462-464行目**: エラーケースのテスト - sqrt(-1) で InvariantException がスローされることを確認

### プログラム呼び出し階層図

```
Math\sqrt($arg)
    │
    ├─ invariant($arg >= 0, ...)
    │      └─ 条件不満足時: InvariantException をスロー
    │
    └─ \sqrt((float)$arg)
           └─ HHVM 組み込み sqrt 関数
```

### データフロー図

```
[入力]               [処理]                              [出力]

num $arg ───▶ バリデーション ───▶ (float)$arg キャスト ───▶ float 平方根
              ($arg >= 0)              │
                  │                    ▼
                  │            \sqrt() 組み込み関数
                  │
                  └─ 失敗時: InvariantException
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | sqrt 関数の実装ファイル |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | sqrt 関数を含む計算関数のユニットテスト |
