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]).

-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 - Core mathematical functions for VIVA.\n"
    "\n"
    " A specialized math library for sentient digital life,\n"
    " built on top of gleam_community_maths.\n"
    "\n"
    " ## Modules\n"
    "\n"
    " - `viva_math/common` - Utilities: clamp, sigmoid, softmax, lerp\n"
    " - `viva_math/vector` - Vec3 type for PAD emotional space\n"
    " - `viva_math/cusp` - Cusp catastrophe theory\n"
    " - `viva_math/free_energy` - Free Energy Principle\n"
    " - `viva_math/attractor` - Emotional attractor dynamics\n"
    " - `viva_math/entropy` - Information theory\n"
    "\n"
    " ## Dependencies\n"
    "\n"
    " Re-exports gleam_community_maths for convenience.\n"
    " Use `import gleam_community/maths` for:\n"
    " - Trigonometry (sin, cos, tan, etc.)\n"
    " - Statistics (mean, variance, etc.)\n"
    " - Distances (euclidean, manhattan, etc.)\n"
    " - Constants (pi, e, tau)\n"
    "\n"
    " ## Example\n"
    "\n"
    " ```gleam\n"
    " import viva_math/vector\n"
    " import viva_math/attractor\n"
    " import viva_math/cusp\n"
    "\n"
    " // Create PAD state\n"
    " let state = vector.pad(-0.3, 0.7, -0.2)\n"
    "\n"
    " // Classify emotion\n"
    " let emotion = attractor.classify_emotion(state)\n"
    " // -> \"fear\"\n"
    "\n"
    " // Check for cusp bistability\n"
    " let params = cusp.from_arousal_dominance(0.7, -0.2)\n"
    " let volatile = cusp.is_bistable(params)\n"
    " // -> True (high arousal creates bistability)\n"
    " ```\n"
).

-file("src/viva_math.gleam", 57).
?DOC(
    " Create a PAD vector with clamping.\n"
    " 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", 63).
?DOC(
    " Classify emotional state to nearest attractor name.\n"
    " Shorthand for attractor.classify_emotion/1.\n"
).
-spec classify(viva_math@vector:vec3()) -> binary().
classify(State) ->
    viva_math@attractor:classify_emotion(State).

-file("src/viva_math.gleam", 68).
?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", 74).
?DOC(" Compute free energy from expected and actual states.\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(
        Expected,
        Actual,
        Baseline,
        Complexity_weight
    ).

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

-file("src/viva_math.gleam", 90).
?DOC(" Standard sigmoid function.\n").
-spec sigmoid(float()) -> float().
sigmoid(X) ->
    viva_math@common:sigmoid_standard(X).

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