Metadata-Version: 2.1
Name: ergodicity
Version: 0.3.16
Summary: A Python library for ergodicity economics and time-average analysis.
Home-page: https://github.com/Kendiukhov/ergodicity_library/
Author: Ihor Kendiukhov
Author-email: kendiukhov@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: absl-py==2.1.0
Requires-Dist: aiohttp==3.9.5
Requires-Dist: aiosignal==1.3.1
Requires-Dist: alabaster==0.7.16
Requires-Dist: astunparse==1.6.3
Requires-Dist: attrs==23.2.0
Requires-Dist: Babel==2.14.0
Requires-Dist: backports.tarfile==1.2.0
Requires-Dist: Brotli==1.1.0
Requires-Dist: certifi==2024.8.30
Requires-Dist: charset-normalizer==3.3.2
Requires-Dist: colorama==0.4.6
Requires-Dist: contourpy==1.2.1
Requires-Dist: cycler==0.12.1
Requires-Dist: docutils==0.21.2
Requires-Dist: filelock==3.15.4
Requires-Dist: flatbuffers==24.3.25
Requires-Dist: fonttools==4.53.0
Requires-Dist: fpdf==1.7.2
Requires-Dist: frozenlist==1.4.1
Requires-Dist: fsspec==2024.6.1
Requires-Dist: gast==0.6.0
Requires-Dist: gmpy2==2.1.5
Requires-Dist: google-pasta==0.2.0
Requires-Dist: grpcio==1.65.4
Requires-Dist: h5py==3.11.0
Requires-Dist: idna==3.7
Requires-Dist: imagesize==1.4.1
Requires-Dist: importlib-metadata==7.1.0
Requires-Dist: jaraco.classes==3.4.0
Requires-Dist: jaraco.context==6.0.1
Requires-Dist: jaraco.functools==4.0.2
Requires-Dist: Jinja2==3.1.4
Requires-Dist: joblib==1.4.2
Requires-Dist: keras==3.4.1
Requires-Dist: keyring==25.4.0
Requires-Dist: kiwisolver==1.4.5
Requires-Dist: libclang==18.1.1
Requires-Dist: loguru==0.7.2
Requires-Dist: Markdown==3.6
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: MarkupSafe==2.1.5
Requires-Dist: matplotlib==3.9.0
Requires-Dist: mdurl==0.1.2
Requires-Dist: ml-dtypes==0.4.0
Requires-Dist: more-itertools==10.5.0
Requires-Dist: mpld3==0.5.10
Requires-Dist: mpmath==1.3.0
Requires-Dist: msgpack==1.0.8
Requires-Dist: multidict==6.0.5
Requires-Dist: namex==0.0.8
Requires-Dist: networkx==3.3
Requires-Dist: nh3==0.2.18
Requires-Dist: numpy==1.26.4
Requires-Dist: opt-einsum==3.3.0
Requires-Dist: optree==0.12.1
Requires-Dist: packaging==24.0
Requires-Dist: pandas==2.2.2
Requires-Dist: patsy==0.5.6
Requires-Dist: pillow==10.3.0
Requires-Dist: pip==24.0
Requires-Dist: pkginfo==1.10.0
Requires-Dist: platformdirs==4.2.2
Requires-Dist: plotly==5.22.0
Requires-Dist: pooch==1.8.2
Requires-Dist: protobuf==4.25.4
Requires-Dist: Pygments==2.18.0
Requires-Dist: pyparsing==3.1.2
Requires-Dist: PySocks==1.7.1
Requires-Dist: python-dateutil==2.9.0
Requires-Dist: pytz==2024.1
Requires-Dist: pyvista==0.43.10
Requires-Dist: PyWavelets==1.6.0
Requires-Dist: readme-renderer==44.0
Requires-Dist: requests==2.32.3
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: rfc3986==2.0.0
Requires-Dist: rich==13.7.1
Requires-Dist: scikit-learn==1.5.1
Requires-Dist: scipy==1.13.1
Requires-Dist: scooby==0.10.0
Requires-Dist: seaborn==0.13.2
Requires-Dist: setuptools==70.0.0
Requires-Dist: six==1.16.0
Requires-Dist: snowballstemmer==2.2.0
Requires-Dist: Sphinx==7.3.7
Requires-Dist: sphinxcontrib-applehelp==1.0.8
Requires-Dist: sphinxcontrib-devhelp==1.0.6
Requires-Dist: sphinxcontrib-htmlhelp==2.0.5
Requires-Dist: sphinxcontrib-jsmath==1.0.1
Requires-Dist: sphinxcontrib-qthelp==1.0.7
Requires-Dist: sphinxcontrib-serializinghtml==1.1.10
Requires-Dist: statsmodels==0.14.2
Requires-Dist: stochastic==0.6.0
Requires-Dist: sympy==1.12.1
Requires-Dist: tenacity==8.4.2
Requires-Dist: tensorboard==2.17.0
Requires-Dist: tensorboard-data-server==0.7.2
Requires-Dist: tensorflow==2.17.0
Requires-Dist: tensorflow-io-gcs-filesystem==0.37.1
Requires-Dist: termcolor==2.4.0
Requires-Dist: threadpoolctl==3.5.0
Requires-Dist: tomli==2.0.1
Requires-Dist: torch==2.3.1
Requires-Dist: twine==5.1.1
Requires-Dist: typing-extensions==4.12.2
Requires-Dist: tzdata==2024.1
Requires-Dist: urllib3==2.2.1
Requires-Dist: vtk==9.2.6
Requires-Dist: Werkzeug==3.0.3
Requires-Dist: wheel==0.43.0
Requires-Dist: wrapt==1.16.0
Requires-Dist: wslink==2.1.1
Requires-Dist: yarl==1.9.4
Requires-Dist: zipp==3.17.0

