ergodicity package

Subpackages

Submodules

ergodicity.cases module

cases Module Overview

The `cases` module showcases a selection of illustrative and practical examples that demonstrate how the library can be used in a variety of contexts. These examples highlight the key functionalities of the library and serve as a guide for users to explore different features in action. Whether you are a beginner seeking to understand the basic processes or an advanced user exploring complex models, this module provides valuable insights through real-world applications.

Key Purposes of this Module:

  1. Demonstrate Library Capabilities:

    • The cases are designed to show the power and flexibility of the library by showcasing its application in different domains, such as stochastic processes, evolutionary neural networks, and utility function fitting.

  2. Educational and Illustrative:

    • Each case walks through a specific feature or combination of features, offering a hands-on way to learn how the library can be applied to real-world problems.

  3. Complete, Ready-to-Run Examples:

    • All cases are self-contained, meaning you can execute them as they are to explore various processes, agents, and tools provided by the library.

  4. Broad Spectrum of Examples:

    • The examples cover simple simulations, advanced stochastic modeling, neural networks, agent-based modeling, utility function fitting, and more. These cases provide a broad perspective on how the library can be leveraged in different scenarios.

Structure of the Module:

  1. `IntroCase`:

    • A basic introduction to using the library with the GeometricBrownianMotion process. The case involves simulating data, visualizing moments, and comparing averages.

  2. `UtilityFitting_case`:

    • Demonstrates utility function fitting by showcasing how multiple utility functions can be fitted using agent choices and different stochastic processes.

  3. `EvolutionaryNN_case`:

    • Explores the use of evolutionary neural networks with agents making decisions based on encoded processes. The case covers process generation, neural network mutation, cloning, and evolutionary training of agents.

  4. `StochasticHeatEquation_case`:

    • Simulates a stochastic partial differential equation (PDE), specifically the stochastic heat equation, showcasing advanced simulation techniques and visualizations like 3D plotting and animations.

  5. `BasicUtilityAgent_case`:

    • Illustrates the use of basic utility agents interacting with GeometricBrownianMotion, comparing symbolic and numerical expected utilities, and running evolutionary algorithms to optimize agent behavior.

  6. `TimeAverageDynamicsGBM_case`:

    • Focuses on time-average dynamics in a Geometric Brownian Motion process and demonstrates the ergodicity transformation.

  7. `GeometricLevyProcess_case`:

    • Simulates and visualizes the Geometric Levy Process, showcasing how ensemble and time averages can be computed and compared.

  8. `VariousSimulations_case`:

    • A collection of simulations involving various stochastic processes such as the Bessel process, Brownian bridge, Cauchy process, and more, illustrating the library’s capabilities across multiple process types.

  9. `MultivariateGeometricBrownianMotion_case`:

    • Demonstrates how to simulate and visualize multivariate Geometric Brownian Motion with a specified correlation matrix.

  10. `GeometricBrownianMotion_case`:

  • Uses parallel execution to simulate the Geometric Brownian Motion process efficiently across multiple settings.

  1. `ItoLemmaApplication`:

  • Applies Ito’s Lemma to a given stochastic differential equation (SDE), providing insight into how symbolic manipulation can be used for process analysis.

Use Cases:

  • Educational Use: The module provides learning materials for users who are new to stochastic processes, agent-based modeling, or neural networks.

  • Advanced Experimentation: For experienced users, the cases demonstrate advanced features such as process encoding, utility fitting, evolutionary strategies, and stochastic PDEs.

  • Library Exploration: Users can explore different parts of the library by running these cases and understanding how each component functions in practice.

## Important Notes:

  • Illustrative Nature: While these cases serve as valuable educational tools, they also illustrate how the library can be applied to complex scenarios in a meaningful way.

  • Self-Contained: Each case is self-contained and can be run independently to experiment with specific functionalities of the library.

  • Comprehensive Coverage: The examples in this module cover a wide range of topics, from basic stochastic processes to advanced neural networks, making it a versatile resource for learning.

ergodicity.cases.BasicUtilityAgent_case()[source]

This case demonstrates the use of basic utility agents interacting with GeometricBrownianMotion processes.

Returns:

final_agents: The final agents after the evolutionary training.

Return type:

list

ergodicity.cases.EvolutionaryNN_case()[source]

This case demonstrates the use of evolutionary neural networks for agent-based modeling with encoded processes. It covers process generation, neural network mutation, cloning, and evolutionary training of agents. The goal is to optimize agent behavior based on encoded processes and fitness evaluation.

Returns:

final_agents: The final agents after the evolutionary training.

Return type:

list

ergodicity.cases.GBM_Properties_case()[source]

This case demonstrates how to access and modify properties of the GeometricBrownianMotion process.

Returns:

None

ergodicity.cases.GeometricBrownianMotion_case()[source]

This case uses parallel execution to simulate the Geometric Brownian Motion process efficiently across multiple settings. Geometric Brownian Motion is a fundamental process in stochastic calculus and financial mathematics.

Returns:

results: The results of the parallel execution.

Return type:

list

ergodicity.cases.GeometricLevyProcess_case()[source]

This case simulates and visualizes the Geometric Levy Process, showcasing how ensemble and time averages can be computed and compared. It is a very general and frequently used process in many areas and the library puts a strong emphasis on it.

return:

None

ergodicity.cases.IntroCase()[source]

This is an introductory case that demonstrates the basic usage of the library with the GeometricBrownianMotion process.

Returns:

simulated_data: The simulated data from the GeometricBrownianMotion process.

Return type:

np.ndarray

ergodicity.cases.ItoLemmaApplication()[source]

