Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

💻 Work environment and submission workflow

Class 2 — Thursday, August 27

Authors
Affiliations
Stony Brook University

In addition to theory 📖 this course has a strong ⚙️ practical component, with hands-on exercises and a semester-long project. To follow the course effectively you need an environment in which you can run code, version code, and — this is the new part — collaborate with an AI assistant on code without losing control of what it does.

This class sets up all three, plus the workflow you will use to submit every homework: a pull request in your own course repository.

Prerequisites

Python

The course primarily uses numpy, scipy, matplotlib and sympy, and Jupyter to run the notebooks. Nothing fancy is required; no deep learning frameworks, no heavy toolboxes.

The current default: uv

uv is a Python package and project manager that has become the default way to set up scientific Python. It installs Python itself, so you do not need a separate Python install, and it resolves and installs the whole stack in seconds rather than minutes.

# install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# on Windows, in PowerShell:
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# then, inside the course repository
uv venv                      # create .venv with a suitable Python
uv pip install -r requirements.txt
uv run jupyter lab           # run without activating anything

For your own project, prefer a pyproject.toml and let uv maintain a lock file:

uv init                      # writes pyproject.toml
uv add numpy scipy matplotlib sympy jupyter
uv sync                      # reproduces the environment exactly from uv.lock

uv.lock records the exact version of every package, transitively. Commit it. It is the difference between “works on my machine” and a replication package someone can actually run.

The alternative: conda

If you already work in conda, or you need compiled libraries that conda packages better, use Miniforge, which is the conda-forge installer:

conda env create -f environment.yml
conda activate eco629

pixi is a newer conda-compatible manager with uv-style lock files, worth knowing about if you end up in a conda-heavy group.

Versions matter more than you think

It is a good practice to record the versions you use in README. When your work cannot be reproduced two years from now, this is almost always why, and it is a problem.

Your solver converges on your laptop but does not on a classmate’s, same code, same data, same seed. Even worse if it is you and the data editor’s team at the journal! What are the plausible causes?

Where you write code

A good editor is invaluable for editing source files — and it is now also the place where AI assistance lives, which makes the choice less cosmetic than it was.

Git and GitHub

Git is the version control system; GitHub hosts repositories and is where course materials and all homework are distributed and collected.

Account setup, once

  1. Register on GitHub. Be mindful about the personal data you use when registering.

  2. Enable two-factor authentication — required for accounts that contribute code. A passkey or an authenticator app is fine; SMS is the weakest option.

  3. Add an SSH key (or use gh auth login, which sets one up for you). Password authentication for Git operations has not worked since 2021; if a tutorial tells you to type your GitHub password into a terminal, it predates the current world.

  4. Apply for the Student Developer Pack — it includes GitHub Pro, Copilot Pro, extra Codespaces hours and a long list of other services, free while you are a student.

  5. Send me your GitHub username. I will create a private repository for you and invite you to it, together with the repository the tasks are posted in — see Homework submission workflow below. Accept both invitations; nothing works until you do.

Commands worth knowing

git pull upstream main         # collect newly posted tasks
git switch -c alpha            # create and move to a branch (modern `checkout -b`)
git status                     # what is changed, staged, untracked
git add -p                     # stage selected hunks — read your own diff
git commit -m "alpha: bisection solver"
git push -u origin alpha
gh pr create                   # open the pull request without leaving the terminal

If you are on Windows

Everything in this course runs on Windows — Python, Git, Jupyter, the assistants. What differs is the shell you type commands into, and a couple of defaults that produce baffling diffs if left alone.

Use Git Bash

Git for Windows installs Git Bash alongside Git. Use it for everything in these notes, ideally inside Windows Terminal. Every command block in this book then runs exactly as written.

The alternative shells will bite you in small ways:

None of this is fatal, and if you already live in PowerShell you will be fine — but Git Bash is the path of least translation.

Install the GitHub CLI

