From 1a6235a1e6493c0d0106dd9e00166b6e66e218a4 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 20 Sep 2023 04:02:03 +0100 Subject: [PATCH 1/3] Re-write the installation guide --- Documentation/guides/installation.md | 274 +++++++++------------------ 1 file changed, 94 insertions(+), 180 deletions(-) diff --git a/Documentation/guides/installation.md b/Documentation/guides/installation.md index 5c4bd00de..bc4b440cf 100644 --- a/Documentation/guides/installation.md +++ b/Documentation/guides/installation.md @@ -1,217 +1,131 @@ # HARK installation guide -HARK is an open source project written in Python. It's compatible with both Python -2 and 3, and with the Anaconda distributions of python 2 and 3. +This guide provides a brief overview of how to install HARK on your computer. -## Instructions for a new user +If you're looking to contribute to HARK itself, +see the [contributor's guide]. -In order to use HARK, you firstly need to download Python and add Python to the PATH. We recommend to install python 3, as eventually support for python 2 will end. If you are not confident about the installation process you can use this step-by-step guide https://realpython.com/installing-python/ . +## Set up Python -Next, install a text editor for Python. If you do not use the Anaconda Python distribution (see below), we recommend [Atom](https://atom.io/). To use Atom for Python, first install it (you can use this [manual](https://flight-manual.atom.io/getting-started/sections/installing-atom/)). Next, install the [packages](https://flight-manual.atom.io/using-atom/sections/atom-packages/) for Python, we recommend to install at least [autocomplete-python](https://atom.io/packages/autocomplete-python) and [atom-ide-debugger-python](https://flight-manual.atom.io/using-atom/sections/atom-packages/). The last enables debugging the Python scripts, that is to set breakpoints and call variables in certain spot of your code (with increase in your codes' sophistication you will find this tools very helpful in finding bugs). +In order to use HARK, you firstly need to download and add [Python 3] to the PATH. +If you are not confident about the installation process, +you can use this [step-by-step guide](https://realpython.com/installing-python/). -After installing Python and the text editor, you can install HARK package. The simplest way is to use [pip](https://pip.pypa.io/en/stable/installing/). +If you do not already have a text editor or integrated development environment (IDE) +for Python, we recommend [PyCharm] or [Visual Studio Code]. -To install HARK with pip, at a command line type `pip install econ-ark`. +## Install HARK -If you prefer to isolate the installation of `econ-ark` from the installations of any other python tools and packages, use a virtual environment such as [virtualenv](https://virtualenv.pypa.io/en/latest/). +After installing Python and the text editor, you can install HARK package. +The simplest way is to use [pip]. -To install `virtualenv`, then to create an environment named `econ-ark`, and finally to activate that environment, at a command line type: +1. We first set up a 'virtual environment' for HARK. + This is a way of isolating the installation of HARK so that it does not interfere + with any other Python scripts or modules on your computer. + To do so, at a command line type: -``` -cd [directory where you want to store the econ-ark virtual environment] -pip install virtualenv -virtualenv econ-ark -``` - -Then for Windows, type: - -``` -econ-ark\Scripts\activate.bat - -``` - -While for Mac or Linux: - -``` -source econ-ark/bin/activate -``` + ```console + cd [directory where you want to store the econ-ark virtual environment] + python -m venv econ-ark + ``` + +2. If you get an error, and you use Debian or Ubuntu, + install the full Python package: -In the both cases, you may see (econ-ark) in your command prompt. + ```console + sudo apt-get install --yes python3-full + ``` -Next, install `econ-ark` into your new virtual environment via pip: +3. Activate the virtual environment: -``` -pip install econ-ark -``` + 1. On Unix: + ```console + source econ-ark/bin/activate + ``` ---- + 2. On Windows: -**!NOTE** + ```console + .\econ-ark\Scripts\activate + ``` -If you install econ-ark into the virtual environment, your HARK scripts will not compile unless it is activated. +4. Install HARK into the virtual environment: -To do so, type for Windows: + ```console + pip install econ-ark + ``` -``` -cd [directory where you want to store the econ-ark virtual environment] -econ-ark\Scripts\activate.bat -``` +## Run your script -While for Mac or Linux: +Every time you run an Econ-ARK script, +you need to activate the virtual environment first, as described above. -``` -cd [directory where you want to store the econ-ark virtual environment] -source econ-ark/bin/activate -``` +Then, you can run your script from the command line: -Next, run your script - -``` +```console cd [directory where you located your script] -python YourScript.py +python your_script.py ``` -For using the text editor, you also need to configure the environment. If you use [Atom](https://atom.io/), simply type `atom` at a command prompt after activating the environment. Atom text editor will open and you will be able to compile your codes which use HARK. - ---- - -### Using HARK with Anaconda - -Installing HARK with pip does not give you full access to HARK's many graphical capabilities. One way to access these capabilities is by using [Anaconda](https://anaconda.com/why-anaconda), which is a distribution of python along with many packages that are frequently used in scientific computing. - -1. Download Anaconda for your operating system and follow the installation instructions [at Anaconda.com](https://www.anaconda.com/distribution/#download-section). - ---- - -**!NOTE** - -You can have the default python distribution from python.org and from anaconda, as they do not interfere. However, be careful with setting the PATH. To avoid problems you can eg. set the environment variables path to the default distribution and access anaconda distribution via anaconda prompt. - ---- - -2. Anaconda includes its own virtual environment system called `conda` which stores environments in a preset location (so you don't have to choose). So in order to create and activate an econ-ark virtual environment: - -``` -conda create -n econ-ark anaconda -conda activate econ-ark -``` - -If you want to install `econ-ark` only into this environment, you need to firstly activate the environment and then install econ-ark via pip or conda. In the second case type: - -``` -conda install econ-ark::econ-ark -``` - -About the differences between conda and pip check https://www.anaconda.com/understanding-conda-and-pip/ . - -3. Open Spyder, an interactive development environment (IDE) for Python (specifically, iPython). You may be able to do this through Anaconda's graphical interface, or you can do so from the command line/prompt. To do so, simply open a command line/prompt and type `spyder`. If `econ-ark` is installed into the particular environment, you firstly need activate it and then type `spyder`. - -`spyder` enables debugging the Python scripts, that is to set breakpoints and call variables in certain spot of your code, in order to find bugs (with increase in your codes' sophistication you will find this tools very helpful). - -4. To verify that `spyder` has access to HARK try typing `pip install econ-ark` into the iPython shell within Spyder. If you have successfully installed HARK as above, you should see a lot of messages saying 'Requirement satisfied'. - - - If that doesn't work, you will need to manually add HARK to your Spyder environment. To do this, you'll need to get the code from Github and import it into Spyder. To get the code from Github, you can either clone it or download a zipped file. - - - If you have `git` installed on the command line, type `git clone git@github.com:econ-ark/HARK.git` in your chosen directory ([more details here](https://git-scm.com/doc)). If you get a permission denied error, you may need to setup SSH for GitHub, or you can clone using HTTPS: 'git clone https://github.com/econ-ark/HARK.git'. - - - If you do not have `git` available on your computer, you can download the [GitHub Desktop app](https://desktop.github.com/) and use it to make a local clone. - - - If you don't want to clone HARK, but just to download it, go to [the HARK repository on GitHub](https://github.com/econ-ark/HARK). In the upper righthand corner is a button that says "clone or download". Click the "Download Zip" option and then unzip the contents into your chosen directory. - - Once you've got a copy of HARK in a directory, return to Spyder and navigate to that directory where you put HARK. This can be done within Spyder by doing `import os` and then using `os.chdir()` to change directories. `chdir` works just like cd at a command prompt on most operating systems, except that it takes a string as input: `os.chdir('Music')` moves to the Music subdirectory of the current working directory. Alternatively, you can install `econ-ark` from the local repository by navigating to that directory where you put HARK and then typing at the command line: - - ``` - pip install -e . - ``` - ## Content Aside from the Toolkit -If you don't already have one, you should designate a place on your computer where you will be putting all the Econ-ARK content. -For example, it is common to just create a folder `GitHub` in your home user directory. Inside `GitHub` you should create folders -corresponding to the GitHub ID's of users whose work you want to obtain; for example, `GitHub/econ-ark`. Inside the `econ-ark` directory you can obtain a number of different resources. +If you don't already have one, you should designate a place on your computer +where you will be putting all the Econ-ARK content. +For example, you could create an `econ-ark` folder within your home directory. ### Demonstrations And Illustrations -Most of the modules in HARK are just collections of tools. To look at a demonstrations, check repository: \* [DemARK](https://github.com/econ-ark/DemARK): Demonstrations of the use of HARK +Most of the modules in HARK are just collections of tools. +To look at a demonstrations, see the [DemARK] and [REMARK] repositories. -You will want to obtain your own local copy of these repos using: +You will want to obtain your own local copy of these repositories using: +```console +git clone https://github.com/econ-ark/DemARK +git clone https://github.com/econ-ark/REMARK ``` -git clone https://github.com/econ-ark/DemARK.git -``` - -Once you have downloaded them, you will find that the repo contains a `notebooks` directory that contains a number of [jupyter notebooks](https://jupyter.org/). If you have the jupyter notebook tool installed (it is installed as part of Anaconda), you should be able to launch the jupyter notebook app from the command line with the command: - -### [REMARK](https://github.com/econ-ark/REMARK/#readme): Replications and Examples Made Using the ARK - -From inside the `GitHub/econ-ark` directory, you will want to obtain your own local copy of the REMARK repo: - -``` -git clone https://github.com/econ-ark/REMARK.git -``` - -Once the download finishes (it should have created `GitHub/econ-ark/REMARK`, change into that directory. -Its root level is mostly descriptive; the main content is in the `REMARKs` subdirectory, so `cd REMARKs` to -have a look at what is there. Each REMARK is contained in a directory with the handle of the REMARK; -for example, `BufferStockTheory` is the handle for the REMARK on 'The Theoretical Foundations of Buffer Stock Saving'. -At the top level of the directory for each REMARK we have some meta-information (title, authors, etc) and an eponymous Jupyter notebook, e.g. `BufferStockTheory.ipynb.` In most cases there will also be an subdirectory, e.g. `BufferStockTheory` which is a placeholder for the substantive content of the project (like, the original paper). +Once downloaded, you will find that the repo contains a `notebooks` directory +that contains a number of [jupyter notebooks]. +If you have the jupyter notebook tool installed (`pip install jupyter`), +you should be able to launch the jupyter notebook app from the command line with the command: -- Until a REMARK is finalized and frozen, the original content is often kept somewhere else, e.g.\ in an author's GitHub repo. In this case, the REMARK repo uses a `submodule` version, which is sort of like a link to the original material. To save space, a regular 'clone' of the REMARK repo does not incorporate all the submodules; therefore you may find those folders empty when you first use them. In order to obtain the **real** content, in the root directory of the repo in question (e.g., in REMARKs/BufferStockTheory), you need execute the command `git submodule update --recursive --remote`. - -Once you have downloaded them, you will find that the repo contains a `notebooks` directory that contains a number of [jupyter notebooks](https://jupyter.org/). If you have the jupyter notebook tool installed (it is installed as part of Anaconda), you should be able to launch the jupyter notebook app from the command line with the command: - -``` +```console jupyter notebook ``` -If you installed the econ-ark into the particular environment, activate it first and then type `jupyter notebook`. - -## Instructions for an advanced user/developer - -If you want to make changes or contributions (yay!) to HARK, you'll need to have access to the source files. Installing HARK via pip (either at the command line, or inside Spyder) makes it hard to access those files (and it's a bad idea to mess with the original code anyway because you'll likely forget what changes you made). If you are adept at GitHub, you can [fork](https://help.github.com/en/articles/fork-a-repo) the repo. If you are less experienced, you should download a personal copy of HARK again using `git clone` (see part for a new user) or the GitHub Desktop app. - -1. Navigate to wherever you want to put the repository and type `git clone git@github.com:econ-ark/HARK.git` ([more details here](https://git-scm.com/doc)). If you get a permission denied error, you may need to setup SSH for GitHub, or you can clone using HTTPS: 'git clone https://github.com/econ-ark/HARK.git'. - -2. Then, create and activate a [virtual environment](https://virtualenv.pypa.io/en/latest/). - -Install virtualenv if you need to and then type: - -``` -virtualenv econ-ark -source econ-ark/bin/activate -``` - -For Windows: - -``` -virtualenv econ-ark -econ-ark\Scripts\activate.bat -``` - -4. Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`. - -5. Install locally the econ-ark: navigate to your local repository and then type: - -``` -pip install -e . -``` - -5. To check that everything has been set up correctly, run HARK's tests with `python -m unittest`. - ---- - -**!NOTE** - -To check the package performance with your local changes, use the same command from the command line (after navigating to your HARK directory): - -``` -pip install -e . -``` - -If for some reason you want to switch back to the PyPI version: - -``` -pip uninstall econ-ark -pip install econ-ark (options) -``` +### [REMARK]: Replications and Examples Made Using the ARK + +To explore the [REMARK]s, enter the `REMARK` directory that contains the cloned +repository from the step above. The root level is mostly descriptive. + +The main content is in the `REMARKs` subdirectory, +so `cd REMARKs` to have a look at what is there. +Each REMARK is contained in a directory with the handle of the REMARK; +for example, `BufferStockTheory` is the handle for the REMARK on +'*The Theoretical Foundations of Buffer Stock Saving*'. + +At the top level of the directory for each REMARK we have some meta-information +(title, authors, etc) and an eponymous Jupyter notebook, e.g. `BufferStockTheory.ipynb.` +In most cases there will also be a subdirectory, e.g. `BufferStockTheory` +which is a placeholder for the substantive content of the project (like, the original paper). + +Until a REMARK is finalized and frozen, the original content is often kept somewhere else, +e.g. in an author's GitHub repo. +In this case, the REMARK repo uses a `submodule` version, +which is sort of like a link to the original material. +To save space, a regular 'clone' of the REMARK repo does not incorporate all the submodules; +therefore you may find those folders empty when you first use them. +In order to obtain the **real** content, in the root directory of the repo in question +(e.g., in `REMARKs/BufferStockTheory`), you need execute the command +`git submodule update --recursive --remote`. + + +[Python 3]: https://www.python.org/downloads/ +[PyCharm]: https://www.jetbrains.com/help/pycharm/quick-start-guide.html +[Visual Studio Code]: https://code.visualstudio.com/learn/get-started/basics +[pip]: https://pip.pypa.io/en/stable/installing/ +[DemARK]: https://github.com/econ-ark/DemARK +[jupyter notebooks]: https://jupyter.org/ +[REMARK]: https://github.com/econ-ark/REMARK/#readme +[contributor's guide]: https://docs.econ-ark.org/guides/contributing.html From d21e95d77df8e62a21f3ff6f7dd1bf6d0e601613 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 28 Dec 2023 04:26:24 +0000 Subject: [PATCH 2/3] Switch to conda --- Documentation/guides/installation.md | 37 +++++++++------------------- 1 file changed, 11 insertions(+), 26 deletions(-) diff --git a/Documentation/guides/installation.md b/Documentation/guides/installation.md index bc4b440cf..58a61639f 100644 --- a/Documentation/guides/installation.md +++ b/Documentation/guides/installation.md @@ -17,48 +17,33 @@ for Python, we recommend [PyCharm] or [Visual Studio Code]. ## Install HARK After installing Python and the text editor, you can install HARK package. -The simplest way is to use [pip]. +The simplest way is to use [conda]. -1. We first set up a 'virtual environment' for HARK. +1. We first set up a Conda 'environment' for HARK. This is a way of isolating the installation of HARK so that it does not interfere with any other Python scripts or modules on your computer. To do so, at a command line type: ```console - cd [directory where you want to store the econ-ark virtual environment] - python -m venv econ-ark + $ conda create -n econ-ark ``` - -2. If you get an error, and you use Debian or Ubuntu, - install the full Python package: + +2. Activate the environment: ```console - sudo apt-get install --yes python3-full + $ conda activate econ-ark ``` -3. Activate the virtual environment: - - 1. On Unix: - ```console - source econ-ark/bin/activate - ``` - - 2. On Windows: - - ```console - .\econ-ark\Scripts\activate - ``` - -4. Install HARK into the virtual environment: +3. Install HARK into the environment: ```console - pip install econ-ark + (econ-ark) $ conda install econ-ark ``` ## Run your script Every time you run an Econ-ARK script, -you need to activate the virtual environment first, as described above. +you need to activate the environment first, as described above. Then, you can run your script from the command line: @@ -87,7 +72,7 @@ git clone https://github.com/econ-ark/REMARK Once downloaded, you will find that the repo contains a `notebooks` directory that contains a number of [jupyter notebooks]. -If you have the jupyter notebook tool installed (`pip install jupyter`), +If you have the jupyter notebook tool installed (`conda install jupyter`), you should be able to launch the jupyter notebook app from the command line with the command: ```console @@ -124,7 +109,7 @@ In order to obtain the **real** content, in the root directory of the repo in qu [Python 3]: https://www.python.org/downloads/ [PyCharm]: https://www.jetbrains.com/help/pycharm/quick-start-guide.html [Visual Studio Code]: https://code.visualstudio.com/learn/get-started/basics -[pip]: https://pip.pypa.io/en/stable/installing/ +[conda]: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html [DemARK]: https://github.com/econ-ark/DemARK [jupyter notebooks]: https://jupyter.org/ [REMARK]: https://github.com/econ-ark/REMARK/#readme From 068f8e98b1de74e2c24c864ae5a09d231be7913e Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 28 Dec 2023 05:45:31 +0000 Subject: [PATCH 3/3] Whitespace --- Documentation/guides/installation.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Documentation/guides/installation.md b/Documentation/guides/installation.md index 58a61639f..343bb72b3 100644 --- a/Documentation/guides/installation.md +++ b/Documentation/guides/installation.md @@ -19,7 +19,7 @@ for Python, we recommend [PyCharm] or [Visual Studio Code]. After installing Python and the text editor, you can install HARK package. The simplest way is to use [conda]. -1. We first set up a Conda 'environment' for HARK. +1. We first set up a Conda 'environment' for HARK. This is a way of isolating the installation of HARK so that it does not interfere with any other Python scripts or modules on your computer. To do so, at a command line type: @@ -85,13 +85,13 @@ To explore the [REMARK]s, enter the `REMARK` directory that contains the cloned repository from the step above. The root level is mostly descriptive. The main content is in the `REMARKs` subdirectory, -so `cd REMARKs` to have a look at what is there. +so `cd REMARKs` to have a look at what is there. Each REMARK is contained in a directory with the handle of the REMARK; for example, `BufferStockTheory` is the handle for the REMARK on -'*The Theoretical Foundations of Buffer Stock Saving*'. +'_The Theoretical Foundations of Buffer Stock Saving_'. At the top level of the directory for each REMARK we have some meta-information -(title, authors, etc) and an eponymous Jupyter notebook, e.g. `BufferStockTheory.ipynb.` +(title, authors, etc) and an eponymous Jupyter notebook, e.g. `BufferStockTheory.ipynb.` In most cases there will also be a subdirectory, e.g. `BufferStockTheory` which is a placeholder for the substantive content of the project (like, the original paper). @@ -101,11 +101,10 @@ In this case, the REMARK repo uses a `submodule` version, which is sort of like a link to the original material. To save space, a regular 'clone' of the REMARK repo does not incorporate all the submodules; therefore you may find those folders empty when you first use them. -In order to obtain the **real** content, in the root directory of the repo in question +In order to obtain the **real** content, in the root directory of the repo in question (e.g., in `REMARKs/BufferStockTheory`), you need execute the command `git submodule update --recursive --remote`. - [Python 3]: https://www.python.org/downloads/ [PyCharm]: https://www.jetbrains.com/help/pycharm/quick-start-guide.html [Visual Studio Code]: https://code.visualstudio.com/learn/get-started/basics