This case applies Ito’s Lemma to a given stochastic differential equation (SDE), providing insight into how symbolic manipulation can be used for process analysis.

Returns:

result: The result of applying Ito’s Lemma to the given SDE.

Return type:

sympy.Expr

ergodicity.cases.MultivariateGeometricBrownianMotion_case()[source]

This case demonstrates how to simulate and visualize multivariate Geometric Brownian Motion with a specified correlation matrix.

Returns:

None

ergodicity.cases.StochasticHeatEquation_case()[source]

This case demonstrates the simulation of a stochastic partial differential equation (PDE), specifically the stochastic heat equation.

Returns:

None

ergodicity.cases.TimeAverageDynamicsGBM_case()[source]

This case focuses on time-average dynamics in a Geometric Brownian Motion process and demonstrates the ergodicity transformation.

Returns:

None

ergodicity.cases.UtilityFitting_case(model_path)[source]

This case demonstrates the functionality for the empirical utility function fitting using the UtilityFunctionInference class.

Parameters:

model_path (str)

Returns:

None

ergodicity.cases.VariousSimulations_case()[source]

This case demonstrates a collection of simulations involving various stochastic processes, showcasing the library’s capabilities across multiple process types.

Returns:

data: The simulated data for each process.

Return type:

list

ergodicity.conf module

ergodicity.configurations module

This file contains the main adjustable configurations for the Ergodicity Library. These are the most important global variables that can be changed by the user. The user can change the values of these variables to customize the behavior of the package. Initially, the parameters are set to enable explanatory command line outputs and conduct analysis pipelines with parameters optimized for Levy processes and computational power of a personal computer.

ergodicity.custom_warnings module

Custom Warnings Module Overview

The `custom_warnings` module defines a set of custom warning classes that are specifically tailored for the development and use of the library. These warnings are meant to inform users and developers about the status, reliability, and recommended usage of certain features or parameters within the library.

Purpose:

This module is primarily used to alert users when they are interacting with:

  • Features that are still under development.

  • Functions or parameters that require careful attention.

  • Code that has not been thoroughly tested or validated.

By providing specific, tailored warnings, the module enhances the transparency and robustness of the library, ensuring that users are aware of potential issues or limitations when using experimental or edge-case features.

Key Warnings Defined:

  1. InDevelopmentWarning:

    • Purpose: Indicates that a feature is still in development and may not work as intended.

    • Usage: Used to alert users when they are interacting with a feature that is under active development and may have limited functionality or unexpected behavior.

    • Message: “This feature is still in development and may not function as intended. Please use with caution.”

  2. KnowWhatYouDoWarning:

    • Purpose: Warns users that they must understand what they are doing, as the function may not raise an error but could behave unexpectedly with invalid inputs.

    • Usage: Useful in cases where the function’s behavior depends heavily on correct inputs, and failure to provide valid input could lead to silent failures.

    • Message: “Make sure you know what you are doing. This function may not work properly if you do not provide a valid input but will not raise an error.”

  3. NotTestedWarning:

    • Purpose: Indicates that a feature has not been thoroughly tested and may have unverified behavior.

    • Usage: Warns users that they are using a feature that could behave unpredictably due to a lack of testing or validation.

    • Message: “This feature has not been tested and may not function as intended. Please use with caution.”

  4. NotRecommendedWarning:

    • Purpose: Alerts users that a specific feature or set of parameters is not recommended for use.

    • Usage: Applied when certain configurations or uses of the library are discouraged, even though they might technically work, to prevent misuse or suboptimal performance.

    • Message: “This feature or set of parameters is not recommended for use. Please use with caution.”

When to Use These Warnings:

These custom warnings should be invoked when:

  • Users are interacting with experimental features.

  • Developers are working on a function that hasn’t yet been validated or widely tested.

  • A certain set of inputs or parameters might lead to suboptimal or incorrect behavior without explicitly raising an error.

By using these warnings, both developers and users are encouraged to carefully consider the use of certain features, promoting a more stable and reliable interaction with the library.

exception ergodicity.custom_warnings.InDevelopmentWarning(message)[source]

Bases: UserWarning

exception ergodicity.custom_warnings.KnowWhatYouDoWarning(message)[source]

Bases: UserWarning

exception ergodicity.custom_warnings.NotRecommendedWarning(message)[source]

Bases: UserWarning

exception ergodicity.custom_warnings.NotTestedWarning(message)[source]

Bases: UserWarning

Module contents

Ergodicity Library: A Python toolkit for stochastic processes and ergodicity economics.

The Ergodicity Library is a comprehensive Python package designed for analyzing stochastic processes, with a particular focus on ergodicity economics. It provides tools for:

Simulating and visualizing various stochastic processes, including Brownian motion, Lévy processes, and custom processes. It is focused on:

Analyzing time averages and ensemble averages of stochastic processes.

Implementing ergodic transformations and other key concepts from ergodicity economics.

Fitting stochastic models to empirical data and estimating process parameters.

Creating and training artificial agents for decision-making under uncertainty.

Performing multi-core computations for efficient large-scale simulations.

Key features:

Object-oriented design with a flexible class hierarchy for stochastic processes

Integration with popular scientific Python libraries (NumPy, SciPy, SymPy, Matplotlib)

Symbolic computation capabilities for stochastic calculus

Tools for analyzing non-ergodic and heavy-tailed processes

Support for both Itô and non-Itô processes

Customizable configurations and default parameters

The library is suitable for researchers, students, and practitioners in fields such as economics, finance, physics, and applied mathematics. It aims to bridge the gap between theoretical concepts in ergodicity economics and practical computational tools. For more information, visit: www.ergodicitylibrary.com Version: 0.3.0