PyCIClib – Python Compound Interest Calculator

PyCIClib is a small Python package offering a versatile compound interest calculator for realistic investment analysis and personal finance applications. It supports variable interest rates and compounding frequencies, periodic contributions with flexible frequencies, 2 different contribution timings and tax adjustments. Additionally, the timeline() method returns a detailed pandas DataFrame that lets you visualize your growth scenarios and export the results to CSV or Excel files.

Calculation Details

For compounding purposes, the effective interest_rate is converted to an equivalent daily rate (p.d.) which is used internally for enhanced calculation accuracy. The system dynamically computes dates starting from the specified start_date; if no date is provided, today’s date datetime.today() is used by default. Interest is applied at the end of each period according to the selected frequency. Contributions are applied at the beginning of the period when contribution_timing is set to "start" and at the end when set to "end". If no value is provided, but there is an input for contribution and contribution_freq, then the default value is "end". For both comp_freq and contribution_freq, you can choose from the following options: "annually", "semiannually", "quarterly", "monthly", "biweekly", "weekly", and "daily". If no comp_freq is provided, it is automatically determined based on the given rate_basis.

Installation

pip install pyciclib

Example Usage

import pyciclib as pc

# creating an instance
calc = pc.CompoundInterest(
    init_value=10_000,
    interest_rate=0.05,
    rate_basis="p.a.",
    years=2,
    start_date="21.02.2025",
    comp_freq="annually",
    contribution=100,
    contribution_freq="monthly",
    contribution_timing="start",
    tax_rate=0.25,
)

# overview of all methods
print(calc.timeline())
print(calc.summary()) # you can also format this nicely with the json package
print(calc.future_value())
print(calc.total_contributions())
print(calc.total_gross_interest())
print(calc.total_tax_paid())
print(calc.total_net_interest())

# you can also write the detailed investment table to csv or excel with pandas
calc.timeline().to_csv("investment_details.csv", index=False)
calc.timeline().to_excel("investment_details.xlsx", index=False, engine="openpyxl")

Class Parameters

Required Parameters:

• init_value: Initial investment

• interest_rate: Effective interest rate as decimal (e.g. 0.05 for 5%)

• rate_basis: Interest rate basis ("p.a.", "p.m.", ...)

• years: Duration in years

Optional Parameters:

• start_date: Starting date of the investment (datetime(), "YYYY-MM-DD" or "DD.MM.YYYY")

• comp_freq: Compounding frequency ("annually", "semiannually", ...)

• contribution: Amount added each interval

• contribution_freq: Frequency of contributions ("annually", "semiannually", ...)

• contribution_timing: Payment at start/end of period. ("start", "end")

• tax_rate: Tax rate applied to interest immediately after compounding.

Available Methods

• timeline(): Returns a detailed pandas dataframe of the investment (see table below)

• future_value(): Returns the future value of the investment

• summary(): Returns a dictonary of the inputs/outputs of the investment

• total_contributions(): Returns the total amount of contributions

• total_gross_interest(): Returns the total amount of gross interest earned

• total_tax_paid(): Returns the total amount of tax paid

• total_net_interest(): Returns the total amount of net interest earned

Sample table output