supplycm 1.2.1__py3-none-any.whl

supplycm/__init__.py

@@ -0,0 +1,34 @@
+"""supplycm - Supply Chain Management algorithms (pure Python).
+
+A collection of 360 patent-free / public-domain algorithms for
+forecasting, inventory, transportation, network optimization,
+scheduling, MRP, statistics, optimization, supplier management,
+warehouse operations, demand planning and risk assessment.
+
+Version 1.2.1 - First stable release with full test coverage.
+"""
+
+__version__ = "1.2.1"
+
+from . import forecasting
+from . import inventory
+from . import statistics
+from . import routing
+from . import network
+from . import scheduling
+from . import mrp
+from . import optimization
+from . import supplier
+from . import warehouse
+from . import demand
+from . import risk
+from . import quality
+from . import lean
+from . import sop
+from . import sustainability
+from . import contracts
+from . import simulation
+from . import cost
+from . import network_design
+from . import iot
+from . import blockchain

supplycm/blockchain/__init__.py

@@ -0,0 +1,6 @@
+"""supplycm.blockchain - Blockchain traceability algorithms."""
+
+from .hash_chain import hash_chain
+from .verify_chain import verify_chain
+from .provenance_tracking import provenance_tracking
+from .smart_contract_check import smart_contract_check

supplycm/blockchain/hash_chain.py

@@ -0,0 +1,35 @@
+"""Simple hash chain for supply chain traceability."""
+import hashlib
+from typing import List, Dict
+
+
+def hash_chain(records: List[Dict]) -> List[str]:
+    """Create a hash chain linking supply chain events.
+
+    Each record hash includes the previous hash, creating an
+    immutable chain. Tampering with any record breaks the chain.
+
+    Args:
+        records: List of event dicts (e.g., timestamp, location, product).
+
+    Returns:
+        List of hash strings, one per record.
+
+    Example:
+        >>> hashes = hash_chain([
+        ...     {'event': 'manufactured', 'product': 'A'},
+        ...     {'event': 'shipped', 'product': 'A'},
+        ...     {'event': 'delivered', 'product': 'A'},
+        ... ])
+        >>> len(hashes) == 3
+        True
+    """
+    hashes = []
+    prev_hash = '0' * 64  # Genesis block
+    for record in records:
+        # Sort keys for deterministic hashing
+        record_str = str(sorted(record.items())) + prev_hash
+        current_hash = hashlib.sha256(record_str.encode()).hexdigest()
+        hashes.append(current_hash)
+        prev_hash = current_hash
+    return hashes

supplycm/blockchain/provenance_tracking.py

@@ -0,0 +1,27 @@
+"""Track product provenance through the supply chain."""
+from typing import List, Dict
+
+
+def provenance_tracking(events: List[Dict], product_id: str) -> List[Dict]:
+    """Extract the full history of a product from supply chain events.
+
+    Args:
+        events: List of all supply chain events.
+        product_id: Product to track.
+
+    Returns:
+        Chronological list of events for the product.
+
+    Example:
+        >>> events = [
+        ...     {'product': 'A', 'event': 'manufactured', 'time': 1},
+        ...     {'product': 'B', 'event': 'manufactured', 'time': 2},
+        ...     {'product': 'A', 'event': 'shipped', 'time': 3},
+        ... ]
+        >>> history = provenance_tracking(events, 'A')
+        >>> len(history) == 2
+        True
+    """
+    history = [e for e in events if e.get('product') == product_id]
+    history.sort(key=lambda e: e.get('time', 0))
+    return history

supplycm/blockchain/smart_contract_check.py