gh is a separate install; it does not come with Git for Windows. Pick one:

winget install --id GitHub.cli     # preinstalled on Windows 11 and recent Windows 10
scoop install gh
choco install gh

Restart the terminal afterwards so PATH picks it up, then run gh auth login.

gh auth login is also the easiest way through the part of setup that Windows makes fussiest. Choose SSH as the protocol and it generates a key, loads it into the agent, and uploads the public key to GitHub for you. Choose HTTPS and gh auth setup-git registers gh as Git’s credential helper, so there is no key to manage at all. Either way you can skip the manual ssh-keygen, enable-the-service, paste-into- settings sequence.

Line endings

Git for Windows sets core.autocrlf=true, which converts line endings on checkout and commit. Left to itself in a mixed-OS class this produces diffs where every line of a file you never touched is marked as changed.

The course repositories carry a .gitattributes that stores every text file with LF regardless of who commits it, which settles the question. Leave both that file and your core.autocrlf alone. If you do end up with a whole-file diff, fix it once with

git add --renormalize .

Where to put the repository

git config --global core.longpaths true

WSL, if you want it

The Windows Subsystem for Linux gives you a real Linux, and everything in this book then works the Linux way. It is a perfectly good choice, and it is not required. Two rules if you go there: install the tools again inside WSL — a Windows gh or uv is invisible from the Linux side — and keep the repository on the Linux filesystem, since a repository under /mnt/c is slow enough to notice.

Notebooks, and their limits

Editing course notebooks and writing project modules are different activities. Use the notebook for exploration and the editor for anything you will reuse.

Jupyter notebooks are an excellent way to present and discuss code — this entire course is taught with them — and a good instrument for developing ideas. They are saved as JSON with text, LaTeX math, code and code output interleaved.

Their limitations have not changed, and they matter for your project:

However, the tooling around these problems is now good enough that there is no excuse for fighting them:

AI coding assistants

This course is AI-friendly: see the AI policy on the front page. The policy is short — you are responsible for everything you submit, and you must understand every line — and it is examined orally. You also must disclose the use of AI assistants beyond text editing: see the disclosure policy below.

Three kinds of tool

KindExamplesGood for
ChatClaude, ChatGPT, Geminideriving, explaining, checking algebra, talking through a modelling choice
In-editorGitHub Copilot, Cursor, Windsurf, Colab’s assistantcompletion, small refactors, docstrings, tests, “explain this cell”
Agentic CLIClaude Code, Codex CLI, Gemini CLImulti-file work: writing a solver module, running it, reading the traceback, fixing it, repeating

The third category is what changed most recently, and it is the one worth your time this semester. An agentic tool runs in your repository, reads and writes files, and executes commands — so it can close the loop between writing code and finding out that the code is wrong, which is exactly the loop a structural project consists of.

Copilot has a free tier, and Copilot Pro is included in the Student Developer Pack. Colab includes assistance at no cost. Anthropic and OpenAI both offer inexpensive entry plans that include their CLIs. You do not need to pay for all of these; pick one from the second or third row and learn it properly.

Configure the context, not just the prompt

Every one of these tools reads a plain-text instructions file from the repository root — CLAUDE.md, AGENTS.md, or the editor’s equivalent — and treats it as standing instructions. This is where you write down what the assistant cannot infer:

# Project: Rust bus engine replacement, ECO 629

- Python, numpy/scipy only. No deep learning frameworks.
- Value functions are indexed by [state]; replacement-specific value is the first element of the vector; keep that order everywhere.
- Always check Bellman convergence with a monotonicity test before trusting output.
- Never edit files under data/raw/.
- Leave all git operations to me.

Five lines like these are worth more than any amount of prompt phrasing. Commit the file: it documents the project’s conventions for humans too.

Where AI helps

Where it will quietly hurt you

Numerical code fails silently. A wrong Jacobian, a mis-signed log-likelihood, a transition matrix whose rows do not sum to one — all of these produce output, plots, and estimates. Nothing raises an exception. Assistants are fluent at producing plausible numerical code, which means the burden of verification is entirely yours.

Disclosure

This is not an obstacle to clear — it is normal professional practice, and increasingly journal policy. A complete disclosure is short:

Claude Code wrote the EGM interpolation helper and the plotting code; I verified the helper against the analytic solution for the cake-eating case. ChatGPT was used to check the algebra of the Euler equation derivation in Section 2.

Disclosure changes nothing about responsibility. The work is yours, the errors are yours, and the oral exam is about your understanding of every line you submit — see the AI policy. Disclosure exists so that we can talk about how you worked, which is a subject of this course in its own right.

An assistant hands you a working NFXP estimator in five minutes. What do you have, and what do you not have? What would you need to do before you would defend it at the board?

Reproducibility, from day one

Your project is a small replication package. Structural estimates that nobody can reproduce — including you, in six months — are not results.

The AEA Data Editor’s replication policy is the standard your future submissions will be held to, and it is a good template now.

Cloud fallback

Homework submission workflow

You do not fork anything, and you never push to the course repository. Two repositories are involved:

RepositoryWhat it isYour access
fediskhakov/sb-dse-classthe task repository — I push each assignment hereread
fediskhakov/sb-dse-<your-username>your repository for the whole semesterwrite

Your repository is created as a clone of the task repository, so it shares its history: pulling from the task repository brings each new assignment straight into your working copy, all semester, without any copying by hand.

Once, at the start of the semester

  1. Send me your GitHub username

  2. Accept the two invitations GitHub emails you — one to your own repository, one to the task repository

  3. Clone your repository and add the task repository as a second remote:

git clone git@github.com:fediskhakov/sb-dse-<your-username>.git
cd sb-dse-<your-username>
git remote add upstream git@github.com:fediskhakov/sb-dse-class.git
uv tool install nbstripout && nbstripout --install    # conda: conda install -c conda-forge nbstripout

origin is now your repository, upstream is the task repository. Confirm with git remote -v.

For each assignment

git pull upstream main                    # collect newly posted tasks
cp -r tasks/<assignment_name> solutions/<assignment_name>  # copy 
git switch -c <assignment_name>           # one branch per assignment
#  ... solve inside solutions/<assignment_name>/ ...
git add . && git commit -m "<short message describing the work you are submitting>"
git push -u origin <assignment_name>.     # submit
gh pr create --reviewer fediskhakov       # add me as a reviewer

While you work

The line git add . && git commit -m "..." above compresses a whole assignment into one commit. Do not actually work that way. Commit every time something starts working — a function that returns the right value, a plot that comes out, a bug you have just fixed:

git status                      # what have I changed?
git diff                        # what exactly did I change?
git add <path/filename>         # stage one file...
git add -p                      # ...or stage selected hunks, reading as you go
git commit -m "<descriptive commit message>"
git push                        # after the first push -u, plain git push is enough

Ten small commits over three evenings, then the pull request:

Write messages that say what changed and why — “fix bug” is worth nothing three weeks later, “clip the value function at the borrowing constraint” is worth a lot.

Three commands that recover from the usual mistakes:

git commit --amend    # fix the message or add a file to the last commit,
                      # but only if you have not pushed it yet
git restore <file>    # discard uncommitted changes to one file
git stash             # park changes to try something else; git stash pop brings them back

Submitting

The pull request is the submission, and its creation time is the timestamp of record. It stays open until we have discussed the assignment in class; then it is merged into your main, so your main ends the semester as a record of your accepted work.

Homework is discussed at the start of the class that follows it, with one student presenting the solution at the board. The presenter rotates, so plan on presenting several times over the semester — including code that does not work yet, which is usually the more instructive case.

INDEX
📖 Introduction
INDEX
📖 Complexity of algorithms