Metadata-Version: 2.4
Name: dlvt
Version: 2.2.0
Summary: A formal model of enacted leadership scope, coordination load, and vitality
Author: William Bendinelli
License-Expression: MIT
Project-URL: Homepage, https://github.com/wbendinelli/dlvt
Project-URL: Documentation, https://github.com/wbendinelli/dlvt#readme
Project-URL: Repository, https://github.com/wbendinelli/dlvt
Project-URL: Bug Tracker, https://github.com/wbendinelli/dlvt/issues
Keywords: dynamical-systems,leadership,vitality,coordination-load,formal-theory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Dynamic: license-file

# dlvt — Dynamic Leadership Vitality Theory (research code)

[![CI](https://github.com/wbendinelli/dlvt/actions/workflows/ci.yml/badge.svg)](https://github.com/wbendinelli/dlvt/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/dlvt.svg)](https://pypi.org/project/dlvt/)
[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://github.com/wbendinelli/dlvt/blob/main/pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/wbendinelli/dlvt/blob/main/LICENSE)
[![Preprint](https://img.shields.io/badge/preprint-SSRN%206455001-b31b1b.svg)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6455001)
[![Cite](https://img.shields.io/badge/cite-CITATION.cff-lightgrey.svg)](https://github.com/wbendinelli/dlvt/blob/main/CITATION.cff)

Executable model, tests, and reproducible numerical experiments for
**Dynamic Leadership Vitality Theory (DLVT)** — a formal, conditional theory
of how enacted leadership scope, experienced coordination load, and
subjective vitality may coevolve. The accompanying paper is
[*Dynamic Leadership Vitality Theory: How Expanding Leadership Scope Can
Drain the Vitality That Sustains It*](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6455001)
(preprint; manuscript in preparation for journal submission).

The package implements a formal model; it is **not** a diagnostic, clinical
tool, or empirically calibrated forecasting system, and it must never be
used to classify, rank, or make decisions about individual people.

**Quick links:** [Install](#install) ·
[Quick start](#canonical-quick-start) ·
[What the implementation establishes](#what-the-implementation-establishes) ·
[Canonical API](#canonical-api) · [Tests](#tests) ·
[Cite](#cite) · [Security](https://github.com/wbendinelli/dlvt/blob/main/SECURITY.md) · [Changelog](https://github.com/wbendinelli/dlvt/blob/main/CHANGELOG.md) ·
[Contributing](https://github.com/wbendinelli/dlvt/blob/main/CONTRIBUTING.md)

This tree is the reviewed public export of a private research monorepo:
every file here is allowlisted, hash-verified
(`EXPORT_SHA256SUMS.txt`), and regenerated only through the export gate —
see "Figures and generated artifacts" below.

## Model

The regularized baseline is a two-state ODE:

```text
dV/dt = R*(1 - V/Vmax) - delta*O**gamma*V/(V + eps)
dC/dt = alpha*I - mu*C

O = O0 + beta*C**eta
I = C*V/(1 + phi*O)
```

The construct mapping is deliberately narrow:

- `V`: subjective vitality available for leadership activity;
- `C`: enacted leadership scope—decision rights, accountability, span, and
  interface obligations currently carried by the leader;
- `O`: experienced coordination load generated by scope under the modeled
  architecture;
- `I`: modeled impact flow, not observed performance.

The bundled parameter vector is illustrative. It is not an empirical estimate,
and the model time unit is not mapped to days, months, or years.

## Install

```bash
python -m pip install dlvt
```

From a clone of this repository, for development:

```bash
python -m pip install -e '.[dev]'
```

The project also includes `uv.lock` for a reproducible `uv` environment.

## Canonical quick start

```python
from dlvt import (
    classify_equilibrium,
    coordination_load,
    find_interior_equilibria,
    make_params,
    simulate,
)

p = make_params()

# Deterministic trajectory from declared initial conditions.
t, V, C, O, I, gamma_ratio = simulate(
    p,
    V0=8.0,
    C0=0.5,
    T=120.0,
)

# The exact monotone solver returns a mathematical equilibrium object.
equilibrium = find_interior_equilibria(p)[0]
print(equilibrium["V"], equilibrium["C"], equilibrium["O"])

# Classification is separate and always discloses its display threshold.
report = classify_equilibrium(p, threshold_fraction=0.5)
print(report["status"], report["threshold_value"])

# Canonical scope -> experienced-load mapping.
print(coordination_load(C=10.0, p=p))
```

At the illustrative baseline the exact solver returns approximately
`V*=4.702529`, `C*=32.033725`, and `O*=9.008431`. The label obtained from a
half-maximum threshold is only a sensitivity classification. Changing the
threshold changes the label, not the equilibrium.

## What the implementation establishes

For positive parameters and `eps > 0`, the executable/formal contract includes:

- positive invariance of regularized vitality and boundedness of the state;
- an exact necessary-and-sufficient condition for an interior equilibrium;
- uniqueness and local asymptotic stability of any interior equilibrium;
- absence of a Hopf crossing in the positive parameter domain;
- conditional global convergence relative to positive initial scope under the
  theorem's regularity assumptions;
- scope absorption for equilibrium kernels depending on scope only through
  `(V, O)`;
- a strong sufficient condition for finite-time entry into a low-vitality band
  under exogenous load.

These are properties of the equations. They do not establish prevalence among
leaders, strategic impairment, burnout, a validated threshold, or a causal
effect of an organizational intervention.

## Important semantics

`Gamma = delta*O**gamma/R` is a coefficient ratio. `Gamma > 1` does not by
itself imply `dV/dt < 0`; the sign also depends on `V`, `Vmax`, and `eps`.

`drain_coefficient_threshold(p)` returns the scope coordinate where
`Gamma == 1`, if a positive crossing exists. It is not a carrying capacity,
trapping bound, equilibrium, or substantive-outcome threshold.

`trapping_scope_bound(p)` returns the scope-coordinate bound used in the
trapping rectangle. Its return value is mathematically distinct from the
coefficient threshold. The historical name `trapping_capital_bound(p)` remains
only as a deprecated compatibility alias.

No active boundary theorem covers `eps == 0`, because `V/(V+eps)` is undefined
at `(V, eps) == (0, 0)` without an additional boundary rule.

## Canonical API

Model:

- `make_params(**overrides)`
- `validate_params(p)`
- `coordination_load(C, p)`
- `impact(V, C, O, p)`
- `dlvt_system(t, y, p)`
- `dlvt_exogenous(t, y, p, C_func)`
- `simulate(p, V0, C0, T)`

Analysis:

- `find_interior_equilibria(p)`
- `classify_equilibrium(p, threshold_fraction=...)`
- `jacobian_eigenvalues(V, C, p)`
- `drain_coefficient_threshold(p)`
- `trapping_scope_bound(p)`
- `is_low_vitality(V_star, p, threshold_fraction=...)`

Experimental modules:

- `fastslow`: quasi-static nullcline diagnostics;
- `nondimensional`: general-`eta` reduced system and dimensionless groups;
- `sobol`: formal full-domain or explicitly exploratory conditional indices;
- `stochastic`: projected Euler–Maruyama numerical experiments;
- `recovery`: deterministic least-squares recovery demonstration on synthetic
  panels, with optional noise and simplified missing-wave/dropout stress tests.

## Deprecated compatibility names

The following names encode historical semantics and should not be used in new
work. Every one emits a `DeprecationWarning`.

Direct replacements:

- `complexity()` → use `coordination_load()`;
- `carrying_capacity()` → use `drain_coefficient_threshold()`;
- `trapping_capital_bound()` → use `trapping_scope_bound()`;
- `is_zombie()` → use `is_low_vitality()` with an explicit threshold;
- `classify_regime()` → use `classify_equilibrium()`;
- `classify_point()` (`nondimensional`) → use `classify_equilibrium()`;
- `slow_manifold()` (`fastslow`) → use `quasi_static_nullcline()`;
- `sobol_indices(output='regime')` → use `output='low_vitality'`.

Deprecated with no direct replacement — build the map or screen from
continuous `classify_equilibrium()` outputs plus an explicit display
threshold:

- `regime_map()`;
- `zombie_boundary_map()`, `zombie_boundary_map_beta()`, and
  `lhs_zombie_fraction()` (`nondimensional`).

Two deprecated **mapping keys** survive beside their canonical twins, because
a dict key cannot warn on access:
`classify_equilibrium(...)["equilibrium"]["zombie"]` duplicates
`["low_vitality"]`, and `basin_of_attraction_sweep(...)["zombie_target"]`
duplicates `["equilibrium_target"]`.

Compatibility names are retained for the whole 2.2 line and are removed in
3.0.0. See `CHANGELOG.md` for the migration decision.

## Tests

From this directory:

```bash
python -m pytest tests/ -q
```

Do not rely on a hard-coded test count. CI discovery is the source of truth.
The standalone suite pins equations, boundary cases, counterexamples, scope
absorption, robustness-generator semantics, nondimensional round trips, and
experimental-module behavior. Byte-pinning of manuscript tables remains a
separate monorepo gate because those private manuscript files are deliberately
absent from the public export.

## Figures and generated artifacts

The standalone reviewed figure command is:

```bash
python scripts/generate_reviewed_figures.py --fig 2,10 --output-dir figures
```

Only Figures 2 and 10 are exposed. Their declared inputs and derived scenario
results are recorded in `artifacts/figure_scenarios.json`; CI regenerates that
manifest and compares it byte-for-byte before accepting the figures. Legacy
development figures remain outside the public export.

The parameter domain, construct mapping, illustrative values, and frozen
reference results are available in `artifacts/model_contract.json`. This file
is generated from the private monorepo's authoritative formal contract and is
byte-pinned by the monorepo artifact gate.

To materialize the exact public source tree and verify its hashes:

```bash
python scripts/check_public_export.py --export-dir /tmp/dlvt-public
python /tmp/dlvt-public/scripts/check_public_export.py \
  --check-tree /tmp/dlvt-public
```

The destination must be empty. The checker rejects missing files, unexpected
files, symlinks, path escapes, and SHA-256 drift.

The monorepo contract/table command is:

```bash
python code/scripts/generate_contract_artifacts.py --check
```

It requires the repository-level `theory/` and `tables/` directories and is not
part of a standalone package export.

## Scientific boundaries

The current implementation does not provide:

- empirical parameter estimates or posterior inference;
- a validated vitality scale or impairment threshold;
- statistical identification from equilibrium observations alone;
- a reflected-SDE theorem;
- a clinical or personnel decision rule;
- proof that the model outpredicts simpler alternatives.

Use the code to reproduce and challenge the formal model. Do not use it to
classify people.

## Cite

Citation metadata live in [`CITATION.cff`](https://github.com/wbendinelli/dlvt/blob/main/CITATION.cff) (GitHub's "Cite
this repository" uses it). Until an archival DOI is minted, cite the
software version or commit used, for example:

> Bendinelli, W. (2026). *dlvt: Dynamic Leadership Vitality Theory research
> code* (Version 2.2.0) [Computer software].
> https://github.com/wbendinelli/dlvt

The theory paper is available as an SSRN preprint (abstract id 6455001);
the manuscript remains in preparation for journal submission.

## Security

See [`SECURITY.md`](https://github.com/wbendinelli/dlvt/blob/main/SECURITY.md) for the supported-version table and how to
report a vulnerability. Dependency locks are kept current against
Dependabot advisories.

## License and citation status

The package is MIT licensed ([`LICENSE`](https://github.com/wbendinelli/dlvt/blob/main/LICENSE)). A stable archival DOI
will be added only after the manuscript and public export pass the release
gates. Until then, cite the repository version/commit used in an analysis
and describe the manuscript as in preparation.
