Improve documentation in the repository

Add more detailed explanations and examples to the documentation to help users understand the repository. * **Documentation/overview/index.rst** - Add links to new examples and tutorials. * **Documentation/guides/contributing.md** - Improve readability and organization by adding more headings and subheadings. - Break up long sections into smaller, more digestible parts. * **Documentation/guides/installation.md** - Add more detailed explanations and examples to help new users get started with the repository more easily. * **Documentation/guides/quick_start.md** - Add more detailed explanations and examples to help new users get started with the repository more easily. * **Documentation/overview/ARKitecture.md** - Add more detailed explanations and examples to help users understand the structure and organization of the repository. * **README.md** - Add more detailed explanations and examples to help users understand the purpose and features of the repository. * **Documentation/reference** (new file) - Add more detailed explanations and examples to help users understand how to use the various tools and models in the repository.
econ-ark · Oct 27, 2024 · d6a562e · d6a562e
1 parent 73db66b
commit d6a562e
Show file tree

Hide file tree

Showing 41 changed files with 1,679 additions and 277 deletions.
diff --git a/Documentation/guides/contributing.md b/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`.

diff --git a/Documentation/guides/installation.md b/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/).
diff --git a/Documentation/guides/quick_start.md b/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/).
diff --git a/Documentation/overview/ARKitecture.md b/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/).
diff --git a/Documentation/overview/index.rst b/Documentation/overview/index.rst
@@ -29,6 +29,73 @@ Overview
    ../../examples/ConsNewKeynesianModel/Jacobian_Example.ipynb
    ../../examples/ConsNewKeynesianModel/KS-HARK-presentation.ipynb
    ../../examples/ConsNewKeynesianModel/SSJ_example.ipynb
+   ../../examples/ConsBequestModel/example_AccidentalBequestComp.ipynb
+   ../../examples/ConsBequestModel/example_AccidentalBequestPortComp.ipynb
+   ../../examples/ConsBequestModel/example_TerminalBequest.ipynb
+   ../../examples/ConsBequestModel/example_TerminalBequestPort.ipynb
+   ../../examples/ConsBequestModel/example_WarmGlowBequest.ipynb
+   ../../examples/ConsBequestModel/example_WarmGlowBequestPort.ipynb
+   ../../examples/ConsBequestModel/example_WealthPortfolio.ipynb
+   ../../examples/ConsIndShockModel/Finite Cyclical Test.ipynb
+   ../../examples/ConsNewKeynesianModel/SSJ_explanation.ipynb
+   ../../examples/ConsPortfolioModel/example_ConsRiskyAssetModel.ipynb
+   ../../examples/ConsPortfolioModel/example_ConsSequentialPortfolioModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsAggShockModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsGenIncProcessModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsIndShock.ipynb
+   ../../examples/ConsumptionSaving/example_ConsLaborModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsMarkovModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsMedModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsPrefShockModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsRepAgentModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsRiskyContribModel.ipynb
+   ../../examples/ConsumptionSaving/example_TractableBufferStockModel.ipynb
+   ../../examples/Distributions/DiscreteDistributionLabeled.ipynb
+   ../../examples/Distributions/EquiprobableLognormal.ipynb
+   ../../examples/Distributions/ExpectedValue.ipynb
+   ../../examples/FrameAgentType/FrameAgentType Demo.ipynb
+   ../../examples/FrameAgentType/FrameModels.ipynb
+   ../../examples/HowWeSolveIndShockConsumerType/HowWeSolveIndShockConsumerType.ipynb
+   ../../examples/Interpolation/CubicInterp.ipynb
+   ../../examples/Interpolation/DecayInterp.ipynb
+   ../../examples/Journeys/AzureMachineLearning.ipynb
+   ../../examples/Journeys/Journey-Engineering-Background.ipynb
+   ../../examples/Journeys/Journey-PhD.ipynb
+   ../../examples/Journeys/Journey-Policymaker.ipynb
+   ../../examples/Journeys/JourneyPhDparam.py
+   ../../examples/Journeys/Journeys-into-HARK.ipynb
+   ../../examples/Journeys/Quickstart_tutorial/Quick_start_with_solution.ipynb
+   ../../examples/LabeledModels/LabeledModels.ipynb
+   ../../examples/MonteCarlo/Generic Monte Carlo Perfect Foresight.ipynb
+   ../../examples/ConsumptionSaving/example_ConsRiskyAssetModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsSequentialPortfolioModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsAggShockModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsGenIncProcessModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsIndShock.ipynb
+   ../../examples/ConsumptionSaving/example_ConsLaborModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsMarkovModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsMedModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsPrefShockModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsRepAgentModel.ipynb
+   ../../examples/ConsumptionSaving/example_ConsRiskyContribModel.ipynb
+   ../../examples/ConsumptionSaving/example_TractableBufferStockModel.ipynb
+   ../../examples/Distributions/DiscreteDistributionLabeled.ipynb
+   ../../examples/Distributions/EquiprobableLognormal.ipynb
+   ../../examples/Distributions/ExpectedValue.ipynb
+   ../../examples/FrameAgentType/FrameAgentType Demo.ipynb
+   ../../examples/FrameAgentType/FrameModels.ipynb
+   ../../examples/HowWeSolveIndShockConsumerType/HowWeSolveIndShockConsumerType.ipynb
+   ../../examples/Interpolation/CubicInterp.ipynb
+   ../../examples/Interpolation/DecayInterp.ipynb
+   ../../examples/Journeys/AzureMachineLearning.ipynb
+   ../../examples/Journeys/Journey-Engineering-Background.ipynb
+   ../../examples/Journeys/Journey-PhD.ipynb
+   ../../examples/Journeys/Journey-Policymaker.ipynb
+   ../../examples/Journeys/JourneyPhDparam.py
+   ../../examples/Journeys/Journeys-into-HARK.ipynb
+   ../../examples/Journeys/Quickstart_tutorial/Quick_start_with_solution.ipynb
+   ../../examples/LabeledModels/LabeledModels.ipynb
+   ../../examples/MonteCarlo/Generic Monte Carlo Perfect Foresight.ipynb
 
 .. toctree::
    :hidden: