Reorganize OverARK

roadmap/MakeHARKworkflow.py

@@ -0,0 +1,51 @@
+'''
+Make a quick workflow diagram for HARK meeting.
+'''
+import graphviz
+
+HARKflow = graphviz.Digraph(comment='workflow for HARK')
+
+HARKflow.node('HARK1', 'HARK 1.0', rank='sink')
+
+with HARKflow.subgraph() as x:
+    x.attr(rank='same')
+    x.node('params','parameter \n improvements')
+    x.node('solve', 'solver \n improvements')
+    x.node('sim', 'simulation \n improvements')
+
+with HARKflow.subgraph() as y:
+    y.attr(rank='same')
+    y.node('A', 'undo hierarchy \n among solvers')
+    y.node('B', 'automated simulation \n from model dynamics')
+    y.node('C2', 'rewrite input \n constructors')
+    y.node('D', 'add "parameters \n block" to models')
+    y.node('H', 'multiple "modes" \n for simulation')
+
+with HARKflow.subgraph() as z:
+    z.attr(rank='same')
+    z.node('F', 'make parser for simulation', shape='rectangle')
+    z.node('G', 'make parser for auto-solution', shape='rectangle')
+    z.node('I', 'make "type \n constructor"', shape='rectangle')
+
+HARKflow.node('C1', 'new system for \n constructed inputs')
+HARKflow.node('E', 'design micro \n syntax for DSL', shape='rectangle', rank='source')
+
+HARKflow.edge('params','HARK1')
+HARKflow.edge('solve','HARK1')
+HARKflow.edge('sim','HARK1')
+HARKflow.edge('C1','C2')
+HARKflow.edge('C2','params')
+HARKflow.edge('D','params')
+HARKflow.edge('A','solve')
+HARKflow.edge('B','sim')
+HARKflow.edge('H','sim')
+HARKflow.edge('E','I')
+HARKflow.edge('E','F')
+HARKflow.edge('E','G')
+HARKflow.edge('I','C2',style='invis')
+HARKflow.edge('I','params')
+HARKflow.edge('G','solve')
+HARKflow.edge('F','sim')
+
+
+

roadmap/memos/.gitignore

@@ -0,0 +1,2 @@
+# MyST build outputs
+_build

roadmap/memos/Schmidt/CoverEmailForSchmidt.tex

