Calculator overview
Inputs and outputs
This summary comes from the calculator's published input and output contract.
Inputs
- The bonds in your ladder (required)
-
Default 1 row
About this input
The bonds you buy today, one row per bond, up to 10: the face amount in dollars, the yearly coupon as a percentage of face, the year it matures counted from today (1 to 30), and the price you pay per 100 of face. Each bond you use needs all four; blank rows are ignored. Coupons are paid once a year, and each bond is bought on a coupon date, so the price is the whole price.
Column Range or allowed values Face amount 1 to 1000000000 Coupon (yearly) 0 to 0.2 Matures in year 1 to 30 Price paid, per 100 of face 1 to 200 - Yield on reinvested principal (required) Conditional
-
Unit %/year Default 0.04 Range 0 to 0.2
About this input
The yearly yield, as a percentage, that the principal of an early bond earns after it is rolled over. Used only when you reinvest.
- Reinvest bonds that mature early (required)
-
Default No Allowed Yes, No
About this input
Yes rolls each bond that matures before the last one, at its face amount, into a new bond that pays the reinvestment yield each year and matures with the last bond. No pays the face back in the year each bond matures.
Outputs
- Each bond at the price you paid
-
No unit declared
About this output
One row per bond you entered: its face, coupon, the year it matures, the price you paid, what it cost, its yield to maturity at that price, its Macaulay duration and its yearly coupon. Rows you left blank stay blank.
- Modified duration (price change per 1 point of yield)
-
Unit years
About this output
The Macaulay duration divided by 1 plus the ladder yield: roughly how many percent the ladder's value moves when yields move one percentage point.
- Model Status
-
No unit declared
About this output
OK when the ladder is computed; CHECK when it is computed but deserves attention, with the reason; NOT VALID when an input is missing or out of range, with what to fix.
- Face amount of all the bonds
-
Unit currency
About this output
The face amounts of all the bonds added together: the principal they repay.
- Every coupon and principal payment added together
-
Unit currency
About this output
Every coupon and every face amount the ladder pays you, added up over all the years, without discounting.
- Workbook self-check
-
No unit declared
About this output
PASS when the workbook's own consistency checks hold for this result: the counts, every yield search bracketing its answer, every face coming back once, the cash, the cost, the durations, par bonds yielding their coupons, the tables and the charts; FAIL means the result should not be relied on.
- Yield of the whole ladder (yearly)
-
Unit %/year
About this output
The yearly yield of all your bonds together: the rate at which every coupon and principal payment, discounted to today, adds up to what the ladder costs. With reinvestment it includes the coupons on the rolled principal.
- Coupon income in the first year
-
Unit currency/yr
About this output
The coupons the ladder pays in the first year.
- Cash you receive, year by year
-
No unit declared
About this output
One row per year until the last bond matures: the coupons from your bonds, the coupons on reinvested principal, the principal paid back to you, the principal rolled into the last year, and the cash you receive.
- Face-weighted average maturity
-
Unit years
About this output
The average year in which the bonds mature, each weighted by its face amount.
- The year the last bond matures
-
Unit years
About this output
The year, counted from today, in which the last bond matures and the ladder ends.
- Macaulay duration of the ladder
-
Unit years
About this output
The Macaulay duration of the ladder, in years: the average time until its payments arrive, each payment weighted by its value today at the ladder yield.
- What the ladder costs today
-
Unit currency
About this output
What the bonds cost today: each face amount times its price per 100, divided by 100, added up.
LogicCommons is in beta. If a result, label, or reference looks wrong, tell us here; we read every message.
Methodology
Purpose and model boundary
This calculator builds a ladder of up to 10 bonds bought today and held to maturity. For each bond you enter its face amount, its yearly coupon, the year it matures counted from today and the price you pay per 100 of face; you also choose whether bonds that mature before the last one are reinvested, and if so at what yield. The workbook lays out every year's coupons and returned principal, finds each bond's yield to maturity and the yield of the whole ladder, and works out the ladder's duration. The main result is the yield of the whole ladder: the yearly rate at which every coupon and principal payment, discounted to today, adds up to what the ladder costs.
Every figure on this page is computed by the spreadsheet; the page adds nothing to it. To study one bond in depth, with its price, duration and convexity, use the Bond Price Yield Duration Convexity Calculator; for the income a dividend stock pays over the years instead, the Dividend Growth Yield on Cost Calculator.
The model is educational. It does not quote prices or yields, and it is not financial, investment, tax or legal advice.
Inputs and units
- The bonds in your ladder, one per row from the first, up to 10. Each row you use needs its face amount, from 1 to 1,000,000,000 dollars; its yearly coupon, from 0% to 20% of face; the year it matures, a whole number from 1 to 30 counted from today; and the price you pay, from 1 to 200 per 100 of face. Blank rows are ignored.
- Reinvest bonds that mature early: Yes or No.
- Yield on reinvested principal, from 0% to 20% a year. It is asked for, and used, only when you choose to reinvest.
At least one bond is required. Money is in US dollars; coupons and yields are yearly percentages.
Governing relationships
Coupons are paid once a year, and each bond is bought on a coupon date, so the price you pay is the whole price, with no accrued interest. A bond of face F, coupon c and maturity m pays F × c at the end of each year up to m and its face F at the end of year m; it costs F × price / 100.
A bond's yield to maturity is the yearly rate y at which its payments, discounted to today, equal its price:
price / 100 = Σ (payment per 1 of face in year t) / (1 + y)^t
The ladder's yield is the same rate for all the ladder's yearly cash flows against what the whole ladder costs. Its Macaulay duration is the average time until those payments arrive, each weighted by its value today at the ladder yield, and the modified duration is the Macaulay duration divided by 1 plus the ladder yield. Every payment after today is positive, so each search has exactly one answer.
With reinvestment, a bond that matures before the last one rolls its face amount, at par, into a new bond that pays the reinvestment yield each year and matures with the last bond. Its new coupons are paid to you as income, and its principal comes back in the ladder's last year, so every face amount comes back exactly once. Without reinvestment, each bond's face comes back in the year it matures.
Calculation sequence
The spreadsheet first checks every row and input. For each bond in use it writes the payment per 1 of face in each of 30 years and finds its yield by halving: the search starts with the range −50% to 100% a year and halves it 48 times, keeping the half where the discounted payments still exceed the price, so the answer is within about 3e-15 of the exact rate. No iterative calculation, solver or yield function is used. It then lays out the ladder's coupons, coupons on reinvested principal, principal paid back and principal rolled for each year, finds the ladder's yield the same way, and works out the durations, the cost, the first year's coupon income and the totals. A block of consistency checks confirms the arithmetic before the status is returned.
Outputs and interpretation
The headline is the yield of the whole ladder. Beside it are the ladder's Macaulay duration, what it costs today and its coupon income in the first year. The tables show each bond with its cost, yield to maturity, duration and yearly coupon, and each year's cash flows until the last bond matures. The modified duration, the total of every coupon and principal payment, the face-weighted average maturity, the total face amount, the year the last bond matures and the workbook's self-check are returned to the API and MCP.
With the default inputs, one 10,000-dollar bond paying 4% a year, maturing in year 5 and bought at 98.50, the ladder costs 9,850 dollars, pays 400 dollars of coupons in the first year and yields 4.340% a year, above its coupon because it was bought below par; its duration is 4.63 years. The five-year ladder example, one 10,000-dollar bond maturing in each of years 1 to 5 with coupons from 4.0% to 4.4%, costs 49,810 dollars, yields 4.403% and has a duration of 2.84 years. Rolling its early bonds into year 5 at 4.5% raises the yield to 4.440% and the duration to 4.61 years, because the principal now comes back in year 5, with 52,240 dollars of cash that year. Ten par bonds paying 4.5% yield exactly 4.5%.
The first chart shows the cash the ladder pays each year: the coupon income and, in the years bonds mature, the principal paid back. The second chart places each bond as a dot at its maturity and its yield to maturity, with the dashed line at the yield of the whole ladder; two bonds maturing in the same year are two dots at one year.
Validation and status logic
The workbook evaluates the conditions below from top to bottom and returns the first matching status.
| Priority | Condition | Returned status |
|---|---|---|
| 1 | A bond row is partly filled | NOT VALID: every rung you use needs its face amount, coupon, maturity year and price |
| 2 | No bond is entered | NOT VALID: enter at least one rung |
| 3 | A face amount is outside the supported interval | NOT VALID: the face amount of each rung must be from 1 to 1,000,000,000 dollars |
| 4 | A coupon is outside the supported interval | NOT VALID: the coupon of each rung must be between 0% and 20% a year |
| 5 | A maturity year is not a whole number in the supported interval | NOT VALID: the maturity year of each rung must be a whole number from 1 to 30 |
| 6 | A price is outside the supported interval | NOT VALID: the price of each rung must be from 1 to 200 per 100 of face |
| 7 | Reinvesting is neither Yes nor No | NOT VALID: choose Yes or No for reinvesting the rungs that mature early |
| 8 | The reinvestment yield is outside the supported interval | NOT VALID: the reinvestment yield must be between 0% and 20% a year |
| 9 | The workbook's self-check fails | CHECK: the self-check of the workbook failed for this result, so do not rely on it; please report it |
| 10 | A bond's or the ladder's yield reaches the end of the range searched | CHECK: the price of at least one rung implies a yield outside -50% to 100% a year, the range searched, so its yield shows the end of that range; check the price |
| 11 | None of the preceding conditions applies | OK |
NOT VALID is a refusal, not a numeric answer: every number reads zero and the tables are empty. CHECK accompanies a computed result but calls for the stated review. The self-check is reported separately as arithmetic-integrity evidence; it does not replace this ordered status chain.
Assumptions and limitations
Coupons are paid once a year and each bond is bought on a coupon date; real bonds often pay twice a year and are bought between coupon dates with accrued interest. Every bond is held to maturity, with no default, call or sale, and there is no tax. Reinvested principal rolls once, at par, into the ladder's last year; a ladder that keeps buying a new longest bond forever is not modelled. Amounts are nominal dollars.
Restrictions and non-computing states
This calculator enforces its numeric and choice limits before it accepts a result. Every row in use must be complete, maturities are whole years from 1 to 30, and at least one bond is needed. The reinvestment yield is checked only when you reinvest; when you do not, it is hidden and ignored. A yield beyond −50% or 100% a year is shown at that end of the range, with the CHECK status above.
Errors and warnings
A request rejected by the page's input limits is not a computed result. A transport or service failure cannot establish a fresh workbook answer. Review the workbook's References and Disclaimer, and check any purchase with a qualified professional before using a result for a real decision.
References
Sources and further reading
The face amounts, coupons, maturities, prices and reinvestment yield come from the inputs, not market data: the model is discounting and simple arithmetic, and it uses no table, rate or figure from any publication. The workbook's References sheet identifies the sources below. The links explain the methods the model follows; they do not endorse this calculator.
- The Bond Price Yield Duration Convexity Calculator on this site uses the same conventions for one bond: a yield found by a bracketing search, the Macaulay duration weighted by present value, and the modified duration as the Macaulay duration divided by 1 plus the yield.
- Microsoft Support's SUMPRODUCT, SMALL and INDEX documentation describe the functions the workbook uses to discount the payments and to sort the bonds.
Each yield is found by halving a range of rates 48 times; the methodology states every relationship the workbook uses.
This is an educational estimate, not financial, investment, tax or legal advice. Bond prices, yields and terms differ in practice, and real bonds can default, be called or be sold before maturity; check any purchase with a qualified professional.
Found a problem, or have an idea?
Tell us if a result looks wrong, a label is unclear, or something is missing. We read every message.