pynamical 0.3.2

pynamical package

pynamical module

pynamical core.

pynamical.pynamical.bifurcation_plot(pops, xmin=0, xmax=4, ymin=0, ymax=1, figsize=(10, 6), title='Bifurcation Diagram', xlabel='Growth Rate', ylabel='Population', color='#003399', filename='image', save=True, show=True, title_font=None, label_font=None, folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Plot the results of the model as a bifurcation diagram.

Parameters:
  • pops (DataFrame) – population data output from the model
  • xmin (float) – minimum value on the x axis
  • xmax (float) – maximum value on the x axis
  • ymin (float) – minimum value on the y axis
  • ymax (float) – maximum value on the y axis
  • figsize (tuple) – (width, height) of figure
  • title (string) – title of the plot
  • xlabel (string) – label of the x axis
  • ylabel (string) – label of the y axis
  • color (string) – color of the points in the scatter plot
  • filename (string) – name of image file to be saved, if applicable
  • save (bool) – whether to save the image to disk or not
  • show (bool) – whether to display the image on screen or not
  • title_font (matplotlib.font_manager.FontProperties) – font properties for figure title
  • label_font (matplotlib.font_manager.FontProperties) – font properties for axis labels
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:

(fig, ax) if show=False, otherwise returns None
Return type:

tuple
pynamical.pynamical.cobweb_plot(model=<function logistic_map>, r=0, function_n=1000, cobweb_n=100, cobweb_x=0.5, num_discard=0, title='', filename='', show=True, save=True, start=0, end=1, figsize=(6, 6), diagonal_linewidth=1.35, cobweb_linewidth=1, function_linewidth=1.5, title_font=None, label_font=None, folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Draw a cobweb plot.

Run the map once each for 1000 population values evenly spaced between 0 and 1. This gives us the results of the equation (y values) across the entire range of possible population values (x values). The gray diagonal line is just a plot of y=x.

Parameters:
  • model (function) – defining an iterated map to simulate
  • r (float) – growth rate parameter value to pass to the map
  • function_n (int) – number of iterations of the function to run
  • cobweb_n (int) – number of iterations of the cobweb line to run
  • num_discard (int) – how many initial iterations of the cobweb line to throw away
  • title (string) – title of the plot
  • filename (string) – name of image file to be saved, if applicable
  • save (bool) – whether to save the image to disk or not
  • show (bool) – whether to display the image on screen or not
  • start (float) – lower limit of the function range
  • end (float) – upper limit of the function range
  • figsize (tuple) – (width, height) of figure
  • diagonal_linewidth (float) – width of y=x line
  • cobweb_linewidth (float) – width of cobweb line
  • function_linewidth (float) – width of function line
  • title_font (matplotlib.font_manager.FontProperties) – font properties for figure title
  • label_font (matplotlib.font_manager.FontProperties) – font properties for axis labels
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:

(fig, ax) if show=False, otherwise returns None
Return type:

tuple
pynamical.pynamical.cubic_map(pop, rate)

Define the equation for the cubic map.

Parameters:
  • pop (float) – current population value at time t
  • rate (float) – growth rate parameter values
Returns:

scalar result of cubic map at time t+1
Return type:

float
pynamical.pynamical.get_bifurcation_plot_points(pops)

Convert a DataFrame of values from the model into a set of xy points.

You can plot these points as a bifurcation diagram.

Parameters:pops (DataFrame) – population data output from the model
Returns:
Return type:DataFrame
pynamical.pynamical.get_cobweb_points(model, r, x, n)

Calculate the vertices of cobweb lines for a cobweb plot.

Steps in the calculation: 1) Let x = 0.5 2) Start on the x-axis at the point (x, 0). 3) Draw a vertical line to the red function curve: this point has the coordinates (x, f(x)). 4) Draw a horizontal line from this point to the gray diagonal line: this point has the coordinates (f(x), f(x)). 5) Draw a vertical line from this point to the red function curve: this point has the coordinates (f(x), f(f(x))). 6) Repeat steps 4 and 5 recursively n times.

