# 機能設計書：50-complex

## 1. 概要

### 機能名
complex - 複素数モジュール

### 目的
複素数とその基本的な数学演算を実装するモジュール。実部（real part）と虚部（imaginary part）からなる複素数を提供し、四則演算、三角関数、双曲線関数、指数・対数関数、極座標変換などの複素数演算を実装する。

### 関連画面
- 該当なし（ライブラリモジュール）

### 機能種別
- [x] ライブラリ
- [ ] バッチ
- [ ] 画面
- [ ] API
- [ ] イベント

## 2. 入力仕様

### 複素数生成パラメータ
| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
|-------------|-----|------|-----------|------|
| re | T (SomeFloat) | Yes | - | 実部 |
| im | T (SomeFloat) | No | 0.0 | 虚部 |

### 極座標パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| r | T | Yes | 絶対値（半径） |
| phi | T | Yes | 偏角（ラジアン） |

## 3. 出力仕様

### 複素数結果
| 項目 | 型 | 説明 |
|------|-----|------|
| 複素数 | Complex[T] | 実部と虚部を持つ複素数 |
| 絶対値 | T | 原点からの距離 |
| 偏角 | T | 正の実軸からの角度（ラジアン） |
| 極座標 | tuple[r, phi: T] | 絶対値と偏角のタプル |
| 文字列 | string | "(re, im)" または "(re+imj)" 形式 |

## 4. 型定義

### Complex型（38-45行目）
```nim
type
  Complex*[T: SomeFloat] = object
    ## 複素数。実部 re と虚部 im から構成される。
    re*, im*: T
  Complex64* = Complex[float64]
    ## 64ビット浮動小数点数を使用した複素数のエイリアス
  Complex32* = Complex[float32]
    ## 32ビット浮動小数点数を使用した複素数のエイリアス
```

## 5. 処理フロー

### 5.1 複素数乗算

```
[x * y: Complex[T]]
    │
    ├── result.re = x.re * y.re - x.im * y.im
    │
    └── result.im = x.im * y.re + x.re * y.im
```

### 5.2 複素数除算

```
[x / y: Complex[T]]
    │
    ├── conj = conjugate(y)  # (y.re, -y.im)
    │
    ├── abs2 = y.re² + y.im²
    │
    └── result = (x * conj) / abs2
```

### 5.3 複素数平方根

```
[sqrt(z: Complex[T])]
    │
    ├── [z == 0] ── return z
    │
    ├── x = abs(z.re), y = abs(z.im)
    │
    ├── [x >= y]
    │       r = y / x
    │       w = sqrt(x) * sqrt(0.5 * (1 + sqrt(1 + r²)))
    │
    ├── [x < y]
    │       r = x / y
    │       w = sqrt(y) * sqrt(0.5 * (r + sqrt(1 + r²)))
    │
    └── [z.re >= 0]
            result = (w, z.im / (2w))
        [z.re < 0]
            result.im = ±w (符号はz.imに依存)
            result.re = z.im / (2 * result.im)
```

### 5.4 複素数べき乗

```
[pow(x, y: Complex[T])]
    │
    ├── [x == 0]
    │       [y == 0] ── return 1
    │       [else] ── return 0
    │
    ├── [y.im == 0] (実数指数)
    │       [y.re == 1] ── return x
    │       [y.re == -1] ── return 1/x
    │       [y.re == 2] ── return x*x
    │       [y.re == 0.5] ── return sqrt(x)
    │       [x.im == 0] ── return pow(x.re, y.re) (実数べき乗)
    │       [else] ── 極座標を使用して計算
    │
    ├── [x == E] (オイラーの公式)
    │       return exp(y)
    │
    └── [else] (一般的なケース)
            rho = abs(x)
            theta = arctan2(x.im, x.re)
            s = pow(rho, y.re) * exp(-y.im * theta)
            r = y.re * theta + y.im * ln(rho)
            result = (s * cos(r), s * sin(r))
```

### 5.5 極座標変換

```
[直交座標 → 極座標]
    z = (re, im)
        │
        ├── r = sqrt(re² + im²)  # abs(z)
        │
        └── phi = arctan2(im, re)  # phase(z)


[極座標 → 直交座標]
    (r, phi)
        │
        ├── re = r * cos(phi)
        │
        └── im = r * sin(phi)
```

## 6. API一覧

