# 機能設計書 133-exp

## 概要

本ドキュメントは、Hack Standard Library (HSL) の Math 名前空間における `exp` 関数の機能設計書である。この関数は、ネイピア数（自然対数の底）e を指定した指数でべき乗した値を計算して返す指数関数である。

### 本機能の処理概要

**業務上の目的・背景**：
指数関数 e^x は数学・科学・工学において最も基本的かつ重要な関数の一つである。複利計算、人口増加モデル、放射性崩壊、電子回路の過渡応答、確率分布など、あらゆる分野で必要とされる。`Math\exp` 関数は、Hack 言語において型安全かつ直感的なインターフェースで指数関数を計算する手段を提供する。HHVM 組み込みの `\exp` 関数をラップし、HSL の統一的な API 設計に従った形で提供することで、開発者の利便性を高めている。

**機能の利用シーン**：
- 複利計算や連続複利の計算
- 確率分布（正規分布、ポアソン分布など）の計算
- 機械学習におけるソフトマックス関数やシグモイド関数の実装
- 物理シミュレーションにおける減衰・成長モデルの計算
- 信号処理における周波数解析

**主要な処理内容**：
1. 入力値（num 型）を受け取る
2. 入力値を float 型にキャストする
3. 組み込みの `\exp` 関数を呼び出して e^x を計算する
4. 計算結果（float 型）を返す

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

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

## 関連画面

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

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $arg | num | Yes | e のべき乗の指数 | なし（任意の数値を受け入れる） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | float | e^$arg の値（0より大きい正の数） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 引数 $arg を受け取る
   └─ num 型（int または float）の値を受け取る
2. float 型へのキャスト
   └─ (float)$arg で明示的に float に変換
3. 組み込み \exp 関数の呼び出し
   └─ HHVM の組み込み指数関数で計算を実行
4. 計算結果を返す
   └─ float 型の e^$arg を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[引数 $arg を受け取る]
    B --> C[$arg を float にキャスト]
    C --> D[組み込み \exp 関数を呼び出し]
    D --> E[e^$arg を返す]
    E --> F[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 自然指数 | 底は常に e（≈ 2.718281828）である | 常に適用 |
| BR-002 | 純粋関数 | 同じ入力に対して常に同じ出力を返す | 常に適用 |
| BR-003 | 型変換 | int 型の入力も自動的に float に変換される | 常に適用 |
| BR-004 | 正の出力 | 出力値は常に正の数（> 0） | 常に適用 |

### 計算ロジック

指数関数は以下の数学的定義に基づく：
- exp(0) = 1
- exp(1) = e ≈ 2.718281828
- exp(-1) = 1/e ≈ 0.367879441
- exp(x) × exp(y) = exp(x + y)
- exp(x) は単調増加関数

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 本関数はエラーをスローしない | - |

### リトライ仕様

該当なし（エラーが発生しないため）

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

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

## パフォーマンス要件

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

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

純粋関数として実装されており、副作用がないため、セキュリティ上のリスクはない。入力値のバリデーションは不要であり、任意の数値入力に対して安全に動作する。非常に大きな正の入力値に対しては INF（無限大）が返される可能性がある。

## 備考

- `Math\log` 関数は逆関数として使用可能（exp と log は互いに逆関数）
- 底が e 以外の指数計算が必要な場合は、`$base ** $exp` 演算子または `Math\log` との組み合わせで実現可能
- e の値は `Math\E` 定数として定義されている（src/math/constants.php）

---

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

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

### 推奨読解順序

#### Step 1: 定数定義を理解する

まず、Math 名前空間で定義されている定数を理解することで、exp 関数の数学的基盤を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.php | `src/math/constants.php` | E 定数（30行目）の定義を確認。e ≈ 2.7182818284590452354 として定義されている |

**読解のコツ**: `Math\E` として外部からアクセス可能。この値が exp(1) の戻り値と一致する。

#### Step 2: exp 関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compute.php | `src/math/compute.php` | exp 関数の実装（170-172行目）を確認。シンプルなラッパー実装を理解する |

**主要処理フロー**:
1. **165-169行目**: 関数のドキュメントコメント - log 関数への参照を含む
2. **170行目**: 関数シグネチャ `function exp(num $arg)[]: float` - num 型を受け取り float を返す純粋関数として定義
3. **171行目**: `return \exp((float)$arg);` - 入力を float にキャストして組み込み関数を呼び出し

#### Step 3: 関連する関数（逆関数）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compute.php | `src/math/compute.php` | log 関数（203-211行目）の実装を確認。exp と log の関係性を理解する |

**読解のコツ**: exp と log は互いに逆関数であり、log(exp(x)) = x、exp(log(x)) = x の関係がある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MathComputeTest.php | `tests/math/MathComputeTest.php` | provideTestExp メソッド（228-235行目）とtestExp メソッド（237-241行目）を確認。期待される動作を理解する |

**主要処理フロー**:
- **229-234行目**: テストケースの定義 - exp(-1)=1/e, exp(0)=1, exp(1)=e, exp(2)=e^2 を検証
- **238-241行目**: テスト実行とアサーション - `toAlmostEqual` による浮動小数点比較

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

```
Math\exp($arg)
    │
    └─ \exp((float)$arg)
           └─ HHVM 組み込み exp 関数
```

### データフロー図

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

num $arg ───▶ (float)$arg キャスト ───▶ float e^$arg
                    │
                    ▼
            \exp() 組み込み関数
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | exp 関数の実装ファイル（三角関数・指数関数などの計算関数群） |
| constants.php | `src/math/constants.php` | ソース | E 定数の定義（自然対数の底） |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | exp 関数を含む計算関数のユニットテスト |
