ergodicity.developer_tools package

Submodules

ergodicity.developer_tools.custom_samplers module

custom_samplers Submodule Overview

The `custom_samplers` submodule provides utility functions for creating custom samplers from both cumulative distribution functions (CDFs) and characteristic functions (CFs). These functions allow for generating random samples from distributions that may not have built-in samplers in standard libraries, by using numerical methods such as inverse transform sampling and Fourier inversion.

Main Features:

  1. create_sampler_from_cdf:

    • Purpose: Constructs a random sampler based on a given cumulative distribution function (CDF).

    • Method: Utilizes numerical inverse CDF (bisection method) to generate random samples.

    • Parameters:

      • cdf: The cumulative distribution function of the desired distribution.

      • lower_bound: The lower bound for the support of the distribution.

      • initial_upper_bound: The initial upper bound for the support of the distribution.

      • tolerance: Numerical tolerance for inverse CDF calculation.

      • max_iterations: Maximum iterations allowed to compute the inverse CDF.

    • Returns: A callable function that generates random samples from the specified distribution.

  2. characteristic_function_to_pdf:

    • Purpose: Converts a characteristic function (CF) into a probability density function (PDF) via numerical inversion (using Fourier transform).

    • Parameters:

      • cf: The characteristic function of the desired distribution.

      • t_values: Array of t values to compute the inverse Fourier transform.

    • Returns: Arrays of PDF values and corresponding x-values for the distribution.

  3. create_sampler_from_cf:

    • Purpose: Constructs a random sampler based on a given characteristic function (CF).

    • Method: Uses numerical inversion of the characteristic function to obtain a PDF, then generates samples by creating the corresponding CDF and applying inverse transform sampling.

    • Parameters:

      • cf: The characteristic function of the desired distribution.

      • t_min and t_max: Range of t values for the Fourier transform.

      • n_points: Number of points for the Fourier transform.

      • lower_bound and upper_bound: Bounds on the support of the distribution.

    • Returns: A callable function that generates random samples from the distribution defined by the characteristic function.

Use Cases:

  1. Custom Distributions: For distributions where standard sampling methods do not exist or are inefficient, you can provide the CDF or CF and generate samples numerically.

  2. Distribution Simulation: Create random samples for simulation purposes using custom distributions, such as non-standard or modified distributions in financial modeling, physics, or statistics.

  3. Numerical Inversion: Utilize numerical methods like inverse transform sampling and Fourier inversion for specialized distributions, especially in cases where direct analytical sampling is difficult.

Example Usage:

### Creating a Sampler from a CDF:

def exponential_cdf(x, lam):

return 1 - np.exp(-lam * x)

# Create a sampler for the exponential distribution with lambda = 1

exponential_sampler = create_sampler_from_cdf(exponential_cdf, lower_bound=0, initial_upper_bound=10)

# Generate random samples

samples = [exponential_sampler(lam=1) for _ in range(10)]

print(samples)

ergodicity.developer_tools.custom_samplers.characteristic_function_to_pdf(cf, t_values)[source]

Numerically invert the characteristic function to obtain the PDF.

Parameters:

  • cf (function) – function: The characteristic function of the desired distribution.

  • t_values (numpy.ndarray) – numpy.ndarray: An array of t values for the inverse Fourier transform.

Returns:

numpy.ndarray: An array of PDF values obtained by inverting the characteristic function.

Return type:

numpy.ndarray

ergodicity.developer_tools.custom_samplers.create_sampler_from_cdf(cdf, lower_bound, initial_upper_bound, tolerance=1e-10, max_iterations=1000, warning=True)[source]

Creates a sampler function for a given distribution using its CDF.