### 6.1 生成関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| complex | `func complex*[T: SomeFloat](re: T; im: T = 0.0): Complex[T]` | 複素数を生成 | 47 |
| complex32 | `func complex32*(re: float32; im: float32 = 0.0): Complex32` | Complex32を生成 | 51 |
| complex64 | `func complex64*(re: float64; im: float64 = 0.0): Complex64` | Complex64を生成 | 55 |
| im | `template im*(arg: typedesc[float32]): Complex32` | 虚数単位i（32bit） | 59 |
| im | `template im*(arg: typedesc[float64]): Complex64` | 虚数単位i（64bit） | 61 |
| im | `template im*(arg: float32): Complex32` | 虚数を生成（32bit） | 63 |
| im | `template im*(arg: float64): Complex64` | 虚数を生成（64bit） | 65 |
| rect | `func rect*[T](r, phi: T): Complex[T]` | 極座標から複素数を生成 | 381 |

### 6.2 変換・属性関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| abs | `func abs*[T](z: Complex[T]): T` | 絶対値（原点からの距離） | 68 |
| abs2 | `func abs2*[T](z: Complex[T]): T` | 絶対値の二乗 | 73 |
| phase | `func phase*[T](z: Complex[T]): T` | 偏角（引数） | 365 |
| polar | `func polar*[T](z: Complex[T]): tuple[r, phi: T]` | 極座標に変換 | 371 |
| conjugate | `func conjugate*[T](z: Complex[T]): Complex[T]` | 複素共役 | 88 |
| inv | `func inv*[T](z: Complex[T]): Complex[T]` | 乗法逆元（1/z） | 92 |
| sgn | `func sgn*[T](z: Complex[T]): Complex[T]` | 位相（単位複素数） | 79 |

### 6.3 算術演算子

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| == | `func \`==\`*[T](x, y: Complex[T]): bool` | 等値比較 | 96 |
| + | `func \`+\`*[T](x: T; y: Complex[T]): Complex[T]` | 実数と複素数の加算 | 100 |
| + | `func \`+\`*[T](x: Complex[T]; y: T): Complex[T]` | 複素数と実数の加算 | 104 |
| + | `func \`+\`*[T](x, y: Complex[T]): Complex[T]` | 複素数同士の加算 | 108 |
| - | `func \`-\`*[T](z: Complex[T]): Complex[T]` | 単項マイナス | 112 |
| - | `func \`-\`*[T](x: T; y: Complex[T]): Complex[T]` | 実数から複素数を減算 | 116 |
| - | `func \`-\`*[T](x: Complex[T]; y: T): Complex[T]` | 複素数から実数を減算 | 120 |
| - | `func \`-\`*[T](x, y: Complex[T]): Complex[T]` | 複素数同士の減算 | 124 |
| * | `func \`*\`*[T](x: T; y: Complex[T]): Complex[T]` | 実数と複素数の乗算 | 128 |
| * | `func \`*\`*[T](x: Complex[T]; y: T): Complex[T]` | 複素数と実数の乗算 | 132 |
| * | `func \`*\`*[T](x, y: Complex[T]): Complex[T]` | 複素数同士の乗算 | 136 |
| / | `func \`/\`*[T](x: Complex[T]; y: T): Complex[T]` | 複素数を実数で除算 | 141 |
| / | `func \`/\`*[T](x: T; y: Complex[T]): Complex[T]` | 実数を複素数で除算 | 145 |
| / | `func \`/\`*[T](x, y: Complex[T]): Complex[T]` | 複素数同士の除算 | 149 |
| += | `func \`+=\`*[T](x: var Complex[T]; y: Complex[T])` | 加算代入 | 153 |
| -= | `func \`-=\`*[T](x: var Complex[T]; y: Complex[T])` | 減算代入 | 158 |
| *= | `func \`*=\`*[T](x: var Complex[T]; y: Complex[T])` | 乗算代入 | 163 |
| /= | `func \`/=\`*[T](x: var Complex[T]; y: Complex[T])` | 除算代入 | 169 |

