viva_math - v1.1.0

viva_math/cusp

Cusp Catastrophe Theory implementation.

Based on René Thom’s catastrophe theory (1972). The cusp is the simplest catastrophe with two control parameters.

Potential function: V(x) = x⁴/4 + αx²/2 + βx Gradient: dV/dx = x³ + αx + β Discriminant: Δ = -4α³ - 27β²

When Δ > 0 and α < 0: bistable region (two stable states) This models emotional “phase transitions” - sudden mood shifts.

References:

Types

CuspParams

</>

Cusp catastrophe parameters.

  • alpha: normal factor (bifurcation parameter)
  • beta: asymmetry factor (splitting factor)
pub type CuspParams {
  CuspParams(alpha: Float, beta: Float)
}

Constructors 

  • CuspParams(alpha: Float, beta: Float)

CuspResult

</>

Result of equilibria calculation.

pub type CuspResult {
  Monostable(equilibrium: Float)
  Bistable(lower: Float, unstable: Float, upper: Float)
}

Constructors 

  • Monostable(equilibrium: Float)

    Single stable state

  • Bistable(lower: Float, unstable: Float, upper: Float)

    Two stable states with one unstable between them

Values

discriminant

</> 
pub fn discriminant(params: CuspParams) -> Float

Compute the discriminant Δ = -4α³ - 27β²

Δ > 0 and α < 0: bistable region Δ ≤ 0 or α ≥ 0: monostable region

equilibria

</> 
pub fn equilibria(params: CuspParams) -> CuspResult

Calculate equilibria (roots of the cubic x³ + αx + β = 0).

Uses Cardano’s formula for the depressed cubic. Returns Monostable or Bistable depending on discriminant.

from_arousal_dominance

</> 
pub fn from_arousal_dominance(
  arousal: Float,
  dominance: Float,
) -> CuspParams

Create cusp parameters from PAD arousal and dominance.

Mapping (from VIVA emotional dynamics):

  • alpha = -arousal (high arousal → negative alpha → bistability)
  • beta = dominance * 0.5 (dominance biases equilibrium)

This means high arousal creates emotional volatility.

gradient

</> 
pub fn gradient(x: Float, params: CuspParams) -> Float

Compute the gradient dV/dx = x³ + αx + β

Equilibria are where gradient = 0.

is_bistable

</> 
pub fn is_bistable(params: CuspParams) -> Bool

Check if the system is in bistable region.

Bistability requires:

  1. α < 0 (necessary for two minima)
  2. Δ > 0 (discriminant positive)

nearest_equilibrium

</> 
pub fn nearest_equilibrium(x: Float, params: CuspParams) -> Float

Find nearest stable equilibrium to current state.

potential

</> 
pub fn potential(x: Float, params: CuspParams) -> Float

Compute the cusp potential V(x) = x⁴/4 + αx²/2 + βx

The potential represents emotional “energy landscape”. Stable states are at local minima of this function.

volatility

</> 
pub fn volatility(x: Float, params: CuspParams) -> Float

Compute emotional volatility based on cusp geometry.

Volatility is high when:

  1. In bistable region
  2. Close to the unstable equilibrium (catastrophe manifold)

would_jump

</> 
pub fn would_jump(x: Float, params: CuspParams) -> Bool

Check if state would “jump” to other attractor.

In bistable regime, if state crosses the unstable equilibrium, it will rapidly transition to the opposite stable state.

✨ Search Document