diff --git a/README.md b/README.md index 3d9ce52..95f7dc6 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,54 @@ Echo State Networks powered by and [dask](https://www.dask.org/). +## Description + +**xesn** is a python package for implementing Echo State Networks (ESNs), a +particular form of Recurrent Neural Network originally introduced by +[Jaeger (2001)](https://www.ai.rug.nl/minds/uploads/EchoStatesTechRep.pdf). +The main purpose of the package is to enable ESNs for relatively large scale +weather and climate applications, +for example as by [Smith et al., (2023)](https://arxiv.org/abs/2305.00100) +and [Arcomano et al., (2020)](https://doi.org/10.1029/2020GL087776). +The package is designed to strike the balance between simplicity and +flexibility, with a focus on implementing features that were shown to matter +most by [Platt et al., (2022)](https://doi.org/10.1016/j.neunet.2022.06.025). + +xesn uses [xarray](https://docs.xarray.dev/en/stable/) +to handle multi-dimensional data, relying on +[dask](https://www.dask.org/) for parallelization and +to handle datasets/networks that are too large for a single compute node. +At its core, xesn uses +[numpy](https://numpy.org/) +and [cupy](https://cupy.dev/) +for efficient CPU and GPU deployment. + +## Installation + +To install from source + +```shell +git clone https://github.com/timothyas/xesn.git +cd xesn +pip install -e . +``` + +Note that additional dependencies can be installed to run the unit test suite:: + +```shell +pip install -e .[test] +pytest xesn/test/*.py +``` + +## Getting Started + +To learn how to use xesn, check out the +[documentation here](https://xesn.readthedocs.io/en/latest/index.html) + +## Get in touch + +Report bugs, suggest features, or view the source code +[on GitHub](https://github.com/timothyas/xesn). ## License and Copyright diff --git a/ci/environment.yaml b/ci/environment.yaml index 1cd9289..f672a48 100644 --- a/ci/environment.yaml +++ b/ci/environment.yaml @@ -20,4 +20,4 @@ dependencies: - coverage - pip - pip: - - smt>=2.0.1 + - smt==2.1.0 diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..4a0b625 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,74 @@ +How to Contribute +################# + +If you're interested in contributing to xesn, thank you! Here are some pointers +for doing so. + +1. Environment Setup +-------------------- + +First you will want to fork the main repository, and clone that fork onto the +machine where you'll do the development work. +Ultimately, we want any contribution in the form of a pull request that is on +this code fork *on a separate branch from the main branch*. +If this is unfamiliar terminology, check out +`this git tutorial +`_ +describing how to make a pull request from a fork, and also +`this page about branches +`_. + +After forking the repository, create and activate a development environment as follows:: + + cd xesn + conda env create -f docs/environment.yaml + conda activate xesn + pip install -e . --no-deps + +and you can test that everything went smoothly by running the unittest suite:: + + pytest xesn/test/*.py + +2. Develop Contributions +------------------------ + +Add those awesome contributions to your development branch. +If you are adding a feature to the code base, then make sure to periodically run the test +suite as shown above:: + + cd xesn + conda activate xesn + pytest xesn/test/*.py + +Additionally, we'll want the new developments to have tests and +`docstrings `_ +of their own, so +please consider writing tests and documentation during development. + +If you are adding to the documentation, then you'll want to first verify that +the documentation builds locally in the environment you created:: + + cd xesn/docs + conda activate xesn + make html + +After that, you can open the generated html files to view in your web browser:: + + open build/html/index.html + +Rinse and repeat as you add your documentation :) + +Don't hesitate to +`create an issue `_ +describing the feature or documentation you're interested in adding, and any areas you might like +some help. +We'd be happy to discuss it and help where we can. + +3. Submit a Pull Request +------------------------ + +We recommend doing this on our repository's +`PR webpage +`_ +as outlined `on this page +`_. diff --git a/docs/index.rst b/docs/index.rst index a72f90d..49a64cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,8 @@ most by :cite:t:`platt_systematic_2022`. xesn uses `xarray `_ to handle multi-dimensional data, relying on -`dask `_ for parallelization. +`dask `_ for parallelization and +to handle datasets/networks that are too large for a single compute node. At its core, xesn uses `numpy `_ and `cupy `_ @@ -27,15 +28,31 @@ for efficient CPU and GPU deployment. - .. toctree:: :maxdepth: 1 + :caption: Getting Started installation methods - example_esn_usage - example_lazy_usage - example_macro_training + +.. toctree:: + :maxdepth: 1 + :caption: Examples + + Using the Standard ESN + Using the Parallel ESN + Macro Parameter Optimization + +.. toctree:: + :maxdepth: 1 + :caption: Community + + contributing + support + +.. toctree:: + :maxdepth: 1 + :caption: References + references api - diff --git a/docs/installation.rst b/docs/installation.rst index bd55bf3..a869d28 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -12,7 +12,8 @@ and install it as follows:: cd xesn pip install -e . -Note that additional dependencies can be installed to run the unit test suite:: +Note that additional dependencies can be installed to run the unit test suite +and ensure everything is working properly:: pip install -e .[test] pytest xesn/test/*.py diff --git a/docs/methods.rst b/docs/methods.rst index 97ab555..f115de6 100644 --- a/docs/methods.rst +++ b/docs/methods.rst @@ -167,21 +167,6 @@ each time step "column-wise": and similarly :math:`\mathbf{V} = (\mathbf{v}(1) \, \mathbf{v}(2) \, \cdots \, \mathbf{v}(N_{\text{train}}))`. -Macro-Scale Parameters ----------------------- - -From our experience, the most important macro-scale parameters that must be -specified by the user are the - -- input matrix scaling, :math:`\sigma`, ``input_kwargs["factor"]`` -- adjacency matrix scaling, :math:`\rho`, ``adjacency_kwargs["factor"]`` -- bias vector scaling, :math:`\sigma_b`, ``bias_kwargs["factor"]`` -- Tikhonov parameter, :math:`\beta`, ``tikhonov_parameter`` -- leak rate, :math:`\alpha`, ``leak_rate`` - -See `this example `_ for a demonstration of using the -`surrogate modeling toolbox `_ -to perform Bayesian optimization and find well performing parameter values. Distributed ESN Architecture ############################ @@ -354,3 +339,19 @@ Note that the various macro-scale paramaters Therefore the only components that drive unique hidden states on each chunk are the different input states :math:`\mathbf{u}_k` and the readout matrices :math:`\mathbf{W}_\text{out}^k`. + +Macro-Scale Parameters +###################### + +From our experience, the most important macro-scale parameters that must be +specified by the user are the + +- input matrix scaling, :math:`\sigma`, ``input_kwargs["factor"]`` +- adjacency matrix scaling, :math:`\rho`, ``adjacency_kwargs["factor"]`` +- bias vector scaling, :math:`\sigma_b`, ``bias_kwargs["factor"]`` +- Tikhonov parameter, :math:`\beta`, ``tikhonov_parameter`` +- leak rate, :math:`\alpha`, ``leak_rate`` + +See `this example `_ for a demonstration of using the +`surrogate modeling toolbox `_ +to perform Bayesian optimization and find well performing parameter values. diff --git a/docs/references.rst b/docs/references.rst index 8b1831b..a304330 100644 --- a/docs/references.rst +++ b/docs/references.rst @@ -1,4 +1,4 @@ -References -########## +Scientific References +##################### .. bibliography:: diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000..71f3cae --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,7 @@ +Getting Support +############### + +If you think there is a bug in the code or have any questions about using xesn, +please +`submit an issue `_, +with a sufficient description of the problem or question. diff --git a/pyproject.toml b/pyproject.toml index 8152cf5..eb7f278 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,6 +21,7 @@ gpus = [ ] [project.urls] +homepage="https://github.com/timothyas/xesn" source="https://github.com/timothyas/xesn" documentation="https://xesn.readthedocs.io/en/latest/"