### 6.4 指数・対数関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| sqrt | `func sqrt*[T](z: Complex[T]): Complex[T]` | 平方根（主値） | 174 |
| exp | `func exp*[T](z: Complex[T]): Complex[T]` | 指数関数（e^z） | 198 |
| ln | `func ln*[T](z: Complex[T]): Complex[T]` | 自然対数（主値） | 205 |
| log10 | `func log10*[T](z: Complex[T]): Complex[T]` | 常用対数 | 211 |
| log2 | `func log2*[T](z: Complex[T]): Complex[T]` | 二進対数 | 218 |
| pow | `func pow*[T](x, y: Complex[T]): Complex[T]` | べき乗（x^y） | 225 |
| pow | `func pow*[T](x: Complex[T]; y: T): Complex[T]` | べき乗（複素数^実数） | 263 |

### 6.5 三角関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| sin | `func sin*[T](z: Complex[T]): Complex[T]` | 正弦 | 267 |
| arcsin | `func arcsin*[T](z: Complex[T]): Complex[T]` | 逆正弦 | 271 |
| cos | `func cos*[T](z: Complex[T]): Complex[T]` | 余弦 | 275 |
| arccos | `func arccos*[T](z: Complex[T]): Complex[T]` | 逆余弦 | 281 |
| tan | `func tan*[T](z: Complex[T]): Complex[T]` | 正接 | 285 |
| arctan | `func arctan*[T](z: Complex[T]): Complex[T]` | 逆正接 | 289 |
| cot | `func cot*[T](z: Complex[T]): Complex[T]` | 余接 | 293 |
| arccot | `func arccot*[T](z: Complex[T]): Complex[T]` | 逆余接 | 297 |
| sec | `func sec*[T](z: Complex[T]): Complex[T]` | 正割 | 301 |
| arcsec | `func arcsec*[T](z: Complex[T]): Complex[T]` | 逆正割 | 305 |
| csc | `func csc*[T](z: Complex[T]): Complex[T]` | 余割 | 309 |
| arccsc | `func arccsc*[T](z: Complex[T]): Complex[T]` | 逆余割 | 313 |

### 6.6 双曲線関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| sinh | `func sinh*[T](z: Complex[T]): Complex[T]` | 双曲線正弦 | 317 |
| arcsinh | `func arcsinh*[T](z: Complex[T]): Complex[T]` | 逆双曲線正弦 | 321 |
| cosh | `func cosh*[T](z: Complex[T]): Complex[T]` | 双曲線余弦 | 325 |
| arccosh | `func arccosh*[T](z: Complex[T]): Complex[T]` | 逆双曲線余弦 | 329 |
| tanh | `func tanh*[T](z: Complex[T]): Complex[T]` | 双曲線正接 | 333 |
| arctanh | `func arctanh*[T](z: Complex[T]): Complex[T]` | 逆双曲線正接 | 337 |
| coth | `func coth*[T](z: Complex[T]): Complex[T]` | 双曲線余接 | 341 |
| arccoth | `func arccoth*[T](z: Complex[T]): Complex[T]` | 逆双曲線余接 | 345 |
| sech | `func sech*[T](z: Complex[T]): Complex[T]` | 双曲線正割 | 349 |
| arcsech | `func arcsech*[T](z: Complex[T]): Complex[T]` | 逆双曲線正割 | 353 |
| csch | `func csch*[T](z: Complex[T]): Complex[T]` | 双曲線余割 | 357 |
| arccsch | `func arccsch*[T](z: Complex[T]): Complex[T]` | 逆双曲線余割 | 361 |

### 6.7 比較・フォーマット関数

| 関数名 | シグネチャ | 説明 | 行番号 |
|--------|-----------|------|--------|
| almostEqual | `func almostEqual*[T: SomeFloat](x, y: Complex[T]; unitsInLastPlace: Natural = 4): bool` | 近似等価判定 | 391 |
| $ | `func \`$\`*(z: Complex): string` | 文字列変換（タプル形式） | 410 |
| formatValue | `proc formatValue*(result: var string; value: Complex; specifier: string)` | カスタムフォーマット | 439 |

## 7. ビジネスルール

### BR-001: 虚数単位の定義
- `im(float32)` は `complex32(0, 1)` を返却（59行目）
- `im(float64)` は `complex64(0, 1)` を返却（61行目）

### BR-002: 複素数の絶対値
- `abs(z) = hypot(z.re, z.im) = sqrt(z.re² + z.im²)`（71行目）
- `abs2(z) = z.re² + z.im²`（より効率的、77行目）

### BR-003: 複素共役
- `conjugate(z) = (z.re, -z.im)`（90行目）

### BR-004: 乗法逆元
- `inv(z) = conjugate(z) / abs2(z)`（94行目）

