Merge pull request #1506 from econ-ark/alanlujan91/improve-documentation

Improve documentation in the repository

Documentation/guides/contributing.md

@@ -108,7 +108,7 @@ Thanks again! We're so glad to have you in our community.
      git remote add upstream [email protected]:econ-ark/HARK
      ```
 
-   - Now, you have remote repositories named:
+   - Now, have remote repositories named:
 
      - `upstream`, which refers to the `HARK` repository
      - `origin`, which refers to your personal fork of `HARK`.

Documentation/guides/installation.md

@@ -189,3 +189,109 @@ Once you have downloaded them, you will find that the repo contains a `notebooks
 ```
 jupyter notebook
 ```
+
+## Example: Installing HARK and Running a Simple Model
+
+To help new users get started with HARK, let's walk through an example of installing HARK and running a simple model.
+
+### Step 1: Install Python and a Text Editor
+
+First, make sure you have Python installed on your computer. You can download Python from the official [Python website](https://www.python.org/downloads/). Follow the installation instructions for your operating system.
+
+Next, install a text editor for writing and running Python code. We recommend using [VSCode](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/pycharm/). If you're using Anaconda, you can also use Spyder, which comes bundled with Anaconda.
+
+### Step 2: Create a Virtual Environment
+
+To keep your HARK installation isolated from other Python packages, create a virtual environment. You can use either `virtualenv` or `conda` for this purpose.
+
+#### Using virtualenv
+
+1. Open a terminal or command prompt.
+2. Navigate to the directory where you want to store the virtual environment.
+3. Run the following commands:
+
+```
+pip install virtualenv
+virtualenv econ-ark
+```
+
+4. Activate the virtual environment:
+
+- For Windows:
+
+```
+.\econ-ark\Scripts\activate.bat
+```
+
+- For Mac or Linux:
+
+```
+source econ-ark/bin/activate
+```
+
+#### Using Conda
+
+1. Open a terminal or command prompt.
+2. Run the following commands:
+
+```
+conda create -n econ-ark anaconda
+conda activate econ-ark
+```
+
+### Step 3: Install HARK
+
+With the virtual environment activated, install HARK using `pip`:
+
+```
+pip install econ-ark
+```
+
+### Step 4: Run a Simple Model
+
+Now that HARK is installed, let's run a simple model. Create a new Python file (e.g., `simple_model.py`) and add the following code:
+
+```python
+from HARK.ConsumptionSaving.ConsIndShockModel import PerfForesightConsumerType
+
+# Define the parameters for the model
+params = {
+    "CRRA": 2.5,  # Relative risk aversion
+    "DiscFac": 0.96,  # Discount factor
+    "Rfree": 1.03,  # Risk-free interest factor
+    "LivPrb": [0.98],  # Survival probability
+    "PermGroFac": [1.01],  # Income growth factor
+    "T_cycle": 1,
+    "cycles": 0,
+    "AgentCount": 10000,
+}
+
+# Create an instance of the model
+model = PerfForesightConsumerType(**params)
+
+# Solve the model
+model.solve()
+
+# Print the consumption function
+print(model.solution[0].cFunc)
+```
+
+Save the file and run it from the terminal or command prompt:
+
+```
+python simple_model.py
+```
+
+You should see the consumption function printed in the output.
+
+Congratulations! You've successfully installed HARK and run a simple model. For more examples and detailed explanations, refer to the [HARK documentation](https://docs.econ-ark.org/).
+
+## Additional Examples and Tutorials
+
+To help new users get started with the repository more easily, we have added more detailed explanations and examples in the following sections:
+
+- [Overview and Examples](https://docs.econ-ark.org/Documentation/overview/index.html): This section provides an introduction to HARK and includes various examples to help users understand how to use the toolkit.
+- [Guides](https://docs.econ-ark.org/Documentation/guides/index.html): This section includes guides on installation, quick start, and contributing to HARK.
+- [Reference](https://docs.econ-ark.org/Documentation/reference/index.html): This section provides detailed explanations and examples of the various tools and models available in the repository.
+
+For more information and resources, please visit the [Econ-ARK documentation](https://docs.econ-ark.org/).

Documentation/guides/quick_start.md

@@ -92,3 +92,109 @@ jupyter notebook
 ## Next steps
 
 To learn more about how to use HARK, check the next sections in this documentation, in particular the example notebooks. For instructions on making changes to HARK, refer to our [contributing guide](https://docs.econ-ark.org/Documentation/guides/contributing.html).
+
+## Example: Installing HARK and Running a Simple Model
+
+To help new users get started with HARK, let's walk through an example of installing HARK and running a simple model.
+
+### Step 1: Install Python and a Text Editor
+
+First, make sure you have Python installed on your computer. You can download Python from the official [Python website](https://www.python.org/downloads/). Follow the installation instructions for your operating system.
+
+Next, install a text editor for writing and running Python code. We recommend using [VSCode](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/pycharm/). If you're using Anaconda, you can also use Spyder, which comes bundled with Anaconda.
+
+### Step 2: Create a Virtual Environment
+
+To keep your HARK installation isolated from other Python packages, create a virtual environment. You can use either `virtualenv` or `conda` for this purpose.
+
+#### Using virtualenv
+
+1. Open a terminal or command prompt.
+2. Navigate to the directory where you want to store the virtual environment.
+3. Run the following commands:
+
+```
+pip install virtualenv
+virtualenv econ-ark
+```
+
+4. Activate the virtual environment:
+
+- For Windows:
+
+```
+.\econ-ark\Scripts\activate.bat
+```
+
+- For Mac or Linux:
+
+```
+source econ-ark/bin/activate
+```
+
+#### Using Conda
+
+1. Open a terminal or command prompt.
+2. Run the following commands:
+
+```
+conda create -n econ-ark anaconda
+conda activate econ-ark
+```
+
+### Step 3: Install HARK
+
+With the virtual environment activated, install HARK using `pip`:
+
+```
+pip install econ-ark
+```
+
+### Step 4: Run a Simple Model
+
+Now that HARK is installed, let's run a simple model. Create a new Python file (e.g., `simple_model.py`) and add the following code:
+
+```python
+from HARK.ConsumptionSaving.ConsIndShockModel import PerfForesightConsumerType
+
+# Define the parameters for the model
+params = {
+    "CRRA": 2.5,  # Relative risk aversion
+    "DiscFac": 0.96,  # Discount factor
+    "Rfree": 1.03,  # Risk-free interest factor
+    "LivPrb": [0.98],  # Survival probability
+    "PermGroFac": [1.01],  # Income growth factor
+    "T_cycle": 1,
+    "cycles": 0,
+    "AgentCount": 10000,
+}
+
+# Create an instance of the model
+model = PerfForesightConsumerType(**params)
+
+# Solve the model
+model.solve()
+
+# Print the consumption function
+print(model.solution[0].cFunc)
+```
+
+Save the file and run it from the terminal or command prompt:
+
+```
+python simple_model.py
+```
+
+You should see the consumption function printed in the output.
+
+Congratulations! You've successfully installed HARK and run a simple model. For more examples and detailed explanations, refer to the [HARK documentation](https://docs.econ-ark.org/).
+
+## Additional Examples and Tutorials
+
+To help new users get started with the repository more easily, we have added more detailed explanations and examples in the following sections:
+
+- [Overview and Examples](https://docs.econ-ark.org/Documentation/overview/index.html): This section provides an introduction to HARK and includes various examples to help users understand how to use the toolkit.
+- [Guides](https://docs.econ-ark.org/Documentation/guides/index.html): This section includes guides on installation, quick start, and contributing to HARK.
+- [Reference](https://docs.econ-ark.org/Documentation/reference/index.html): This section provides detailed explanations and examples of the various tools and models available in the repository.
+
+For more information and resources, please visit the [Econ-ARK documentation](https://docs.econ-ark.org/).

Documentation/overview/ARKitecture.md

@@ -187,3 +187,13 @@ If you want to run the notebooks on your own machine make sure to install the ne
 HARK can be used to replicate papers as well. For this purpose the _R_[eplications/eproductions] and *E*xplorations *M*ade using _ARK_ (REMARK) [repository](https://github.com/econ-ark/REMARK) was created.
 
 Each replication consists of a _metadata file_ (.md) with an overview, a _notebook_ which replicates the paper, and a _requirement.txt_ file with the necessary packages to run the notebooks on your local mashine.
+
+### Additional Examples and Tutorials
+
+To help users understand the structure and organization of the repository, we have added more detailed explanations and examples in the following sections:
+
+- [HARK](https://github.com/econ-ark/HARK): Includes the source code as well as some example notebooks.
+- [DemARK](https://github.com/econ-ark/DemARK): Here you can find *Dem*onstrations of tools, AgentTypes, and ModelClasses.
+- [REMARK](https://github.com/econ-ark/REMARK): Here you can find _R_[eplications/eproductions] and *E*xplorations *M*ade using _ARK_.
+
+For more detailed explanations and examples, please refer to the [HARK documentation](https://docs.econ-ark.org/).

README.md

@@ -238,3 +238,13 @@ This is the guide that collaborators follow in maintaining the Econ-ARK project.
 ## Disclaimer
 
 This is a beta version of HARK. The code has not been extensively tested as it should be. We hope it is useful, but there are absolutely no guarantees (expressed or implied) that it works or will do what you want. Use at your own risk. And please, let us know if you find bugs by posting an issue to [the GitHub page](https://github.com/econ-ark/HARK)!
+
+## Detailed Explanations and Examples
+
+To help users understand the purpose and features of the repository, we have provided detailed explanations and examples in various sections of the documentation. Here are some key resources:
+
+- [Overview and Examples](https://docs.econ-ark.org/Documentation/overview/index.html): This section provides an introduction to HARK and includes various examples to help users understand how to use the toolkit.
+- [Guides](https://docs.econ-ark.org/Documentation/guides/index.html): This section includes guides on installation, quick start, and contributing to HARK.
+- [Reference](https://docs.econ-ark.org/Documentation/reference/index.html): This section provides detailed explanations and examples of the various tools and models available in the repository.
+
+For more information and resources, please visit the [Econ-ARK documentation](https://docs.econ-ark.org/).