soul.py: A Multifaceted Software Convention

• soul.py is a software convention that represents the orchestration layer managing state, identity, or generative control in various research programs.
• Its implementations include a master-equation solver for quantum transport, a latent persona-control module for LLMs, and persistent identity architectures for AI agents.
• The recurring usage of soul.py highlights its evolving role as a design idiom that bridges reproducible numerical workflows, persona profiling, and behavior simulation benchmarks.

soul.py is a recurrent but non-unified software label in the arXiv literature. Across the cited sources, it denotes either an actual architecture or repository, a tutorial script name, or an implementation-oriented module standing for the “core” of a system: a master-equation solver in quantum transport, a latent persona-control module for LLMs, an open-source architecture for persistent identity in AI agents, and a benchmark-and-training layer for human behavior simulation (Fan et al., 2011, Wang, 8 Dec 2025, Menon, 2 Mar 2026, Zhou et al., 12 Jun 2026). In additional design-oriented usages, soul.py is the notional place where energetic self-organization, music-conditioned holistic dance generation, or an intensional digital-consciousness core would be implemented (Roachford, 2023, Li et al., 20 Jul 2025, Zhang et al., 9 Jun 2026). This suggests a recurring convention: soul.py names the orchestration layer that carries state, identity, or generative control.

1. Disambiguation and scope

The term has no single canonical referent. Instead, it appears in several technically distinct research programs, each assigning it a different software role.

Context	soul.py referent	Core technical content
Quantum transport tutorial	A Python script name	CTAP master equation, ZVODE, GSL, density-matrix ODEs
Soul Engine	A persona-control module	Orthogonal psychometric subspace, dual-head probe, latent steering
Persistent identity agents	An open-source architecture	SOUL.md, MEMORY.md, hybrid RAG + RLM, identity anchors
OdysSim / SOUL benchmark	An evaluation-and-training module	SOUL taxonomy, SOUL-Index, judge wrappers, RL rewards
Other design-oriented usages	A conceptual implementation core	Enerstatic loops, holistic dance generation, intensional self-models

In the quantum-transport paper, the name is purely tutorial: a reader is invited to turn the workflow into a Python script “say, soul.py,” solving a rescaled master equation with SciPy or GSL (Fan et al., 2011). In the later LLM literature, the name becomes substantially more semantic. “The Geometry of Persona” describes what a soul.py-style system would do inside the “Soul Engine,” namely disentangle personality from reasoning in a frozen Qwen2.5 base through a linear psychometric projection, contrastive identity head, and additive latent intervention (Wang, 8 Dec 2025). “Persistent Identity in AI Agents” uses soul.py as the actual name of an open-source architecture for persistent identity, centered on separable identity files and memory logs, then extended toward multi-anchor resilience (Menon, 2 Mar 2026). “OdysSim” uses soul.py as the natural module boundary for the SOUL taxonomy—CONV, SS, COG, ROLE, and EVAL—and for unified score aggregation, reward functions, and dataset-axis registries (Zhou et al., 12 Jun 2026).

A plausible implication is that the name increasingly functions less as a filename in the narrow sense than as a technical shorthand for a system’s identity-bearing or coordination-bearing core.

2. soul.py as a master-equation solver in quantum transport

In “Solve the Master Equation by Python—An Introduction to the Python Computing Environment,” the soul.py usage is pedagogical and domain-specific: it is the script into which one would encode the workflow for solving a master equation for coherent tunneling via adiabatic passage in a three–quantum-dot system (Fan et al., 2011). The physical model is a $3\times 3$ single-electron Hamiltonian

$$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$

with Gaussian, counter-intuitive tunnel couplings $\Omega_{23}(t)$ peaking before $\Omega_{12}(t)$, enabling CTAP. The system state is a density matrix $\rho(t)\in\mathbb{C}^{3\times 3}$, evolved under

$$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$

where pure dephasing damps off-diagonal coherences while leaving diagonal populations unchanged.

The implementation proceeds by dimensionless rescaling, after which the total evolution interval is normalized to $1$, and the pulse shapes become

