financecalculator2025.contribution
==================================

.. py:module:: financecalculator2025.contribution


Functions
---------

.. autoapisummary::

   financecalculator2025.contribution.calculate_contribution


Module Contents
---------------

.. py:function:: calculate_contribution(principal, future_value, annual_rate, n_periods)

   Calculates the contribution required per period to achieve a specified future value
   or pay off a loan, considering the possibility of depositing or withdrawing funds.

   :param principal: The initial loan amount or investment (present value). For loans, this should be a
                     negative value (e.g., -1000 for a loan of 1000).
   :type principal: float
   :param future_value: The target future value (amount remaining after n_periods). For loans, this is usually 0.
   :type future_value: float
   :param annual_rate: Annual interest rate (as a percentage, e.g., 5 for 5%).
   :type annual_rate: float
   :param n_periods: Total number of periods (e.g., months or years). Must be a positive integer.
   :type n_periods: int

   :returns: The payment amount per period required to reach the specified future value
             or pay off the loan. A positive value represents an inflow (e.g., making deposits),
             while a negative value represents an outflow (e.g., withdrawals or loan repayments).
   :rtype: float

   :raises ValueError: If any input is invalid, such as non-numeric types or invalid ranges.

   .. warning::

      UserWarning
          Warnings for potentially unusual inputs.

   .. rubric:: Examples

   >>> calculate_contribution(principal=0, future_value=10000, annual_rate=5, n_periods=120)