### BR-005: 複素数乗算
- `(a + bi)(c + di) = (ac - bd) + (ad + bc)i`（138-139行目）

### BR-006: 複素数除算
- `x / y = x * conjugate(y) / abs2(y)`（151行目）

### BR-007: 平方根の主値
- Wikipediaの主値定義に従う（176行目）
- z == 0 の場合はそのまま z を返却（180-181行目）

### BR-008: 自然対数の主値
- `ln(z) = (ln(abs(z)), arctan2(z.im, z.re))`（209行目）

### BR-009: 指数関数（オイラーの公式）
- `exp(z) = e^(z.re) * (cos(z.im) + i*sin(z.im))`（200-203行目）

### BR-010: べき乗の最適化
- y == 0 の場合 1 を返却（228-229行目）
- y == 1 の場合 x をそのまま返却（233-234行目）
- y == 2 の場合 x * x を計算（237-238行目）
- y == 0.5 の場合 sqrt を使用（239-240行目）
- x == E の場合オイラーの公式を使用（252-254行目）

### BR-011: 三角関数の複素数拡張
- `sin(z) = (sin(z.re)*cosh(z.im), cos(z.re)*sinh(z.im))`（269行目）
- `cos(z) = (cos(z.re)*cosh(z.im), -sin(z.re)*sinh(z.im))`（277-278行目）

### BR-012: 双曲線関数の定義
- `sinh(z) = (exp(z) - exp(-z)) / 2`（319行目）
- `cosh(z) = (exp(z) + exp(-z)) / 2`（327行目）

## 8. バリデーションルール

### VR-001: almostEqualのULP比較
- 実部と虚部それぞれが近似等値であることを確認（407-408行目）
- デフォルトで4ULPの誤差を許容（391行目）

## 9. フォーマット仕様

### タプル形式（デフォルト）
- `$(complex(1.0, 2.0))` => `"(1.0, 2.0)"`（415行目）

### 複素数形式（'j'指定子）
- `&"{z:j}"` => `"(1.0+2.0j)"`
- 実部と虚部を「+」で結合、虚部に「j」を付加（425-437行目）

### カスタム指定子
- `'j'`指定子がある場合: `(re+imj)` 形式（447-448行目）
- それ以外: `(re, im)` 形式（449-450行目）

## 10. 数学的性質

### 複素数体の性質
- 交換法則: z1 + z2 == z2 + z1, z1 * z2 == z2 * z1
- 結合法則: (z1 + z2) + z3 == z1 + (z2 + z3)
- 分配法則: z1 * (z2 + z3) == z1*z2 + z1*z3
- 単位元: z + 0 == z, z * 1 == z
- 逆元: z + (-z) == 0, z * inv(z) == 1 (z != 0)

### オイラーの公式
- `e^(i*theta) = cos(theta) + i*sin(theta)`
- `pow` 関数で x == E の場合に使用（252-254行目）

### 極座標表現
- `z = r * e^(i*phi) = r * (cos(phi) + i*sin(phi))`
- `polar` と `rect` 関数で相互変換

## 11. 関連モジュール

- `std/math` - 基本数学関数（sin, cos, exp, ln, hypot, arctan2など）（36行目）
- `std/strformat` - 文字列フォーマット（36行目）
- `std/strutils` - 文字列操作（36行目）

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

### 12.1 推奨読解順序

1. **型定義と生成関数** (38-66行目)
   - Complex 型の定義
   - complex, complex32, complex64 関数
   - im テンプレート

2. **基本属性関数** (68-94行目)
   - abs, abs2
   - sgn, conjugate, inv

3. **四則演算** (96-171行目)
   - 加算、減算、乗算、除算
   - 複合代入演算子

4. **初等関数** (174-265行目)
   - sqrt, exp, ln
   - pow（べき乗の最適化）

5. **三角関数・双曲線関数** (267-363行目)
   - sin, cos, tan とその逆関数
   - sinh, cosh, tanh とその逆関数

6. **極座標変換** (365-389行目)
   - phase, polar, rect

7. **比較とフォーマット** (391-451行目)
   - almostEqual
   - formatValue

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