# Ergodicity Library

## Overview

The **Ergodicity Library** is a Python-based open-source library focused on the study of stochastic processes, ergodicity, and time-average behaviors. Initially inspired by the work of Ole Peters and Alexander Adamou in *Ergodicity Economics*, the library extends far beyond economics and can be applied in fields such as biology, physics, finance, and more. It provides tools for simulating and analyzing stochastic processes, with a particular focus on processes with heavy tails, and enables research on non-ergodic dynamics.

## Key Features

- **Stochastic Process Simulation**: Includes a wide variety of stochastic processes, including Brownian motion, Lévy processes, and fractional Brownian motion.
- **Ergodicity Research**: Tools for studying ergodicity and time-average behavior of stochastic processes.
- **Artificial Agents**: Evolutionary algorithms and machine learning models for training agents to make decisions under uncertainty.
- **Heavy-Tailed Processes**: Special focus on processes with heavy-tailed distributions, such as Lévy alpha-stable processes.
- **Symbolic Computations**: Powerful tools for solving stochastic differential equations (SDEs) both numerically and symbolically.
- **Parallel Processing**: Support for multiprocessing to handle large-scale simulations efficiently.
- **Visualization**: Dynamic visualization of stochastic processes, with support for 3D interactive graphs.

## Installation

To install the Ergodicity Library, you can clone the repository from GitHub:

```bash
git clone https://github.com/Kendiukhov/ergodicity_library.git
cd ergodicity-library
pip install -r requirements.txt
```
Or you just install it directly from PyPI:

```bash
pip install ergodicity-library
```

The library relies on widely used Python libraries like `numpy`, `matplotlib`, `scipy`, `tensorflow`, and `keras`.

For some features (mostly related to video generation), you need to install ffmpeg. 

On MacOS, firstly install Homebrew:

```bash 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Then install ffmpeg:

```bash 
brew install ffmpeg
```

On Ubuntu, install ffmpeg with:

```bash   
sudo apt-get install ffmpeg
```

Fedora:

```bash
sudo dnf install ffmpeg
```

Arch Linux:

```bash
sudo pacman -S ffmpeg
```

On Windows, download the ffmpeg executable from the official [website](https://ffmpeg.org/) and add it to your PATH.

The library will still work without ffmpeg, but some visualization features will be disabled.

## Getting Started

### Programming Prerequisites

- Basic knowledge of Python
- Familiarity with scientific libraries: `NumPy`, `SymPy`, `Matplotlib`
- Optional: `TensorFlow` and `Keras` for machine learning components

### Academic Prerequisites

A basic understanding of the following topics is recommended:

- Probability theory and stochastic processes
- Ito calculus and stochastic differential equations (SDEs)
- Statistical estimation and fitting

### Example

Here is a simple example to get started with simulating a Brownian motion process:

```python
from ergodicity.process.basic import BrownianMotion

# Create a Brownian motion process
bm = BrownianMotion()

