pystra.decision.criteria.LQI#

Use it: User guide · Worked example · Theory

class LQI(swtp=None, consequence=None, target=None)[source]#

Bases: DDOCriterion

Minimum acceptable life-safety criterion using LQI/SWTP.

The criterion adds consequence valuation and LQI acceptability columns to the reliability and objective results produced by DDO. It does not select the economic optimum by itself.

Methods

`acceptability_boundary`	Return the design where the LQI acceptability margin changes sign.
`acceptability_margin`	Return the JCSS marginal LQI acceptability margin.
`acceptability_margin_at`	Return the finite-difference LQI acceptability margin at a design.
`derive_target`	Calculate an LQI target from the marginal optimization condition.
`evaluate`	Return decision results with LQI/SWTP columns.
`feasible`	Return a boolean feasibility mask for evaluated results.
`from_country`	Create an LQI criterion from a built-in country SWTP value.
`from_lqi`	Create an LQI criterion from the LQI SWTP relation.
`from_swtp`	Create an LQI criterion from an SWTP value.
`lookup_target`	Return the rounded source-table LQI target for `k1`.
`risk_cost`	Return the JCSS LQI life-safety risk-cost term.
`risk_cost_from_result`	Return LQI risk cost from an aggregated risk result.

static lookup_target(k1, variability='medium')[source]#

Return the rounded source-table LQI target for k1.

Return type:: TargetReliability

static derive_target(k1, resistance_cov=0.4, load_cov=0.4, bounds=(1.0, 20.0))[source]#

Calculate an LQI target from the marginal optimization condition.

Return type:: TargetReliability

classmethod from_swtp(swtp, *, expected_fatalities_given_failure=None, consequence=None, marginal_safety_cost, variability='medium')[source]#

Create an LQI criterion from an SWTP value.

Parameters:

swtp (float | SWTP) – Societal willingness to pay per statistical life.
expected_fatalities_given_failure (float | None) – Expected fatalities conditional on failure.
consequence (FatalityConsequence | None) – Consequence model. Use this instead of expected_fatalities_given_failure when exposure and fatality probability should remain explicit.
marginal_safety_cost (float) – Marginal annual safety cost used in the LQI target-reliability table.
variability (str) – Variability class for the LQI target-reliability table.

Return type:

LQI

classmethod from_country(code, *, expected_fatalities_given_failure=None, consequence=None, marginal_safety_cost, indexed=None, variability='medium')[source]#

Create an LQI criterion from a built-in country SWTP value.

Return type:: LQI

classmethod from_lqi(*, gross_domestic_product_per_capita, work_leisure_parameter, demographic_constant, expected_fatalities_given_failure=None, consequence=None, marginal_safety_cost, variability='medium', currency='currency units', price_year=None, source='LQI relation SWTP = g / q * G')[source]#

Create an LQI criterion from the LQI SWTP relation.

work_leisure_parameter is the dimensionless LQI parameter q (~0.1–0.2), not an annual mortality rate.

Return type:: LQI

property expected_fatalities_given_failure: float | None#: Return expected fatalities conditional on failure when available.

property k1: float | None#: Return the LQI safety cost ratio when a target is available.

risk_cost(safety_cost, failure_rate)[source]#

Return the JCSS LQI life-safety risk-cost term.

Return type:: float | ndarray

risk_cost_from_result(safety_cost, risk, include_economic_loss=False)[source]#

Return LQI risk cost from an aggregated risk result.

Return type:: float

acceptability_margin(safety_cost_derivative, failure_rate_derivative)[source]#

Return the JCSS marginal LQI acceptability margin.

Return type:: float

acceptability_margin_at(safety_cost, failure_rate, design, step=None)[source]#

Return the finite-difference LQI acceptability margin at a design.

This is acceptability_margin() evaluated from cost and failure-rate callables, differentiating each by central finite differences.

Return type:: float

acceptability_boundary(safety_cost, failure_rate, bounds, step=None)[source]#

Return the design where the LQI acceptability margin changes sign.

The marginal acceptability margin dC/dp + SWTP * N_F * dh/dp is negative where society would still pay to reduce risk and non-negative once the marginal cost of safety meets or exceeds the SWTP-valued risk reduction. The boundary is the design at which the margin is zero: the minimum design the LQI criterion accepts (the marginal acceptability boundary), which is a minimum safety requirement, not the economic optimum. Root finding uses Brent’s method over bounds and requires the margin to change sign across the interval.

Parameters:

safety_cost (Callable[[float], float]) – Safety or construction cost as a function of the design value.
failure_rate (Callable[[float], float]) – Annual failure probability or rate as a function of the design.
bounds (tuple[float, float]) – Increasing (lower, upper) search interval bracketing the boundary.
step (float | None) – Finite-difference step for the marginal derivatives.

Returns:

Design value at which the marginal LQI margin is zero.

Return type:

float

evaluate(results)[source]#

Return decision results with LQI/SWTP columns.

Return type:: DataFrame

feasible(results)#

Return a boolean feasibility mask for evaluated results.

Return type:: Series