Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Changes to quick-start guide #1366

Merged
merged 7 commits into from
Apr 18, 2024
Merged

Changes to quick-start guide #1366

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
eef05c4
Changes to quick-start guide
sidd3888 Dec 26, 2023
e145c51
indent fix
sidd3888 Dec 26, 2023
ead8be4
indent fix 2
sidd3888 Dec 26, 2023
bcebcb3
indent fix 3
sidd3888 Dec 27, 2023
d50b832
Update Documentation/guides/quick_start.md
alanlujan91 Mar 2, 2024
ffb7fd6
Update Documentation/guides/quick_start.md
alanlujan91 Mar 2, 2024
ab835cf
organizational changes to quick start
sidd3888 Mar 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 36 additions & 68 deletions Documentation/guides/quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,77 +2,64 @@

## Installing HARK

HARK is an open source project that is compatible with Python 3.

### Installing HARK with pip
HARK is an open source project that is compatible with Python 3. Currently, we recommend using version 3.10 or lower.
alanlujan91 marked this conversation as resolved.
Show resolved Hide resolved

The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installation/).

To install HARK with pip, at a command line type `pip install econ-ark`.

(If you want to install a release that is not the default stable release, for instance if you want to install a development release, you'll need to use a "pinned" release number: `pip install econ-ark==0.10.1.dev1`, substituting "0.10.1.dev1" for your desired release number.)

If you are installing via pip, we recommend using a virtual environment such as [virtualenv](https://virtualenv.pypa.io/en/latest/). Creation of a virtual environment isolates the installation of `econ-ark` from the installations of any other python tools and packages.
Before installing HARK, we recommend creating a new virtual environment, which isolates the installation of `econ-ark` from the installations of any other Python tools and packages, thus avoiding conflicts.
alanlujan91 marked this conversation as resolved.
Show resolved Hide resolved

To install `virtualenv`, then to create an environment named `econ-ark`, and finally to activate that environment:
To create a new virtual environment, enter this in your command line:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we ought recommend conda, perhaps replace the rest of this sub-section with the following?

To create a new environment, follow the steps below in your command line:

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
   $ conda create -n econ-ark "python=3.10"
   ```

2. Activate the environment:

   ```console
   $ conda activate econ-ark
   ```

3. Install HARK into the environment:

   ```console
   (econ-ark) $ conda install econ-ark
   ```

I'd also consider remove the line about installing a non-default release, I'm unsure if it fits in the quick-start guide.


```
cd [directory where you want to store the econ-ark virtual environment]
pip install virtualenv
virtualenv econ-ark
source econ-ark/bin/activate
python -m venv econ-ark
```

---

### Using HARK with Anaconda
On Windows, type:

If you intend ever to use the toolkit for anything other than running the precooked material we have provided, you should probably install [Anaconda](https://anaconda.com/), which will install 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).
```
econ-ark\Scripts\activate
```

1. 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:
On Mac or Linux:

```
conda create -n econ-ark anaconda
conda activate econ-ark
conda install -c conda-forge econ-ark
source econ-ark/bin/activate
```

1. 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`.

1. 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'.
Then use `pip install econ-ark` to install HARK in this environment.

- 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.
Alternatively, if you are using either the [Anaconda](https://anaconda.com/) distribution or [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/), you can create a virtual environment using `conda`, which eliminates the need to manage the environment's location:

- If you have `git` installed on the command line, type `git clone [email protected]:econ-ark/HARK.git` in your chosen directory ([more details here](https://git-scm.com/doc)).
```
conda create -n econ-ark python=3.10
conda activate econ-ark
pip install econ-ark
```

- 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 want to install a release that is not the default stable release, for instance if you want to install a development release, you'll need to use a "pinned" release number: `pip install econ-ark==0.10.1.dev1`, substituting "0.10.1.dev1" for your desired release number.)

- 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.
### Demonstrations on using HARK
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sub-section should go within "Learning HARK" below


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.
Most of the modules in HARK are just collections of tools. There are a few demonstrations/applications that use the tools that you automatically get when you install HARK -- they are available in [Overview & Examples](https://docs.econ-ark.org/overview/index.html). A much larger set of uses of HARK can be found at two repositories:

6) Most of the modules in HARK are just collections of tools. There are a few demonstration
applications that use the tools that you automatically get when you install HARK -- they are listed in the sidebar at the left. A much larger set of uses of HARK can be found at two repositories:
_ [DemARK](https://github.com/econ-ark/DemARK): Demonstrations of the use of HARK
_ [REMARK](https://github.com/econ-ark/REMARK): Replications of existing papers made using HARK
- [DemARK](https://github.com/econ-ark/DemARK): Demonstrations of the use of HARK
- [REMARK](https://github.com/econ-ark/REMARK): Replications of existing papers made using HARK

You will want to obtain your own local copy of these repos using:

```
git clone https://github.com/econ-ark/DemARK.git
git clone https://github.com/econ-ark/REMARK.git
```

and similarly for the REMARK repo. Once you have downloaded them, you will find that each 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:
Once you have downloaded them, you will find that each repo contains a `notebooks` directory that contains a number of [jupyter notebooks](https://jupyter.org/). You can either view them in your integrated development environment (IDE) -- such as [VS Code](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/pycharm/) -- or if you have `jupyter` installed, launch the Jupyter notebook tool using the command line:

```
cd [directory containing the repository]
jupyter notebook
```

and from there you can open the notebooks and execute them.

## Learning HARK

We have a set of 30-second [Elevator Spiels](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#capsule-summaries-of-what-the-econ-ark-project-is) describing the project, tailored to people with several different kinds of background.
Expand Down Expand Up @@ -103,44 +90,25 @@ The most broadly applicable advice is to go to [Econ-ARK](https://econ-ark.org)

## Making changes to HARK
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Arguably this doesn't belong in the quick-start guide -- perhaps just redirect to the contributing guide?


If you want to make changes or contributions to HARK, you'll need to have access to the source files. Installing HARK via `pip install econ-ark` (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 above) or the GitHub Desktop app.

### Clone HARK

Navigate to wherever you want to put the repository and type `git clone [email protected]: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`.

### (Optionally) Create a virtual environment
_For detailed instructions, refer to our [contributing guide](https://docs.econ-ark.org/guides/contributing.html)._

If you are familiar with [virtual environments](https://virtualenv.pypa.io/en/latest/), you can optionally create and activate a virtual environment which will isolate the econ-ark specific tools from the rest of your computer.
If you want to make changes or contributions to HARK, you'll need to have access to the source files. Installing HARK via `pip` makes it hard to access these files. If you are adept at GitHub, you can [fork](https://help.github.com/en/articles/fork-a-repo) the repository. If you are less experienced, you should download a personal copy of HARK again using `git clone https://github.com/econ-ark/HARK.git` or the GitHub Desktop app.

For Mac or Linux:
As described above, it is advisable to use a virtual environment even when making changes to HARK. Follow the instructions provided previously to create and activate a virtual environment.

- Install virtualenv if you need to and then type:

```
virtualenv econ-ark
source econ-ark/bin/activate
```
### Install requirements

- For Windows:
Once you have created a local copy of the repository, install requirements as follows:

```
virtualenv econ-ark
econ-ark\\Scripts\\activate.bat
cd [to where the repository was stored]/HARK/requirements
pip install -r base.txt
pip install -r dev.txt
pip install -r doc.txt
```

Once the virtualenv is activated, you may see `(econ-ark)` in your command prompt (depending on how your machine is configured)

### Install requirements

Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`.

### Test your installation

To check that everything has been set up correctly, run HARK's tests with `python -m unittest`.
To check that everything has been set up correctly, you can run HARK's tests using `python -m unittest`.

## Next steps

To learn more about how to use HARK, check the next sections in this documentation, in particular the jupyter notebooks.

For help making changes to HARK, check out our [contributing guide](contributing.md).
To learn more about how to use HARK, check the next sections in this documentation, in particular the example notebooks.