@@ -0,0 +1,42 @@
+"""Simple smart contract validation for supply chain rules."""
+from typing import Dict, List
+
+
+def smart_contract_check(transaction: Dict, rules: List[Dict]) -> Dict:
+    """Validate a transaction against supply chain rules.
+
+    Args:
+        transaction: Dict with transaction details.
+        rules: List of rule dicts with 'field', 'operator', 'value'.
+
+    Returns:
+        Dict with 'valid' (bool) and 'violations' (list).
+
+    Example:
+        >>> result = smart_contract_check(
+        ...     {'temperature': 5, 'humidity': 60},
+        ...     [{'field': 'temperature', 'operator': '<=', 'value': 8},
+        ...      {'field': 'humidity', 'operator': '>=', 'value': 40}])
+        >>> result['valid']
+        True
+    """
+    violations = []
+    for rule in rules:
+        field = rule['field']
+        op = rule['operator']
+        value = rule['value']
+        actual = transaction.get(field)
+        if actual is None:
+            violations.append(f'Missing field: {field}')
+            continue
+        if op == '<=' and not (actual <= value):
+            violations.append(f'{field}={actual} exceeds {value}')
+        elif op == '>=' and not (actual >= value):
+            violations.append(f'{field}={actual} below {value}')
+        elif op == '==' and not (actual == value):
+            violations.append(f'{field}={actual} not equal to {value}')
+        elif op == '<' and not (actual < value):
+            violations.append(f'{field}={actual} not less than {value}')
+        elif op == '>' and not (actual > value):
+            violations.append(f'{field}={actual} not greater than {value}')
+    return {'valid': len(violations) == 0, 'violations': violations}

supplycm/blockchain/verify_chain.py

@@ -0,0 +1,32 @@
+"""Verify integrity of a hash chain."""
+import hashlib
+from typing import List, Dict
+
+
+def verify_chain(records: List[Dict], hashes: List[str]) -> bool:
+    """Verify that a hash chain is valid (not tampered with).
+
+    Args:
+        records: Original event records.
+        hashes: Hash chain to verify.
+
+    Returns:
+        True if chain is valid, False otherwise.
+
+    Example:
+        >>> from supplycm.blockchain.hash_chain import hash_chain
+        >>> records = [{'event': 'created'}, {'event': 'shipped'}]
+        >>> hashes = hash_chain(records)
+        >>> verify_chain(records, hashes)
+        True
+    """
+    if len(records) != len(hashes):
+        return False
+    prev_hash = '0' * 64
+    for record, expected_hash in zip(records, hashes):
+        record_str = str(sorted(record.items())) + prev_hash
+        actual_hash = hashlib.sha256(record_str.encode()).hexdigest()
+        if actual_hash != expected_hash:
+            return False
+        prev_hash = expected_hash
+    return True

supplycm/contracts/__init__.py

@@ -0,0 +1,5 @@
+"""supplycm.contracts - Supply chain contract algorithms."""
+
+from .revenue_sharing_contract import revenue_sharing_contract
+from .buyback_contract import buyback_contract
+from .quantity_flexibility_contract import quantity_flexibility_contract

supplycm/contracts/buyback_contract.py

@@ -0,0 +1,28 @@
+"""Buyback contract analysis."""
+
+
+def buyback_contract(wholesale_price: float, retail_price: float,
+                      buyback_price: float, demand: float,
+                      unit_cost: float, salvage_value: float = 0) -> dict:
+    """Analyze buyback contract.
+
+    Example:
+        >>> result = buyback_contract(50, 100, 30, 800, 20, 10)
+        >>> isinstance(result['supplier_profit'], float)
+        True
+    """
+    if buyback_price > wholesale_price:
+        raise ValueError("buyback should not exceed wholesale")
+    order_qty = demand
+    unsold = max(0, order_qty - demand)
+    supplier_revenue = wholesale_price * order_qty - buyback_price * unsold + salvage_value * unsold
+    supplier_cost = unit_cost * order_qty
+    supplier_profit = supplier_revenue - supplier_cost
+    retailer_revenue = retail_price * demand + buyback_price * unsold
+    retailer_cost = wholesale_price * order_qty
+    retailer_profit = retailer_revenue - retailer_cost
+    return {
+        "supplier_profit": supplier_profit,
+        "retailer_profit": retailer_profit,
+        "total_profit": supplier_profit + retailer_profit,
+    }

supplycm/contracts/quantity_flexibility_contract.py

@@ -0,0 +1,28 @@
+"""Quantity flexibility contract analysis."""
+
+
+def quantity_flexibility_contract(wholesale_price: float, retail_price: float,
+                                   order_quantity: float, actual_demand: float,
+                                   unit_cost: float, flexibility_fraction: float = 0.2) -> dict:
+    """Analyze quantity flexibility contract.
+
+    Example:
+        >>> result = quantity_flexibility_contract(50, 100, 1000, 900, 20, 0.2)
+        >>> result['final_quantity'] <= 1000
+        True
+    """
+    if flexibility_fraction < 0 or flexibility_fraction > 1:
+        raise ValueError("flexibility must be in [0, 1]")
+    min_qty = order_quantity * (1 - flexibility_fraction)
+    max_qty = order_quantity * (1 + flexibility_fraction)
+    final_qty = max(min_qty, min(max_qty, actual_demand))
+    sales = min(final_qty, actual_demand)
+    unsold = final_qty - sales
+    supplier_profit = wholesale_price * final_qty - unit_cost * final_qty
+    retailer_profit = retail_price * sales + 0 * unsold - wholesale_price * final_qty
+    return {
+        "final_quantity": final_qty,
+        "supplier_profit": supplier_profit,
+        "retailer_profit": retailer_profit,
+        "total_profit": supplier_profit + retailer_profit,
+    }