```
complex.nim
├── [Type]
│   └── Complex[T: SomeFloat] (38-45)
│       ├── Complex64 = Complex[float64]
│       └── Complex32 = Complex[float32]
│
├── [Constructor]
│   ├── complex(re, im) (47-49)
│   ├── complex32(re, im) (51-53)
│   ├── complex64(re, im) (55-57)
│   ├── im(typedesc/value) (59-66)
│   └── rect(r, phi) (381-389)
│       └── cos(phi), sin(phi)
│
├── [Basic Operations]
│   ├── abs(z) (68-71)
│   │   └── hypot(z.re, z.im)
│   │
│   ├── abs2(z) (73-77)
│   │   └── z.re² + z.im²
│   │
│   ├── sgn(z) (79-86)
│   │   └── z / abs(z)
│   │
│   ├── conjugate(z) (88-90)
│   │   └── (z.re, -z.im)
│   │
│   └── inv(z) (92-94)
│       └── conjugate(z) / abs2(z)
│
├── [Arithmetic]
│   ├── +(x, y) (100-110)
│   ├── -(x, y) (112-126)
│   │
│   ├── *(x, y) (128-139)
│   │   └── (x.re*y.re - x.im*y.im, x.im*y.re + x.re*y.im)
│   │
│   └── /(x, y) (141-151)
│       └── x * conjugate(y) / abs2(y)
│
├── [Elementary Functions]
│   ├── sqrt(z) (174-196)
│   │   └── Principal square root
│   │
│   ├── exp(z) (198-203)
│   │   └── e^re * (cos(im) + i*sin(im))
│   │
│   ├── ln(z) (205-209)
│   │   └── (ln(abs(z)), arctan2(z.im, z.re))
│   │
│   └── pow(x, y) (225-265)
│       ├── Special cases (0, 1, -1, 2, 0.5)
│       └── General: polar form calculation
│
├── [Trigonometric]
│   ├── sin(z) (267-269)
│   │   └── sin(re)*cosh(im) + i*cos(re)*sinh(im)
│   │
│   ├── cos(z) (275-279)
│   │   └── cos(re)*cosh(im) - i*sin(re)*sinh(im)
│   │
│   ├── tan(z) (285-287)
│   │   └── sin(z) / cos(z)
│   │
│   └── arcsin/arccos/arctan (271, 281, 289)
│       └── Inverse via ln and sqrt
│
├── [Hyperbolic]
│   ├── sinh(z) (317-319)
│   │   └── (exp(z) - exp(-z)) / 2
│   │
│   ├── cosh(z) (325-327)
│   │   └── (exp(z) + exp(-z)) / 2
│   │
│   └── tanh(z) (333-335)
│       └── sinh(z) / cosh(z)
│
├── [Polar Coordinates]
│   ├── phase(z) (365-369)
│   │   └── arctan2(z.im, z.re)
│   │
│   └── polar(z) (371-379)
│       └── (abs(z), phase(z))
│
└── [Format]
    ├── $(z) (410-415)
    │   └── "(re, im)"
    │
    └── formatValue(z, specifier) (439-450)
        ├── [specifier has 'j'] ── "(re+imj)"
        └── [else] ── "(re, im)"
```

### 12.3 データフロー図

```
[入力]
   │
   ├── [直交座標 (re, im)]
   │       │
   │       ▼
   │   ┌─────────────────┐
   │   │ complex(re, im) │
   │   └─────────────────┘
   │           │
   │           ▼
   └──────────────────────┐
                          │
   ├── [極座標 (r, phi)]  │
   │       │              │
   │       ▼              │
   │   ┌─────────────────┐│
   │   │ rect(r, phi)    ││
   │   │ r*cos, r*sin    ││
   │   └─────────────────┘│
   │           │          │
   └───────────┼──────────┘
               │
               ▼
       ┌─────────────────┐
       │  Complex[T]     │
       │  (re, im)       │
       └─────────────────┘
               │
               ├── 四則演算 ── Complex[T]
               │
               ├── abs/abs2 ── T (実数)
               │
               ├── phase ── T (ラジアン)
               │
               ├── polar ── (r, phi)
               │
               ├── exp/ln/sqrt ── Complex[T]
               │
               ├── sin/cos/tan ── Complex[T]
               │
               └── $ ── string
```

### 12.4 関連ファイル一覧

| ファイルパス | 役割 |
|-------------|------|
| lib/pure/complex.nim | メインモジュール（453行） |
| lib/pure/math.nim | 基本数学関数（hypot, sin, cos, exp, ln等） |
| lib/pure/strformat.nim | 文字列フォーマット |
| lib/pure/strutils.nim | 文字列操作 |
