# nhpp

## INSTALLATION: ```pip install nhpp```

## PURPOSE:
This package is a standalone module for
generating non-homogeneous Poisson processes (nhpp).
Homogeneous Poisson processes are easily generated by specifying
an arrival rate, lambda, then generating samples from 
X ~ exp(1 / lambda). These samples indicate the inter-arrival
times between events, or the delay between events.

The above case is only true when lambda is a constant.
Generalizing to the case of lambda(t), a time-dependent arrival
rate, is much trickier. A couple main approaches exist
to tackle this issue:

    (1) relate the INTEGRATED rate function LAMBDA(t) to a homogeneous Poisson process via an inversion function,
    (2) use a "thinning" method which acts as an acceptance-rejection sampling routine.

The method nhpp.get_arrivals can be used in two different ways. The first method allows the user to specify a
piecewise linear function by passing a dictionary specifying the function's 'knots'. See the example usage below.

Alternatively, if the true arrival rate function lambda(t) is known, one can define a function to be then passed as
an argument. In this case, the 'knots' that must be passed as an argument must specify a piecewise linear function
that dominates the true rate function everywhere in the domain: lambda(t) <= piecewise(t) for all t. See example
usage below.

## EXAMPLE USAGE WITH PIECEWISE LINEAR FUNCTION

```
# Specify the piecewise linear arrival rate via knots.
# Below we specify arrival_rate = 1 at time = 0, arrival_rate = 2 at time = 5,
# arrival_rate = 1 at time = 2.5 (linearity between time = 0 and time = 5), etc.

>>> knots = {0: 1, 5: 2, 12: 0.3, 15: 0.3, 16: 0, 18: 0, 20: 2}

>>> arrs = nhpp.get_arrivals(knots)

# Print out arrival times.
>>> for arr in arrs:
		print(round(arr, 2))

0.08
1.1
1.14
2.35
2.41
2.45
2.91
3.67
4.41
4.65
4.7
6.78
7.13
7.18
8.12
10.15
18.33
19.21
19.53
19.54
```

## EXAMPLE USAGE FOR KNOWN ARRIVAL FUNCTION

```
# Define a quadratic rate function.
def rate(t):
	return t*(5-t)

# Specify a piecewise linear function that dominates rate(t):
knots = {0: 0, 1: 6.25, 2.5: 6.25, 4: 6.25, 5: 0}

arrivals = get_arrivals(knots, rate)

for arr in arrivals:
	print(round(arr, 2))

0.59
0.73
0.74
0.89
1.02
1.11
1.39
1.6
1.61
1.7
2.1
2.17
2.18
2.7
3.04
3.24
3.47
3.57
3.6
3.61
```

## Next steps
Future progress on this package will include a means to only specify the rate function
without having to include the 'knots'.