From 0425c1061219c3ce09d0d944cff4c235530e5320 Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 16:31:31 -0400 Subject: [PATCH 01/10] initial commit --- docs/source/{contribute.rst => installation.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/{contribute.rst => installation.rst} (100%) diff --git a/docs/source/contribute.rst b/docs/source/installation.rst similarity index 100% rename from docs/source/contribute.rst rename to docs/source/installation.rst From 269785cf07ba9b904bbfdd5997b4b6d0c6bd55c1 Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 16:36:54 -0400 Subject: [PATCH 02/10] update getting-started page --- docs/source/getting-started.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 1b2489b6..5578b774 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -9,7 +9,7 @@ Installation .. _install: -If you are working windows, you need to first install PyTorch with +If you are working Windows, you need to first install PyTorch with ``pip install torch -f https://download.pytorch.org/whl/torch_stable.html``. @@ -18,14 +18,15 @@ Otherwise, you can proceed with ``pip install pytorch-forecasting`` -Alternatively, to installl the package via conda: +Alternatively, to install the package via ``conda``: ``conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge`` PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. To use the MQF2 loss (multivariate quantile loss), also install -`pip install pytorch-forecasting[mqf2]` + +``pip install pytorch-forecasting[mqf2]`` Usage From 52665de7d8b382c7d74c74dcf8d5848e0a24a897 Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 17:55:39 -0400 Subject: [PATCH 03/10] removed contribute and replaced with installation --- docs/source/index.rst | 2 +- docs/source/installation.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b833f4b..6bfcc349 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -66,7 +66,7 @@ The :ref:`Tutorials ` section provides guidance on how to use models models metrics faq - contribute + installation api CHANGELOG diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 09765c01..be4f0edb 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,5 +1,5 @@ -Contribute -========== +Installation +============ Contributions to PyTorch Forecasting are very welcome! You do not have to be an expert in deep learning to contribute. If you find a bug - fix it! If you miss a feature - propose it! From e38e3723b25d55cb61eeab88a4586b889c104aeb Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 19:07:23 -0400 Subject: [PATCH 04/10] added installation page --- docs/source/installation.rst | 178 +++++++++++++++++++++++++++++++++-- 1 file changed, 168 insertions(+), 10 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index be4f0edb..23824028 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -1,25 +1,179 @@ Installation ============ +``pytorch-forecasting`` currently supports: + +* Python versions 3.8, 3.9, 3.10, 3.11, and 3.12. +* Operating systems : ... ... and ... + +Installing pytorch-forecasting +------------------------------ + +``pytorch-forecasting`` is a library build off of the popular deep learning framework ``pytorch`` and +heavily uses the Pytorch Lightning library ``lightning`` for ease of training and multiple GPU usage. + +You'll need to install ``pytorch`` along or before with ``pytorch-forecasting`` in order to get a working +install of this library. + +If you are working Windows, you can install PyTorch with + +.. code-block:: bash + + pip install torch -f https://download.pytorch.org/whl/torch_stable.html + +.. note:: + It is recommended to visit the Pytorch official page https://pytorch.org/get-started/locally/#start-locally to + figure out which version of ``pytorch`` best suits your machine if you are + unfamiliar with the library. + +Otherwise, you can proceed with: + +.. code-block:: bash + pip install pytorch-forecasting + + +Alternatively, to install the package via ``conda``: +.. code-block:: bash + conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge + +PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. + +To install ``pytorch-forecasting`` with the use of the MQF2 loss (multivariate quantile loss), run: +.. code-block:: bash + pip install pytorch-forecasting[mqf2] + + +To install the Pytorch Lightning library, please visit their `official page `__ or run: + +.. code-block:: bash + pip install lightning + + +Obtaining a latest ``pytorch-forecasting`` version +-------------------------------------------------- + +This type of installation obtains a latest static snapshot of the repository, with +various features that are not published in a release. It is mainly intended for developers +that wish to build or test code using a version of the repository that contains +all of the latest or current updates. + +.. code-block:: bash + + pip install git+https://github.com/sktime/pytorch-forecasting.git + + +To install from a specific branch, use the following command: + +.. code-block:: bash + + pip install git+https://github.com/sktime/pytorch-forecasting.git@ + + +Contributing to ``pytorch-forecasting`` +--------------------------------------- + Contributions to PyTorch Forecasting are very welcome! You do not have to be an expert in deep learning to contribute. If you find a bug - fix it! If you miss a feature - propose it! -Contribution guidelines ------------------------- +To obtain an editible version ``pytorch-forecasting`` for development or contributions, +you will need to set up: + +* a local clone of the ``pytorch-forecasting`` repository. +* a virtual environment with an editable install of ``pytorch-forecasting`` and the developer dependencies. + +The following steps guide you through the process: + +1. Follow the Git workflow: + +Creating a fork and cloning the repository - initial one time setup +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Fork the `project + repository `__ by + clicking on the 'Fork' button near the top right of the page. This + creates a copy of the code under your GitHub user account. For more + details on how to fork a repository see `this + guide `__. + +2. `Clone `__ + your fork of the pytorch-forecasting repo from your GitHub account to your local + disk: + + .. code:: bash + + git clone git@github.com:/sktime/pytorch-forecasting.git + cd pytorch-forecasting + + where :code:`` is your GitHub username. + +3. Configure and link the remote for your fork to the upstream + repository: + + .. code:: bash + + git remote -v + git remote add upstream https://github.com/sktime/pytorch-forecasting.git + +4. Verify the new upstream repository you've specified for your fork: + + .. code:: bash + + git remote -v + > origin https://github.com//sktime/pytorch-forecasting.git (fetch) + > origin https://github.com//sktime/pytorch-forecasting.git (push) + > upstream https://github.com/sktime/pytorch-forecasting.git (fetch) + > upstream https://github.com/sktime/pytorch-forecasting.git (push) + +2. Set up a new virtual environment. Our instructions will go through the commands to set up a ``conda`` environment which is recommended for ``pytorch-forecasting`` development. +The process will be similar for ``venv`` or other virtual environment managers. + + .. warning:: + Using ``conda`` via one of the commercial distributions such as Anaconda + is in general not free for commercial use and may incur significant costs or liabilities. + Consider using free distributions and channels for package management, + and be aware of applicable terms and conditions. + +In the ``conda`` terminal: + +3. Navigate to your local pytorch-forecasting folder, :code:`cd pytorch-forecasting` or similar + +4. Create a new environment with a supported python version: :code:`conda create -n pytorch-forecasting-dev python=3.11` (or :code:`python=3.12` etc) + + .. warning:: + If you already have an environment called ``pytorch-forecasting-dev`` from a previous attempt you will first need to remove this. + +5. Activate the environment: :code:`conda activate pytorch-forecasting-dev` + +6. Build an editable version of pytorch-forecasting. +In order to install only the dev dependencies, :code:`pip install -e ".[dev]"` +If you also want to install soft dependencies, install them individually, after the above, +or instead use: :code:`pip install -e ".[all_extras,dev]"` to install all of them. + +Contribution Guidelines and Recommendations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To ensure that maintainers and other developers are able to help your issues or +review your contributions/pull requests, please read the following guidelines below. * Open issues to discuss your proposed changes before starting pull requests. - This ensures that your contribution will be swiftly integrated into the code base. + This ensures that other developers or maintainers have adequete context/knowledge + about your future contribution so that it can be swiftly integrated into the code base. -* Mark your PR with ``ready for review`` to indicate that you are done with it and - request the maintainers to have a look. +* Adding context tags to the PR title. + This will greatly help categorize different types of pull requests without having + to look at the full title. Usually tags that start with either [ENH] - Enhancement: + adding a feature, or improving code, [BUG] - Bugfixes, [MNT] - CI: test framework, [DOC] - + Documentation: writing or improving documentation or docstrings. -* To contribute, fork and clone the repository, install depdencies with ``poetry install``, - create a new branch from master such as ``feature/my_new_awesome_model``, write your code - and create the PR on GitHub. +* Adding references to other links or pull requests + This helps to add context about previous or current issues/prs that relate to + your contribution. This is done usually by including a full link or a hash tag '#1234'. +Technical Design Principles +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Design principles ------------------- +When writing code for your new feature, it is recommended to follow these +technical design principles to ensure compatability between the feature and the library. * Backward compatible API if possible to prevent breaking code. * Powerful abstractions to enable quick experimentation. At the same time, the abstractions should @@ -28,4 +182,8 @@ Design principles * Focus on forecasting time-related data - specificially timeseries regression and classificiation. Contributions not directly related to this topic might not be merged. We want to keep the library as crisp as possible. +* Install ``pre-commit`` and have it run on every commit that you make on your feature branches. + This library requires strict coding and development best practices to ensure the highest code quality. + Contributions or pull requests that do not adhere to these standards will not likely be merged until fixed. + For more information on ``pre-commit`` you can visit `this page `__ * Always add tests and documentation to new features. From 410f5032a669dd15bdfa4f15dfa303d847c0b942 Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 19:12:39 -0400 Subject: [PATCH 05/10] updates to installation page --- docs/source/installation.rst | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 23824028..7df65525 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -83,10 +83,8 @@ you will need to set up: The following steps guide you through the process: -1. Follow the Git workflow: - -Creating a fork and cloning the repository - initial one time setup -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Creating a fork and cloning the repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Fork the `project repository `__ by @@ -124,7 +122,10 @@ Creating a fork and cloning the repository - initial one time setup > upstream https://github.com/sktime/pytorch-forecasting.git (fetch) > upstream https://github.com/sktime/pytorch-forecasting.git (push) -2. Set up a new virtual environment. Our instructions will go through the commands to set up a ``conda`` environment which is recommended for ``pytorch-forecasting`` development. +Setting up an editible virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Set up a new virtual environment. Our instructions will go through the commands to set up a ``conda`` environment which is recommended for ``pytorch-forecasting`` development. The process will be similar for ``venv`` or other virtual environment managers. .. warning:: @@ -135,22 +136,25 @@ The process will be similar for ``venv`` or other virtual environment managers. In the ``conda`` terminal: -3. Navigate to your local pytorch-forecasting folder, :code:`cd pytorch-forecasting` or similar +2. Navigate to your local pytorch-forecasting folder, :code:`cd pytorch-forecasting` or similar -4. Create a new environment with a supported python version: :code:`conda create -n pytorch-forecasting-dev python=3.11` (or :code:`python=3.12` etc) +3. Create a new environment with a supported python version: :code:`conda create -n pytorch-forecasting-dev python=3.11` (or :code:`python=3.12` etc) .. warning:: If you already have an environment called ``pytorch-forecasting-dev`` from a previous attempt you will first need to remove this. -5. Activate the environment: :code:`conda activate pytorch-forecasting-dev` +4. Activate the environment: :code:`conda activate pytorch-forecasting-dev` -6. Build an editable version of pytorch-forecasting. +5. Build an editable version of pytorch-forecasting. In order to install only the dev dependencies, :code:`pip install -e ".[dev]"` If you also want to install soft dependencies, install them individually, after the above, or instead use: :code:`pip install -e ".[all_extras,dev]"` to install all of them. Contribution Guidelines and Recommendations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------- + +Submitting pull request best practices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ensure that maintainers and other developers are able to help your issues or review your contributions/pull requests, please read the following guidelines below. From fe763822b308829596acb80b22d9712c248735fa Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 20:05:10 -0400 Subject: [PATCH 06/10] fix bugs --- docs/source/installation.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 7df65525..e6a7e6f9 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -19,7 +19,7 @@ If you are working Windows, you can install PyTorch with .. code-block:: bash - pip install torch -f https://download.pytorch.org/whl/torch_stable.html + pip install torch -f https://download.pytorch.org/whl/torch_stable.html .. note:: It is recommended to visit the Pytorch official page https://pytorch.org/get-started/locally/#start-locally to @@ -29,24 +29,25 @@ If you are working Windows, you can install PyTorch with Otherwise, you can proceed with: .. code-block:: bash - pip install pytorch-forecasting + pip install pytorch-forecasting Alternatively, to install the package via ``conda``: .. code-block:: bash - conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge + conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. To install ``pytorch-forecasting`` with the use of the MQF2 loss (multivariate quantile loss), run: + .. code-block:: bash - pip install pytorch-forecasting[mqf2] + pip install pytorch-forecasting[mqf2] To install the Pytorch Lightning library, please visit their `official page `__ or run: .. code-block:: bash - pip install lightning + pip install lightning Obtaining a latest ``pytorch-forecasting`` version From 973b6ff1d353b4d087c8c116beaf93a91bbc7a9d Mon Sep 17 00:00:00 2001 From: julian fong Date: Mon, 28 Oct 2024 21:43:11 -0400 Subject: [PATCH 07/10] fix bugs --- docs/source/installation.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index e6a7e6f9..b134111b 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -29,11 +29,13 @@ If you are working Windows, you can install PyTorch with Otherwise, you can proceed with: .. code-block:: bash + pip install pytorch-forecasting Alternatively, to install the package via ``conda``: .. code-block:: bash + conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. @@ -41,12 +43,14 @@ PyTorch Forecasting is now installed from the conda-forge channel while PyTorch To install ``pytorch-forecasting`` with the use of the MQF2 loss (multivariate quantile loss), run: .. code-block:: bash + pip install pytorch-forecasting[mqf2] To install the Pytorch Lightning library, please visit their `official page `__ or run: .. code-block:: bash + pip install lightning From 55ac23165d101d48205bf77ae2b2b7d838411aa8 Mon Sep 17 00:00:00 2001 From: julian fong Date: Fri, 1 Nov 2024 10:53:24 -0400 Subject: [PATCH 08/10] replcaed code snippets with code blocks --- docs/source/getting-started.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 5578b774..bcefc069 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -11,22 +11,29 @@ Installation If you are working Windows, you need to first install PyTorch with -``pip install torch -f https://download.pytorch.org/whl/torch_stable.html``. +.. code-block:: bash + + pip install torch -f https://download.pytorch.org/whl/torch_stable.html Otherwise, you can proceed with +.. code-block:: bash -``pip install pytorch-forecasting`` + pip install pytorch-forecasting Alternatively, to install the package via ``conda``: -``conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge`` +.. code-block:: bash + + conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. To use the MQF2 loss (multivariate quantile loss), also install -``pip install pytorch-forecasting[mqf2]`` +.. code-block:: bash + + pip install pytorch-forecasting[mqf2] Usage From 81ffaa974306818a982120157913031d6424e108 Mon Sep 17 00:00:00 2001 From: julian fong Date: Fri, 1 Nov 2024 11:07:40 -0400 Subject: [PATCH 09/10] updates --- docs/source/getting-started.rst | 1 + docs/source/installation.rst | 9 +++++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index bcefc069..c22f6911 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -16,6 +16,7 @@ If you are working Windows, you need to first install PyTorch with pip install torch -f https://download.pytorch.org/whl/torch_stable.html Otherwise, you can proceed with + .. code-block:: bash pip install pytorch-forecasting diff --git a/docs/source/installation.rst b/docs/source/installation.rst index b134111b..59ed7eee 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -4,12 +4,12 @@ Installation ``pytorch-forecasting`` currently supports: * Python versions 3.8, 3.9, 3.10, 3.11, and 3.12. -* Operating systems : ... ... and ... +* Operating systems : Linux, macOS, and Windows Installing pytorch-forecasting ------------------------------ -``pytorch-forecasting`` is a library build off of the popular deep learning framework ``pytorch`` and +``pytorch-forecasting`` is a library built on top of the popular deep learning framework ``pytorch`` and heavily uses the Pytorch Lightning library ``lightning`` for ease of training and multiple GPU usage. You'll need to install ``pytorch`` along or before with ``pytorch-forecasting`` in order to get a working @@ -34,9 +34,10 @@ Otherwise, you can proceed with: Alternatively, to install the package via ``conda``: + .. code-block:: bash - conda install pytorch-forecasting pytorch>=1.7 -c pytorch -c conda-forge + conda install pytorch-forecasting pytorch>=2.0.0 -c pytorch -c conda-forge PyTorch Forecasting is now installed from the conda-forge channel while PyTorch is install from the pytorch channel. @@ -174,7 +175,7 @@ review your contributions/pull requests, please read the following guidelines be adding a feature, or improving code, [BUG] - Bugfixes, [MNT] - CI: test framework, [DOC] - Documentation: writing or improving documentation or docstrings. -* Adding references to other links or pull requests +* Adding references to other links or pull requests. This helps to add context about previous or current issues/prs that relate to your contribution. This is done usually by including a full link or a hash tag '#1234'. From 4b7cc443c40f59a0785be4c9090eaf9ce95c8674 Mon Sep 17 00:00:00 2001 From: julian fong Date: Sun, 10 Nov 2024 21:38:30 -0500 Subject: [PATCH 10/10] updated install command --- docs/source/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 59ed7eee..a751a713 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -30,7 +30,7 @@ Otherwise, you can proceed with: .. code-block:: bash - pip install pytorch-forecasting + pip install pytorch-forecasting --extra-index-url https://download.pytorch.org/whl/cpu Alternatively, to install the package via ``conda``: