"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Discounted cash flow valuation: WACC, the FCFF bridge, dual terminal value,
discounting, and the bridge from enterprise value to value per share.
This module is the executable form of the DCF walkthrough that used to live as
markdown in valuation write-ups -- a WACC formula, an FCFF formula, a Gordon
growth terminal value, all typed out fresh (and inconsistently) on every run.
Several design choices are deliberate and are exactly the places a hand-rolled
DCF usually goes wrong silently.
**No valuation parameter defaults to anything.** This follows
:mod:`src.quantlib.valuation.contracts` to the letter: the risk-free rate,
beta, the equity risk premium, the cost of debt, the tax rate, the terminal
growth rate, the exit multiple and the diluted share count are all required
arguments with no fallback value anywhere in this file. :func:`run_dcf` takes
them as a flat mapping and refuses to run with :class:`~..contracts.MissingInputError`
if any is absent, so a caller assembling a model from filings learns exactly
what is still missing rather than getting a number built on a guess.
**Terminal growth and the exit multiple are Assumptions, not bare floats.**
``contracts.py``'s own docstring names "terminal growth quietly defaulted to
2.5%" as the canonical example of a valuation opinion wearing a constant's
clothes. Both terminal-value drivers here must therefore arrive as
:class:`~..contracts.Assumption` objects carrying a ``basis`` -- the model
refuses a bare number for either one, and the justification travels through to
:class:`TerminalValueResult` so it can be checked, not just the output.
**Terminal value is always computed two ways, and the two are cross-checked.**
:func:`terminal_value` never runs the perpetuity-growth method alone: it also
runs the exit-multiple method and reports each one's implied version of the
other's driver -- the perpetuity value's implied EV/EBITDA multiple, and the
exit value's implied perpetuity growth rate. This is the only mechanism that
catches a terminal assumption that is arithmetically fine but economically
detached from reality (a growth rate that implies a 35x EBITDA multiple is
wrong even though the Gordon growth formula was applied correctly). ``growth
>= WACC`` is refused outright -- the terminal value is undefined there, not
merely large -- while growth above a long-run nominal GDP reference is only
flagged, because that is a judgment call the model has no standing to veto.
**``delta_nwc`` sign convention.** An *increase* in net working capital is a
*use* of cash: ``delta_nwc > 0`` means working capital grew period over
period and is subtracted from FCFF; a working-capital release
(``delta_nwc < 0``) adds cash back. This is the ordinary balance-sheet
convention, stated explicitly because the alternative reading (delta_nwc as
"cash contribution") is exactly as common in the wild and the two disagree on
every sign.
**Discounting convention is exact, not approximate, at the enterprise-value
level.** Mid-year discounting multiplies every present value by exactly
``(1 + WACC) ** 0.5`` relative to year-end discounting, for one reason: this
module discounts the terminal value using the *same* time index as the final
explicit forecast year (``t = n - 0.5`` under mid-year, ``t = n`` under
year-end), so every dollar in the model -- explicit FCFF or terminal value --
is scaled by the identical constant when the convention flips. That makes the
mid-year/year-end enterprise-value ratio equal to ``sqrt(1 + WACC)`` exactly,
not approximately, which is a strong assertion the test suite checks bit for
bit. The equality does *not* extend to equity value or value per share, since
the net-debt bridge below enterprise value is a fixed balance-sheet fact that
does not scale with the discounting convention.
**Equity bridge sign convention.** Every line between enterprise value and
equity value is supplied as a **non-negative magnitude**; the formula itself
applies the sign::
equity_value = EV - total_debt + cash_and_equivalents - minority_interest
- preferred_equity + associate_investments
Passing a negative magnitude is refused rather than silently flipping the
formula's intent, because that is the single most common sign error in a
hand-built bridge.
**Capital-structure basis is a required, explicit argument.** WACC weights can
come from *current* market values (``E / (D + E)``, ``D / (D + E)`` off
today's market value of equity and debt) or from a *target* structure the
analyst believes the firm is moving toward. The two are not interchangeable:
current weights are only the theoretically correct WACC weights if the firm
intends to hold that mix going forward, and a firm expected to lever up or
delever needs target weights instead (Copeland/Koller enterprise-DCF
convention). Nothing here picks one silently -- see
``capital_structure_basis`` on :func:`wacc` and :func:`run_dcf`.
"""
from __future__ import annotations
import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from typing import Any
import numpy as np
import pandas as pd
from src.quantlib.valuation.contracts import (
Assumption,
MissingInputError,
ValuationError,
require_inputs,
require_positive,
)
__all__ = [
"CAPITAL_STRUCTURE_BASES",
"DISCOUNTING_CONVENTIONS",
"TERMINAL_VALUE_METHODS",
"DEFAULT_LONG_RUN_GDP_GROWTH_CEILING",
"DCF_BASE_REQUIRED_FIELDS",
"DCF_CURRENT_STRUCTURE_FIELDS",
"DCF_TARGET_STRUCTURE_FIELDS",
"WACCResult",
"FCFFYear",
"TerminalValueResult",
"DiscountedCashFlow",
"NetDebtBridgeResult",
"DCFResult",
"wacc",
"fcff_bridge",
"terminal_value",
"discount_fcff",
"equity_bridge",
"run_dcf",
"sensitivity_grid",
]
#: How WACC's capital-structure weights are sourced. ``"current"`` derives
#: ``E / (D + E)`` and ``D / (D + E)`` from today's market values; ``"target"``
#: takes the weights directly as the analyst's view of the structure the firm
#: is moving toward. See the module docstring for why the two are not
#: interchangeable.
CAPITAL_STRUCTURE_BASES: tuple[str, ...] = ("current", "target")
#: Timing convention for discounting a cash flow that arrives sometime during
#: year ``t``. ``"mid_year"`` assumes it lands on average at ``t - 0.5``;
#: ``"year_end"`` assumes it lands at ``t``.
DISCOUNTING_CONVENTIONS: tuple[str, ...] = ("mid_year", "year_end")
#: Which terminal-value estimate feeds the enterprise-value bridge. Both
#: methods are always computed and cross-checked (see :func:`terminal_value`);
#: this only selects which one is discounted into ``DCFResult.enterprise_value``.
TERMINAL_VALUE_METHODS: tuple[str, ...] = ("perpetuity_growth", "exit_multiple")
#: Reference ceiling used only to FLAG a perpetuity growth assumption, never to
#: block or alter one -- a terminal growth rate above long-run nominal GDP
#: growth is not mathematically wrong, only worth a second look. This is a
#: diagnostic threshold, not a valuation input: it never appears in any formula
#: that produces a price. 4% approximates long-run US real GDP growth
#: (~2%) plus a long-run inflation target (~2%); callers valuing a business
#: against a different economy should pass their own ``gdp_growth_ceiling``.
DEFAULT_LONG_RUN_GDP_GROWTH_CEILING: float = 0.04
#: Flat input-mapping keys :func:`run_dcf` requires regardless of
#: ``capital_structure_basis``.
DCF_BASE_REQUIRED_FIELDS: tuple[str, ...] = (
"risk_free_rate",
"beta",
"equity_risk_premium",
"pretax_cost_of_debt",
"tax_rate",
"ebit",
"depreciation_amortization",
"capex",
"delta_nwc",
"terminal_growth",
"exit_multiple",
"total_debt",
"cash_and_equivalents",
"minority_interest",
"preferred_equity",
"associate_investments",
"diluted_shares",
)
#: Additional keys :func:`run_dcf` requires when ``capital_structure_basis="current"``.
DCF_CURRENT_STRUCTURE_FIELDS: tuple[str, ...] = (
"market_value_of_equity",
"market_value_of_debt",
)
#: Additional keys :func:`run_dcf` requires when ``capital_structure_basis="target"``.
DCF_TARGET_STRUCTURE_FIELDS: tuple[str, ...] = (
"target_equity_weight",
"target_debt_weight",
)
#: Slack allowed when checking that capital-structure weights sum to 1, and
#: when re-checking a dataclass's own internal arithmetic in ``__post_init__``.
_RECONCILIATION_TOLERANCE: float = 1e-6
# ---------------------------------------------------------------------------
# small private helpers
# ---------------------------------------------------------------------------
def _require_assumption(value: Any, expected_name: str, model: str) -> Assumption:
"""Check that a terminal-value driver arrived as a justified Assumption.
Args:
value: Candidate supplied by the caller.
expected_name: The :attr:`Assumption.name` this slot expects.
model: Name used in the error message.
Returns:
``value``, unchanged.
Raises:
ValuationError: If ``value`` is not an :class:`Assumption`, or if its
``name`` does not match ``expected_name`` (which usually means two
assumptions were passed under swapped keys).
"""
if not isinstance(value, Assumption):
raise ValuationError(
f"{model}: {expected_name!r} must be supplied as an Assumption("
f"name=..., value=..., basis=...) carrying its justification, not "
f"a bare {type(value).__name__}. A terminal growth rate or exit "
"multiple chosen without a stated reason is exactly the kind of "
"silent default this package refuses to make on your behalf."
)
if value.name != expected_name:
raise ValuationError(
f"{model}: expected an Assumption named {expected_name!r}, got "
f"{value.name!r}; check that assumptions were not passed under "
"swapped keys."
)
return value
def _require_nonnegative(value: float, name: str, model: str) -> float:
"""Check a value that is a signed formula's magnitude, so must be >= 0.
Args:
value: The candidate magnitude.
name: Field name for the error message.
model: Model name for the error message.
Returns:
``value`` as a float.
Raises:
ValuationError: If the value is negative or not a finite number. A
negative magnitude here would silently flip the sign the bridge
formula already applies.
"""
try:
numeric = float(value)
except (TypeError, ValueError) as exc:
raise ValuationError(f"{model}: {name} must be a number, got {value!r}") from exc
if not math.isfinite(numeric) or numeric < 0.0:
raise ValuationError(
f"{model}: {name} must be supplied as a non-negative magnitude "
f"(its sign is applied by the bridge formula), got {numeric!r}"
)
return numeric
def _require_finite(value: float, name: str, model: str) -> float:
"""Check a value is a finite number, refusing NaN and infinity.
Args:
value: The candidate value.
name: Field name for the error message.
model: Model name for the error message.
Returns:
``value`` as a float.
Raises:
ValuationError: If the value is not a finite number. A non-finite
input here would otherwise flow through the valuation arithmetic
and surface as a silently wrong per-share number, which is exactly
the outcome the package's no-silent-defaults rule exists to prevent.
"""
try:
numeric = float(value)
except (TypeError, ValueError) as exc:
raise ValuationError(f"{model}: {name} must be a number, got {value!r}") from exc
if not math.isfinite(numeric):
raise ValuationError(
f"{model}: {name} must be a finite number, got {numeric!r}"
)
return numeric
def _validate_weights(equity_weight: float, debt_weight: float, *, model: str) -> None:
"""Check that a pair of capital-structure weights is usable.
Args:
equity_weight: Proposed ``E / (D + E)``.
debt_weight: Proposed ``D / (D + E)``.
model: Model name for the error message.
Raises:
ValuationError: If either weight is negative, or if they do not sum to
1 within :data:`_RECONCILIATION_TOLERANCE`.
"""
if equity_weight < 0.0 or debt_weight < 0.0:
raise ValuationError(
f"{model}: capital-structure weights must be non-negative, got "
f"equity_weight={equity_weight!r} debt_weight={debt_weight!r}"
)
total = equity_weight + debt_weight
if abs(total - 1.0) > _RECONCILIATION_TOLERANCE:
raise ValuationError(
f"{model}: capital-structure weights must sum to 1 (within "
f"{_RECONCILIATION_TOLERANCE:g}), got equity_weight={equity_weight!r} "
f"+ debt_weight={debt_weight!r} = {total!r}"
)
# ---------------------------------------------------------------------------
# WACC
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class WACCResult:
"""The WACC build, with every component that fed it kept visible.
Attributes:
risk_free_rate: ``rf`` used in CAPM.
beta: Levered beta used in CAPM.
equity_risk_premium: ``ERP`` used in CAPM.
size_premium: Additive small-cap premium, ``0.0`` if not supplied.
country_risk_premium: Additive sovereign/country premium, ``0.0`` if
not supplied.
cost_of_equity: ``Re = rf + beta * ERP + size_premium + country_risk_premium``.
pretax_cost_of_debt: ``Rd`` before the tax shield.
tax_rate: Marginal tax rate applied to the debt tax shield (and, in
:func:`fcff_bridge`, to EBIT -- the same statutory rate drives both).
cost_of_debt_after_tax: ``Rd * (1 - tax_rate)``.
capital_structure_basis: ``"current"`` or ``"target"``; see the module
docstring for the difference.
equity_weight: ``E / (D + E)``.
debt_weight: ``D / (D + E)``.
wacc: The blended discount rate,
``equity_weight * cost_of_equity + debt_weight * cost_of_debt_after_tax``.
"""
risk_free_rate: float
beta: float
equity_risk_premium: float
size_premium: float
country_risk_premium: float
cost_of_equity: float
pretax_cost_of_debt: float
tax_rate: float
cost_of_debt_after_tax: float
capital_structure_basis: str
equity_weight: float
debt_weight: float
wacc: float
def __post_init__(self) -> None:
"""Re-check the blend arithmetic and the weight identity.
Raises:
ValueError: If the weights do not sum to 1, or ``wacc`` is not the
stated weighted blend of the two costs of capital.
"""
_validate_weights(self.equity_weight, self.debt_weight, model="WACCResult")
expected = (
self.equity_weight * self.cost_of_equity
+ self.debt_weight * self.cost_of_debt_after_tax
)
if not math.isclose(
self.wacc, expected, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-12
):
raise ValueError(
f"WACCResult.wacc={self.wacc!r} does not match the weighted "
f"blend {expected!r} of cost_of_equity and cost_of_debt_after_tax"
)
def wacc(
*,
risk_free_rate: float,
beta: float,
equity_risk_premium: float,
pretax_cost_of_debt: float,
tax_rate: float,
capital_structure_basis: str,
market_value_of_equity: float | None = None,
market_value_of_debt: float | None = None,
target_equity_weight: float | None = None,
target_debt_weight: float | None = None,
size_premium: float = 0.0,
country_risk_premium: float = 0.0,
) -> WACCResult:
"""Build the weighted average cost of capital.
``Re`` is CAPM plus two optional additive premiums; ``Rd`` is the pretax
cost of debt shielded by the tax rate; the two are blended by
capital-structure weights sourced per ``capital_structure_basis``.
Args:
risk_free_rate: ``rf``, as a decimal.
beta: Levered equity beta.
equity_risk_premium: ``ERP``, as a decimal.
pretax_cost_of_debt: ``Rd`` before the tax shield, as a decimal.
tax_rate: Marginal tax rate in ``[0, 1]``.
capital_structure_basis: One of :data:`CAPITAL_STRUCTURE_BASES`.
``"current"`` derives weights from today's market values;
``"target"`` takes the weights directly. Required, no default --
see the module docstring for why the two are not interchangeable.
market_value_of_equity: Market value of equity. Required (and only
used) when ``capital_structure_basis="current"``.
market_value_of_debt: Market value of debt. Required (and only used)
when ``capital_structure_basis="current"``.
target_equity_weight: Target ``E / (D + E)``. Required (and only used)
when ``capital_structure_basis="target"``.
target_debt_weight: Target ``D / (D + E)``. Required (and only used)
when ``capital_structure_basis="target"``.
size_premium: Additive small-cap premium on cost of equity. Optional --
absence means "not applying one", which is a structural choice, not
a guessed magnitude standing in for an unknown rate.
country_risk_premium: Additive sovereign/country premium on cost of
equity. Same optionality rationale as ``size_premium``.
Returns:
A :class:`WACCResult` with every intermediate figure visible.
Raises:
MissingInputError: If the market-value or target-weight pair matching
``capital_structure_basis`` is not fully supplied.
ValuationError: If ``capital_structure_basis`` is unrecognised, if
``tax_rate`` is outside ``[0, 1]``, if a market value is negative
or not finite, if the market value of equity plus debt is zero
(weights undefined), if the resulting weights are negative or do
not sum to 1, or if ``risk_free_rate``, ``beta``,
``equity_risk_premium``, ``pretax_cost_of_debt``, ``size_premium``,
``country_risk_premium`` or a target weight is not a finite number.
"""
if capital_structure_basis not in CAPITAL_STRUCTURE_BASES:
raise ValuationError(
f"wacc: capital_structure_basis must be one of "
f"{CAPITAL_STRUCTURE_BASES}, got {capital_structure_basis!r}"
)
if not 0.0 <= tax_rate <= 1.0:
raise ValuationError(f"wacc: tax_rate must be within [0, 1], got {tax_rate!r}")
if capital_structure_basis == "current":
missing = [
name
for name, value in (
("market_value_of_equity", market_value_of_equity),
("market_value_of_debt", market_value_of_debt),
)
if value is None
]
if missing:
raise MissingInputError(missing, "wacc")
equity_mv = _require_nonnegative(
market_value_of_equity, "market_value_of_equity", "wacc"
)
debt_mv = _require_nonnegative(
market_value_of_debt, "market_value_of_debt", "wacc"
)
total_mv = equity_mv + debt_mv
if total_mv <= 0.0:
raise ValuationError(
"wacc: market value of equity plus debt is zero (D + E = 0); "
"capital-structure weights are undefined"
)
equity_weight = equity_mv / total_mv
debt_weight = debt_mv / total_mv
else:
missing = [
name
for name, value in (
("target_equity_weight", target_equity_weight),
("target_debt_weight", target_debt_weight),
)
if value is None
]
if missing:
raise MissingInputError(missing, "wacc")
equity_weight = _require_finite(
target_equity_weight, "target_equity_weight", "wacc"
)
debt_weight = _require_finite(target_debt_weight, "target_debt_weight", "wacc")
_validate_weights(equity_weight, debt_weight, model="wacc")
risk_free_rate = _require_finite(risk_free_rate, "risk_free_rate", "wacc")
beta = _require_finite(beta, "beta", "wacc")
equity_risk_premium = _require_finite(equity_risk_premium, "equity_risk_premium", "wacc")
pretax_cost_of_debt = _require_finite(pretax_cost_of_debt, "pretax_cost_of_debt", "wacc")
size_premium = _require_finite(size_premium, "size_premium", "wacc")
country_risk_premium = _require_finite(country_risk_premium, "country_risk_premium", "wacc")
cost_of_equity = (
risk_free_rate + beta * equity_risk_premium + size_premium + country_risk_premium
)
cost_of_debt_after_tax = pretax_cost_of_debt * (1.0 - tax_rate)
blended = equity_weight * cost_of_equity + debt_weight * cost_of_debt_after_tax
return WACCResult(
risk_free_rate=float(risk_free_rate),
beta=float(beta),
equity_risk_premium=float(equity_risk_premium),
size_premium=float(size_premium),
country_risk_premium=float(country_risk_premium),
cost_of_equity=cost_of_equity,
pretax_cost_of_debt=float(pretax_cost_of_debt),
tax_rate=float(tax_rate),
cost_of_debt_after_tax=cost_of_debt_after_tax,
capital_structure_basis=capital_structure_basis,
equity_weight=equity_weight,
debt_weight=debt_weight,
wacc=blended,
)
# ---------------------------------------------------------------------------
# FCFF bridge
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class FCFFYear:
"""One projection year's bridge from EBIT to free cash flow to the firm.
``FCFF = NOPAT + depreciation_amortization - capex - delta_nwc``. Every
step is a field so a reader can see which one consumed the cash, not just
the final number.
Attributes:
year: 1-indexed projection year (1 is the first forecast year).
ebit: Earnings before interest and tax.
tax_rate: Marginal tax rate applied to EBIT.
nopat: ``ebit * (1 - tax_rate)``.
depreciation_amortization: Non-cash D&A added back.
capex: Capital expenditure, a positive magnitude representing a cash
outflow.
delta_nwc: Change in net working capital. **Positive means working
capital increased and cash was used**; negative means working
capital was released and cash was returned. See the module
docstring.
fcff: ``nopat + depreciation_amortization - capex - delta_nwc``.
"""
year: int
ebit: float
tax_rate: float
nopat: float
depreciation_amortization: float
capex: float
delta_nwc: float
fcff: float
def __post_init__(self) -> None:
"""Re-check the NOPAT and FCFF arithmetic.
Raises:
ValueError: If ``nopat`` or ``fcff`` do not match their formulas,
or ``year`` is not a positive integer.
"""
if self.year < 1:
raise ValueError(f"FCFFYear.year must be >= 1, got {self.year!r}")
expected_nopat = self.ebit * (1.0 - self.tax_rate)
if not math.isclose(
self.nopat, expected_nopat, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-9
):
raise ValueError(
f"FCFFYear(year={self.year}).nopat={self.nopat!r} does not match "
f"ebit * (1 - tax_rate) = {expected_nopat!r}"
)
expected_fcff = (
self.nopat + self.depreciation_amortization - self.capex - self.delta_nwc
)
if not math.isclose(
self.fcff, expected_fcff, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-9
):
raise ValueError(
f"FCFFYear(year={self.year}).fcff={self.fcff!r} does not match the "
f"bridge total {expected_fcff!r}"
)
def fcff_bridge(
*,
ebit: Sequence[float],
tax_rate: float,
depreciation_amortization: Sequence[float],
capex: Sequence[float],
delta_nwc: Sequence[float],
) -> tuple[FCFFYear, ...]:
"""Build the EBIT -> FCFF bridge for every projection year.
Args:
ebit: EBIT forecast, one entry per projection year, oldest first.
tax_rate: Marginal tax rate in ``[0, 1]``, applied to every year.
depreciation_amortization: D&A forecast, same length as ``ebit``.
capex: Capital expenditure forecast (positive = cash outflow), same
length as ``ebit``.
delta_nwc: Net-working-capital change forecast (positive = cash
outflow; see the module docstring), same length as ``ebit``.
Returns:
One :class:`FCFFYear` per projection year, in order.
Raises:
ValuationError: If ``tax_rate`` is outside ``[0, 1]``, if ``ebit`` is
empty, if the other three forecasts are not the same length as
``ebit``, or if any forecast entry is not a finite number.
"""
if not 0.0 <= tax_rate <= 1.0:
raise ValuationError(f"fcff_bridge: tax_rate must be within [0, 1], got {tax_rate!r}")
ebit_list = list(ebit)
horizon = len(ebit_list)
if horizon == 0:
raise ValuationError(
"fcff_bridge: ebit forecast is empty; at least one projection year "
"is required"
)
forecasts = {
"depreciation_amortization": list(depreciation_amortization),
"capex": list(capex),
"delta_nwc": list(delta_nwc),
}
for name, values in forecasts.items():
if len(values) != horizon:
raise ValuationError(
f"fcff_bridge: {name} has {len(values)} year(s), expected "
f"{horizon} to match ebit"
)
years = []
for index in range(horizon):
ebit_value = _require_finite(ebit_list[index], f"ebit[{index}]", "fcff_bridge")
da_value = _require_finite(
forecasts["depreciation_amortization"][index],
f"depreciation_amortization[{index}]",
"fcff_bridge",
)
capex_value = _require_finite(
forecasts["capex"][index], f"capex[{index}]", "fcff_bridge"
)
delta_nwc_value = _require_finite(
forecasts["delta_nwc"][index], f"delta_nwc[{index}]", "fcff_bridge"
)
nopat = ebit_value * (1.0 - tax_rate)
fcff_value = nopat + da_value - capex_value - delta_nwc_value
years.append(
FCFFYear(
year=index + 1,
ebit=ebit_value,
tax_rate=tax_rate,
nopat=nopat,
depreciation_amortization=da_value,
capex=capex_value,
delta_nwc=delta_nwc_value,
fcff=fcff_value,
)
)
return tuple(years)
# ---------------------------------------------------------------------------
# Dual terminal value
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class TerminalValueResult:
"""Both terminal-value estimates, each cross-checked against the other.
Attributes:
wacc_rate: Discount rate used by the perpetuity-growth method.
terminal_growth: The :class:`Assumption` behind the perpetuity-growth
method, carrying its ``basis``.
perpetuity_terminal_value: ``FCFF_{n+1} / (wacc_rate - g)`` where
``FCFF_{n+1} = FCFF_n * (1 + g)``.
terminal_year_ebitda: ``EBITDA`` of the final explicit forecast year,
used by the exit-multiple method.
exit_multiple: The :class:`Assumption` behind the exit-multiple
method, carrying its ``basis``.
exit_terminal_value: ``terminal_year_ebitda * exit_multiple.value``.
implied_ev_ebitda_multiple: What EV/EBITDA multiple
``perpetuity_terminal_value`` implies -- the perpetuity method's
result, restated in the exit method's units, so a reader can judge
whether the growth assumption is realistic on its face.
implied_perpetuity_growth: What perpetuity growth rate
``exit_terminal_value`` implies -- the exit method's result,
restated in the perpetuity method's units.
gdp_growth_ceiling: Reference ceiling used for ``growth_exceeds_gdp_ceiling``.
growth_exceeds_gdp_ceiling: ``True`` if ``terminal_growth.value`` is
above ``gdp_growth_ceiling``. A flag, never an error -- see the
module docstring.
"""
wacc_rate: float
terminal_growth: Assumption
perpetuity_terminal_value: float
terminal_year_ebitda: float
exit_multiple: Assumption
exit_terminal_value: float
implied_ev_ebitda_multiple: float
implied_perpetuity_growth: float
gdp_growth_ceiling: float
growth_exceeds_gdp_ceiling: bool
def __post_init__(self) -> None:
"""Re-check that the stored growth rate is still below WACC.
Raises:
ValueError: If ``terminal_growth.value >= wacc_rate``. This should
already have been refused by :func:`terminal_value` before
construction; this is a second, independent check.
"""
if float(self.terminal_growth.value) >= self.wacc_rate:
raise ValueError(
f"TerminalValueResult.terminal_growth.value="
f"{self.terminal_growth.value!r} is not below wacc_rate="
f"{self.wacc_rate!r}"
)
def terminal_value(
*,
final_year_fcff: float,
terminal_year_ebitda: float,
wacc_rate: float,
terminal_growth: Assumption,
exit_multiple: Assumption,
gdp_growth_ceiling: float = DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,
) -> TerminalValueResult:
"""Compute both terminal-value estimates and cross-validate them.
Args:
final_year_fcff: ``FCFF_n``, the last explicit forecast year's free
cash flow to the firm.
terminal_year_ebitda: ``EBITDA`` of the final explicit forecast year.
wacc_rate: The discount rate, as a decimal.
terminal_growth: An :class:`Assumption` naming the perpetuity growth
rate ``g`` and its basis.
exit_multiple: An :class:`Assumption` naming the EV/EBITDA exit
multiple and its basis.
gdp_growth_ceiling: Reference ceiling used only to flag
``terminal_growth`` -- see :data:`DEFAULT_LONG_RUN_GDP_GROWTH_CEILING`.
Returns:
A :class:`TerminalValueResult` carrying both terminal values and both
cross-checks.
Raises:
ValuationError: If either argument is not the matching
:class:`Assumption`; if ``wacc_rate``, ``final_year_fcff``,
``terminal_year_ebitda``, ``terminal_growth.value`` or
``exit_multiple.value`` is not a finite number; if ``wacc_rate <= -1``;
if ``terminal_growth.value >= wacc_rate`` (the perpetuity terminal
value is negative or infinite there, not merely large); if
``terminal_year_ebitda <= 0`` (an EV/EBITDA multiple is undefined);
if ``exit_multiple.value <= 0``; or if the exit terminal value
happens to equal ``-final_year_fcff`` exactly, which makes the
implied-growth reverse-solve's denominator zero.
"""
_require_assumption(terminal_growth, "terminal_growth", "terminal_value")
_require_assumption(exit_multiple, "exit_multiple", "terminal_value")
final_year_fcff = _require_finite(final_year_fcff, "final_year_fcff", "terminal_value")
terminal_year_ebitda = _require_finite(
terminal_year_ebitda, "terminal_year_ebitda", "terminal_value"
)
wacc_rate = _require_finite(wacc_rate, "wacc_rate", "terminal_value")
if wacc_rate <= -1.0:
raise ValuationError(
f"terminal_value: wacc_rate must exceed -1, got {wacc_rate!r}"
)
growth = _require_finite(terminal_growth.value, "terminal_growth.value", "terminal_value")
if growth >= wacc_rate:
raise ValuationError(
f"terminal_value: terminal_growth ({growth!r}) must be strictly "
f"less than WACC ({wacc_rate!r}); at or above WACC the Gordon-growth "
"terminal value is negative or infinite, not merely a large number. "
"Lower the growth assumption or check the WACC build."
)
if terminal_year_ebitda <= 0.0:
raise ValuationError(
f"terminal_value: terminal_year_ebitda must be positive to derive "
f"an implied EV/EBITDA multiple, got {terminal_year_ebitda!r}"
)
multiple = _require_finite(exit_multiple.value, "exit_multiple.value", "terminal_value")
if multiple <= 0.0:
raise ValuationError(
f"terminal_value: exit_multiple.value must be positive, got {multiple!r}"
)
next_year_fcff = final_year_fcff * (1.0 + growth)
perpetuity_tv = next_year_fcff / (wacc_rate - growth)
exit_tv = terminal_year_ebitda * multiple
implied_ev_ebitda_multiple = perpetuity_tv / terminal_year_ebitda
denominator = exit_tv + final_year_fcff
if denominator == 0.0:
raise ValuationError(
"terminal_value: cannot solve the exit multiple's implied perpetuity "
"growth because exit_terminal_value and final_year_fcff are equal "
"and opposite, making the reverse-solve denominator zero"
)
implied_perpetuity_growth = (exit_tv * wacc_rate - final_year_fcff) / denominator
return TerminalValueResult(
wacc_rate=float(wacc_rate),
terminal_growth=terminal_growth,
perpetuity_terminal_value=perpetuity_tv,
terminal_year_ebitda=float(terminal_year_ebitda),
exit_multiple=exit_multiple,
exit_terminal_value=exit_tv,
implied_ev_ebitda_multiple=implied_ev_ebitda_multiple,
implied_perpetuity_growth=implied_perpetuity_growth,
gdp_growth_ceiling=float(gdp_growth_ceiling),
growth_exceeds_gdp_ceiling=growth > gdp_growth_ceiling,
)
# ---------------------------------------------------------------------------
# Discounting
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class DiscountedCashFlow:
"""One projection year's FCFF, discounted to present value.
Attributes:
year: 1-indexed projection year, matching :attr:`FCFFYear.year`.
fcff: The undiscounted free cash flow to the firm for this year.
wacc_rate: Discount rate used.
time_period: The exponent ``t`` actually used --
``year - 0.5`` under ``"mid_year"``, ``year`` under ``"year_end"``.
discount_factor: ``(1 + wacc_rate) ** -time_period``.
present_value: ``fcff * discount_factor``.
"""
year: int
fcff: float
wacc_rate: float
time_period: float
discount_factor: float
present_value: float
def __post_init__(self) -> None:
"""Re-check the discount factor and present-value arithmetic.
Raises:
ValueError: If ``discount_factor`` or ``present_value`` do not
match their formulas.
"""
expected_factor = (1.0 + self.wacc_rate) ** (-self.time_period)
if not math.isclose(
self.discount_factor, expected_factor, rel_tol=1e-9, abs_tol=1e-12
):
raise ValueError(
f"DiscountedCashFlow(year={self.year}).discount_factor="
f"{self.discount_factor!r} does not match "
f"(1 + wacc_rate) ** -time_period = {expected_factor!r}"
)
expected_pv = self.fcff * self.discount_factor
if not math.isclose(self.present_value, expected_pv, rel_tol=1e-9, abs_tol=1e-9):
raise ValueError(
f"DiscountedCashFlow(year={self.year}).present_value="
f"{self.present_value!r} does not match fcff * discount_factor "
f"= {expected_pv!r}"
)
def discount_fcff(
fcff_years: Sequence[FCFFYear],
*,
wacc_rate: float,
discounting_convention: str,
) -> tuple[DiscountedCashFlow, ...]:
"""Discount every projection year's FCFF to present value.
Args:
fcff_years: The FCFF bridge, e.g. from :func:`fcff_bridge`.
wacc_rate: Discount rate, as a decimal, strictly greater than -1.
discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.
Required, no default -- see the module docstring for why mid-year
and year-end are not interchangeable.
Returns:
One :class:`DiscountedCashFlow` per input year, in the same order.
Raises:
ValuationError: If ``discounting_convention`` is unrecognised, if
``fcff_years`` is empty, if ``wacc_rate`` is not a finite number,
or if ``wacc_rate <= -1``.
"""
if discounting_convention not in DISCOUNTING_CONVENTIONS:
raise ValuationError(
f"discount_fcff: discounting_convention must be one of "
f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"
)
if not fcff_years:
raise ValuationError("discount_fcff: fcff_years is empty")
wacc_rate = _require_finite(wacc_rate, "wacc_rate", "discount_fcff")
if wacc_rate <= -1.0:
raise ValuationError(f"discount_fcff: wacc_rate must exceed -1, got {wacc_rate!r}")
results = []
for entry in fcff_years:
time_period = (
entry.year - 0.5 if discounting_convention == "mid_year" else float(entry.year)
)
discount_factor_value = (1.0 + wacc_rate) ** (-time_period)
results.append(
DiscountedCashFlow(
year=entry.year,
fcff=entry.fcff,
wacc_rate=float(wacc_rate),
time_period=time_period,
discount_factor=discount_factor_value,
present_value=entry.fcff * discount_factor_value,
)
)
return tuple(results)
# ---------------------------------------------------------------------------
# Net-debt bridge to value per share
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class NetDebtBridgeResult:
"""The bridge from enterprise value to value per share.
Every balance-sheet item is a non-negative magnitude; the sign each one
carries in the formula is fixed and documented here, not inferred from the
number's own sign.
Attributes:
enterprise_value: EV entering the bridge.
total_debt: Subtracted -- debt is a claim ahead of equity.
cash_and_equivalents: Added -- cash is equity value EV does not price.
minority_interest: Subtracted -- non-controlling interests' claim on
consolidated value.
preferred_equity: Subtracted -- senior to common equity.
associate_investments: Added -- equity-method investments EV does not
capture (their earnings are typically excluded from EBIT/EBITDA).
equity_value: ``enterprise_value - total_debt + cash_and_equivalents -
minority_interest - preferred_equity + associate_investments``.
diluted_shares: Fully diluted share count.
value_per_share: ``equity_value / diluted_shares``.
"""
enterprise_value: float
total_debt: float
cash_and_equivalents: float
minority_interest: float
preferred_equity: float
associate_investments: float
equity_value: float
diluted_shares: float
value_per_share: float
def __post_init__(self) -> None:
"""Re-check the bridge and per-share arithmetic.
Raises:
ValueError: If ``equity_value`` or ``value_per_share`` do not
match their formulas.
"""
expected_equity = (
self.enterprise_value
- self.total_debt
+ self.cash_and_equivalents
- self.minority_interest
- self.preferred_equity
+ self.associate_investments
)
if not math.isclose(
self.equity_value, expected_equity, rel_tol=_RECONCILIATION_TOLERANCE, abs_tol=1e-6
):
raise ValueError(
f"NetDebtBridgeResult.equity_value={self.equity_value!r} does not "
f"match the bridge total {expected_equity!r}"
)
expected_per_share = self.equity_value / self.diluted_shares
if not math.isclose(
self.value_per_share,
expected_per_share,
rel_tol=_RECONCILIATION_TOLERANCE,
abs_tol=1e-9,
):
raise ValueError(
f"NetDebtBridgeResult.value_per_share={self.value_per_share!r} "
f"does not match equity_value / diluted_shares = {expected_per_share!r}"
)
def equity_bridge(
*,
enterprise_value: float,
total_debt: float,
cash_and_equivalents: float,
minority_interest: float,
preferred_equity: float,
associate_investments: float,
diluted_shares: float,
) -> NetDebtBridgeResult:
"""Bridge enterprise value to equity value and value per share.
Args:
enterprise_value: EV entering the bridge.
total_debt: Non-negative magnitude of total debt; subtracted.
cash_and_equivalents: Non-negative magnitude of cash and equivalents;
added.
minority_interest: Non-negative magnitude of non-controlling
interests; subtracted.
preferred_equity: Non-negative magnitude of preferred equity;
subtracted.
associate_investments: Non-negative magnitude of equity-method
investments in associates/joint ventures; added.
diluted_shares: Fully diluted share count; must be strictly positive.
Returns:
A :class:`NetDebtBridgeResult`.
Raises:
ValuationError: If ``enterprise_value`` is not a finite number, if any
of the five balance-sheet items is negative or not finite, or if
``diluted_shares`` is not a finite positive number.
"""
debt = _require_nonnegative(total_debt, "total_debt", "equity_bridge")
cash = _require_nonnegative(cash_and_equivalents, "cash_and_equivalents", "equity_bridge")
minority = _require_nonnegative(minority_interest, "minority_interest", "equity_bridge")
preferred = _require_nonnegative(preferred_equity, "preferred_equity", "equity_bridge")
associates = _require_nonnegative(
associate_investments, "associate_investments", "equity_bridge"
)
shares = require_positive(diluted_shares, "diluted_shares", "equity_bridge")
enterprise_value = _require_finite(enterprise_value, "enterprise_value", "equity_bridge")
equity_value = enterprise_value - debt + cash - minority - preferred + associates
value_per_share = equity_value / shares
return NetDebtBridgeResult(
enterprise_value=enterprise_value,
total_debt=debt,
cash_and_equivalents=cash,
minority_interest=minority,
preferred_equity=preferred,
associate_investments=associates,
equity_value=equity_value,
diluted_shares=shares,
value_per_share=value_per_share,
)
# ---------------------------------------------------------------------------
# Sensitivity grid
# ---------------------------------------------------------------------------
def sensitivity_grid(
fcff_years: Sequence[FCFFYear],
*,
wacc_values: Sequence[float],
growth_values: Sequence[float],
discounting_convention: str,
total_debt: float,
cash_and_equivalents: float,
minority_interest: float,
preferred_equity: float,
associate_investments: float,
diluted_shares: float,
) -> pd.DataFrame:
"""Value-per-share sensitivity to WACC and perpetuity terminal growth.
Every cell re-runs the full model (discount the explicit FCFFs at that
WACC, build the perpetuity-growth terminal value at that WACC and growth,
discount it at the same timing as the final explicit year, then bridge
through the same fixed balance-sheet items) rather than perturbing the
published enterprise value, so the grid is internally consistent at every
point. Only the perpetuity-growth method is swept -- the exit-multiple
method has no growth axis.
Args:
fcff_years: The FCFF bridge, e.g. from :func:`fcff_bridge`. WACC- and
growth-independent, so it is reused unchanged at every cell.
wacc_values: WACC values forming the grid's rows, each strictly
greater than -1.
growth_values: Perpetuity growth values forming the grid's columns.
discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.
total_debt: Non-negative magnitude; subtracted at every cell.
cash_and_equivalents: Non-negative magnitude; added at every cell.
minority_interest: Non-negative magnitude; subtracted at every cell.
preferred_equity: Non-negative magnitude; subtracted at every cell.
associate_investments: Non-negative magnitude; added at every cell.
diluted_shares: Fully diluted share count; must be strictly positive.
Returns:
A ``pandas.DataFrame`` indexed by ``wacc_values`` (index name
``"wacc"``) with columns ``growth_values`` (columns name
``"terminal_growth"``). Cells where ``growth >= wacc`` are ``NaN``
rather than a large number, because the perpetuity terminal value is
undefined there, not merely large -- see the module docstring.
Raises:
ValuationError: If ``fcff_years``, ``wacc_values`` or
``growth_values`` is empty, if ``discounting_convention`` is
unrecognised, if any ``wacc_values`` or ``growth_values`` entry is
not a finite number, if any ``wacc_values`` entry is at or below
-1, or if any balance-sheet item is negative or ``diluted_shares``
is not positive.
"""
if discounting_convention not in DISCOUNTING_CONVENTIONS:
raise ValuationError(
f"sensitivity_grid: discounting_convention must be one of "
f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"
)
if not fcff_years:
raise ValuationError("sensitivity_grid: fcff_years is empty")
wacc_list = list(wacc_values)
growth_list = list(growth_values)
if not wacc_list:
raise ValuationError("sensitivity_grid: wacc_values is empty")
if not growth_list:
raise ValuationError("sensitivity_grid: growth_values is empty")
wacc_list = [
_require_finite(v, f"wacc_values[{i}]", "sensitivity_grid")
for i, v in enumerate(wacc_list)
]
growth_list = [
_require_finite(v, f"growth_values[{i}]", "sensitivity_grid")
for i, v in enumerate(growth_list)
]
debt = _require_nonnegative(total_debt, "total_debt", "sensitivity_grid")
cash = _require_nonnegative(cash_and_equivalents, "cash_and_equivalents", "sensitivity_grid")
minority = _require_nonnegative(minority_interest, "minority_interest", "sensitivity_grid")
preferred = _require_nonnegative(preferred_equity, "preferred_equity", "sensitivity_grid")
associates = _require_nonnegative(
associate_investments, "associate_investments", "sensitivity_grid"
)
shares = require_positive(diluted_shares, "diluted_shares", "sensitivity_grid")
final_fcff = fcff_years[-1].fcff
grid = np.full((len(wacc_list), len(growth_list)), np.nan, dtype=float)
for row, wacc_value in enumerate(wacc_list):
if wacc_value <= -1.0:
raise ValuationError(
f"sensitivity_grid: wacc_values must exceed -1, got {wacc_value!r}"
)
discounted = discount_fcff(
fcff_years, wacc_rate=wacc_value, discounting_convention=discounting_convention
)
pv_explicit = sum(entry.present_value for entry in discounted)
terminal_factor = discounted[-1].discount_factor
for col, growth_value in enumerate(growth_list):
if growth_value >= wacc_value:
continue # left as NaN: the perpetuity terminal value is undefined here
tv = final_fcff * (1.0 + growth_value) / (wacc_value - growth_value)
enterprise_value = pv_explicit + tv * terminal_factor
equity_value = (
enterprise_value - debt + cash - minority - preferred + associates
)
grid[row, col] = equity_value / shares
return pd.DataFrame(
grid,
index=pd.Index(wacc_list, name="wacc"),
columns=pd.Index(growth_list, name="terminal_growth"),
)
# ---------------------------------------------------------------------------
# Top-level orchestration
# ---------------------------------------------------------------------------
@dataclass(frozen=True)
class DCFResult:
"""The full DCF: every bridge, both terminal values, and the final price.
Attributes:
wacc_build: The WACC build, with every component visible.
fcff_bridge: One :class:`FCFFYear` per projection year.
discounted_fcff: One :class:`DiscountedCashFlow` per projection year.
pv_of_explicit_fcff: Sum of ``discounted_fcff[*].present_value``.
terminal_value: Both terminal-value estimates and their cross-checks.
terminal_value_method: Which of :data:`TERMINAL_VALUE_METHODS` was
discounted into ``enterprise_value``. The other method's estimate
is still fully computed and visible on ``terminal_value``.
discounting_convention: Which of :data:`DISCOUNTING_CONVENTIONS` was used.
terminal_discount_factor: Discount factor applied to the chosen
terminal value -- the same factor used for the final explicit
year, per the module docstring.
pv_of_terminal_value: The chosen terminal value, discounted.
enterprise_value: ``pv_of_explicit_fcff + pv_of_terminal_value``.
net_debt_bridge: The full enterprise-value-to-equity-value bridge.
equity_value: ``net_debt_bridge.equity_value``.
value_per_share: ``net_debt_bridge.value_per_share``.
"""
wacc_build: WACCResult
fcff_bridge: tuple[FCFFYear, ...]
discounted_fcff: tuple[DiscountedCashFlow, ...]
pv_of_explicit_fcff: float
terminal_value: TerminalValueResult
terminal_value_method: str
discounting_convention: str
terminal_discount_factor: float
pv_of_terminal_value: float
enterprise_value: float
net_debt_bridge: NetDebtBridgeResult
equity_value: float
value_per_share: float
def __post_init__(self) -> None:
"""Re-check that the top-level rollups match their components.
Raises:
ValueError: If ``enterprise_value``, ``equity_value`` or
``value_per_share`` do not match the components they are
built from.
"""
expected_pv_explicit = sum(entry.present_value for entry in self.discounted_fcff)
if not math.isclose(
self.pv_of_explicit_fcff, expected_pv_explicit, rel_tol=1e-9, abs_tol=1e-6
):
raise ValueError(
f"DCFResult.pv_of_explicit_fcff={self.pv_of_explicit_fcff!r} does "
f"not match sum(discounted_fcff.present_value)={expected_pv_explicit!r}"
)
expected_ev = self.pv_of_explicit_fcff + self.pv_of_terminal_value
if not math.isclose(self.enterprise_value, expected_ev, rel_tol=1e-9, abs_tol=1e-6):
raise ValueError(
f"DCFResult.enterprise_value={self.enterprise_value!r} does not "
f"match pv_of_explicit_fcff + pv_of_terminal_value = {expected_ev!r}"
)
if not math.isclose(
self.enterprise_value, self.net_debt_bridge.enterprise_value, rel_tol=1e-9, abs_tol=1e-6
):
raise ValueError(
f"DCFResult.enterprise_value={self.enterprise_value!r} does not "
f"match net_debt_bridge.enterprise_value="
f"{self.net_debt_bridge.enterprise_value!r}"
)
if self.equity_value != self.net_debt_bridge.equity_value:
raise ValueError(
f"DCFResult.equity_value={self.equity_value!r} does not match "
f"net_debt_bridge.equity_value={self.net_debt_bridge.equity_value!r}"
)
if self.value_per_share != self.net_debt_bridge.value_per_share:
raise ValueError(
f"DCFResult.value_per_share={self.value_per_share!r} does not "
f"match net_debt_bridge.value_per_share="
f"{self.net_debt_bridge.value_per_share!r}"
)
def run_dcf(
inputs: Mapping[str, Any],
*,
capital_structure_basis: str,
discounting_convention: str,
terminal_value_method: str,
gdp_growth_ceiling: float = DEFAULT_LONG_RUN_GDP_GROWTH_CEILING,
) -> DCFResult:
"""Run a complete DCF from a flat mapping of named inputs.
This is the entry point :mod:`contracts` was written for: every required
field is named, checked for presence up front, and the model refuses to
run rather than substitute anything for one that is missing.
Args:
inputs: Flat mapping of raw inputs. Required keys are
:data:`DCF_BASE_REQUIRED_FIELDS` plus
:data:`DCF_CURRENT_STRUCTURE_FIELDS` (if
``capital_structure_basis="current"``) or
:data:`DCF_TARGET_STRUCTURE_FIELDS` (if ``"target"``).
``inputs["terminal_growth"]`` and ``inputs["exit_multiple"]`` must
each be an :class:`Assumption` (named ``"terminal_growth"`` /
``"exit_multiple"`` respectively), not a bare number. Optional
keys ``"size_premium"`` and ``"country_risk_premium"`` default to
``0.0`` when absent (an explicit "not applying one", not a guessed
magnitude). ``"ebit"``, ``"depreciation_amortization"``,
``"capex"`` and ``"delta_nwc"`` are equal-length sequences, one
entry per projection year.
capital_structure_basis: One of :data:`CAPITAL_STRUCTURE_BASES`.
Required, no default.
discounting_convention: One of :data:`DISCOUNTING_CONVENTIONS`.
Required, no default.
terminal_value_method: One of :data:`TERMINAL_VALUE_METHODS`, selecting
which terminal-value estimate is discounted into
``enterprise_value``. Required, no default. Both estimates are
always computed and cross-checked regardless of which is chosen --
see ``DCFResult.terminal_value``.
gdp_growth_ceiling: Reference ceiling used only to flag (never block)
``terminal_growth`` -- see :data:`DEFAULT_LONG_RUN_GDP_GROWTH_CEILING`.
Returns:
A :class:`DCFResult` with every intermediate figure visible.
Raises:
MissingInputError: If any required key is absent from ``inputs``.
ValuationError: If ``capital_structure_basis``,
``discounting_convention`` or ``terminal_value_method`` is
unrecognised; if ``terminal_growth`` or ``exit_multiple`` is not
the matching :class:`Assumption`; if ``terminal_growth.value >=``
the built WACC; if any capital-structure, FCFF-bridge or
balance-sheet input fails its own guard (see :func:`wacc`,
:func:`fcff_bridge`, :func:`terminal_value`, :func:`equity_bridge`).
"""
if capital_structure_basis not in CAPITAL_STRUCTURE_BASES:
raise ValuationError(
f"run_dcf: capital_structure_basis must be one of "
f"{CAPITAL_STRUCTURE_BASES}, got {capital_structure_basis!r}"
)
if discounting_convention not in DISCOUNTING_CONVENTIONS:
raise ValuationError(
f"run_dcf: discounting_convention must be one of "
f"{DISCOUNTING_CONVENTIONS}, got {discounting_convention!r}"
)
if terminal_value_method not in TERMINAL_VALUE_METHODS:
raise ValuationError(
f"run_dcf: terminal_value_method must be one of "
f"{TERMINAL_VALUE_METHODS}, got {terminal_value_method!r}"
)
structure_fields = (
DCF_CURRENT_STRUCTURE_FIELDS
if capital_structure_basis == "current"
else DCF_TARGET_STRUCTURE_FIELDS
)
require_inputs(inputs, (*DCF_BASE_REQUIRED_FIELDS, *structure_fields), model="run_dcf")
terminal_growth = _require_assumption(inputs["terminal_growth"], "terminal_growth", "run_dcf")
exit_multiple = _require_assumption(inputs["exit_multiple"], "exit_multiple", "run_dcf")
wacc_build = wacc(
risk_free_rate=inputs["risk_free_rate"],
beta=inputs["beta"],
equity_risk_premium=inputs["equity_risk_premium"],
pretax_cost_of_debt=inputs["pretax_cost_of_debt"],
tax_rate=inputs["tax_rate"],
capital_structure_basis=capital_structure_basis,
market_value_of_equity=inputs.get("market_value_of_equity"),
market_value_of_debt=inputs.get("market_value_of_debt"),
target_equity_weight=inputs.get("target_equity_weight"),
target_debt_weight=inputs.get("target_debt_weight"),
size_premium=inputs.get("size_premium", 0.0),
country_risk_premium=inputs.get("country_risk_premium", 0.0),
)
bridge = fcff_bridge(
ebit=inputs["ebit"],
tax_rate=inputs["tax_rate"],
depreciation_amortization=inputs["depreciation_amortization"],
capex=inputs["capex"],
delta_nwc=inputs["delta_nwc"],
)
final_year = bridge[-1]
terminal_year_ebitda = final_year.ebit + final_year.depreciation_amortization
tv = terminal_value(
final_year_fcff=final_year.fcff,
terminal_year_ebitda=terminal_year_ebitda,
wacc_rate=wacc_build.wacc,
terminal_growth=terminal_growth,
exit_multiple=exit_multiple,
gdp_growth_ceiling=gdp_growth_ceiling,
)
discounted = discount_fcff(
bridge, wacc_rate=wacc_build.wacc, discounting_convention=discounting_convention
)
pv_explicit = sum(entry.present_value for entry in discounted)
chosen_tv = (
tv.perpetuity_terminal_value
if terminal_value_method == "perpetuity_growth"
else tv.exit_terminal_value
)
# Discounted at the same timing as the final explicit year -- see the
# module docstring for why this makes the mid-year/year-end enterprise
# value ratio exactly sqrt(1 + WACC).
terminal_discount_factor = discounted[-1].discount_factor
pv_of_terminal_value = chosen_tv * terminal_discount_factor
enterprise_value = pv_explicit + pv_of_terminal_value
net_debt = equity_bridge(
enterprise_value=enterprise_value,
total_debt=inputs["total_debt"],
cash_and_equivalents=inputs["cash_and_equivalents"],
minority_interest=inputs["minority_interest"],
preferred_equity=inputs["preferred_equity"],
associate_investments=inputs["associate_investments"],
diluted_shares=inputs["diluted_shares"],
)
return DCFResult(
wacc_build=wacc_build,
fcff_bridge=bridge,
discounted_fcff=discounted,
pv_of_explicit_fcff=pv_explicit,
terminal_value=tv,
terminal_value_method=terminal_value_method,
discounting_convention=discounting_convention,
terminal_discount_factor=terminal_discount_factor,
pv_of_terminal_value=pv_of_terminal_value,
enterprise_value=enterprise_value,
net_debt_bridge=net_debt,
equity_value=net_debt.equity_value,
value_per_share=net_debt.value_per_share,
)