Cashflower

Updates:
- removed unnecessary data transposing for increased efficiency,
- added a description of the release process to the documentation,
- updated to numpy 2.0.1 for better compatibility,
- made minor documentation fixes.

Updates:
- refactored codebase for improved readability and maintainability,
- added support for handling graphs with strongly connected components (SCCs).

In this release, we have introduced a new feature: stochastic variables.

To run the model stochastically, set the `NUM_STOCHASTIC_SCENARIOS` with the desired number of stochastic scenarios.

python
settings = {
...
"NUM_STOCHASTIC_SCENARIOS": 10,
}


Next define create stochastic variables. These variables that have two parameters: `t` and `stoch`.

python
variable()
def discount_rate(t, stoch):
return assumption["discount_rates"+stoch][t]


variable()
def pv_premiums(t, stoch):
if t == settings["T_MAX_CALCULATION"]:
return premium(t)
else:
return premium(t) + pv_premiums(t+1, stoch) * discount_rate(t+1, stoch)


These stochastic variables will be calculated 10 times, where `stoch` value ranging from `1` to `10`.
The output will show the average result from these scenarios.

In this latest release, the primary focus has been on refining the order of variable calculation within cyclic relationships.

The key improvements in this version:

1. **Addition of the `cycle_order` attribute** - we've introduced the `cycle_order` attribute within the `Variable` class. This attribute contains an integer that defines the calculation order within groups of variables forming cycles.

2. **Prevention of bidirectional recursion** - bidirectional recursion, where a variable calls both `t-...` and `t+...` in its definition, is now explicitly disallowed in the models. This restriction helps maintain clear and manageable relationships between variables.

3. **Error handling for negative index calls** - the package raises errors for calls with negative indexes. When a model variable is invoked for `t<0`, the package prompts an error, preventing potential inconsistencies in computations.

**New in this release:**

- new feature for model variables that don’t aggregate,
- eliminated redundant warnings for non-git repository folders,
- enhanced and updated the documentation.

---

**New feature:**

Now, users can specify the `aggregation_type` for variables.

<br>

Default behaviour:
All results are summed automatically.

python
variable()
def my_variable(t):
code


This is equivalent to explicitly defining aggregation as sum:

python
variable(aggregation_type="sum")
def my_variable(t):
code


This default behavior suits most financial scenarios involving cash flows like premiums and expenses.

<br>

Additional customization:
Users can now specify variables where results are sourced only from the first model point:

python
variable(aggregation_type="first")
def my_variable(t):
code


This configuration ensures that only the results from the first model point are included.
Suitable for containing results like interest rate curves or projection years.

To upgrade your existing model to version >= 0.6.0 of the cashflower, insert the following code into your `run.py` script:

python
import os
from cashflower import run
from settings import settings

if __name__ == "__main__":
output = run(settings=settings, path=os.path.dirname(__file__))