supplycm/contracts/revenue_sharing_contract.py

@@ -0,0 +1,26 @@
+"""Revenue sharing contract analysis."""
+
+
+def revenue_sharing_contract(wholesale_price: float, retail_price: float,
+                              revenue_share_fraction: float,
+                              demand: float, unit_cost: float) -> dict:
+    """Analyze revenue sharing contract.
+
+    Example:
+        >>> result = revenue_sharing_contract(40, 100, 0.2, 1000, 20)
+        >>> result['supplier_profit'] > 0
+        True
+    """
+    if revenue_share_fraction < 0 or revenue_share_fraction > 1:
+        raise ValueError("share must be in [0, 1]")
+    supplier_revenue = wholesale_price * demand + revenue_share_fraction * retail_price * demand
+    supplier_cost = unit_cost * demand
+    supplier_profit = supplier_revenue - supplier_cost
+    retailer_revenue = (1 - revenue_share_fraction) * retail_price * demand
+    retailer_cost = wholesale_price * demand
+    retailer_profit = retailer_revenue - retailer_cost
+    return {
+        "supplier_profit": supplier_profit,
+        "retailer_profit": retailer_profit,
+        "total_profit": supplier_profit + retailer_profit,
+    }

supplycm/cost/__init__.py

@@ -0,0 +1,4 @@
+"""supplycm.cost - Cost analysis algorithms."""
+
+from .landed_cost import landed_cost
+from .total_cost_procurement import total_cost_procurement

supplycm/cost/landed_cost.py

@@ -0,0 +1,19 @@
+"""Landed cost calculation."""
+
+
+def landed_cost(unit_price: float, freight: float, duty_rate: float = 0,
+                insurance_rate: float = 0, handling: float = 0,
+                customs_broker: float = 0, quantity: float = 1) -> float:
+    """Total cost per unit including all logistics expenses.
+
+    Example:
+        >>> round(landed_cost(100, 500, 0.05, 0.01, 100, 50, 10), 2)
+        165.5
+    """
+    if quantity <= 0:
+        raise ValueError("quantity must be positive")
+    subtotal = unit_price * quantity
+    duty = subtotal * duty_rate
+    insurance = subtotal * insurance_rate
+    total = subtotal + freight + duty + insurance + handling + customs_broker
+    return total / quantity

supplycm/cost/total_cost_procurement.py

@@ -0,0 +1,14 @@
+"""Total Cost of Procurement (TCP)."""
+
+
+def total_cost_procurement(purchase_cost: float, ordering_cost: float,
+                            holding_cost: float, stockout_cost: float = 0,
+                            quality_cost: float = 0, admin_cost: float = 0) -> float:
+    """Sum of all procurement-related costs.
+
+    Example:
+        >>> total_cost_procurement(100000, 5000, 8000, 2000, 1000, 3000)
+        119000
+    """
+    return (purchase_cost + ordering_cost + holding_cost +
+            stockout_cost + quality_cost + admin_cost)

supplycm/demand/__init__.py

@@ -0,0 +1,10 @@
+"""supplycm.demand - Demand algorithms."""
+from .demand_aggregation import demand_aggregation
+from .demand_disaggregation import demand_disaggregation
+from .demand_class_abc_xyz import demand_class_abc_xyz
+from .promotional_demand_lift import promotional_demand_lift
+from .cannibalization_effect import cannibalization_effect
+from .stockout_demand_loss import stockout_demand_loss
+from .demand_sensing import demand_sensing
+from .seasonality_index import seasonality_index
+from .trend_seasonal_decomposition_forecast import trend_seasonal_decomposition_forecast

supplycm/demand/cannibalization_effect.py

