SVO Engine (Social Value of Carbon Storage)

A strict, physics-driven Node.js & TypeScript valuation model. It calculates the financial damage avoided by temporary carbon storage projects by simulating carbon decay and oceanic thermal inertia across a 600-year horizon.

Installation

The SVO engine automatically computes its complex 600-year climate arrays locally upon installation to ensure fast, lightweight execution.

Local (Node.js 20+)

git clone https://github.com/your-org/svo-engine.git
cd svo-engine
npm install

Docker (Isolated)

docker build -t svo-engine .

Note: If you use VS Code, open the folder and use the built-in .devcontainer to instantly spin up a pre-configured environment.

Quick Start (CLI)

The easiest way to see the engine in action is by running the built-in benchmark test via the Command Line Interface.

# Test the native 1-Tonne, 50-Year RCP2.6 benchmark 
npm run svo -- examples/1T-SCC-Benchmark.jsonc

(If using Docker: docker run -it svo-engine -- examples/1T-SCC-Benchmark.jsonc)

This will trace the physical climate impulse and return the Social Cost of Carbon (SCC) and the Social Value of your Offset (SVO) directly to your terminal.

Usage

1. The CLI Tester

You can test any project profile by editing the default svo-input.jsonc file in the root directory.

# Automatically loads svo-input.jsonc
npm run svo

# Pass a different configuration file explicitly:
npm run svo -- path/to/custom-input.jsonc

2. Import as a Library (Web Apps)

Once installed into your project's node_modules, the engine will automatically run its precomputation scripts, generating the physics constants locally inside your node_modules.

You can then import the engine exactly like a standard NPM library to evaluate JSON payloads in your own API routes.

import { ValuationEngine, ResearchDefaults } from 'svo-engine';
import fs from 'fs';
import path from 'path';

// 1. Load the automatically precomputed climate arrays (generated during npm install)
const constantsPath = path.resolve('./node_modules/svo-engine/src/data/constants.json');
const constants = JSON.parse(fs.readFileSync(constantsPath, 'utf8'));

// 2. Load your JSON payload (e.g. from a user upload, API request, or local file)
// Note: If you use .jsonc files with comments, strip them before parsing. 
const userInputPath = path.resolve('./svo-input.json');
const userConfig = JSON.parse(fs.readFileSync(userInputPath, 'utf8'));

// 3. Combine base parameters with the strict, explicitly required payload inputs
const params = {
    ...ResearchDefaults.Valuation, // Inherits default base parameters mathematically (gamma_scalar, etc.)
    discount_rate_decimal: userConfig.Valuation.discount_rate_decimal,
    gdp_growth_decimal: userConfig.Valuation.gdp_growth_decimal,
    phi_decimal: userConfig.Risk.phi_decimal,
    varphi_decimal: userConfig.Risk.varphi_decimal,
    type: userConfig.type,
    timeline: userConfig.timeline
};

// 4. Process the SVO
const scenario = userConfig.scenario;
const result = ValuationEngine.process(params, constants, scenario);

console.log(`Avoided Damages: $${result.svo}`); 

Configuration / Parameters

Input Schema (svo-input.jsonc)

The CLI and the ValuationEngine.process() method accept these standard economic variables.

| Parameter | Default | Description | |-----------|---------|-------------| | scenario | rcp4.5 | The baseline climate path (rcp2.6, rcp4.5, rcp6.0, rcp8.5). | | type | removal | removal (e.g. DAC, Afforestation) or conservation (e.g. Peat, Forestry). | | discount_rate_decimal | 0.032 (3.2%) | Economic time-value-of-money penalty applied annually to future damages. | | gdp_growth_decimal | 0.02 (2%) | Annual global GDP growth assumption used in the damage function. | | gamma_scalar | "medium" | Damage function severity. "low" (0.0050, Nordhaus DICE 2017), "medium" (0.0154, Howard & Sterner 2017), "high" (0.030, Weitzman 2012), or an explicit float. | | starting_gdp_trillions_usd| 85 | The absolute baseline global GDP in the year the project starts. | | phi_decimal | 0.01 (1%) | Project failure risk: fraction of carbon stock lost annually to decay. | | varphi_decimal | 0.0 or 0.25 | Immediate verification uncertainty penalty (0% active removal, 25% conservation). |

Output Contract (ValuationResult)

Every calculation returns a strict JSON object detailing the physical valuation of the project:

{
  "scc": 82.43,
  "svo": 37.33,
  "ratio": 0.45,
  "multiplier": 2.21,
  "metadata": { ... }
}

• scc (Social Cost of Carbon): The global benchmark damage (in USD) caused by 1 permanent tonne of CO₂ entering the atmosphere today.
• svo (Social Value of Offset): The financial damages safely avoided by your imperfect/temporary project timeline.
• ratio: SVO / SCC. The "quality score" of your temporary offset compared to a permanent one (e.g. 0.45 = 45% of the value of permanent storage).
• multiplier: 1 / ratio. The exact number of project tonnes required to mathematically equal 1 permanent tonne (e.g. 2.21 project tonnes needed).

📚 Examples & Documentation

• examples/benchmark.ts: A heavily-commented, complete integration script demonstrating how to natively import the codebase into a TS environment and execute the exact math that generated the globally recognized ~$37 SVO Target checkpoint.
• examples/1T-SCC-Benchmark.jsonc: The CLI-equivalent of the benchmark script.
• docs/svo_physics_and_economics.md: Deep dive into the Four-Pool exponential decay (Joos) and Thermal Inertia (Geoffroy) physics models.
• docs/system_architecture.md: Diagramming the pipeline steps and class interactions.