From 85fb3542ac3649a14906593dcf1f3b26b03a58e1 Mon Sep 17 00:00:00 2001 From: marcelolafleur Date: Tue, 21 Jul 2026 16:15:34 -0400 Subject: [PATCH] Update installation instructions to the uv workflow --- CHANGELOG.md | 21 +++ README.md | 157 +++++++++++++++--- .../content/contributing/contributor_guide.md | 63 ++++--- 3 files changed, 197 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d90aebc..88e4679 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Changed + +- Rewrote the installation instructions. The README now documents two + install paths — the OG family universal installer + (`bash install.sh --repo og-bra`, from OG-Core's `scripts/`) and a + manual uv install — with complete, copy-pasteable per-platform blocks + for macOS, Linux, and Windows, and a "what happens" note for the + example run (runtime, output locations, and the UN Data Portal token + prompt fallback). Removed the PyPI install section and badges: the + `ogbra` package has never been published to PyPI, so `pip install + ogbra` fails for everyone who tries it. +- Updated the contributor guide to the uv workflow: `uv sync --extra + dev` and `uv run` replace the conda environment steps, which have + been broken since `environment.yml` was removed in 0.1.0. Fixed the + test command to this repo's real marker set (`pytest -m "not + local"`; the old text cited OG-USA's `needs_puf`/`regression` + markers and 24-hour suite) and replaced stale `master`-branch + references with `main`. + ## [0.1.0] - 2026-06-25 12:00:00 ### Changed diff --git a/README.md b/README.md index 6676f44..50cbf45 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,155 @@ | | | | --- | --- | | Org | [![PSL cataloged](https://img.shields.io/badge/PSL-cataloged-a0a0a0.svg)](https://www.PSLmodels.org) [![OS License: CC0-1.0](https://img.shields.io/badge/OS%20License-CC0%201.0-yellow)](https://github.com/PSLmodels/OG-BRA/blob/main/LICENSE) | -| Package | [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3119/) [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3129/) [![PyPI Latest Release](https://img.shields.io/pypi/v/ogbra.svg)](https://pypi.org/project/ogbra/) [![PyPI Downloads](https://img.shields.io/pypi/dm/ogbra.svg?label=PyPI%20downloads)](https://pypi.org/project/ogbra/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) | +| Package | [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3119/) [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3129/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) | | Testing | ![example event parameter](https://github.com/PSLmodels/OG-BRA/actions/workflows/build_and_test.yml/badge.svg?branch=main) ![example event parameter](https://github.com/PSLmodels/OG-BRA/actions/workflows/deploy_docs.yml/badge.svg?branch=main) ![example event parameter](https://github.com/PSLmodels/OG-BRA/actions/workflows/check_ruff.yml/badge.svg?branch=main) [![Codecov](https://codecov.io/gh/PSLmodels/OG-BRA/branch/main/graph/badge.svg)](https://codecov.io/gh/PSLmodels/OG-BRA) | OG-BRA is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for Brazil. OG-BRA is built on the OG-Core framework. The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available at https://pslmodels.github.io/OG-Core and documentation of the specific Brazil calibration of the model will be available soon. -## Using and contributing to OG-BRA +## Installation -There are two primary methods for installing and running OG-BRA on your computer locally. The first and simplest method is to download the most recent `ogbra` Python package from the Python Package Index ([PyPI.org](https://pypi.org/project/ogbra/)). The second option is to fork and clone the most recent version of OG-BRA from its GitHub repository and install the `ogbra` package with its development dependencies using `uv`. Both methods are detailed below. +OG-BRA is installed from this GitHub repository. (There is no `pip install ogbra` from PyPI: a PyPI install would not pin the version of OG-Core the model is tested with, and on older Pythons `pip` silently resolves years-old releases. Installing from the repository uses `uv.lock`, which pins the exact tested versions.) -### Installing and Running OG-BRA from PyPI +There are two ways to install. The easy way is the OG family's universal installer, which sets up everything in one step. The manual way does the same steps one at a time. -* On macOS, first install Xcode Command Line Tools (in Terminal: `xcode-select --install`). -* Open your terminal and install the [`ogbra`](https://pypi.org/project/ogbra/) package from the Python Package Index by typing `pip install ogbra`. -* Navigate to a folder `./YourFolderName/` where you want to save scripts to run OG-BRA and output from the simulations in those scripts. -* Copy the python script [`run_og_bra.py`](https://github.com/PSLmodels/OG-BRA/blob/main/examples/run_og_bra.py) from the OG-BRA GitHub repository into your folder as `./YourFolderName/run_og_bra.py`. -* Run the model with an example reform from terminal/command prompt by typing `python run_og_bra.py`. +### The easy way: the universal installer -### Installing and Running OG-BRA from the GitHub repository +The installer needs only [Git](https://git-scm.com/). It installs [`uv`](https://docs.astral.sh/uv/) if needed, clones OG-BRA into a folder named `OG-BRA` inside your current directory, creates a Python environment in `OG-BRA/.venv` with everything the model needs (downloading a compatible Python if necessary), and verifies the installation. -* On macOS, first install Xcode Command Line Tools (in Terminal: `xcode-select --install`). -* Install [`uv`](https://docs.astral.sh/uv/) by following the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/) for your platform (or simply run `pip install uv`). -* Fork this repository and clone your fork to a directory on your computer. -* From the terminal, navigate to the cloned directory and run `uv sync --extra dev` to create a local `.venv` and install OG-BRA with its development dependencies. `uv` will also download a compatible Python interpreter if you don't already have one. -* For docs/Jupyter Book work, also run `uv sync --extra dev --extra docs`. +**macOS** — open Terminal and run each line: + +``` +xcode-select --install +``` + +(That installs Git and Apple's command line tools; it is only needed once, and it is fine if it says the tools are already installed.) Then: + +``` +curl -fsSL https://raw.githubusercontent.com/PSLmodels/OG-Core/master/scripts/install.sh -o install.sh +bash install.sh --repo og-bra --yes +``` + +**Linux** — Git is usually preinstalled (if not, install it with your distribution's package manager, e.g. `sudo apt install git`). Then: + +``` +curl -fsSL https://raw.githubusercontent.com/PSLmodels/OG-Core/master/scripts/install.sh -o install.sh +bash install.sh --repo og-bra --yes +``` + +**Windows** — open PowerShell and run each line: + +``` +winget install --id Git.Git -e --source winget +``` + +Close and reopen PowerShell (so Git is on your PATH), then: + +``` +Invoke-WebRequest -UseBasicParsing -Uri https://raw.githubusercontent.com/PSLmodels/OG-Core/master/scripts/install.ps1 -OutFile install.ps1 +powershell -ExecutionPolicy Bypass -File .\install.ps1 -Repo og-bra -Yes +``` + +More installer options (choosing a destination folder, installing other OG country models) are documented in [OG-Core's quick-install guide](https://github.com/PSLmodels/OG-Core/blob/master/scripts/QUICK_INSTALL.md). + +### Manual install + +**macOS** — open Terminal and run each line: + +``` +xcode-select --install +``` + +``` +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +``` +source $HOME/.local/bin/env +``` + +(That last line puts the just-installed `uv` on the current shell's PATH; new terminal windows will have it automatically.) Then: + +``` +git clone https://github.com/PSLmodels/OG-BRA.git +``` + +``` +cd OG-BRA +``` + +``` +uv sync --extra dev +``` + +**Linux** — same idea, run each line (install Git first with your package manager if it is missing): + +``` +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +``` +source $HOME/.local/bin/env +``` + +``` +git clone https://github.com/PSLmodels/OG-BRA.git +``` + +``` +cd OG-BRA +``` + +``` +uv sync --extra dev +``` + +**Windows** — open PowerShell and run each line: + +``` +winget install --id Git.Git -e --source winget +``` + +``` +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Close and reopen PowerShell (so Git and `uv` are on your PATH), then: + +``` +git clone https://github.com/PSLmodels/OG-BRA.git +``` + +``` +cd OG-BRA +``` + +``` +uv sync --extra dev +``` + +On every platform this leaves you with an `OG-BRA` folder inside the directory where you ran `git clone`, containing the model code and a ready-to-use Python environment in `OG-BRA/.venv`. `uv sync` downloads a compatible Python interpreter if you don't already have one. For docs/Jupyter Book work, also run `uv sync --extra dev --extra docs`. + +If you want to contribute changes rather than just run the model, fork this repository on GitHub first and clone your fork instead; the [contributor guide](docs/book/content/contributing/contributor_guide.md) walks through the whole workflow. ### Run an example of the model -* Navigate to `./examples`. -* Run the model with an example reform: `uv run python run_og_bra.py` (or activate the venv first with `source .venv/bin/activate` on macOS/Linux or `.\.venv\Scripts\Activate.ps1` on Windows, then `python run_og_bra.py`). +From the `OG-BRA` folder: + +``` +cd examples +``` + +``` +uv run python run_og_bra.py +``` + +(`uv run` uses the project's `.venv` automatically. If you prefer to activate the environment first: `source .venv/bin/activate` on macOS/Linux, or `.\.venv\Scripts\Activate.ps1` on Windows, then `python run_og_bra.py`.) + +**What happens when you run it:** + +* If you are connected to the internet, the model refreshes its calibration inputs, including United Nations demographic data. If you are asked for a UN Data Portal API token, just press return — the model falls back to a public data mirror. +* A full run (solving the baseline and reform time paths) takes from about 35 minutes to more than two hours, depending on your machine. * You can adjust the `./examples/run_og_bra.py` by modifying model parameters specified in the dictionary passed to the `p.update_specifications()` calls. * Model outputs will be saved in the following files: * `./examples/OG-BRA_example_plots` @@ -50,8 +169,6 @@ There are two primary methods for installing and running OG-BRA on your computer * See [`ogcore.TPI.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/TPI.py) for what is in the dictionary object in this pickle file * An analogous set of files in the `./examples/OUTPUT_REFORM` directory, which represent objects from the simulation of the reform policy -Note that, depending on your machine, a full model run (solving for the full time path equilibrium for the baseline and reform policies) can take from 35 minutes to more than two hours of compute time. - If you run into errors running the example script, please open a new issue in the OG-BRA repo with a description of the issue and any relevant tracebacks you receive. Once the package is installed, one can adjust parameters in the OG-Core `Specifications` object using the `Calibration` class as follows: @@ -66,7 +183,7 @@ p.update_specifications({'initial_debt_ratio': updated_params['initial_debt_rati ``` ## Disclaimer -The organization of this repository will be changing rapidly, but the `OG-BRA/examples/run_og_bra.py` script will be kept up to date to run with the master branch of this repo. +The organization of this repository will be changing rapidly, but the `OG-BRA/examples/run_og_bra.py` script will be kept up to date to run with the main branch of this repo. ## Core Maintainers diff --git a/docs/book/content/contributing/contributor_guide.md b/docs/book/content/contributing/contributor_guide.md index ba53894..64d547b 100644 --- a/docs/book/content/contributing/contributor_guide.md +++ b/docs/book/content/contributing/contributor_guide.md @@ -11,7 +11,20 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit` (Sec_SetupPython)= ## Setup Python -`OG-BRA` is written in the Python programming language. Download and install the free and most recent Anaconda distribution of Python and associated libraries from [Anaconda.com](https://www.anaconda.com/products/individual#Downloads).[^recent_python] You should do this even if you already have Python installed on your computer because the Anaconda distribution contains additional Python packages that are used by `OG-BRA` (many of which are not included in other Python installations). You can install the Anaconda distribution without having administrative privileges on your computer and the Anaconda distribution will not interfere with any Python installation that came as part of your computer's operating system. +`OG-BRA` is written in the Python programming language, and the project uses [`uv`](https://docs.astral.sh/uv/) to manage Python and all of the packages the model depends on.[^recent_python] You do not need to install Python yourself — `uv` downloads a compatible Python interpreter automatically the first time you set up the project. Install `uv` by following the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/) for your platform. On macOS and Linux: + +``` + $ curl -LsSf https://astral.sh/uv/install.sh | sh + $ source $HOME/.local/bin/env +``` + +(The second line puts the just-installed `uv` on the current shell's PATH; new terminal windows will have it automatically.) On Windows (PowerShell): + +``` + > powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +Then close and reopen PowerShell so `uv` is on your PATH. (Sec_SetupGit)= @@ -42,24 +55,26 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit` OG-BRA$ git remote add upstream https://github.com/PSLmodels/OG-BRA.git ``` -9. Create a conda environment with all of the necessary packages to execute the source code. -The process of creating the `ogbra-dev` conda environment can take up to 10 minutes. The pip install of the `OG-Core` dependency from [pypi.org](https://pypi.org/project/ogcore/). +9. Create the project's Python environment and install `ogbra` with all of its dependencies (including development tools) by running: ``` - OG-BRA$ conda env create + OG-BRA$ uv sync --extra dev ``` -10. The prior command will create a conda environment called `ogbra-dev`. - Activate this environment as follows: + This creates a local virtual environment in `OG-BRA/.venv`, downloads a compatible Python interpreter if needed, and installs the exact package versions pinned in `uv.lock`. It usually takes a minute or two. + +10. You do not need to activate the environment: prefix commands with `uv run` and they execute inside it automatically, for example: ``` - OG-BRA$ conda activate ogbra-dev + OG-BRA$ uv run python examples/run_og_bra.py ``` -11. Once the environment is activated, install the `ogbra` package in the `ogbra-dev` environment with all its modules by executing the following `pip install` command. + If you prefer an activated environment, run `source .venv/bin/activate` (macOS/Linux) or `.\.venv\Scripts\Activate.ps1` (Windows PowerShell). + +11. If you are going to work on the documentation (this Jupyter Book), also install the docs dependencies: ``` - (ogbra-dev) OG-BRA$ pip install -e . + OG-BRA$ uv sync --extra dev --extra docs ``` If you have made it this far, you've successfully made a remote copy (a @@ -95,27 +110,27 @@ situations, in which case other contributors are here to help. make sure you have the latest version of the central OG-BRA repository by executing the following **four** Git commands: - a. Tell Git to switch to the master branch in your local repo. + a. Tell Git to switch to the main branch in your local repo. Navigate to your local `OG-BRA` directory and enter the following text at the command line: ``` - OG-BRA$ git checkout master + OG-BRA$ git checkout main ``` b. Download all of the content from the central `OG-BRA` repo: ``` OG-BRA$ git fetch upstream ``` - c. Update your local master branch to contain the latest content of - the central master branch using [merge](https://help.github.com/articles/github-glossary/#merge). This step ensures that + c. Update your local main branch to contain the latest content of + the central main branch using [merge](https://help.github.com/articles/github-glossary/#merge). This step ensures that you are working with the latest version of OG-BRA: ``` - OG-BRA$ git merge upstream/master + OG-BRA$ git merge upstream/main ``` - d. Push the updated master branch in your local repo to your GitHub repo: + d. Push the updated main branch in your local repo to your GitHub repo: ``` - OG-BRA$ git push origin master + OG-BRA$ git push origin main ``` 2. Create a new [branch](https://help.github.com/articles/github-glossary/#branch) on your local machine. Think of your branches as a way to organize your projects. If you want to work on this documentation, for example, create a separate branch for that work. If you want to change an element of the OG-BRA model, create a different branch for that project: ``` @@ -123,12 +138,12 @@ situations, in which case other contributors are here to help. ``` 3. As you make changes, frequently check that your changes do not introduce bugs or degrade the accuracy of the `OG-BRA`. To do - this, run the following command from the command line from inside - the `/OG-BRA/ogbra/` directory: + this, run the following command from the command line from the + root `OG-BRA` directory: ``` - OG-BRA/ogbra$ pytest -m "not needs_puf and not regression" + OG-BRA$ uv run python -m pytest -m "not local" ``` - Note that running this full suite of tests may take close to 24 hours (depending on your hardware). To run the small set of tests that run on each pull request (and take about 40 minutes), use `pytest -m "not needs_puf and not local and not regression"`. If the tests do not pass, try to fix the issue by using the information provided by the error message. If this isn't possible or doesn't work, the core maintainers are here to help via a [GitHub Issue](https://github.com/PSLmodels/OG-BRA/issues). + This runs the same set of tests that runs on each pull request (the `-m "not local"` marker skips only the slow full example run, which is exercised separately). If the tests do not pass, try to fix the issue by using the information provided by the error message. If this isn't possible or doesn't work, the core maintainers are here to help via a [GitHub Issue](https://github.com/PSLmodels/OG-BRA/issues). 4. Now you're ready to [commit](https://help.github.com/articles/github-glossary/#commit) your changes to your local repo using the code below. The first line of code tells `Git` to track a file. Use "git status" to find all the files you've edited, and "git add" each of the files that you'd like `Git` to track. As a rule, do not add large files. If you'd like to add a file that is larger than 25 MB, please contact the other contributors and ask how to proceed. The second line of code commits your changes to your local repo and allows you to create a commit message; this should be a short description of your changes. @@ -138,10 +153,10 @@ situations, in which case other contributors are here to help. OG-BRA$ git commit -m "[description-of-your-commit]" ``` -5. Periodically, make sure that the branch you created in step 2 is in sync with the changes other contributors are making to the central master branch by fetching upstream and merging upstream/master into your branch: +5. Periodically, make sure that the branch you created in step 2 is in sync with the changes other contributors are making to the central main branch by fetching upstream and merging upstream/main into your branch: ``` OG-BRA$ git fetch upstream - OG-BRA$ git merge upstream/master + OG-BRA$ git merge upstream/main ``` You may need to resolve conflicts that arise when another contributor changed the same section of code that you are changing. Feel free to ask other contributors for guidance if this happens to you. If you do need to fix a merge conflict, re-run the test suite afterwards (step 4.) @@ -151,7 +166,7 @@ situations, in which case other contributors are here to help. ``` 7. From the GitHub.com user interface, [open a pull request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request). -8. When you open a GitHub pull request, a code coverage report will be automatically generated. If your branch adds new code that is not tested, the code coverage percent will decline and the number of untested statements ("misses" in the report) will increase. If this happens, you need to add to your branch one or more tests of your newly added code. Add tests so that the number of untested statements is the same as it is on the master branch. +8. When you open a GitHub pull request, a code coverage report will be automatically generated. If your branch adds new code that is not tested, the code coverage percent will decline and the number of untested statements ("misses" in the report) will increase. If this happens, you need to add to your branch one or more tests of your newly added code. Add tests so that the number of untested statements is the same as it is on the main branch. (Sec_SimpleUsage)= @@ -163,6 +178,6 @@ situations, in which case other contributors are here to help. (Sec_ContribFootnotes)= ## Footnotes -[^recent_python]:The most recent version of Python from Anaconda is Python 3.12. `OG-BRA` is currently tested to run on Python 3.11 and 3.12. +[^recent_python]:`OG-BRA` is currently tested to run on Python 3.11 and 3.12; `uv` selects a compatible interpreter for you automatically. [^commandline_note]:The dollar sign is the end of the command prompt on a Mac. If you are using the Windows operating system, this is usually the right angle bracket (>). No matter the symbol, you don't need to type it (or anything to its left, which shows the current working directory) at the command line before you enter a command; the prompt symbol and preceding characters should already be there.