@@ -0,0 +1,16 @@
+"""Compute cannibalization effect of new product on existing."""
+from typing import List, Tuple
+
+
+def cannibalization_effect(existing_before: float, existing_after: float,
+                           new_product_sales: float) -> float:
+    """Fraction of new product sales that came from existing product.
+
+    Example:
+        >>> round(cannibalization_effect(100, 80, 50), 4)
+        0.4
+    """
+    lost_sales = existing_before - existing_after
+    if new_product_sales <= 0:
+        return 0.0
+    return lost_sales / new_product_sales

supplycm/demand/demand_aggregation.py

@@ -0,0 +1,17 @@
+"""Aggregate demand by time bucket."""
+from typing import List
+
+
+def demand_aggregation(daily_demand: List[float], bucket_size: int) -> List[float]:
+    """Aggregate daily demand into larger buckets.
+
+    Example:
+        >>> demand_aggregation([10, 20, 30, 40, 50, 60], 3)
+        [60.0, 150.0]
+    """
+    if bucket_size <= 0:
+        raise ValueError("bucket_size must be positive")
+    result = []
+    for i in range(0, len(daily_demand), bucket_size):
+        result.append(sum(daily_demand[i:i + bucket_size]))
+    return result

supplycm/demand/demand_class_abc_xyz.py

@@ -0,0 +1,20 @@
+"""Combine ABC value with XYZ variability classification."""
+from typing import List, Tuple
+
+
+def demand_class_abc_xyz(abc: List[Tuple[str, str]],
+                          xyz: List[Tuple[str, str]]) -> List[Tuple[str, str]]:
+    """Combine into 9-class matrix (AX, AY, AZ, BX, ...).
+
+    Example:
+        >>> result = demand_class_abc_xyz([('a', 'A'), ('b', 'B')],
+        ...                               [('a', 'X'), ('b', 'Y')])
+        >>> result[0] == ('a', 'AX')
+        True
+    """
+    abc_dict = dict(abc)
+    xyz_dict = dict(xyz)
+    result = []
+    for item in sorted(set(abc_dict) | set(xyz_dict)):
+        result.append((item, abc_dict.get(item, 'C') + xyz_dict.get(item, 'Z')))
+    return result

supplycm/demand/demand_disaggregation.py

@@ -0,0 +1,17 @@
+"""Disaggregate forecast using historical proportions."""
+from typing import Dict, List
+
+
+def demand_disaggregation(aggregate_forecast: float,
+                           proportions: Dict[str, float]) -> Dict[str, float]:
+    """Split aggregate forecast by proportions.
+
+    Example:
+        >>> d = demand_disaggregation(1000, {'A': 0.5, 'B': 0.3, 'C': 0.2})
+        >>> d['A']
+        500.0
+    """
+    total = sum(proportions.values())
+    if total == 0:
+        return {k: 0 for k in proportions}
+    return {k: aggregate_forecast * (v / total) for k, v in proportions.items()}

supplycm/demand/demand_sensing.py

@@ -0,0 +1,21 @@
+"""Demand sensing using short-term signal adjustment."""
+from typing import List
+
+
+def demand_sensing(forecast: List[float], actual_recent: List[float],
+                    adjustment_window: int = 3) -> List[float]:
+    """Adjust forecast based on recent actuals.
+
+    Example:
+        >>> adj = demand_sensing([100, 100, 100], [110, 105], 2)
+        >>> adj[0] > 100
+        True
+    """
+    if not actual_recent:
+        return forecast
+    avg_recent = sum(actual_recent[-adjustment_window:]) / min(len(actual_recent), adjustment_window)
+    avg_forecast_recent = sum(forecast[:adjustment_window]) / min(len(forecast), adjustment_window)
+    if avg_forecast_recent == 0:
+        return forecast
+    adjustment = avg_recent / avg_forecast_recent
+    return [f * adjustment for f in forecast]

supplycm/demand/promotional_demand_lift.py

@@ -0,0 +1,14 @@
+"""Calculate promotional lift factor."""
+from typing import List, Tuple
+
+
+def promotional_demand_lift(baseline_demand: float, promotion_demand: float) -> float:
+    """Lift factor = promotion_demand / baseline.
+
+    Example:
+        >>> promotional_demand_lift(100, 150)
+        1.5
+    """
+    if baseline_demand <= 0:
+        raise ValueError("baseline demand must be positive")
+    return promotion_demand / baseline_demand

supplycm/demand/seasonality_index.py

