Build your own AI office with Univer Office SDK. Bring editing, calculation, collaboration, and file processing into your product for people and AI agents. Built on an extensible open-source core.
TypeScript boardcollaborationdocdocxexceloffce365officepdfpptpptxpresentationsdksheetslidesspreadsheetuniverwordwordprocessorworkspacexlsx
fix(engine-formula): stabilize RATE function with fast-path and adaptive damping (#6055)
Enajjachi Zakariaa8fbbb2d74e7c
diff --git a/packages/engine-formula/src/functions/financial/rate/__tests__/index.spec.ts b/packages/engine-formula/src/functions/financial/rate/__tests__/index.spec.tsindex db10208812..a77449e2b5 100644--- a/packages/engine-formula/src/functions/financial/rate/__tests__/index.spec.ts+++ b/packages/engine-formula/src/functions/financial/rate/__tests__/index.spec.ts@@ -167,5 +167,63 @@ describe('Test rate function', () => {);expect(typeof getObjectValue(result)).toBe('number');});++ // Edge cases for growth-only / zero-guess-+ it('Correctly calculates long-term growth-only rate even with zero guess', () => {+ const result = testFunction.calculate(+ NumberValueObject.create(90),+ NumberValueObject.create(0),+ NumberValueObject.create(-1000),+ NumberValueObject.create(7_500_000),+ NumberValueObject.create(0),+ NumberValueObject.create(0) // zero guess+ );+ expect(getObjectValue(result, true)).toBeCloseTo(0.10422, 5);+ });++ it('Rejects invalid sign convention with PMT=0', () => {+ const result = testFunction.calculate(+ NumberValueObject.create(90),+ NumberValueObject.create(0),+ NumberValueObject.create(1000),+ NumberValueObject.create(7_500_000)+ );+ expect(getObjectValue(result)).toBe(ErrorType.NUM); // PV and FV same sign+ });++ // Test type parameter boolean conversion: non-zero values should be treated as 1, only 0 as 0+ it('Converts type parameter using standard boolean conversion (non-zero = 1, zero = 0)', () => {+ const nper = NumberValueObject.create(48);+ const pmt = NumberValueObject.create(-1000);+ const pv = NumberValueObject.create(100000);+ const fv = NumberValueObject.create(0);+ const guess = NumberValueObject.create(0.1);++ // type = 0 should give one result+ const result0 = testFunction.calculate(nper, pmt, pv, fv, NumberValueObject.create(0), guess);+ const value0 = getObjectValue(result0, true) as number;++ // type = 1 should give a different result+ const result1 = testFunction.calculate(nper, pmt, pv, fv, NumberValueObject.create(1), guess);+ const value1 = getObjectValue(result1, true) as number;++ // Verify 0 and 1 produce different results+ expect(value0).not.toBe(value1);++ // Non-zero values (0.2, -1, 0.49) should be treated as 1 (true)+ const result02 = testFunction.calculate(nper, pmt, pv, fv, NumberValueObject.create(0.2), guess);+ const resultNeg1 = testFunction.calculate(nper, pmt, pv, fv, NumberValueObject.create(-1), guess);+ const result049 = testFunction.calculate(nper, pmt, pv, fv, NumberValueObject.create(0.49), guess);++ // All non-zero values should match type=1, not type=0+ expect(getObjectValue(result02, true)).toBe(value1);+ expect(getObjectValue(resultNeg1, true)).toBe(value1);+ expect(getObjectValue(result049, true)).toBe(value1);++ // Verify they don't match type=0+ expect(getObjectValue(result02, true)).not.toBe(value0);+ expect(getObjectValue(resultNeg1, true)).not.toBe(value0);+ expect(getObjectValue(result049, true)).not.toBe(value0);+ });});});diff --git a/packages/engine-formula/src/functions/financial/rate/index.ts b/packages/engine-formula/src/functions/financial/rate/index.tsindex 8337532b54..a58fd304c2 100644--- a/packages/engine-formula/src/functions/financial/rate/index.ts+++ b/packages/engine-formula/src/functions/financial/rate/index.ts@@ -86,9 +86,12 @@ export class Rate extends BaseFunction {return ErrorValueObject.create(ErrorType.NUM);}- // ? return error whenever the cash flows doesn’t make economic sense- if ((pmtValue >= 0 && pvValue >= 0 && fvValue >= 0) ||- (pmtValue <= 0 && pvValue <= 0 && fvValue <= 0)) {+ // Cash flow sanity check - prevent all-positive or all-negative cash flows+ // Zero values are considered neutral (valid for both signs)+ const allPositive = pmtValue >= 0 && pvValue >= 0 && fvValue >= 0;+ const allNegative = pmtValue <= 0 && pvValue <= 0 && fvValue <= 0;++ if (allPositive || allNegative) {return ErrorValueObject.create(ErrorType.NUM);}@@ -113,45 +116,115 @@ export class Rate extends BaseFunction {columnIndex: number): BaseValueObject {const epsMax = 1e-10;- const iterMax = 20;+ const iterMax = 100;++ // Fast path for PMT == 0+ if (Math.abs(pmtValue) < 1e-14) {+ return this._computeSimpleGrowthRate(nperValue, pvValue, fvValue, rowIndex, columnIndex);+ }let result = guessValue;+ let lastResidual = Number.POSITIVE_INFINITY;for (let i = 0; i < iterMax; i++) {if (result <= -1) {return ErrorValueObject.create(ErrorType.NUM);}- let y, f;+ const { value: y, derivative: dy } = this._evaluateRateFunction(+ result,+ nperValue,+ pmtValue,+ pvValue,+ fvValue,+ typeValue,+ epsMax+ );++ const residual = Math.abs(y);- if (Math.abs(result) < epsMax) {- y = pvValue * (1 + nperValue * result) + pmtValue * (1 + result * typeValue) * nperValue + fvValue;- } else {- f = (1 + result) ** nperValue;- y = pvValue * f + pmtValue * (1 / result + typeValue) * (f - 1) + fvValue;+ if (residual < epsMax) {+ break;}- if (Math.abs(y) < epsMax) {+ if (Math.abs(dy) < 1e-14) {break;}- let dy;+ // Adaptive damping: larger steps when far from solution, smaller when close+ const dampedStep = this._getAdaptiveDampedStep(y, dy, residual, lastResidual);- if (Math.abs(result) < epsMax) {- dy = pvValue * nperValue + pmtValue * typeValue * nperValue;- } else {- f = (1 + result) ** nperValue;- const df = nperValue * (1 + result) ** (nperValue - 1);- dy = pvValue * df + pmtValue * (1 / result + typeValue) * df + pmtValue * (-1 / (result * result)) * (f - 1);- }+ result -= dampedStep;+ lastResidual = residual;+ }- result -= y / dy;+ // Only reject rates that are mathematically invalid or non-finite+ if (!Number.isFinite(result) || result <= -1) {+ return ErrorValueObject.create(ErrorType.NUM);}- if (rowIndex === 0 && columnIndex === 0) {- return NumberValueObject.create(result, '0%');+ return NumberValueObject.create(result, rowIndex === 0 && columnIndex === 0 ? '0%' : undefined);+ }++ private _computeSimpleGrowthRate(+ nperValue: number,+ pvValue: number,+ fvValue: number,+ rowIndex: number,+ columnIndex: number+ ): BaseValueObject {+ if (Math.sign(pvValue) === Math.sign(fvValue)) {+ return ErrorValueObject.create(ErrorType.NUM);+ }+ const r = (fvValue / -pvValue) ** (1 / nperValue) - 1;+ return NumberValueObject.create(r, rowIndex === 0 && columnIndex === 0 ? '0%' : undefined);+ }++ private _evaluateRateFunction(+ rate: number,+ nperValue: number,+ pmtValue: number,+ pvValue: number,+ fvValue: number,+ typeValue: number,+ epsMax: number+ ): { value: number; derivative: number } {+ let y: number;+ let dy: number;+ let f: number;++ if (Math.abs(rate) < epsMax) {+ // Use Taylor series limit as rate approaches 0+ y = pvValue * (1 + nperValue * rate) + pmtValue * (1 + rate * typeValue) * nperValue + fvValue;+ dy = pvValue * nperValue + pmtValue * typeValue * nperValue;+ } else {+ // Standard evaluation+ f = (1 + rate) ** nperValue;+ y = pvValue * f + pmtValue * (1 / rate + typeValue) * (f - 1) + fvValue;++ const df = nperValue * (1 + rate) ** (nperValue - 1);+ dy = pvValue * df + pmtValue * (1 / rate + typeValue) * df + pmtValue * (-1 / (rate * rate)) * (f - 1);+ }++ return { value: y, derivative: dy };+ }++ private _getAdaptiveDampedStep(+ y: number,+ dy: number,+ residual: number,+ lastResidual: number+ ): number {+ const rawStep = y / dy;++ // When residual is large (>1e-3) or not improving, allow larger steps+ // When residual is small (<1e-3), use tighter damping for precision+ if (residual > 1e-3 || residual >= lastResidual * 0.9) {+ // Far from solution - allow steps up to ±5.0+ return Math.max(Math.min(rawStep, 5.0), -5.0);} else {- return NumberValueObject.create(result);+ // Close to solution - use conservative damping for stability+ return Math.max(Math.min(rawStep, 0.5), -0.5);}}}