# Simulate the process
realization = bm.simulate(t=10, timestep=0.1 num_instance=1000, plot=True)
```

## Documentation

Extensive documentation, examples, and tutorials are available at the Ergodicity Library website: [https://ergodicitylibrary.com](https://ergodicitylibrary.com).

The documentation is also available on GitHub: [https://kendiukhov.github.io/ergodicity_library](https://kendiukhov.github.io/ergodicity_library).

The Pypi page for the library can be found here: [https://pypi.org/project/ergodicity/](https://pypi.org/project/ergodicity/).

## Structure

The library is structured into three main modules:

1. **Processes**: Provides the core stochastic processes such as Brownian motion, Poisson processes, Lévy processes, and custom-defined processes.
   - *Submodules*:
     - `basic.py`: Core stochastic processes.
     - `multiplicative.py`: Processes with multiplicative dynamics.
     - `with_memory.py`: Stochastic processes with memory.
     - `increments.py`: Defines various stochastic differentials.
     - `lib.py`: Additional less common processes.
     - `constructor.py`: Allows creating new processes without programming.
     - `custom_classes.py`: Facilitates creating new process classes.
     - `default_values.py`: Contains default process parameters.
     - `definitions.py`: Core of the library, containing abstract classes and methods.
     - `discrete.py`: Handles discrete stochastic processes.

2. **Tools**: Functions for computation, analysis, and symbolic/numerical solutions for stochastic processes.
   - *Submodules*:
     - `compute.py`: Functions for calculating parameters of stochastic processes.
     - `evaluate.py`: Evaluates time-series data.
     - `fit.py`: Fits data to various distributions.
     - `solve.py`: Symbolic solutions for stochastic analysis problems.
     - `multiprocessing.py`: Supports multi-core computations.
     - `automate.py`: Automates research calls for comparative results.
     - `preasymptotics.py`: Analyzes pre-asymptotic behavior of processes.
     - `research.py`: Automated research pipelines.
     - `partial_sde.py`: Numerical simulations of partial stochastic differential equations.
     - `helper.py`: Auxiliary functions for different parts of the tools module.

3. **Agents**: Tools to create and train artificial agents using evolutionary algorithms and machine learning models.
   - *Submodules*:
     - `agents.py`: Initializes artificial agents and elementary algorithms for training.
     - `agent_pool.py`: Manages ensembles of interacting agents.
     - `evaluation.py`: Tool for analyzing agent behavior and utility functions.
     - `evolutionary_nn.py`: Implements evolutionary training for agent neural networks.
     - `sml.py`: Standard machine learning algorithms for training agents.
     - `portfolio.py`: Simulates portfolios of stochastic processes.
     - `probability_weighting.py`: Implements probability weighting functions for decision making.

Additionally, the library contains the following components:

- `developer_tools`: Tools for developers working on the library.
- `gui`: Placeholder for future graphical user interface implementation.
- `integrations`: Placeholder for integration with other languages and domain-specific libraries.
- `cases.py`: Practical cases demonstrating the library’s functionality.
- `configurations.py`: Global parameters for the library’s behavior.
- `custom_warnings.py`: Custom warnings designed to help users with library-specific issues.

## Example Projects

Here are a few example projects you can explore with the Ergodicity Library:

1. **Simulating Financial Models**: Apply the library’s tools to simulate and analyze geometric Brownian motion and other stochastic processes in financial markets.
2. **Biological Population Dynamics**: Use stochastic population models to simulate growth patterns in ecosystems and analyze stability using ergodic theory.
3. **Training Artificial Agents**: Implement machine learning agents that optimize their decision-making strategies under stochastic environments using evolutionary algorithms.

## Contributions

The library is in active development, and contributions are welcome. Here’s how you can help:

1. **Bug Reports & Feedback**: If you encounter any bugs or have suggestions for improvements, feel free to report them on the GitHub issues page.
2. **New Features & Modules**: You can help by developing new features, improving existing ones, or expanding the library into new scientific domains like finance, biology, or physics.
3. **Testing**: If you are using the library for your own research, we would greatly appreciate your feedback and testing of its features.

To contribute, fork the repository and submit a pull request with your changes.

## Roadmap

Future releases of the Ergodicity Library will include:

- **Graphical User Interface (GUI)**: To enable easier interaction with the library without requiring deep programming knowledge.
- **Expanded Machine Learning Support**: Improved agent training models with integration of reinforcement learning and other neural network architectures.
- **Performance Enhancements**: Integration with C and Wolfram languages to optimize large-scale stochastic process simulations.
- **New Domain-Specific Modules**: Modules for domain-specific analysis in biology, finance, and physics.

## License

The Ergodicity Library is open-source and licensed under the MIT License. See the `LICENSE` file for more details.
