From e1d10acb58590c81bf04bbc91330b8798c3b054f Mon Sep 17 00:00:00 2001 From: Sijia Wang Date: Tue, 28 Oct 2025 18:46:20 -0400 Subject: [PATCH 1/4] Expand UV installation and usage instructions --- docs/users-guide/modelsetup.rst | 276 ++++++++++++++++++++------------ 1 file changed, 173 insertions(+), 103 deletions(-) diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst index 2398ed3d9..1792f10da 100644 --- a/docs/users-guide/modelsetup.rst +++ b/docs/users-guide/modelsetup.rst @@ -92,8 +92,9 @@ There are two recommended ways to install ActivitySim: 2. Using the :ref:`UV Package and Project Manager` -The first is recommended for users who do not need to change the Python code and are on Windows, -and the second is recommended for users who need to change/customize the Python code. +The first is recommended for users who are new to Python and use Windows, do not actively create and manage Python virtual environments, +and do not need to change the ActivitySim code. The second is recommended for users who actively create and manage Python virtual environments, +and/or want to change/customize the ActivitySim code. Pre-packaged Installer @@ -125,116 +126,113 @@ UV Package and Project Manager ______________________________________ This method is recommended for ActivitySim users who are familiar with -Python and optionally wish to customize the Python code to run their models. +Python, create and manage ActivitySim Python virtual environments, and optionally wish to customize ActivitySim code to run their models. UV is a free open source cross-platform package and project manager that runs on Windows, OS X, and Linux. It is 10-100x faster than conda, and pip itself, which is the standard Python package manager. The *uv* features include automatic environment management including installation and management of Python versions and dependency locking. -.. note:: - There are two options for using *uv* to install ActivitySim. - -The first is to use *uv* to install an official ActivitySim release from the Python Package Index (PyPI). -The second is to use *uv* to install ActivitySim from a local directory, which should be the cloned ActivitySim repository. +Install UV +^^^^^^^^^^^^^^ -.. note:: - The first *uv* option is recommended for users who want to install ActivitySim from an official release and do not wish to change the Python code. - However, they may end up using different deep dependencies than those tested by the developers. - The second *uv* option is recommended for users who may want to customize the Python code, and who want to run ActivitySim - exactly as it was tested by the developers using the dependency lockfile which results in the exact same deep dependencies. +We recommend installing UV as an independent tool on your machine, separate from any existing package managers you may have such as conda or pip. -The steps involved are described as follows. - -Option 1: Install ActivitySim from PyPI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For Windows users, run the following command in PowerShell to install *uv*. It does not require administrator privileges and installs *uv* for the current user only. +by default, uv is installed to `~/.local/bin` directory. Usually, this is `C:/Users//.local/bin`. +:: + # Run the installer. Please review the printed message after installation. + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -(Note: This step may fail at the moment because the ActivitySim version available on PyPI has dependency conflicts. -This step should work when ActivitySim release ** which is built with *uv* is available on PyPI. -In the meantime, use Option 2 below to install ActivitySim from the lockfile.) + # Add uv to PATH + $env:PATH = "$env:USERPROFILE\.local\bin;$env:Path" -1. Install *uv*. Instructions can be found -`here `_. +If an agency wants to install *uv* globally for all users on Windows, run PowerShell as Administrator and run the following command. +:: + # Run the installer with a custom install directory + powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\custom\install\directory";irm https://astral.sh/uv/install.ps1 | iex} -2. Create a new project and virtual environment to work from and add ActivitySim. (Warning: This approach is quickest -for getting started but does not rely on the lockfile to install dependencies so you may -end up with different versions. If you want to use the lockfile, see Option 2 below.) + # Add uv to PATH for all users (requires administrator privileges) + [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\custom\install\directory", [EnvironmentVariableTarget]::Machine) -Open a terminal, such as Command Prompt (note: not Anaconda Prompt), and run the following commands. +For more instructions on installing *uv* on Windows, MacOS, or Linux, please visit https://docs.astral.sh/uv/getting-started/installation/. +To verify that *uv* is installed correctly, open a new Command Prompt (not Anaconda Prompt) and run the following command. :: - mkdir asim_project - cd asim_project - echo 3.10 > .python-version # This sets the Python version to 3.10, which is currently used for ActivitySim development. - uv init - uv add activitysim + uv --version -*uv* will create a new virtual environment within the `asim_project` project folder -and install ActivitySim and its dependencies. The virtual environment is a hidden folder -within the `asim_project` directory called `.venv` and operates the same way as Python's classic *venv*. +.. note:: + If you already have *uv* installed from an older project and you encounter errors + such as + :: -3. Run an ActivitySim command using the following. + error: Failed to parse uv.lock... missing field version... + + later in the process, you may need to update *uv* to the latest version by reinstalling it via the official + installation script: https://docs.astral.sh/uv/getting-started/installation/#standalone-installer. + You can check the version of *uv* you have installed by running + :: -:: + uv --version - uv run ... -For example, run the ActivitySim commandline using the following. -More information about the commandline interface is available in -the :ref:`Ways to Run the Model` section. -:: +Install ActivitySim with UV +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - uv run activitysim run -c configs -o output -d data +There are two options to install ActivitySim using *uv*. +The first is to use *uv* to install an official ActivitySim release from the Python Package Index (PyPI). +The second is to use *uv* to install ActivitySim from the source code repository and use the dependency lockfile. -Run ActivitySim from a Different Directory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you want to run ActivitySim from a directory different than where the code lives, -use the `project` option to point *uv* to this project using relative paths: +.. note:: + The first option (:ref:`From PyPI`) is the quickest way to install ActivitySim from an official release and is recommended for users who do not wish to change the Python code. + However, they may end up using different deep dependencies than those tested by the developers. + The second option (:ref:`From Source with Lockfile`) is recommended for users who may want to customize the Python code, and/or who want to run ActivitySim + exactly as it was tested by the developers using the dependency lockfile which results in the exact same deep dependencies. -:: +The steps involved are described as follows. - uv run --project relative/path/to/asim_project activitysim run -c configs -o output -d data +Option 1: From PyPI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You will use *uv* to create a project and virtual environment to work from and add ActivitySim. -You could also activate the virtual environment created by *uv* and run ActivitySim from any directory. +Open Command Prompt (not Anaconda Prompt), and run the following commands. :: - .venv\Scripts\activate + # create a new project directory and cd into it + mkdir asim_project + cd asim_project -With this command, you have activated the virtual environment created by *uv* and can run ActivitySim commands from any directory. + # initialize a virtual environment + # This sets the Python version to 3.10, which is currently fully tested for ActivitySim development + uv init --python 3.10 -For more on *uv*, visit https://docs.astral.sh/uv/. + # add ActivitySim package from the latest release on PyPI + uv add activitysim -Option 2: Install ActivitySim from the lockfile +*uv* will create a new virtual environment within the `asim_project` project folder +and install ActivitySim and its dependencies. The virtual environment is a hidden folder +within the `asim_project` directory called `.venv` and operates the same way as Python's classic *venv*. You will notice +two new files created in the `asim_project` directory: `pyproject.toml` and `uv.lock`. These files +are automatically created, updated, and used by *uv* to manage your `asim_project` project and its dependencies. +You can share these files with others to recreate the same environment for your `asim_project` project. For more guidance on sharing your working environment, +see the Common Q&A :ref:`How to share my working environment with others?` section below. + +By running the command `uv add activitysim`, you install the official release of ActivitySim from PyPI and its direct dependencies +listed in ActivitySim's `pyproject.toml` file. This approach is the quickest +for getting started but it does not rely on ActivitySim's own lockfile to install deep dependencies so you may +end up with different versions of deep dependencies than those tested by ActivitySim developers. +If you want to ensure exact versions of ActivitySim's deep dependencies, you should install ActivitySim using Option 2: From Source with Lockfile. + +Option 2: From Source with Lockfile ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To install dependencies from the lockfile and run ActivitySim exactly how -its developers tested it, after installing *uv* clone the code repository -and then run code. - -1. Install *uv*. Instructions can be found -`here `_. (Skip -if already installed above. It only needs to be installed once per machine.) - -.. note:: - If you already have *uv* installed from an older project and you encounter errors - such as - :: - - error: Failed to parse uv.lock... missing field version... - - later in the process, you may need to update *uv* to the latest version by reinstalling it via the official - installation script: https://docs.astral.sh/uv/getting-started/installation/#standalone-installer. - You can check the version of *uv* you have installed by running - :: - - uv --version - -1. Clone the ActivitySim project using Git. (If Git is not installed, +its developers tested it, after installing *uv*, open Command Prompt, clone the ActivitySim project using Git. (If Git is not installed, instructions can be found `here `_.) :: @@ -242,56 +240,128 @@ instructions can be found `here `_.) git clone https://github.com/ActivitySim/activitysim.git cd activitysim -3. Optionally create the virtual environment. This is created automatically -when running code in the next step, but manually syncing is an option too. -This step creates a hidden folder within the current directory called -`.venv` and operates the same way as Python's classic *venv*. (If you -want to install the project in a non-editable mode so that users on -your machine cannot accidentally change the source code, use the -`--no-editable` option.) +Run the `uv sync` command to create a virtual environment using the lockfile. It will initialize a virtual environment within the `activitysim` directory +and install ActivitySim and all its dependencies exactly as specified in the `uv.lock` file. +The virtual environment is a hidden folder within the current directory called +`.venv` and operates the same way as Python's classic *venv*. :: - uv sync --no-editable - -4. Run an ActivitySim command using the following. (This will automatically -create a virtual environment from the lockfile, if it does not already -exist.) - -:: - - uv run ... - + uv sync + # or uv sync --no-editable It is worth pointing out that by default, *uv* installs projects in editable mode, such that changes to the source code are immediately reflected -in the environment. `uv sync` and `uv run` both accept a `--no-editable` +in the environment. `uv sync` accepts a `--no-editable` flag, which instructs *uv* to install the project in non-editable mode, removing any dependency on the source code. -Also, `uv run` automatically installs the dependencies listed in `pyproject.toml` +Also, `uv sync` automatically installs the dependencies listed in `pyproject.toml` under `dependencies` under `[project]`, and it also installs those listed under `dev` under `[dependency-groups]`. If you want to skip the dependency groups entirely with a *uv* install (and only install those that would install via `pip` from 'pypi`), use the `--no-default-groups` flag with `uv sync`. -Run ActivitySim from a Different Directory -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you want to run ActivitySim from a directory different than where the code lives, -use the `project` option to point *uv* to this project using relative paths: -:: +Which Option Should I Use? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - uv run --project relative/path/to/asim_project activitysim run -c configs -o output -d data ++--------------------------------------------------------------------------------+-----------+---------------------------+ +| If I want to ... | From PyPI | From Source with Lockfile | ++================================================================================+===========+===========================+ +| Install an official release of ActivitySim. | Yes | | ++--------------------------------------------------------------------------------+-----------+---------------------------+ +| Install a development version of ActivitySim. | | Yes | ++--------------------------------------------------------------------------------+-----------+---------------------------+ +| Install ActivitySim quickly to run models without changing the code. | Yes | | ++--------------------------------------------------------------------------------+-----------+---------------------------+ +| Do ActivitySim code development. | | Yes | ++--------------------------------------------------------------------------------+-----------+---------------------------+ +| Run ActivitySim with deep dependencies exactly as tested by the developers. | | Yes | ++--------------------------------------------------------------------------------+-----------+---------------------------+ -You could also activate the virtual environment created by *uv* and run ActivitySim from any directory. +Run ActivitySim with UV +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Activate the virtual environment created by *uv*. This option is similar to using Python's classic venv or Conda env. :: + # cd into the project directory if not already there + ## if you used the From PyPI option + cd asim_project + ## if you used the From Source with Lockfile option + cd activitysim + # Activate the virtual environment .venv\Scripts\activate -With this command, you have activated the virtual environment created by *uv* and can run ActivitySim commands from any directory. +Once the virtual environment is activated, you can run ActivitySim commands directly using the `activitysim` command. +For example, run the ActivitySim commandline using the following. More information about the commandline interface is available in +the :ref:`Ways to Run the Model` section. +:: + + activitysim run -c configs -o output -d data -For more on *uv*, visit https://docs.astral.sh/uv/. \ No newline at end of file +Alternatively, you can run ActivitySim commands directly using *uv* without activating the virtual environment. +:: + + uv run activitysim run -c configs -o output -d data + +Common Q&A +^^^^^^^^^^^^^^^^ +My travel demand model requires additional Python packages not included with ActivitySim. How do I add them? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can add additional packages to your *uv* project by using the `uv add` command. For example, to add the `geopandas` package, +run the following command within your existing *uv* project directory. +:: + # cd into your project directory + cd asim_project + + # Add geopandas package + uv add geopandas +This will add the package to your virtual environment and update the `pyproject.toml` and the `uv.lock` file to include the new package and its dependencies. + +If you envision having a version of Python packages that is different from the one used by ActivitySim, e.g., you need pandas 1.x for visualization (for some reason), +we recommend creating a separate *uv* project for your custom packages and managing them independently from ActivitySim. +:: + # Open Command Prompt + mkdir viz_project + cd viz_project + uv init + uv add pandas==1.5.3 + +Many agencies use commerical software that have Python APIs and dependencies that may conflict with ActivitySim dependencies. +In such cases, we also recommend creating a separate *uv* project for the commerical software and managing them independently from ActivitySim. +:: + # Open Command Prompt + mkdir emme_project + cd emme_project + uv init --python 2.7 + # Then copy the emme.pth file (provides EMME API handshakes) from the Emme installation directory to emme_project/.venv/Lib/site-packages/ + +How to share my working environment with others? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can share your working environment with others by sharing the `uv.lock` file located in your project directory. +This file contains the exact versions of all packages and dependencies used in your project. +Others can recreate the same environment by running the `uv sync` command in a new project directory containing the shared `uv.lock` file. +:: + # Copy uv.lock file to new project directory + uv sync + +If I use the From PyPI option to install ActivitySim, would I run into dependency issues? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Using the :ref:`From PyPI` option to install ActivitySim may result in different versions of deep dependencies than those tested by ActivitySim developers. +This is because the :ref:`From PyPI` option installs only the direct dependencies listed in ActivitySim's `pyproject.toml` file, +and relies on *uv* to resolve and install the deep dependencies. It is likely that a newer version of ActivitySim deep dependencies +may cause compatibility issues. For example, see this recent update with `numexpr`: https://github.com/pydata/numexpr/issues/540 + +When that happens, we recommend using the :ref:`From Source with Lockfile` option to install ActivitySim, which ensures that +you are using the exact same deep dependencies as those tested by ActivitySim developers. In the meantime, you can also +report the compatibility issues to the ActivitySim development team via GitHub Issues, so that they can address them in future releases. + +If I want to use `uv run` to run ActivitySim commands, do I still need to activate the virtual environment? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +No, if you use `uv run` to run ActivitySim commands, you do not need to activate the virtual environment first. +However, you will need to call `uv run` in the project directory where the virtual environment is located. Also, like `uv sync`, +`uv run` automatically updates the lockfile and installs any missing dependencies before running the command. From 77059cecbfad8c124464f8287ce4164fd6ef9a80 Mon Sep 17 00:00:00 2001 From: Sijia Wang Date: Fri, 31 Oct 2025 10:03:54 -0400 Subject: [PATCH 2/4] disable auto upgrade --- docs/users-guide/modelsetup.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst index 1792f10da..4b74a404e 100644 --- a/docs/users-guide/modelsetup.rst +++ b/docs/users-guide/modelsetup.rst @@ -240,15 +240,15 @@ instructions can be found `here `_.) git clone https://github.com/ActivitySim/activitysim.git cd activitysim -Run the `uv sync` command to create a virtual environment using the lockfile. It will initialize a virtual environment within the `activitysim` directory +Run the `uv sync --locked` command to create a virtual environment using the lockfile. It will initialize a virtual environment within the `activitysim` directory and install ActivitySim and all its dependencies exactly as specified in the `uv.lock` file. The virtual environment is a hidden folder within the current directory called `.venv` and operates the same way as Python's classic *venv*. :: - uv sync - # or uv sync --no-editable + uv sync --locked + # or uv sync --locked --no-editable It is worth pointing out that by default, *uv* installs projects in editable mode, such that changes to the source code are immediately reflected @@ -344,10 +344,10 @@ How to share my working environment with others? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can share your working environment with others by sharing the `uv.lock` file located in your project directory. This file contains the exact versions of all packages and dependencies used in your project. -Others can recreate the same environment by running the `uv sync` command in a new project directory containing the shared `uv.lock` file. +Others can recreate the same environment by running the `uv sync --locked` command in a new project directory containing the shared `uv.lock` file. :: # Copy uv.lock file to new project directory - uv sync + uv sync --locked If I use the From PyPI option to install ActivitySim, would I run into dependency issues? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 171618d3a9a246fc33704ff5ab7ce7b5760b837e Mon Sep 17 00:00:00 2001 From: Sijia Wang Date: Fri, 31 Oct 2025 10:39:38 -0400 Subject: [PATCH 3/4] Update modelsetup.rst --- docs/users-guide/modelsetup.rst | 53 ++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 11 deletions(-) diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst index 4b74a404e..caf3d707d 100644 --- a/docs/users-guide/modelsetup.rst +++ b/docs/users-guide/modelsetup.rst @@ -139,8 +139,10 @@ Install UV We recommend installing UV as an independent tool on your machine, separate from any existing package managers you may have such as conda or pip. For Windows users, run the following command in PowerShell to install *uv*. It does not require administrator privileges and installs *uv* for the current user only. -by default, uv is installed to `~/.local/bin` directory. Usually, this is `C:/Users//.local/bin`. +By default, uv is installed to `~/.local/bin` directory. Usually, this is `C:/Users//.local/bin`. + :: + # Run the installer. Please review the printed message after installation. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" @@ -148,7 +150,9 @@ by default, uv is installed to `~/.local/bin` directory. Usually, this is `C:/Us $env:PATH = "$env:USERPROFILE\.local\bin;$env:Path" If an agency wants to install *uv* globally for all users on Windows, run PowerShell as Administrator and run the following command. + :: + # Run the installer with a custom install directory powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\custom\install\directory";irm https://astral.sh/uv/install.ps1 | iex} @@ -158,6 +162,7 @@ If an agency wants to install *uv* globally for all users on Windows, run PowerS For more instructions on installing *uv* on Windows, MacOS, or Linux, please visit https://docs.astral.sh/uv/getting-started/installation/. To verify that *uv* is installed correctly, open a new Command Prompt (not Anaconda Prompt) and run the following command. + :: uv --version @@ -165,6 +170,7 @@ To verify that *uv* is installed correctly, open a new Command Prompt (not Anaco .. note:: If you already have *uv* installed from an older project and you encounter errors such as + :: error: Failed to parse uv.lock... missing field version... @@ -172,6 +178,7 @@ To verify that *uv* is installed correctly, open a new Command Prompt (not Anaco later in the process, you may need to update *uv* to the latest version by reinstalling it via the official installation script: https://docs.astral.sh/uv/getting-started/installation/#standalone-installer. You can check the version of *uv* you have installed by running + :: uv --version @@ -187,9 +194,9 @@ The first is to use *uv* to install an official ActivitySim release from the Pyt The second is to use *uv* to install ActivitySim from the source code repository and use the dependency lockfile. .. note:: - The first option (:ref:`From PyPI`) is the quickest way to install ActivitySim from an official release and is recommended for users who do not wish to change the Python code. + The first option (:ref:`Option 1: From PyPI`) is the quickest way to install ActivitySim from an official release and is recommended for users who do not wish to change the Python code. However, they may end up using different deep dependencies than those tested by the developers. - The second option (:ref:`From Source with Lockfile`) is recommended for users who may want to customize the Python code, and/or who want to run ActivitySim + The second option (:ref:`Option 2: From Source with Lockfile`) is recommended for users who may want to customize the Python code, and/or who want to run ActivitySim exactly as it was tested by the developers using the dependency lockfile which results in the exact same deep dependencies. The steps involved are described as follows. @@ -286,7 +293,9 @@ Run ActivitySim with UV ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Activate the virtual environment created by *uv*. This option is similar to using Python's classic venv or Conda env. + :: + # cd into the project directory if not already there ## if you used the From PyPI option cd asim_project @@ -299,11 +308,13 @@ Activate the virtual environment created by *uv*. This option is similar to usin Once the virtual environment is activated, you can run ActivitySim commands directly using the `activitysim` command. For example, run the ActivitySim commandline using the following. More information about the commandline interface is available in the :ref:`Ways to Run the Model` section. + :: activitysim run -c configs -o output -d data Alternatively, you can run ActivitySim commands directly using *uv* without activating the virtual environment. + :: uv run activitysim run -c configs -o output -d data @@ -314,26 +325,33 @@ My travel demand model requires additional Python packages not included with Act ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can add additional packages to your *uv* project by using the `uv add` command. For example, to add the `geopandas` package, run the following command within your existing *uv* project directory. + :: + # cd into your project directory cd asim_project # Add geopandas package uv add geopandas + This will add the package to your virtual environment and update the `pyproject.toml` and the `uv.lock` file to include the new package and its dependencies. If you envision having a version of Python packages that is different from the one used by ActivitySim, e.g., you need pandas 1.x for visualization (for some reason), we recommend creating a separate *uv* project for your custom packages and managing them independently from ActivitySim. + :: + # Open Command Prompt mkdir viz_project cd viz_project uv init uv add pandas==1.5.3 -Many agencies use commerical software that have Python APIs and dependencies that may conflict with ActivitySim dependencies. -In such cases, we also recommend creating a separate *uv* project for the commerical software and managing them independently from ActivitySim. +Many agencies use commercial software that have Python APIs and dependencies that may conflict with ActivitySim dependencies. +In such cases, we also recommend creating a separate *uv* project for the commercial software and managing them independently from ActivitySim. + :: + # Open Command Prompt mkdir emme_project cd emme_project @@ -342,21 +360,34 @@ In such cases, we also recommend creating a separate *uv* project for the commer How to share my working environment with others? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can share your working environment with others by sharing the `uv.lock` file located in your project directory. -This file contains the exact versions of all packages and dependencies used in your project. -Others can recreate the same environment by running the `uv sync --locked` command in a new project directory containing the shared `uv.lock` file. +You can share your working environment with others by sharing the `uv.lock` file and the `pyproject.toml` file located in your project directory. +The `uv.lock` file contains the exact versions of all packages and dependencies used in your project. +Others can recreate the same environment by running the `uv sync --locked` command in a new project directory containing the shared files. + :: + + # Initialize a new project directory + mkdir new_asim_project + cd new_asim_project + + # Copy .python-version file to new project directory (if exists) + copy path\to\shared\.python-version . + # Copy pyproject.toml file to new project directory + copy path\to\shared\pyproject.toml . # Copy uv.lock file to new project directory + copy path\to\shared\uv.lock . + + # Recreate the same environment uv sync --locked If I use the From PyPI option to install ActivitySim, would I run into dependency issues? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Using the :ref:`From PyPI` option to install ActivitySim may result in different versions of deep dependencies than those tested by ActivitySim developers. -This is because the :ref:`From PyPI` option installs only the direct dependencies listed in ActivitySim's `pyproject.toml` file, +Using the :ref:`Option 1: From PyPI` option to install ActivitySim may result in different versions of deep dependencies than those tested by ActivitySim developers. +This is because the :ref:`Option 1: From PyPI` option installs only the direct dependencies listed in ActivitySim's `pyproject.toml` file, and relies on *uv* to resolve and install the deep dependencies. It is likely that a newer version of ActivitySim deep dependencies may cause compatibility issues. For example, see this recent update with `numexpr`: https://github.com/pydata/numexpr/issues/540 -When that happens, we recommend using the :ref:`From Source with Lockfile` option to install ActivitySim, which ensures that +When that happens, we recommend using the :ref:`Option 2: From Source with Lockfile` option to install ActivitySim, which ensures that you are using the exact same deep dependencies as those tested by ActivitySim developers. In the meantime, you can also report the compatibility issues to the ActivitySim development team via GitHub Issues, so that they can address them in future releases. From acee9d4d09ab9b23db4fb37145baada00c82b054 Mon Sep 17 00:00:00 2001 From: Sijia Wang Date: Fri, 7 Nov 2025 16:20:05 -0500 Subject: [PATCH 4/4] address comments --- docs/users-guide/modelsetup.rst | 119 +++++++++++++++++++++++--------- 1 file changed, 87 insertions(+), 32 deletions(-) diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst index caf3d707d..a3293fdbd 100644 --- a/docs/users-guide/modelsetup.rst +++ b/docs/users-guide/modelsetup.rst @@ -139,7 +139,7 @@ Install UV We recommend installing UV as an independent tool on your machine, separate from any existing package managers you may have such as conda or pip. For Windows users, run the following command in PowerShell to install *uv*. It does not require administrator privileges and installs *uv* for the current user only. -By default, uv is installed to `~/.local/bin` directory. Usually, this is `C:/Users//.local/bin`. +By default, uv is installed to ``~/.local/bin`` directory. Usually, this is ``C:/Users//.local/bin``. :: @@ -153,11 +153,11 @@ If an agency wants to install *uv* globally for all users on Windows, run PowerS :: - # Run the installer with a custom install directory - powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\custom\install\directory";irm https://astral.sh/uv/install.ps1 | iex} + # Run the installer with a custom install directory (e.g., C:\shared\uv) that is accessible to all users + powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "C:\shared\uv";irm https://astral.sh/uv/install.ps1 | iex} # Add uv to PATH for all users (requires administrator privileges) - [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\custom\install\directory", [EnvironmentVariableTarget]::Machine) + [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\shared\uv", [EnvironmentVariableTarget]::Machine) For more instructions on installing *uv* on Windows, MacOS, or Linux, please visit https://docs.astral.sh/uv/getting-started/installation/. @@ -221,16 +221,16 @@ Open Command Prompt (not Anaconda Prompt), and run the following commands. # add ActivitySim package from the latest release on PyPI uv add activitysim -*uv* will create a new virtual environment within the `asim_project` project folder +*uv* will create a new virtual environment within the ``asim_project`` project folder and install ActivitySim and its dependencies. The virtual environment is a hidden folder -within the `asim_project` directory called `.venv` and operates the same way as Python's classic *venv*. You will notice -two new files created in the `asim_project` directory: `pyproject.toml` and `uv.lock`. These files -are automatically created, updated, and used by *uv* to manage your `asim_project` project and its dependencies. -You can share these files with others to recreate the same environment for your `asim_project` project. For more guidance on sharing your working environment, +within the ``asim_project`` directory called ``.venv`` and operates the same way as Python's classic *venv*. You will notice +two new files created in the ``asim_project`` directory: ``pyproject.toml`` and ``uv.lock``. These files +are automatically created, updated, and used by *uv* to manage your ``asim_project`` project and its dependencies. +You can share these files with others to recreate the same environment for your ``asim_project`` project. For more guidance on sharing your working environment, see the Common Q&A :ref:`How to share my working environment with others?` section below. -By running the command `uv add activitysim`, you install the official release of ActivitySim from PyPI and its direct dependencies -listed in ActivitySim's `pyproject.toml` file. This approach is the quickest +By running the command ``uv add activitysim``, you install the official release of ActivitySim from PyPI and its direct dependencies +listed in ActivitySim's ``pyproject.toml`` file. This approach is the quickest for getting started but it does not rely on ActivitySim's own lockfile to install deep dependencies so you may end up with different versions of deep dependencies than those tested by ActivitySim developers. If you want to ensure exact versions of ActivitySim's deep dependencies, you should install ActivitySim using Option 2: From Source with Lockfile. @@ -247,10 +247,10 @@ instructions can be found `here `_.) git clone https://github.com/ActivitySim/activitysim.git cd activitysim -Run the `uv sync --locked` command to create a virtual environment using the lockfile. It will initialize a virtual environment within the `activitysim` directory -and install ActivitySim and all its dependencies exactly as specified in the `uv.lock` file. +Run the ``uv sync --locked`` command to create a virtual environment using the lockfile. It will initialize a virtual environment within the ``activitysim`` directory +and install ActivitySim and all its dependencies exactly as specified in the ``uv.lock`` file. The virtual environment is a hidden folder within the current directory called -`.venv` and operates the same way as Python's classic *venv*. +``.venv`` and operates the same way as Python's classic *venv*. :: @@ -259,16 +259,16 @@ The virtual environment is a hidden folder within the current directory called It is worth pointing out that by default, *uv* installs projects in editable mode, such that changes to the source code are immediately reflected -in the environment. `uv sync` accepts a `--no-editable` +in the environment. ``uv sync`` accepts a ``--no-editable`` flag, which instructs *uv* to install the project in non-editable mode, removing any dependency on the source code. -Also, `uv sync` automatically installs the dependencies listed in `pyproject.toml` -under `dependencies` under `[project]`, and it also installs those listed -under `dev` under `[dependency-groups]`. If you want to +Also, ``uv sync`` automatically installs the dependencies listed in ``pyproject.toml`` +under ``dependencies`` under ``[project]``, and it also installs those listed +under ``dev`` under ``[dependency-groups]``. If you want to skip the dependency groups entirely with a *uv* install (and only install those -that would install via `pip` from 'pypi`), use the `--no-default-groups` flag -with `uv sync`. +that would install via ``pip`` from ``pypi``), use the ``--no-default-groups`` flag +with ``uv sync``. Which Option Should I Use? @@ -305,7 +305,7 @@ Activate the virtual environment created by *uv*. This option is similar to usin # Activate the virtual environment .venv\Scripts\activate -Once the virtual environment is activated, you can run ActivitySim commands directly using the `activitysim` command. +Once the virtual environment is activated, you can run ActivitySim commands directly using the ``activitysim`` command. For example, run the ActivitySim commandline using the following. More information about the commandline interface is available in the :ref:`Ways to Run the Model` section. @@ -323,7 +323,7 @@ Common Q&A ^^^^^^^^^^^^^^^^ My travel demand model requires additional Python packages not included with ActivitySim. How do I add them? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can add additional packages to your *uv* project by using the `uv add` command. For example, to add the `geopandas` package, +You can add additional packages to your *uv* project by using the ``uv add`` command. For example, to add the ``geopandas`` package, run the following command within your existing *uv* project directory. :: @@ -334,7 +334,7 @@ run the following command within your existing *uv* project directory. # Add geopandas package uv add geopandas -This will add the package to your virtual environment and update the `pyproject.toml` and the `uv.lock` file to include the new package and its dependencies. +This will add the package to your virtual environment and update the ``pyproject.toml`` and the ``uv.lock`` file to include the new package and its dependencies. If you envision having a version of Python packages that is different from the one used by ActivitySim, e.g., you need pandas 1.x for visualization (for some reason), we recommend creating a separate *uv* project for your custom packages and managing them independently from ActivitySim. @@ -358,11 +358,23 @@ In such cases, we also recommend creating a separate *uv* project for the commer uv init --python 2.7 # Then copy the emme.pth file (provides EMME API handshakes) from the Emme installation directory to emme_project/.venv/Lib/site-packages/ +When having multiple *uv* projects, you can switch between them by activating the respective virtual environments. + +:: + + # Activate visualization project + # Open Command Prompt + cd path\to\viz_project + .venv\Scripts\activate + + # Deactivate visualization project + deactivate + How to share my working environment with others? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can share your working environment with others by sharing the `uv.lock` file and the `pyproject.toml` file located in your project directory. -The `uv.lock` file contains the exact versions of all packages and dependencies used in your project. -Others can recreate the same environment by running the `uv sync --locked` command in a new project directory containing the shared files. +You can share your working environment with others by sharing the ``uv.lock`` file and the ``pyproject.toml`` file located in your project directory (and ``.python-version`` file if it exists). +The ``uv.lock`` file contains the exact versions of all packages and dependencies used in your project. +Others can recreate the same environment by running the ``uv sync --locked`` command in a new project directory containing the shared files. :: @@ -380,19 +392,62 @@ Others can recreate the same environment by running the `uv sync --locked` comma # Recreate the same environment uv sync --locked +Can other users on the same server or machine use my already created virtual environment? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This is doable but it requires additional setup and admin rights - therefore we do not generally recommend it. We recommend following the practice in :ref:`How to share my working environment with others?`. + +If you'd still like to proceed, here are the recommended steps to follow (proceed with caution!): + +1. Ensure that you installed UV globally (requires admin rights) on the server/machine for all users. :ref:`Install UV` section above provides instructions on how to do this. + +2. Assuming you installed UV globally in ``C:\shared\uv\``, ensure that all users have read and execute permissions to this directory. + +3. Create a directory under ``C:\shared\uv\`` to install Python globally for UV. For example, open Command Prompt, create a directory named ``uv_python`` under ``C:\shared\uv\``. + +:: + + cd C:\shared\uv\ + mkdir uv_python + +4. Under Environment Variables > System variables (requires Admin), create a new system environment variable named ``UV_PYTHON_INSTALL_DIR`` and set its value to the Python directory created in step 3 ``C:\shared\uv\uv_python\``. + +5. Run the following command to install Python globally for UV. This should install Python executables globally in the ``UV_PYTHON_INSTALL_DIR`` directory. + +:: + + uv python install 3.10 + +6. Under Environment Variables > System variables (requires Admin), create a new system environment variable named ``UV_PYTHON`` and set its value to the ``python.exe`` created in step 5. + +7. Create a directory to host UV projects under ``C:\shared\uv\`` + +:: + + cd C:\shared\uv\ + mkdir uv_projects + cd uv_projects + +8. Create a new *uv* project and install ActivitySim using either :ref:`Option 1: From PyPI` or :ref:`Option 2: From Source with Lockfile` as described above. + +9. Ensure that all users have read and execute permissions to the shared uv directory. + +:: + + icacls C:\shared\uv /reset /T + If I use the From PyPI option to install ActivitySim, would I run into dependency issues? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the :ref:`Option 1: From PyPI` option to install ActivitySim may result in different versions of deep dependencies than those tested by ActivitySim developers. -This is because the :ref:`Option 1: From PyPI` option installs only the direct dependencies listed in ActivitySim's `pyproject.toml` file, +This is because the :ref:`Option 1: From PyPI` option installs only the direct dependencies listed in ActivitySim's ``pyproject.toml`` file, and relies on *uv* to resolve and install the deep dependencies. It is likely that a newer version of ActivitySim deep dependencies -may cause compatibility issues. For example, see this recent update with `numexpr`: https://github.com/pydata/numexpr/issues/540 +may cause compatibility issues. For example, see this recent update with ``numexpr``: https://github.com/pydata/numexpr/issues/540 When that happens, we recommend using the :ref:`Option 2: From Source with Lockfile` option to install ActivitySim, which ensures that you are using the exact same deep dependencies as those tested by ActivitySim developers. In the meantime, you can also report the compatibility issues to the ActivitySim development team via GitHub Issues, so that they can address them in future releases. -If I want to use `uv run` to run ActivitySim commands, do I still need to activate the virtual environment? +If I want to use ``uv run`` to run ActivitySim commands, do I still need to activate the virtual environment? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -No, if you use `uv run` to run ActivitySim commands, you do not need to activate the virtual environment first. -However, you will need to call `uv run` in the project directory where the virtual environment is located. Also, like `uv sync`, -`uv run` automatically updates the lockfile and installs any missing dependencies before running the command. +No, if you use ``uv run`` to run ActivitySim commands, you do not need to activate the virtual environment first. +However, you will need to call ``uv run`` in the project directory where the virtual environment is located. Also, like ``uv sync``, +``uv run`` automatically updates the lockfile and installs any missing dependencies before running the command.