diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..56f87ad18 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,3 @@ +# Code of Conduct + +* [NumFOCUS Code of Conduct](https://numfocus.org/code-of-conduct) \ No newline at end of file diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 000000000..33514c431 --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,3 @@ +# Support + +This guide is not yet drafted. Visit the [legacy documentation](https://github.com/econ-ark/HARK/tree/master/Documentation) for more info. \ No newline at end of file diff --git a/CHANGES.md b/CHANGELOG.md similarity index 100% rename from CHANGES.md rename to CHANGELOG.md diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md new file mode 100644 index 000000000..93e709664 --- /dev/null +++ b/COLLABORATOR_GUIDE.md @@ -0,0 +1,3 @@ +# HARK Collaborator Guide + +This guide is not yet drafted. Visit the [legacy documentation](https://github.com/econ-ark/HARK/tree/master/Documentation) for more info. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b489aee9..58ae30f38 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,38 +1,58 @@ -# Contributing to Econ-ARK +# Contributing to HARK -### Welcome! +* [Code of Conduct](#code-of-conduct) +* [Issues](#issues) +* [Pull Requests](#pull-requests) +* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) -Thank you for considering contributing to Econ-ARK! We're a young project with a small but committed community that's hoping to grow while maintaining our friendly and responsive culture. Whether you're an economist or a technologist, a writer or a coder, an undergrad or a full professor, a professional or a hobbyist, there's a place for you in the Econ-ARK community. +## [Code of Conduct](./doc/guides/contributing/coc.md) -We're still creating our contribution infrastructure, so this document is a work in progress. If you have any questions please feel free to @ or otherwise reach out project manager [Shauna](https://github.com/shaunagm), or lead developers [Chris](https://github.com/llorracc) and [Matt](https://github.com/mnwhite). If you prefer to connect through email, you can send it to __econ-ark at jhuecon dot org__. +The Econ-ARK project has a +[Code of Conduct](./.github/CODE_OF_CONDUCT.md) +to which all contributors must adhere. -### How to Contribute +See [details on our policy on Code of Conduct](./.github/CODE_OF_CONDUCT.md). -We're open to all kinds of contributions, from bug reports to help with our docs to suggestions on how to improve our code. The best way to figure out if the contribution you'd like to make is something we'd merge or otherwise accept, is to open up an issue in our issue tracker. Please create an issue rather than immediately submitting pull request, unless the change you'd like to make is so minor you won't mind if the pull request is rejected. For bigger contributions, we want to proactively talk things through so we don't end up wasting your time. +## [Issues](./doc/guides/contributing/issues.md) -While we're thrilled to receive all kinds of contributions, there are a few key areas we'd especially like help with: +* [How to Contribute in Issues](./doc/guides/contributing/issues.md#how-to-contribute-in-issues) +* [Asking for General Help](./doc/guides/contributing/issues.md#asking-for-general-help) +* [Discussing non-technical topics](./doc/guides/contributing/issues.md#discussing-non-technical-topics) +* [Submitting a Bug Report](./doc/guides/contributing/issues.md#submitting-a-bug-report) +* [Triaging a Bug Report](./doc/guides/contributing/issues.md#triaging-a-bug-report) +* [Resolving a Bug Report](./doc/guides/contributing/issues.md#resolving-a-bug-report) -* porting existing heterogenous agent/agent based models into HARK -* curating and expanding the collection of projects which use Econ-ARK (which we store in the [remark](https://github.com/econ-ark/REMARK) repository) -* creating demonstrations of how to use Econ-ARK (which we store in the [DemARK](https://github.com/econ-ark/DemARK) repository) -* expanding test coverage of our existing code +## [Pull Requests](./doc/guides/contributing/pull-requests.md) -If you'd like to help with those or any other kind of contribution, reach out to us and we'll help you do so. +* [Dependencies](./doc/guides/contributing/pull-requests.md#dependencies) +* [Setting up your local environment](./doc/guides/contributing/pull-requests.md#setting-up-your-local-environment) +* [The Process of Making Changes](./doc/guides/contributing/pull-requests.md#the-process-of-making-changes) +* [Reviewing Pull Requests](./doc/guides/contributing/pull-requests.md#reviewing-pull-requests) +* [Notes](./doc/guides/contributing/pull-requests.md#notes) -We don't currently have guidelines for opening issues or pull requests, so include as much information as seems relevant to you, and we'll ask you if we need to know more. + +## Developer's Certificate of Origin 1.1 -### Responding to Issues & Pull Requests +By making a contribution to this project, I certify that: -We're trying to get better at managing our open issues and pull requests. We've created a new set of goals for all issues and pull requests in our Econ-ARK repos: +* (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or -1. Initial response within one or two days. -2. Substantive response within two weeks. -3. Resolution of issue/pull request within three months. +* (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or -If you've been waiting on us for more than two weeks for any reason, please feel free to give us a nudge. Correspondingly, we ask that you respond to any questions or requests from us within two weeks as well, even if it's just to say, "Sorry, I can't get to this for a while yet". If we don't hear back from you, we may close your issue or pull request. If you want to re-open it, just ask - we're glad to do so. +* (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. -### Getting Started - -The [quick start guide](https://github.com/econ-ark/HARK#ii-quick-start-guide) in our README provides instructions for how to get started running HARK. This also serves as a setup guide for new contributors. If you run into any problems, please let us know by opening an issue in the issue tracker. - -Thanks again! We're so glad to have you in our community. +* (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. \ No newline at end of file diff --git a/Documentation/CONTRIBUTING.md b/Documentation/CONTRIBUTING.md new file mode 100644 index 000000000..1b489aee9 --- /dev/null +++ b/Documentation/CONTRIBUTING.md @@ -0,0 +1,38 @@ +# Contributing to Econ-ARK + +### Welcome! + +Thank you for considering contributing to Econ-ARK! We're a young project with a small but committed community that's hoping to grow while maintaining our friendly and responsive culture. Whether you're an economist or a technologist, a writer or a coder, an undergrad or a full professor, a professional or a hobbyist, there's a place for you in the Econ-ARK community. + +We're still creating our contribution infrastructure, so this document is a work in progress. If you have any questions please feel free to @ or otherwise reach out project manager [Shauna](https://github.com/shaunagm), or lead developers [Chris](https://github.com/llorracc) and [Matt](https://github.com/mnwhite). If you prefer to connect through email, you can send it to __econ-ark at jhuecon dot org__. + +### How to Contribute + +We're open to all kinds of contributions, from bug reports to help with our docs to suggestions on how to improve our code. The best way to figure out if the contribution you'd like to make is something we'd merge or otherwise accept, is to open up an issue in our issue tracker. Please create an issue rather than immediately submitting pull request, unless the change you'd like to make is so minor you won't mind if the pull request is rejected. For bigger contributions, we want to proactively talk things through so we don't end up wasting your time. + +While we're thrilled to receive all kinds of contributions, there are a few key areas we'd especially like help with: + +* porting existing heterogenous agent/agent based models into HARK +* curating and expanding the collection of projects which use Econ-ARK (which we store in the [remark](https://github.com/econ-ark/REMARK) repository) +* creating demonstrations of how to use Econ-ARK (which we store in the [DemARK](https://github.com/econ-ark/DemARK) repository) +* expanding test coverage of our existing code + +If you'd like to help with those or any other kind of contribution, reach out to us and we'll help you do so. + +We don't currently have guidelines for opening issues or pull requests, so include as much information as seems relevant to you, and we'll ask you if we need to know more. + +### Responding to Issues & Pull Requests + +We're trying to get better at managing our open issues and pull requests. We've created a new set of goals for all issues and pull requests in our Econ-ARK repos: + +1. Initial response within one or two days. +2. Substantive response within two weeks. +3. Resolution of issue/pull request within three months. + +If you've been waiting on us for more than two weeks for any reason, please feel free to give us a nudge. Correspondingly, we ask that you respond to any questions or requests from us within two weeks as well, even if it's just to say, "Sorry, I can't get to this for a while yet". If we don't hear back from you, we may close your issue or pull request. If you want to re-open it, just ask - we're glad to do so. + +### Getting Started + +The [quick start guide](https://github.com/econ-ark/HARK#ii-quick-start-guide) in our README provides instructions for how to get started running HARK. This also serves as a setup guide for new contributors. If you run into any problems, please let us know by opening an issue in the issue tracker. + +Thanks again! We're so glad to have you in our community. diff --git a/Documentation/readme.md b/Documentation/readme.md deleted file mode 120000 index 32d46ee88..000000000 --- a/Documentation/readme.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/Documentation/readme.md b/Documentation/readme.md new file mode 100644 index 000000000..20e40d06b --- /dev/null +++ b/Documentation/readme.md @@ -0,0 +1,403 @@ +# Heterogeneous Agents Resources and toolKit (HARK) +pre-release 0.10.1.dev3 + +Click the Badge for Citation Info. +[![DOI](https://zenodo.org/badge/50448254.svg)](https://zenodo.org/badge/latestdoi/50448254) + + +Table of Contents: + +* [1. Introduction](#i-introduction) +* [2. Quick start guide](#ii-quick-start-guide) + * [Installing](#Installing-HARK) + * [Installing Anaconda](#Using-HARK-with-Anaconda) + * [Learning HARK](#Learning-HARK) +* [3. List of files in repository](#iii-list-of-files-in-repository) +* [4. Warnings and disclaimers](#iv-warnings-and-disclaimers) +* [5. License Information](#v-license) + + +## I. INTRODUCTION + +This document will tell you how to get HARK up and +running on your machine, how to get started using it, and give you an +overview of the main elements of the toolkit. + +Other useful resources are: + + * Documentation: [ReadTheDocs](https://hark.readthedocs.io/) + * User guide: [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf) + * In the [HARK repository](https://github.com/econ-ark/HARK) + * Demonstrations of HARK functionality: [DemARK](https://github.com/econ-ark/DemARK/) + * Replications and Explorations Made using the ARK : [REMARK](https://github.com/econ-ark/REMARK/) + +## II. QUICK START GUIDE + +### Installing HARK + +HARK is an open source project that is compatible with both python 2 and 3. But we recommend +using python 3; eventually support for python 2 will end. + +#### Installing HARK with pip + +The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installing/). + +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. + +To install `virtualenv`, then to create an environment named `econ-ark`, and finally to activate that environment: + +``` +cd [directory where you want to store the econ-ark virtual environment] +pip install virtualenv +virtualenv econ-ark +source econ-ark/bin/activate +``` + +---- +#### Using HARK with Anaconda + +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/why-anaconda), 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). + +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: +``` +conda create -n econ-ark anaconda +conda activate econ-ark +conda install -c conda-forge econ-ark +``` +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'. + + * 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/documentation)). + + * 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. + +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 below in [Application Modules](#application-modules). 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 + +You will want to obtain your own local copy of these repos using: +``` +git clone https://github.com/econ-ark/DemARK.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: + +``` +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. + +The most broadly applicable advice is to go to [Econ-ARK](https://econ-ark.org) and click on "Notebooks", and choose [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) which will launch as a [jupyter notebook](https://jupyter.org/). + +##### [For people with a technical/scientific/computing background but little economics background](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-people-with-a-technicalscientificcomputing-background-but-no-economics-background) + +* [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) + +##### [For economists who have done some structural modeling](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-done-some-structural-modeling) + +* A full replication of the [Iskhakov, Jørgensen, Rust, and Schjerning](https://onlinelibrary.wiley.com/doi/abs/10.3982/QE643) paper for solving the discrete-continuous retirement saving problem + * An informal discussion of the issues involved is [here](https://github.com/econ-ark/DemARK/blob/master/notebooks/DCEGM-Upper-Envelope.ipynb) (part of the [DemARK](https://github.com/econ-ark/DemARK) repo) + +* [Structural-Estimates-From-Empirical-MPCs](https://github.com/econ-ark/DemARK/blob/master/notebooks/Structural-Estimates-From-Empirical-MPCs-Fagereng-et-al.ipynb) is an example of the use of the toolkit in a discussion of a well known paper. (Yes, it is easy enough to use that you can estimate a structural model on somebody else's data in the limited time available for writing a discussion) + +##### [For economists who have not yet done any structural modeling but might be persuadable to start](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-not-yet-done-any-structural-modeling-but-might-be-persuadable-to-start) + +* Start with [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) to get your feet wet + +* A simple indirect inference/simulated method of moments structural estimation along the lines of Gourinchas and Parker's 2002 Econometrica paper or Cagetti's 2003 paper is performed by the [SolvingMicroDSOPs](https://github.com/econ-ark/REMARK/tree/master/REMARKs/SolvingMicroDSOPs) [REMARK](https://github.com/econ-ark/REMARK); this code implements the solution methods described in the corresponding section of [these lecture notes](http://www.econ2.jhu.edu/people/ccarroll/SolvingMicroDSOPs/) + +##### [For Other Developers of Software for Computational Economics](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-other-developers-of-software-for-computational-economics) + + +* Our workhorse module is [ConsIndShockModel.py](https://github.com/econ-ark/HARK/blob/master/HARK/ConsumptionSaving/ConsIndShockModel.py) + * which is explored and explained (a bit) in [this jupyter notebook](https://github.com/econ-ark/DemARK/blob/master/notebooks/ConsIndShockModel.ipynb) + +### Making changes to HARK + +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 above) 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/documentation)). 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]([virtualenv]((https://virtualenv.pypa.io/en/latest/))). + +For Mac or Linux: + +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 +``` + +3. Once the virtualenv is activated, you may see `(econ-ark)` in your command prompt (depending on how your machine is configured) + +3. Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`. + +4. To check that everything has been set up correctly, run HARK's tests with `python -m unittest`. + +### Trouble with installation? + +We've done our best to give correct, thorough instructions on how to install HARK but we know this information may be inaccurate or incomplete. Please let us know if you run into trouble so we can update this guide! Here's a list of platforms and versions this guide has been verified for: + +| Installation Type | Platform | Python Version | Date Tested | Tested By | +| ------------- |:-------------:| -----:| -----:|-----:| +| basic pip install | Linux (16.04) | 3 | 2019-04-24 | @shaunagm | +| anaconda | Linux (16.04) | 3 | 2019-04-24 | @shaunagm | +| basic pip install | MacOS 10.13.2 "High Sierra" | 2.7| 2019-04-26 | @llorracc | + +### Next steps + +To learn more about how to use HARK, check out our [user manual](Documentation/HARKmanual.pdf). + +For help making changes to HARK, check out our [contributing guide](CONTRIBUTING.md). + + +## III. LIST OF FILES IN REPOSITORY + +This section contains descriptions of the main files in the repo. + +Documentation files: +* [README.md](README.md): The file you are currently reading. +* [Documentation/HARKdoc.pdf](Documentation/HARKdoc.pdf): A mini-user guide produced for a December 2015 workshop on HARK, unofficially representing the alpha version. (Substantially out of date). +* [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf): A user guide for HARK, written for the beta release at CEF 2016 in Bordeaux. Should contain 90% fewer lies relative to HARKdoc.pdf. + * [Documentation/HARKmanual.tex](Documentation/HARKmanual.tex): LaTeX source for the user guide. Open source code probably requires an open source manual as well. +* [Documentation/ConsumptionSavingModels.pdf](Documentation/ConsumptionSavingModels.pdf): Mathematical descriptions of the various consumption-saving models in HARK and how they map into the code. + * [Documentation/ConsumptionSavingModels.tex](Documentation/ConsumptionSavingModels.tex): LaTeX source for the "models" writeup. +* [Documentation/NARK.pdf](Documentation/NARK.pdf): Variable naming conventions for HARK, plus concordance with LaTeX variable definitions. Still in development. + +Tool modules: +* [HARK/core.py](HARK/core.py): + Frameworks for "microeconomic" and "macroeconomic" models in HARK. + We somewhat abuse those terms as shorthand; see the user guide for a + description of what we mean. Every model in HARK extends the classes + AgentType and Market in this module. Does nothing when run. +* [HARK/utilities.py](HARK/utilities.py): + General purpose tools and utilities. Contains literal utility functions + (in the economic sense), functions for making discrete approximations + to continuous distributions, basic plotting functions for convenience, + and a few unclassifiable things. Does nothing when run. +* [HARK/estimation.py](HARK/estimation.py): + Functions for estimating models. As is, it only has a few wrapper + functions for scipy.optimize optimization routines. Will be expanded + in the future with more interesting things. Does nothing when run. +* [HARK/simulation.py](HARK/simulation.py): + Functions for generating simulated data. Functions in this module have + names like drawUniform, generating (lists of) arrays of draws from + various distributions. Does nothing when run. +* [HARK/interpolation.py](HARK/interpolation.py): + Classes for representing interpolated function approximations. Has + 1D-4D interpolation methods, mostly based on linear or cubic spline + interpolation. Will have ND methods in the future. Does nothing when run. +* [HARK/parallel.py](HARK/parallel.py): + Early version of parallel processing in HARK. Works with instances of + the AgentType class (or subclasses of it), distributing commands (as + methods) to be run on a list of AgentTypes. Only works with local CPU. + The module also contains a parallel implentation of the Nelder-Mead + simplex algorithm, poached from Wiswall and Lee (2011). Does nothing + when run. + +Model modules: +* [ConsumptionSaving/TractableBufferStockModel.py](HARK/ConsumptionSaving/TractableBufferStockModel.py): + * A "tractable" model of consumption and saving in which agents face one + simple risk with constant probability: that they will become permanently + unemployed and receive no further income. Unlike other models in HARK, + this one is not solved by iterating on a sequence of one period problems. + Instead, it uses a "backshooting" routine that has been shoehorned into + the AgentType.solve framework. Solves an example of the model when run, + then solves the same model again using MarkovConsumerType. +* [ConsumptionSaving/ConsIndShockModel.py](HARK/ConsumptionSaving/ConsIndShockModel.py): + * Consumption-saving models with idiosyncratic shocks to income. Shocks + are fully transitory or fully permanent. Solves perfect foresight model, + a model with idiosyncratic income shocks, and a model with idiosyncratic + income shocks and a different interest rate on borrowing vs saving. When + run, solves several examples of these models, including a standard infinite + horizon problem, a ten period lifecycle model, a four period "cyclical" + model, and versions with perfect foresight and "kinked R". +* [ConsumptionSaving/ConsPrefShockModel.py](HARK/ConsumptionSaving/ConsPrefShockModel.py): + * Consumption-saving models with idiosyncratic shocks to income and multi- + plicative shocks to utility. Currently has two models: one that extends + the idiosyncratic shocks model, and another that extends the "kinked R" + model. The second model has very little new code, and is created merely + by merging the two "parent models" via multiple inheritance. When run, + solves examples of the preference shock models. +* [ConsumptionSaving/ConsMarkovModel.py](HARK/ConsumptionSaving/ConsMarkovModel.py): + * Consumption-saving models with a discrete state that evolves according to + a Markov rule. Discrete states can vary by their income distribution, + interest factor, and/or expected permanent income growth rate. When run, + solves four example models: (1) A serially correlated unemployment model + with boom and bust cycles (4 states). (2) An "unemployment immunity" model + in which the consumer occasionally learns that he is immune to unemployment + shocks for the next N periods. (3) A model with a time-varying permanent + income growth rate that is serially correlated. (4) A model with a time- + varying interest factor that is serially correlated. +* [ConsumptionSaving/ConsAggShockModel.py](HARK/ConsumptionSaving/ConsAggShockModel.py): + * Consumption-saving models with idiosyncratic and aggregate income shocks. + Currently has a micro model with a basic solver (linear spline consumption + function only, no value function), and a Cobb-Douglas economy for the + agents to "live" in (as a "macroeconomy"). When run, solves an example of + the micro model in partial equilibrium, then solves the general equilibrium + problem to find an evolution rule for the capital-to-labor ratio that is + justified by consumers' collective actions. +* [FashionVictim/FashionVictimModel.py](HARK/FashionVictim/FashionVictimModel.py): + * A very serious model about choosing to dress as a jock or a punk. Used to + demonstrate micro and macro framework concepts from HARKcore. It might be + the simplest model possible for this purpose, or close to it. When run, + the module solves the microeconomic problem of a "fashion victim" for an + example parameter set, then solves the general equilibrium model for an + entire "fashion market" constituting many types of agents, finding a rule + for the evolution of the style distribution in the population that is justi- + fied by fashion victims' collective actions. + +Application modules: + +* [SolvingMicroDSOPs/Code/StructEstimation.py](HARK/SolvingMicroDSOPs/Code/StructEstimation.py): + * Conducts a very simple structural estimation using the idiosyncratic shocks + model in ConsIndShocksModel. Estimates an adjustment factor to an age-varying + sequence of discount factors (taken from Cagetti (2003)) and a coefficient + of relative risk aversion that makes simulated agents' wealth profiles best + match data from the 2004 Survey of Consumer Finance. Also demonstrates + the calculation of standard errors by bootstrap and can construct a contour + map of the objective function. Based on section 9 of Chris Carroll's + lecture notes "Solving Microeconomic Dynamic Stochastic Optimization Problems". +* [cstwMPC/cstwMPC.py](HARK/cstwMPC/cstwMPC.py): + * Conducts the estimations for the paper "The Distribution of Wealth and the + Marginal Propensity to Consume" by Carroll, Slacalek, Tokuoka, and White (2016). + Runtime options are set in SetupParamsCSTW.py, specifying choices such as: + perpetual youth vs lifecycle, beta-dist vs beta-point, liquid assets vs net + worth, aggregate vs idiosyncratic shocks, etc. Uses ConsIndShockModel and + ConsAggShockModel; can demonststrate HARK's "macro" framework on a real model. +* [cstwMPC/MakeCSTWfigs.py](HARK/cstwMPC/MakeCSTWfigs.py): + * Makes various figures for the text of the [cstwMPC](http://econ.jhu.edu/people/ccarroll/papers/cstwMPC) paper. Requires many output + files produced by cstwMPC.py, from various specifications, which are not + distributed with HARK. Has not been tested in quite some time. +* [cstwMPC/MakeCSTWfigsForSlides.py](HARK/cstwMPC/MakeCSTWfigsForSlides.py): + * Makes various figures for the slides for the cstwMPC paper. Requires many + output files produced by cstwMPC.py, from various specifications, which are not + distributed with HARK. Has not been tested in quite some time. + +Parameter and data modules: +* [ConsumptionSaving/ConsumerParameters.py](HARK/ConsumptionSaving/ConsumerParameters.py): + * Defines dictionaries with the minimal set of parameters needed to solve the + models in ConsIndShockModel, ConsAggShockModel, ConsPrefShockModel, and + ConsMarkovModel. These dictionaries are used to make examples when those + modules are run. Does nothing when run itself. +* [SolvingMicroDSOPs/SetupSCFdata.py](HARK/SolvingMicroDSOPs/Calibration/SetupSCFdata.py): + * Imports 2004 SCF data for use by SolvingMicroDSOPs/StructEstimation.py. +* [cstwMPC/SetupParamsCSTW.py](HARK/cstwMPC/SetupParamsCSTW.py): + * Loads calibrated model parameters for cstwMPC.py, chooses specification. +* [FashionVictim/FashionVictimParams.py](HARK/FashionVictim/FashionVictimParams.py): + * Example parameters for FashionVictimModel.py, loaded when that module is run. + +Test modules: +* [Testing/Comparison_UnitTests.py](Testing/Comparison_UnitTests.py): + * Early version of unit testing for HARK, still in development. Compares + the perfect foresight model solution to the idiosyncratic shocks model + solution with shocks turned off; also compares the tractable buffer stock + model solution to the same model solved using a "Markov" description. +* [Testing/ModelTesting.py](Testing/ModelTesting.py): + * Early version of unit testing for HARK, still in development. Defines a + few wrapper classes to run unit tests on subclasses of AgentType. +* [Testing/TractableBufferStockModel_UnitTests.py](Testing/TractableBufferStockModel_UnitTests.py) + * Early version of unit testing for HARK, still in development. Runs a test + on TractableBufferStockModel. +* [Testing/MultithreadDemo.py](Testing/MultithreadDemo.py): + * Demonstrates the multithreading functionality in HARKparallel.py. When + run, it solves oneexample consumption-saving model with idiosyncratic + shocks to income, then solves *many* such models serially, varying the + coefficient of relative risk aversion between rho=1 and rho=8, displaying + the results graphically and presenting the timing. It then solves the + same set of many models using multithreading on the local CPU, displays + the results graphically along with the timing. + +Data files: +* [SolvingMicroDSOPs/Calibration/SCFdata.csv](HARK/SolvingMicroDSOPs/Calibration/SCFdata.csv): + * SCF 2004 data for use in SolvingMicroDSOPs/StructEstimation.py, loaded by + SolvingMicroDSOPs/EstimationParameters.py. +* [cstwMPC/SCFwealthDataReduced.txt](HARK/cstwMPC/SCFwealthDataReduced.txt): + * SCF 2004 data with just net worth and data weights, for use by cstwMPC.py +* [cstwMPC/USactuarial.txt](HARK/cstwMPC/USactuarial.txt): + * U.S. mortality data from the Social Security Administration, for use by + cstwMPC.py when running a lifecycle specification. +* [cstwMPC/EducMortAdj.txt](HARK/cstwMPC/EducMortAdj.txt): + * Mortality adjusters by education and age (columns by sex and race), for use + by cstwMPC.py when running a lifecycle specification. Taken from [Brown et al. (2002)](https://www.nber.org/chapters/c9757). + +Other files that you don't need to worry about: +* /index.py: + * A file used by Sphinx when generating html documentation for HARK. Users + don't need to worry about it. Several copies are found throughout HARK. +* [.gitignore](.gitignore): + * A file that tells git which files (or types of files) might be found in + the repository directory tree, but should be ignored (not tracked) for + the repo. Currently ignores compiled Python code, LaTex auxiliary files, etc. +* [LICENSE](LICENSE): + * License text for HARK, Apache 2.0. Read it if you're a lawyer! +* [SolvingMicroDSOPs/Figures/SMMcontour.png](HARK/SolvingMicroDSOPs/Figures/SMMcontour.png): + * Contour plot of the objective function for SolvingMicroDSOPs/StructEstimation.py. + Generated when that module is run, along with a PDF version. +* [cstwMPC/Figures/placeholder.txt](HARK/cstwMPC/Figures/placeholder.txt): + * A placeholder file because git doesn't like empty folders, but cstwMPC.py + needs the /Figures directory to exist when it runs. +* [Documentation/conf.py](Documentation/conf.py): + * A configuration file for producing html documentation with Sphinx, generated + by sphinx-quickstart. +* [Documentation/includeme.rst](Documentation/includeme.rst): + * A very small file used by Sphinx to produce documentation. +* [Documentation/index.rst](Documentation/index.rst): + * A list of modules to be included in HARK's Sphinx documentation. This should + be edited if a new tool or model module is added to HARK. +* [Documentation/instructions.md](Documentation/instructions.md): + * A markdown file with instructions for how to set up and run Sphinx. You + don't need to read it. +* [Documentation/simple-steps-getting-sphinx-working.md](Documentation/simple-steps-getting-sphinx-working.md): + * Another markdown file with instructions for how to set up and run Sphinx. +* [Documentation/make.bat](Documentation/make.bat): + * A batch file for producing Sphinx documentation, generated by sphinx-quickstart. +* [Documentation/Makefile](Documentation/Makefile): + * Another Sphinx auxiliary file generated by sphinx-quickstart. +* [Documentation/econtex.sty](Documentation/econtex.sty): + * LaTeX style file with notation definitions. +* [Documentation/econtex.cls](Documentation/econtex.cls): + * LaTeX class file with document layout for the user manual. +* [Documentation/econtexSetup.sty](Documentation/econtexSetup.sty): + * LaTeX style file with notation definitions. +* [Documentation/econtexShortcuts.sty](Documentation/econtexShortcuts.sty): + * LaTeX style file with notation definitions. +* [Documentation/UserGuidePic.pdf](Documentation/UserGuidePic.pdf): + * Image for the front cover of the user guide, showing the consumption + function for the KinkyPref model. + + +## IV. WARNINGS AND DISCLAIMERS + +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)! + + +## V. License + +All of HARK is licensed under the Apache License, Version 2.0 (ALv2). Please see +the LICENSE file for the text of the license. More information can be found at: +http://www.apache.org/dev/apply-license.html diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..ee018ce74 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,3 @@ +# HARK Project Governance + +This document is not yet drafted. Please contact the [TSC](./README.md#tsc-technical-steering-committee) if you have any questions. \ No newline at end of file diff --git a/HARK/GOVERNANCE.md b/HARK/GOVERNANCE.md new file mode 100644 index 000000000..03baf25bb --- /dev/null +++ b/HARK/GOVERNANCE.md @@ -0,0 +1,3 @@ +# Econ-ARK Project Governance + +Econ-ARK project governance is still being drafted. Please refer to the [**Technical Steering Commitee**]() for questions. \ No newline at end of file diff --git a/README.md b/README.md index 20e40d06b..e289b5384 100644 --- a/README.md +++ b/README.md @@ -1,403 +1,270 @@ +
+ + + +
+
+ +[![Anaconda Cloud](https://anaconda.org/conda-forge/econ-ark/badges/version.svg?style=flat)](https://anaconda.org/conda-forge/econ-ark) +[![PyPi](https://img.shields.io/pypi/v/econ-ark.png?style=flat)](https://pypi.org/project/econ-ark/) +[![Documentation Status](https://readthedocs.org/projects/hark/badge/?style=flat&version=latest)](https://hark.readthedocs.io/en/latest/?badge=latest) +[![GitHub Good First Issues](https://img.shields.io/github/issues/econ-ark/HARK/good%20first%20issue.svg)](https://github.com/econ-ark/HARK/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/econ-ark/demos/master) +[![DOI](https://zenodo.org/badge/50448254.svg)](https://zenodo.org/badge/latestdoi/50448254) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![Powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](https://numfocus.org/) +[![Donate](https://img.shields.io/badge/donate-$2-brightgreen.svg)](https://numfocus.salsalabs.org/donate-to-econ-ark/index.html) + + + +
+ # Heterogeneous Agents Resources and toolKit (HARK) -pre-release 0.10.1.dev3 -Click the Badge for Citation Info. -[![DOI](https://zenodo.org/badge/50448254.svg)](https://zenodo.org/badge/latestdoi/50448254) +HARK is a toolkit for the structural modeling of economic choices of optimizing and non-optimizing heterogeneous agents. For more information on using HARK, see the [Econ-ARK Website](https://econ-ark.org). +The Econ-ARK project uses an [open governance model](./GOVERNANCE.md) and is fiscally sponsored by [NumFOCUS](https://numfocus.org/). Consider making a [tax-deductible donation](https://numfocus.salsalabs.org/donate-to-econ-ark/index.html) to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs. -Table of Contents: +
+ + + +
+
-* [1. Introduction](#i-introduction) -* [2. Quick start guide](#ii-quick-start-guide) - * [Installing](#Installing-HARK) - * [Installing Anaconda](#Using-HARK-with-Anaconda) - * [Learning HARK](#Learning-HARK) -* [3. List of files in repository](#iii-list-of-files-in-repository) -* [4. Warnings and disclaimers](#iv-warnings-and-disclaimers) -* [5. License Information](#v-license) +**This project is bound by a [Code of Conduct](/.github/CODE_OF_CONDUCT.md).** +# Table of Contents -## I. INTRODUCTION +* [Install](#install) +* [Usage](#usage) +* [Citation](#citation) +* [Support](#support) +* [Release Types](#release-types) +* [API Documentation](#api-documentation) +* [Introduction](#introduction) + * [For Students: A Gentle Introduction to Hark](#for-students-a-gentle-introduction-to-hark) + * [For Economists: Structural Modeling with Hark](#for-economists-structural-modeling-with-hark) + * [For Computational Economics Developers](#for-computational-economics-developers) +* [Contributing to HARK](#contributing-to-hark) +* [Current Project Team Members](#current-project-team-members) + * [Founders](#founders) + * [TSC (Technical Steering Commitee)](#tsc-technical-steering-committee) + * [Collaborators](#collaborators) + * [Release Team](#release-team) +* [Contributors](#contributors) +* [Disclaimer](#disclaimer) -This document will tell you how to get HARK up and -running on your machine, how to get started using it, and give you an -overview of the main elements of the toolkit. +## Install -Other useful resources are: +Install from [Anaconda Cloud](https://docs.anaconda.com/anaconda/install/) by running: - * Documentation: [ReadTheDocs](https://hark.readthedocs.io/) - * User guide: [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf) - * In the [HARK repository](https://github.com/econ-ark/HARK) - * Demonstrations of HARK functionality: [DemARK](https://github.com/econ-ark/DemARK/) - * Replications and Explorations Made using the ARK : [REMARK](https://github.com/econ-ark/REMARK/) +`conda install econ-ark` -## II. QUICK START GUIDE +Install from [PyPi](https://pypi.org/) by running: -### Installing HARK +`pip install econ-ark` -HARK is an open source project that is compatible with both python 2 and 3. But we recommend -using python 3; eventually support for python 2 will end. +## Usage -#### Installing HARK with pip +We start with almost the simplest possible consumption model: A consumer with CRRA utility -The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installing/). +
+ +
-To install HARK with pip, at a command line type `pip install econ-ark`. +has perfect foresight about everything except the (stochastic) date of death. -(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.) +The agent's problem can be written in [Bellman form](https://en.wikipedia.org/wiki/Bellman%E2%80%93Ford_algorithm) as: -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. +
+ +
-To install `virtualenv`, then to create an environment named `econ-ark`, and finally to activate that environment: +
-``` -cd [directory where you want to store the econ-ark virtual environment] -pip install virtualenv -virtualenv econ-ark -source econ-ark/bin/activate -``` +To model the above problem, start by importing the `PerfForesightConsumerType` model from the appropriate `HARK` module then create an agent instance using the appropriate paramaters: + +```python +import HARK ----- -#### Using HARK with Anaconda +from HARK.ConsumptionSaving.ConsIndShockModel import PerfForesightConsumerType -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/why-anaconda), which will install python along with many packages that are frequently used in scientific computing. +PF_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 +} -1. Download Anaconda for your operating system and follow the installation instructions [at Anaconda.com](https://www.anaconda.com/distribution/#download-section). +# Create an instance of a Perfect Foresight agent with the above paramaters +PFexample = PerfForesightConsumerType(**PF_params) -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: ``` -conda create -n econ-ark anaconda -conda activate econ-ark -conda install -c conda-forge econ-ark +Once the model is created, ask the the agent to solve the problem with `.solve()`: + +```python +# Tell the agent to solve the problem +PFexample.solve() ``` -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'. +Solving the problem populates the agent's `.solution` list attribute with solutions to each period of the problem. In the case of an infinite horizon model, there is just one element in the list, at **index-zero**. - * 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. +You can retrieve the solution's consumption function from the `.cFunc` attribute: - * 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/documentation)). +```python +# Retrieve the consumption function of the solution +PFexample.solution[0].cFunc +``` - * 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 +Or you can retrieve the solved value for human wealth normalized by permanent income from the solution's `.hNm` attribute: - * 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. +```python +# Retrieve the solved value for human wealth normalized by permanent income +PFexample.solution[0].hNm +``` +For a detailed explanation of the above example please see the demo notebook [*A Gentle Introduction to HARK*](https://mybinder.org/v2/gh/econ-ark/demos/master?filepath=notebooks%2FA+Gentle+Introduction+to+HARK.ipynb). - 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. +For more examples please visit the [econ-ark/demos](https://github.com/econ-ark/demos) repository. -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 below in [Application Modules](#application-modules). 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 +## Citation -You will want to obtain your own local copy of these repos using: -``` -git clone https://github.com/econ-ark/DemARK.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: +If using Econ-ARK in your work or research please [cite our Digital Object Identifier](http://doi.org/10.5281/zenodo.1001068) or copy the BibTex below. + +[![DOI](https://zenodo.org/badge/50448254.svg)](https://zenodo.org/badge/latestdoi/50448254) + +[1] Carroll, Christopher D, Palmer, Nathan, White, Matthew N., Kazil, Jacqueline, Low, David C, & Kaufman, Alexander. (2017, October 3). *econ-ark/HARK* + +**BibText** ``` -jupyter notebook +@InProceedings{carroll_et_al-proc-scipy-2018, + author = { {C}hristopher {D}. {C}arroll and {A}lexander {M}. {K}aufman and {J}acqueline {L}. {K}azil and {N}athan {M}. {P}almer and {M}atthew {N}. {W}hite }, + title = { {T}he {E}con-{A}{R}{K} and {H}{A}{R}{K}: {O}pen {S}ource {T}ools for {C}omputational {E}conomics }, + booktitle = { {P}roceedings of the 17th {P}ython in {S}cience {C}onference }, + pages = { 25 - 30 }, + year = { 2018 }, + editor = { {F}atih {A}kici and {D}avid {L}ippa and {D}illon {N}iederhut and {M} {P}acer }, + doi = { 10.25080/Majora-4af1f417-004 } +} ``` -and from there you can open the notebooks and execute them. -#### Learning HARK +For more on acknowledging Econ-ARK [visit our website](https://econ-ark.org/acknowledging/). -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. +## Support -The most broadly applicable advice is to go to [Econ-ARK](https://econ-ark.org) and click on "Notebooks", and choose [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) which will launch as a [jupyter notebook](https://jupyter.org/). +Looking for help? Please open a [GitHub issue](https://github.com/econ-ark/HARK/issues/new) or reach out to the [TSC](#tsc-technical-steering-committee). -##### [For people with a technical/scientific/computing background but little economics background](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-people-with-a-technicalscientificcomputing-background-but-no-economics-background) +For more support options see [SUPPORT.md](./.github/SUPPORT.md). -* [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) +## Release Types -##### [For economists who have done some structural modeling](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-done-some-structural-modeling) +* **Current**: Under active development. Code for the Current release is in the branch for its major version number (for example, v1.x). +* **Development**: Under active development. Code for the Current release is in the development. +* **Nightly**: Code from the master branch built every night when there are changes. Use with caution. -* A full replication of the [Iskhakov, Jørgensen, Rust, and Schjerning](https://onlinelibrary.wiley.com/doi/abs/10.3982/QE643) paper for solving the discrete-continuous retirement saving problem - * An informal discussion of the issues involved is [here](https://github.com/econ-ark/DemARK/blob/master/notebooks/DCEGM-Upper-Envelope.ipynb) (part of the [DemARK](https://github.com/econ-ark/DemARK) repo) +Current releases follow [Semantic Versioning](https://semver.org/). For more information please see the [Release documentation](doc/release/README.md). -* [Structural-Estimates-From-Empirical-MPCs](https://github.com/econ-ark/DemARK/blob/master/notebooks/Structural-Estimates-From-Empirical-MPCs-Fagereng-et-al.ipynb) is an example of the use of the toolkit in a discussion of a well known paper. (Yes, it is easy enough to use that you can estimate a structural model on somebody else's data in the limited time available for writing a discussion) +## API Documentation -##### [For economists who have not yet done any structural modeling but might be persuadable to start](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-not-yet-done-any-structural-modeling-but-might-be-persuadable-to-start) +Documentation for the latest release is at [hark.readthedocs.io](https://hark.readthedocs.io/en/latest/). Version-specific documentation is available from the same source. -* Start with [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) to get your feet wet +## Introduction -* A simple indirect inference/simulated method of moments structural estimation along the lines of Gourinchas and Parker's 2002 Econometrica paper or Cagetti's 2003 paper is performed by the [SolvingMicroDSOPs](https://github.com/econ-ark/REMARK/tree/master/REMARKs/SolvingMicroDSOPs) [REMARK](https://github.com/econ-ark/REMARK); this code implements the solution methods described in the corresponding section of [these lecture notes](http://www.econ2.jhu.edu/people/ccarroll/SolvingMicroDSOPs/) +### For Students: A Gentle Introduction to HARK -##### [For Other Developers of Software for Computational Economics](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-other-developers-of-software-for-computational-economics) +Most of what economists have done so far with 'big data' has been like what Kepler did with astronomical data: Organizing the data, and finding patterns and regularities and interconnections. +An alternative approach called 'structural modeling' aims to do, for economic data, what Newton did for astronomical data: Provide a deep and rigorous mathematical (or computational) framework that distills the essence of the underlying behavior that produces the 'big data.' -* Our workhorse module is [ConsIndShockModel.py](https://github.com/econ-ark/HARK/blob/master/HARK/ConsumptionSaving/ConsIndShockModel.py) - * which is explored and explained (a bit) in [this jupyter notebook](https://github.com/econ-ark/DemARK/blob/master/notebooks/ConsIndShockModel.ipynb) +The notebook [*A Gentle Introduction to HARK*](https://mybinder.org/v2/gh/econ-ark/demos/master?filepath=notebooks%2FA+Gentle+Introduction+to+HARK.ipynb) details how you can easily utilize our toolkit for structural modeling. Starting with a simple [Perfect Foresight Model](https://en.wikipedia.org/wiki/Rational_expectations) we solve an agent problem, then experiment with adding [income shocks](https://en.wikipedia.org/wiki/Shock_(economics)) and changing constructed attributes. -### Making changes to HARK +### For Economists: Structural Modeling with HARK -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 above) or the GitHub Desktop app. +Dissatisfaction with the ability of Representative Agent models to answer important questions raised by the Great Recession has led to a strong movement in the macroeconomics literature toward 'Heterogeneous Agent' models, in which microeconomic agents (consumers; firms) solve a structural problem calibrated to match microeconomic data; aggregate outcomes are derived by explicitly simulating the equilibrium behavior of populations solving such models. -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/documentation)). 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'. +The same kinds of modeling techniques are also gaining popularity among microeconomists, in areas ranging from labor economics to industrial organization. In both macroeconomics and structural micro, the chief barrier to the wide adoption of these techniques has been that programming a structural model has, until now, required a great deal of specialized knowledge and custom software development. -2. Then, create and activate a [virtual environment]([virtualenv]((https://virtualenv.pypa.io/en/latest/))). +HARK provides a robust, well-designed, open-source toolkit for building such models much more efficiently than has been possible in the past. -For Mac or Linux: +Our [*DCEGM Upper Envelope*](https://mybinder.org/v2/gh/econ-ark/demos/master?filepath=notebooks%2FDCEGM+Upper+Envelope.ipynb) notebook illustrates using HARK to replicate the [Iskhakov, Jørgensen, Rust, and Schjerning paper](https://onlinelibrary.wiley.com/doi/abs/10.3982/QE643) for solving the discrete-continuous retirement saving problem. -Install virtualenv if you need to and then type: +The notebook [*Making Structural Estimates From Empirical Results*](https://mybinder.org/v2/gh/econ-ark/demos/master?filepath=notebooks%2FMaking+Structural+Estimates+From+Empirical+Results.ipynb) is another demonstration of using HARK to conduct a quick structural estimation based on Table 9 of [*MPC Heterogeneity and Household Balance Sheets* by Fagereng, Holm, and Natvik](https://www.ssb.no/en/forskning/discussion-papers/_attachment/286054?_ts=158af859c98). -``` -virtualenv econ-ark -source econ-ark/bin/activate -``` -For Windows: -``` -virtualenv econ-ark -econ-ark\\Scripts\\activate.bat -``` +### For Computational Economics Developers -3. Once the virtualenv is activated, you may see `(econ-ark)` in your command prompt (depending on how your machine is configured) - -3. Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`. - -4. To check that everything has been set up correctly, run HARK's tests with `python -m unittest`. - -### Trouble with installation? - -We've done our best to give correct, thorough instructions on how to install HARK but we know this information may be inaccurate or incomplete. Please let us know if you run into trouble so we can update this guide! Here's a list of platforms and versions this guide has been verified for: - -| Installation Type | Platform | Python Version | Date Tested | Tested By | -| ------------- |:-------------:| -----:| -----:|-----:| -| basic pip install | Linux (16.04) | 3 | 2019-04-24 | @shaunagm | -| anaconda | Linux (16.04) | 3 | 2019-04-24 | @shaunagm | -| basic pip install | MacOS 10.13.2 "High Sierra" | 2.7| 2019-04-26 | @llorracc | - -### Next steps - -To learn more about how to use HARK, check out our [user manual](Documentation/HARKmanual.pdf). - -For help making changes to HARK, check out our [contributing guide](CONTRIBUTING.md). - - -## III. LIST OF FILES IN REPOSITORY - -This section contains descriptions of the main files in the repo. - -Documentation files: -* [README.md](README.md): The file you are currently reading. -* [Documentation/HARKdoc.pdf](Documentation/HARKdoc.pdf): A mini-user guide produced for a December 2015 workshop on HARK, unofficially representing the alpha version. (Substantially out of date). -* [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf): A user guide for HARK, written for the beta release at CEF 2016 in Bordeaux. Should contain 90% fewer lies relative to HARKdoc.pdf. - * [Documentation/HARKmanual.tex](Documentation/HARKmanual.tex): LaTeX source for the user guide. Open source code probably requires an open source manual as well. -* [Documentation/ConsumptionSavingModels.pdf](Documentation/ConsumptionSavingModels.pdf): Mathematical descriptions of the various consumption-saving models in HARK and how they map into the code. - * [Documentation/ConsumptionSavingModels.tex](Documentation/ConsumptionSavingModels.tex): LaTeX source for the "models" writeup. -* [Documentation/NARK.pdf](Documentation/NARK.pdf): Variable naming conventions for HARK, plus concordance with LaTeX variable definitions. Still in development. - -Tool modules: -* [HARK/core.py](HARK/core.py): - Frameworks for "microeconomic" and "macroeconomic" models in HARK. - We somewhat abuse those terms as shorthand; see the user guide for a - description of what we mean. Every model in HARK extends the classes - AgentType and Market in this module. Does nothing when run. -* [HARK/utilities.py](HARK/utilities.py): - General purpose tools and utilities. Contains literal utility functions - (in the economic sense), functions for making discrete approximations - to continuous distributions, basic plotting functions for convenience, - and a few unclassifiable things. Does nothing when run. -* [HARK/estimation.py](HARK/estimation.py): - Functions for estimating models. As is, it only has a few wrapper - functions for scipy.optimize optimization routines. Will be expanded - in the future with more interesting things. Does nothing when run. -* [HARK/simulation.py](HARK/simulation.py): - Functions for generating simulated data. Functions in this module have - names like drawUniform, generating (lists of) arrays of draws from - various distributions. Does nothing when run. -* [HARK/interpolation.py](HARK/interpolation.py): - Classes for representing interpolated function approximations. Has - 1D-4D interpolation methods, mostly based on linear or cubic spline - interpolation. Will have ND methods in the future. Does nothing when run. -* [HARK/parallel.py](HARK/parallel.py): - Early version of parallel processing in HARK. Works with instances of - the AgentType class (or subclasses of it), distributing commands (as - methods) to be run on a list of AgentTypes. Only works with local CPU. - The module also contains a parallel implentation of the Nelder-Mead - simplex algorithm, poached from Wiswall and Lee (2011). Does nothing - when run. - -Model modules: -* [ConsumptionSaving/TractableBufferStockModel.py](HARK/ConsumptionSaving/TractableBufferStockModel.py): - * A "tractable" model of consumption and saving in which agents face one - simple risk with constant probability: that they will become permanently - unemployed and receive no further income. Unlike other models in HARK, - this one is not solved by iterating on a sequence of one period problems. - Instead, it uses a "backshooting" routine that has been shoehorned into - the AgentType.solve framework. Solves an example of the model when run, - then solves the same model again using MarkovConsumerType. -* [ConsumptionSaving/ConsIndShockModel.py](HARK/ConsumptionSaving/ConsIndShockModel.py): - * Consumption-saving models with idiosyncratic shocks to income. Shocks - are fully transitory or fully permanent. Solves perfect foresight model, - a model with idiosyncratic income shocks, and a model with idiosyncratic - income shocks and a different interest rate on borrowing vs saving. When - run, solves several examples of these models, including a standard infinite - horizon problem, a ten period lifecycle model, a four period "cyclical" - model, and versions with perfect foresight and "kinked R". -* [ConsumptionSaving/ConsPrefShockModel.py](HARK/ConsumptionSaving/ConsPrefShockModel.py): - * Consumption-saving models with idiosyncratic shocks to income and multi- - plicative shocks to utility. Currently has two models: one that extends - the idiosyncratic shocks model, and another that extends the "kinked R" - model. The second model has very little new code, and is created merely - by merging the two "parent models" via multiple inheritance. When run, - solves examples of the preference shock models. -* [ConsumptionSaving/ConsMarkovModel.py](HARK/ConsumptionSaving/ConsMarkovModel.py): - * Consumption-saving models with a discrete state that evolves according to - a Markov rule. Discrete states can vary by their income distribution, - interest factor, and/or expected permanent income growth rate. When run, - solves four example models: (1) A serially correlated unemployment model - with boom and bust cycles (4 states). (2) An "unemployment immunity" model - in which the consumer occasionally learns that he is immune to unemployment - shocks for the next N periods. (3) A model with a time-varying permanent - income growth rate that is serially correlated. (4) A model with a time- - varying interest factor that is serially correlated. -* [ConsumptionSaving/ConsAggShockModel.py](HARK/ConsumptionSaving/ConsAggShockModel.py): - * Consumption-saving models with idiosyncratic and aggregate income shocks. - Currently has a micro model with a basic solver (linear spline consumption - function only, no value function), and a Cobb-Douglas economy for the - agents to "live" in (as a "macroeconomy"). When run, solves an example of - the micro model in partial equilibrium, then solves the general equilibrium - problem to find an evolution rule for the capital-to-labor ratio that is - justified by consumers' collective actions. -* [FashionVictim/FashionVictimModel.py](HARK/FashionVictim/FashionVictimModel.py): - * A very serious model about choosing to dress as a jock or a punk. Used to - demonstrate micro and macro framework concepts from HARKcore. It might be - the simplest model possible for this purpose, or close to it. When run, - the module solves the microeconomic problem of a "fashion victim" for an - example parameter set, then solves the general equilibrium model for an - entire "fashion market" constituting many types of agents, finding a rule - for the evolution of the style distribution in the population that is justi- - fied by fashion victims' collective actions. - -Application modules: - -* [SolvingMicroDSOPs/Code/StructEstimation.py](HARK/SolvingMicroDSOPs/Code/StructEstimation.py): - * Conducts a very simple structural estimation using the idiosyncratic shocks - model in ConsIndShocksModel. Estimates an adjustment factor to an age-varying - sequence of discount factors (taken from Cagetti (2003)) and a coefficient - of relative risk aversion that makes simulated agents' wealth profiles best - match data from the 2004 Survey of Consumer Finance. Also demonstrates - the calculation of standard errors by bootstrap and can construct a contour - map of the objective function. Based on section 9 of Chris Carroll's - lecture notes "Solving Microeconomic Dynamic Stochastic Optimization Problems". -* [cstwMPC/cstwMPC.py](HARK/cstwMPC/cstwMPC.py): - * Conducts the estimations for the paper "The Distribution of Wealth and the - Marginal Propensity to Consume" by Carroll, Slacalek, Tokuoka, and White (2016). - Runtime options are set in SetupParamsCSTW.py, specifying choices such as: - perpetual youth vs lifecycle, beta-dist vs beta-point, liquid assets vs net - worth, aggregate vs idiosyncratic shocks, etc. Uses ConsIndShockModel and - ConsAggShockModel; can demonststrate HARK's "macro" framework on a real model. -* [cstwMPC/MakeCSTWfigs.py](HARK/cstwMPC/MakeCSTWfigs.py): - * Makes various figures for the text of the [cstwMPC](http://econ.jhu.edu/people/ccarroll/papers/cstwMPC) paper. Requires many output - files produced by cstwMPC.py, from various specifications, which are not - distributed with HARK. Has not been tested in quite some time. -* [cstwMPC/MakeCSTWfigsForSlides.py](HARK/cstwMPC/MakeCSTWfigsForSlides.py): - * Makes various figures for the slides for the cstwMPC paper. Requires many - output files produced by cstwMPC.py, from various specifications, which are not - distributed with HARK. Has not been tested in quite some time. - -Parameter and data modules: -* [ConsumptionSaving/ConsumerParameters.py](HARK/ConsumptionSaving/ConsumerParameters.py): - * Defines dictionaries with the minimal set of parameters needed to solve the - models in ConsIndShockModel, ConsAggShockModel, ConsPrefShockModel, and - ConsMarkovModel. These dictionaries are used to make examples when those - modules are run. Does nothing when run itself. -* [SolvingMicroDSOPs/SetupSCFdata.py](HARK/SolvingMicroDSOPs/Calibration/SetupSCFdata.py): - * Imports 2004 SCF data for use by SolvingMicroDSOPs/StructEstimation.py. -* [cstwMPC/SetupParamsCSTW.py](HARK/cstwMPC/SetupParamsCSTW.py): - * Loads calibrated model parameters for cstwMPC.py, chooses specification. -* [FashionVictim/FashionVictimParams.py](HARK/FashionVictim/FashionVictimParams.py): - * Example parameters for FashionVictimModel.py, loaded when that module is run. - -Test modules: -* [Testing/Comparison_UnitTests.py](Testing/Comparison_UnitTests.py): - * Early version of unit testing for HARK, still in development. Compares - the perfect foresight model solution to the idiosyncratic shocks model - solution with shocks turned off; also compares the tractable buffer stock - model solution to the same model solved using a "Markov" description. -* [Testing/ModelTesting.py](Testing/ModelTesting.py): - * Early version of unit testing for HARK, still in development. Defines a - few wrapper classes to run unit tests on subclasses of AgentType. -* [Testing/TractableBufferStockModel_UnitTests.py](Testing/TractableBufferStockModel_UnitTests.py) - * Early version of unit testing for HARK, still in development. Runs a test - on TractableBufferStockModel. -* [Testing/MultithreadDemo.py](Testing/MultithreadDemo.py): - * Demonstrates the multithreading functionality in HARKparallel.py. When - run, it solves oneexample consumption-saving model with idiosyncratic - shocks to income, then solves *many* such models serially, varying the - coefficient of relative risk aversion between rho=1 and rho=8, displaying - the results graphically and presenting the timing. It then solves the - same set of many models using multithreading on the local CPU, displays - the results graphically along with the timing. - -Data files: -* [SolvingMicroDSOPs/Calibration/SCFdata.csv](HARK/SolvingMicroDSOPs/Calibration/SCFdata.csv): - * SCF 2004 data for use in SolvingMicroDSOPs/StructEstimation.py, loaded by - SolvingMicroDSOPs/EstimationParameters.py. -* [cstwMPC/SCFwealthDataReduced.txt](HARK/cstwMPC/SCFwealthDataReduced.txt): - * SCF 2004 data with just net worth and data weights, for use by cstwMPC.py -* [cstwMPC/USactuarial.txt](HARK/cstwMPC/USactuarial.txt): - * U.S. mortality data from the Social Security Administration, for use by - cstwMPC.py when running a lifecycle specification. -* [cstwMPC/EducMortAdj.txt](HARK/cstwMPC/EducMortAdj.txt): - * Mortality adjusters by education and age (columns by sex and race), for use - by cstwMPC.py when running a lifecycle specification. Taken from [Brown et al. (2002)](https://www.nber.org/chapters/c9757). - -Other files that you don't need to worry about: -* /index.py: - * A file used by Sphinx when generating html documentation for HARK. Users - don't need to worry about it. Several copies are found throughout HARK. -* [.gitignore](.gitignore): - * A file that tells git which files (or types of files) might be found in - the repository directory tree, but should be ignored (not tracked) for - the repo. Currently ignores compiled Python code, LaTex auxiliary files, etc. -* [LICENSE](LICENSE): - * License text for HARK, Apache 2.0. Read it if you're a lawyer! -* [SolvingMicroDSOPs/Figures/SMMcontour.png](HARK/SolvingMicroDSOPs/Figures/SMMcontour.png): - * Contour plot of the objective function for SolvingMicroDSOPs/StructEstimation.py. - Generated when that module is run, along with a PDF version. -* [cstwMPC/Figures/placeholder.txt](HARK/cstwMPC/Figures/placeholder.txt): - * A placeholder file because git doesn't like empty folders, but cstwMPC.py - needs the /Figures directory to exist when it runs. -* [Documentation/conf.py](Documentation/conf.py): - * A configuration file for producing html documentation with Sphinx, generated - by sphinx-quickstart. -* [Documentation/includeme.rst](Documentation/includeme.rst): - * A very small file used by Sphinx to produce documentation. -* [Documentation/index.rst](Documentation/index.rst): - * A list of modules to be included in HARK's Sphinx documentation. This should - be edited if a new tool or model module is added to HARK. -* [Documentation/instructions.md](Documentation/instructions.md): - * A markdown file with instructions for how to set up and run Sphinx. You - don't need to read it. -* [Documentation/simple-steps-getting-sphinx-working.md](Documentation/simple-steps-getting-sphinx-working.md): - * Another markdown file with instructions for how to set up and run Sphinx. -* [Documentation/make.bat](Documentation/make.bat): - * A batch file for producing Sphinx documentation, generated by sphinx-quickstart. -* [Documentation/Makefile](Documentation/Makefile): - * Another Sphinx auxiliary file generated by sphinx-quickstart. -* [Documentation/econtex.sty](Documentation/econtex.sty): - * LaTeX style file with notation definitions. -* [Documentation/econtex.cls](Documentation/econtex.cls): - * LaTeX class file with document layout for the user manual. -* [Documentation/econtexSetup.sty](Documentation/econtexSetup.sty): - * LaTeX style file with notation definitions. -* [Documentation/econtexShortcuts.sty](Documentation/econtexShortcuts.sty): - * LaTeX style file with notation definitions. -* [Documentation/UserGuidePic.pdf](Documentation/UserGuidePic.pdf): - * Image for the front cover of the user guide, showing the consumption - function for the KinkyPref model. - - -## IV. WARNINGS AND DISCLAIMERS +HARK provides a modular and extensible open-source toolkit for solving heterogeneous-agent partial-and general-equilibrium structural models. The code for such models has always been handcrafted, idiosyncratic, poorly documented, and sometimes not generously shared from leading researchers to outsiders. The result being that it can take years for a new researcher to become proficient. By building an integrated system from the bottom up using object-oriented programming techniques and other tools, we aim to provide a platform that will become a focal point for people using such models. -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)! +HARK is written in Python, making significant use of libraries such as numpy and scipy which offer a wide array of mathematical and statistical functions and tools. Our modules are generally categorized into Tools (mathematical functions and techniques), Models (particular economic models and solvers) and Applications (use of tools to simulate an economic phenomenon). + +For more information on how you can create your own Models or use Tools and Model to create Applications please see the [Architecture documentation](./doc/architecture/README.md). + +### Contributing to HARK + +**We want contributing to Econ-ARK to be fun, enjoyable, and educational for anyone, and everyone.** + +Contributions go far beyond pull requests and commits. Although we love giving you the opportunity to put your stamp on HARK, we are also thrilled to receive a variety of other contributions including: +* Documentation updates, enhancements, designs, or bugfixes +* Spelling or grammar fixes +* REAME.md corrections or redesigns +* Adding unit, or functional tests +* [Triaging GitHub issues](https://github.com/econ-ark/HARK/issues?utf8=%E2%9C%93&q=label%3A%E2%80%9DTag%3A+Triage+Needed%E2%80%9D+) -- e.g. pointing out the relevant files, checking for reproducibility +* [Searching for #econ-ark on twitter](https://twitter.com/search?q=webpack) and helping someone else who needs help +* Answering questions from StackOverflow tagged with [econ-ark](https://stackoverflow.com/questions/tagged/econ-ark) +* Teaching others how to contribute to HARK +* Blogging, speaking about, or creating tutorials about HARK +* Helping others in our mailing list + +If you are worried or don’t know how to start, you can always reach out to the [TSC](#tsc-technical-steering-committee) or simply submit [an issue](https://github.com/econ-ark/HARK/issues/new) and a member can help give you guidance! + +**After your first contribution please let us know and we will add you to the Contributors list below!** + +To install for development see the [Quickstart Guide](./Documentation/readme.md#ii-quick-start-guide). +For more information on contributing to HARK please see [CONTRIBUTING.md](./CONTRIBUTING.md). -## V. License +## Current Project Team Members -All of HARK is licensed under the Apache License, Version 2.0 (ALv2). Please see -the LICENSE file for the text of the license. More information can be found at: -http://www.apache.org/dev/apply-license.html +For information about the governance of the Econ-ARK project, see +[GOVERNANCE.md](./GOVERNANCE.md). + +Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in maintaining the Econ-ARK project. + +### Founders +Econ-ARK was created by [**Christopher D. Carroll**](http://www.econ2.jhu.edu/people/ccarroll/), Professor of Economics at the Johns Hopkins University. + +Founders of the current repository also include: +* [shaunagm](https://github.com/shaunagm) - **Shauna Gordon-McKeon** <shaunagm@gmail.com> (she/her) +* [sbrice](https://github.com/sbrice) - [**Samuel Brice**](https://medium.com/@sbrice) <brices@gmail.com> (he/him) + +### TSC (Technical Steering Committee) +* [llorracc](https://github.com/llorracc) - [**Christopher “Chris” D. Carroll**]((http://www.econ2.jhu.edu/people/ccarroll/)) <ccarroll@llorracc.org> (he/him) +* [sbrice](https://github.com/sbrice) - [**Samuel Brice**](https://medium.com/@sbrice) <brices@gmail.com> (he/him) +* [shaunagm](https://github.com/shaunagm) - **Shauna Gordon-McKeon** <shaunagm@gmail.com> (she/her) + +### Collaborators +* [albop](https://github.com/albop) - **Pablo Winant** <pablo.winant@gmail.com> (he/him) +* [DrDrij](https://github.com/DrDrij) - **Andrij Stachurski** <dr.drij@gmail.com> (he/him) + +### Release Team +* [shaunagm](https://github.com/shaunagm) - **Shauna Gordon-McKeon** <shaunagm@gmail.com> (she/her) + +## Contributors +* [ericholscher](https://github.com/ericholscher) - **Eric Holscher** (he/him) + +## 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)! diff --git a/doc/architecture/README.md b/doc/architecture/README.md new file mode 100644 index 000000000..2e4b3a28b --- /dev/null +++ b/doc/architecture/README.md @@ -0,0 +1,3 @@ +# HARK Component Architecture + +* [A User's Guide for HARK](https://github.com/econ-ark/HARK/blob/master/Documentation/HARKmanual.pdf) \ No newline at end of file diff --git a/doc/guides/contributing/issues.md b/doc/guides/contributing/issues.md new file mode 100644 index 000000000..b6ec059f5 --- /dev/null +++ b/doc/guides/contributing/issues.md @@ -0,0 +1,3 @@ +# Issues + +This guide is not yet drafted. Visit the [legacy documentation](https://github.com/econ-ark/HARK/tree/master/Documentation) for more info. \ No newline at end of file diff --git a/doc/guides/contributing/pull-requests.md b/doc/guides/contributing/pull-requests.md new file mode 100644 index 000000000..af2cc9097 --- /dev/null +++ b/doc/guides/contributing/pull-requests.md @@ -0,0 +1,3 @@ +# Pull Requests + +This guide is not yet drafted. Visit the [legacy documentation](https://github.com/econ-ark/HARK/tree/master/Documentation) for more info. \ No newline at end of file diff --git a/doc/images/econ-ark-logo.png b/doc/images/econ-ark-logo.png new file mode 100644 index 000000000..e9db35a23 Binary files /dev/null and b/doc/images/econ-ark-logo.png differ diff --git a/doc/images/numfocus-logo.png b/doc/images/numfocus-logo.png new file mode 100644 index 000000000..4a6f9a48c Binary files /dev/null and b/doc/images/numfocus-logo.png differ diff --git a/doc/images/usage-agent-problem-bellman-form.png b/doc/images/usage-agent-problem-bellman-form.png new file mode 100644 index 000000000..1c936deb0 Binary files /dev/null and b/doc/images/usage-agent-problem-bellman-form.png differ diff --git a/doc/images/usage-crra-utility-function.png b/doc/images/usage-crra-utility-function.png new file mode 100644 index 000000000..be3fcf42c Binary files /dev/null and b/doc/images/usage-crra-utility-function.png differ diff --git a/doc/release/README.md b/doc/release/README.md new file mode 100644 index 000000000..9c77912a5 --- /dev/null +++ b/doc/release/README.md @@ -0,0 +1,5 @@ +# HARK Release Instructions + +[Release Management](https://github.com/econ-ark/OverARK/wiki/Release-Management) + +[Packaging HARK](https://github.com/econ-ark/HARK/blob/master/Documentation/packaging.md) \ No newline at end of file