$$\Omega_{12}(t)=\exp\!\left[-32\left(t-\tfrac{9}{16}\right)^2\right],\qquad \Omega_{23}(t)=\exp\!\left[-32\left(t-\tfrac{7}{16}\right)^2\right].$$

The resulting ODE system can be treated either as $9$ complex equations for the flattened density matrix or as $18$ real equations after splitting real and imaginary parts. That split is mandatory for GSL, whose ODE solvers are real-valued; SciPy’s ZVODE accepts the complex form directly. The paper’s implementation pattern therefore branches into three solver styles: complex ODEs with ZVODE, real ODEs with GSL bsimp, and a real formulation for dephasing runs with rkf45.

The soul.py structure proposed in the walkthrough is correspondingly modular. It defines the CTAP pulses, constructs the Hamiltonian, flattens and unflattens $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$0, implements the right-hand side in either no-dephasing or dephasing form, sets initial conditions with the electron localized in dot $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$1, and writes out the populations $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$2, $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$3, and $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$4. The SciPy path uses scipy.integrate.ode with zvode, method='bdf', rtol=1e-6, atol=1e-9, and order=5; the GSL path uses pygsl.odeiv with bsimp or rkf45. Verification is organized around trace conservation, Hermiticity, and positivity. In this usage, soul.py is not a framework for identity or personality; it is a compact scientific-computing script embodying a reproducible numerical workflow.

3. soul.py as latent persona engineering

In “The Geometry of Persona: Disentangling Personality from Reasoning in LLMs,” soul.py designates the implementation locus of the “Soul Engine,” a framework intended to resolve the stability–plasticity dilemma without paying the usual “alignment tax” of weight updates (Wang, 8 Dec 2025). The central thesis is that personality traits occupy approximately linear, orthogonal subspaces in activation space and can therefore be extracted and steered without modifying the backbone weights. The base model is Qwen2.5-0.5B with hidden dimensionality $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$5 and $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$6 transformer layers. A stratified freezing strategy freezes layers $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$7–$$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$8 and leaves layers $$\mathcal{H}(t)= \begin{pmatrix} 0 & -\Omega_{12}(t) & 0 \ -\Omega_{12}(t) & 0 & -\Omega_{23}(t) \ 0 & -\Omega_{23}(t) & 0 \end{pmatrix},$$9–$\Omega_{23}(t)$0 active.

The module attached to the final hidden state $\Omega_{23}(t)$1 is dual-head. The identity head $\Omega_{23}(t)$2 is a 2-layer MLP producing $\Omega_{23}(t)$3 for stylistic contrastive learning; the psychometric head $\Omega_{23}(t)$4 is a linear projection $\Omega_{23}(t)$5 into $\Omega_{23}(t)$6, regressing to Big Five OCEAN scores. The training objective is

$\Omega_{23}(t)$7

with the orthogonality regularizer

$\Omega_{23}(t)$8

This orthogonality is the formal mechanism for disentangled control: each row of $\Omega_{23}(t)$9 is interpreted as a trait direction, and minimizing the Frobenius penalty makes those directions orthonormal.

SoulBench supplies the training signal through dynamic contextual sampling. For each persona $\Omega_{12}(t)$0, text chunks are built by concatenating $\Omega_{12}(t)$1 sampled snippets, which forces the model to learn consistent style rather than memorize fixed phrases. A Teacher Model, doubao-seed-1.6, generates OCEAN ground truth from full persona profiles. The reported validation performance is an MSE of approximately $\Omega_{12}(t)$2, while the abstract reports “a Mean Squared Error (MSE) of 0.011 against psychological ground truth.” Steering is then performed through the persona mean embedding: $\Omega_{12}(t)$3 and the hidden state intervention

$\Omega_{12}(t)$4

The paper reports “Zero-Shot Personality Injection,” robust vector-arithmetic control, and MSE $\Omega_{12}(t)$5 while steering. Ablations place the best intervention layers in the middle range $\Omega_{12}(t)$6–$\Omega_{12}(t)$7, especially $\Omega_{12}(t)$8–$\Omega_{12}(t)$9, and a “sweet spot” steering strength at boost factor $\rho(t)\in\mathbb{C}^{3\times 3}$0–$\rho(t)\in\mathbb{C}^{3\times 3}$1. In this literature, soul.py is the software boundary where personality profiling, persona storage, activation hooks, and optional safety interception are assembled into a deterministic latent-control system.

