Expand UV installation and usage instructions

[i-am-sijia]

This pull request substantially revises and expands the documentation for installing and setting up ActivitySim using the UV package and project manager. The changes clarify recommended installation methods for different user types, provide detailed step-by-step instructions for installing UV and ActivitySim (both from PyPI and from source with a lockfile), and introduce a comprehensive Q&A section to address common user scenarios and troubleshooting.

Expanded and Detailed UV Installation Instructions

• Added step-by-step instructions for installing UV on Windows (including user and global installs), updating PATH, and verifying installation, with links to official resources.

Comprehensive ActivitySim Installation Options Guidance and User Recommendations

• Provided thorough instructions for installing ActivitySim using UV both from PyPI and from source with a lockfile, including explanations of the implications for dependency management and reproducibility.
• Clarified which installation method is recommended for different users, specifying criteria such as familiarity with Python, need to customize code, and management of virtual environments.
• Added a comparison table to help users choose between installation options based on their needs (official release, development, reproducibility, etc.).

New Q&A Section for Common User Scenarios

• Introduced a Q&A section addressing how to add additional packages, manage conflicting dependencies, share working environments, handle dependency issues, and clarify when to activate virtual environments versus using uv run.

[Copilot]

Pull Request Overview

This PR reorganizes and expands the UV Package and Project Manager installation documentation for ActivitySim. The documentation is restructured to provide clearer guidance on installation options and includes more detailed instructions for Windows users.

• Reorganized UV installation section with clearer subsections and step-by-step instructions
• Added detailed Windows-specific UV installation instructions with PowerShell commands
• Expanded Option 1 (From PyPI) and Option 2 (From Source with Lockfile) with more context and clarification
• Added new Common Q&A section to address frequently asked questions about UV usage

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jpn--]

Do we want to consider recommending locking uv on a script file for model application use? An example is here. I'm not sure if this is easier or harder for an agency application.

[i-am-sijia]

@jpn-- my understanding is that uv lock --script one_single_script.py is a minimal set up, is fast, but is limited to single scripts (what happens if agencies have multiple scripts?). Is there any additional benefit compared to just setting up a UV project/environment in the normal way? The locking process is not fundamentally different than setting up a UV project/environment so I am open to be convinced either way. Some online posts suggest: "for model applications, use script locking for exploration/prototyping, transition to full project when moving to production or when complexity grows."

[dhensle]

Suggest we add an additional Question here: "Can other users on the same server or machine use my already created virtual environment?"
My understanding is the answer is: "No. When UV installs the dependencies, paths are created specific to the user. As such, if another user tries to activate your virtual environment, that environment will not work for them."

[i-am-sijia]

The answer is Yes, but it requires admin rights and additional setup. I added it to the Q&A and provided some instructions. SANDAG was able to do this. I haven't tested it myself because I do not have admin rights on WSP machines. I think we should advise "This is doable but we do not recommend it. We recommend sharing the lockfile and uv sync"

[jpn--]

I think what @i-am-sijia wrote in this version of the docs is fine. If I were writing it I'd write it in an even more strongly worded manner; an ideal use case is a fully containerized environment where ActivitySim runs in a way where no other user and no other process can interfere with it.