@@ -0,0 +1,23 @@
+"""Compute seasonality index per period."""
+from typing import List
+
+
+def seasonality_index(demand_series: List[float], season_length: int) -> List[float]:
+    """Seasonality index = period_avg / overall_avg.
+
+    Example:
+        >>> idx = seasonality_index([10, 20, 30, 40, 50, 60, 70, 80], 4)
+        >>> len(idx) == 4
+        True
+    """
+    if season_length <= 0 or len(demand_series) < season_length:
+        raise ValueError("invalid season length or insufficient data")
+    overall_avg = sum(demand_series) / len(demand_series)
+    if overall_avg == 0:
+        return [1.0] * season_length
+    indices = []
+    for i in range(season_length):
+        period_values = demand_series[i::season_length]
+        avg = sum(period_values) / len(period_values)
+        indices.append(avg / overall_avg)
+    return indices

supplycm/demand/stockout_demand_loss.py

@@ -0,0 +1,15 @@
+"""Estimate demand permanently lost due to stockout."""
+from typing import List
+
+
+def stockout_demand_loss(stockout_qty: float, stockout_duration: float,
+                          substitution_rate: float = 0.5) -> float:
+    """Lost demand = stockout_qty * (1 - substitution_rate).
+
+    Example:
+        >>> stockout_demand_loss(100, 5, 0.5)
+        50.0
+    """
+    if substitution_rate < 0 or substitution_rate > 1:
+        raise ValueError("substitution rate must be in [0, 1]")
+    return stockout_qty * (1 - substitution_rate)

supplycm/demand/trend_seasonal_decomposition_forecast.py

@@ -0,0 +1,55 @@
+"""Forecast using decomposed trend and seasonality."""
+from typing import List
+
+
+def trend_seasonal_decomposition_forecast(data: List[float], season_length: int,
+                                          horizon: int) -> List[float]:
+    """Decompose and forecast.
+
+    Example:
+        >>> fcst = trend_seasonal_decomposition_forecast(
+        ...     [10, 20, 30, 40, 50, 60, 70, 80], 4, 2)
+        >>> len(fcst) == 2
+        True
+    """
+    n = len(data)
+    if n < 2 * season_length:
+        # Use simple linear regression
+        from .linear_regression_forecast import linear_regression_forecast
+        _, _, f = linear_regression_forecast(data, horizon)
+        return f
+    # Centered moving average
+    half = season_length // 2
+    trend = [None] * n
+    for t in range(half, n - half):
+        trend[t] = sum(data[t - half:t + half + 1]) / (2 * half + 1)
+    # Compute seasonal indices
+    detrended = [data[t] - trend[t] if trend[t] is not None else 0 for t in range(n)]
+    s_idx = [0.0] * season_length
+    counts = [0] * season_length
+    for t in range(n):
+        s_idx[t % season_length] += detrended[t]
+        counts[t % season_length] += 1
+    s_idx = [s_idx[i] / counts[i] if counts[i] else 0 for i in range(season_length)]
+    # Mean zero adjustment
+    mean_s = sum(s_idx) / season_length
+    s_idx = [s - mean_s for s in s_idx]
+    # Linear trend on the trend series (excluding None)
+    trend_points = [(t, trend[t]) for t in range(n) if trend[t] is not None]
+    if len(trend_points) < 2:
+        return [data[-1]] * horizon
+    xs = [p[0] for p in trend_points]
+    ys = [p[1] for p in trend_points]
+    mean_x = sum(xs) / len(xs)
+    mean_y = sum(ys) / len(ys)
+    num = sum((xs[i] - mean_x) * (ys[i] - mean_y) for i in range(len(xs)))
+    den = sum((x - mean_x) ** 2 for x in xs)
+    slope = num / den if den else 0
+    intercept = mean_y - slope * mean_x
+    forecasts = []
+    for h in range(horizon):
+        t = n + h
+        trend_val = intercept + slope * t
+        seasonal = s_idx[t % season_length]
+        forecasts.append(trend_val + seasonal)
+    return forecasts

supplycm/forecasting/__init__.py