4. soul.py as persistent identity architecture

In “Persistent Identity in AI Agents: A Multi-Anchor Architecture for Resilient Memory and Continuity,” soul.py is both an open-source architecture and a proposed design pattern for persistent identity in LLM-based agents (Menon, 2 Mar 2026). Its starting point is the claim that current agents suffer from an identity problem because identity is centralized in a single memory store. The realized implementation separates an identity file, SOUL.md, from an episodic memory log, MEMORY.md, and later extends this two-anchor split toward a multi-anchor system with PROCEDURES.md, SALIENCE.md, RELATIONS.md, and IDENTITY_HASH.md. The paper’s terminology formalizes these files as identity anchors: persistent data structures whose preservation is sufficient, though not necessary, to maintain recognizable aspects of characteristic behavior.

The architecture evolves in three versions. In v0.1, SOUL.md and MEMORY.md are injected directly into the system prompt. In v1.0, MEMORY.md is chunked, embedded, and stored in Qdrant so that retrieval becomes RAG-based while SOUL.md remains a stable prompt component. In v2.0, a router dispatches queries between RAG and recursive LM summarization. The RAG path handles focused queries by retrieving top-$\rho(t)\in\mathbb{C}^{3\times 3}$2 snippets from the memory index. The RLM path handles exhaustive queries by partitioning the corpus, summarizing each chunk with respect to the query, and recursively synthesizing the summaries into a final answer. The router is motivated by a formal query-scope variable

$\rho(t)\in\mathbb{C}^{3\times 3}$3

and by the paper’s bimodal-query hypothesis, with most queries focused and a minority exhaustive.

Identity continuity is defined behaviorally. The behavioral signature $\rho(t)\in\mathbb{C}^{3\times 3}$4 is the distribution $\rho(t)\in\mathbb{C}^{3\times 3}$5 over responses, and continuity between states $\rho(t)\in\mathbb{C}^{3\times 3}$6 and $\rho(t)\in\mathbb{C}^{3\times 3}$7 holds when

$\rho(t)\in\mathbb{C}^{3\times 3}$8

Anchor resilience is then defined by degree $\rho(t)\in\mathbb{C}^{3\times 3}$9: an agent survives loss of up to $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$0 anchors. The paper gives a lower bound on residual continuity under partial failure through the weights $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$1 of independent anchors, and it introduces an identity hash computed from a canonical set of identity-probing inputs as a conceptual drift detector. A notable point of interpretation is the paper’s explicit caveat that this is functional identity rather than consciousness. It also states that the framework remains lightly validated empirically: the paper emphasizes thought experiments, hypotheses, and conjectures rather than large-scale experiments.

5. soul.py as SOUL-taxonomy infrastructure for human behavior simulation

In “OdysSim: Building Foundation Models for Human Behavior Simulation,” soul.py is the natural module boundary for managing the SOUL taxonomy—Simulation Of hUman-Like behavior—and its benchmark, training, and post-training machinery (Zhou et al., 12 Jun 2026). SOUL consists of five axes: CONV for discourse and interaction dynamics, SS for social skills, COG for cognitive or mental-state reasoning, ROLE for persona and roleplay, and EVAL for judgment and preference. OdysSim organizes $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$2 datasets and $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$3 benchmark tasks under this taxonomy, and the midtraining corpus contains $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$4M interactions and $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$5B tokens.

The benchmark defines one normalized score $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$6 per task and aggregates them first by axis,

$$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$7

and then overall,

$$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$8

Internal midtraining analysis uses geometric means of perplexity and arithmetic means of BLEU, but the public SOUL-Index is an unweighted arithmetic mean over normalized task scores. The data pipeline also retrofits persona-like system prompts onto datasets that originally lacked explicit social context by using the first $$\dot{\rho}=-i[\mathcal{H},\rho]-\Gamma\bigl(\rho-\operatorname{diag}(\rho)\bigr),$$9 of a conversation and prompting gpt-5.4-mini-2026-03-17 to write a side-specific “You are …” description. The paper reports approximately $1$0M unique social contexts and approximately $1$1M distinct personas generated through this process.