Parameters:
  • model (function) – defining an iterated map to simulate
  • r (float) – growth rate parameter value to pass to the map
  • x (float) – starting population value
  • n (int) – number of iterations to run
Returns:

cobweb_x_vals, cobweb_y_vals
Return type:

tuple
pynamical.pynamical.get_function_points(model, r, n, start, end)

Calculate model results for n population values.

Values are evenly spaced between start and end values.

Parameters:
  • model (function) – defining an iterated map to simulate
  • r (float) – growth rate parameter value to pass to the map
  • n (int) – number of iterations to run
  • start (float) – lower limit of the function range
  • end (float) – upper limit of the function range
Returns:

x_vals, y_vals
Return type:

tuple
pynamical.pynamical.get_label_font(family='Helvetica', style='normal', size=16, weight='normal', stretch='normal')

Define fonts to use for image axis labels.

Parameters:
  • family (string) –
  • style (string) –
  • size (numeric) –
  • weight (string) –
  • stretch (string) –
Returns:
Return type:

matplotlib.font_manager.FontProperties
pynamical.pynamical.get_phase_colors(color_request, length=1, color_reverse=False, default_color='#003399')

Return a list of colors based on a request.

Request could be a list, string color name, or string colormap name.

Parameters:
  • color_request (string or list) – what color the caller wants, could be a list, string color name, or string colormap name
  • length (int) – how many total colors to return in the list
  • color_reverse (bool) – reverse the returned list of colors if True
  • default_color (string) – if the list is shorter than the specified length, pad it out with default_color
Returns:
Return type:

list
pynamical.pynamical.get_phase_diagram_points(pops, discard_gens=1, dimensions=2)

Convert a DataFrame of values from the model into a set of xy(z) points.

Parameters:
  • pops (DataFrame) – population data output from the model
  • discard_gens (int) – number of rows to discard before keeping points to plot
  • dimensions (int) – {2, 3}, number of dimensions specifying if we want points for a 2-D or 3-D plot: (t, t+1) vs (t, t+1, t+2)
Returns:
Return type:

DataFrame
pynamical.pynamical.get_title_font(family='Helvetica', style='normal', size=20, weight='normal', stretch='normal')

Define fonts to use for image titles.

Parameters:
  • family (string) –
  • style (string) –
  • size (numeric) –
  • weight (string) –
  • stretch (string) –
Returns:
Return type:

matplotlib.font_manager.FontProperties
pynamical.pynamical.logistic_map(pop, rate)

Define the equation for the logistic map.

Parameters:
  • pop (float) – current population value at time t
  • rate (float) – growth rate parameter values
Returns:

scalar result of logistic map at time t+1
Return type:

float
pynamical.pynamical.make_jit_simulator(model, num_gens, rate_min, rate_max, num_rates, num_discard, initial_pop)

Create a jitted simulator function.

It receives the jitted model function, without it being an argument passed to the simulator function, because of the closure local scope.

Parameters:
  • model (function) – the function defining an iterated map to simulate
  • num_gens (int) – number of iterations to run the model
  • rate_min (float) – the first growth rate for the model, between 0 and 4
  • rate_max (float) – the last growth rate for the model, between 0 and 4
  • num_rates (int) – how many growth rates between min and max to run the model on
  • num_discard (int) – number of generations to discard before keeping population values
  • initial_pop (float) – starting population when you run the model, between 0 and 1
Returns:
Return type:

function
pynamical.pynamical.phase_diagram(pops, discard_gens=0, figsize=(6, 6), xmin=0, xmax=1, ymin=0, ymax=1, title='', xlabel='Population (t)', ylabel='Population (t + 1)', marker='.', size=5, alpha=0.7, color='#003399', color_reverse=False, legend=False, filename='image', save=True, show=True, title_font=None, label_font=None, folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Draw a 2D phase diagram for one or more time series.

Plot the value at time t on the x-axis and the value at t+1 on the y-axis.

Parameters:
  • pops (DataFrame) – population data output from the model
  • discard_gens (int) – number of rows to discard before keeping points to plot
  • figsize (tuple) – (width, height) of figure
  • xmin (float) – minimum value on the x axis
  • xmax (float) – maximum value on the x axis
  • ymin (float) – minimum value on the y axis
  • ymax (float) – maximum value on the y axis
  • title (string) – title of the plot
  • xlabel (string) – label of the x axis
  • ylabel (string) – label of the y axis
  • marker (string) – the type of point to use in the plot
  • size (float) – the size of the marker
  • alpha (float) – the opacity of the marker
  • color (string) – color of the points in the scatter plot
  • color_reverse (bool) – reverse the returned list of colors if True
  • legend (bool) – if we should display a legend or not
  • filename (string) – name of image file to be saved, if applicable
  • save (bool) – whether to save the image to disk or not
  • show (bool) – whether to display the image on screen or not
  • title_font (matplotlib.font_manager.FontProperties) – font properties for figure title
  • label_font (matplotlib.font_manager.FontProperties) – font properties for axis labels
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:

(fig, ax) if show=False, otherwise returns None
Return type:

tuple
pynamical.pynamical.phase_diagram_3d(pops, discard_gens=0, figsize=(10, 8), xmin=0, xmax=1, ymin=0, ymax=1, zmin=0, zmax=1, remove_ticks=True, title='', elev=25, azim=240, dist=10, xlabel='Population (t)', ylabel='Population (t + 1)', zlabel='Population (t + 2)', marker='.', size=5, alpha=0.7, color='#003399', color_reverse=False, legend=False, legend_bbox_to_anchor=None, filename='image', save=True, show=True, title_font=None, label_font=None, folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Draw a 3D phase diagram for one or more time series.

Plot the value at time t on the x-axis, the value at t+1 on the y-axis, and the value of t+2 on the z-axis.

Parameters:
  • pops (DataFram) – population data output from the model
  • discard_gens (int) – number of rows to discard before keeping points to plot
  • figsize (tuple) – (width, height) of figure
  • xmin (float) – minimum value on the x axis
  • xmax (float) – maximum value on the x axis
  • ymin (float) – minimum value on the y axis
  • ymax (float) – maximum value on the y axis
  • zmin (float) – minimum value on the z axis
  • zmax (float) – maximum value on the z axis
  • remove_ticks (bool) – remove axis ticks or not
  • title (string) – title of the plot
  • elev (float) – the elevation of the viewing perspective
  • azim (float) – the azimuth of the viewing perspective
  • dist (float) – the distance of the viewing perspective
  • xlabel (string) – label of the x axis
  • ylabel (string) – label of the y axis
  • zlabel (string) – label of the z axis
  • marker (string) – the type of point to use in the plot
  • size (float) – the size of the marker
  • alpha (float) – the opacity of the marker
  • color (string) – color of the points in the scatter plot
  • color_reverse (bool) – reverse the returned list of colors if True
  • legend (bool) – if we should display a legend or not
  • legend_bbox_to_anchor (float) – amount to offset the legend from its natural position
  • filename (string) – name of image file to be saved, if applicable
  • save (bool) – whether to save the image to disk or not
  • show (bool) – whether to display the image on screen or not
  • title_font (matplotlib.font_manager.FontProperties) – font properties for figure title
  • label_font (matplotlib.font_manager.FontProperties) – font properties for axis labels
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:

  • tuple
  • (fig, ax) if show=False, otherwise returns None
pynamical.pynamical.save_and_show(fig, ax, save, show, filename='image', folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Consistently handle plot completion.

Save then either display or return the figure.

Parameters:
  • fig (matplotlib figure) –
  • ax (matplotlib axis) –
  • save (bool) – whether to save the image to disk, or not
  • show (bool) – whether to display the image or instead just return figure and axis
  • filename (string) – filename of image file to be saved
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:

(fig, ax) if show=False, otherwise returns None
Return type:

tuple
pynamical.pynamical.save_fig(filename='image', folder='images', dpi=300, bbox_inches='tight', pad=0.1)

Save the current figure as a file to disk.

Parameters:
  • filename (string) – filename of image file to be saved
  • folder (string) – folder in which to save the image file
  • dpi (int) – resolution at which to save the image
  • bbox_inches (string) – tell matplotlib to figure out the tight bbox of the figure
  • pad (float) – inches to pad around the figure
Returns:
Return type:

None
pynamical.pynamical.simulate(model=<function logistic_map>, num_gens=50, rate_min=0.5, rate_max=4, num_rates=8, num_discard=0, initial_pop=0.5, jit=True)

Simulate a module.

Call simulator (either JIT compiled or not) to create a DataFrame with columns for each growth rate, row labels for each time step, and values computed by the model.

Parameters:
  • model (function) – the function defining an iterated map to simulate; default is the logistic map
  • num_gens (int) – number of iterations to run the model
  • rate_min (float) – the first growth rate for the model, between 0 and 4
  • rate_max (float) – the last growth rate for the model, between 0 and 4
  • num_rates (int) – how many growth rates between min and max to run the model on
  • num_discard (int) – number of generations to discard before keeping population values
  • initial_pop (float) – starting population when you run the model, between 0 and 1
  • jit (bool) – if True, use jit compiled simulator function to speed up simulation, if False, use uncompiled simulator function
Returns:
Return type:

DataFrame
pynamical.pynamical.simulate_jit(model, num_gens, rate_min, rate_max, num_rates, num_discard, initial_pop)

Create a DataFrame with columns for each growth rate.

Row labels for each time step, and values computed by the model (with JIT compilation). You can’t pass a jitted function to a jitted function unless you turn off ‘nopython’ mode (which makes it slow). In other words, you can’t pass different model functions directly to the simulate function. Instead, use a closure: The make_jit_simulator function returns a jitted simulator function that receives the jitted model function, without it being an argument passed to the simulator function, because of the closure local scope

Parameters:
  • model (function) – the function defining an iterated map to simulate
  • num_gens (int) – number of iterations to run the model
  • rate_min (float) – the first growth rate for the model, between 0 and 4
  • rate_max (float) – the last growth rate for the model, between 0 and 4
  • num_rates (int) – how many growth rates between min and max to run the model on
  • num_discard (int) – number of generations to discard before keeping population values
  • initial_pop (float) – starting population when you run the model, between 0 and 1
Returns:
Return type:

DataFrame
pynamical.pynamical.simulate_no_compile(model, num_gens, rate_min, rate_max, num_rates, num_discard, initial_pop)

Create a DataFrame with columns for each growth rate.

Row labels for each time step and values computed by the model (without JIT compilation).

Parameters:
  • model (function) – the function defining an iterated map to simulate
  • num_gens (int) – number of iterations to run the model
  • rate_min (float) – the first growth rate for the model, between 0 and 4
  • rate_max (float) – the last growth rate for the model, between 0 and 4
  • num_rates (int) – how many growth rates between min and max to run the model on
  • num_discard (int) – number of generations to discard before keeping population values
  • initial_pop (float) – starting population when you run the model, between 0 and 1
Returns:
Return type:

DataFrame
pynamical.pynamical.singer_map(pop, rate)

Define the equation for the singer map.

Parameters:
  • pop (float) – current population value at time t
  • rate (float) – growth rate parameter values
Returns:

scalar result of singer map at time t+1
Return type:

float

pynamical is a Python package for modeling, simulating, visualizing, and animating discrete nonlinear dynamical systems and chaos. It uses pandas, numpy, and numba for fast simulation, and matplotlib for beautiful visualizations and animations to explore system behavior.

Citation information: Boeing, G. 2016. “Visual Analysis of Nonlinear Dynamical Systems: Chaos, Fractals, Self-Similarity and the Limits of Prediction.” Systems, 4 (4), 37. doi:10.3390/systems4040037.

Installation

You can install pynamical with conda:

conda config --prepend channels conda-forge
conda create -n pynamical --strict-channel-priority jupyterlab pynamical

Alternatively, you can run pynamical + Jupyter directly from its Docker container, or you can install it with pip.

Examples

For examples and demos, see the GitHub repo: https://github.com/gboeing/pynamical

License

The project is licensed under the MIT license.

Indices and tables