@@ -0,0 +1,66 @@
+       \documentclass[12pt,pdftex,letterpaper]{article}
+            \usepackage{setspace}
+            \usepackage[dvips,]{graphicx} %draft option suppresses graphics dvi display
+%            \usepackage{lscape}
+%            \usepackage{latexsym}
+%            \usepackage{endnotes}
+%            \usepackage{epsfig}
+            \usepackage{amsmath}
+%           \singlespace
+            \setlength{\textwidth}{6.5in}
+            \setlength{\textheight}{9in}
+            \addtolength{\topmargin}{-\topmargin} 
+            \setlength{\oddsidemargin}{0in}
+            \setlength{\evensidemargin}{0in}
+            \addtolength{\headsep}{-\headsep}
+            \addtolength{\topskip}{-\topskip}
+            \addtolength{\headheight}{-\headheight}
+            \setcounter{secnumdepth}{2}
+%            \renewcommand{\thesection}{\arabic{section}}
+            % \renewcommand{\footnote}{\endnote}
+            \newtheorem{proposition}{Proposition}
+            \newtheorem{definition}{Definition}
+            \newtheorem{lemma}{lemma}
+            \newtheorem{corollary}{Corollary}
+            \newtheorem{assumption}{Assumption}
+            \newcommand{\Prob}{\operatorname{Prob}}
+            \clubpenalty 5000
+            \widowpenalty 5000
+            \renewcommand{\baselinestretch}{1.1}
+            \usepackage{amsmath}
+            \usepackage{amsthm}
+            \usepackage{amsfonts}
+            \usepackage{amssymb}
+            \usepackage{bbm}
+            \newcommand{\N}{\mathbb{N}}
+			\newcommand{\R}{\mathbb{R}}
+			\newcommand{\E}{\mathbb{E}}
+			\newcommand{\der}[2]{\frac{\text{d}#1}{\text{d}#2}}
+			\newcommand{\pd}[2]{\frac{\partial#1}{\partial#2}}
+
+			\setlength{\parindent}{0pt}
+			\setlength{\parskip}{1em}
+
+\begin{document}
+	\pagestyle{empty}
+
+Jim:
+
+Jim:
+
+"consumption Carroll" here!
+
+Our previous email chain was the result of your contacting me to see if we needed funding for the [Econ-ARK](https://econ-ark.org) project.  At that time, we'd recently received a generous grant from the Sloan Foundation-- I think my response was along the lines of  "we need people, not money!''  Since then, we have found (some of) the right people and have made great progress.   
+
+Having completed most of what we originally envisioned, we now have ambitious ideas for our next steps. (I'm attaching a brief letter of interest describing our proposed work, and its virtues.)  In short, Econ-ARK wants to create a modeling framework (like, a much more powerful version of DYNARE) that encompasses the wide array of features that can be included in either micro or macro dynamic structural models -- basically, we want to create a way to represent any Bellman problem.  The idea is to design a specification (that is both human- and machine-readable) for describing the mathematical content of models, as well as the numeric methods used to solve them.
+
+I'm reaching out now because, if you're amenable, this is the right time to get help from Schmidt Futures, both with respect to funding and personnel. You mentioned that the organization has several Googlers emeriti, and their technical expertise could be tremendously valuable to us.  
+
+It would be great if we could set up a meeting with you to discuss all this (or, someone else if that would be more appropriate).
+
+Thank you very much, and I hope you are well.
+
+~~~~~---CDC
+
+
+\end{document}

roadmap/memos/Sloan/2024-Small-Grant/EconARKpointsForLoS-email.md

@@ -0,0 +1,21 @@
+Dear John:
+
+The next phase of the Econ-ARK project aims to develop something like the DYNARE `mod file` syntax, but capable of representing ANY Markov decision problem (including, but not limited to, any Bellman problem). The chief purpose of this email is to ask if you would be willing to help advise us as we pursue this goal.
+
+You can find an overview of what we have done and what we intend to do at our [this link]().
+
+The role we hope you can play is described in 
+
+
+
+I'm using the word `representing` because the idea is NOT to tie the model representation to any specific solution method or toolkit. Instead, it is to provide a complete specification of the problem, which could be ingested by ANY compatible solution engine, which could then go to work solving the problem. 
+
+We plan to use the tools we have already developed in the HARK toolkit to provide an example solution engine capable of solving the particular models we know our tools can solve. We also aim to provide examples of how to use existing tools, like Michael Reiter's toolkit and Robert Kirkby's VFI toolkit and Pablo Winant's Dolo, as the solution engine for models that they are capable of handling.
+
+Developing a model-description standard like this will require iterative feedback from economists with experience and knowledge about the theoretical foundations, scope, and breadth of dynamic modeling. We would like you to participate in this process as part of a working group, periodically providing constructive criticism on draft versions of the language specification. For example, feedback on whether it can encompass the range of models you have studied (or have considered) in your own projects. 
+
+We have already developed a very primitive sketch of such a standard, which builds on Winant's Dolo framework. The next step (assuming we continue to have funding) is to convene an in-person meeting for the working group to help guide us in further development of the standard.
+
+We are applying for a grant from the Sloan Foundation to pursue this project. Sloan's guidelines say: "If the success of the project depends on the support of key figures or institutions other than the project lead or project team, the proposal must include an appendix with a letter from each, articulating the nature of their relationship to the project and their understanding of the role they expect to play in the project’s success."
+
+If you are willing to help, your letter can be addressed to Daniel L. Goroff, Economics Program Director, Alfred P. Sloan Foundation. I have attached a memo that summarizes Econ-ARK's work so far, and provides some additional details about our current direction and this project.

roadmap/memos/Sloan/2024-Small-Grant/EconARKpointsForLoS.md

@@ -0,0 +1,195 @@
+# Working Group on Model Development
+
+To implement the goals in the [roadmap](https://)
+
+
+**Overview:** [Econ-ARK](https://econ-ark.org/) is developing a
+[*modeling language*](https://ampl.com/wp-content/uploads/amlopt.pdf)
+for representing dynamic structural models. This memo summarizes what
+we've done so far and what we aim to do next.
+
+**What Econ-ARK Has Done:** Our progress since founding in 2016 is
+summarized here. Our primary software output is
+[HARK](https://github.com/econ-ark/HARK), a Python package for solving
+and simulating heterogeneous agents (HA) macroeconomic models.
+
+-   HARK is a framework for HA models that makes it easy to add or
+    change *ex ante* heterogeneity among agents, in both infinite
+    horizon and lifecycle frameworks.
+
+-   You can install it from the command line (`pip install econ-ark`) or
+    see a gentle introduction
+    [here](https://econ-ark.org/materials/gentle-intro-to-hark/).
+
+-   Includes [representations of
+    variations](https://docs.econ-ark.org/Documentation/reference/index.html)
+    on the canonical consumption-saving problem, including: shocks to
+    marginal utility of consumption, a second consumption good with
+    random marginal utility, aggregate productivity shocks, an exogenous
+    discrete state, endogenous labor supply, portfolio allocation,
+    non-normalizable income processes, etc.
+
+-   Also has a
+    [framework](https://docs.econ-ark.org/Documentation/reference/tools/core.html#HARK.core.Market)
+    for representing (and solving for) aggregative equilibrium, using a
+    generalized Krusell-Smith-style algorithm.
+
+-   Can be used for structural micro as well, e.g. [endogenous pricing
+    of health insurance](http://www.mnwhite.org/DynInsSelPaper.pdf).
+
+-   Has
+    [tools](https://github.com/econ-ark/HARK/blob/master/HARK/dcegm.py)
+    for discrete-continuous choice models, with an [example
+    implementation](https://econ-ark.org/materials/endogenousretirement/).
+
+-   Recently begun
+    [integrating](https://docs.econ-ark.org/examples/ConsNewKeynesianModel/SSJ_example.html)
+    with the [SSJ
+    toolkit](https://github.com/shade-econ/sequence-jacobian) to enable
+    analysis of (e.g.) HANK models in HARK.
+
+-   Models are [*documented* to
+    explain](https://docs.econ-ark.org/Documentation/reference/ConsumptionSaving/ConsRiskyAssetModel.html#HARK.ConsumptionSaving.ConsRiskyAssetModel.IndShockRiskyAssetConsumerType)
+    what they mean/do, but these equations (etc) are not *encoded* in
+    HARK itself. *That's what we're going to change with this grant.*
+
+Econ-ARK has also designed the
+[REMARK](https://github.com/econ-ark/REMARK) structure for archiving
+research projects and reproductions of other papers that use HARK. *This
+grant application is not about REMARKs.* You might be interested in the
+reproductions of Jeppe Druedahl's
+[guide](https://econ-ark.org/materials/durableconsumertype/) to
+non-convex consumption-saving models, the [deep learning
+method](https://econ-ark.org/materials/deep-learning-euler-method-krusell-smith/)
+from Maliar, Maliar, & Winant (2018), and Alan Lujan's $\text{EGM}^n$
+[method notebook](https://econ-ark.org/materials/sequentialegm/).
+
+**What We're Trying to Address:** In broad terms, our organizational
+focus is on reproducibility and robustness in economic research. We
+don't think there's a "replicability crisis" *per se* (at least, not
+yet), but we want to address the following significant issues related to
+replicability:
+
+-   Exact model specifications, and especially computational and numeric
+    details of the solution and/or estimation method, are not well
+    communicated in published research.
+
+-   Dependency of economic conclusions on obscure arbitrary choices
+    (e.g., approximation gridpoints)
+
+-   Implementation details might be in online appendix, or only in the
+    code itself.
+
+-   Impact of these details on conclusions is not really probed in the
+    refereeing process.
+
+-   Reproducing or replicating someone else's project often "starts from
+    zero".
+
+-   There is no easy way to directly compare two implementations of the
+    same project or idea, and even verifying that two things are
+    tackling "the same" problem is difficult.
+
+**What We're Going to Do:** Econ-ARK's proposed solution is a new scheme
+for unambiguously specifying both the precise mathematical structure of
+a model *and* the methods and approximations used to numerically solve
+the model and generate output from it.
+
+-   A lot like [DYNARE](https://www.dynare.org/) for a (much) wider
+    class of models: feature set broad enough to be used for HA macro,
+    dynamic structural microeconomics, industrial organization, etc.
+
+-   DYNARE model file contents are strictly informed by DYNARE solution
+    capabilities: can only specify model features that the package is
+    capable of handling.
+
+-   New modeling language *not* tied to any particular software. Meant
+    to be common/shared way to precisely represent models *across*
+    solution methods or software packages.
+
+-   Large feature set informed by *iterative feedback from working group
+    of experts* in the field. If language can't describe a feature they
+    want, then it needs to expand.
+
+-   Will *organize a workshop to present preliminary version* of the
+    language to a working group and solicit feedback. Funding for this
+    event is requested in the grant.
+
+-   HARK doesn't formally represent models internally. Will develop
+    model specification for HARK to inform language design. *This will
+    not restrict the modeling language*.
+
+-   Language will have explicit separation of representation of the
+    "pure mathematical" or "Platonic ideal" model vs computational
+    implementation.
+
+-   This grant application is to make HARK "language compatible" as
+    groundwork, establish working group, begin developing modeling
+    language, and hold workshop.
+
+-   *Completing* development of the language exceeds scope of this
+    grant. We have ambitious future plans for what can be done with the
+    modeling language.
+
+**What We Want to Accomplish:** There are several potential upsides that
+we hope to achieve with this project, some of which we have explicitly
+discussed with you. Your letter need not advocate for the proposal, but
+feel free to use any of these points if you want.
+
+-   Economics is not immune to "failure to replicate," and the reasons
+    can be subtle. There are well-known examples papers in top journals
+    whose results were reversed by due to issues with numeric methods.
+
+-   Frontier models have features that make solution not "well behaved"
+    (e.g. discrete-continuous choice). "Most interesting" papers might
+    be most susceptible to hard-to-detect numeric complications.
+
+-   Even without any new software, a common format for representing
+    choices about numeric integrals, discretized state spaces, etc is a
+    big step in the right direction.
+
+-   Greatly reduces burden on reader / evaluator to understand what was
+    *actually done*-- the *first prerequisite* to independently
+    reproducing the work.
+
+-   Some top journals use a ["data
+    editor"](https://www.econometricsociety.org/publications/es-data-editor-website)
+    who tries to reproduce results in accepted papers, using the
+    authors' own files. Reproduces paper results; does *not* address
+    robustness.
+
+-   "Robustness checks" in refereeing focus on model specification, not
+    numeric details.
+
+-   Systematic representation / documentation of computational methods
+    (etc) could make it feasible to *actually* investigate whether and
+    how "hidden choices" affect conclusions.
+
+-   There is no "standard software" in structural modeling, nor standard
+    *anything*. Other than well known numeric packages (`numpy`,
+    `lapack`), researchers hand code everything.
+
+-   Some economists publish toolkits for solving particular types of
+    models or handling a specific method, but there's no commonality
+    among them or way to link them.
+
+-   Some software tools are "inherited" from adviser or coauthors; need
+    to be an "insider".
+
+-   Some overlap among toolkit capabilities. How does their output
+    compare when given *exact same* problem? Currently no easy way to
+    specify "exact same".
+
+-   Includes AI / deep learning platforms not specifically designed for
+    economics.
+
+-   Common platform for interacting with multiple toolkits would
+    accelerate research.
+
+-   Economists are independent and opinionated. The kinds of economists
+    who will be invited to the workshop have strong opinions about the
+    topic and want to be included.
+
+-   Dynamic models are diverse, many with some "unusual" feature. It
+    would not be reasonable for a small team to "get everything"
+    *without significant outside feedback*.