@@ -0,0 +1,51 @@
+"""supplycm.forecasting - Forecasting algorithms."""
+from .simple_moving_average import simple_moving_average
+from .weighted_moving_average import weighted_moving_average
+from .single_exponential_smoothing import single_exponential_smoothing
+from .holt_linear_trend import holt_linear_trend
+from .holt_winters import holt_winters
+from .naive_forecast import naive_forecast
+from .seasonal_naive_forecast import seasonal_naive_forecast
+from .drift_method import drift_method
+from .average_method import average_method
+from .crostons_method import crostons_method
+from .sba_method import sba_method
+from .tsb_method import tsb_method
+from .linear_regression_forecast import linear_regression_forecast
+from .polynomial_regression_forecast import _solve_linear_system
+from .exponential_trend_forecast import exponential_trend_forecast
+from .classical_decomposition import classical_decomposition
+from .moving_median_filter import moving_median_filter
+from .akaike_information_criterion import akaike_information_criterion
+from .bayesian_information_criterion import bayesian_information_criterion
+from .autocorrelation import autocorrelation
+from .partial_autocorrelation import partial_autocorrelation
+from .ar_model import ar_model
+from .ma_model import ma_model
+from .theta_method import theta_method
+from .theils_u import theils_u
+from .tracking_signal import tracking_signal
+from .brier_score import brier_score
+from .browns_double_exponential import browns_double_exponential
+from .browns_triple_exponential import browns_triple_exponential
+from .pegels_classification import pegels_classification
+from .bottom_up_reconciliation import bottom_up_reconciliation
+from .top_down_reconciliation import top_down_reconciliation
+from .bates_granger_combination import bates_granger_combination
+from .dampened_trend import dampened_trend
+from .seasonal_trend_loess import seasonal_trend_loess
+from .box_cox_transform import box_cox_transform
+from .inverse_box_cox import inverse_box_cox
+from .kpss_test import kpss_test
+from .adf_test import adf_test
+from .ljung_box_test import ljung_box_test
+from .hurst_exponent import hurst_exponent
+from .seasonal_indices import seasonal_indices
+from .doubling_seasonal_smoothing import doubling_seasonal_smoothing
+from .gompertz_trend import gompertz_trend
+from .logistic_trend import logistic_trend
+from .mstl_decomposition import mstl_decomposition
+from .rolling_mean_forecast import rolling_mean_forecast
+from .ses_with_drift import ses_with_drift
+from .var_model import var_model
+from .croston_with_decay import croston_with_decay

supplycm/forecasting/adf_test.py

@@ -0,0 +1,32 @@
+"""Simplified Augmented Dickey-Fuller (ADF) test statistic."""
+from typing import List
+
+
+def adf_test(data: List[float]) -> float:
+    """Compute simplified ADF t-statistic for unit root testing.
+
+    Example:
+        >>> round(adf_test([1, 2, 3, 4, 5]), 4)
+        1.0
+    """
+    n = len(data)
+    if n < 4:
+        raise ValueError("need at least 4 observations")
+    # Regress delta(y_t) on y_{t-1} - mean
+    mean = sum(data) / n
+    dy = [data[t] - data[t - 1] for t in range(1, n)]
+    y_lag_centered = [data[t - 1] - mean for t in range(1, n)]
+    if all(y == 0 for y in y_lag_centered):
+        return 0.0
+    num = sum(y_lag_centered[i] * dy[i] for i in range(len(dy)))
+    den = sum(y * y for y in y_lag_centered)
+    if den == 0:
+        return 0.0
+    rho = num / den
+    residuals = [dy[i] - rho * y_lag_centered[i] for i in range(len(dy))]
+    rss = sum(r * r for r in residuals)
+    se = math.sqrt(rss / (n - 2)) / math.sqrt(den) if den > 0 and rss > 0 else 0.0
+    return rho / se if se > 0 else 0.0
+
+
+import math

supplycm/forecasting/akaike_information_criterion.py

@@ -0,0 +1,22 @@
+"""Akaike Information Criterion (AIC)."""
+from typing import List
+import math
+
+
+def akaike_information_criterion(residuals: List[float], k: int) -> float:
+    """Compute AIC given residuals and number of parameters k.
+
+    AIC = 2k - 2*ln(L); we use the Gaussian likelihood approximation
+    AIC = n * ln(RSS / n) + 2k.
+
+    Example:
+        >>> round(akaike_information_criterion([1.0, -1.0, 0.5, -0.5], 2), 4)
+        -3.4657
+    """
+    n = len(residuals)
+    if n == 0:
+        raise ValueError("residuals empty")
+    rss = sum(r * r for r in residuals)
+    if rss <= 0:
+        rss = 1e-12
+    return n * math.log(rss / n) + 2 * k