# How to Perform Three-Scenario Valuation Using financial_rigor.py: A Complete Guide

> Learn to perform three scenario valuation using financial_rigor.py. Discover how to calculate optimistic, neutral, and pessimistic price targets with EPS growth and PE multiples.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-11

---

**The `three_scenario_valuation` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) computes optimistic, neutral, and pessimistic price targets by compounding EPS growth over a specified period and applying scenario-specific PE multiples.**

The **xbtlin/ai-berkshire** repository provides a **Financial Rigor Toolkit** designed for reproducible equity analysis. The `three_scenario_valuation` routine sits at the heart of this toolkit, offering a deterministic way to model bull, base, and bear cases using exact decimal arithmetic to eliminate floating-point drift.

## Core Architecture of the Valuation Model

The implementation prioritizes numerical precision and transparent scenario modeling. Unlike standard floating-point calculations that accumulate rounding errors, this tool uses a dedicated decimal context for every operation.

### Exact Decimal Arithmetic

All monetary and ratio calculations rely on the `exact` helper function (defined around lines 31–38) and a shared `_CTX` context (line 28). This context enforces a fixed precision and rounding mode, ensuring that EPS projections and target prices remain identical across repeated runs. The `exact` helper converts raw inputs like share prices and growth rates into `Decimal` objects before any mathematics occurs.

### Scenario Definition Structure

The function internally defines three scenarios as a list of tuples containing the scenario name, annual growth rate, and target PE multiple (lines 33–37). These map to:

- **Optimistic**: Higher growth assumptions with premium PE multiples
- **Neutral**: Moderate growth aligned with historical averages
- **Pessimistic**: Conservative or zero growth with compressed multiples

## How to Use three_scenario_valuation in Python

Import the function directly from the tools module and supply current market data along with your three sets of assumptions.

```python
from tools.financial_rigor import three_scenario_valuation

# Current market data

price = 510                # Current share price

eps   = 23.5               # Current EPS

shares = 9.11              # Total shares (in billions)

# Growth rates for optimistic, neutral, pessimistic (15%, 8%, 0%)

growth = [0.15, 0.08, 0.00]

# Target PE multiples for each scenario

pe = [25, 20, 15]

# Run the valuation

three_scenario_valuation(
    current_price=price,
    current_eps=eps,
    shares_billion=shares,
    growth_optimistic=growth[0],
    growth_neutral=growth[1],
    growth_pessimistic=growth[2],
    pe_optimistic=pe[0],
    pe_neutral=pe[1],
    pe_pessimistic=pe[2],
    years=3,
    currency="HKD"
)

```

The function outputs a formatted table showing projected EPS, target prices, and percentage changes relative to the current market price.

## Command-Line Interface Usage

The repository exposes this functionality via the `three-scenario` sub-parser (lines 13–24 in the CLI block). This allows rapid valuation without writing Python scripts.

```bash
python3 tools/financial_rigor.py three-scenario \
    --price 510 \
    --eps 23.5 \
    --shares 9.11 \
    --growth 0.15 0.08 0.00 \
    --pe 25 20 15 \
    --years 3 \
    --currency HKD

```

When executed, the CLI forwards these arguments to the core `three_scenario_valuation` function (lines 41–45), producing identical output to the Python API.

## Step-by-Step Calculation Process

Understanding the internal mechanics helps validate your assumptions and debug outliers.

### Future EPS Projection

For each scenario, the function compounds the current EPS over the specified timeframe (default 3 years) using the scenario-specific growth rate (lines 51–53). The calculation uses exact multiplication: `future_eps = current_eps * (1 + growth_rate) ** years`.

### Target Price Calculation

The projected EPS is multiplied by the scenario's target PE multiple to derive the intrinsic value (line 54). This follows the formula: `target_price = projected_eps * pe_multiple`.

### Result Presentation

The function prints a formatted table (lines 44–58) including:
- Scenario name (乐观/中性/悲观)
- Annual growth percentage
- Target PE multiple
- Projected EPS
- Target price in the specified currency
- Percentage change from current price

All values maintain the decimal precision established by the `_CTX` context.

## Integrating into Research Workflows

You can embed this valuation routine into larger analysis pipelines. Here is a pattern for generating automated research reports:

```python
def generate_report(ticker):
    # ... fetch latest price, EPS, and share count ...

    three_scenario_valuation(
        current_price=price,
        current_eps=eps,
        shares_billion=shares,
        growth_optimistic=0.12,
        growth_neutral=0.06,
        growth_pessimistic=0.00,
        pe_optimistic=30,
        pe_neutral=22,
        pe_pessimistic=18,
        years=5,
        currency="USD"
    )
    # Append results to your markdown report

```

This approach leverages the exact-decimal engine to ensure that your valuation outputs remain consistent across different environments and Python versions.

## Summary

- **`three_scenario_valuation`** in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) implements a three-case valuation model using exact decimal arithmetic to prevent floating-point errors.
- The function requires current market data (price, EPS, shares) plus three sets of growth assumptions and PE targets.
- **Exact calculations** are ensured through the `exact` helper and `_CTX` context (lines 28–38).
- You can invoke the model **programmatically** via Python import or **interactively** through the `three-scenario` CLI command.
- The output displays projected EPS, target prices, and upside/downside percentages for optimistic, neutral, and pessimistic scenarios.

## Frequently Asked Questions

### What precision does the three-scenario valuation use for calculations?

The function uses Python's `Decimal` type with a shared context `_CTX` (line 28) that provides fixed precision and rounding modes. All inputs pass through the `exact` helper (lines 31–38) to ensure reproducible results without floating-point drift.

### Can I change the forecast period from the default 3 years?

Yes. Pass the `years` parameter to `three_scenario_valuation` or use the `--years` flag in the CLI. The function compounds EPS growth using this horizon for all three scenarios.

### Where is the CLI entry point defined in the source code?

The `three-scenario` sub-parser is defined in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) around lines 13–24. This block configures argument parsing for price, EPS, growth rates, and PE multiples, then forwards them to the core valuation function at lines 41–45.

### How does the function handle share count in billions?

The `shares_billion` parameter accepts the total share count expressed in billions (e.g., 9.11 for 9.11 billion shares). The function uses this for display purposes and any per-share calculations within the exact decimal context.