From 237eee71516012868a5f11c1728919c7c18a4818 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sat, 14 Jun 2025 14:54:17 -0500 Subject: [PATCH] Update documentation to use conda instead of mamba * Initial plan for issue * Update documentation to use conda instead of mamba commands Co-authored-by: jpn-- <1036626+jpn--@users.noreply.github.com> * Fix redundant conda package in benchmarking setup command Co-authored-by: jpn-- <1036626+jpn--@users.noreply.github.com> * Remove redundant note about conda activate/deactivate commands Co-authored-by: jpn-- <1036626+jpn--@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jpn-- <1036626+jpn--@users.noreply.github.com> --- docs/benchmarking.rst | 6 ++-- docs/dev-guide/build-docs.md | 2 +- docs/dev-guide/install.md | 12 +++---- docs/gettingstarted.rst | 35 +++++++++--------- docs/users-guide/modelsetup.rst | 45 ++++++++++++------------ docs/users-guide/run_primary_example.rst | 4 +-- 6 files changed, 50 insertions(+), 54 deletions(-) diff --git a/docs/benchmarking.rst b/docs/benchmarking.rst index 83b91b8100..935125956b 100644 --- a/docs/benchmarking.rst +++ b/docs/benchmarking.rst @@ -34,13 +34,13 @@ common repository to which you have write-access. If this isn't already set up on your performance benchmarking machine, you can do all of this setup by following these steps:: - conda create -n ASIM-BENCH mamba git gh -c conda-forge --override-channels + conda create -n ASIM-BENCH git gh -c conda-forge --override-channels conda activate ASIM-BENCH gh auth login # <--- (only needed if gh is not logged in) gh repo clone ActivitySim/activitysim # TEMPORARY: use jpn--/activitysim cd activitysim git switch develop # TEMPORARY: use performance1 branch - mamba env update --file=conda-environments/activitysim-dev.yml + conda env update --file=conda-environments/activitysim-dev.yml cd .. gh repo fork ActivitySim/asim-benchmarks --remote cd asim-benchmarks @@ -61,7 +61,7 @@ consider updating the environment like this:: conda activate ASIM-BENCH cd activitysim git switch develop # TEMPORARY: use performance1 branch - mamba env update --file=conda-environments/activitysim-dev.yml + conda env update --file=conda-environments/activitysim-dev.yml cd .. cd asim-benchmarks git pull diff --git a/docs/dev-guide/build-docs.md b/docs/dev-guide/build-docs.md index dc8c5d67d3..384d0382d3 100644 --- a/docs/dev-guide/build-docs.md +++ b/docs/dev-guide/build-docs.md @@ -22,7 +22,7 @@ main repository (i.e. you should see subdirectories including `activitysim`, ```bash mkdir -p ../.env -mamba env update -p ../.env/DOCBUILD -f conda-environments/docbuild.yml +conda env update -p ../.env/DOCBUILD -f conda-environments/docbuild.yml conda activate ../.env/DOCBUILD cd docs make clean diff --git a/docs/dev-guide/install.md b/docs/dev-guide/install.md index 8f4b07bd8e..970a71d7ad 100644 --- a/docs/dev-guide/install.md +++ b/docs/dev-guide/install.md @@ -8,12 +8,12 @@ testing. ## Package Manager ActivitySim has a lot of dependencies. It's easiest and fastest to install -them using a package manager like conda, or its faster and free sibling -[Mambaforge](https://github.com/conda-forge/miniforge#mambaforge). +them using a package manager like conda. You can also use +[Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) if you prefer. Depending on your security settings, you might need to install in a container like docker, instructions for that are coming soon. -Note that if you are installing `mamba`, you only should install `mamba` +Note that if you choose to install `mamba`, you only should install `mamba` in the *base* environment. If you install `mamba` itself in other environments, it will not function correctly. If you've got an existing conda installation and you want to install mamba into it, you can install mamba into the *base* @@ -29,7 +29,7 @@ While you are at it, if you are a Jupyter user you might want to also install libraries: ```sh -mamba install -n base nb_conda_kernels -c conda-forge +conda install -n base nb_conda_kernels -c conda-forge ``` This will ensure your development environments are selectable as kernels in @@ -38,13 +38,13 @@ Jupyter Notebook/Lab/Etc. ## Environment It's convenient to start from a completely clean conda environment -and git repository. Assuming you have `mamba` installed, and you +and git repository. Using conda (or mamba if you prefer), and you want to install in a new directory called "workspace" run: ```sh mkdir workspace cd workspace -mamba env create -p ASIM-ENV --file https://raw.githubusercontent.com/ActivitySim/activitysim/main/conda-environments/activitysim-dev-base.yml +conda env create -p ASIM-ENV --file https://raw.githubusercontent.com/ActivitySim/activitysim/main/conda-environments/activitysim-dev-base.yml conda activate ./ASIM-ENV git clone https://github.com/ActivitySim/sharrow.git python -m pip install -e ./sharrow diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst index e318cdba58..88209b1eb6 100644 --- a/docs/gettingstarted.rst +++ b/docs/gettingstarted.rst @@ -42,9 +42,9 @@ Installation 1. It is recommended that you install and use a *conda* package manager for your system. One easy way to do so is by using `Mambaforge `__. -Mamba is a free open source cross-platform package manager that runs on -Windows, OS X and Linux and is fully compatible with conda packages. It is -also usually substantially faster than conda itself. +Conda is a free open source cross-platform package manager that runs on +Windows, OS X and Linux. Modern versions of conda have significantly improved +performance compared to older versions. Alternatively, if you prefer a package installer backed by corporate tech support available (for a fee) as necessary, you can install @@ -52,9 +52,8 @@ support available (for a fee) as necessary, you can install although you should consult the `terms of service `__ for this product and ensure you qualify since businesses and governments with over 200 employees do not qualify for free usage. -If you're using `conda` instead of `mamba`, just replace every call to -`mamba` below with `conda`, as they share the same user interface and most -command formats. +You can use `conda` for all the commands below, as it now has the same +performance and capabilities that were previously only available in mamba. 2. If you access the internet from behind a firewall, then you may need to configure your proxy server. To do so, create a `.condarc` file in your @@ -70,7 +69,7 @@ home installation folder, such as: 3. Create a conda environment (basically a Python install just for this project) using conda Prompt (on Windows) or the terminal (macOS or Linux):: - mamba create -n asim python=3.10 activitysim -c conda-forge --override-channels + conda create -n asim python=3.10 activitysim -c conda-forge --override-channels This command will create the environment and install all the dependencies required for running ActivitySim. It is only necessary to create the environment @@ -78,35 +77,35 @@ once per machine, you do not need to (re)create the environment for each session If you would also like to install other tools or optional dependencies, it is possible to do so by adding additional libraries to this command. For example:: - mamba create -n asim python=3.10 activitysim jupyterlab larch -c conda-forge --override-channels + conda create -n asim python=3.10 activitysim jupyterlab larch -c conda-forge --override-channels This example installs a specific version of Python, version 3.10. A similar approach can be used to install specific versions of other libraries as well, including ActivitySim, itself. For example:: - mamba create -n asim python=3.10 activitysim=1.0.2 -c conda-forge --override-channels + conda create -n asim python=3.10 activitysim=1.0.2 -c conda-forge --override-channels Additional libraries can also be installed later. You may want to consider these tools for certain development tasks:: # packages for testing - mamba install pytest pytest-cov coveralls black flake8 pytest-regressions -c conda-forge --override-channels -n asim + conda install pytest pytest-cov coveralls black flake8 pytest-regressions -c conda-forge --override-channels -n asim # packages for building documentation - mamba install sphinx numpydoc sphinx_rtd_theme==0.5.2 -c conda-forge --override-channels -n asim + conda install sphinx numpydoc sphinx_rtd_theme==0.5.2 -c conda-forge --override-channels -n asim # packages for estimation integration - mamba install larch -c conda-forge --override-channels -n asim + conda install larch -c conda-forge --override-channels -n asim # packages for example notebooks - mamba install jupyterlab matplotlib geopandas descartes -c conda-forge --override-channels -n asim + conda install jupyterlab matplotlib geopandas descartes -c conda-forge --override-channels -n asim To create an environment containing all these optional dependencies at once, you can run the shortcut command :: - mamba env create activitysim/ASIM -n asim + conda env create activitysim/ASIM -n asim 4. To use the **asim** environment, you need to activate it @@ -115,9 +114,7 @@ can run the shortcut command conda activate asim The activation of the correct environment needs to be done every time you -start a new session (e.g. opening a new conda Prompt window). Note that -the *activate* and *deactivate* commands to start and stop using environments -are called as `conda` even if you are otherwise using `mamba`. +start a new session (e.g. opening a new conda Prompt window). Alternative Installation Methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -128,7 +125,7 @@ required dependencies installed correctly. If you can use conda for the dependencies, you can get most of the libraries you need from there:: # required packages for running ActivitySim - mamba install cytoolz numpy pandas psutil pyarrow numba pytables pyyaml openmatrix requests -c conda-forge + conda install cytoolz numpy pandas psutil pyarrow numba pytables pyyaml openmatrix requests -c conda-forge # required for ActivitySim version 1.0.1 and earlier pip install zbox @@ -153,7 +150,7 @@ Installing from source is easier if you have all the necessary dependencies alre installed in a development conda environment. Developers can create an environment that has all the optional dependencies preinstalled by running:: - mamba env create activitysim/ASIM-DEV + conda env create activitysim/ASIM-DEV If you prefer to use a different environment name than `ASIM-DEV`, just append `--name OTHERNAME` to the command. Then all that's left to do is install diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst index 2a64830625..eaa3ad2fbc 100644 --- a/docs/users-guide/modelsetup.rst +++ b/docs/users-guide/modelsetup.rst @@ -83,9 +83,9 @@ ________ Activitysim is implemented in the Python programming language. It also uses several open source Python packages such as pandas, numpy, pytables, openmatrix etc. Hence it is recommended that you install and use a *conda* package manager for your system. One easy way to do so is by using `Mambaforge `__. -Mamba is a free open source cross-platform package manager that runs on -Windows, OS X and Linux and is fully compatible with conda packages. It is -also usually substantially faster than conda itself. Instructions to install mambaforge can be found `here `__. Installers for different Operating Systems can be found `here `__. +Conda is a free open source cross-platform package manager that runs on +Windows, OS X and Linux. Modern versions of conda have significantly improved +performance compared to older versions. Instructions to install mambaforge can be found `here `__. Installers for different Operating Systems can be found `here `__. Alternatively, if you prefer a package installer backed by corporate tech support available (for a fee) as necessary, you can install @@ -93,9 +93,8 @@ support available (for a fee) as necessary, you can install although you should consult the `terms of service `__ for this product and ensure you qualify since businesses and governments with over 200 employees do not qualify for free usage. -If you're using `conda` instead of `mamba`, just replace every call to -`mamba` below with `conda`, as they share the same user interface and most -command formats. +You can use `conda` for all the commands below, as it now has the same +performance and capabilities that were previously only available in mamba. If you access the internet from behind a firewall, then you may need to configure your proxy server. To do so, create a `.condarc` file in your @@ -117,7 +116,7 @@ There are multiple ways to install the ActivitySim codebase: 1. Using a :ref:`Pre-packaged Installer` (recommended for users who do not need to change the Python code) -2. Using a :ref:`Python package manager like mamba ` (recommended for users who need to change/customize the Python code) +2. Using a :ref:`Python package manager like conda ` (recommended for users who need to change/customize the Python code) 3. Using :ref:`pip - Python's standard package manager ` @@ -146,17 +145,17 @@ Once the install is complete, ActivitySim can be run directly from any command prompt by running `/Scripts/ActivitySim.exe`. -Using *mamba* package manager +Using *conda* package manager _____________________________ This method is recommended for ActivitySim users who also wish to customize the Python code to run their models. The steps involved are described as follows: -1. Install the *mamba* package manager as described in the :ref:`Software Requirements ` subsection. +1. Install the *conda* package manager as described in the :ref:`Software Requirements ` subsection. 2. Create a conda environment (basically a Python install just for this project) -using mambaforge prompt or conda prompt depending on the package manager you use (on Windows) or the terminal (macOS or Linux):: +using conda prompt (on Windows) or the terminal (macOS or Linux):: - mamba create -n asim python=3.10 activitysim -c conda-forge --override-channels + conda create -n asim python=3.10 activitysim -c conda-forge --override-channels This command will create the environment and install all the dependencies required for running ActivitySim. It is only necessary to create the environment @@ -164,35 +163,35 @@ once per machine, you do not need to (re)create the environment for each session If you would also like to install other tools or optional dependencies, it is possible to do so by adding additional libraries to this command. For example:: - mamba create -n asim python=3.10 activitysim jupyterlab larch -c conda-forge --override-channels + conda create -n asim python=3.10 activitysim jupyterlab larch -c conda-forge --override-channels This example installs a specific version of Python, version 3.9. A similar approach can be used to install specific versions of other libraries as well, including ActivitySim, itself. For example:: - mamba create -n asim python=3.9 activitysim=1.0.2 -c conda-forge --override-channels + conda create -n asim python=3.9 activitysim=1.0.2 -c conda-forge --override-channels Additional libraries can also be installed later. You may want to consider these tools for certain development tasks:: # packages for testing - mamba install pytest pytest-cov coveralls black flake8 pytest-regressions -c conda-forge --override-channels -n asim + conda install pytest pytest-cov coveralls black flake8 pytest-regressions -c conda-forge --override-channels -n asim # packages for building documentation - mamba install sphinx numpydoc sphinx_rtd_theme==0.5.2 -c conda-forge --override-channels -n asim + conda install sphinx numpydoc sphinx_rtd_theme==0.5.2 -c conda-forge --override-channels -n asim # packages for estimation integration - mamba install larch -c conda-forge --override-channels -n asim + conda install larch -c conda-forge --override-channels -n asim # packages for example notebooks - mamba install jupyterlab matplotlib geopandas descartes -c conda-forge --override-channels -n asim + conda install jupyterlab matplotlib geopandas descartes -c conda-forge --override-channels -n asim To create an environment containing all these optional dependencies at once, you can run the shortcut command :: - mamba env create activitysim/ASIM -n asim + conda env create activitysim/ASIM -n asim 3. To use the **asim** environment, you need to activate it @@ -205,19 +204,19 @@ start a new session (e.g. opening a new conda Prompt window). .. note:: The *activate* and *deactivate* commands to start and stop using environments - are called as `conda` even if you are otherwise using `mamba`. mamba is a drop-in replacement and uses the same commands and configuration options as conda. - You can swap almost all commands between conda & mamba. For more details, refer to `the mamba user guide `__. + are always called as `conda`. Modern conda has the same performance and configuration options as mamba. + For more details, refer to `the conda user guide `__. Using *pip* - Python's standard package manager _______________________________________________ -If you prefer to install ActivitySim without a package manager like *mamba* or *conda*, it is possible to +If you prefer to install ActivitySim without a package manager like *conda*, it is possible to do so with pip, although you may find it more difficult to get all of the required dependencies installed correctly. If you can use conda for the dependencies, you can get most of the libraries you need from there:: # required packages for running ActivitySim - mamba install cytoolz numpy pandas psutil pyarrow numba pytables pyyaml openmatrix requests -c conda-forge + conda install cytoolz numpy pandas psutil pyarrow numba pytables pyyaml openmatrix requests -c conda-forge # required for ActivitySim version 1.0.1 and earlier pip install zbox @@ -242,7 +241,7 @@ Installing from source is easier if you have all the necessary dependencies alre installed in a development conda environment. Developers can create an environment that has all the optional dependencies preinstalled by running:: - mamba env create activitysim/ASIM-DEV + conda env create activitysim/ASIM-DEV If you prefer to use a different environment name than `ASIM-DEV`, just append `--name OTHERNAME` to the command. Then all that's left to do is install diff --git a/docs/users-guide/run_primary_example.rst b/docs/users-guide/run_primary_example.rst index 898b354041..1846d1dabd 100644 --- a/docs/users-guide/run_primary_example.rst +++ b/docs/users-guide/run_primary_example.rst @@ -3,12 +3,12 @@ Run the Primary Example To setup and run the primary example (see :ref:`examples`) from the command line interface, do the following: -* Open the mamba or conda command prompt +* Open the conda command prompt * If you installed ActivitySim using conda environments, activate the conda environment with ActivitySim installed (i.e. ``conda activate asim``) .. note:: - Most ``conda`` and ``mamba`` commands can be used interchangeably in the **mamba command prompt**. In the above step, you could instead use ``mamba activate asim`` in the mamba command prompt. + You can use ``conda activate asim`` to activate your environment. * Or, if you used the :ref:`pre-packaged installer`, replace all the commands below that call ``activitysim ...`` with the complete path to your installed location, which is probably something