# 機能設計書 31-対数・指数関数

## 概要

本ドキュメントは、Nushellにおける対数・指数関数機能（math log, math exp, math ln, math sqrt）の設計を記述する。これらのコマンドは数値データに対する数学的な対数・指数・平方根計算を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
科学技術計算、データ分析、統計処理などにおいて、対数・指数計算は基本的な数学演算として不可欠である。Nushellはシェルとしてデータ処理パイプラインを構築できるため、これらの数学関数を組み込みで提供することで、外部ツールに依存せずに数値計算を行える環境を実現する。

**機能の利用シーン**：
- データ分析において対数スケールでの変換が必要な場合
- 指数関数的な成長・減衰のモデリング
- 統計計算における平方根の算出
- 自然対数を用いた数学的計算

**主要な処理内容**：
1. `math log`: 任意の底に対する対数を計算する
2. `math exp`: 自然対数の底eの累乗を計算する（nu-cmd-extraで提供）
3. `math ln`: 自然対数（底がe）を計算する（nu-cmd-extraで提供）
4. `math sqrt`: 平方根を計算する

**関連システム・外部連携**：
- nu-command クレート（math log, math sqrt）
- nu-cmd-extra クレート（math exp, math ln）
- nu-protocol クレートの型システム

**権限による制御**：
特になし。すべてのユーザーが実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 参照画面 | コマンド入力・結果表示 |

## 機能種別

計算処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| input | Number/List<Number>/Range | Yes | 計算対象の数値 | 数値型（Int/Float）であること |
| base (math log) | Number | Yes | 対数の底 | 0より大きい値 |

### 入力データソース

パイプラインからの数値入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | Float | 計算結果（浮動小数点数） |

### 出力先

パイプライン出力（次のコマンドへ）

## 処理フロー

### 処理シーケンス

```
1. 入力値の取得
   └─ パイプラインから数値またはリストを受け取る
2. 入力バリデーション
   └─ 空入力、非数値型のチェック
3. 引数バリデーション（math logの場合）
   └─ 底が0以下でないことを確認
4. 数学計算の実行
   └─ Rustの標準ライブラリを使用して計算
5. 結果の返却
   └─ Float型として結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{入力が空?}
    B -->|Yes| C[PipelineEmptyエラー]
    B -->|No| D{入力型チェック}
    D -->|数値| E{引数チェック}
    D -->|非数値| F[型エラー]
    E -->|OK| G[数学計算実行]
    E -->|NG| H[引数エラー]
    G --> I{計算可能?}
    I -->|Yes| J[結果を返却]
    I -->|No| K[計算エラー]
    J --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-31-1 | 対数の定義域 | math logは0以下の値に対してエラー | 入力値が0以下 |
| BR-31-2 | 底の制約 | math logの底は0より大きい必要がある | 底が0以下 |
| BR-31-3 | 平方根の定義域 | math sqrtは負の値に対してNaNを返さずエラー | 入力値が負 |
| BR-31-4 | 自然対数の定義域 | math lnは0以下の値に対してエラー | 入力値が0以下 |

### 計算ロジック

- `math log base`: log_base(x) = ln(x) / ln(base)
- `math exp`: e^x
- `math ln`: 自然対数 ln(x)
- `math sqrt`: 平方根 sqrt(x)

特殊な最適化：
- 底が10の場合：`val.log10()`を使用（高精度・高速）
- 底が2の場合：`val.log2()`を使用（高精度・高速）

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

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

該当なし（データベース操作を行わない純粋な計算機能）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PipelineEmpty | 入力エラー | パイプライン入力が空 | 数値を入力する |
| UnsupportedInput | 入力エラー | 対数の値が0以下、または底が0以下 | 正の値を使用 |
| OnlySupportsThisInputType | 型エラー | 数値以外の型が入力された | 数値型を入力 |
| NegativeSqrt | 計算エラー | 平方根に負の値が入力された | 非負の値を使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 単一数値の計算は即座に完了
- リストに対する処理はmap関数により効率的に実行

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

特になし

## 備考

- math exp と math ln は nu-cmd-extra クレートで提供され、追加機能として位置づけられる
- math log と math sqrt は nu-command クレートで提供され、コア機能として位置づけられる
- すべてのコマンドはconst実行をサポートする（コンパイル時評価可能）

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

数値型の処理パターンを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | value.rs | `crates/nu-protocol/src/value/mod.rs` | Value::Int, Value::Float の定義 |

**読解のコツ**: RustのEnum型でValue型が定義されており、Int/Floatの2つの数値型を持つ。

#### Step 2: エントリーポイントを理解する

各コマンドのCommand trait実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | log.rs | `crates/nu-command/src/math/log.rs` | MathLogコマンドの実装 |
| 2-2 | sqrt.rs | `crates/nu-command/src/math/sqrt.rs` | MathSqrtコマンドの実装 |
| 2-3 | exp.rs | `crates/nu-cmd-extra/src/extra/math/exp.rs` | MathExpコマンドの実装 |
| 2-4 | ln.rs | `crates/nu-cmd-extra/src/extra/math/ln.rs` | MathLnコマンドの実装 |

**主要処理フロー**:
1. **44-58行目 (log.rs)**: run関数で入力値を受け取り、底のパラメータを取得
2. **98-118行目 (log.rs)**: log関数で底の検証と計算実行
3. **120-164行目 (log.rs)**: operate関数で実際の対数計算

#### Step 3: 計算ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | log.rs | `crates/nu-command/src/math/log.rs` | operate関数の計算処理 |

**主要処理フロー**:
- **143-149行目**: 底による最適化（底10の場合log10、底2の場合log2を使用）
- **130-141行目**: 入力値が0以下の場合のエラーハンドリング

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

```
MathLog::run()
    │
    ├─ call.req() [底パラメータの取得]
    │
    ├─ ensure_bounded() [Range入力の境界チェック]
    │
    └─ log()
           │
           └─ input.map(operate) [各値に対して計算]
                  │
                  └─ val.log() / val.log10() / val.log2()
```

### データフロー図

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

数値/リスト ───▶ MathLog::run() ───▶ Float/List<Float>
    │                  │
    │                  ├─ 底パラメータ検証
    │                  │
    │                  ├─ 入力値検証
    │                  │
    │                  └─ 対数計算
    │
底(f64) ────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| log.rs | `crates/nu-command/src/math/log.rs` | ソース | math log コマンド実装 |
| sqrt.rs | `crates/nu-command/src/math/sqrt.rs` | ソース | math sqrt コマンド実装 |
| exp.rs | `crates/nu-cmd-extra/src/extra/math/exp.rs` | ソース | math exp コマンド実装 |
| ln.rs | `crates/nu-cmd-extra/src/extra/math/ln.rs` | ソース | math ln コマンド実装 |
| mod.rs | `crates/nu-command/src/math/mod.rs` | ソース | mathモジュール定義 |
| utils.rs | `crates/nu-command/src/math/utils.rs` | ソース | 共通ユーティリティ（ensure_bounded等） |
