Quickstart

Import from the top-level package for common tasks:

import numpy as np
import pandas as pd

from parasolpy import (
    convert_cfs_to_af,
    create_ism_traces,
    pivot_timeseries_by_year,
    sequent_peak,
)

Calculate Required Capacity using Sequent Peak

inflow = np.array([12.0, 8.0, 6.0, 15.0, 10.0])
demand = 10.0

storage = sequent_peak(inflow, demand)
required_capacity = storage.max()

For a sequence of flows given in inflow, this uses the Sequent Peak method to find the required storage needed to meet demand at each timestep. The method calculates running tallies of shortage for time periods when demand cannot be met. The entire timeseries of shortage values is saved in storage. The method assumes that its maximum is the required storage capacity for the sequence.

To test whether the required_capacity is enough, you can perform a basic mass balance calculation where the ‘new’ reservoir starts full, accepts inflow, and releases demand (or spills). The storage within the reservoir should never go below 0, and demand should be able to be met over the sequence.

Stochastic Streamflow: Index Sequential Method

historical = np.arange(1, 13)
traces, source_indices = create_ism_traces(historical, k=3, trace_length=6)

In this example, the historical trace is simply the numbers from 1-12. To create Index Sequential Method (ISM) traces, we use the create_ism_traces function, passing in the historical data, indicating we want to skip 3 timesteps between each sequence (k=3) and we want traces that are 6 units long (trace_length=6). Each column in traces is one index-sequential trace. source_indices records which positions from the original historical record were used.

Unit Conversion and Yearly Pivot

parasolpy also contains common utility functions that can help when processing reservoir timeseries:

daily_cfs = pd.Series(
    [100.0, 120.0, 95.0],
    index=pd.to_datetime(["2026-01-01", "2026-01-02", "2026-01-03"]),
)

daily_af = convert_cfs_to_af(daily_cfs)
by_year = pivot_timeseries_by_year(daily_af)

More Examples

The examples/ directory contains runnable scripts that generate synthetic inputs and write outputs to examples/_output/.