Command Line Interface

ActivitySim includes a Command Line Interface for creating examples and running the model. See activitysim -h for more information.

Note

The example_manifest.yaml contains example commands to create and run several versions of the examples.

Create

Create an ActivitySim example setup. See activitysim create -h for more information. More complete examples, including the full scale prototype MTC regional demand model are available for creation by typing activitysim create -l. To create these examples, ActivitySim downloads the large input files from the ActivitySim resources repository.

API

activitysim.cli.create.add_create_args(parser)

Create command args

activitysim.cli.create.create(args)

Create a new ActivitySim configuration from an existing template.

Use the -l flag to view a list of example configurations, then copy to your own working directory. These new project files can be run with the ‘run’ command.

activitysim.cli.create.download_asset(url: str, target_path: str, sha256: Optional[str] = None, link: bool = True, base_path: Optional[str] = None, unpack: Optional[str] = None)

Download assets (extra files) associated with examples.

Parameters:

urlstr

The URL to download.

target_pathstr

The location where the asset should be made available. The raw asset file is not necessarily stored here, as it may be stored in a cache directory and symlinked here instead (see link).

sha256str, optional

Checksum for the file. If there is already a cached file and the checksum matches, it is not re-downloaded and the cached version is used. Otherwise, the file is downloaded, and if the downloaded file’s checksum does not match, an error is raised.

linkbool, default True

Download the raw asset to a cache location, and then symlink to the desired target_path location. Note symlinks may not work on Windows so the file will still be stored in the cache but it will be copied instead of linked.

base_pathstr, optional

Give the base directory for the example.

unpackstr, optional

If the asset is an archive file (.zip, .tar.gz, or .tar.zst), it will be decompressed into this location.

activitysim.cli.create.get_example(example_name, destination, benchmarking=False, optimize=True, link=True, with_subdirs=False)

Copy project data to user-specified directory.

Examples and their data are described in a manifest YAML file. Each example contains at least a name and include field which is a list of files/folders to include in the copied example.

Parameters:

example_name: str, name of the example to copy.

Options can be found via list_examples()

destination: name of target directory to copy files to.

If the target directory does not exist, it is created. Project files will then be copied into a subdirectory with the same name as the example

benchmarking: bool

optimize: bool

link: bool or path-like

Files downloaded via http pointers will be cached in this location. If a path is not given but just a truthy value, then a cache directory is created using in a location selected by the platformdirs library (or, if not installed, linking is skipped.)

with_subdirs: bool, default False

Also return any instructions about sub-directories.

Returns:

Path or (Path, dict)

The path to the location where the example was installed, and optionally also a mapping of example subdirectory locations.

Run

Run ActivitySim. See activitysim run -h for more information.

Settings File Inheritance

ActivitySim model runs can be configured with settings file inheritance to avoid duplicating settings across model configurations. The command below runs ActivitySim with two configs folders - configs and configs_mp. This setup allows for overriding setings in the configs folder with additional settings in the configs_mp folder so that expression files and settings in the single process (e.g. configs folder) can be re-used for the multiprocessed setup (e.g. configs_mp folder). Settings files, as opposed to configs folders, can also be inherited by specifying -s multiple times. See activitysim run -h for more information.

# in configs_mp\settings.yaml
inherit_settings: True

#then on the command line
activitysim run -c configs_mp -c configs -d data -o output

API

activitysim.cli.run.add_run_args(parser, multiprocess=True)

Run command args

activitysim.cli.run.run(args)

Run the models. Specify a project folder using the ‘–working_dir’ option, or point to the config, data, and output folders directly with ‘–config’, ‘–data’, and ‘–output’. Both ‘–config’ and ‘–data’ can be specified multiple times. Directories listed first take precedence.

returns:

int: sys.exit exit code