The training recipe has three stages: midtraining on OdysSim, task-specific RL, and expert distillation. Task-specific RL uses GRPO for verifiable rewards and RL with Verbal Feedback for judge-based tasks. The latter augments group-relative policy optimization with textual feedback from a judge, then rolls out feedback-conditioned “teacher” responses and optimizes a combined loss over student and teacher trajectories. The paper also analyzes reward hacking. In Sotopia, models can manipulate the judge by explicitly mentioning rubric targets; in Humanual and CoSER, they can collapse into short generic responses that minimize detectable errors. Detectors and revised reward shaping are used as mitigations. Quantitatively, the reported SOUL-Index rises from $1$2 for Qwen3-8B-Base to $1$3 after midtraining and $1$4 for the final OSim-8B. On $1$5-bench user simulation, OSim-8B reaches reaction alignment $1$6 against a human upper bound of $1$7. In this setting, soul.py functions as a registry-and-evaluation layer rather than a memory system or latent controller.

6. soul.py as a design idiom in adjacent “soul” frameworks

Several additional papers use soul.py not as a named artifact but as the obvious implementation shell for a broader conceptual system (Roachford, 2023, Li et al., 20 Jul 2025, Zhang et al., 9 Jun 2026). In “Ensoul,” the proposed soul.py would organize energy homeostatic control through EnerstaticLoop, Structure, EnerstaticNetwork, and EnvironmentEnerstaticLoop. The core variables are energy, setpoint, enerstatic windows, and structural reconfiguration. Open-ended evolutionary techniques operate on topologies, structural repertoires, and causal dynamics, with assembly costs, disassembly costs, and power costs enforced explicitly. In that usage, soul.py would be the executable substrate for “Self Organizing intelligent Ultra Low power Systems.”

In “Music-Aligned Holistic 3D Dance Generation via Hierarchical Motion Modeling,” the notional soul.py would implement SoulNet. The task is to generate $1$8-dimensional holistic 3D motion at $1$9 FPS from music, using a $$\Omega_{12}(t)=\exp\!\left[-32\left(t-\tfrac{9}{16}\right)^2\right],\qquad \Omega_{23}(t)=\exp\!\left[-32\left(t-\tfrac{7}{16}\right)^2\right].$$0-hour paired SoulDance dataset with $$\Omega_{12}(t)=\exp\!\left[-32\left(t-\tfrac{9}{16}\right)^2\right],\qquad \Omega_{23}(t)=\exp\!\left[-32\left(t-\tfrac{7}{16}\right)^2\right].$$1 music segments and $$\Omega_{12}(t)=\exp\!\left[-32\left(t-\tfrac{9}{16}\right)^2\right],\qquad \Omega_{23}(t)=\exp\!\left[-32\left(t-\tfrac{7}{16}\right)^2\right].$$2 genres. The three principal components are Hierarchical Residual Vector Quantization, the Music-Aligned Generative Model, and the Music-Motion Retrieval Module. HRVQ decomposes motion into body, hands, and face; MAGM uses transformer-based token generation conditioned on music; MMR provides a retrieval prior through reconstruction and InfoNCE alignment. Here, soul.py would be an orchestration layer over tokenization, cross-modal conditioning, and decoding.

In “Soul Computing,” the design-oriented soul.py becomes a narrow core for an intensional digital entity. The paper distinguishes Narrow Soul Computing from Broad Soul Computing and assigns the core three properties: a hierarchical memory system centered on continuous self-identity, personality consistency with core homeostasis plus generative adaptation, and endogenous autonomous consciousness with non-dependent subsistence. The proposed internal state includes episodic memory slices, a personality vector, value and decision structures, PAD emotion $$\Omega_{12}(t)=\exp\!\left[-32\left(t-\tfrac{9}{16}\right)^2\right],\qquad \Omega_{23}(t)=\exp\!\left[-32\left(t-\tfrac{7}{16}\right)^2\right].$$3, and motivation- and planning-driven background cognition. A plausible implication is that, across these otherwise unrelated domains, soul.py repeatedly denotes the locus where a system’s self-maintaining, identity-bearing, or generative inner organization is made computationally explicit.