Parameters:

  • cdf (function) – function: The cumulative distribution function (CDF) of the desired distribution.

  • lower_bound (float) – float: The lower bound of the support of the distribution.

  • initial_upper_bound (float) – float: The initial upper bound for the support of the distribution.

  • tolerance (float) – float: The tolerance level for the numerical inverse CDF calculation.

  • max_iterations (int) – int: The maximum number of iterations to find the upper bound if the initial upper bound is insufficient.

Returns:

function: A function that generates a random number from the given distribution using the specified parameters.

Return type:

function

ergodicity.developer_tools.custom_samplers.create_sampler_from_cf(cf, t_min=-0.5, t_max=0.5, n_points=10000, lower_bound=1000, upper_bound=1000, warning=True)[source]

Creates a sampler function for a given distribution using its characteristic function.

Parameters:

  • cf (function) – function: The characteristic function of the desired distribution.

  • t_min (float) – float: The minimum t value for the Fourier transform.

  • t_max (float) – float: The maximum t value for the Fourier transform.

  • n_points (int) – int: The number of points for the Fourier transform.

  • lower_bound (float) – float: The lower bound of the support of the distribution.

  • upper_bound (float) – float: The upper bound of the support of the distribution.

Returns:

function: A function that generates a random number from the given distribution.

Return type:

function

ergodicity.developer_tools.stationarity module

Module contents

developer_tools Module Overview

The `developer_tools` module is designed specifically for contributors and developers working on enhancing or maintaining the library. It provides a collection of utilities, experimental features, and testing tools that assist in the development process, but are not essential for regular usage of the library. This module contains advanced functionality, internal tools, and experimental methods that help streamline development, testing, and debugging of the library.

Key Purposes of this Module:

  1. Development Support: - The module contains tools and utilities that assist developers in building, modifying, and extending the core functionality of the library.

  2. Experimental Features: - Includes experimental or in-development features that may not yet be fully integrated into the main library but are available for testing and evaluation by developers.

  3. Testing and Validation: - Provides methods and utilities for testing the accuracy, performance, and reliability of different components within the library. This includes custom samplers, debugging tools, and numerical methods that are used during development.

  4. Not Required for General Usage: - For most users of the library, this module is not required. It is designed for internal development purposes and should be used primarily by those who are contributing to or experimenting with the underlying codebase.

Structure of the Module:

  1. `custom_samplers`: - Contains utilities for creating custom random samplers from cumulative distribution functions (CDFs) or characteristic functions (CFs). These tools are useful for testing custom distribution behaviors and validating numerical methods, particularly for experimental distributions or stochastic processes.

  2. `experimental`: - Includes experimental features and methods that are in development or under evaluation. This section provides cutting-edge tools for developers to test new ideas, methods, or integrations that may later become core parts of the library.

  3. `testing_tools` (notional): - Provides various utilities for testing and benchmarking the functionality of different library components. Developers can use these tools to ensure correctness, stability, and performance of new features before they are released.

Use Cases:

  • For Contributors: The developer_tools module provides an essential set of utilities for contributors who want to experiment with new features or test the library’s internal components.

  • Experimental Methods: Developers looking to test the boundaries of current implementations or introduce new experimental features can use this module as a sandbox environment.

  • Library Maintenance: This module also aids in testing and debugging the overall library to maintain high standards of reliability and performance.

Important Notes:

  • Experimental Nature: Many features in this module are experimental and may not be fully tested or integrated into the main library. Developers should be cautious when using these features, as they may change or be deprecated in future versions.

  • Developer Warnings: Some of the functions in this module include custom warnings to notify users of potential issues or instability, especially when working with unvalidated or experimental components.

  • Not for End Users: This module is primarily for development purposes and is not intended to be used by the general user base of the library. Regular users should focus on the core functionalities provided by the main modules, while this module remains a behind-the-scenes tool for developers.

Dependencies:

  • This module relies on the same core dependencies as the rest of the library, including NumPy, SciPy, Matplotlib, and SymPy. Additionally, it uses some development-specific libraries like inspect and warnings to manage experimental features and assist in debugging.