viva_math

-module(viva_math).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/viva_math.gleam").
-export([pad/3, classify/1, is_volatile/2, free_energy/2, entropy/1, sigmoid/1, clamp_bipolar/1, erf/1, gelu/1]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " viva_math - Mathematical foundations for VIVA's sentient digital life.\n"
    "\n"
    " A specialized math library for the BEAM, designed to sit between\n"
    " `gleam_community_maths` (primitives) and `viva_tensor` (tensors + NIF).\n"
    "\n"
    " ## Modules\n"
    "\n"
    " ### Foundations\n"
    " - `viva_math/scalar`     - Scalar math: erf, gelu, silu, mish, logsumexp...\n"
    " - `viva_math/constants`  - High-precision constants (pi, e, sqrt_2pi...)\n"
    " - `viva_math/common`     - Generic helpers: clamp, lerp, sigmoid, softmax\n"
    "\n"
    " ### Geometry & linear algebra\n"
    " - `viva_math/vector`     - Vec3 (PAD emotional space) + ops\n"
    " - `viva_math/vec2`       - 2-D vectors (polar, planar)\n"
    " - `viva_math/vec4`       - 4-D vectors (RGBA, homogeneous, quaternions)\n"
    " - `viva_math/vecn`       - N-D vectors as List(Float)\n"
    " - `viva_math/matrix`     - Mat2, Mat3, Mat4 and generic MatN\n"
    "\n"
    " ### Stochastic & inference\n"
    " - `viva_math/random`     - PRNG with opaque Seed (Erlang :rand backed)\n"
    " - `viva_math/statistics` - mean, var, ema, percentile, correlation\n"
    " - `viva_math/distributions` - gaussian/uniform/exponential/categorical\n"
    " - `viva_math/entropy`    - Shannon, KL, JS, Rényi, Tsallis, Fisher\n"
    "\n"
    " ### Dynamical systems\n"
    " - `viva_math/cusp`       - Catastrophe theory (Thom)\n"
    " - `viva_math/free_energy` - Friston FEP + active inference\n"
    " - `viva_math/attractor`  - Mehrabian PAD attractors + OU dynamics\n"
    " - `viva_math/ode`        - Euler / RK2 / RK4 / Euler-Maruyama / Milstein\n"
    " - `viva_math/calculus`   - Finite differences + Simpson / Romberg\n"
    " - `viva_math/scheduler`  - Cosine annealing, warmup, decay schedules\n"
    "\n"
    " ## Quick start\n"
    "\n"
    " ```gleam\n"
    " import viva_math/scalar\n"
    " import viva_math/vector\n"
    " import viva_math/attractor\n"
    " import viva_math/random\n"
    "\n"
    " // PAD emotional state\n"
    " let state = vector.pad(-0.3, 0.7, -0.2)\n"
    "\n"
    " // Classify nearest emotion\n"
    " let emotion = attractor.classify_emotion(state)\n"
    " // -> \"fear\"\n"
    "\n"
    " // Scalar activations for ML\n"
    " let y = scalar.gelu(0.5)\n"
    "\n"
    " // Seedable, reproducible normal sample\n"
    " let seed = random.from_int(42)\n"
    " let #(x, _) = random.normal(seed, 0.0, 1.0)\n"
    " ```\n"
).

-file("src/viva_math.gleam", 69).
?DOC(" Create a PAD vector with clamping. Shorthand for `vector.pad/3`.\n").
-spec pad(float(), float(), float()) -> viva_math@vector:vec3().
pad(Pleasure, Arousal, Dominance) ->
    viva_math@vector:pad(Pleasure, Arousal, Dominance).

-file("src/viva_math.gleam", 74).
?DOC(" Classify emotional state to nearest attractor name.\n").
-spec classify(viva_math@vector:vec3()) -> binary().
classify(State) ->
    viva_math@attractor:classify_emotion(State).

-file("src/viva_math.gleam", 79).
?DOC(" Check if emotional state is volatile (cusp bistability).\n").
-spec is_volatile(float(), float()) -> boolean().
is_volatile(Arousal, Dominance) ->
    _pipe = viva_math@cusp:from_arousal_dominance(Arousal, Dominance),
    viva_math@cusp:is_bistable(_pipe).

-file("src/viva_math.gleam", 85).
?DOC(" Compute free energy from expected and actual states with default precision.\n").
-spec free_energy(viva_math@vector:vec3(), viva_math@vector:vec3()) -> viva_math@free_energy:free_energy_state().
free_energy(Expected, Actual) ->
    Baseline = viva_math@vector:zero(),
    Complexity_weight = 0.1,
    viva_math@free_energy:compute_state_simple(
        Expected,
        Actual,
        Baseline,
        Complexity_weight
    ).

-file("src/viva_math.gleam", 100).
?DOC(" Shannon entropy of a probability distribution.\n").
-spec entropy(list(float())) -> float().
entropy(Probabilities) ->
    viva_math@entropy:shannon(Probabilities).

-file("src/viva_math.gleam", 105).
?DOC(" Standard sigmoid σ(x) = 1 / (1 + e^(-x)).\n").
-spec sigmoid(float()) -> float().
sigmoid(X) ->
    viva_math@scalar:sigmoid(X).

-file("src/viva_math.gleam", 110).
?DOC(" Clamp value to [-1, 1] range.\n").
-spec clamp_bipolar(float()) -> float().
clamp_bipolar(X) ->
    viva_math@common:clamp_bipolar(X).

-file("src/viva_math.gleam", 115).
?DOC(" Error function. Delegates to `viva_math/scalar.erf` (Erlang `:math.erf`).\n").
-spec erf(float()) -> float().
erf(X) ->
    math:erf(X).

-file("src/viva_math.gleam", 120).
?DOC(" GELU activation (exact form using erf).\n").
-spec gelu(float()) -> float().
gelu(X) ->
    viva_math@scalar:gelu(X).