mech-math 0.3.4

math/asec
===============================================================================

%% Arc secant of argument in radians

1. Usage
-------------------------------------------------------------------------------

```mech:disabled
Y := math/asec(X)
```

2. Description
-------------------------------------------------------------------------------

Computes the arc secant (inverse secant) of each element of `X`. The input `X` is interpreted as a numeric value. The result `Y` has the same shape as the input `X`.

3. Input
-------------------------------------------------------------------------------

| Argument | Kind                     | Description                           |
|----------|--------------------------|---------------------------------------|
| `X`      | `float`, `[float]`       | Input value(s). Can be real or complex. For real inputs, values must satisfy `|X| >= 1`. For complex inputs, results are computed accordingly. |

4. Output
-------------------------------------------------------------------------------

| Argument | Kind                     | Description                           |
|----------|--------------------------|---------------------------------------|
| `Y`      | matches input            | Arc secant of the input values, expressed in radians. For real inputs, results are in the range `[0, π]` excluding `π/2`. The shape of `Y` matches the shape of `X`. |

5. Examples  
-------------------------------------------------------------------------------

(a) Find the arc secant of a number 

```mech:ex1
y := math/asec(2.0)
```

(b) Find the arc secant for a vector of numbers

```mech:ex2
x := [1, -2, 10]
y := math/asec(x)
```

(c) Find the arc secant for a matrix of numbers

```mech:ex3
x := [2, -3; 4, -5]
y := math/asec(x)
```

(d) Relationship with acos

```mech:ex4
x := [2, 3, 4]
y := math/asec(x)  # equivalent to acos(1/x)
```

6. Details
-------------------------------------------------------------------------------

The arc secant (inverse secant) function returns the angle whose secant is the specified value.

For real numbers $$x$$ with $$|x| \geq 1$$:

$$ y = asec(x)

means $$ sec(y) = x $$, with $$ y \in [0, π] $$ and $$ y \neq π/2 $$.

It can be expressed in terms of arccosine:

$$ asec(x) = acos(1/x)

for $$x \neq 0$$.

For complex numbers, arc secant can be expressed as:

$$ asec(z) = \cos^{-1}(1/z)

or equivalently:

$$ asec(z) = -i \ln \left( \frac{1}{z} + i\sqrt{1 - \frac{1}{z^2}} \right)

This definition extends the function beyond real numbers, allowing it to handle complex inputs.