function results = effective_damping_example(beta_I, beta_V0, beta_HD, mu, varargin)
%EFFECTIVE_DAMPING_EXAMPLE  ASCE/SEI 7-22 Ch.18 effective damping -> demand reduction.
%
%   results = EFFECTIVE_DAMPING_EXAMPLE(beta_I, beta_V0, beta_HD, mu)
%   composes the three effective-damping contributions, applies the
%   sqrt(mu) ductility modulation to the viscous term, interpolates the
%   damping coefficient B from Table 18.7-1, and computes the resulting
%   reduction in design spectral demand. It also computes the separate B
%   for the minimum base-shear floor (Sec. 18.2.1.1), which credits
%   inherent + viscous damping ONLY (no hysteretic contribution).
%
%   Inputs (all scalars):
%     beta_I   - inherent damping of bare structure, % of critical
%                (Sec 18.2.2.1 typically 2-5%)
%     beta_V0  - viscous device damping at mu = 1, % of critical
%     beta_HD  - hysteretic damping (displacement-dependent devices
%                + SFRS post-yield), % of critical
%     mu       - ductility ratio (demand displacement / yield displacement)
%
%   Name/value options:
%     'Verbose' - true/false, print a formatted report (default true)
%     'Plot'    - true/false, plot Table 18.7-1 with operating points
%                 (default false)
%
%   Output struct 'results' fields:
%     beta_V, beta_total, B_total, reduction_pct,
%     beta_VplusI, B_VplusI, reduction_floor_pct
%
%   Called with no arguments, runs the slide demo case
%   (beta_I=3, beta_V0=9, beta_HD=12, mu=3).
%
%   Example:
%     r = effective_damping_example(3, 9, 12, 3, 'Plot', true);
%
%   NOTE: input values are illustrative. Actual beta contributions come
%   from force-deformation loops verified by NLRH and prototype testing.
%   Verify Table 18.7-1 values against your copy of ASCE/SEI 7-22.
%
%   Tom Irvine / Vibrationdata

    % ---- Demo defaults if called with no arguments ----------------------
    if nargin == 0
        beta_I  = 3.0;
        beta_V0 = 9.0;
        beta_HD = 12.0;
        mu      = 3.0;
    end

    % ---- Parse options --------------------------------------------------
    p = inputParser;
    p.addParameter('Verbose', true,  @(x) islogical(x) || isnumeric(x));
    p.addParameter('Plot',    false, @(x) islogical(x) || isnumeric(x));
    p.parse(varargin{:});
    verbose  = logical(p.Results.Verbose);
    doPlot   = logical(p.Results.Plot);

    % ---- Validate inputs ------------------------------------------------
    validateattributes(beta_I,  {'numeric'}, {'scalar','nonnegative'}, mfilename, 'beta_I');
    validateattributes(beta_V0, {'numeric'}, {'scalar','nonnegative'}, mfilename, 'beta_V0');
    validateattributes(beta_HD, {'numeric'}, {'scalar','nonnegative'}, mfilename, 'beta_HD');
    validateattributes(mu,      {'numeric'}, {'scalar','positive'},    mfilename, 'mu');

    % ---- Core calculation -----------------------------------------------
    beta_V     = beta_V0 / sqrt(mu);                 % Step 1: ductility modulation
    beta_total = beta_I + beta_V + beta_HD;          % Step 2: sum contributions
    B_total    = damping_coefficient_B(beta_total);  % Step 3: Table 18.7-1 lookup
    reduction_pct = (1 - 1/B_total) * 100;           % Step 4: demand reduction

    % Minimum base-shear floor (Sec 18.2.1.1): inherent + viscous only
    beta_VplusI         = beta_I + beta_V;
    B_VplusI            = damping_coefficient_B(beta_VplusI);
    reduction_floor_pct = (1 - 1/B_VplusI) * 100;

    % ---- Pack results ---------------------------------------------------
    results = struct( ...
        'beta_I',              beta_I, ...
        'beta_V0',             beta_V0, ...
        'beta_HD',             beta_HD, ...
        'mu',                  mu, ...
        'beta_V',              beta_V, ...
        'beta_total',          beta_total, ...
        'B_total',             B_total, ...
        'reduction_pct',       reduction_pct, ...
        'beta_VplusI',         beta_VplusI, ...
        'B_VplusI',            B_VplusI, ...
        'reduction_floor_pct', reduction_floor_pct);

    % ---- Report ---------------------------------------------------------
    if verbose
        fprintf('=================================================================\n');
        fprintf(' ASCE 7-22 Ch.18  Effective Damping -> Demand Reduction\n');
        fprintf('=================================================================\n');
        fprintf(' Given:\n');
        fprintf('   beta_I   (inherent)              = %5.1f %%\n', beta_I);
        fprintf('   beta_V0  (viscous, at mu=1)      = %5.1f %%\n', beta_V0);
        fprintf('   beta_HD  (hysteretic)            = %5.1f %%\n', beta_HD);
        fprintf('   mu       (ductility)             = %5.2f   (sqrt(mu) = %4.2f)\n', mu, sqrt(mu));
        fprintf('-----------------------------------------------------------------\n');
        fprintf(' Step 1  beta_V = beta_V0 / sqrt(mu) = %4.1f / %4.2f = %5.2f %%\n', ...
                beta_V0, sqrt(mu), beta_V);
        fprintf(' Step 2  beta   = beta_I + beta_V + beta_HD    = %5.1f %%\n', beta_total);
        fprintf(' Step 3  B (from Table 18.7-1, interp)         = %5.2f\n', B_total);
        fprintf(' Step 4  Design demand reduction = 1 - 1/B     = %5.1f %%\n', reduction_pct);
        fprintf('-----------------------------------------------------------------\n');
        fprintf(' Minimum base-shear floor (Sec 18.2.1.1, inherent + viscous only):\n');
        fprintf('   beta_(V+I) = %5.1f %%   ->   B_(V+I) = %4.2f   ->   %4.1f %% reduction\n', ...
                beta_VplusI, B_VplusI, reduction_floor_pct);
        fprintf('=================================================================\n');
    end

    % ---- Optional plot --------------------------------------------------
    if doPlot
        [beta_tab, B_tab] = table_18_7_1();
        figure('Color','w','Name','ASCE 7-22 Table 18.7-1');
        plot(beta_tab, B_tab, '-o', 'LineWidth', 1.5, 'MarkerFaceColor', 'w'); hold on;
        plot(beta_total,  B_total,  'p', 'MarkerSize', 14, ...
             'MarkerFaceColor', [0.72 0.31 0.26], 'MarkerEdgeColor', 'k');
        plot(beta_VplusI, B_VplusI, 's', 'MarkerSize', 11, ...
             'MarkerFaceColor', [0.12 0.42 0.46], 'MarkerEdgeColor', 'k');
        grid on; box on;
        xlabel('Effective damping  \beta  (% of critical)');
        ylabel('Damping coefficient  B');
        title('ASCE/SEI 7-22 Table 18.7-1');
        legend({'Table 18.7-1', ...
                sprintf('Full \\beta = %.1f%%,  B = %.2f', beta_total, B_total), ...
                sprintf('Floor \\beta_{V+I} = %.1f%%,  B = %.2f', beta_VplusI, B_VplusI)}, ...
               'Location', 'southeast');
    end
end

% ========================================================================
function B = damping_coefficient_B(beta)
%DAMPING_COEFFICIENT_B  Interpolate B from ASCE 7-22 Table 18.7-1.
%   Linear interpolation between tabulated points; clamps to table range.
    [beta_tab, B_tab] = table_18_7_1();
    beta_clamped = min(max(beta, beta_tab(1)), beta_tab(end));
    B = interp1(beta_tab, B_tab, beta_clamped, 'linear');
end

% ========================================================================
function [beta_tab, B_tab] = table_18_7_1()
%TABLE_18_7_1  ASCE/SEI 7-22 Table 18.7-1 data.
%   beta in % of critical, B dimensionless. Values carried forward from
%   ASCE 7-05/-16. Verify against your copy of ASCE/SEI 7-22 before use.
    beta_tab = [2  5  10  20  30  40  50  60  70  80  90  100];
    B_tab    = [0.8 1.0 1.2 1.5 1.7 1.9 2.0 2.1 2.2 2.3 2.4 2.5];
end