Our Approach

Our Rust library treats psychology as a queryable computation. You provide entities, events, and timestamps. We compute state at any point in time. No stored history. No simulation loop. Just deterministic computation from events to state.

The Core Abstraction: StateValue

Every psychological dimension - mood, personality, trust, needs - is represented as a StateValue:

pub struct StateValue {
    base: f32,              // Stable tendency (who you are)
    delta: f32,             // Current deviation (what just happened)
    chronic_delta: f32,     // Persistent deviation (what keeps happening)
    decay_half_life: Duration,
}

This single abstraction unifies mood swings, personality traits, relationship warmth, and mental health factors under one computational model.

Two Pathways for Change

StateValue supports two fundamentally different types of change:

Short-term Pathway

Events create deltas. Deltas decay. A bad day lowers mood; it recovers over hours or days. A stressful meeting adds negative valence delta. A good conversation adds positive delta. These accumulate: multiple events in succession create compounding effects.

The decay is exponential, controlled by the half-life. After one half-life, the delta is half its original value. After two half-lives, one quarter. This models psychological reality: emotional responses fade. The sharp sting of criticism softens over days.

Long-term Pathway

Formative events shift the base permanently. Severe shifts (greater than 0.20) follow a settling curve - full impact immediately, then stabilizing to 70% over 180 days. This models post-traumatic growth and personality plasticity research.

Not every event is formative. Most events only create deltas. Only experiences that cross the formative threshold change who you are, not just how you currently feel.

Theoretical Grounding

The same event affects different entities differently. A rejection processed through high neuroticism creates larger mood deltas than the same rejection processed through high emotional stability. Events are interpreted through personality, not applied uniformly.

We integrate six established psychological frameworks:

• HEXACO - Six-factor personality model (interpretation filter)
• PAD - Valence, arousal, dominance for mood (emotional state space)
• ITS - Interpersonal Theory of Suicide for risk modeling (social disconnection)
• PPCT - Person-Process-Context-Time developmental framework (change over time)
• Bronfenbrenner - Five nested ecological context layers (environmental structure)
• Mayer's Trust Model - Domain-specific trustworthiness decomposition (relationships)

Each theory addresses a different aspect of human psychology; together, they form a comprehensive model of how people think, feel, and behave. For a deeper exploration of how these frameworks work together, see Theoretical Foundations.

Code Sample

Here is how you create an entity, apply events, and query state:

// Create an entity with personality and anchor state
let entity = EntityBuilder::new("john", Species::Human)
    .with_age(35)
    .with_hexaco(Hexaco {
        honesty_humility: 0.6,
        neuroticism: 0.3,
        extraversion: 0.5,
        agreeableness: 0.7,
        conscientiousness: 0.8,
        openness: 0.4,
    })
    .build();

// Add to simulation with anchor timestamp
let mut sim = Simulation::new();
let anchor = Timestamp::from_date(2024, 1, 1);
sim.add_entity(entity, anchor);

// Apply an event
let event = EventBuilder::new(EventType::SocialRejection)
    .with_severity(0.6)
    .with_target("john")
    .build();
sim.add_event(event, Timestamp::from_date(2024, 3, 15));

// Query state at any timestamp
let handle = sim.query_entity("john");
let state_before = handle.state_at(Timestamp::from_date(2024, 3, 14));
let state_after = handle.state_at(Timestamp::from_date(2024, 3, 16));
let state_recovered = handle.state_at(Timestamp::from_date(2024, 6, 1));

No stored history. Compute on demand. Query forward or backward in time.

Key Properties

For a complete treatment of StateValue including decay mathematics, implementation details, and usage patterns, see Understanding State.