math/log
===============================================================================
%% Natural logarithm
1. Usage
-------------------------------------------------------------------------------
```mech:disabled
Y := math/log(X)
```
2. Description
-------------------------------------------------------------------------------
Computes the **natural logarithm** (base *e*) of the input, elementwise:
$$ Y = \ln(X).
3. Input
-------------------------------------------------------------------------------
| Argument | Kind | Description |
|----------|------------------------------|-------------|
| `X` | `float`, `[float]`, `matrix` | Real-valued input(s). Supported scalar types are `f64` and `f32`, and their vector/matrix forms. Complex inputs are **not** supported. |
4. Output
-------------------------------------------------------------------------------
| Argument | Kind | Description |
|----------|------------------|-------------|
| `Y` | matches input | Natural log of `X`, computed elementwise. |
5. Examples
-------------------------------------------------------------------------------
(a) Scalar value
```mech:ex1
y := math/log(1.0)
```
(b) Positive input
```mech:ex2
y := math/log(2.7182818)
```
(c) Vector input
```mech:ex3
x := [1.0, 2.0, 10.0]
y := math/log(x)
```
(d) Matrix input
```mech:ex4
x := [1.0, 4.0; 10.0, 100.0]
y := math/log(x)
```
6. Details
-------------------------------------------------------------------------------
- **Definition:**
$$ \ln(x) = \int_1^x \frac{1}{t} dt, \quad x > 0.
- **Domain & special cases (real inputs):**
- `x > 0`: returns finite real value.
- `x = 0`: tends to `-∞`.
- `x < 0`: undefined (returns `NaN`).
- `log(∞) = ∞`, `log(1) = 0`.
- **Shapes & types:** Scalars map to scalars; vectors/matrices are computed elementwise. Implementations exist for `f64` (`log`) and `f32` (`logf`).
- **Performance:** Vector and matrix paths loop over elements. For large arrays, contiguous memory improves cache locality.
7. Notes for Implementers
-------------------------------------------------------------------------------
Backed by Rust/libm `log` (f64) and `logf` (f32). This codebase dispatches
across scalar, vector, and matrix variants; each computes the natural logarithm
elementwise and returns an output of the same shape and precision.
8. See also
-------------------------------------------------------------------------------
`math/log10`, `math/log2`, `math/exp`.