{"record":{"id":"d7ac132851f9cfdf","repo":"HKUDS/Vibe-Trading","slug":"convergenceerror-period-iterations-delta-circul","errorCode":null,"errorMessage":"ConvergenceError(period, iterations, delta, circularity_tolerance)","messagePattern":"ConvergenceError\\(period, iterations, delta, circularity_tolerance\\)","errorType":"error_code","errorClass":"ConvergenceError","httpStatus":null,"severity":"error","filePath":"agent/src/quantlib/valuation/threestatement.py","lineNumber":614,"sourceCode":"            surplus = cash_before_revolver - minimum_cash\n            revolver_repayment = min(surplus, debt_begin)\n            revolver_draw = 0.0\n        else:\n            revolver_draw = minimum_cash - cash_before_revolver\n            revolver_repayment = 0.0\n\n        debt_end_actual = debt_begin + revolver_draw - revolver_repayment\n        cash_end = cash_before_revolver + revolver_draw - revolver_repayment\n\n        scale = max(abs(debt_end_actual), 1.0)\n        delta = abs(debt_end_actual - debt_end_guess)\n        if delta <= circularity_tolerance * scale:\n            converged = True\n            break\n        debt_end_guess = debt_end_actual\n\n    if not converged:\n        raise ConvergenceError(period, iterations, delta, circularity_tolerance)\n\n    financing_activities = revolver_draw - revolver_repayment - dividends_paid\n    net_change_in_cash = net_income + depreciation_amortization - change_in_nwc - capex + financing_activities\n\n    income_statement = IncomeStatement(\n        period=period,\n        revenue=revenue,\n        gross_profit=gross_profit,\n        opex=opex,\n        ebitda=ebitda,\n        depreciation_amortization=depreciation_amortization,\n        ebit=ebit,\n        interest_expense=interest_expense,\n        pretax_income=pretax_income,\n        tax_expense=tax_expense,\n        net_income=net_income,\n    )\n    cash_flow_statement = CashFlowStatement(","sourceCodeStart":596,"sourceCodeEnd":632,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/quantlib/valuation/threestatement.py#L596-L632","documentation":"The three-statement model solves debt/cash circularity iteratively per period; _project_period iterates up to max_circularity_iterations and declares convergence when the update delta falls below circularity_tolerance*scale. If the fixed point is not reached in the budget, it raises ConvergenceError with the period, iterations, final delta and tolerance so you can tell how far off it is.","triggerScenarios":"Highly levered or volatile driver sets where debt swings large amounts each iteration; circularity_tolerance set extremely small (e.g. 1e-14); max_circularity_iterations left at a low default while the model needs more passes; NaN-adjacent scale issues.","commonSituations":"Stress-test scenarios with extreme growth or payout ratios; tightening tolerance for audit-grade precision without raising iterations; opening balance sheets far from steady state.","solutions":["Raise max_circularity_iterations (e.g. 100 -> 1000) — check the reported delta trend to see if it is converging slowly vs oscillating.","Relax circularity_tolerance to something commensurate with your figures' scale (it is relative to balance size).","If delta is not decreasing, revisit extreme drivers (payout > earnings, capex > FCF) that may create a divergent or oscillating fixed point."],"exampleFix":"# before\nresult = project_three_statement(opening, drivers)  # ConvergenceError\n# after\nresult = project_three_statement(\n    opening, drivers,\n    max_circularity_iterations=1000,\n    circularity_tolerance=1e-8,\n)","handlingStrategy":"retry","validationCode":"# cannot fully pre-validate; sanity-check extremes\nassert all(abs(g) < 2.0 for g in drivers['revenue_growth'])  # implausible growth hints at divergence","typeGuard":null,"tryCatchPattern":"from quantlib.valuation.threestatement import ConvergenceError\nfor iters in (100, 500, 2000):\n    try:\n        return project_three_statement(opening, drivers, max_circularity_iterations=iters)\n    except ConvergenceError as e:\n        last = e\nraise last","preventionTips":["Start with generous max_circularity_iterations and tighten only if slow","Keep tolerance relative to balance-sheet scale, not absolute","Watch reported delta between retries: decreasing means slow convergence, flat/oscillating means model problem"],"tags":["valuation","three-statement","convergence","iteration-limit"],"backgroundTag":"solver-did-not-converge","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}