diff --git a/v1.3.0/.buildinfo b/v1.3.0/.buildinfo new file mode 100644 index 000000000..e0afc03db --- /dev/null +++ b/v1.3.0/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 9d831c22f136af6bbf934ad4ed67042d +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/v1.3.0/_images/estimation_example.jpg b/v1.3.0/_images/estimation_example.jpg new file mode 100644 index 000000000..da2c4f719 Binary files /dev/null and b/v1.3.0/_images/estimation_example.jpg differ diff --git a/v1.3.0/_images/estimation_tools.jpg b/v1.3.0/_images/estimation_tools.jpg new file mode 100644 index 000000000..963c6cc63 Binary files /dev/null and b/v1.3.0/_images/estimation_tools.jpg differ diff --git a/v1.3.0/_images/example_flowchart.png b/v1.3.0/_images/example_flowchart.png new file mode 100644 index 000000000..d1ebf79cf Binary files /dev/null and b/v1.3.0/_images/example_flowchart.png differ diff --git a/v1.3.0/_images/run_select_components.png b/v1.3.0/_images/run_select_components.png new file mode 100644 index 000000000..4997cdf63 Binary files /dev/null and b/v1.3.0/_images/run_select_components.png differ diff --git a/v1.3.0/_images/viz_nav-1.png b/v1.3.0/_images/viz_nav-1.png new file mode 100644 index 000000000..3bfe835d0 Binary files /dev/null and b/v1.3.0/_images/viz_nav-1.png differ diff --git a/v1.3.0/_images/viz_nav-2.png b/v1.3.0/_images/viz_nav-2.png new file mode 100644 index 000000000..e6f748d2d Binary files /dev/null and b/v1.3.0/_images/viz_nav-2.png differ diff --git a/v1.3.0/_images/viz_nav-3.png b/v1.3.0/_images/viz_nav-3.png new file mode 100644 index 000000000..9fc79667e Binary files /dev/null and b/v1.3.0/_images/viz_nav-3.png differ diff --git a/v1.3.0/_images/viz_nav-4.png b/v1.3.0/_images/viz_nav-4.png new file mode 100644 index 000000000..f9ee435d7 Binary files /dev/null and b/v1.3.0/_images/viz_nav-4.png differ diff --git a/v1.3.0/_images/viz_nav-5.png b/v1.3.0/_images/viz_nav-5.png new file mode 100644 index 000000000..8e1837de5 Binary files /dev/null and b/v1.3.0/_images/viz_nav-5.png differ diff --git a/v1.3.0/_sources/benchmarking.rst.txt b/v1.3.0/_sources/benchmarking.rst.txt new file mode 100644 index 000000000..83b91b810 --- /dev/null +++ b/v1.3.0/_sources/benchmarking.rst.txt @@ -0,0 +1,283 @@ + +.. _benchmarking : + +Benchmarking +------------ + +A key focus of the ActivitySim project is *performance*. It's not enough +to build a new modeling platform that's mathematically sound and simulates +travel behavior as expected. It's also required that it do so quickly. +It's not too hard to run performance tests manually on individual models, and +doing so after making changes that are expected to *improve* performance is +typical. But monitoring performance regularly and automatically can help ensure +that new features do not introduce unexpected performance regressions (i.e. +models run slower than before). Developing an extensive set of automatic +performance benchmarks can streamline the former problem and solve the latter. + +ActivitySim includes the ability to run performance benchmarks using a tool +called `airspeed velocity `__. + +The benchmarking process is closely tied to ActivitySim's *git* repository, +so it is recommended that you use Git to clone the repository from GitHub. + + +Benchmarking Setup +~~~~~~~~~~~~~~~~~~ + +The first step in running benchmarks is to have a conda environment for +benchmarking, as well as a local clone of the main ActivitySim repository, +plus one of the ``asim-benchmarks`` repository. If you plan to submit your +benchmarking results to the common repository of results, you'll want to +also make sure that your ``asim-benchmarks`` repository is using a fork of the +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 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 + cd .. + gh repo fork ActivitySim/asim-benchmarks --remote + cd asim-benchmarks + python initialize-hooks.py + +For non-Windows users, you can then actually activate the pre-commit hooks like +this:: + + pre-commit install # macOS/Linux only, do not run this line on Windows + +Windows users should not attempt to use installed pre-commit hooks with conda +(see note below). Instead, you must manually ``pre-commit run`` inside the correct +conda environment before committing. + +If this environment is set up but it's been a while since you last used it, +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 + cd .. + cd asim-benchmarks + git pull + +Next, we'll want to declare the specs of our benchmarking machine. Some of +these can be determined quasi-automatically, but we want to confirm the specs +we'll use as they are written with our benchmark results into the database. +Define machine specs by running this command:: + + activitysim benchmark machine + +This will start an interactive questions and answer session to describe your +computer. Don't be afraid, just answer the questions. The tool may make +suggestions, but they are not always correct, so check them first and don't just +accept all. For example, under "arch" it may suggest "AMD64", but for consistency +you can change that to "x86_64", which is the same thing by a different name. + +Running Benchmarks +~~~~~~~~~~~~~~~~~~ + +ActivitySim automates the process of running many benchmarks. It can also easily +accumulate and analyze benchmark results across many different machines, as long as the +benchmarks are all run in the same (relative) place. So before running benchmarks, +change your working directory (at the command prompt) into the top directory of +the `asim-benchmarks` repository, if you're not already there. + +To run all of the benchmarks on the most recent commit in the main ActivitySim repo:: + + activitysim benchmark latest + +.. important:: + + The benchmarks do not currently use ActivitySim's dynamic chunking features, + as these require manual configuration and training on a per-machine basis + to ensure good performance. + + Running the complete suite of benchmarks currently includes downloading and + running full-region model data for several different SANDAG zone systems. + Ideally you should have at least 50 GB of free disk space and 120 GB of RAM + to attempt this process on any given machine. For a smaller machine, consider + benchmarking only the "test" sized examples, by adding `--bench sandag.example` + to this command, as discussed below. + +This will run the benchmarks only on the "HEAD" commit of the main activitysim git +repository. To run on some other historical commit[s] from the git history, you can +specify an individual commit or a range, in the same way you would do so for the +`git log` command. For example, to run benchmarks on the commits to develop since +it was branched off main, run:: + + activitysim benchmark run main..develop + +or to run only on the latest commit in develop, run:: + + activitysim benchmark run "develop^!" + +Note that the literal quotation marks are necessary on Windows, as the carat character +preceding the exclamation mark is otherwise interpreted as an escape character. +In most other shells (e.g. on Linux or macOS) the literal quotation marks are unnecessary. + +To run only benchmarks from a certain example, we can +use the `--bench` argument, which allows us to write a "regular expression" that +filters the benchmarks actually executed. This is handy if you are interested in +benchmarking a particular model or component, as running *all* the benchmarks can +take a very long time, and the larger benchmarks (e.g. on the full SANDAG model) +will need a lot of disk space and RAM. For example, to run only the mandatory +tour frequency benchmark for the SANDAG 1-Zone example-sized system, run:: + + activitysim benchmark latest --bench sandag1example.time_mandatory_tour_frequency + +The "." character here means a literal dot, but since this is a regex expression, +it is also a single-character wildcard. Thus, you can run all the example-sized +SANDAG benchmarks with:: + + activitysim benchmark latest --bench sandag.example + +You can also repeat the `--bench` argument to give multiple different expressions. +So, you can run just the 1- and 2-zone examples, without the 3-zone example:: + + activitysim benchmark latest --bench sandag1example --bench sandag2example + +If you want to run several different benchmarking commmands together, for example +to run a custom curated subset of interesting benchmarks, the benchmark tool also +includes a `batch` mode. You can assemble the various commands you would run +(i.e. everything you would type on the command line after "activitysim benchmark") +into a text file, and then point to that file using the `batch` command:: + + activitysim benchmark batch my_interesting_benchmarks.txt + + +Threading Limits +~~~~~~~~~~~~~~~~ + +When you run benchmarking using the `activitysim benchmark` command, the +following environment variable are set automatically before benchmarking begins:: + + MKL_NUM_THREADS = 1 + OMP_NUM_THREADS = 1 + OPENBLAS_NUM_THREADS = 1 + NUMBA_NUM_THREADS = 1 + VECLIB_MAXIMUM_THREADS = 1 + NUMEXPR_NUM_THREADS = 1 + +This ensures that all benchmarking operations run processes in single-threaded +mode. This still allows ActivitySim itself to spin up multiple processes if the +item being timed is a multiprocess benchmark. + +Submitting Benchmarks +~~~~~~~~~~~~~~~~~~~~~ + +One of the useful features of the airspeed velocity benchmarking engine is the +opportunity to compare performance benchmarks across different machines. The +ActivitySim community is interested in aggregating such results from a number +of participants, so once you have successfully run a set of benchmarks, you +should submit those results to our repository. + +To do so, assuming you have run the benchmark tool inside the ``asim-benchmarks`` +repository as noted above, you simply need to commit any new or changed files +in the ``asim-benchmarks/results`` directory. You can then open a pull request +against the community ``asim-benchmarks`` to submit those results. + +Assuming you are in (or first ``cd`` into) the ``asim-benchmarks`` directory, You can +do this from the command line using the following steps:: + + git add results + pre-commit run # required on Windows only, see note + git commit -m "adding benchmark results" + git push + gh pr create + +.. note:: + + On Windows, the process for automatically running pre-commit hooks when + making a Git a commit is not compatible with conda, see + `here `. This will + probably never be fixed, as the developers of pre-commit and conda each + feel that the "bug" is in the other library. So, manually running the + pre-commit step is required. + +Users may find it simpler to skip the last step on the command line, and simply +visit their fork on GitHub.com to use the web interface to open a pull request. + +Publishing to Github Pages +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Publishing the standard airspeed velocity content to GitHub pages is a built-in +feature of the command line tool, available to users who have write-access to the +asim-benchmarks GitHub repository. Be sure you have all the relevant branches +tracked locally (especially main and develop) and then run:: + + activitysim benchmark gh-pages + + +Profiling +~~~~~~~~~ + +The benchmarking tool can also be used for profiling, which allows a developer to +inspect the timings for various commands *inside* a particular benchmark. This is +most conveniently accomplished using the ``snakeviz`` tool, which should be installed +in the developer tools environment (``conda install snakeviz -c conda-forge``). +Then, the developer needs to run two commands to compute and view the component +profile. + +To create a profile record when benchmarking, add the ``--profile`` option when +running the benchmarks. For example, to create profile records for the SANDAG +example-sized model's non-mandatory tour scheduling component across all three +zone systems, run:: + + activitysim benchmark latest --bench sandag.example.non_mandatory_tour_scheduling --profile + +This command will save the profiling data directly into the json file that stores +the benchmark timings. This is a lot of extra data, so it's not advised to +save profiling data for every benchmark, but only for benchmarks of particular +interest. + +Once this data has been saved, you can access it using the ``snakeviz`` tool. This +visualization requires pointing to a specific profiled benchmark in a specific +json result file. For example:: + + activitysim benchmark snakeviz results/LUMBERJACK/241ddb64-env-c87ac846ee78e51351a06682de5adcb5.json sandag3example.non_mandatory_tour_scheduling.time_component + +On running this command, a web browser should pop open to display the snakeviz +interface. + +Writing New Benchmarks +~~~~~~~~~~~~~~~~~~~~~~ + +New benchmarks for other model examples can be added to +``activitysim/benchmarking/benchmarks``. A basic template structure has been used, +so that it should be relatively straight-forward to implement component-level +single thread benchmarks for any model that is available using the +``activitysim create`` tool. + +A basic framework for multi-processing benchmarks has been implemented and is +demonstrated in the ``mtc1mp4`` benchmark file. However, work remains to write +a stable process to execute chunking training for each machine prior to running +the production-version benchmarks that will be meaningful for users. + +Running Benchmarks for Pull Requests +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The complete set of performance benchmarks is too large to include in ActivitySim's +automatic continuous integration (CI) testing, both by compute time and by memory usage. +However, it is valuable to run these tests once against the final version of +each PR before merging into the ``develop`` branch, to ensure there are no +unexpected performance regressions. The airspeed velocity tools include a special +CI mode, which runs the same benchmarks on the same machine with the same settings, +giving developers a fair shot at a strict apples-to-apples comparison of performance. + +This mode can be activated to check the performance of code on a git branch called +``my-new-feature-branch``, and compare against the ``develop`` branch like this:: + + activitysim benchmark continuous develop my-new-feature-branch + +Unlike other tests for mathematical correctness, it is not always necessary that +new PR's must "pass" this testing, as new features or capabilities may justify a +performance degradation. But developers should always run these tests on new PR's +so that the community is aware of the trade offs (if any) and can take steps to +mitigate problems promptly if desired. + diff --git a/v1.3.0/_sources/cli.rst.txt b/v1.3.0/_sources/cli.rst.txt new file mode 100644 index 000000000..c9bcbfeb4 --- /dev/null +++ b/v1.3.0/_sources/cli.rst.txt @@ -0,0 +1,65 @@ + +.. _cli : + +Command Line Interface +====================== + +ActivitySim includes a :ref:`cli` 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 +~~~ + +.. automodule:: activitysim.cli.create + :members: + + +Run +--- + + +Run ActivitySim. See ``activitysim run -h`` for more information. + +.. index:: _settings_file_inheritance +.. _settings_file_inheritance : + +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 +~~~ + +.. automodule:: activitysim.cli.run + :members: + diff --git a/v1.3.0/_sources/core.rst.txt b/v1.3.0/_sources/core.rst.txt new file mode 100644 index 000000000..687e8f956 --- /dev/null +++ b/v1.3.0/_sources/core.rst.txt @@ -0,0 +1,735 @@ + +Core Components +=============== + +ActivitySim's core components include features for multiprocessing, data management, +utility expressions, choice models, person time window management, and helper +functions. These core components include the multiprocessor, network LOS (skim) manager, the +data pipeline manager, the random number manager, the tracer, sampling +methods, simulation methods, model specification readers and expression +evaluators, choice models, timetable, transit virtual path builder, and helper functions. + +.. _multiprocessing_in_detail: + +Multiprocessing +--------------- + +Parallelization using multiprocessing + +API +~~~ + +.. automodule:: activitysim.core.mp_tasks + :members: + + +Data Management +--------------- + +Input +~~~~~ + +Input data table functions + +API +^^^ + +.. automodule:: activitysim.core.input + :members: + +.. _los_in_detail: + +LOS +~~~ + +Network Level of Service (LOS) data access + +API +^^^ + +.. automodule:: activitysim.core.los + :members: + +Skims +~~~~~ + +Skims data access + +API +^^^ + +.. automodule:: activitysim.core.skim_dict_factory + :members: + +.. automodule:: activitysim.core.skim_dictionary + :members: + + +.. _random_in_detail: + +Random +~~~~~~ + +ActivitySim's random number generation has a number of important features unique to AB modeling: + +* Regression testing, debugging - run the exact model with the same inputs and get exactly the same results. +* Debugging models - run the exact model with the same inputs but with changes to expression files and get the same results except where the equations differ. +* Since runs can take a while, the above cases need to work with a restartable pipeline. +* Debugging Multithreading - run the exact model with different multithreading configurations and get the same results. +* Repeatable household-level choices - results for a household are repeatable when run with different sample sizes +* Repeatable household level results with different scenarios - results for a household are repeatable with different scenario configurations sequentially up to the point at which those differences emerge, and in alternate submodels in which those differences do not apply. + +Random number generation is done using the `numpy Mersenne Twister PNRG `__. +ActivitySim seeds on-the-fly and uses a stream of random numbers seeded by the household id, person id, tour id, trip id, the model step offset, and the global seed. +The global seed can be set in the settings.yaml file using the ```rng_base_seed`` option. +The logic for calculating the seed is something along the lines of: + +:: + + chooser_table.index * number_of_models_for_chooser + chooser_model_offset + global_seed_offset + + for example + 1425 * 2 + 0 + 1 + where: + 1425 = household table index - households.id + 2 = number of household level models - auto ownership and cdap + 0 = first household model - auto ownership + 1 = global seed offset for testing the same model under different random global seeds + +ActivitySim generates a separate, distinct, and stable random number stream for each tour type and tour number in order to maintain as much stability as is +possible across alternative scenarios. This is done for trips as well, by direction (inbound versus outbound). + +.. note:: + The Random module contains max model steps constants by chooser type - household, person, tour, trip - needs to be equal to the number of chooser sub-models. + +API +^^^ + +.. automodule:: activitysim.core.random + :members: + +.. _trace : + +Tracing +~~~~~~~ + +Household tracer. If a household trace ID is specified, then ActivitySim will output a +comprehensive set of trace files for all calculations for all household members: + +* ``hhtrace.log`` - household trace log file, which specifies the CSV files traced. The order of output files is consistent with the model sequence. +* ``various CSV files`` - every input, intermediate, and output data table - chooser, expressions/utilities, probabilities, choices, etc. - for the trace household for every sub-model + +With the set of output CSV files, the user can trace ActivitySim's calculations in order to ensure they are correct and/or to +help debug data and/or logic errors. + +API +^^^ + +.. automodule:: activitysim.core.tracing + :members: + + +.. _util_expressions: + +Utility Expressions +------------------- + +Much of the power of ActivitySim comes from being able to specify Python, pandas, and +numpy expressions for calculations. Refer to the pandas help for a general +introduction to expressions. ActivitySim provides two ways to evaluate expressions: + +* Simple table expressions are evaluated using ``DataFrame.eval()``. `pandas' eval `__ operates on the current table. +* Python expressions, denoted by beginning with ``@``, are evaluated with `Python's eval() `__. + +Simple table expressions can only refer to columns in the current DataFrame. Python expressions can refer to any Python objects currently in memory. + +Conventions +~~~~~~~~~~~ + +There are a few conventions for writing expressions in ActivitySim: + +* each expression is applied to all rows in the table being operated on +* expressions must be vectorized expressions and can use most numpy and pandas expressions +* global constants are specified in the settings file +* comments are specified with ``#`` +* you can refer to the current table being operated on as ``df`` +* often an object called ``skims``, ``skims_od``, or similar is available and is used to lookup the relevant skim information. See :ref:`los_in_detail` for more information. +* when editing the CSV files in Excel, use single quote ' or space at the start of a cell to get Excel to accept the expression + +Example Expressions File +~~~~~~~~~~~~~~~~~~~~~~~~ + +An expressions file has the following basic form: + ++---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+ +| Label | Description | Expression | cars0 | cars1 | ++=================================+=================================+===============================+===========+=================================+ +| util_drivers_2 | 2 Adults (age 16+) | drivers==2 | | coef_cars1_drivers_2 | ++---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+ +| util_persons_25_34 | Persons age 25-34 | num_young_adults | | coef_cars1_persons_25_34 | ++---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+ +| util_num_workers_clip_3 | Number of workers, capped at 3 | @df.workers.clip(upper=3) | | coef_cars1_num_workers_clip_3 | ++---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+ +| util_dist_0_1 | Distance, from 0 to 1 miles | @skims['DIST'].clip(1) | | coef_dist_0_1 | ++---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+ + +In the :ref:`tour_mode_choice` model expression file example shown below, the ``@c_ivt*(@odt_skims['SOV_TIME'] + dot_skims['SOV_TIME'])`` +expression is travel time for the tour origin to destination at the tour start time plus the tour destination to tour origin at the tour end time. +The ``odt_skims`` and ``dot_skims`` objects are setup ahead-of-time to refer to the relevant skims for this model. The ``@c_ivt`` comes from the +tour mode choice coefficient file. The tour mode choice model is a nested logit (NL) model and the nesting structure (including nesting +coefficients) is specified in the YAML settings file. + ++-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+ +| Label | Description | Expression | DRIVEALONEFREE | DRIVEALONEPAY | ++===========================================================+========================================================+================================================+=================+===============+ +| util_DRIVEALONEFREE_Unavailable | DRIVEALONEFREE - Unavailable | sov_available == False | -999 | | ++-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+ +| util_DRIVEALONEFREE_In_vehicle_time | DRIVEALONEFREE - In-vehicle time | odt_skims['SOV_TIME'] + dot_skims['SOV_TIME'] | coef_ivt | | ++-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+ +| util_DRIVEALONEFREE_Unavailable_for_persons_less_than_16 | DRIVEALONEFREE - Unavailable for persons less than 16 | age < 16 | -999 | | ++-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+ +| util_DRIVEALONEFREE_Unavailable_for_joint_tours | DRIVEALONEFREE - Unavailable for joint tours | is_joint == True | -999 | | ++-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+ + +* Rows are vectorized expressions that will be calculated for every record in the current table being operated on +* The Label column is the unique expression name (used for model estimation integration) +* The Description column describes the expression +* The Expression column contains a valid vectorized Python/pandas/numpy expression. In the example above, ``drivers`` is a column in the current table. Use ``@`` to refer to data outside the current table +* There is a column for each alternative and its relevant coefficient from the submodel coefficient file + +There are some variations on this setup, but the functionality is similar. For example, +in the example destination choice model, the size terms expressions file has market segments as rows and employment type +coefficients as columns. Broadly speaking, there are currently four types of model expression configurations: + +* Simple :ref:`simulate` choice model - select from a fixed set of choices defined in the specification file, such as the example above. +* :ref:`simulate_with_interaction` choice model - combine the choice expressions with the choice alternatives files since the alternatives are not listed in the expressions file. The :ref:`non_mandatory_tour_destination_choice` model implements this approach. +* Combinatorial choice model - first generate a set of alternatives based on a combination of alternatives across choosers, and then make choices. The :ref:`cdap` model implements this approach. + +Expressions +~~~~~~~~~~~ + +The expressions class is often used for pre- and post-processor table annotation, which read a CSV file of expression, calculate +a number of additional table fields, and join the fields to the target table. An example table annotation expressions +file is found in the example configuration files for households for the CDAP model - +`annotate_households_cdap.csv `__. + +.. automodule:: activitysim.core.expressions + :members: + +Sampling with Interaction +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Methods for expression handling, solving, and sampling (i.e. making multiple choices), +with interaction with the chooser table. + +Sampling is done with replacement and a sample correction factor is calculated. The factor is +calculated as follows: + +:: + + freq = how often an alternative is sampled (i.e. the pick_count) + prob = probability of the alternative + correction_factor = log(freq/prob) + + #for example: + + freq 1.00 2.00 3.00 4.00 5.00 + prob 0.30 0.30 0.30 0.30 0.30 + correction factor 1.20 1.90 2.30 2.59 2.81 + +As the alternative is oversampled, its utility goes up for final selection. The unique set +of alternatives is passed to the final choice model and the correction factor is +included in the utility. + +API +^^^ + +.. automodule:: activitysim.core.interaction_sample + :members: + +.. _simulate: + +Simulate +~~~~~~~~ + +Methods for expression handling, solving, choosing (i.e. making choices) from a fixed set of choices +defined in the specification file. + +API +^^^ + +.. automodule:: activitysim.core.simulate + :members: + +.. _simulate_with_interaction: + +Simulate with Interaction +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Methods for expression handling, solving, choosing (i.e. making choices), +with interaction with the chooser table. + +API +^^^ + +.. automodule:: activitysim.core.interaction_simulate + :members: + +Simulate with Sampling and Interaction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Methods for expression handling, solving, sampling (i.e. making multiple choices), +and choosing (i.e. making choices), with interaction with the chooser table. + +API +^^^ + +.. automodule:: activitysim.core.interaction_sample_simulate + :members: + +Assign +~~~~~~ + +Alternative version of the expression evaluators in :mod:`activitysim.core.simulate` that supports temporary variable assignment. +Temporary variables are identified in the expressions as starting with "_", such as "_hh_density_bin". These +fields are not saved to the data pipeline store. This feature is used by the :ref:`accessibility` model. + +API +^^^ + +.. automodule:: activitysim.core.assign + :members: + + +Choice Models +------------- + +.. _logit_in_detail: + +Logit +~~~~~ + +Multinomial logit (MNL) or Nested logit (NL) choice model. These choice models depend on the foundational components of ActivitySim, such +as the expressions and data handling described in the :ref:`how_the_system_works` section. + +To specify and solve an MNL model: + +* either specify ``LOGIT_TYPE: MNL`` in the model configuration YAML file or omit the setting +* call either ``simulate.simple_simulate()`` or ``simulate.interaction_simulate()`` depending if the alternatives are interacted with the choosers or because alternatives are sampled + +To specify and solve an NL model: + +* specify ``LOGIT_TYPE: NL`` in the model configuration YAML file +* specify the nesting structure via the NESTS setting in the model configuration YAML file. An example nested logit NESTS entry can be found in ``example/configs/tour_mode_choice.yaml`` +* call ``simulate.simple_simulate()``. The ``simulate.interaction_simulate()`` functionality is not yet supported for NL. + +API +^^^ + +.. automodule:: activitysim.core.logit + :members: + +.. _time_windows: + +Person Time Windows +------------------- + +The departure time and duration models require person time windows. Time windows are adjacent time +periods that are available for travel. Time windows are stored in a timetable table and each row is +a person and each time period (in the case of MTC TM1 is 5am to midnight in 1 hr increments) is a column. +Each column is coded as follows: + +* 0 - unscheduled, available +* 2 - scheduled, start of a tour, is available as the last period of another tour +* 4 - scheduled, end of a tour, is available as the first period of another tour +* 6 - scheduled, end or start of a tour, available for this period only +* 7 - scheduled, unavailable, middle of a tour + +A good example of a time window expression is ``@tt.previous_tour_ends(df.person_id, df.start)``. This +uses the person id and the tour start period to check if a previous tour ends in the same time period. + +API +~~~ + +.. automodule:: activitysim.core.timetable + :members: + +.. _transit_virtual_path_builder: + +Transit Virtual Path Builder +---------------------------- + +Transit virtual path builder (TVPB) for three zone system (see :ref:`multiple_zone_systems`) transit path utility calculations. +TAP to TAP skims and walk access and egress times between MAZs and TAPs are input to the +demand model. ActivitySim then assembles the total transit path utility based on the user specified TVPB +expression files for the respective components: + +* from MAZ to first boarding TAP + +* from first boarding to final alighting TAP + +* from alighting TAP to destination MAZ + +This assembling is done via the TVPB, which considers all the possible combinations of nearby boarding and alighting TAPs for each origin +destination MAZ pair and selects the user defined N best paths to represent the transit mode. After selecting N best paths, the logsum across +N best paths is calculated and exposed to the mode choice models and a random number is drawn and a path is chosen. The boarding TAP, +alighting TAP, and TAP to TAP skim set for the chosen path is saved to the chooser table. + +The initialize TVPB submodel (see :ref:`initialize_los`) pre-computes TAP to TAP total utilities for the user defined attribute_segments, +which are typically demographic segment (for example household income bin), time-of-day, and access/egress mode. This submodel can be +run in both single process and multiprocess mode, with single process excellent for development/debugging and multiprocess excellent +for application. ActivitySim saves the pre-calculated TAP to TAP total utilities to a memory mapped cache file for reuse by downstream models +such as tour mode choice. In tour mode choice, the pre-computed TAP to TAP total utilities for the attribute_segment, along with the +access and egress impedances, are used to evaluate the best N TAP pairs for each origin MAZ destination MAZ pair being evaluated. +Assembling the total transit path impedance and then picking the best N is quick since it is done in a de-duplicated manner within +each chunk of multiprocessed choosers. + +A model with TVPB can take considerably longer to run than a traditional TAZ based model since it does an order of magnitude more +calculations. Thus, it is important to be mindful of your approach to your network model as well, especially the number of TAPs +accessible to each MAZ, which is the key determinant of runtime. + +API +~~~ + +.. automodule:: activitysim.core.pathbuilder + :members: + + +Cache API +~~~~~~~~~ + +.. automodule:: activitysim.core.pathbuilder_cache + :members: + +.. _visualization: + +Visualization +------------- +Visualization capabilities are provided with SimWrapper, a standalone browser-based software that creates interactive, graphical visualizations of ActivitySim outputs. SimWrapper builds graphs and other visualization components from CSV summary tables that are produced by the *summarize* model step. Once the model run is complete, Simwrapper can be started and stopped at any time, independent of ActivitySim to visualize outputs. The tool currently allows users to view dashboards for multiple model runs side-by-side in the browser. The ability to compute and visualize the differences between two model runs is a planned future enhancement. + +To use set up the summarize model to produce tables for SimWrapper, add ``summarize`` to the list of models in ``configs_mp/settings.yaml`` and add the following files to the `config` directory: + +* ``summarize.yaml``: configuration for the summarize model step +* ``summarize.csv:`` expression file containing the final aggregations that will be generated at the end of the model run +* ``summarize_preprocessor.csv``: intermediate expression file used to add columns, including skim summaries, to the ``trips_merged`` pipeline table + +In the output directory, add a new summarize directory, which must contain: + +* ``dashboard-1-summary.yaml``: configuration for the layout and formatting of charts and other objects in the dashboard +* Additional ``dashboard-\*.yaml`` files may be used to configure additional dashboard tabs +* ``topsheet.yaml``: configuration for calculated statistics in the ‘At-a-Glance’ table at the top of the dashboard +* The ``/output/summarize`` directory may also contain one or more .geojson files to support map-based visualizations in the dashboard. + +At present, example versions of all of the items above are located in the prototype MTC example model: ``/activitysim/examples/prototype_mtc``. Complete documentation for configuring dashboards is available in the `SimWrapper Docs `_. + + +Configure the Summarize Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Summary Expressions +^^^^^^^^^^^^^^^^^^^ +Example configuration files for the summarize model step (as listed above) are included in prototype MTC example. These files will need to be adjusted to produce customized SimWrapper dashboards. These files are structured as standard ActivitySim expression (CSV) and configuration (YAML) files. More detailed information about configuration of the summarize model step is available in the Models documentation. + +You may wish to manipulate the default expression files to suit your particular needs. Expression files are formatted as CSVs and structured according to ActivitySim conventions with three columns: + +* ``Description``: Brief description of expression. Non-functional and may be left blank. +* ``Output``: Name of expression output. Will be used to name either the CSV or local variable storing the expression output. +* ``Expression``: Python expression that will be evaluated to produce the output. + +Rows with output values that begin with an alphanumeric character will be saved to a CSV (e.g., ``output_name`` --> ``output_name.csv``). These expressions must yield a Pandas Series, DataFrame, or another object with a ``to_csv`` method. + +Rows with output values that begin with underscores (e.g., ``_output_name``) will be stored as temporary variables in the local namespace so they can be used in following expressions. Expressions defining temporary variables can produce any data type. Users are encouraged to follow the ActivitySim convention using capitals to denote constants (e.g., ``_TEMP_CONSTANT``), though this convention is not formally enforced for summarize expressions. + +Summarize expressions can make use of several convenience functions for binning numeric Pandas Series' into quantiles, equal intervals, or manually-specified ranges. These functions are available in the local namespace used to evaluate summarize expressions (as well as for preprocessing the ``trips_merged`` table; see below), so they can be used directly in summary expressions. These functions include: + +* ``quantiles``: Construct quantiles from a Series given a number of bins. +* ``spaced_intervals``: Construct evenly-spaced intervals from a Series given a starting value and bin size. +* ``equal_intervals``: Construct equally-spaced intervals across the entire range of a Series. +* ``manual_breaks``: Classify numeric data in a Series into manually-defined bins. + +For example population density quintiles could be calculated with the expression: +:: + + quantiles(data=land_use.TOTPOP/land_use.TOTACRE, bins:5, label_format:'{rank}') + +The ``label_format`` parameter uses f-string formatting to specify how bins should be labeled. Several named variables are automatically available in the local namespace for use in labels: + +* ``left``: Left extent, or minimum, of the bin range +* ``mid``: Center of the bin range +* ``right``: Right extent, or maximum, of the bin range +* ``rank``: Numeric rank of the bin, with 1 being the lowest rank + +By default, bins are labeled with their extents using the following f-string: ``'{left:,.2f} - {right:,.2f}'``. The ``'{rank}'`` option demonstrated above would label each bin with its ordinal rank. Numeric labels are converted to numeric data types, if possible. + +Examples of each summarize function are included in the ``summarize.csv`` expression file for the prototype MTC example. Consult the docstrings for each function in the ``/activitysim/abm/models/summarize.py`` module for complete specification of parameters. + +Preprocessing +^^^^^^^^^^^^^ +Pipeline tables available for summarization can be preprocessed to include columns that bin or aggregate existing columns into categories or add skim data related to trips or tours. Preprocessing is configured both in ``summarize.yaml`` and ``summarize_preprocessor.csv``. + +Binning and aggregation operations that should take place *before* expressions are calculated, in order to produce a new column in a pipeline table, can be specified in ``summarize.yaml``. This can be useful for reducing clutter and redundancy in the summary expressions file. + +Binning during the preprocessing stage uses the same convenience functions available for expression files but specifies them in the configuration YAML. To calculate manually-defined income categories, for example, the YAML would include: + +:: + + persons_merged: # Pipeline table on which to operate + BIN: + # Manually-specified bins + - column: income # Column on which to operate + label: income_category # New column to make + type: manual_breaks # Binning function + bin_breaks: # Must include lower and upper extents; + - 0 # (One more value than the number of bins) + - 25000 + - 50000 + - 75000 + - 100000 + - 999999 + bin_labels: # (optional) + - Very Low Income ($0-$25k) + - Low Income ($25k-$50k) + - Medium Income ($50k-$75k) + - High Income ($75k-$100k) + - Very High Income (>$100k) + +Example uses of each binning function are included in the ``summarize.yaml`` configuration file in the prototype MTC example. + +Table columns can also be aggregated, or "remapped," during the preprocessing stage. Aggregations are specified in the configuration YAML using a key-value structure: + +:: + + trips_merged: # Pipeline table on which to operate + AGGREGATE: + - column: major_trip_mode # Column on which to operate + label: major_trip_mode # New column to make + map: + DRIVEALONEFREE: SOV # Keys: Existing values to map from + DRIVEALONEPAY: SOV # Values: New values to map to + SHARED2FREE: HOV + SHARED2PAY: HOV + SHARED3FREE: HOV + SHARED3PAY: HOV + WALK_LOC: Transit + WALK_LRF: Transit + WALK_EXP: Transit + WALK_HVY: Transit + WALK_COM: Transit + DRIVE_LOC: Transit + DRIVE_LRF: Transit + DRIVE_EXP: Transit + DRIVE_HVY: Transit + DRIVE_COM: Transit + DRIVEACCESS: Transit + WALK: Non-Motorized + BIKE: Non-Motorized + TAXI: Ride Hail + TNC_SINGLE: Ride Hail + TNC_SHARED: Ride Hail + + +Trip-level skim data are also made available in the preprocessing stage by attaching columns to the ``trips_merged`` table based on expressions in ``summarize_preprocessor.csv``. This process uses skim wrappers indexed by origin, destination, and time of day to gather distance, time, and cost data and each trip, enabling calculation of variables such as vehicle miles traveled (VMT). Preprocessing expressions are interpreted with standard ActivitySim annotation methods, including definition of scalar and vector temporary variables based on underscores and capitalization. The preprocessor expressions included in the prototype MTC example demonstrate calculation of a number of skim-based variables involving distance, time, and cost. The system for joining skim data to trips is currently configured for the one-zone MTC example model and will need to be generalized for multi-zone systems in future work. + + +Install and Run Simwrapper +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The SimWrapper Python package, which contains convenience functions for initiating the SimWrapper app in the browser and a local file server for accessing summary tables from this app, is automatically installed as a dependency of ActivitySim. However, you can also use SimWrapper independent of ActivitySim to, for example, visualize summaries on a different workstation. SimWrapper is available on both conda-forge and pip: +:: + + > conda install -c conda-forge simwrapper + +or + + > pip install simwrapper + +The latest information about the Simwrapper package is available on its `PyPI page `_. + +To run SimWrapper, navigate on the command line to ``output\summarize`` within the model directory, or a directory where you may have copied outputs, and run: +:: + + > simwrapper open asim + +This will start SimWrapper in your default browser. If this directory contains the appropriate configuration files for a dashboard (see above), the dashboard will open automatically. Otherwise, SimWrapper will show a file browser with the contents of the directory. + + +Navigate SimWrappper +~~~~~~~~~~~~~~~~~~~~ +When Simwrapper launches, the dashboard is displayed in the scrollable field in the main part of the browser window, and there are +two sets of navigation controls. The left-hand sidebar contains a menu of the available simulation outputs you can access from the +current directory, including a number of sample outputs: + +.. image:: images/viz_nav-1.png + +The header and tabs at the top of the page help you navigate within the simulation run that is currently being visualized: + +.. image:: images/viz_nav-2.png + +Clicking on ‘Details’ will switch from the visualizations view to a current directory listing to facilitate viewing and downloading of +the code and raw data used to create the dashboard: + +.. image:: images/viz_nav-3.png + +Clicking on ‘Topsheet’ returns you to the visualization graphics page. The three buttons in the lower left corner provide additional +functionality to: + +1. re-sync with the latest version of the output files, +2. toggle light theme vs. dark theme, and +3. split the visualization window into two separate panels like this: + +.. image:: images/viz_nav-4.png + +Before starting the split-screen view, choose the model run that you want to appear in the right side pane (‘1-sf-run’ in the image above). +Then, click on the split view button to divide the window into two visualization panels. Finally, use the left-hand navigation pane to +change the comparison run on the left side (‘2-nine-county’ in the image above). + +Each side of the split screen has independent header navigation (Topsheet vs. Details) and independent vertical and horizontal scrolling. +However, panning and zooming on any one map object controls all maps on both sides of the split view at the same time: + +.. image:: images/viz_nav-5.png + +.. _helpers: + +Helpers +------- + +.. index:: chunk_size +.. _chunk_size: +.. _chunk_in_detail: + +Chunk +~~~~~ + +Chunking management. + +.. note:: + The definition of chunk_size has changed from previous versions of ActivitySim. The revised definition + of chunk_size simplifies model setup since it is the approximate amount of RAM available to + ActivitySim as opposed to the obscure number of doubles (64-bit numbers) in a chunk of a choosers table. + +The ``chunk_size`` is the approximate amount of RAM in bytes (1 Gigabyte or 1 GB is equal to 1,000,000,000 bytes) to allocate to ActivitySim for batch +processing choosers across all processes. It is specified in bytes, for example ``chunk_size: 500_000_000_000`` is 500 GBs. +If set ``chunk_training_mode: disabled`` then no chunking will be performed and ActivitySim will attempt to solve all the +choosers at once across all the processes. Chunking is required when all the chooser data required to process all the +choosers cannot fit within the available RAM and so ActivitySim must split the choosers into batches and then process the batches in sequence. + +Configuration of the ``chunk_size`` depends on several parameters: + +* The amount of machine RAM +* The number of machine processors (CPUs/cores) +* The number of households (and number of zones for aggregate models) +* The amount of headroom required for shared data across processes, such as the skims/network LOS data +* The desired runtimes + +An example helps illustrate configuration of the ``chunk_size``. If the example model has 1 million households and the +current submodel is auto ownership, then there are 1 million choosers since every household participates in the auto +ownership model. In single process mode, ActivitySim would create one chooser table with 1 million rows, assuming this table +and the additional extra data such as the skims can fit within the available memory (RAM). If the 1 million row table cannot fit +within memory then chunking needs to be setup to split the choosers table into batches that are processed in sequence and small +enough to fit within the available memory. For example, the choosers table is split into 2 chunks of 500,000 choosers each and then +processed in sequence. In multi process mode, for example with 10 processes, ActivitySim splits the 1 million households into 10 +mini processes each with 100,000 households. Then for the auto ownership submodel, the chooser table within each process is the +100,000 choosers and there must be enough RAM to simultaneously solve all 10 processes with each 100,000 choosers at once. If not, +then chunking can be setup so each mini process table of choosers is split into chunks for sequential processing, for example from +10 tables of 100,000 choosers to 20 tables of 50,000 choosers. + +If the user desires the fastest runtimes possible given their hardware, model inputs, and model configuration, then ActivitySim +should be configured to use most of the CPUs/cores (physical, not virtual), most of the RAM, and with the :ref:`mkl_settings`. For +example, if the machine has 12 cores and 256 GB of RAM, then try configuring the model with ``num_processes: 10`` and +``chunk_size: 0`` to start and seeing if the model can fit the problem into the available RAM. If not, then try setting ``chunk_size`` +to something like 225 GB, ``chunk_size: 225_000_000_000``. Experimentation of the desired configuration of the CPUs and RAM should be done +for each new machine and model setup (with respect to the number of households, skims, and model configuration). In general, more processors +means faster runtimes and more RAM means faster runtimes, but the relationship of processors to RAM is not linear as processors can only +go so fast and because there is more to runtime than processors and RAM, including cache speed, disk speed, etc. Also, the amount of RAM +to use is approximate and ActivitySim often pushes a bit above the user specified amount due to pandas/numpy memory spikes for +memory intensive operations and so it is recommended to leave some RAM unallocated. The exact amount to leave unallocated depends on the +parameters above. + +To configure chunking behavior, ActivitySim must first be trained with the model setup and machine. To do so, first +run the model with ``chunk_training_mode: training``. This tracks the amount of memory used by each table by submodel and writes the results +to a cache file that is then re-used for production runs. This training mode is significantly slower than production mode since it does +significantly more memory inspection. For a training mode run, set ``num_processors`` to about 80% of the avaiable logical processors and ``chunk_size`` +to about 80% of the available RAM. This will run the model and create the ``chunk_cache.csv`` file in output\cache for reuse. After creating +the chunk cache file, the model can be run with ``chunk_training_mode: production`` and the desired ``num_processors`` and ``chunk_size``. The +model will read the chunk cache file from the output\cache folder, similar to how it reads cached skims if specified. +The software trains on the size of problem so the cache file can be re-used and only needs to be updated due to significant revisions in population, +expression, skims/network LOS, or changes in machine specs. If run in production mode and no cache file is found then ActivitySim falls +back to training mode. A third ``chunk_training_mode`` is adaptive, which if a cache file exists, runs the model with the starting cache +settings but also updates the cache settings based on additional memory inspection. This may additionally improve the cache setttings to +reduce runtimes when run in production mode. If ``resume_after`` is set, then the chunk cache file is not overwritten in cache directory +since the list of submodels would be incomplete. A foruth ``chunk_training_mode`` is disabled, which assumes the model can be run without +chunking due to an abundance of RAM. + +The following ``chunk_methods`` are supported to calculate memory overhead when chunking is enabled: + +* bytes - expected rowsize based on actual size (as reported by numpy and pandas) of explicitly allocated data this can underestimate overhead due to transient data requirements of operations (e.g. merge, sort, transpose) +* uss - expected rowsize based on change in (unique set size) (uss) both as a result of explicit data allocation, and readings by MemMonitor sniffer thread that measures transient uss during time-consuming numpy and pandas operations +* hybrid_uss - hybrid_uss avoids problems with pure uss, especially with small chunk sizes (e.g. initial training chunks) as numpy may recycle cached blocks and show no increase in uss even though data was allocated and logged +* rss - like uss, but for resident set size (rss), which is the portion of memory occupied by a process that is held in RAM +* hybrid_rss - like hybrid_uss, but for rss + +RSS is reported by psutil.memory_info and USS is reported by psutil.memory_full_info. USS is the memory which is private to +a process and which would be freed if the process were terminated. This is the metric that most closely matches the rather +vague notion of memory "in use" (the meaning of which is difficult to pin down in operating systems with virtual memory +where memory can (but sometimes can't) be swapped or mapped to disk. ``hybrid_uss`` performs best and is most reliable and +is therefore the default. + +Additional chunking settings: + +* min_available_chunk_ratio: 0.05 - minimum fraction of total chunk_size to reserve for adaptive chunking +* default_initial_rows_per_chunk: 500 - initial number of chooser rows for first chunk in training mode, when there is no pre-existing chunk_cache to set initial value, ordinarily bigger is better as long as it is not so big it causes memory issues (e.g. accessibility with lots of zones) +* keep_chunk_logs: True - whether to preserve or delete subprocess chunk logs when they are consolidated at end of multiprocess run +* keep_mem_logs: True - whether to preserve or delete subprocess mem logs when they are consolidated at end of multiprocess run + + +API +^^^ + +.. automodule:: activitysim.core.chunk + :members: + +Utilities +~~~~~~~~~ + +Vectorized helper functions + +API +^^^ + +.. automodule:: activitysim.core.util + :members: + +Config +~~~~~~ + +Helper functions for configuring a model run + +API +^^^ + +.. automodule:: activitysim.core.config + :members: + +Mem +~~~ + +Helper functions for tracking memory usage + +API +^^^ + +.. automodule:: activitysim.core.mem + :members: + +Output +~~~~~~ + +Write output files and track skim usage. + +API +^^^ + +.. automodule:: activitysim.core.steps.output + :members: + +Tests +~~~~~ + +See activitysim.core.test diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PreprocessorSettings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PreprocessorSettings.rst.txt new file mode 100644 index 000000000..8f9fdb261 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PreprocessorSettings.rst.txt @@ -0,0 +1,8 @@ +PreprocessorSettings +==================== + +.. currentmodule:: activitysim.core.configuration.base + +.. autopydantic_model:: PreprocessorSettings + :inherited-members: BaseModel + :show-inheritance: \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PydanticReadable.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PydanticReadable.rst.txt new file mode 100644 index 000000000..f6e873732 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.base.PydanticReadable.rst.txt @@ -0,0 +1,8 @@ +PydanticReadable +================ + +.. currentmodule:: activitysim.core.configuration.base + +.. autopydantic_model:: PydanticReadable + :inherited-members: BaseModel + :show-inheritance: \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitComponentSettings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitComponentSettings.rst.txt new file mode 100644 index 000000000..04ca39040 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitComponentSettings.rst.txt @@ -0,0 +1,8 @@ +LogitComponentSettings +====================== + +.. currentmodule:: activitysim.core.configuration.logit + +.. autopydantic_model:: LogitComponentSettings + :inherited-members: BaseModel + :show-inheritance: \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitNestSpec.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitNestSpec.rst.txt new file mode 100644 index 000000000..3e3f4d454 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.LogitNestSpec.rst.txt @@ -0,0 +1,8 @@ +LogitNestSpec +============= + +.. currentmodule:: activitysim.core.configuration.logit + +.. autopydantic_model:: LogitNestSpec + :inherited-members: BaseModel + :show-inheritance: \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.TemplatedLogitComponentSettings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.TemplatedLogitComponentSettings.rst.txt new file mode 100644 index 000000000..22129053e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.configuration.logit.TemplatedLogitComponentSettings.rst.txt @@ -0,0 +1,8 @@ +TemplatedLogitComponentSettings +=============================== + +.. currentmodule:: activitysim.core.configuration.logit + +.. autopydantic_model:: TemplatedLogitComponentSettings + :inherited-members: BaseModel + :show-inheritance: \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.__init__.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.__init__.rst.txt new file mode 100644 index 000000000..24175f3d1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.__init__.rst.txt @@ -0,0 +1,6 @@ +State.\_\_init\_\_ +================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.__init__ \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.access.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.access.rst.txt new file mode 100644 index 000000000..21d4b61a6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.access.rst.txt @@ -0,0 +1,6 @@ +State.access +============ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.access \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_injectable.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_injectable.rst.txt new file mode 100644 index 000000000..091e9880a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_injectable.rst.txt @@ -0,0 +1,6 @@ +State.add\_injectable +===================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.add_injectable \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_table.rst.txt new file mode 100644 index 000000000..b2096c38b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.add_table.rst.txt @@ -0,0 +1,6 @@ +State.add\_table +================ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.add_table \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.add.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.add.rst.txt new file mode 100644 index 000000000..a46bfbb0b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.add.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.add +============================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.add diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.check_against.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.check_against.rst.txt new file mode 100644 index 000000000..8c96faec2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.check_against.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.check_against +======================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.check_against diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.checkpoints.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.checkpoints.rst.txt new file mode 100644 index 000000000..d3e4163e2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.checkpoints.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.checkpoints +====================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.checkpoint.checkpoints diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.cleanup.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.cleanup.rst.txt new file mode 100644 index 000000000..232305995 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.cleanup.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.cleanup +================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.cleanup diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.close_store.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.close_store.rst.txt new file mode 100644 index 000000000..3dc27abb3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.close_store.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.close_store +====================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.close_store diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.default_pipeline_file_path.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.default_pipeline_file_path.rst.txt new file mode 100644 index 000000000..2edd9c21a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.default_pipeline_file_path.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.default_pipeline_file_path +===================================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.default_pipeline_file_path diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.get_inventory.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.get_inventory.rst.txt new file mode 100644 index 000000000..3af5a65b7 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.get_inventory.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.get_inventory +======================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.get_inventory diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.is_readonly.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.is_readonly.rst.txt new file mode 100644 index 000000000..4ea71ebd6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.is_readonly.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.is_readonly +====================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.is_readonly diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint.rst.txt new file mode 100644 index 000000000..dc2bdcd13 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.last_checkpoint +========================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.checkpoint.last_checkpoint diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint_name.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint_name.rst.txt new file mode 100644 index 000000000..92451f87c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.last_checkpoint_name.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.last_checkpoint_name +=============================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.last_checkpoint_name diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.list_tables.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.list_tables.rst.txt new file mode 100644 index 000000000..3d79f73c5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.list_tables.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.list_tables +====================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.list_tables diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load.rst.txt new file mode 100644 index 000000000..808c957e6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.load +=============================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.load diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load_dataframe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load_dataframe.rst.txt new file mode 100644 index 000000000..2e42d56b5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.load_dataframe.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.load_dataframe +========================================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.load_dataframe diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.open_store.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.open_store.rst.txt new file mode 100644 index 000000000..82a4b8747 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.open_store.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.open_store +===================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.open_store diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore.rst.txt new file mode 100644 index 000000000..0eea59dd9 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.restore +================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.restore diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore_from.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore_from.rst.txt new file mode 100644 index 000000000..f916fb917 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.restore_from.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.restore_from +======================================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.restore_from diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.rst.txt new file mode 100644 index 000000000..83a7feb87 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.rst.txt @@ -0,0 +1,6 @@ +State.checkpoint +================ + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.checkpoint \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store.rst.txt new file mode 100644 index 000000000..cc8cf3df5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.store +================================================ + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.checkpoint.store diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store_is_open.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store_is_open.rst.txt new file mode 100644 index 000000000..aae8b7d71 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.checkpoint.store_is_open.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint.store_is_open +======================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.checkpoint.store_is_open diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.chunk.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.chunk.rst.txt new file mode 100644 index 000000000..63025cee3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.chunk.rst.txt @@ -0,0 +1,6 @@ +State.chunk +=========== + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.chunk \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_on_exit.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_on_exit.rst.txt new file mode 100644 index 000000000..b38ad47cf --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_on_exit.rst.txt @@ -0,0 +1,6 @@ +State.close\_on\_exit +===================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.close_on_exit \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_open_files.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_open_files.rst.txt new file mode 100644 index 000000000..f3c9a3ff8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_open_files.rst.txt @@ -0,0 +1,6 @@ +State.close\_open\_files +======================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.close_open_files \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_pipeline.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_pipeline.rst.txt new file mode 100644 index 000000000..153fc509d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.close_pipeline.rst.txt @@ -0,0 +1,6 @@ +State.close\_pipeline +===================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.close_pipeline \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.copy.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.copy.rst.txt new file mode 100644 index 000000000..8739862b4 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.copy.rst.txt @@ -0,0 +1,6 @@ +State.copy +========== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.copy \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.current_model_name.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.current_model_name.rst.txt new file mode 100644 index 000000000..c46a5f227 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.current_model_name.rst.txt @@ -0,0 +1,6 @@ +State.current\_model\_name +========================== + +.. currentmodule:: activitysim.core.workflow + +.. autoproperty:: State.current_model_name \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.dataset.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.dataset.rst.txt new file mode 100644 index 000000000..9d52cc6a2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.dataset.rst.txt @@ -0,0 +1,6 @@ +State.dataset +============= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.dataset \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.default_settings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.default_settings.rst.txt new file mode 100644 index 000000000..8a44963db --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.default_settings.rst.txt @@ -0,0 +1,6 @@ +State.default\_settings +======================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.default_settings \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop.rst.txt new file mode 100644 index 000000000..5cd32cff5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop.rst.txt @@ -0,0 +1,6 @@ +State.drop +========== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.drop \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop_table.rst.txt new file mode 100644 index 000000000..7edd3ef89 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.drop_table.rst.txt @@ -0,0 +1,6 @@ +State.drop\_table +================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.drop_table \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_names.rst.txt new file mode 100644 index 000000000..ab9c2d61f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_names.rst.txt @@ -0,0 +1,6 @@ +State.existing\_table\_names +============================ + +.. currentmodule:: activitysim.core.workflow + +.. autoproperty:: State.existing_table_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_status.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_status.rst.txt new file mode 100644 index 000000000..07a9c93f2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.existing_table_status.rst.txt @@ -0,0 +1,6 @@ +State.existing\_table\_status +============================= + +.. currentmodule:: activitysim.core.workflow + +.. autoproperty:: State.existing_table_status \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.declare_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.declare_table.rst.txt new file mode 100644 index 000000000..6501ea92d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.declare_table.rst.txt @@ -0,0 +1,7 @@ +State.extend.declare_table +==================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.extend.declare_table diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.rst.txt new file mode 100644 index 000000000..16a3dbd90 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend.rst.txt @@ -0,0 +1,6 @@ +State.extend +============ + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.extend \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend_table.rst.txt new file mode 100644 index 000000000..a81e8df7a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extend_table.rst.txt @@ -0,0 +1,6 @@ +State.extend\_table +=================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.extend_table \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extract.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extract.rst.txt new file mode 100644 index 000000000..7054cc42d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.extract.rst.txt @@ -0,0 +1,6 @@ +State.extract +============= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.extract \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.filesystem.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.filesystem.rst.txt new file mode 100644 index 000000000..014b0eec4 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.filesystem.rst.txt @@ -0,0 +1,6 @@ +State.filesystem +================ + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.filesystem \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get.rst.txt new file mode 100644 index 000000000..0c023ed12 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get.rst.txt @@ -0,0 +1,6 @@ +State.get +========= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataarray.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataarray.rst.txt new file mode 100644 index 000000000..a283ff27f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataarray.rst.txt @@ -0,0 +1,6 @@ +State.get\_dataarray +==================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_dataarray \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe.rst.txt new file mode 100644 index 000000000..68698ca80 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe.rst.txt @@ -0,0 +1,6 @@ +State.get\_dataframe +==================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_dataframe \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe_index_name.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe_index_name.rst.txt new file mode 100644 index 000000000..2e6841203 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataframe_index_name.rst.txt @@ -0,0 +1,6 @@ +State.get\_dataframe\_index\_name +================================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_dataframe_index_name \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataset.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataset.rst.txt new file mode 100644 index 000000000..b7c4c4568 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_dataset.rst.txt @@ -0,0 +1,6 @@ +State.get\_dataset +================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_dataset \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_global_constants.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_global_constants.rst.txt new file mode 100644 index 000000000..241daac33 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_global_constants.rst.txt @@ -0,0 +1,6 @@ +State.get\_global\_constants +============================ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_global_constants \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_injectable.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_injectable.rst.txt new file mode 100644 index 000000000..f51cfecde --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_injectable.rst.txt @@ -0,0 +1,6 @@ +State.get\_injectable +===================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_injectable \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_log_file_path.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_log_file_path.rst.txt new file mode 100644 index 000000000..fd3fcb5c2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_log_file_path.rst.txt @@ -0,0 +1,6 @@ +State.get\_log\_file\_path +========================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_log_file_path \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_output_file_path.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_output_file_path.rst.txt new file mode 100644 index 000000000..02fe99bd2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_output_file_path.rst.txt @@ -0,0 +1,6 @@ +State.get\_output\_file\_path +============================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_output_file_path \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_pyarrow.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_pyarrow.rst.txt new file mode 100644 index 000000000..9b13ba4ec --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_pyarrow.rst.txt @@ -0,0 +1,6 @@ +State.get\_pyarrow +================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_pyarrow \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_rn_generator.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_rn_generator.rst.txt new file mode 100644 index 000000000..40d4e97a2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_rn_generator.rst.txt @@ -0,0 +1,6 @@ +State.get\_rn\_generator +======================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_rn_generator \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_step_arg.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_step_arg.rst.txt new file mode 100644 index 000000000..685f6af26 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_step_arg.rst.txt @@ -0,0 +1,6 @@ +State.get\_step\_arg +==================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_step_arg \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_table.rst.txt new file mode 100644 index 000000000..7ba247911 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.get_table.rst.txt @@ -0,0 +1,6 @@ +State.get\_table +================ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.get_table \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.import_extensions.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.import_extensions.rst.txt new file mode 100644 index 000000000..86b1dfe32 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.import_extensions.rst.txt @@ -0,0 +1,6 @@ +State.import\_extensions +======================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.import_extensions \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.init_state.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.init_state.rst.txt new file mode 100644 index 000000000..5f7b400d5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.init_state.rst.txt @@ -0,0 +1,6 @@ +State.init\_state +================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.init_state \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.initialize_filesystem.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.initialize_filesystem.rst.txt new file mode 100644 index 000000000..783e93fd5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.initialize_filesystem.rst.txt @@ -0,0 +1,6 @@ +State.initialize\_filesystem +============================ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.initialize_filesystem \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.is_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.is_table.rst.txt new file mode 100644 index 000000000..927b57066 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.is_table.rst.txt @@ -0,0 +1,6 @@ +State.is\_table +=============== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.is_table \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.known_table_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.known_table_names.rst.txt new file mode 100644 index 000000000..5556de4ac --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.known_table_names.rst.txt @@ -0,0 +1,6 @@ +State.known\_table\_names +========================= + +.. currentmodule:: activitysim.core.workflow + +.. autoproperty:: State.known_table_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.load_settings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.load_settings.rst.txt new file mode 100644 index 000000000..1febeb1dc --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.load_settings.rst.txt @@ -0,0 +1,6 @@ +State.load\_settings +==================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.load_settings \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.config_logger.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.config_logger.rst.txt new file mode 100644 index 000000000..d872331b0 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.config_logger.rst.txt @@ -0,0 +1,7 @@ +State.logging.config_logger +===================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.logging.config_logger diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rotate_log_directory.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rotate_log_directory.rst.txt new file mode 100644 index 000000000..7feb2485b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rotate_log_directory.rst.txt @@ -0,0 +1,7 @@ +State.logging.rotate_log_directory +============================================================ + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.logging.rotate_log_directory diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rst.txt new file mode 100644 index 000000000..06d7876e8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.logging.rst.txt @@ -0,0 +1,6 @@ +State.logging +============= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.logging \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_default.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_default.rst.txt new file mode 100644 index 000000000..4a769bca4 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_default.rst.txt @@ -0,0 +1,6 @@ +State.make\_default +=================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.make_default \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_temp.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_temp.rst.txt new file mode 100644 index 000000000..d7da05383 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.make_temp.rst.txt @@ -0,0 +1,6 @@ +State.make\_temp +================ + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.make_temp \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.network_settings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.network_settings.rst.txt new file mode 100644 index 000000000..28f39b59c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.network_settings.rst.txt @@ -0,0 +1,6 @@ +State.network\_settings +======================= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.network_settings \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.open_files.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.open_files.rst.txt new file mode 100644 index 000000000..9d98b45f8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.open_files.rst.txt @@ -0,0 +1,6 @@ +State.open\_files +================= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.open_files \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.pipeline_table_key.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.pipeline_table_key.rst.txt new file mode 100644 index 000000000..9d4b9c92b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.pipeline_table_key.rst.txt @@ -0,0 +1,6 @@ +State.pipeline\_table\_key +========================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.pipeline_table_key \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.registered_tables.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.registered_tables.rst.txt new file mode 100644 index 000000000..dc07db9ef --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.registered_tables.rst.txt @@ -0,0 +1,6 @@ +State.registered\_tables +======================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.registered_tables \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.report.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.report.rst.txt new file mode 100644 index 000000000..a293420af --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.report.rst.txt @@ -0,0 +1,6 @@ +State.report +============ + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.report \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rng.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rng.rst.txt new file mode 100644 index 000000000..24eac8980 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rng.rst.txt @@ -0,0 +1,6 @@ +State.rng +========= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.rng \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rst.txt new file mode 100644 index 000000000..d6493042e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.rst.txt @@ -0,0 +1,84 @@ +State +===== + +.. currentmodule:: activitysim.core.workflow + +.. autoclass:: State + + + + .. rubric:: Methods + + .. autosummary:: + :toctree: + + ~State.__init__ + ~State.access + ~State.add_injectable + ~State.add_table + ~State.close_on_exit + ~State.close_open_files + ~State.close_pipeline + ~State.copy + ~State.default_settings + ~State.drop + ~State.drop_table + ~State.extend_table + ~State.extract + ~State.get + ~State.get_dataarray + ~State.get_dataframe + ~State.get_dataframe_index_name + ~State.get_dataset + ~State.get_global_constants + ~State.get_injectable + ~State.get_log_file_path + ~State.get_output_file_path + ~State.get_pyarrow + ~State.get_rn_generator + ~State.get_step_arg + ~State.get_table + ~State.import_extensions + ~State.init_state + ~State.initialize_filesystem + ~State.is_table + ~State.load_settings + ~State.make_default + ~State.make_temp + ~State.pipeline_table_key + ~State.registered_tables + ~State.rng + ~State.set + ~State.set_step_args + ~State.should_save_checkpoint + ~State.trace_memory_info + ~State.uncheckpointed_table_names + + + + + + .. rubric:: Attributes + + .. autosummary:: + :toctree: + + ~State.checkpoint + ~State.chunk + ~State.current_model_name + ~State.dataset + ~State.existing_table_names + ~State.existing_table_status + ~State.extend + ~State.filesystem + ~State.known_table_names + ~State.logging + ~State.network_settings + ~State.report + ~State.run + ~State.settings + ~State.this_step + ~State.tracing + ~State.open_files + + \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.all.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.all.rst.txt new file mode 100644 index 000000000..eef96f8aa --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.all.rst.txt @@ -0,0 +1,7 @@ +State.run.all +======================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.run.all diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.by_name.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.by_name.rst.txt new file mode 100644 index 000000000..e8aba58fd --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.by_name.rst.txt @@ -0,0 +1,7 @@ +State.run.by_name +=========================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.run.by_name diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.heading_level.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.heading_level.rst.txt new file mode 100644 index 000000000..c396b1118 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.heading_level.rst.txt @@ -0,0 +1,7 @@ +State.run.heading_level +================================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.run.heading_level diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.rst.txt new file mode 100644 index 000000000..998ab0d1a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.run.rst.txt @@ -0,0 +1,6 @@ +State.run +========= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.run \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set.rst.txt new file mode 100644 index 000000000..1a07fbbc4 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set.rst.txt @@ -0,0 +1,6 @@ +State.set +========= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.set \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set_step_args.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set_step_args.rst.txt new file mode 100644 index 000000000..e086bd31d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.set_step_args.rst.txt @@ -0,0 +1,6 @@ +State.set\_step\_args +===================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.set_step_args \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.settings.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.settings.rst.txt new file mode 100644 index 000000000..7a1111b80 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.settings.rst.txt @@ -0,0 +1,6 @@ +State.settings +============== + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.settings \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.should_save_checkpoint.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.should_save_checkpoint.rst.txt new file mode 100644 index 000000000..a8efc6af3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.should_save_checkpoint.rst.txt @@ -0,0 +1,6 @@ +State.should\_save\_checkpoint +============================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.should_save_checkpoint \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.this_step.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.this_step.rst.txt new file mode 100644 index 000000000..242f05ec6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.this_step.rst.txt @@ -0,0 +1,6 @@ +State.this\_step +================ + +.. currentmodule:: activitysim.core.workflow + +.. autoproperty:: State.this_step \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.trace_memory_info.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.trace_memory_info.rst.txt new file mode 100644 index 000000000..c611bb835 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.trace_memory_info.rst.txt @@ -0,0 +1,6 @@ +State.trace\_memory\_info +========================= + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.trace_memory_info \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_output_files.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_output_files.rst.txt new file mode 100644 index 000000000..5e5878dea --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_output_files.rst.txt @@ -0,0 +1,7 @@ +State.tracing.delete_output_files +=========================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.delete_output_files diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_trace_files.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_trace_files.rst.txt new file mode 100644 index 000000000..8ef1141a8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.delete_trace_files.rst.txt @@ -0,0 +1,7 @@ +State.tracing.delete_trace_files +========================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.delete_trace_files diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.deregister_traceable_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.deregister_traceable_table.rst.txt new file mode 100644 index 000000000..0ea9cb120 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.deregister_traceable_table.rst.txt @@ -0,0 +1,7 @@ +State.tracing.deregister_traceable_table +================================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.deregister_traceable_table diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.dump_df.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.dump_df.rst.txt new file mode 100644 index 000000000..ada42b561 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.dump_df.rst.txt @@ -0,0 +1,7 @@ +State.tracing.dump_df +=============================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.dump_df diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.get_trace_target.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.get_trace_target.rst.txt new file mode 100644 index 000000000..367914464 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.get_trace_target.rst.txt @@ -0,0 +1,7 @@ +State.tracing.get_trace_target +======================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.get_trace_target diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.has_trace_targets.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.has_trace_targets.rst.txt new file mode 100644 index 000000000..b9dc09590 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.has_trace_targets.rst.txt @@ -0,0 +1,7 @@ +State.tracing.has_trace_targets +========================================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.has_trace_targets diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.initialize.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.initialize.rst.txt new file mode 100644 index 000000000..6622f07aa --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.initialize.rst.txt @@ -0,0 +1,7 @@ +State.tracing.initialize +================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.initialize diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.register_traceable_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.register_traceable_table.rst.txt new file mode 100644 index 000000000..55360e1ff --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.register_traceable_table.rst.txt @@ -0,0 +1,7 @@ +State.tracing.register_traceable_table +================================================================ + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.register_traceable_table diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.rst.txt new file mode 100644 index 000000000..54f9dd99f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.rst.txt @@ -0,0 +1,6 @@ +State.tracing +============= + +.. currentmodule:: activitysim.core.workflow + +.. autoattribute:: State.tracing \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.run_id.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.run_id.rst.txt new file mode 100644 index 000000000..7fcf34902 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.run_id.rst.txt @@ -0,0 +1,7 @@ +State.tracing.run_id +============================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.tracing.run_id diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_df.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_df.rst.txt new file mode 100644 index 000000000..184befa82 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_df.rst.txt @@ -0,0 +1,7 @@ +State.tracing.trace_df +================================================ + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.trace_df diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_interaction_eval_results.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_interaction_eval_results.rst.txt new file mode 100644 index 000000000..23bade4f3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_interaction_eval_results.rst.txt @@ -0,0 +1,7 @@ +State.tracing.trace_interaction_eval_results +====================================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.trace_interaction_eval_results diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_targets.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_targets.rst.txt new file mode 100644 index 000000000..d22a5b3e9 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.trace_targets.rst.txt @@ -0,0 +1,7 @@ +State.tracing.trace_targets +===================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.trace_targets diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_ids.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_ids.rst.txt new file mode 100644 index 000000000..822fff954 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_ids.rst.txt @@ -0,0 +1,7 @@ +State.tracing.traceable_table_ids +=========================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.tracing.traceable_table_ids diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_indexes.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_indexes.rst.txt new file mode 100644 index 000000000..24bf86715 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_table_indexes.rst.txt @@ -0,0 +1,7 @@ +State.tracing.traceable_table_indexes +=============================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.tracing.traceable_table_indexes diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_tables.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_tables.rst.txt new file mode 100644 index 000000000..e2fd4276e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.traceable_tables.rst.txt @@ -0,0 +1,7 @@ +State.tracing.traceable_tables +======================================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.tracing.traceable_tables diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.validation_directory.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.validation_directory.rst.txt new file mode 100644 index 000000000..1a5229c6e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.validation_directory.rst.txt @@ -0,0 +1,7 @@ +State.tracing.validation_directory +============================================================ + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorattribute:: State.tracing.validation_directory diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.write_csv.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.write_csv.rst.txt new file mode 100644 index 000000000..8b54299ca --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.tracing.write_csv.rst.txt @@ -0,0 +1,7 @@ +State.tracing.write_csv +================================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessormethod:: State.tracing.write_csv diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.uncheckpointed_table_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.uncheckpointed_table_names.rst.txt new file mode 100644 index 000000000..92ebcc2d1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.State.uncheckpointed_table_names.rst.txt @@ -0,0 +1,6 @@ +State.uncheckpointed\_table\_names +================================== + +.. currentmodule:: activitysim.core.workflow + +.. automethod:: State.uncheckpointed_table_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.cached_object.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.cached_object.rst.txt new file mode 100644 index 000000000..199ca202e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.cached_object.rst.txt @@ -0,0 +1,8 @@ +cached\_object +============== + + +.. currentmodule:: activitysim.core.workflow + +.. autoclass:: cached_object + :show-inheritance: diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.__init__.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.__init__.rst.txt new file mode 100644 index 000000000..ade4927ff --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.__init__.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.\_\_init\_\_ +=================================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.__init__ \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.close.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.close.rst.txt new file mode 100644 index 000000000..3e85cac0c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.close.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.close +============================ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.close \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.filename.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.filename.rst.txt new file mode 100644 index 000000000..7e2baeffe --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.filename.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.filename +=============================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: GenericCheckpointStore.filename \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.from_hdf.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.from_hdf.rst.txt new file mode 100644 index 000000000..4f2f1884d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.from_hdf.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.from\_hdf +================================ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.from_hdf \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.get_dataframe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.get_dataframe.rst.txt new file mode 100644 index 000000000..b6410c31d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.get_dataframe.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.get\_dataframe +===================================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.get_dataframe \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_open.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_open.rst.txt new file mode 100644 index 000000000..fdb24ae25 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_open.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.is\_open +=============================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: GenericCheckpointStore.is_open \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_readonly.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_readonly.rst.txt new file mode 100644 index 000000000..5d29a312b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.is_readonly.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.is\_readonly +=================================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: GenericCheckpointStore.is_readonly \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.list_checkpoint_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.list_checkpoint_names.rst.txt new file mode 100644 index 000000000..6d1ab2000 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.list_checkpoint_names.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.list\_checkpoint\_names +============================================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.list_checkpoint_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.put.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.put.rst.txt new file mode 100644 index 000000000..d62a43b3e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.put.rst.txt @@ -0,0 +1,6 @@ +GenericCheckpointStore.put +========================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: GenericCheckpointStore.put \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.rst.txt new file mode 100644 index 000000000..f8b62fd09 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.GenericCheckpointStore.rst.txt @@ -0,0 +1,35 @@ +GenericCheckpointStore +====================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoclass:: GenericCheckpointStore + + + + .. rubric:: Methods + + .. autosummary:: + :toctree: + + ~GenericCheckpointStore.__init__ + ~GenericCheckpointStore.close + ~GenericCheckpointStore.from_hdf + ~GenericCheckpointStore.get_dataframe + ~GenericCheckpointStore.list_checkpoint_names + ~GenericCheckpointStore.put + + + + + + .. rubric:: Attributes + + .. autosummary:: + :toctree: + + ~GenericCheckpointStore.filename + ~GenericCheckpointStore.is_open + ~GenericCheckpointStore.is_readonly + + \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.__init__.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.__init__.rst.txt new file mode 100644 index 000000000..8d6c050d4 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.__init__.rst.txt @@ -0,0 +1,6 @@ +HdfStore.\_\_init\_\_ +===================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.__init__ \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.close.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.close.rst.txt new file mode 100644 index 000000000..c1caf09c2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.close.rst.txt @@ -0,0 +1,6 @@ +HdfStore.close +============== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.close \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.filename.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.filename.rst.txt new file mode 100644 index 000000000..9bb83db6c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.filename.rst.txt @@ -0,0 +1,6 @@ +HdfStore.filename +================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: HdfStore.filename \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.from_hdf.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.from_hdf.rst.txt new file mode 100644 index 000000000..0ba2c3644 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.from_hdf.rst.txt @@ -0,0 +1,6 @@ +HdfStore.from\_hdf +================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.from_hdf \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.get_dataframe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.get_dataframe.rst.txt new file mode 100644 index 000000000..d3c3247f9 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.get_dataframe.rst.txt @@ -0,0 +1,6 @@ +HdfStore.get\_dataframe +======================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.get_dataframe \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_open.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_open.rst.txt new file mode 100644 index 000000000..8ed3a2231 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_open.rst.txt @@ -0,0 +1,6 @@ +HdfStore.is\_open +================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: HdfStore.is_open \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_readonly.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_readonly.rst.txt new file mode 100644 index 000000000..fd7291f56 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.is_readonly.rst.txt @@ -0,0 +1,6 @@ +HdfStore.is\_readonly +===================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: HdfStore.is_readonly \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.list_checkpoint_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.list_checkpoint_names.rst.txt new file mode 100644 index 000000000..acee31df1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.list_checkpoint_names.rst.txt @@ -0,0 +1,6 @@ +HdfStore.list\_checkpoint\_names +================================ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.list_checkpoint_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.put.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.put.rst.txt new file mode 100644 index 000000000..398cb89da --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.put.rst.txt @@ -0,0 +1,6 @@ +HdfStore.put +============ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: HdfStore.put \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.rst.txt new file mode 100644 index 000000000..59cd46579 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.HdfStore.rst.txt @@ -0,0 +1,35 @@ +HdfStore +======== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoclass:: HdfStore + + + + .. rubric:: Methods + + .. autosummary:: + :toctree: + + ~HdfStore.__init__ + ~HdfStore.close + ~HdfStore.from_hdf + ~HdfStore.get_dataframe + ~HdfStore.list_checkpoint_names + ~HdfStore.put + + + + + + .. rubric:: Attributes + + .. autosummary:: + :toctree: + + ~HdfStore.filename + ~HdfStore.is_open + ~HdfStore.is_readonly + + \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.__init__.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.__init__.rst.txt new file mode 100644 index 000000000..0fed23501 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.__init__.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.\_\_init\_\_ +========================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.__init__ \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.close.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.close.rst.txt new file mode 100644 index 000000000..f629d2b4d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.close.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.close +================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.close \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.extension.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.extension.rst.txt new file mode 100644 index 000000000..5f0763bfb --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.extension.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.extension +====================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoattribute:: ParquetStore.extension \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.filename.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.filename.rst.txt new file mode 100644 index 000000000..9f73db4d5 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.filename.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.filename +===================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: ParquetStore.filename \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.from_hdf.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.from_hdf.rst.txt new file mode 100644 index 000000000..f6f95cf77 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.from_hdf.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.from\_hdf +====================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.from_hdf \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.get_dataframe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.get_dataframe.rst.txt new file mode 100644 index 000000000..8961d19ad --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.get_dataframe.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.get\_dataframe +=========================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.get_dataframe \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_open.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_open.rst.txt new file mode 100644 index 000000000..618d48de1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_open.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.is\_open +===================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: ParquetStore.is_open \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_readonly.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_readonly.rst.txt new file mode 100644 index 000000000..d02b0ab01 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.is_readonly.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.is\_readonly +========================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoproperty:: ParquetStore.is_readonly \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.list_checkpoint_names.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.list_checkpoint_names.rst.txt new file mode 100644 index 000000000..bcf4c7567 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.list_checkpoint_names.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.list\_checkpoint\_names +==================================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.list_checkpoint_names \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.make_zip_archive.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.make_zip_archive.rst.txt new file mode 100644 index 000000000..ab9cda507 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.make_zip_archive.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.make\_zip\_archive +=============================== + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.make_zip_archive \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.put.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.put.rst.txt new file mode 100644 index 000000000..8221ee204 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.put.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.put +================ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.put \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.rst.txt new file mode 100644 index 000000000..9573f318e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.rst.txt @@ -0,0 +1,38 @@ +ParquetStore +============ + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. autoclass:: ParquetStore + + + + .. rubric:: Methods + + .. autosummary:: + :toctree: + + ~ParquetStore.__init__ + ~ParquetStore.close + ~ParquetStore.from_hdf + ~ParquetStore.get_dataframe + ~ParquetStore.list_checkpoint_names + ~ParquetStore.make_zip_archive + ~ParquetStore.put + ~ParquetStore.wipe + + + + + + .. rubric:: Attributes + + .. autosummary:: + :toctree: + + ~ParquetStore.extension + ~ParquetStore.filename + ~ParquetStore.is_open + ~ParquetStore.is_readonly + + \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.wipe.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.wipe.rst.txt new file mode 100644 index 000000000..f6fa32cd9 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.checkpoint.ParquetStore.wipe.rst.txt @@ -0,0 +1,6 @@ +ParquetStore.wipe +================= + +.. currentmodule:: activitysim.core.workflow.checkpoint + +.. automethod:: ParquetStore.wipe \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.create_example.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.create_example.rst.txt new file mode 100644 index 000000000..70b1059f0 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.create_example.rst.txt @@ -0,0 +1,6 @@ +create\_example +=============== + +.. currentmodule:: activitysim.core.workflow + +.. autofunction:: create_example \ No newline at end of file diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.step.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.step.rst.txt new file mode 100644 index 000000000..93f931f20 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.step.rst.txt @@ -0,0 +1,8 @@ +step +==== + + +.. currentmodule:: activitysim.core.workflow + +.. autoclass:: step + :show-inheritance: diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.table.rst.txt new file mode 100644 index 000000000..7458023a0 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.table.rst.txt @@ -0,0 +1,8 @@ +table +===== + + +.. currentmodule:: activitysim.core.workflow + +.. autoclass:: table + :show-inheritance: diff --git a/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.temp_table.rst.txt b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.temp_table.rst.txt new file mode 100644 index 000000000..5682f0ea1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated/activitysim.core.workflow.temp_table.rst.txt @@ -0,0 +1,8 @@ +temp\_table +=========== + + +.. currentmodule:: activitysim.core.workflow + +.. autoclass:: temp_table + :show-inheritance: diff --git a/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.checkpoint.rst.txt b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.checkpoint.rst.txt new file mode 100644 index 000000000..7b7e5d2a6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.checkpoint.rst.txt @@ -0,0 +1,7 @@ +State.checkpoint +========================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessor:: State.checkpoint diff --git a/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.dataset.rst.txt b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.dataset.rst.txt new file mode 100644 index 000000000..dadcd04d8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.dataset.rst.txt @@ -0,0 +1,7 @@ +State.dataset +======================================= + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessor:: State.dataset diff --git a/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.extend.rst.txt b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.extend.rst.txt new file mode 100644 index 000000000..6075c74ee --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.extend.rst.txt @@ -0,0 +1,7 @@ +State.extend +====================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessor:: State.extend diff --git a/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.report.rst.txt b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.report.rst.txt new file mode 100644 index 000000000..c8e88da0b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.report.rst.txt @@ -0,0 +1,7 @@ +State.report +====================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessor:: State.report diff --git a/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.run.rst.txt b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.run.rst.txt new file mode 100644 index 000000000..f7b98ba42 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/_generated2/activitysim.core.workflow.State.run.rst.txt @@ -0,0 +1,7 @@ +State.run +=================================== + + +.. currentmodule:: activitysim.core.workflow + +.. autoaccessorcallable:: State.run.__call__ diff --git a/v1.3.0/_sources/dev-guide/build-docs.md.txt b/v1.3.0/_sources/dev-guide/build-docs.md.txt new file mode 100644 index 000000000..dc8c5d67d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/build-docs.md.txt @@ -0,0 +1,49 @@ + +(write-docs)= +# Documentation + +The core documentation for ActivitySim is built with [Sphinx](https://www.sphinx-doc.org). +The input files for this documentation can be written either in +[markdown](https://www.markdownguide.org) with filenames ending in `.md` (preferred +for new documentation pages) or +[reStructuredText](http://docutils.sourceforge.net/rst.html) with filenames ending in `.rst`. +In addition to converting *.md and *.rst files +to html format, Sphinx can also read the inline Python docstrings and convert +them into html as well. ActivitySim's docstrings are written in +[numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) format. + +## Building the Documentation + +Developers who want to test a build of the ActivitySim documentation locally can +do so using `sphinx`. A pre-packaged conda environment is available to simplify this +process. On the command line, starting from the `activitysim` directory that constitutes the +main repository (i.e. you should see subdirectories including `activitysim`, +`conda-environments`, `docs`, and a few others) run these commands: + +```bash +mkdir -p ../.env +mamba env update -p ../.env/DOCBUILD -f conda-environments/docbuild.yml +conda activate ../.env/DOCBUILD +cd docs +make clean +make html +``` + +This will build the docs in the `docs/_build/html` directory. They can be viewed +in a web browser using the `file:///` protocol, or by double-clicking on the +`index.html` file (or any other .html file in that directory). + +## Automatic Documentation Builds + +Documentation can also be rendered online automatically by GitHub. Several scripts +are included in this repository's GitHub Actions to do so when updates are made +to the `main` or `develop` branches in the primary `ActivitySim` repository. + +If you are working in a *fork* of the primary `ActivitySim/activitysim` repository, you +can generate test builds of the documentation by pushing a commit to your branch +with the tag `[makedocs]` in the commit message. Note to prevent conflicts this +only works on a fork, not within the primary `ActivitySim` repository, and only +on branches named something other than `develop`. The documentation will then be +published on your own subdomain. For example, if your fork is `tacocat/activitysim`, +and you are working on the `featuring-cilantro` branch, the GitHub will render your +documentation build at `https://tacocat.github.io/activitysim/featuring-cilantro`. diff --git a/v1.3.0/_sources/dev-guide/changes.md.txt b/v1.3.0/_sources/dev-guide/changes.md.txt new file mode 100644 index 000000000..e8a94effd --- /dev/null +++ b/v1.3.0/_sources/dev-guide/changes.md.txt @@ -0,0 +1,283 @@ +# Change Log + +This document describes significant changes to ActivitySim. This includes +major new features that may require modifications to existing model configurations +or code to utilize, as well as breaking changes that may cause existing model +configurations or code to fail to run correctly. + +## v1.3 + +### New Canonical Examples + +Beginning with version 1.3, ActivitySim provides two supported "canonical" example +implementations: + +- the [SANDAG Model](https://github.com/ActivitySim/sandag-abm3-example) is a two-zone + model based on the SANDAG ABM3 model, and +- the [MTC Model](https://github.com/ActivitySim/activitysim-prototype-mtc) is a + one-zone model based on the MTC's Travel Model One. + +Each example implementation includes a complete set of model components, input data, +and configuration files, and is intended to serve as a reference for users to build +their own models. They are provided as stand-alone repositories, to highlight the +fact that model implementations are separate from the ActivitySim core codebase, +and to make it easier for users to fork and modify the examples for their own use +without needing to modify the ActivitySim core codebase. The examples are maintained +by the ActivitySim Consortium and are kept up-to-date with the latest version of +ActivitySim. + +```{note} +The two example models are not identical to the original agency models from which +they were created. They are generally similar to those models, and have been calibrated +and validated to reproduce reasonable results. They are intended to demonstrate the +capabilities of ActivitySim and to provide a starting point for users to build their own +models. However, they are not intended to be used as-is for policy analysis or forecasting. +``` + +### Logging + +The reading of YAML configuration files has been modified to use the "safe" reader, +which prohibits the use of arbitrary Python code in configuration files. This is a +security enhancement, but it requires some changes to the way logging is configured. + +In previous versions, the logging configuration file could contain Python code to +place log files in various subdirectories of the output directory, which might +vary for different subprocesses of the model, like this: + +```yaml +logging: + handlers: + logfile: + class: logging.FileHandler + filename: !!python/object/apply:activitysim.core.config.log_file_path ['activitysim.log'] + mode: w + formatter: fileFormatter + level: NOTSET +``` + +In the new version, the use of `!!python/object/apply` is prohibited. Instead of using +this directive, the `log_file_path` function can be invoked in the configuration file +by using the `get_log_file_path` key, like this: + +```yaml +logging: + handlers: + logfile: + class: logging.FileHandler + filename: + get_log_file_path: activitysim.log + mode: w + formatter: fileFormatter + level: NOTSET +``` + +Similarly, previous use of the `if_sub_task` directive in the logging level +configuration like this: + +```yaml +logging: + handlers: + console: + class: logging.StreamHandler + stream: ext://sys.stdout + level: !!python/object/apply:activitysim.core.mp_tasks.if_sub_task [WARNING, NOTSET] + formatter: elapsedFormatter +``` + +can be replaced with the `if_sub_task` and `if_not_sub_task` keys, like this: + +```yaml +logging: + handlers: + console: + class: logging.StreamHandler + stream: ext://sys.stdout + level: + if_sub_task: WARNING + if_not_sub_task: NOTSET + formatter: elapsedFormatter +``` + +For more details, see [logging](Logging). + +### Chunking + +Version 1.3 introduces a new "[explicit](Explicit-Chunking)" chunking mechanism. + +Explicit chunking is simpler to use and understand than dynamic chunking, and in +practice has been found to be more robust and reliable. It requires no "training" +and is activated in the top level model configuration file (typically `settings.yaml`): + +```yaml +chunk_training_mode: explicit +``` + +Then, for model components that may stress the memory limits of the machine, +the user can specify the number of choosers in each chunk explicitly, either as an integer +number of choosers per chunk, or as a fraction of the overall number of choosers. +This is done by setting the `explicit_chunk` configuration setting in the model +component's settings. For this setting, integer values greater than or equal to 1 +correspond to the number of chooser rows in each explicit chunk. Fractional values +less than 1 correspond to the fraction of the total number of choosers. +If the `explicit_chunk` value is 0 or missing, then no chunking +is applied for that component. The `explicit_chunk` values in each component's +settings are ignored if the `chunk_training_mode` is not set to `explicit`. +Refer to each model component's configuration documentation for details. + +Refer to code updates that implement explicit chunking for accessibility in +[PR #759](https://github.com/ActivitySim/activitysim/pull/759), for +vehicle type choice, non-mandatory tour frequency, school escorting, and +joint tour frequency in [PR #804](https://github.com/ActivitySim/activitysim/pull/804), +and all remaining interaction-simulate components in +[PR #870](https://github.com/ActivitySim/activitysim/pull/870). + +### Automatic dropping of unused columns + +Variables that are not used in a model component are now automatically dropped +from the chooser table before the component is run. Whether a variable is deemed +as "used" is determined by a text search of the model component code and specification +files for the variable name. Dropping unused columns can be disabled by setting +[`drop_unused_columns`](activitysim.core.configuration.base.ComputeSettings.drop_unused_columns) +to `False` in the [`compute_settings`](activitysim.core.configuration.base.ComputeSettings) +for any model component, but by default this setting is `True`, as it can result in a +significant reduction in memory usage for large models. + +Dropping columns may also cause problems if the model is not correctly configured. +If it is desired to use this feature, but some required columns are being dropped +incorrectly, the user can specify columns that should not be dropped by setting the +[`protect_columns`](activitysim.core.configuration.base.ComputeSettings.protect_columns) +setting under [`compute_settings`](activitysim.core.configuration.base.ComputeSettings). +This allows the user to specify columns that should not be dropped, even if they are +not apparently used in the model component. For [example](https://github.com/ActivitySim/activitysim/blob/67820ad32789f59217608b5311e9a2a322d029ed/activitysim/examples/prototype_sandag_xborder/configs/tour_od_choice.yaml#L59-L61): + +```yaml +compute_settings: + protect_columns: + - origin_destination +``` + +Code updates to drop unused columns are in +[PR #833](https://github.com/ActivitySim/activitysim/pull/833) and to protect +columns in [PR #871](https://github.com/ActivitySim/activitysim/pull/871). + +### Automatic conversion of string data to categorical + +Version 1.3 introduces a new feature that automatically converts string data +to categorical data. This reduces memory usage and speeds up processing for +large models. The conversion is done automatically for string columns +in most chooser tables. + +To further reduce memory usage, there is also an optional downcasting of numeric +data available. For example, this allows storing integers that never exceed 255 +as `int8` instead of `int64`. This feature is controlled by the `downcast_int` +and `downcast_float` settings in the top level model configuration file (typically +`settings.yaml`). The default value for these settings is `False`, meaning that +downcasting is not applied. It is recommended to leave these settings at their +default values unless memory availability is severely constrained, as downcasting +can cause numerical instability in some cases. First, changing the precision of +numeric data could cause results to change slightly and impact a previous calibrated +model result. Second, downcasting to lower byte data types, e.g., int8, can cause +numeric overflow in downstream components if the numeric variable is used in +mathematical calculations that would result in values beyond the lower bit width +limit (e.g. squaring the value). If downcasting is desired, it is strongly recommended +to review all model specifications for compatability, and to review model results +to verify if the changes are acceptable. + +See code updates in [PR #782](https://github.com/ActivitySim/activitysim/pull/782) +and [PR #863](https://github.com/ActivitySim/activitysim/pull/863) + +### Alternatives preprocessors for trip destination. + +Added alternatives preprocessor in +[PR #865](https://github.com/ActivitySim/activitysim/pull/869), +and converted to separate preprocessors for sample (at the TAZ level) and +simulate (at the MAZ level for 2 zone systems) in +[PR #869](https://github.com/ActivitySim/activitysim/pull/869). + +### Per-component sharrow controls + +This version adds a uniform interface for controlling sharrow optimizations +at the component level. This allows users to disable sharrow entirely, +or to disable the "fastmath" optimization for individual components. +Controls for sharrow are set in each component's settings under `compute_settings`. +For example, to disable sharrow entirely for a component, use: + +```yaml +compute_settings: + sharrow_skip: true +``` + +This overrides the global sharrow setting, and is useful if you want to skip +sharrow for particular components, either because their specifications are +not compatible with sharrow or if the sharrow performance is known to be +poor on this component. + +When a component has multiple subcomponents, the `sharrow_skip` setting can be +a dictionary that maps the names of the subcomponents to boolean values. +For example, in the school escorting component, to skip sharrow for an +OUTBOUND and OUTBOUND_COND subcomponent but not the INBOUND subcomponent, +use the following settings: + +```yaml +compute_settings: + sharrow_skip: + OUTBOUND: true + INBOUND: false + OUTBOUND_COND: true +``` + +The `compute_settings` can also be used to disable the "fastmath" optimization. +This is useful if the component is known to have numerical stability issues +with the fastmath optimization enabled, usually when the component potentially +works with data that includes `NaN` or `Inf` values. To disable fastmath for +a component, use: + +```yaml +compute_settings: + fastmath: false +``` + +Code updates that apply these settings are in +[PR #824](https://github.com/ActivitySim/activitysim/pull/824). + +### Configuration validation + +Version 1.3 adds a configuration validation system using the Pydantic library. +Previously, the YAML-based configuration files were allowed to contain arbitrary +keys and values, which could lead to errors if the configuration was not correctly +specified. The new validation system checks the configuration files for correctness, +and provides useful error messages if the configuration is invalid. Invalid +conditions include missing required keys, incorrect data types, and the presence +of unexpected keys. Existing models may need to be cleaned up (i.e. extraneous settings +in config files removed) to conform to the new validation system. + +See [PR #758](https://github.com/ActivitySim/activitysim/pull/758) for code updates. + +### Input checker + +Version 1.3 adds an input checker that verifies that the input data is consistent +with expectations. This tool can help identify problems with the input data before +the model is run, and can be used to ensure that the input data is correctly +formatted and complete. + +See [PR #753](https://github.com/ActivitySim/activitysim/pull/753) for code updates. + +### Removal of orca dependency + +This new version of ActivitySim does not use `orca` as a dependency, and thus does +not rely on orca’s global state to manage data. Instead, a new [`State`](activitysim.core.workflow.State) +class is introduced, which encapsulates the current state of a simulation including +all data tables. This is a significant change “under the hood”, which may be +particularly consequential for model that use “extensions” to the ActivitySim framework. +See [PR #654](https://github.com/ActivitySim/activitysim/pull/654) for code updates. + +## v1.2 + +The [v1.2](https://github.com/ActivitySim/activitysim/releases/tag/v1.2.0) release +includes all updates and enhancements complete in the ActivitySim Consortium's Phase 7 +development cycle, including: + +- Sharrow performance enhancement +- Explicit school escorting +- Disaggregate accessibility +- Simulation-based shadow pricing diff --git a/v1.3.0/_sources/dev-guide/checkpointing.md.txt b/v1.3.0/_sources/dev-guide/checkpointing.md.txt new file mode 100644 index 000000000..0698a7b63 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/checkpointing.md.txt @@ -0,0 +1,45 @@ +# Checkpointing + +```{eval-rst} +.. currentmodule:: activitysim.core.workflow.checkpoint +``` + +ActivitySim provides a checkpointing mechanism, whereby the content of data tables +can be stored to disk in an intermediate state. This intermediate state can +subsequently be restored from disk, setting up the data tables to resume +simulation from that point forward. + +There are currently two data file formats available for checkpointing: + +- [HDF5](https://www.hdfgroup.org/solutions/hdf5/), the longstanding default + format for ActivitySim checkpointing, and +- [Apache Parquet](https://parquet.apache.org/), added as an option as of + ActivitySim version 1.3. + +## Usage + +The operation of automatic checkpointing during an ActivitySim run is controlled +via a few values in the top-level settings: + +- [`checkpoint_format`](activitysim.core.configuration.Settings.checkpoint_format) + controls which checkpoint data file format is used. +- [`checkpoints`](activitysim.core.configuration.Settings.checkpoints) + controls how frequently checkpoints are written (after every component, after + only certain components, or not at all). + +For code developers wanting to integrate some aspect of checkpointing into +a manual workflow or a new component, the +[`State.checkpoint`](activitysim.core.workflow.State.checkpoint) +accessor has most of the relevant methods. + +## API + +```{eval-rst} +.. autosummary:: + :toctree: _generated + :recursive: + + GenericCheckpointStore + HdfStore + ParquetStore +``` diff --git a/v1.3.0/_sources/dev-guide/component-configs.md.txt b/v1.3.0/_sources/dev-guide/component-configs.md.txt new file mode 100644 index 000000000..0fd1a9705 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/component-configs.md.txt @@ -0,0 +1,20 @@ +(component-config)= +# Component Configuration + +Individual components each have their own component-level configuration. These +configuration can include custom component-specific settings, as well as groups +of settings from these boilerplate base classes: + +```{eval-rst} +.. currentmodule:: activitysim.core.configuration +.. autosummary:: + :toctree: _generated + :template: autopydantic-inherits.rst + :recursive: + + ~base.PydanticReadable + ~base.PreprocessorSettings + ~logit.LogitComponentSettings + ~logit.TemplatedLogitComponentSettings + ~logit.LogitNestSpec +``` diff --git a/v1.3.0/_sources/dev-guide/components/accessibility.md.txt b/v1.3.0/_sources/dev-guide/components/accessibility.md.txt new file mode 100644 index 000000000..32c97d4bc --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/accessibility.md.txt @@ -0,0 +1,69 @@ +(component-accessibility)= +# Accessibility + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.accessibility +``` + +The accessibilities model is an aggregate model that calculates multiple origin-based accessibility +measures by origin zone to all destination zones. + +The accessibility measure first multiplies an employment variable by a mode-specific decay function. The +product reflects the difficulty of accessing the activities the farther (in terms of round-trip travel time) +the jobs are from the location in question. The products to each destination zone are next summed over +each origin zone, and the logarithm of the product mutes large differences. The decay function on +the walk accessibility measure is steeper than automobile or transit. The minimum accessibility is zero. + +Level-of-service variables from three time periods are used, specifically the AM peak period (6 am to 10 am), the +midday period (10 am to 3 pm), and the PM peak period (3 pm to 7 pm). + +*Inputs* + +* Highway skims for the three periods. Each skim is expected to include a table named "TOLLTIMEDA", which is the drive alone in-vehicle travel time for automobiles willing to pay a "value" (time-savings) toll. +* Transit skims for the three periods. Each skim is expected to include the following tables: (i) "IVT", in-vehicle time; (ii) "IWAIT", initial wait time; (iii) "XWAIT", transfer wait time; (iv) "WACC", walk access time; (v) "WAUX", auxiliary walk time; and, (vi) "WEGR", walk egress time. +* Zonal data with the following fields: (i) "TOTEMP", total employment; (ii) "RETEMPN", retail trade employment per the NAICS classification. + +*Outputs* + +* taz, travel analysis zone number +* autoPeakRetail, the accessibility by automobile during peak conditions to retail employment for this TAZ +* autoPeakTotal, the accessibility by automobile during peak conditions to all employment +* autoOffPeakRetail, the accessibility by automobile during off-peak conditions to retail employment +* autoOffPeakTotal, the accessibility by automobile during off-peak conditions to all employment +* transitPeakRetail, the accessibility by transit during peak conditions to retail employment +* transitPeakTotal, the accessibility by transit during peak conditions to all employment +* transitOffPeakRetail, the accessiblity by transit during off-peak conditions to retail employment +* transitOffPeakTotal, the accessiblity by transit during off-peak conditions to all employment +* nonMotorizedRetail, the accessibility by walking during all time periods to retail employment +* nonMotorizedTotal, the accessibility by walking during all time periods to all employment + +The main interface to the accessibility model is the +[compute_accessibility](activitysim.abm.models.accessibility.compute_accessibility) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `accessibility.yaml` +- *Core Table*: `skims` +- *Result Table*: `accessibility` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: AccessibilitySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/accessibility.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/accessibility.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: compute_accessibility +``` diff --git a/v1.3.0/_sources/dev-guide/components/atwork_subtour_destination.md.txt b/v1.3.0/_sources/dev-guide/components/atwork_subtour_destination.md.txt new file mode 100644 index 000000000..8c08193a2 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/atwork_subtour_destination.md.txt @@ -0,0 +1,46 @@ +(component-atwork-subtour-destination)= +# At-work Subtours Destination Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_destination +``` + +The at-work subtours destination choice model is made up of three model steps: + + * sample - selects a sample of alternative locations for the next model step. This selects X locations from the full set of model zones using a simple utility. + * logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative location. + * simulate - starts with the table created above and chooses a final location, this time with the mode choice logsum included. + +At-work subtour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interface to the at-work subtour destination model is the +[atwork_subtour_destination](ctivitysim.abm.models.atwork_subtour_destination.atwork_subtour_destination) +function. This function is registered as an Inject step in the example Pipeline. +[writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `atwork_subtour_destination.yaml` +- *Core Table*: `tours` +- *Result Field*: `destination` +- *Skims keys*: `workplace_taz, alt_dest, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_destination +``` diff --git a/v1.3.0/_sources/dev-guide/components/atwork_subtour_frequency.md.txt b/v1.3.0/_sources/dev-guide/components/atwork_subtour_frequency.md.txt new file mode 100644 index 000000000..0b0b4c78a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/atwork_subtour_frequency.md.txt @@ -0,0 +1,48 @@ +(component-atwork-subtour-frequency)= +# At-work Subtours Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_frequency +``` + +The at-work subtour frequency model selects the number of at-work subtours made for each work tour. +It also creates at-work subtours by adding them to the tours table in the data pipeline. +These at-work sub-tours are travel tours taken during the workday with their origin at the work +location, rather than from home. Explanatory variables include employment status, +income, auto ownership, the frequency of other tours, characteristics of the parent work tour, and +characteristics of the workplace zone. + +Choosers: work tours +Alternatives: none, 1 eating out tour, 1 business tour, 1 maintenance tour, 2 business tours, 1 eating out tour + 1 business tour +Dependent tables: household, person, accessibility +Outputs: work tour subtour frequency choice, at-work tours table (with only tour origin zone at this point) + +The main interface to the at-work subtours frequency model is the +[atwork_subtour_frequency](activitysim.abm.models.atwork_subtour_frequency.atwork_subtour_frequency) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `atwork_subtour_frequency.yaml` +- *Core Table*: `tours` +- *Result Field*: `atwork_subtour_frequency` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: AtworkSubtourFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_frequency +``` diff --git a/v1.3.0/_sources/dev-guide/components/atwork_subtour_mode_choice.md.txt b/v1.3.0/_sources/dev-guide/components/atwork_subtour_mode_choice.md.txt new file mode 100644 index 000000000..a3038badc --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/atwork_subtour_mode_choice.md.txt @@ -0,0 +1,41 @@ +(component-atwork-subtour-mode-choice)= +# At-work Subtour Mode + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_mode_choice +``` + +The at-work subtour mode choice model assigns a travel mode to each at-work subtour using the `tour_mode_choice` model. + +The main interface to the at-work subtour mode choice model is the +[atwork_subtour_mode_choice](activitysim.abm.models.atwork_subtour_mode_choice.atwork_subtour_mode_choice) +function. This function is called in the Inject step `atwork_subtour_mode_choice` and +is registered as an Inject step in the example Pipeline. +[writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `tour_mode_choice.yaml` +- *Core Table*: `tour` +- *Result Field*: `tour_mode` +- *Skims keys*: `workplace_taz, destination, start, end` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourModeComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_mode_choice +``` diff --git a/v1.3.0/_sources/dev-guide/components/atwork_subtour_scheduling.md.txt b/v1.3.0/_sources/dev-guide/components/atwork_subtour_scheduling.md.txt new file mode 100644 index 000000000..bac01be00 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/atwork_subtour_scheduling.md.txt @@ -0,0 +1,50 @@ +(component-atwork-subtour-scheduling)= +# At-work Subtour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_scheduling +``` + +The at-work subtours scheduling model selects a tour departure and duration period (and therefore a start and end +period as well) for each at-work subtour. This model uses person `time_windows`. + +This model is the same as the mandatory tour scheduling model except it operates on the at-work tours and +constrains the alternative set to available person `time_windows`. The at-work subtour scheduling model does not use mode choice logsums. +The at-work subtour frequency model can choose multiple tours so this model must process all first tours and then second +tours since isFirstAtWorkTour is an explanatory variable. + +Choosers: at-work tours +Alternatives: alternative departure time and arrival back at origin time pairs WITHIN the work tour departure time and arrival time back at origin AND the person time window. If no time window is available for the tour, make the first and last time periods within the work tour available, make the choice, and log the number of times this occurs. +Dependent tables: skims, person, land use, work tour +Outputs: at-work tour departure time and arrival back at origin time, updated person time windows + +The main interface to the at-work subtours scheduling model is the +[atwork_subtour_scheduling](activitysim.abm.models.atwork_subtour_scheduling.atwork_subtour_scheduling) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `tour_scheduling_atwork.yaml` +- *Core Table*: `tours` +- *Result Field*: `start, end, duration` +- *Skims keys*: `workplace_taz, alt_dest, MD time period, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourSchedulingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_scheduling_atwork.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_scheduling_atwork.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_scheduling +``` diff --git a/v1.3.0/_sources/dev-guide/components/auto_ownership.md.txt b/v1.3.0/_sources/dev-guide/components/auto_ownership.md.txt new file mode 100644 index 000000000..5c2dd6c9f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/auto_ownership.md.txt @@ -0,0 +1,36 @@ +(component-auto-ownership)= +# Auto Ownership + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.auto_ownership +``` + +The auto ownership model selects a number of autos for each household in the simulation. +The primary model components are household demographics, zonal density, and accessibility. + +## Structure + +- *Configuration File*: `auto_ownership.yaml` +- *Core Table*: `households` +- *Result Field*: `auto_owenership` + +This model is typically structured as multinomial logit model. + +## Configuration + +```{eval-rst} +.. autopydantic_model:: AutoOwnershipSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/auto_ownership.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/auto_ownership.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: auto_ownership_simulate +``` diff --git a/v1.3.0/_sources/dev-guide/components/cdap.md.txt b/v1.3.0/_sources/dev-guide/components/cdap.md.txt new file mode 100644 index 000000000..63e665543 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/cdap.md.txt @@ -0,0 +1,53 @@ +(component-cdap)= +# Coordinated Daily Activity Pattern + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.cdap +``` + +The Coordinated Daily Activity Pattern (CDAP) model predicts the choice of daily activity pattern (DAP) +for each member in the household, simultaneously. The DAP is categorized in to three types as +follows: +* Mandatory: the person engages in travel to at least one out-of-home mandatory activity - work, university, or school. The mandatory pattern may also include non-mandatory activities such as separate home-based tours or intermediate stops on mandatory tours. +* Non-mandatory: the person engages in only maintenance and discretionary tours, which, by definition, do not contain mandatory activities. +* Home: the person does not travel outside the home. + +The CDAP model is a sequence of vectorized table operations: + +* create a person level table and rank each person in the household for inclusion in the CDAP model. Priority is given to full time workers (up to two), then to part time workers (up to two workers, of any type), then to children (youngest to oldest, up to three). Additional members up to five are randomly included for the CDAP calculation. +* solve individual M/N/H utilities for each person +* take as input an interaction coefficients table and then programmatically produce and write out the expression files for households size 1, 2, 3, 4, and 5 models independent of one another +* select households of size 1, join all required person attributes, and then read and solve the automatically generated expressions +* repeat for households size 2, 3, 4, and 5. Each model is independent of one another. + +The main interface to the CDAP model is the [run_cdap](activitysim.abm.models.util.cdap.run_cdap) +function. This function is called by the Inject step `cdap_simulate` which is +registered as an Inject step in the example Pipeline. There are two cdap class definitions in +ActivitySim. The first is at [cdap](activitysim.abm.models.cdap) and contains the Inject +wrapper for running it as part of the model pipeline. The second is +at [cdap](activitysim.abm.models.util.cdap) and contains CDAP model logic. + +## Structure + +- *Configuration File*: `cdap.yaml` +- *Core Table*: `persons` +- *Result Field*: `cdap_activity` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: CdapSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/cdap.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/cdap.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: cdap_simulate +``` diff --git a/v1.3.0/_sources/dev-guide/components/disaggregate_accessibility.md.txt b/v1.3.0/_sources/dev-guide/components/disaggregate_accessibility.md.txt new file mode 100644 index 000000000..7705f4b9c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/disaggregate_accessibility.md.txt @@ -0,0 +1,77 @@ +(component-disaggregate-accessibility)= +# Disaggregate Accessibility + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.disaggregate_accessibility +``` + +The disaggregate accessibility model is an extension of the base accessibility model. +While the base accessibility model is based on a mode-specific decay function and uses fixed market +segments in the population (i.e., income), the disaggregate accessibility model extracts the actual +destination choice logsums by purpose (i.e., mandatory fixed school/work location and non-mandatory +tour destinations by purpose) from the actual model calculations using a user-defined proto-population. +This enables users to include features that may be more critical to destination +choice than just income (e.g., automobile ownership). + +## Structure + +*Inputs* + * disaggregate_accessibility.yaml - Configuration settings for disaggregate accessibility model. + * annotate.csv [optional] - Users can specify additional annotations specific to disaggregate accessibility. For example, annotating the proto-population tables. + +*Outputs* + * final_disaggregate_accessibility.csv [optional] + * final_non_mandatory_tour_destination_accesibility.csv [optional] + * final_workplace_location_accessibility.csv [optional] + * final_school_location_accessibility.csv [optional] + * final_proto_persons.csv [optional] + * final_proto_households.csv [optional] + * final_proto_tours.csv [optional] + +The above tables are created in the model pipeline, but the model will not save +any outputs unless specified in settings.yaml - output_tables. Users can return +the proto population tables for inspection, as well as the raw logsum accessibilities +for mandatory school/work and non-mandatory destinations. The logsums are then merged +at the household level in final_disaggregate_accessibility.csv, which each tour purpose +logsums shown as separate columns. + +*Usage* + +The disaggregate accessibility model is run as a model step in the model list. +There are two necessary steps: + +* `initialize_proto_population` +* `compute_disaggregate_accessibility` + +The reason the steps must be separate is to enable multiprocessing. +The proto-population must be fully generated and initialized before activitysim +slices the tables into separate threads. These steps must also occur before +initialize_households in order to avoid conflict with the shadow_pricing model. + +The model steps can be run either as part the activitysim model run, or setup +to run as a standalone run to pre-computing the accessibility values. +For standalone implementations, the final_disaggregate_accessibility.csv is read +into the pipeline and initialized with the initialize_household model step. + +- *Configuration File*: `disaggregate_accessibility.yaml` +- *Core Table*: Users define the variables to be generated for 'PROTO_HOUSEHOLDS', 'PROTO_PERSONS', and 'PROTO_TOURS' tables. These tables must include all basic fields necessary for running the actual model. Additional fields can be annotated in pre-processing using the annotation settings of this file. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: DisaggregateAccessibilitySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC_Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/disaggregate_accessibility.yaml) +- [Placeholder_SANDAG_2_Zone](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/placeholder_sandag/test/configs_2_zone/disaggregate_accessibility.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: disaggregate_accessibility +``` diff --git a/v1.3.0/_sources/dev-guide/components/free_parking.md.txt b/v1.3.0/_sources/dev-guide/components/free_parking.md.txt new file mode 100644 index 000000000..b1bc9de10 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/free_parking.md.txt @@ -0,0 +1,40 @@ +(component-free-parking)= +# Free Parking Eligibility + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.free_parking +``` + +The Free Parking Eligibility model predicts the availability of free parking at a person's +workplace. It is applied for people who work in zones that have parking charges, which are +generally located in the Central Business Districts. The purpose of the model is to adequately +reflect the cost of driving to work in subsequent models, particularly in mode choice. + +## Structure + +- *Configuration File*: `free_parking.yaml` +- *Core Table*: `persons` +- *Result Field*: `free_parking_at_work` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: FreeParkingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: free_parking +``` diff --git a/v1.3.0/_sources/dev-guide/components/index.rst.txt b/v1.3.0/_sources/dev-guide/components/index.rst.txt new file mode 100644 index 000000000..9329f3b0d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/index.rst.txt @@ -0,0 +1,54 @@ +.. _dev_components : + +========== +Components +========== + +.. toctree:: + :maxdepth: 1 + initialize + initialize_los + initialize_tours + accessibility + auto_ownership + vehicle_type_choice + telecommute_frequency + cdap + mandatory_tour_frequency + school_escorting + joint_tour_composition + joint_tour_participation + joint_tour_destination + joint_tour_scheduling + non_mandatory_tour_frequency + non_mandatory_destination + non_mandatory_scheduling + mandatory_scheduling + disaggregate_accessibility + free_parking + school_location_choice + transit_pass_ownership + transit_pass_subsidy + trip_destination + work_from_home + work_location_choice + tour_mode_choice + atwork_subtour_frequency + atwork_subtour_destination + atwork_subtour_scheduling + atwork_subtour_mode_choice + stop_frequency + trip_purpose + trip_destination + trip_purpose_and_destination + trip_scheduling_choice + trip_departure_choice + trip_mode_choice + parking_location_choice + write_trip_matrices + + +.. note:: + + The documentation for individual components is being migrated to this + section. See :ref:`models` for other components. diff --git a/v1.3.0/_sources/dev-guide/components/initialize.md.txt b/v1.3.0/_sources/dev-guide/components/initialize.md.txt new file mode 100644 index 000000000..90bba4a35 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/initialize.md.txt @@ -0,0 +1,25 @@ +(component-initialize)= +# Initialize + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize +``` + +The initialize model isn't really a model, but rather a few data processing steps in the data pipeline. +The initialize data processing steps code variables used in downstream models, such as household and person +value-of-time. This step also pre-loads the land_use, households, persons, and person_windows tables because +random seeds are set differently for each step and therefore the sampling of households depends on which step +they are initially loaded in. + +The main interface to the initialize land use step is the [initialize_landuse](activitysim.abm.models.initialize.initialize_landuse) +function. The main interface to the initialize household step is the [initialize_households](activitysim.abm.models.initialize.initialize_households) +function. The main interface to the initialize tours step is the [initialize_tours](activitysim.abm.models.initialize_tours.initialize_tours) +function. These functions are registered as Inject steps in the example Pipeline. + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_landuse +.. autofunction:: initialize_households +``` diff --git a/v1.3.0/_sources/dev-guide/components/initialize_los.md.txt b/v1.3.0/_sources/dev-guide/components/initialize_los.md.txt new file mode 100644 index 000000000..98f0363c6 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/initialize_los.md.txt @@ -0,0 +1,25 @@ +(component-initialize-los)= +# Initialize LOS + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize_los +``` + +The initialize LOS model isn't really a model, but rather a series of data processing steps in the data pipeline. +The initialize LOS model does two things: + + * Loads skims and cache for later if desired + * Loads network LOS inputs for transit virtual path building (see [transit_virtual_path_builder](transit_virtual_path_builder), pre-computes tap-to-tap total utilities and cache for later if desired + +The main interface to the initialize LOS step is the [initialize_los](activitysim.abm.models.initialize_los.initialize_los) +function. The main interface to the initialize TVPB step is the [initialize_tvpb](activitysim.abm.models.initialize_los.initialize_tvpb) +function. These functions are registered as Inject steps in the example Pipeline. + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_los +.. autofunction:: compute_utilities_for_attribute_tuple +.. autofunction:: initialize_tvpb +``` diff --git a/v1.3.0/_sources/dev-guide/components/initialize_tours.md.txt b/v1.3.0/_sources/dev-guide/components/initialize_tours.md.txt new file mode 100644 index 000000000..a05ec127f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/initialize_tours.md.txt @@ -0,0 +1,15 @@ +(component-initialize-tours)= +# Initialize Tours + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize_tours +``` + + + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_tours +``` diff --git a/v1.3.0/_sources/dev-guide/components/joint_tour_composition.md.txt b/v1.3.0/_sources/dev-guide/components/joint_tour_composition.md.txt new file mode 100644 index 000000000..980bd38a3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/joint_tour_composition.md.txt @@ -0,0 +1,42 @@ +(component-joint-tour-composition)= +# Joint Tour Composition + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.joint_tour_composition +``` +In the joint tour party composition model, the makeup of the travel party (adults, children, or +mixed - adults and children) is determined for each joint tour. The party composition determines the +general makeup of the party of participants in each joint tour in order to allow the micro-simulation +to faithfully represent the prevalence of adult-only, children-only, and mixed joint travel tours +for each purpose while permitting simplicity in the subsequent person participation model. + +The main interface to the joint tour composition model is the +[joint_tour_composition](activitysim.abm.models.joint_tour_composition.joint_tour_composition) +function. This function is registered as an Inject step in the example Pipeline. + + +## Structure + +- *Configuration File*: `joint_tour_composition.yaml` +- *Core Table*: `tours` +- *Result Field*: `composition` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: JointTourCompositionSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/joint_tour_composition.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: joint_tour_composition +``` diff --git a/v1.3.0/_sources/dev-guide/components/joint_tour_destination.md.txt b/v1.3.0/_sources/dev-guide/components/joint_tour_destination.md.txt new file mode 100644 index 000000000..21700fdd0 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/joint_tour_destination.md.txt @@ -0,0 +1,60 @@ +(component-joint-tour-destination)= +# Joint Tour Destination + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.joint_tour_destination +``` + +The joint tour destination choice model operate similarly to the usual work and +school location choice model, selecting the primary destination for travel tours. The only +procedural difference between the models is that the usual work and school location choice +model selects the usual location of an activity whether or not the activity is undertaken during the +travel day, while the joint tour destination choice model selects the location for an +activity which has already been generated. + +The tour's primary destination is the location of the activity that is assumed to provide the greatest +impetus for engaging in the travel tour. In the household survey, the primary destination was not asked, but +rather inferred from the pattern of stops in a closed loop in the respondents' travel diaries. The +inference was made by weighing multiple criteria including a defined hierarchy of purposes, the +duration of activities, and the distance from the tour origin. The model operates in the reverse +direction, designating the primary purpose and destination and then adding intermediate stops +based on spatial, temporal, and modal characteristics of the inbound and outbound journeys to +the primary destination. + +The joint tour destination choice model is made up of three model steps: + * sample - selects a sample of alternative locations for the next model step. This selects X locations from the full set of model zones using a simple utility. + * logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative location. + * simulate - starts with the table created above and chooses a final location, this time with the mode choice logsum included. + +Joint tour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interface to the model is the [joint_tour_destination](activitysim.abm.models.joint_tour_destination.joint_tour_destination) +function. This function is registered as an Inject step in the example Pipeline. See [writing_logsums](writing_logsums) for how +to write logsums for estimation. + +## Structure + +- *Configuration File*: `joint_tour_destination.yaml` +- *Core Table*: `tours` +- *Result Field*: `destination` +- *Skims Keys*: `TAZ, alt_dest, MD time period` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/joint_tour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_destination.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: joint_tour_destination +``` diff --git a/v1.3.0/_sources/dev-guide/components/joint_tour_participation.md.txt b/v1.3.0/_sources/dev-guide/components/joint_tour_participation.md.txt new file mode 100644 index 000000000..b93d5d33b --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/joint_tour_participation.md.txt @@ -0,0 +1,48 @@ +(component-joint-tour-participation)= +# Joint Tour Participation + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.joint_tour_participation +``` +In the joint tour person participation model, each eligible person sequentially makes a +choice to participate or not participate in each joint tour. Since the party composition model +determines what types of people are eligible to join a given tour, the person participation model +can operate in an iterative fashion, with each household member choosing to join or not to join +a travel party independent of the decisions of other household members. In the event that the +constraints posed by the result of the party composition model are not met, the person +participation model cycles through the household members multiple times until the required +types of people have joined the travel party. + +This step also creates the ``joint_tour_participants`` table in the pipeline, which stores the +person ids for each person on the tour. + +The main interface to the joint tour participation model is the +[joint_tour_participation](activitysim.abm.models.joint_tour_participation.joint_tour_participation) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `joint_tour_participation.yaml` +- *Core Table*: `tours` +- *Result Field*: `number_of_participants, person_id (for the point person)` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: JointTourParticipationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/joint_tour_participation.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_participation.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: joint_tour_participation +.. autofunction:: participants_chooser +``` diff --git a/v1.3.0/_sources/dev-guide/components/joint_tour_scheduling.md.txt b/v1.3.0/_sources/dev-guide/components/joint_tour_scheduling.md.txt new file mode 100644 index 000000000..6a9fa2190 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/joint_tour_scheduling.md.txt @@ -0,0 +1,46 @@ +(component-joint-tour-scheduling)= +# Joint Tour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.joint_tour_scheduling +``` + +The joint tour scheduling model selects a tour departure and duration period (and therefore a start and end +period as well) for each joint tour. This model uses person [time_windows](time_windows). The primary drivers in the +models are accessibility-based parameters such +as the auto travel time for the departure/arrival hour combination, demographics, and time +pattern characteristics such as the time windows available from previously scheduled tours. +The joint tour scheduling model does not use mode choice logsums. + +The main interface to the joint tour purpose scheduling model is the +[joint_tour_scheduling](activitysim.abm.models.joint_tour_scheduling.joint_tour_scheduling) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `joint_tour_scheduling.yaml` +- *Core Table*: `tours` +- *Result Field*: `start, end, duration` +- *Skims Keys*: ` TAZ, destination, MD time period, MD time period` + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourSchedulingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/joint_tour_scheduling.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_scheduling.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: joint_tour_scheduling +``` diff --git a/v1.3.0/_sources/dev-guide/components/mandatory_scheduling.md.txt b/v1.3.0/_sources/dev-guide/components/mandatory_scheduling.md.txt new file mode 100644 index 000000000..7780bc81f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/mandatory_scheduling.md.txt @@ -0,0 +1,52 @@ +(component-mandatory-scheduling)= +# Mandatory Tour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.mandatory_scheduling +``` + +The mandatory tour scheduling model selects a tour departure and duration period (and therefore a +start and end period as well) for each mandatory tour. The primary drivers in the model are +accessibility-based parameters such as the mode choice logsum for the departure/arrival hour +combination, demographics, and time pattern characteristics such as the time windows available +from previously scheduled tours. This model uses person :ref:`time_windows`. + +```{note} +For `prototype_mtc`, the modeled time periods for all submodels are hourly from 3 am to +3 am the next day, and any times before 5 am are shifted to time period 5, and any times +after 11 pm are shifted to time period 23. +``` + +If ``tour_departure_and_duration_segments.csv`` is included in the configs, then the model +will use these representative start and end time periods when calculating mode choice logsums +instead of the specific start and end combinations for each alternative to reduce runtime. This +feature, know as ``representative logsums``, takes advantage of the fact that the mode choice logsum, +say, from 6 am to 2 pm is very similar to the logsum from 6 am to 3 pm, and 6 am to 4 pm, and so using +just 6 am to 3 pm (with the idea that 3 pm is the "representative time period") for these alternatives is +sufficient for tour scheduling. By reusing the 6 am to 3 pm mode choice logsum, ActivitySim saves +significant runtime. + +The main interface to the mandatory tour purpose scheduling model is the +[mandatory_tour_scheduling](activitysim.abm.models.mandatory_scheduling.mandatory_tour_scheduling) +function. This function is registered as an Inject step in the example Pipeline + +## Structure + +- *Configuration File*: `mandatory_tour_scheduling.yaml` +- *Core Table*: `tours` +- *Result Field*: `start`,`end`,`duration` +- *Skim Keys*: `TAZ`,`workplace_taz`,`school_taz`,`start`,`end` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/mandatory_tour_scheduling.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/mandatory_tour_scheduling.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: mandatory_tour_scheduling +``` diff --git a/v1.3.0/_sources/dev-guide/components/mandatory_tour_frequency.md.txt b/v1.3.0/_sources/dev-guide/components/mandatory_tour_frequency.md.txt new file mode 100644 index 000000000..2a5e61706 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/mandatory_tour_frequency.md.txt @@ -0,0 +1,44 @@ +(component-mandatory-tour-frequency)= +# Mandatory Tour Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.mandatory_tour_frequency +``` + +The individual mandatory tour frequency model predicts the number of work and school tours +taken by each person with a mandatory DAP. The primary drivers of mandatory tour frequency +are demographics, accessibility-based parameters such as drive time to work, and household +automobile ownership. It also creates mandatory tours in the data pipeline. + +The main interface to the mandatory tour purpose frequency model is the +[mandatory_tour_frequency](activitysim.abm.models.mandatory_tour_frequency.mandatory_tour_frequency) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `mandatory_tour_frequency.yaml` +- *Core Table*: `persons` +- *Result Field*: `mandatory_tour_frequency` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: MandatoryTourFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/mandatory_tour_frequency.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/mandatory_tour_frequency.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: mandatory_tour_frequency +``` diff --git a/v1.3.0/_sources/dev-guide/components/non_mandatory_destination.md.txt b/v1.3.0/_sources/dev-guide/components/non_mandatory_destination.md.txt new file mode 100644 index 000000000..11ce041fe --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/non_mandatory_destination.md.txt @@ -0,0 +1,43 @@ +(component-non-mandatory-destination)= +# Non-Mandatory Destination Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.non_mandatory_destination +``` + +The non-mandatory tour destination choice model chooses a destination zone for +non-mandatory tours. The three step (sample, logsums, final choice) process also used for +mandatory tour destination choice is used for non-mandatory tour destination choice. + +Non-mandatory tour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interface to the non-mandatory tour destination choice model is the +[non_mandatory_tour_destination](activitysim.abm.models.non_mandatory_destination.non_mandatory_tour_destination) +function. This function is registered as an Inject step in the example Pipeline. See :ref:`writing_logsums` +for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `non_mandatory_tour_destination.yaml` +- *Core Table*: `tours` +- *Result Field*: `destination` +- *Skims Keys*: `TAZ, alt_dest, MD time period, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/non_mandatory_tour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_destination.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: non_mandatory_tour_destination +``` diff --git a/v1.3.0/_sources/dev-guide/components/non_mandatory_scheduling.md.txt b/v1.3.0/_sources/dev-guide/components/non_mandatory_scheduling.md.txt new file mode 100644 index 000000000..3c73bdb78 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/non_mandatory_scheduling.md.txt @@ -0,0 +1,30 @@ +(component-non-mandatory-scheduling)= +# Non-Mandatory Tour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.non_mandatory_scheduling +``` +The non-mandatory tour scheduling model selects a tour departure and duration period (and therefore a start and end +period as well) for each non-mandatory tour. This model uses person [time_windows](time_windows). Includes support +for [representative_logsums](representative_logsums). + +The main interface to the non-mandatory tour purpose scheduling model is the +[non_mandatory_tour_scheduling](activitysim.abm.models.non_mandatory_scheduling.non_mandatory_tour_scheduling) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `non_mandatory_tour_scheduling.yaml` +- *Core Table*: `tours` +- *Result Field*: `start, end, duration` +- *Skims Keys*: `TAZ, destination, MD time period, MD time period` + +### Examples + +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_scheduling.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: non_mandatory_tour_scheduling +``` diff --git a/v1.3.0/_sources/dev-guide/components/non_mandatory_tour_frequency.md.txt b/v1.3.0/_sources/dev-guide/components/non_mandatory_tour_frequency.md.txt new file mode 100644 index 000000000..c4bd957de --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/non_mandatory_tour_frequency.md.txt @@ -0,0 +1,42 @@ +(component-non-mandatory-tour-frequency)= +# Non-Mandatory Tour Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.non_mandatory_tour_frequency +``` + +The non-mandatory tour frequency model selects the number of non-mandatory tours made by each person on the simulation day. +It also adds non-mandatory tours to the tours in the data pipeline. The individual non-mandatory tour frequency model +operates in two stages: + + * A choice is made using a random utility model between combinations of tours containing zero, one, and two or more escort tours, and between zero and one or more tours of each other purpose. + * Up to two additional tours of each purpose are added according to fixed extension probabilities. + +The main interface to the non-mandatory tour purpose frequency model is the +[non_mandatory_tour_frequency](activitysim.abm.models.non_mandatory_tour_frequency.non_mandatory_tour_frequency) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `non_mandatory_tour_frequency.yaml` +- *Core Table*: `persons` +- *Result Field*: `non_mandatory_tour_frequency` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: NonMandatoryTourFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/non_mandatory_tour_frequency.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_frequency.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: non_mandatory_tour_frequency +``` diff --git a/v1.3.0/_sources/dev-guide/components/parking_location_choice.md.txt b/v1.3.0/_sources/dev-guide/components/parking_location_choice.md.txt new file mode 100644 index 000000000..05b6e2a3f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/parking_location_choice.md.txt @@ -0,0 +1,78 @@ +(component-parking-location-choice)= +# Parking Location Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.parking_location_choice +``` + +The parking location choice model selects a parking location for specified trips. While the model does not +require parking location be applied to any specific set of trips, it is usually applied for drive trips to +specific zones (e.g., CBD) in the model. + +The model provides provides a filter for both the eligible choosers and eligible parking location zone. The +trips dataframe is the chooser of this model. The zone selection filter is applied to the land use zones +dataframe. + +If this model is specified in the pipeline, the `Write Trip Matrices`_ step will using the parking location +choice results to build trip tables in lieu of the trip destination. + +The main interface to the trip mode choice model is the +[parking_location_choice](activitysim.abm.models.parking_location_choice.parking_location_choice) function. This function +is registered as an Inject step, and it is available from the pipeline. + +## Structure + +- *Configuration File*: `parking_location_choice.yaml` +- *Core Table*: `trips` +- *Result*: `omx trip matrices` +- *Skims*: `odt_skims: Origin to Destination by Time of Day`, `dot_skims: Destination to Origin by Time of Day`, +`opt_skims: Origin to Parking Zone by Time of Day`, `pdt_skims: Parking Zone to Destination by Time of Day`, +`od_skims: Origin to Destination`, `do_skims: Destination to Origin`, `op_skims: Origin to Parking Zone`, +`pd_skims: Parking Zone to Destination` + +#### Required YAML attributes: + +- `SPECIFICATION`: + This file defines the logit specification for each chooser segment. +- `COEFFICIENTS`: + Specification coefficients +- `PREPROCESSOR`: + Preprocessor definitions to run on the chooser dataframe (trips) before the model is run +- `CHOOSER_FILTER_COLUMN_NAME`: + Boolean field on the chooser table defining which choosers are eligible to parking location choice model. If no + filter is specified, all choosers (trips) are eligible for the model. +- `CHOOSER_SEGMENT_COLUMN_NAME`: + Column on the chooser table defining the parking segment for the logit model +- `SEGMENTS`: + List of eligible chooser segments in the logit specification +- `ALTERNATIVE_FILTER_COLUMN_NAME`: + Boolean field used to filter land use zones as eligible parking location choices. If no filter is specified, + then all land use zones are considered as viable choices. +- `ALT_DEST_COL_NAME`: + The column name to append with the parking location choice results. For choosers (trips) ineligible for this + model, a -1 value will be placed in column. +- `TRIP_ORIGIN`: + Origin field on the chooser trip table +- `TRIP_DESTINATION`: + Destination field on the chooser trip table + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: ParkingLocationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/parking_location_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: parking_location +.. autofunction:: wrap_skims +.. autofunction:: parking_destination_simulate +``` diff --git a/v1.3.0/_sources/dev-guide/components/school_escorting.md.txt b/v1.3.0/_sources/dev-guide/components/school_escorting.md.txt new file mode 100644 index 000000000..f1f162603 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/school_escorting.md.txt @@ -0,0 +1,167 @@ +(component-school-escorting)= +# School Escorting + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.school_escorting +``` +The school escort model determines whether children are dropped-off at or picked-up from school, +simultaneously with the chaperone responsible for chauffeuring the children, +which children are bundled together on half-tours, and the type of tour (pure escort versus rideshare). +The model is run after work and school locations have been chosen for all household members, +and after work and school tours have been generated and scheduled. +The model labels household members of driving age as potential ‘chauffeurs’ and children with school tours as potential ‘escortees’. +The model then attempts to match potential chauffeurs with potential escortees in a choice model whose alternatives +consist of ‘bundles’ of escortees with a chauffeur for each half tour. + +School escorting is a household level decision – each household will choose an alternative from the ``school_escorting_alts.csv`` file, +with the first alternative being no escorting. This file contains the following columns: + +```{eval-rst} ++------------------------------------------------+--------------------------------------------------------------------+ +| Column Name | Column Description | ++================================================+====================================================================+ +| Alt | Alternative number | ++------------------------------------------------+--------------------------------------------------------------------+ +| bundle[1,2,3] | bundle number for child 1,2, and 3 | ++------------------------------------------------+--------------------------------------------------------------------+ +| chauf[1,2,3] | chauffeur number for child 1,2, and 3 | +| | - 0 = child not escorted | +| | - 1 = chauffeur 1 as ride share | +| | - 2 = chauffeur 1 as pure escort | +| | - 3 = chauffeur 2 as ride share | +| | - 4 = chauffeur 3 as pure escort | ++------------------------------------------------+--------------------------------------------------------------------+ +| nbund[1,2] | - number of escorting bundles for chauffeur 1 and 2 | ++------------------------------------------------+--------------------------------------------------------------------+ +| nbundles | - total number of bundles | +| | - equals nbund1 + nbund2 | ++------------------------------------------------+--------------------------------------------------------------------+ +| nrs1 | - number of ride share bundles for chauffeur 1 | ++------------------------------------------------+--------------------------------------------------------------------+ +| npe1 | - number of pure escort bundles for chauffeur 1 | ++------------------------------------------------+--------------------------------------------------------------------+ +| nrs2 | - number of ride share bundles for chauffeur 2 | ++------------------------------------------------+--------------------------------------------------------------------+ +| npe2 | - number of pure escort bundles for chauffeur 2 | ++------------------------------------------------+--------------------------------------------------------------------+ +| Description | - text description of alternative | ++------------------------------------------------+--------------------------------------------------------------------+ +``` + +The model as currently implemented contains three escortees and two chauffeurs. +Escortees are students under age 16 with a mandatory tour whereas chaperones are all persons in the household over the age of 18. +For households that have more than three possible escortees, the three youngest children are selected for the model. +The two chaperones are selected as the adults of the household with the highest weight according to the following calculation: +`Weight = 100*personType + 10*gender + 1*age(0,1)` +Where `personType` is the person type number from 1 to 5, `gender` is 1 for male and 2 for female, and +`age` is a binary indicator equal to 1 if age is over 25 else 0. + +The model is run sequentially three times, once in the outbound direction, once in the inbound direction, +and again in the outbound direction with additional conditions on what happened in the inbound direction. +There are therefore three sets of utility specifications, coefficients, and pre-processor files. +Each of these files is specified in the school_escorting.yaml file along with the number of escortees and number of chaperones. + +There is also a constants section in the school_escorting.yaml file which contain two constants. +One which sets the maximum time bin difference to match school and work tours for ride sharing +and another to set the number of minutes per time bin. +In the [prototype_mtc_extended](prototype_mtc_extended) example, these are set to 1 and 60 respectively. + +After a school escorting alternative is chosen for the inbound and outbound direction, the model will +create the tours and trips associated with the decision. Pure escort tours are created, +and the mandatory tour start and end times are changed to match the school escort bundle start and end times. +(Outbound tours have their start times matched and inbound tours have their end times matched.) +Escortee drop-off / pick-up order is determined by the distance from home to the school locations. +They are ordered from smallest to largest in the outbound direction, and largest to smallest in the inbound direction. +Trips are created for each half-tour that includes school escorting according to the provided order. + +The created pure escort tours are joined to the already created mandatory tour table in the pipeline +and are also saved separately to the pipeline under the table name “school_escort_tours”. +Created school escorting trips are saved to the pipeline under the table name “school_escort_trips”. +By saving these to the pipeline, their data can be queried in downstream models to set correct purposes, +destinations, and schedules to satisfy the school escorting model choice. + +There are a host of downstream model changes that are involved when including the school escorting model. +The following list contains the models that are changed in some way when school escorting is included: + +```{eval-rst} ++--------------------------------------------------------------------+------------------------------------------------------------------+ +| File Name(s) | Change(s) Needed | ++====================================================================+==================================================================+ +| - `non_mandatory_tour_scheduling_annotate_tours_preprocessor.csv` | | +| - `tour_scheduling_nonmandatory.csv` | - Set availability conditions based on those times | +| | - Do not schedule over other school escort tours | ++--------------------------------------------------------------------+------------------------------------------------------------------+ +| - `tour_mode_choice_annotate_choosers_preprocessor.csv` | - count number of escortees on tour by parsing the | +| - `tour_mode_choice.csv` | ``escort_participants`` column | +| | - set mode choice availability based on number of escortees | +| | | ++--------------------------------------------------------------------+------------------------------------------------------------------+ +| - `stop_frequency_school.csv` | Do not allow stops for half-tours that include school escorting | +| - `stop_frequency_work.csv` | | +| - `stop_frequency_univ.csv` | | +| - `stop_frequency_escort.csv` | | ++--------------------------------------------------------------------+------------------------------------------------------------------+ +| - `trip_mode_choice_annotate_trips_preprocessor.csv` | - count number of escortees on trip by parsing the | +| - `trip_mode_choice.csv` | ``escort_participants`` column | +| | - set mode choice availability based on number of escortees | +| | | ++--------------------------------------------------------------------+------------------------------------------------------------------+ +``` + +- *Joint tour scheduling:* Joint tours are not allowed to be scheduled over school escort tours. + This happens automatically by updating the timetable object with the updated mandatory tour times + and created pure escort tour times after the school escorting model is run. + There were no code or config changes in this model, but it is still affected by school escorting. +- *Non-Mandatory tour frequency:* Pure school escort tours are joined to the tours created in the + non-mandatory tour frequency model and tour statistics (such as tour_count and tour_num) are re-calculated. +- *Non-Mandatory tour destination:* Since the primary destination of pure school escort tours is known, + they are removed from the choosers table and have their destination set according to the destination in\ + school_escort_tours table. They are also excluded from the estimation data bundle. +- *Non-Mandatory tour scheduling:* Pure escort tours need to have the non-escorting portion of their tour scheduled. + This is done by inserting availability conditions in the model specification that ensures the alternative + chosen for the start of the tour is equal to the alternative start time for outbound tours and the end time + is equal to the alternative end time for the inbound tours. There are additional terms that ensure the tour + does not overlap with subsequent school escorting tours as well. Beware -- If the availability conditions + in the school escorting model are not set correctly, the tours created may not be consistent with each other + and this model will fail. +- *Tour mode choice:* Availability conditions are set in tour mode choice to prohibit the drive alone mode + if the tour contains an escortee and the shared-ride 2 mode if the tour contains more than one escortee. +- *Stop Frequency:* No stops are allowed on half-tours that include school escorting. + This is enforced by adding availability conditions in the stop frequency model. After the stop frequency + model is run, the school escorting trips are merged from the trips created by the stop frequency model + and a new stop frequency is computed along with updated trip numbers. +- *Trip purpose, destination, and scheduling:* Trip purpose, destination, and departure times are known + for school escorting trips. As such they are removed from their respective chooser tables and the estimation + data bundles, and set according to the values in the school_escort_trips table residing in the pipeline. +- *Trip mode choice:* Like in tour mode choice, availability conditions are set to prohibit trip containing + an escortee to use the drive alone mode or the shared-ride 2 mode for trips with more than one escortee. + +Many of the changes discussed in the above list are handled in the code and the user is not required to make any +changes when implementing the school escorting model. However, it is the users responsibility to include the +changes in the following model configuration files for models downstream of the school escorting model: + + +When not including the school escorting model, all of the escort trips to and from school are counted implicitly in +escort tours determined in the non-mandatory tour frequency model. Thus, when including the school escort model and +accounting for these tours explicitly, extra care should be taken not to double count them in the non-mandatory +tour frequency model. The non-mandatory tour frequency model should be re-evaluated and likely changed to decrease +the number of escort tours generated by that model. This was not implemented in the [prototype_mtc_extended](prototype_mtc_extended) +implementation due to a lack of data surrounding the number of escort tours in the region. + +## Configuration + +```{eval-rst} +.. autopydantic_model:: SchoolEscortSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/school_escorting.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: school_escorting +``` diff --git a/v1.3.0/_sources/dev-guide/components/school_location_choice.md.txt b/v1.3.0/_sources/dev-guide/components/school_location_choice.md.txt new file mode 100644 index 000000000..6238d8e42 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/school_location_choice.md.txt @@ -0,0 +1,53 @@ +(component-location_choice)= +# School Location + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.location_choice.school_location +``` + +The usual school location choice models assign a usual school location for the primary +mandatory activity of each child and university student in the +synthetic population. The models are composed of a set of accessibility-based parameters +(including one-way distance between home and primary destination and the tour mode choice +logsum - the expected maximum utility in the mode choice model which is given by the +logarithm of the sum of exponentials in the denominator of the logit formula) and size terms, +which describe the quantity of grade-school or university opportunities in each possible +destination. + +The school location model is made up of four steps: + * sampling - selects a sample of alternative school locations for the next model step. This selects X locations from the full set of model zones using a simple utility. + * logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative school location. + * simulate - starts with the table created above and chooses a final school location, this time with the mode choice logsum included. + * shadow prices - compare modeled zonal destinations to target zonal size terms and calculate updated shadow prices. + +These steps are repeated until shadow pricing convergence criteria are satisfied or a max number of iterations is reached. See [shadow_pricing](shadow_pricing). + +School location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interfaces to the model is the [school_location](activitysim.abm.models.location_choice.school_location) function. +This function is registered as an Inject step in the example Pipeline. [writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `school_location.yaml` +- *Core Table*: `persons` +- *Result Field*: `school_taz` +- *School Location - Skims Keys*: `TAZ, alt_dest, AM time period, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/school_location.yaml) +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/school_location.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: school_location +``` diff --git a/v1.3.0/_sources/dev-guide/components/shadow_pricing.md.txt b/v1.3.0/_sources/dev-guide/components/shadow_pricing.md.txt new file mode 100644 index 000000000..c618858fe --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/shadow_pricing.md.txt @@ -0,0 +1,83 @@ +(component-shadow-pricing)= +# Shadow Pricing + +```{eval-rst} +.. currentmodule:: activitysim.abm.tables.shadow_pricing +``` + +The shadow pricing calculator used by work and school location choice. + +## Structure +- *Configuration File*: `shadow_pricing.yaml` + +### Turning on and saving shadow prices + +Shadow pricing is activated by setting the `use_shadow_pricing` to True in the settings.yaml file. +Once this setting has been activated, ActivitySim will search for shadow pricing configuration in +the shadow_pricing.yaml file. When shadow pricing is activated, the shadow pricing outputs will be +exported by the tracing engine. As a result, the shadow pricing output files will be prepended with +`trace` followed by the iteration number the results represent. For example, the shadow pricing +outputs for iteration 3 of the school location model will be called +`trace.shadow_price_school_shadow_prices_3.csv`. + +In total, ActivitySim generates three types of output files for each model with shadow pricing: + +- `trace.shadow_price__desired_size.csv` The size terms by zone that the ctramp and daysim + methods are attempting to target. These equal the size term columns in the land use data + multiplied by size term coefficients. + +- `trace.shadow_price__modeled_size_.csv` These are the modeled size terms after + the iteration of shadow pricing identified by the number. In other words, these are + the predicted choices by zone and segment for the model after the iteration completes. (Not + applicable for ``simulation`` option.) + +- `trace.shadow_price__shadow_prices_.csv` The actual shadow price for each zone + and segment after the of shadow pricing. This is the file that can be used to warm + start the shadow pricing mechanism in ActivitySim. (Not applicable for `simulation` option.) + +There are three shadow pricing methods in activitysim: `ctramp`, `daysim`, and `simulation`. +The first two methods try to match model output with workplace/school location model size terms, +while the last method matches model output with actual employment/enrollmment data. + +The simulation approach operates the following steps. First, every worker / student will be +assigned without shadow prices applied. The modeled share and the target share for each zone are +compared. If the zone is overassigned, a sample of people from the over-assigned zones will be +selected for re-simulation. Shadow prices are set to -999 for the next iteration for overassigned +zones which removes the zone from the set of alternatives in the next iteration. The sampled people +will then be forced to choose from one of the under-assigned zones that still have the initial +shadow price of 0. (In this approach, the shadow price variable is really just a switch turning that +zone on or off for selection in the subsequent iterations. For this reason, warm-start functionality +for this approach is not applicable.) This process repeats until the overall convergence criteria +is met or the maximum number of allowed iterations is reached. + +Because the simulation approach only re-simulates workers / students who were over-assigned in the +previous iteration, run time is significantly less (~90%) than the CTRAMP or DaySim approaches which +re-simulate all workers and students at each iteration. + +## Configuration + +```{eval-rst} +.. autopydantic_model:: ShadowPriceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: ShadowPriceCalculator +.. autofunction:: buffers_for_shadow_pricing +.. autofunction:: buffers_for_shadow_pricing_choice +.. autofunction:: shadow_price_data_from_buffers_choice +.. autofunction:: shadow_price_data_from_buffers +.. autofunction:: load_shadow_price_calculator +.. autofunction:: add_size_tables +.. autofunction:: get_shadow_pricing_info +.. autofunction:: get_shadow_pricing_choice_info + +``` diff --git a/v1.3.0/_sources/dev-guide/components/stop_frequency.md.txt b/v1.3.0/_sources/dev-guide/components/stop_frequency.md.txt new file mode 100644 index 000000000..84e3ba25e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/stop_frequency.md.txt @@ -0,0 +1,53 @@ +(component-stop-frequency)= +# Stop Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.stop_frequency +``` + +The stop frequency model assigns to each tour the number of intermediate destinations a person +will travel to on each leg of the tour from the origin to tour primary destination and back. +The model incorporates the ability for more than one stop in each direction, +up to a maximum of 3, for a total of 8 trips per tour (four on each tour leg). + +Intermediate stops are not modeled for drive-transit tours because doing so can have unintended +consequences because of the difficulty of tracking the location of the vehicle. For example, +consider someone who used a park and ride for work and then took transit to an intermediate +shopping stop on the way home. Without knowing the vehicle location, it cannot be determined +if it is reasonable to allow the person to drive home. Even if the tour were constrained to allow +driving only on the first and final trip, the trip home from an intermediate stop may not use the +same park and ride where the car was dropped off on the outbound leg, which is usually as close +as possible to home because of the impracticality of coding drive access links from every park +and ride lot to every zone. + +This model also creates a trips table in the pipeline for later models. + +The main interface to the intermediate stop frequency model is the +[stop_frequency](activitysim.abm.models.stop_frequency.stop_frequency) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `stop_frequency.yaml` +- *Core Table*: `tours` +- *Result Field*: `stop_frequency` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: StopFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/stop_frequency.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/stop_frequency.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: stop_frequency +``` diff --git a/v1.3.0/_sources/dev-guide/components/telecommute_frequency.md.txt b/v1.3.0/_sources/dev-guide/components/telecommute_frequency.md.txt new file mode 100644 index 000000000..971188533 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/telecommute_frequency.md.txt @@ -0,0 +1,44 @@ +(component-telecommute-frequency)= +# Telecommute Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.telecommute_frequency +``` + +Telecommuting is defined as workers who work from home instead of going to work. It only applies to +workers with a regular workplace outside of home. The telecommute model consists of two +submodels - a person [work_from_home](work_from_home) model and this person telecommute frequency model. + +For all workers that work out of the home, the telecommute models predicts the +level of telecommuting. The model alternatives are the frequency of telecommuting in +days per week (0 days, 1 day, 2 to 3 days, 4+ days). + +The main interface to the work from home model is the +[telecommute_frequency](activitysim.abm.models.telecommute_frequency) function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `telecommute_frequency.yaml` +- *Core Table*: `persons` +- *Result Field*: `telecommute_frequency` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TelecommuteFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/telecommute_frequency.yaml) +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/telecommute_frequency.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: telecommute_frequency +``` diff --git a/v1.3.0/_sources/dev-guide/components/tour_mode_choice.md.txt b/v1.3.0/_sources/dev-guide/components/tour_mode_choice.md.txt new file mode 100644 index 000000000..43c95c38c --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/tour_mode_choice.md.txt @@ -0,0 +1,68 @@ +(component-tour-mode-choice)= +# Tour Mode Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.tour_mode_choice +``` + +The mandatory, non-mandatory, and joint tour mode choice model assigns to each tour the "primary" mode that +is used to get from the origin to the primary destination. The tour-based modeling approach requires a reconsideration +of the conventional mode choice structure. Instead of a single mode choice model used in a four-step +structure, there are two different levels where the mode choice decision is modeled: (a) the +tour mode level (upper-level choice); and, (b) the trip mode level (lower-level choice conditional +upon the upper-level choice). + +The mandatory, non-mandatory, and joint tour mode level represents the decisions that apply to the entire tour, and +that will affect the alternatives available for each individual trip or joint trip. These decisions include the choice to use a private +car versus using public transit, walking, or biking; whether carpooling will be considered; and +whether transit will be accessed by car or by foot. Trip-level decisions correspond to details of +the exact mode used for each trip, which may or may not change over the trips in the tour. + +The mandatory, non-mandatory, and joint tour mode choice structure is a nested logit model which separates +similar modes into different nests to more accurately model the cross-elasticities between the alternatives. The +eighteen modes are incorporated into the nesting structure specified in the model settings file. The +first level of nesting represents the use a private car, non-motorized +means, or transit. In the second level of nesting, the auto nest is divided into vehicle occupancy +categories, and transit is divided into walk access and drive access nests. The final level splits +the auto nests into free or pay alternatives and the transit nests into the specific line-haul modes. + +The primary variables are in-vehicle time, other travel times, cost (the influence of which is derived +from the automobile in-vehicle time coefficient and the persons' modeled value of time), +characteristics of the destination zone, demographics, and the household's level of auto +ownership. + +The main interface to the mandatory, non-mandatory, and joint tour mode model is the +[tour_mode_choice_simulate](activitysim.abm.models.tour_mode_choice.tour_mode_choice_simulate) function. This function is +called in the Inject step [tour_mode_choice_simulate](tour_mode_choice_simulate) and is registered as an Inject step in the example Pipeline. +See [writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `tour_mode_choice.yaml` +- *Core Table*: `tours` +- *Result Field*: `mode` +- *Skims Keys*: `TAZ, destination, start, end` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourModeComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: tour_mode_choice_simulate +.. autofunction:: create_logsum_trips +.. autofunction:: append_tour_leg_trip_mode_choice_logsums +.. autofunction:: get_trip_mc_logsums_for_all_modes +.. autofunction:: get_trip_mc_logsums_for_all_modes +``` diff --git a/v1.3.0/_sources/dev-guide/components/transit_pass_ownership.md.txt b/v1.3.0/_sources/dev-guide/components/transit_pass_ownership.md.txt new file mode 100644 index 000000000..845979878 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/transit_pass_ownership.md.txt @@ -0,0 +1,43 @@ +(component-transit-pass-ownership)= +# Transit Pass Ownership +```{eval-rst} +.. currentmodule:: activitysim.abm.models.transit_pass_ownership +``` + +The transit fare discount is defined as persons who purchase or are +provided a transit pass. The transit fare discount consists of two submodels - this +transit pass ownership model and a person [transit_pass_subsidy](transit_pass_subsidy) model. The +result of this model can be used to condition downstream models such as the tour and trip +mode choice models via fare discount adjustments. + +The main interface to the transit pass ownership model is the +[transit_pass_ownership](activitysim.abm.models.transit_pass_ownership) function. This +function is registered as an Inject step in the example Pipeline. + +This model generates only True or False outcomes, and is structured as a binary +logit model. + +## Structure + +- *Configuration File*: `transit_pass_ownership.yaml` +- *Core Table*: `persons` +- *Result Field*: `transit_pass_ownership` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TransitPassOwnershipSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/transit_pass_ownership.yaml) +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/transit_pass_ownership.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: transit_pass_ownership +``` diff --git a/v1.3.0/_sources/dev-guide/components/transit_pass_subsidy.md.txt b/v1.3.0/_sources/dev-guide/components/transit_pass_subsidy.md.txt new file mode 100644 index 000000000..e8e2bf772 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/transit_pass_subsidy.md.txt @@ -0,0 +1,42 @@ +(component-transit-pass-subsidy)= +# Transit Pass Subsidy + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.transit_pass_subsidy +``` + +The transit pass subsidy model is a component of the transit fare discount model, which models persons who purchase or are +provided a transit pass. The transit fare discount consists of two submodels - this +transit pass subsidy model and a person [transit_pass_ownership](transit_pass_ownership) model. The +result of this model can be used to condition downstream models such as the +person [transit_pass_ownership](transit_pass_ownership) model and the tour and trip mode choice models +via fare discount adjustments. + +The main interface to the transit pass subsidy model is the +[transit_pass_subsidy](activitysim.abm.models.transit_pass_subsidy) function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `transit_pass_subsidy.yaml` +- *Core Table*: `persons` +- *Result Field*: `transit_pass_subsidy` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TransitPassSubsidySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/transit_pass_subsidy.yaml) +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/transit_pass_subsidy.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: transit_pass_subsidy +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_departure_choice.md.txt b/v1.3.0/_sources/dev-guide/components/trip_departure_choice.md.txt new file mode 100644 index 000000000..268f3b3fa --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_departure_choice.md.txt @@ -0,0 +1,33 @@ +(component-trip-departure-choice)= +# Trip Departure Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_departure_choice +``` + +Used in conjuction with Trip Scheduling Choice (Logit Choice), this model chooses departure +time periods consistent with the time windows for the appropriate leg of the trip. + +## Structure + +- *Configuration File*: `trip_departure_choice.yaml` +- *Core Table*: `trips` +- *Result Field*: `depart` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripDepartureChoiceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_departure_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: trip_departure_choice +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_destination.md.txt b/v1.3.0/_sources/dev-guide/components/trip_destination.md.txt new file mode 100644 index 000000000..b6be0398d --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_destination.md.txt @@ -0,0 +1,133 @@ +(component-trip-destination)= +# Trip Destination + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_destination +``` + +The trip location choice model predicts the location of trips (or stops) made +along the tour other than the primary destination. Final trips already have a +destination (the primary tour destination for outbound trips, and home for +inbound trips) so no choice is needed in those cases. + +## Structure + +- *Configuration File*: `trip_destination.yaml` +- *Core Table*: `trips` +- *Result Field*: `destination` + +This model is structured as +a multinomial logit model using a zone attraction size variable +and route deviation measure as impedance. The alternatives are sampled +from the full set of zones, subject to availability of a zonal attraction size +term. The sampling mechanism is also based on accessibility between tour origin +and primary destination, and is subject to certain rules based on tour mode. + +All destinations are available for auto tour modes, so long as there is a positive +size term for the zone. Intermediate stops on walk tours must be within X miles of both the tour +origin and primary destination zones. Intermediate stops on bike tours must be within X miles of both +the tour origin and primary destination zones. Intermediate stops on walk-transit tours must either be +within X miles walking distance of both the tour origin and primary destination, or have transit access to +both the tour origin and primary destination. Additionally, only short and long walk zones are +available destinations on walk-transit tours. + +The intermediate stop location choice model works by cycling through stops on tours. The level-of-service +variables (including mode choice logsums) are calculated as the additional utility between the +last location and the next known location on the tour. For example, the LOS variable for the first stop +on the outbound direction of the tour is based on additional impedance between the tour origin and the +tour primary destination. The LOS variable for the next outbound stop is based on the additional +impedance between the previous stop and the tour primary destination. Stops on return tour legs work +similarly, except that the location of the first stop is a function of the additional impedance between the +tour primary destination and the tour origin. The next stop location is based on the additional +impedance between the first stop on the return leg and the tour origin, and so on. + +Trip location choice for [two- and three-zone](multiple_zone_systems) models +uses [presampling](presampling) by default. + +The main interface to the trip destination choice model is the +[trip_destination](activitysim.abm.models.trip_destination.trip_destination) function. +This function is registered as an Inject step in the example Pipeline. +See [writing_logsums](writing_logsums) for how to write logsums for estimation. + +```{note} +Trip purpose and trip destination choice can be run iteratively together via +[trip_purpose_and_destination](trip_purpose_and_destination_model). +``` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripDestinationSettings +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_destination.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: trip_destination +``` + +## Context Variables + +The following variables are made available for use in this component's utility +specifications: + +- `network_los` ([Network_LOS](activitysim.core.los.Network_LOS)): A reference + to the main network_los object for this model. +- `size_terms` ([DataFrameMatrix](activitysim.core.skim_dictionary.DataFrameMatrix)): + This DataFrameMatrix offers a specialized two-dimension lookup wrapper + on an array, to access the size terms by alternative zone and trip + purpose by label simultaneously. When sharrow is enabled for this model, + this value also embeds a special linked array accessible as + `size_terms['sizearray']`, which automatically compiles to point to the + alternative destination zone and the 'purpose_index_num' (an integer + offset value instead of a label, which should be set in a preprocessor). +- `size_terms_array` (numpy.ndarray): A numpy array of size term values, + with rows for zones and columns for trip purposes. This is just the + raw data underneath the `size_terms` value above. +- `timeframe` (str): Contains the constant value "trip". +- `odt_skims` ([Skim3dWrapper](activitysim.core.skim_dictionary.Skim3dWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims + giving the LOS characteristics from the fixed trip origin to each + alternative destination, by time period. +- `dot_skims` ([Skim3dWrapper](activitysim.core.skim_dictionary.Skim3dWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims giving the LOS + characteristics from each alternative destination backwards to the + fixed trip origin, by time period. +- `dpt_skims` ([Skim3dWrapper](activitysim.core.skim_dictionary.Skim3dWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims giving the LOS + characteristics from each alternative destination to the tour final + destination, by time period. +- `pdt_skims` ([Skim3dWrapper](activitysim.core.skim_dictionary.Skim3dWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims giving the LOS + characteristics backwards to each alternative destination from the tour + final destination, by time period. +- `od_skims` ([SkimWrapper](activitysim.core.skim_dictionary.SkimWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims giving the LOS + characteristics from the fixed trip origin to each alternative + destination. +- `dpt_skims` ([SkimWrapper](activitysim.core.skim_dictionary.SkimWrapper) + or [DatasetWrapper](activitysim.core.skim_dataset.DatasetWrapper)): Skims giving the LOS + characteristics from each alternative destination to the tour final + destination. + +The following TransitVirtualPathLogsumWrapper values are also available, +only for 3-zone models: + +- `tvpb_logsum_odt` +- `tvpb_logsum_dot` +- `tvpb_logsum_dpt` +- `tvpb_logsum_pdt` + +## Additional Related Functions + +```{eval-rst} +.. autofunction:: trip_destination_sample +.. autofunction:: compute_logsums +.. autofunction:: compute_ood_logsums +.. autofunction:: trip_destination_simulate +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_mode_choice.md.txt b/v1.3.0/_sources/dev-guide/components/trip_mode_choice.md.txt new file mode 100644 index 000000000..331f09f37 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_mode_choice.md.txt @@ -0,0 +1,49 @@ +(component-trip-mode-choice)= +# Trip Mode Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_mode_choice +``` + +The trip mode choice model assigns a travel mode for each trip on a given tour. It +operates similarly to the tour mode choice model, but only certain trip modes are available for +each tour mode. The correspondence rules are defined according to the following principles: + + * Pay trip modes are only available for pay tour modes (for example, drive-alone pay is only available at the trip mode level if drive-alone pay is selected as a tour mode). + * The auto occupancy of the tour mode is determined by the maximum occupancy across all auto trips that make up the tour. Therefore, the auto occupancy for the tour mode is the maximum auto occupancy for any trip on the tour. + * Transit tours can include auto shared-ride trips for particular legs. Therefore, 'casual carpool', wherein travelers share a ride to work and take transit back to the tour origin, is explicitly allowed in the tour/trip mode choice model structure. + * The walk mode is allowed for any trip. + * The availability of transit line-haul submodes on transit tours depends on the skimming and tour mode choice hierarchy. Free shared-ride modes are also available in walk-transit tours, albeit with a low probability. Paid shared-ride modes are not allowed on transit tours because no stated preference data is available on the sensitivity of transit riders to automobile value tolls, and no observed data is available to verify the number of people shifting into paid shared-ride trips on transit tours. + +The trip mode choice models explanatory variables include household and person variables, level-of-service +between the trip origin and destination according to the time period for the tour leg, urban form +variables, and alternative-specific constants segmented by tour mode. + +The main interface to the trip mode choice model is the +[trip_mode_choice](activitysim.abm.models.trip_mode_choice.trip_mode_choice) function. This function +is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `trip_mode_choice.yaml` +- *Result Field*: `trip_mode` +- *Skim Keys*: `origin, destination, trip_period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripModeChoiceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_mode_choice.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_mode_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: trip_mode_choice +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_purpose.md.txt b/v1.3.0/_sources/dev-guide/components/trip_purpose.md.txt new file mode 100644 index 000000000..671db4091 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_purpose.md.txt @@ -0,0 +1,46 @@ +(component-trip-purpose)= +# Trip Purpose + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_purpose +``` + +For trip other than the last trip outbound or inbound, assign a purpose based on an +observed frequency distribution. The distribution is segmented by tour purpose, tour +direction and person type. Work tours are also segmented by departure or arrival time period. + +The main interface to the trip purpose model is the +[trip_purpose](activitysim.abm.models.trip_purpose.trip_purpose) +function. This function is registered as an Inject step in the example Pipeline. + + +## Structure + + +- *Core Table*: `trips` +- *Result Field*: `purpose` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Note +Trip purpose and trip destination choice can be run iteratively together [trip_purpose_and_destination_model](activitysim.abm.models.trip_purpose_and_destination.py) + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_purpose.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_purpose.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: trip_purpose +.. autofunction:: choose_intermediate_trip_purpose +.. autofunction:: run_trip_purpose +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_purpose_and_destination.md.txt b/v1.3.0/_sources/dev-guide/components/trip_purpose_and_destination.md.txt new file mode 100644 index 000000000..8d074fa08 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_purpose_and_destination.md.txt @@ -0,0 +1,40 @@ +(component-trip-purpose-and-destination)= +# Trip Purpose and Destination + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_purpose_and_destination +``` + +After running trip purpose and trip destination separately, the two model can be ran together in an iterative fashion on +the remaining failed trips (i.e. trips that cannot be assigned a destination). Each iteration uses new random numbers. + +The main interface to the trip purpose model is the +[trip_purpose_and_destination](activitysim.abm.models.trip_purpose_and_destination.trip_purpose_and_destination) +function. This function is registered as an Inject step in the example Pipeline. + + +## Structure + +- *Core Table*: `trips` +- *Result Field*: `purpose, destination` +- *Skims Keys*: `origin, (tour primary) destination, dest_taz, trip_period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripPurposeAndDestinationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_purpose_and_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_purpose_and_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: trip_purpose_and_destination +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_scheduling_choice.md.txt b/v1.3.0/_sources/dev-guide/components/trip_scheduling_choice.md.txt new file mode 100644 index 000000000..186078e8f --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_scheduling_choice.md.txt @@ -0,0 +1,43 @@ +(component-trip-scheduling-choice)= +# Trip Scheduling Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_scheduling_choice +``` + +This model uses a logit-based formulation to determine potential trip windows for the three +main components of a tour. + +- Outbound Leg: The time from leaving the origin location to the time second to last outbound stop. +- Main Leg: The time window from the last outbound stop through the main tour destination to the first inbound stop. +- Inbound Leg: The time window from the first inbound stop to the tour origin location. + +## Structure + +- *Configuration File*: `trip_scheduling_choice.yaml` +- *Core Table*: `tours` +- *Result Field*: `outbound_duration`, `main_leg_duration`, `inbound_duration` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripSchedulingChoiceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_scheduling_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: trip_scheduling_choice +.. autofunction:: generate_schedule_alternatives +.. autofunction:: no_stops_patterns +.. autofunction:: stop_one_way_only_patterns +.. autofunction:: stop_two_way_only_patterns +.. autofunction:: get_pattern_index_and_arrays +.. autofunction:: get_spec_for_segment +``` diff --git a/v1.3.0/_sources/dev-guide/components/trip_scheduling_probabilistic.md.txt b/v1.3.0/_sources/dev-guide/components/trip_scheduling_probabilistic.md.txt new file mode 100644 index 000000000..a92fea627 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/trip_scheduling_probabilistic.md.txt @@ -0,0 +1,93 @@ +(component-trip-scheduling-probabilistic)= +# Trip Scheduling (Probabilistic) + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_scheduling +``` + +For each trip, assign a departure hour based on an input lookup table of percents by tour purpose, +direction (inbound/outbound), tour hour, and trip index. + + * The tour hour is the tour start hour for outbound trips and the tour end hour for inbound trips. The trip index is the trip sequence on the tour, with up to four trips per half tour + * For outbound trips, the trip depart hour must be greater than or equal to the previously selected trip depart hour + * For inbound trips, trips are handled in reverse order from the next-to-last trip in the leg back to the first. The tour end hour serves as the anchor time point from which to start assigning trip time periods. + * Outbound trips on at-work subtours are assigned the tour depart hour and inbound trips on at-work subtours are assigned the tour end hour. + +The assignment of trip depart time is run iteratively up to a max number of iterations since it is possible that +the time period selected for an earlier trip in a half-tour makes selection of a later trip time +period impossible (or very low probability). Thus, the sampling is re-run until a feasible set of trip time +periods is found. If a trip can't be scheduled after the max iterations, then the trip is assigned +the previous trip's choice (i.e. assumed to happen right after the previous trip) or dropped, as configured by the user. +The trip scheduling model does not use mode choice logsums. + +Alternatives: Available time periods in the tour window (i.e. tour start and end period). When processing stops on +work tours, the available time periods is constrained by the at-work subtour start and end period as well. + +In order to avoid trip failing, a new probabilistic trip scheduling mode was developed named "relative". +When setting the _scheduling_mode_ option to relative, trips are scheduled relative to the previously scheduled trips. +The first trip still departs when the tour starts and for every subsequent trip, the choices are selected with respect to +the previous trip depart time. Inbound trips are no longer handled in reverse order. The key to this relative mode is to +index the probabilities based on how much time is remaining on the tour. For tours that include subtours, the time remaining will +be based on the subtour start time for outbound trips and will resume again for inbound trips after the subtour ends. +By indexing the probabilities based on time remaining and scheduling relative to the previous trip, scheduling trips in relative +mode will not fail. Note also that relative scheduling mode requires the use of logic +version 2 (see warning about logic versions, below). + +An example of trip scheduling in relative mode is included in the [prototype_mwcog](prototype_mwcog) example. In this example, trip +scheduling probabilities are indexed by the following columns: + + * periods_left_min: the minimum bin for the number of time periods left on the tour. + * periods_left_max: the maximum bin for the number of time periods left on the tour. This is the same as periods_left_min until the final time period bin. + * outbound: whether the trip occurs on the outbound leg of a tour. + * tour_purpose_grouped: Tour purpose grouped into mandatory and non-mandatory categories + * half_tour_stops_remaining_grouped: The number of stops remaining on the half tour with the categories of 0 and 1+ + +Each of these variables are listed as merge columns in the trip_scheduling.yaml file and are declared in the trip scheduling preprocessor. +The variables above attempt to balance the statistics available for probability creation with the amount of segmentation of trip characteristics. + +.. warning:: + + Earlier versions of ActivitySim contained a logic error in this model, whereby + the earliest departure time for inbound legs was bounded by the maximum outbound + departure time, even if there was a scheduling failure for one or more outbound + leg departures and that bound was NA. For continuity, this process has been + retained in this ActivitySim component as *logic_version* 1, and it remains the + default process if the user does not explicitly specify a logic version in the + model settings yaml file. The revised logic includes bounding inbound legs only + when the maximum outbound departure time is well defined. This version of the + model can be used by explicitly setting `logic_version: 2` (or greater) in the + model settings yaml file. It is strongly recommended that all new model + development efforts use logic version 2; a future version of ActivitySim may + make this the default for this component, and/or remove logic version 1 entirely. + +The main interface to the trip scheduling model is the +[trip_scheduling](activitysim.abm.models.trip_scheduling.trip_scheduling) function. +This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `trip_scheduling.yaml` +- *Core Table*: `trips` +- *Result Field*: `depart` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripSchedulingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/camsys/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_scheduling.yaml) +- [Prototype SEMCOG](https://github.com/camsys/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/trip_scheduling.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: trip_scheduling +.. autofunction:: set_stop_num +.. autofunction:: update_tour_earliest +.. autofunction:: schedule_trips_in_leg +``` diff --git a/v1.3.0/_sources/dev-guide/components/vehicle_allocation.md.txt b/v1.3.0/_sources/dev-guide/components/vehicle_allocation.md.txt new file mode 100644 index 000000000..68d6de034 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/vehicle_allocation.md.txt @@ -0,0 +1,49 @@ +(component-vehicle_allocation)= +# Vehicle Allocation + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.vehicle_allocation +``` + +The vehicle allocation model selects which vehicle would be used for a tour of given occupancy. The alternatives for the vehicle +allocation model consist of the vehicles owned by the household and an additional non household vehicle option. (Zero-auto +households would be assigned the non-household vehicle option since there are no owned vehicles in the household). +A vehicle is selected for each occupancy level set by the user such that different tour modes that have different occupancies could see different operating +characteristics. The output of the vehicle allocation model is appended to the tour table with column names [vehicle_occup_{occupancy}](vehicle_occup_{occupancy}) and the values are +the vehicle type selected. + +In [prototype_mtc_extended](prototype_mtc_extended), three occupancy levels are used: 1, 2, and 3.5. The auto operating cost +for occupancy level 1 is used in the drive alone mode and drive to transit modes. Occupancy levels 2 and 3.5 are used for shared +ride 2 and shared ride 3+ auto operating costs, respectively. Auto operating costs are selected in the mode choice pre-processors by selecting the allocated +vehicle type data from the vehicles table. If the allocated vehicle type was the non-household vehicle, the auto operating costs uses +the previous default value from [prototype_mtc](prototype_mtc). All trips and atwork subtours use the auto operating cost of the parent tour. Functionality +was added in tour and atwork subtour mode choice to annotate the tour table and create a ``selected_vehicle`` which denotes the actual vehicle used. +If the tour mode does not include a vehicle, then the ``selected_vehicle`` entry is left blank. + +The current implementation does not account for possible use of the household vehicles by other household members. Thus, it is possible for a +selected vehicle to be used in two separate tours at the same time. + +## Structure + +- *Configuration File*: `vehicle_allocation.yaml` +- *Result Field*: `vehicle_occup_{occupancy}` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: VehicleAllocationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/vehicle_type_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: vehicle_allocation +.. autofunction:: annotate_vehicle_allocation +.. autofunction:: get_skim_dict +``` diff --git a/v1.3.0/_sources/dev-guide/components/vehicle_type_choice.md.txt b/v1.3.0/_sources/dev-guide/components/vehicle_type_choice.md.txt new file mode 100644 index 000000000..bdf8d65c7 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/vehicle_type_choice.md.txt @@ -0,0 +1,70 @@ +(component-vehicle-type-choice)= +# Vehicle Type Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.vehicle_type_choice +``` + +The vehicle type choice model selects a vehicle type for each household vehicle. A vehicle type +is a combination of the vehicle's body type, age, and fuel type. For example, a 13 year old +gas powered van would have a vehicle type of *van_13_gas*. + +There are two vehicle type choice model structures implemented: + +1. Simultaneous choice of body type, age, and fuel type. +2. Simultaneous choice of body type and age, with fuel type assigned from a probability distribution. + +## Structure + +- *Configuration File*: `vehicle_type_choice.yaml` + +Input vehicle type data included in [prototype_mtc_extended](prototype_mtc_extended) came from a variety of sources. The number of vehicle makes, models, MPG, and +electric vehicle range was sourced from the Enivornmental Protection Agency (EPA). Additional data on vehicle costs were derived from the +National Household Travel Survey. Auto operating costs in the vehicle type data file were a sum of fuel costs and maintenance costs. +Fuel costs were calculated from MPG assuming a $3.00 cost for a gallon of gas. When MPG was not available to calculate fuel costs, +the closest year, vehicle type, or body type available was used. Maintenance costs were taken from AAA's +[2017 driving cost study](https://exchange.aaa.com/wp-content/uploads/2017/08/17-0013_Your-Driving-Costs-Brochure-2017-FNL-CX-1.pdf). +Size categories within body types were averaged, e.g. car was an average of AAA's small, medium, and large sedan categories. +Motorcycles were assigned the small sedan maintenance costs since they were not included in AAA's report. +Maintenance costs were not varied by vehicle year. (According to +`data from the U.S. [Bureau of Labor Statistics](https://www.bls.gov/opub/btn/volume-3/pdf/americans-aging-autos.pdf), +there was no consistent relationship between vehicle age and maintenance costs.) + +Using the above methodology, the average auto operating costs of vehicles output from :ref:`prototype_mtc_extended` was 18.4 cents. +This value is very close to the auto operating cost of 18.3 cents used in [prototype_mtc](prototype_mtc). +Non-household vehicles in prototype_mtc_extended use the auto operating cost of 18.3 cents used in prototype_mtc. +Users are encouraged to make their own assumptions and calculate auto operating costs as they see fit. + +The distribution of fuel type probabilities included in [prototype_mtc_extended](prototype_mtc_extended) are computed directly from the National Household Travel Survey data +and include the entire US. Therefore, there is "lumpiness" in probabilities due to poor statistics in the data for some vehicle types. +The user is encouraged to adjust the probabilities to their modeling region and "smooth" them for more consistent results. + +Further discussion of output results and model sensitivities can be found [here](https://github.com/ActivitySim/activitysim/wiki/Project-Meeting-2022.05.05). + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: VehicleTypeChoiceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/vehicle_type_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: vehicle_type_choice +.. autofunction:: append_probabilistic_vehtype_type_choices +.. autofunction:: annotate_vehicle_type_choice_households +.. autofunction:: annotate_vehicle_type_choice_persons +.. autofunction:: annotate_vehicle_type_choice_vehicles +.. autofunction:: get_combinatorial_vehicle_alternatives +.. autofunction:: construct_model_alternatives +.. autofunction:: get_vehicle_type_data +.. autofunction:: iterate_vehicle_type_choice +``` diff --git a/v1.3.0/_sources/dev-guide/components/work_from_home.md.txt b/v1.3.0/_sources/dev-guide/components/work_from_home.md.txt new file mode 100644 index 000000000..d5faf9cc3 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/work_from_home.md.txt @@ -0,0 +1,51 @@ +(component-work_from_home)= +# Work from Home + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.work_from_home +``` + +Telecommuting is defined as workers who work from home instead of going +to work. It only applies to workers with a regular workplace outside of home. +The telecommute model consists of two submodels - this work from home model and a +person [telecommute_frequency](telecommute_frequency) model. This model predicts for all workers whether they +usually work from home. + +The work from home model includes the ability to adjust a work from home alternative +constant to attempt to realize a work from home percent for what-if type analysis. +This iterative single process procedure takes as input a number of iterations, a filter on +the choosers to use for the calculation, a target work from home percent, a tolerance percent +for convergence, and the name of the coefficient to adjust. An example setup is provided and +the coefficient adjustment at each iteration is: +``new_coefficient = log( target_percent / current_percent ) + current_coefficient``. + +The main interface to the work from home model is the +[work_from_home](activitysim.abm.models.work_from_home) function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `work_from_home.yaml` +- *Core Table*: `persons` +- *Result Table*: `work_from_home` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: WorkFromHomeSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/work_from_home.yaml) +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/work_from_home.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: work_from_home +``` diff --git a/v1.3.0/_sources/dev-guide/components/work_location_choice.md.txt b/v1.3.0/_sources/dev-guide/components/work_location_choice.md.txt new file mode 100644 index 000000000..5a484cd30 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/work_location_choice.md.txt @@ -0,0 +1,52 @@ +(component-location_choice)= +# Work Location + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.location_choice.workplace_location +``` + +The usual work location choice models assign a usual work location for the primary +mandatory activity of each employed person in the +synthetic population. The models are composed of a set of accessibility-based parameters +(including one-way distance between home and primary destination and the tour mode choice +logsum - the expected maximum utility in the mode choice model which is given by the +logarithm of the sum of exponentials in the denominator of the logit formula) and size terms, +which describe the quantity of work opportunities in each possible destination. + +The work location model is made up of four steps: + * sample - selects a sample of alternative work locations for the next model step. This selects X locations from the full set of model zones using a simple utility. + * logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative work location. + * simulate - starts with the table created above and chooses a final work location, this time with the mode choice logsum included. + * shadow prices - compare modeled zonal destinations to target zonal size terms and calculate updated shadow prices. + +These steps are repeated until shadow pricing convergence criteria are satisfied or a max number of iterations is reached. See [shadow_pricing](shadow_pricing). + +Work location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interfaces to the model is the [workplace_location](activitysim.abm.models.location_choice.workplace_location) function. +This function is registered as an Inject step in the example Pipeline. See [writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `workplace_location.yaml` +- *Core Table*: `persons` +- *Result Field*: `workplace_taz` +- *School Location - Skims Keys*: `TAZ, alt_dest, AM time period, PM time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/workplace_location.yaml) +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/workplace_location.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: workplace_location +``` diff --git a/v1.3.0/_sources/dev-guide/components/write_trip_matrices.md.txt b/v1.3.0/_sources/dev-guide/components/write_trip_matrices.md.txt new file mode 100644 index 000000000..c5349c707 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/components/write_trip_matrices.md.txt @@ -0,0 +1,42 @@ +(component-write-trip-matrices)= +# Write Trip Matrices + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_matrices +``` + +Write open matrix (OMX) trip matrices for assignment. Reads the trips table post preprocessor and run expressions +to code additional data fields, with one data fields for each matrix specified. The matrices are scaled by a +household level expansion factor, which is the household sample rate by default, which is calculated when +households are read in at the beginning of a model run. The main interface to write trip +matrices is the [write_trip_matrices](activitysim.abm.models.trip_matrices.write_trip_matrices) function. +This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Core Table*: `trips` +- *Result*: `omx trip matrices` +- *Skims Keys*: `origin, destination` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: WriteTripMatricesSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/write_trip_matrices.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/write_trip_matrices.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: write_trip_matrices +``` diff --git a/v1.3.0/_sources/dev-guide/core-workflow-api.md.txt b/v1.3.0/_sources/dev-guide/core-workflow-api.md.txt new file mode 100644 index 000000000..71cb339c1 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/core-workflow-api.md.txt @@ -0,0 +1,290 @@ +# State API + +```{eval-rst} +.. currentmodule:: activitysim.core.workflow + +.. autosummary:: + :toctree: _generated + :recursive: + + State +``` + +## Constructors + +```{eval-rst} +.. autosummary:: + :toctree: _generated + :recursive: + + State.__init__ + State.make_default + State.make_temp + create_example +``` + +## Model Setup + +```{eval-rst} +.. autosummary:: + + State.init_state + State.import_extensions + State.initialize_filesystem + State.default_settings + State.load_settings + State.settings + State.filesystem + State.network_settings +``` + + + +## Basic Context Management + +The most basic function of the `State` object is to serve as a defined +namespace for storing model-relevant variables. This includes the top-level +model settings, data tables, skims, and any other Python variables +that represent the current state of a particular modeling system (or when +multiprocessing, sub-system). Below are the basic methods to get and set values +in this context in their "raw" form, with minimal additional processing. + +```{eval-rst} +.. autosummary:: + + State.get + State.set + State.drop + State.access + State.get_injectable + State.add_injectable +``` + + +## Data Access and Manipulation + +In addition to "raw" access to context variable, several methods are provided +to simplify different kinds access to the "tables" that represent the +simulation inputs and outputs of ActivitySim. We say "tables" here in the +abstract sense -- historically these tables have been stored internally by +ORCA as `pandas.DataFrame`s, but the exact internal storage format is abstracted +away here in favor of providing access to the data in several specific formats. + +```{eval-rst} + +.. rubric:: Methods + +.. autosummary:: + + State.get_dataset + State.get_dataframe + State.get_dataarray + State.get_dataframe_index_name + State.get_pyarrow + State.add_table + State.is_table + State.registered_tables + State.get_table + +.. rubric:: Accessor + +.. autosummary:: + :toctree: _generated2 + :template: autosummary/accessor.rst + + State.dataset +``` + + +## Run + +Executing model components is handled by methods in the `run` accessor. + +```{eval-rst} + +.. rubric:: Accessor + +.. autosummary:: + :toctree: _generated2 + :template: autosummary/accessor_callable.rst + + State.run + + + +.. rubric:: Attributes + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_attribute.rst + + State.run.heading_level + + + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.run.by_name + State.run.all +``` + +(state-checkpoint)= +## Checkpoints + +The `State` object provides access to [checkpointing](checkpointing.md) functions +within the `checkpoint` accessor. + +```{eval-rst} + +.. rubric:: Accessor + +.. autosummary:: + :toctree: _generated2 + :template: autosummary/accessor.rst + + State.checkpoint + + +.. rubric:: Attributes + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_attribute.rst + + State.checkpoint.last_checkpoint + State.checkpoint.checkpoints + State.checkpoint.store + + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.checkpoint.store_is_open + State.checkpoint.open_store + State.checkpoint.close_store + State.checkpoint.add + State.checkpoint.list_tables + State.checkpoint.load + State.checkpoint.get_inventory + State.checkpoint.restore + State.checkpoint.restore_from + State.checkpoint.check_against + State.checkpoint.cleanup + State.checkpoint.load_dataframe + State.checkpoint.last_checkpoint_name + State.checkpoint.is_readonly + State.checkpoint.default_pipeline_file_path + +``` + + +## Tracing + +```{eval-rst} + +.. rubric:: Attributes + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_attribute.rst + + State.tracing.traceable_tables + State.tracing.traceable_table_ids + State.tracing.traceable_table_indexes + State.tracing.run_id + State.tracing.validation_directory + + + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.tracing.initialize + State.tracing.register_traceable_table + State.tracing.deregister_traceable_table + State.tracing.write_csv + State.tracing.trace_df + State.tracing.trace_interaction_eval_results + State.tracing.get_trace_target + State.tracing.trace_targets + State.tracing.has_trace_targets + State.tracing.dump_df + State.tracing.delete_output_files + State.tracing.delete_trace_files +``` + + +## Logging + +```{eval-rst} + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.logging.config_logger + State.logging.rotate_log_directory +``` + + +## Reporting + +```{eval-rst} + +.. rubric:: Accessor + +.. autosummary:: + :toctree: _generated2 + :template: autosummary/accessor.rst + + State.report + + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.report.nominal_distribution + State.report.ordinal_distribution + State.report.histogram +``` + + +## Extending + +Methods to extend ActivitySim's functionality are available under the `extend` +accessor. + +```{eval-rst} + +.. rubric:: Accessor + +.. autosummary:: + :toctree: _generated2 + :template: autosummary/accessor.rst + + State.extend + + +.. rubric:: Methods + +.. autosummary:: + :toctree: _generated + :template: autosummary/accessor_method.rst + + State.extend.declare_table +``` diff --git a/v1.3.0/_sources/dev-guide/core-workflow-steps.md.txt b/v1.3.0/_sources/dev-guide/core-workflow-steps.md.txt new file mode 100644 index 000000000..c3d12541e --- /dev/null +++ b/v1.3.0/_sources/dev-guide/core-workflow-steps.md.txt @@ -0,0 +1,76 @@ +(workflow-steps)= +# Workflow Steps + +An ActivitySim component is written as a Python function with a `@workflow.step` +decorator: + +```python +import pandas as pd +from activitysim.core import workflow + +@workflow.step +def component_name( + state: workflow.State, + named_temp_table: pd.DataFrame, + named_table: pd.DataFrame, + cached_object: bool = False, +) -> None: + ... # do something +``` + +Similar to a typical Python class method, the first argument to a +workflow step must be a reference to a [`State`](core-workflow-api.md) +object named `state`. Unlike a typical Python class method, this is +rigorously enforced -- if you decorate a function as a `workflow.step` +and the first argument is not named `state` a `TypeError` will be raised. + +Similar to the legacy ORCA-based implementation of ActivitySim, when called +by the automated processes that orchestrate component execution, the names +of all subsequent arguments should generally match objects that are expected +to be already stored as keys in the `state` context, or have decorated +constructors declared elsewhere in the imported codebase. However, if an +argument is provided with a default value, then the default value is used +unless it is explicitly overloaded in the function call; i.e. the default +value in the function signature takes precedence over any value stored in the +state's context. + +Unlike typical Python functions, the type annotations for the decorated +function's arguments are *not* totally ignored, at least when the function is +called via the [`State.run`](activitysim.core.workflow.State.run) mechanisms. +When asking for a data table to be provided, the type annotation is respected +if it is `pandas.DataFrame` or `xarray.Dataset`; the caller will receive the +table in the indicated format. + +The decorator will spin off a reference of the decorated function in the +`_RUNNABLE_STEPS` class attribute for `State`, facilitating the automatic +discovery and/or execution of this function via the +[`State.run`](activitysim.core.workflow.State.run) mechanisms. +The original function also remains available to import and use without +changes. + +The decorated function may mutate the `state` argument by adding or removing +things from the state's context. Most existing workflow steps operate in this +manner. The return type annotation can be given as "None" to flag that +this mutation behavior is indeed baked in to the decorated function -- indeed, +by implication it must be as there is no other pathway to output a result, +although that is not otherwise checked. + +Alternatively, the wrapped function can return a `Mapping[str, Any]` that +will be used to update the state's context. This happens automatically when +the step is called via the `State.run` accessor, or can (must) be handled +separately by the caller if the function is executed directly. (Future work +may migrate ActivitySim to favor or require this "pure" function behavior.) + + +## API + +```{eval-rst} +.. currentmodule:: activitysim.core.workflow + +.. autosummary:: + :toctree: _generated + :template: autosummary/class_decorator.rst + :recursive: + + step +``` diff --git a/v1.3.0/_sources/dev-guide/core-workflow-table.md.txt b/v1.3.0/_sources/dev-guide/core-workflow-table.md.txt new file mode 100644 index 000000000..16ce5b788 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/core-workflow-table.md.txt @@ -0,0 +1,117 @@ +# Workflow Tables + +## Standard Tables + +An ActivitySim table definition is written as a Python function with a +`workflow.table` decorator: + +```python +import pandas as pd +from activitysim.core import workflow + +@workflow.table +def households(state: workflow.State) -> pd.DataFrame: + df = pd.DataFrame(...) + # do something to set up table here + return df +``` + +Similar to a typical Python class method, the first argument to a workflow table +function is always a reference to a [`State`](core-workflow-api.md) +object named `state`. Unlike a typical Python class method, this is rigorously +enforced -- if you decorate a function as a `workflow.table` and the first +argument is not named `state` a `TypeError` will be raised. + +For most tables, the initialization of the table will be defined by values in +the {py:class}`Settings `, and there will +be no other function arguments. + +If table initialization does require access to other tables (e.g. the *vehicles* +table needs access to the *households* table to be initialized) then other tables +can be provided as matching-named arguments, in the same way as +[`workflow.step`](core-workflow-steps) functions. + +The `workflow.table` function should return a `pandas.DataFrame` or +`xarray.Dataset` representation of the table. When this function is called +automatically by the processes that orchestrate execution, this object will be +stored in the state's context as the name of the table. + + +## Temporary Tables + +In addition to the main `workflow.table` decorator, there is also a similar +`workflow.temp_table` decorator for temporary tables. + +```python +import pandas as pd +from activitysim.core import workflow + +@workflow.temp_table +def households_merged( + state: workflow.State, + households: pd.DataFrame, + land_use: pd.DataFrame, + accessibility: pd.DataFrame, +) -> pd.DataFrame: + df = pd.DataFrame(...) + # do something to set up table here + return df +``` + +There are two main differences between regular tables and temporary tables: + +1. Temporary tables are never checkpointed. + + The supposition for temporary tables is that they are generally large, and + easy to re-create on the fly, so storing them to disk is wasteful. Most + temporary tables in ActivitySim are simply merges of other existing tables, + although that is not formally a requirement of a temporary tables. + +2. Temporary tables are dropped when any predicate argument is changed in the same `State`. + + The *predicates* are all the named arguments of the `workflow.temp_table` + wrapped function after the `state`. If another ActivitySim instruction + triggers an update to *any* of these predicate arguments, the temporary + table is dropped from the state's context. It can (presumably) be recreated + easily from the (now different) predicate values if/when needed for later steps. + + +(core-workflow-cached-objects)= +## Other Cached Objects + +Other arbitrary Python objects can also be generated by functions that are +handled by the same automatic system as tables, using the `workflow.cached_object` +decorator. + +```python +from activitysim.core import workflow + +@workflow.cached_object +def name_of_object( + state: workflow.State, + other_thing: bool = False, +): + obj = [1,2,3] if other_thing else [7,8,9] # or any python object + return obj +``` + +Similar to temporary tables, these objects are not stored in checkpoint files. +Unlike temporary tables, they are not formally predicated on their arguments, so +for example in the `cached_object` above, a change in the value of `other_thing` +will cause `name_of_object` to be regenerated if it already exists in the state's +context. + +## API + +```{eval-rst} +.. currentmodule:: activitysim.core.workflow + +.. autosummary:: + :toctree: _generated + :template: autosummary/class_decorator.rst + :recursive: + + table + temp_table + cached_object +``` diff --git a/v1.3.0/_sources/dev-guide/core-workflow.md.txt b/v1.3.0/_sources/dev-guide/core-workflow.md.txt new file mode 100644 index 000000000..d20280902 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/core-workflow.md.txt @@ -0,0 +1,42 @@ +# Workflow State + +The general framework of each ActivitySim model is defined within an encapsulated +[`State`](core-workflow-api) object. This object maintains references to data and +model structures in a well-defined context, and allow the user to pass that context +around to the various functions and methods that progressively build up the simulated +activity patterns. + +The [`State`](core-workflow-api) object replaces the ORCA framework, and allows for data +from multiple models, or multiple versions of the same model, to co-exist in a single +Python instance simultaneously. The state contains references for overall model +settings, the network level of service features, as well as the state of the +simulated households, persons, etc. Extensive documentation on the +[API](core-workflow-api.md) for working with the state is available. + +The [`State`](core-workflow-api) class for ActivitySim also offers hooks for a +few fundamental elements: + +- [**Steps**](core-workflow-steps), also referred to as "model components", + which represent the fundamental mathematical building blocks of an ActivitySim + model. Each component contains instructions for incrementally augmenting the + state of the model, generally by adding columns or rows to an existing table, + although components are not limited to that and can potentially do other things + as well. +- [**Data Tables**](core-workflow-table), sometimes referred to in older + documentation sections as "pipeline tables". These tables include households, + persons, trips, tours, and potentially other tables that represent aspects of + the simulated agents. +- [**Other Cached Objects**](core-workflow-table.md#other-cached-objects), which can + be any arbitrary Python object that can be created programmatically and stored + in the state's context dictionary. + + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :hidden: + + core-workflow-api + core-workflow-steps + core-workflow-table +``` diff --git a/v1.3.0/_sources/dev-guide/index.rst.txt b/v1.3.0/_sources/dev-guide/index.rst.txt new file mode 100644 index 000000000..da6c64973 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/index.rst.txt @@ -0,0 +1,38 @@ + +.. _devguide: + +Developers +========== + +The mission of the ActivitySim project is to create and maintain advanced, open-source, +activity-based travel behavior modeling software based on best software development +practices for distribution at no charge to the public. + +The ActivitySim project is led by a consortium of Metropolitan Planning Organizations +(MPOs) and other transportation planning agencies, which provides technical direction +and resources to support project development. New member agencies are welcome to join +the consortium. All member agencies help make decisions about development priorities +and benefit from contributions of other agency partners. Additional information about +the development and management of the ActivitySim is on the `project site `__. + + +Contents +-------- + +.. toctree:: + :maxdepth: 3 + + install + core-workflow + using-sharrow + skim-dataset + checkpointing + workflows + logging + ../development + component-configs + components/index + ../core + ../benchmarking + build-docs + changes diff --git a/v1.3.0/_sources/dev-guide/install.md.txt b/v1.3.0/_sources/dev-guide/install.md.txt new file mode 100644 index 000000000..8f4b07bd8 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/install.md.txt @@ -0,0 +1,73 @@ +(developer-installation)= +# Developer Installation + +Installing ActivitySim as a developer is almost as easy as just using it, +but making some tweaks to the processes enables live code development and +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). +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` +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* +environment like this: + +```sh +conda update conda -n base +conda install -n base -c conda-forge mamba +``` + +While you are at it, if you are a Jupyter user you might want to also install +`nb_conda_kernels` in your base conda environment alongside any other `jupyter` +libraries: + +```sh +mamba install -n base nb_conda_kernels -c conda-forge +``` + +This will ensure your development environments are selectable as kernels in +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 +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 activate ./ASIM-ENV +git clone https://github.com/ActivitySim/sharrow.git +python -m pip install -e ./sharrow +git clone https://github.com/ActivitySim/activitysim.git +python -m pip install -e ./activitysim +``` + +Note the above commands will create an environment with all the +necessary dependencies, clone both ActivitySim and sharrow from GitHub, +and `pip install` each of these libraries in editable mode, which +will allow your code changes to be reflected when running ActivitySim +in this environment. + +Depending on what you are working on, you may want to check out a branch +other than `develop`. To do so, you can point the `git switch` command +above to any other existing branch name. If you want to start an new +branch, first create it with `git branch cool-new-feature` and then switch +to it with `git switch cool-new-feature`. + +Now your environment should be ready to use. Happy coding! + +```{important} +If you add to the ActivitySim dependencies, make sure to also update +the environments in `conda-environments`, which are used for testing +and development. +``` diff --git a/v1.3.0/_sources/dev-guide/logging.md.txt b/v1.3.0/_sources/dev-guide/logging.md.txt new file mode 100644 index 000000000..f2a5a3db7 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/logging.md.txt @@ -0,0 +1,71 @@ +# Logging + +ActivitySim uses the usual Python [logging](https://docs.python.org/3/library/logging.html) +infrastructure, with just a few additional features. + +Generally, logging configuration is done via the +[dictConfig](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) +interface, with keys and values as documented +[here](https://docs.python.org/3/library/logging.config.html#dictionary-schema-details). +This dictionary fed to this configurator is loaded from the `logging.yaml` +file(s) located in your model's configuration directory(s) following the +usual pattern for finding and loading config files. + +```{versionadded} 1.3 +ActivitySim no longer permits the use of `!!python/object/apply` directives inside +yaml input files. These commands imply the capability to allow arbitrary code +execution, and we would like to move away from that. +``` + +Instead of allowing arbitrary code to be loaded into and modify the logging configuration, +there are just a few particular ActivitySim functions are exposed. + +## Log file locations + +As noted above, the logging configuration implementation relies heavily on the +standard Python logging library, which by default knows nothing about ActivitySim +or its typical layout of output files, including placement of logs in a designated +output directory. Therefore, if you set the filename of a logging FileHandler to +just a string like this: + +```yaml +logfile: + class: logging.FileHandler + filename: just-a-file-name.log +``` + +then that file will be created in the Python current working directory (typically +wherever you invoked the script) and not in your designated output directory. +To fix this and write the log into your designated output directory, you can use +`get_log_file_path` as an intervening key in the configuration between the +`filename` key and the desired value, like this: + +```yaml +logfile: + class: logging.FileHandler + filename: + get_log_file_path: my-file-name.log +``` + +This special formatting will be pre-processed by ActivitySim before configuring +the logging, so that the file will be created in your designated output directory. +This also works when subprocesses are running, in which case the log file will +then be created in (or relative to) the process' log file directory, +not in (or relative to) the main output directory. + +## Identifying Subprocesses + +You may want to have different settings for subprocess workers and the main +ActivitySim process. For example, you may have the main processes log everything it writes +to both the console and a log file, while the subprocesses log mostly to files, and +only write higher priority messages (warnings and errors) to the console. Any +logging configuration can be set to bifurcate like this between the main process and +subtasks by setting "is_sub_task" and "is_not_sub_task" keys like this: + +```yaml +handlers: + console: + level: + if_sub_task: WARNING + if_not_sub_task: NOTSET +``` diff --git a/v1.3.0/_sources/dev-guide/skim-dataset.md.txt b/v1.3.0/_sources/dev-guide/skim-dataset.md.txt new file mode 100644 index 000000000..39fdce353 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/skim-dataset.md.txt @@ -0,0 +1,38 @@ +(skim-datasets)= +# Using Skim Dataset + +ActivitySim 1.2 offers two internal frameworks for managing skim data. + +- [`SkimDict`](activitysim.core.skim_dictionary.SkimDict), the legacy + framework, that stores all skim data in one large omnibus array, with + various offset lookups and tools to access values. +- [`SkimDataset`](activitysim.core.skim_dataset.SkimDataset), an + [xarray.Dataset]() based framework, which mimics the + [`SkimDict`](activitysim.core.skim_dictionary.SkimDict) interface, and + adds a number of features optimized specifically for use with `sharrow`. + This framework is automatically used when sharrow is enabled, and there + is no user configuration to enable it separately. + +## Skims in Shared Memory + +These two internal frameworks manage shared memory differently when running +ActivitySim in multiprocessing mode. + +For [`SkimDict`](activitysim.core.skim_dictionary.SkimDict), shared memory is +used only when running with multiprocessing active, and is allocated via the +[`allocate_shared_skim_buffers`](activitysim.core.mp_tasks.allocate_shared_skim_buffers) +function, which in turn invokes +[Network_LOS.allocate_shared_skim_buffers](activitysim.core.los.Network_LOS.allocate_shared_skim_buffers). + +For [`SkimDataset`](activitysim.core.skim_dataset.SkimDataset), shared memory is +used regardless of whether multiprocessing is active or not. The shared memory +allocation is done via the `Dataset.shm.to_shared_memory` method called at the end +of the [`load_skim_dataset_to_shared_memory`](activitysim.core.skim_dataset.load_skim_dataset_to_shared_memory) +function. + +## Skim Dataset API + +```{eval-rst} +.. automodule:: activitysim.core.skim_dataset + :members: +``` diff --git a/v1.3.0/_sources/dev-guide/using-sharrow.md.txt b/v1.3.0/_sources/dev-guide/using-sharrow.md.txt new file mode 100644 index 000000000..d3924ed2a --- /dev/null +++ b/v1.3.0/_sources/dev-guide/using-sharrow.md.txt @@ -0,0 +1,638 @@ + +# Using Sharrow + +This page will walk through an exercise of running a model with `sharrow`. + +## How it Works + +Sharrow accelerates ActivitySim in part by using numba to create optimized and +pre-compiled versions of utility specification files, and caching those bits +of code to disk. + +```{important} +Running the compiler needs to be done in single-process mode, otherwise the +various process all do the compiling and compete to write to the same cache +location on disk, which is likely to fail. You can safely run in +multiprocessing mode after all the compilation for all model components is +complete. +``` + +### Top-Level Activation Options + +Activating sharrow is done at the top level of the model settings file, typically +`settings.yaml`, by setting the `sharrow` configuration setting to `True`: + +```yaml +sharrow: True +``` + +The default operation for sharrow is to attempt to use the sharrow compiler for +all model specifications, and to revert to the legacy pandas-based evaluation +if the sharrow compiler encounters a problem. Alternatively, the `sharrow` +setting can also be set to `require` or `test`. The `require` setting +will cause the model simply fail if sharrow encounters a problem, which is +useful if the user is interested in ensuring maximum performance. +The `test` setting will run the model in a mode where both sharrow and the +legacy pandas-based evaluation are run on each model specification, and the +results are compared to ensure they are substantially identical. This is +useful for debugging and testing, but is not recommended for production runs +as it is much slower than running only one evaluation path or the other. + +Testing is strongly recommended during model development, as it is possible +to write expressions that are valid in one evaluation mode but not the other. +This can happen if model data includes `NaN` values +(see [Performance Considerations](#performance-considerations)), or when +using arithmatic on logical values +(see [Arithmetic on Logical Values](#arithmetic-on-logical-values)). + +### Caching of Precompiled Functions + +The first time you run a model with sharrow enabled, the compiler will run +and create a cache of compiled functions. This can take a long time, especially +for models with many components or complex utility specifications. However, +once the cache is created, subsequent runs of the model will be much faster. +By default, the cached functions are stored in a subdirectory of the +`platformdirs.user_cache_dir` directory, which is located in a platform-specific +location: + +- Windows: `%USERPROFILE%\AppData\Local\ActivitySim\ActivitySim\Cache\...` +- MacOS: `~/Library/Caches/ActivitySim/...` +- Linux: `~/.cache/ActivitySim/...` or `~/$XDG_CACHE_HOME/ActivitySim/...` + +The cache directory can be changed from this default location by setting the +[`sharrow_cache_dir`](activitysim.core.configuration.FileSystem.sharrow_cache_dir) +setting in the `settings.yaml` file. Note if you change this setting and provide +a relative path, it will be interpreted as relative to the model working directory, +and cached functions may not carry over to other model runs unless copied there +by the user. + +## Model Design Requirements + +Activating the `sharrow` optimizations also requires using the new +[`SkimDataset`](skim-datasets) interface for skims instead of the legacy +[`SkimDict`](activitysim.core.skim_dictionary.SkimDict), and internally +recoding zones into a zero-based contiguous indexing scheme. + +### Zero-based Recoding of Zones + +Using sharrow requires recoding zone id's to be zero-based contiguous index +values, at least for internal usage. This recoding needs to be written into +the input table list explicitly. For example, the following snippet of a +`settings.yaml` settings file shows the process of recoding zone ids in +the input files. + +```yaml +input_table_list: + - tablename: land_use + filename: land_use.csv + index_col: zone_id + recode_columns: + zone_id: zero-based + - tablename: households + filename: households.csv + index_col: household_id + recode_columns: + home_zone_id: land_use.zone_id +``` + +For the `land_use` table, the `zone_id` field is marked for recoding explicitly +as `zero-based`, which will turn whatever nominal id's appear in that column into +zero-based index values, as well as store a mapping of the original values that +is used to recode and decode zone id's when used elsewhere. + +The first "elsewhere" recoding is in the households input table, where we will +map the `home_zone_id` to the new zone id's by pointing the recoding instruction +at the `land_use.zone_id` field. If zone id's appear in other input files, they +need to be recoded in those fields as well, using the same process. + +The other places where we need to handle zone id's is in output files. The +following snippet of a `settings.yaml` settings file shows how those id's are +decoded in various output files. Generally, for columns that are fully populated +with zone id's (e.g. tour and trip ends) we can apply the `decode_columns` settings +to reverse the mapping and restore the nominal zone id's globally for the entire +column of data. For columns where there is some missing data flagged by negative +values, the "nonnegative" filter is prepended to the instruction. + +```yaml +output_tables: + action: include + tables: + - tablename: land_use + decode_columns: + zone_id: land_use.zone_id + - tablename: households + decode_columns: + home_zone_id: land_use.zone_id + - tablename: persons + decode_columns: + home_zone_id: land_use.zone_id + school_zone_id: nonnegative | land_use.zone_id + workplace_zone_id: nonnegative | land_use.zone_id + - tablename: tours + decode_columns: + origin: land_use.zone_id + destination: land_use.zone_id + - tablename: trips + decode_columns: + origin: land_use.zone_id + destination: land_use.zone_id +``` + +## Measuring Performance + +Testing with sharrow requires two steps: test mode and production mode. + +In test mode, the code is run to compile all the spec files and +ascertain whether the functions are working correctly. Test mode is expected +to be slow, potentially much slower than older versions of ActivitySim, +especially for models with small populations and zone systems, as the compile +time is a function of the complexity of the utility functions and *not* a +function of the number of households or zones. Once the compile and test is +complete, production mode can then just run the pre-compiled functions with +sharrow, which is much faster. + +It is possible to run test mode and production mode independently using the +existing `activitysim run` command line tool, pointing that tool to the test +and production configurations directories as appropriate. + +To generate a meaningful measure of performance enhancement, it is necessary +to compare the runtimes in production mode against equivalent runtimes with +sharrow disabled. This is facilitated by the `activitysim workflow` command +line tool, which permits the use of pre-made batches of activitysim runs, as +well as automatic report generation from the results. For more details on the +use of this tool, see [workflows](workflows). + + +## Sharrow Compatability and Limitations + +In general, utility specification files contain a sequence of :ref:`expressions` that +are evaluated for each row in a main DataFrame. In legacy ActivitySim, +there are two fundamental evaluation modes: + +- `pandas.DataFrame.eval`, which is the default, and +- plain Python `eval`, which is used when the expression is prefixed with an `@` symbol. + +Under the `pandas.DataFrame.eval` mode, expressions are evaluated within the context +of the current main dataframe only. References can be made to other columns +in that dataframe directly, i.e. if the dataframe contains a column named "income", +the expression can reference that value as "income". However, the expression can +*only* reference other values that are stored in the current row of the dataframe. +The available syntax for these expressions is a subset of regular python, see the +[supported syntax](https://pandas.pydata.org/docs/user_guide/enhancingperf.html#supported-syntax) +section of the pandas documentation for details. + +Under the plain `eval` mode, expressions are evaluated within a broader context +that potentially includes other variables (which other variables is component +dependent) and constants defined in the model settings file. References to +columns in the main dataframe must be made indirectly via attribution, i.e. if +the dataframe contains a column named "income", the expression needs to reference +that value as "df.income". Typically, references to skims, time tables, and anything +else that isn't the simple original dataframe use this mode. While it is sometimes +not as fast as `pandas.DataFrame.eval`, this mode is far more flexible, as you +can write basically any valid Python expression, including calling other functions, +accessing or manipulating table metadata, indexes, or adjacent rows, etc. + +Within sharrow, the distinction between these two modes is ignored, as sharrow +uses a completely different evaluation system routed through numba. The `@` prefix +does not need to be stripped or added anywhere, it is simply ignored. The expression +can reference other columns of the main dataframe directly or indirectly, so that +either "income" or "df.income" is a valid reference to that column in the main +dataframe. You can also reference other variables, including skims as usual for each component +and constants defined in in the model settings file. Within scheduling models, +references can also be made to the timetable as "tt", accessing that interfaces +methods to compute presence and length of adjacent and available time windows. +However, you *cannot* write arbitrary Python code. External functions are not allowed unless they have +already been compiled with numba's `njit` wrapper. Typically, unless specifically +constructed to be allowed for a model component, cross-referencing, merging or +reindexing against tables other than the main dataframe is not allowed. Such +customizations will generally require a custom extension. + +Sharrow only runs for utility specification files. ActivitySim also features the +ability to apply pre-processors and post-processors to annotate tables, which use +specification files that look very similar to utility specifications. These +functions do *not* run through sharrow, and are a great place to relocate expressions +that need to run arbitrary code or join data from other tables. + +### Temporary Variables + +Temporary variables can be created from `@` mode expressions by adding a variable +name beginning with an underscore before the `@`, e.g. `_stops_on_leg@df.trip_count-1`. + +In legacy mode, temporary variables are useful but they can consume substantial +memory, as the variable is computed and stored for every row in the entire dataframe +before it can be used in other expressions. In sharrow, temporary variables are +allocated, used, and freed for each row separately, so no extra memory is required. + +### Pandas-only Expressions + +In legacy mode, expressions can be evaluated using expressions that tap into the +full pandas library, including the ability to call pandas functions and methods +directly. This is not possible in sharrow, as the expressions are compiled into +numba code, which does not have access to the pandas library. If a pandas function +is needed, it must be called in a pre-processor. However, many pandas functions +can be replaced with numpy functions, which are available in numba. For example, +`df.income.fillna(0)` can be replaced with `np.nan_to_num(df.income)`. + +### Switchable Expressions + +As a general rule, it is best to write each utility expression in a manner that +is cross-compatible between sharrow and legacy evaluation modes, even if that +means transitioning a few expressions or parts of expressions into preprocessors. + +However, sometimes this is not possible or makes writing the expressions excessively +complex. In this case, it is possible to write a toggling expression, where the +individual expression evaluated is different for sharrow and legacy modes. The +special comment string `# sharrow:` splits the expression, with everything before this +comment evaluated under the legacy process, and everything after evaluated only +when sharrow is enabled. + +An example of a switching expression is found in the trip destination utilities found +in several examples: + + `@np.log1p(size_terms.get(df.alt_dest, df.purpose)) # sharrow: np.log1p(size_terms['sizearray'])` + +Here, `size_terms` is a DataFrameMatrix class instance, a special class written into +ActivitySim to facilitate reading from a DataFrame as if it were a 2-d array. As it +is a special purpose class written in Python, the numba compiler cannot handle it directly. +Fortunately, sharrow provides an alternative: passing the size terms as a xarray `DataArray`. +This has a slightly different interface, so the sharrow and legacy evaluation modes require +different expressions. The switching expression is used to handle the DataFrameMatrix +on the left (before "# sharrow:") and the DataArray on the right. + +### Optional Variables + +In some cases, a variable may be used where it is available, but is not strictly +necessary for the model to run. For example, a model may have a reference to +mode choice logsums, but the model can still run without them, if it is being used +prior to when logsums are calculated. In this case, the variable can be accessed +using the `get` method, which allows for a default value if the variable is not found. + + `@df.get('mode_choice_logsum', 0)` + +### Performance Considerations + +Sharrow is usually expected to bring significant performance gains to ActivitySim. +However, the numba engine beneath sharrow has a few known performance limitations, +most notably when using [strings](https://numba.readthedocs.io/en/stable/reference/pysupported.html#str). +To enhance performance, it is best to limit the number of string operations, +including simple equality checks (e.g. `df.tour_purpose == 'work'`). Ideally, +such string operations won't appear in utility specifications at all, or if they +do appear, they are executed only once and stored in a temporary value for re-use +as needed. + +A good approach to reduce string operations in model spec files is to convert +string columns to integer or categorical columns in preprocessors. This can +be done using the `map` method, which can be used to convert strings to integers, +for example: + + `df['fuel_type'].map({'Gas': 1, 'Diesel': 2, 'Hybrid': 3}).fillna(-1).astype(int)` + +Alternatively, data columns can be converted to categorical columns with well-defined +structures. Recent versions of sharrow have made significant improvements in +handling of unordered categorical values, allowing for the use of possibly +more intuitive categorical columns. For example, the fuel type column above +could instead be redefined as a categorical column with the following code: + + `df['fuel_type'].astype(pd.CategoricalDtype(categories=['Gas', 'Diesel', 'Hybrid'], ordered=False))` + +It is important that the categories are defined with the same set of values +in the same order, as any deviation will from this will void the compiler cache +and cause the model specification to be recompiled. This means that using +`x.astype('category')` is not recommended, as the categories will be inferred +from the data and may not be consistent across multiple calls to the model +specification evaluator. + +```{note} +Beginning with ActivitySim version 1.3, string-valued +columns created in preprocessors are converted to categorical columns automatically, +which means that ignoring encoding for string-valued outputs is equivalent to +using the `astype('category')` method, and is not recommended. +``` + +For models with utility expressions that include a lot of string comparisons, +(e.g. because they are built for the legacy `pandas.eval` interpreter and have not +been updated) sharrow can be disabled by setting + +```yaml +compute_settings: + sharrow_skip: true +``` + +in the component's configuration yaml file. + +In addition, by default sharrow also tries to optimize performance by setting the +`fastmath` flag to True in the numba compiler. This makes the compiler generate +faster code, by assuming that all variables have finite values (not NaN or Inf). +If the model has expressions that use variables that can contains NaN or Inf +values, the `fastmath` flag can be disabled by setting + +```yaml +compute_settings: + fastmath: false +``` + +### Multiprocessing Performance + +Sharrow leverages a number of performance enhancing techniques, including +parallelization of various computations. This multi-threading can provide significant +benefits within a single-process, but if enabled alongside ActivitySim's multiprocessing +paradigm, the multi-threading does more harm than good, as too many threads will +compete for limited computational resources. To avoid this, the user should completely +disable multi-threading and rely exclusively on multiprocessing to generate parallelism. +This can be done by setting a number of thread-limiting environment variables before +running Python, or immediately at the start of a Python script before ActivitySim +is loaded: + +```python +import os +os.environ["MKL_NUM_THREADS"] = "1" +os.environ["OMP_NUM_THREADS"] = "1" +os.environ["OPENBLAS_NUM_THREADS"] = "1" +os.environ["NUMBA_NUM_THREADS"] = "1" +os.environ["VECLIB_MAXIMUM_THREADS"] = "1" +os.environ["NUMEXPR_NUM_THREADS"] = "1" +``` + +### Limited Tracing and Estimation Mode Capabilities + +When running sharrow-optimized code, large parts of certain calculations are routed +through numba to enhance speed and reduce memory footprint. Many intermediate arrays +are not created, or are allocated and released by numba in a manner not visible to the +general Python interpreter. As a result, in many places the "trace" capabilities of +ActivitySim are limited. These capabilities output intermediate calculations in +extreme detail and are typically only used in debugging and model development, not +in production model runs that need to be optimized for speed. Tracing features can +be re-enabled by switching sharrow off or by using "test" mode, which runs both sharrow +and legacy evaluations together to confirm they are substantially identical. In this +fashion, detailed tracing (albeit slow) remains available for users on all models when +needed. + +Similar constraints apply to estimation mode, as complete estimation mode output +capabilities are not yet integrated with the sharrow engine. Estimation mode remains +fully available when running with sharrow disabled. + + +### Arithmetic on Logical Values + +In expressions written in specification files, boolean values must be treated with +care. When an expression is evaluated in the legacy implementation, the addition +of two boolean values will be processed according to numpy logic, such that: + +```python +np.array([True]) + np.array([True]) == np.array([True]) +np.array([True]) + np.array([False]) == np.array([True]) +np.array([False]) + np.array([True]) == np.array([True]) +np.array([False]) + np.array([False]) == np.array([False]) +``` + +When the same expression is evaluated using sharrow, the expression is evaluated +using Pythonesque rules, such that logical values are implicitly upcast to integers, +giving: + +```python +True + True == 2 +True + False == 1 +False + True == 1 +False + False == 0 +``` + +If this value is later upcast to a number and used in a mathematical calculation +(e.g. multiplied by a float-valued coefficient), obviously the results will vary, +as in the first case the result is never other than 1 or 0, but in the latter case +the result can also be 2. This mismatch can be readily avoided by wrapping the +term in an extra logic gate, which will evaluate the same in both environments: + +```python +(True + True)>0 == True +(True + False)>0 == True +(False + True)>0 == True +(False + False)>0 == False +``` + +(digital-encoding)= +## Digital Encoding + +Sharrow is compatible with and able to efficiently use +[digital encoding](https://activitysim.github.io/sharrow/walkthrough/encoding.html). +These encodings are applied to data either prospectively (i.e. before ActivitySim +ever sees the skim data), or dynamically within a run using the +`taz_skims.digital-encoding` or `taz_skims.zarr-digital-encoding` settings in +the `network_los.yaml` settings file. The only difference between these two +settings is that the former applies this digital encoding internally every +time you run the model, while the latter applies it prior to caching encoded +skims to disk in Zarr format (and then reuses those values without re-encoding +on subsequent runs with the same data). Dictionary encoding (especially joint +dictionary encodings) can take a long time to prepare, so caching the values can +be useful. As read/write speeds for zarr files are fast, you usually won't +notice a meaningful performance degradation when caching, so the default is +generally to use `zarr-digital-encoding`. + +Very often, data can be expressed adequately with far less memory than is +needed to store a standard 32-bit floating point representation. There are +two simple ways to reduce the memory footprint for data: fixed point +encoding, or dictionary encoding. + +### Fixed Point Encoding + +In fixed point encoding, which is also sometimes called scaled integers, +data is multiplied by some factor, then rounded to the nearest integer. +The integer is stored in memory instead of a floating point value, but the +original value can be (approximately) restored by reversing the process. +An offset factor can also be applied, so that the domain of values does not +need to start at zero. + +For example, instead of storing matrix table values as 32-bit floating point values, +they could be multiplied by a scale factor (e.g., 100) +and then converted to 16-bit integers. This uses half the +RAM and can still express any value (to two decimal point +precision) up to positive or negative 327.68. If the lowest +values in that range are never needed, it can also be shifted, +moving both the bottom and top limits by a fixed amount. Then, +for a particular scale $\mu$ and shift $\xi$ (stored in metadata), +from any array element $i$ the implied (original) value $x$ +can quickly be recovered by evaluating $(i / \mu) - \xi$. + +Fixed point digital encoding can be applied to matrix tables in the skims +using options in the `network_los.yaml` settings file. Making transformations +currently also requires shifting the data from OMX to ZARR file formats; +future versions of ActivitySim may accept digitally encoded data directly +from external sources. + +To apply the default 16-bit encoding to individual named skim variables in the +TAZ skims, just give their names under the `zarr-digital-encoding` setting +like this: + +```yaml +taz_skims: + omx: skims.omx + zarr: skims.zarr + zarr-digital-encoding: + - name: SOV_TIME + - name: HOV2_TIME +``` + +If some variables can use less RAM and still be represented adequately with only +8-bit integers, you can specify the bitwidth as well: + +```yaml +taz_skims: + omx: skims.omx + zarr: skims.zarr + zarr-digital-encoding: + - name: SOV_TIME + - name: HOV2_TIME + - name: SOV_TOLL + bitwidth: 8 + - name: HOV2_TOLL + bitwidth: 8 +``` + +If groups of similarly named variables should have the same encoding applied, +they can be identified by regular expressions ("regex") instead of explicitly +giving each name. For example: + +```yaml +taz_skims: + omx: skims.omx + zarr: skims.zarr + zarr-digital-encoding: + - regex: .*_TIME + - regex: .*_TOLL + bitwidth: 8 +``` + + +### Dictionary Encoding + +For dictionary encoding, a limited number of unique values are stored in a +lookup array, and then each encoded value is stored as the position of the +value (or its closest approximation) in the lookup array. If there are fewer +than 256 unique values, this can allow the storage of those values to any level +of precision (even float64 if needed) while using only a single byte per array +element, plus a small fixed amount of overhead for the dictionary itself. The +overhead memory doesn't scale with the dimensions of the array, so this works +particularly well for models with thousands of zones. + +Dictionary encoding can be applied to a single variable in a similar fashion as +fixed point encoding, giving the dictionary bit width in the `by_dict` setting, +or as an additional setting value. + +```yaml +taz_skims: + omx: skims.omx + zarr: skims.zarr + zarr-digital-encoding: + - name: TRANSIT_FARE + by_dict: 8 + - name: TRANSIT_XFERS + by_dict: true + bitwidth: 8 +``` + +The most dramatic memory savings can be found when the categorical correlation +(also known as [Cramér's V](https://en.wikipedia.org/wiki/Cram%C3%A9r%27s_V)) +between multiple variables is high. In this case, we can encode more than one +matrix table using the same dictionary lookup indexes. There may be some +duplication in the lookup table, (e.g. if FARE and XFER are joint encoded, +and if a FARE of 2.25 can be matched with either 0 or 1 XFER, the 2.25 would +appear twice in the lookup array for FARE, once for each value of XFER.) + +Since it is the lookup *indexes* that scale with the number of zones and consume most +of the memory for large zone systems, putting multiple variables together into one +set of indexes can save a ton of memory, so long as the overhead of the lookup array +does not combinatorially explode (hence the need for categorical correlation). + +Practical testing for large zone systems suggest this method of encoding can +reduce the footprint of some low variance data tables (especially transit data) +by 95% or more. + +Applying joint dictionary encoding requires more than one variable name, so only +the `regex` form works here. Use wildcards to match on name patterns, or select a +few specific names by joining them with the pipe operator (|). + +```yaml +taz_skims: + omx: skims.omx + zarr: skims.zarr + zarr-digital-encoding: + - regex: .*_FARE|.*_WAIT|.*_XFERS + joint_dict: true + - regex: FERRYTIME|FERRYFARE|FERRYWAIT + joint_dict: true +``` + +For more details on all the settings available for digital encoding, see +[DigitalEncoding](activitysim.core.configuration.network.DigitalEncoding). + +## Troubleshooting + +If you encounter errors when running the model with sharrow enabled, it is +important to address them before using the model for analysis. This is +especially important when errors are found running in "test" mode (activated +by `sharrow: test` in the top level settings.yaml). Errors may +indicate that either sharrow or the legacy evaluator is not correctly processing +the mathematical expressions in the utility specifications. + +### "utility not aligned" Error + +One common error that can occur when running the model with sharrow in "test" +mode is the "utility not aligned" error. This error occurs when a sharrow +compiled utility calculation does not sufficiently match the legacy utility +calculation. We say "sufficiently" here because the two calculations may have +slight differences due to numerical precision optimizations applied by sharrow. +These optimizations can result in minor differences in the final utility values, +which are typically inconsequential for model results. However, if the differences +are too large, the "utility not aligned" error will be raised. This error does +not indicate whether the incorrect result is from the sharrow or legacy calculation +(or both), and it is up to the user to determine how to align the calculations +so they are reflective of the model developer's intent. + +To troubleshoot the "utility not aligned" error, the user can use a Python debugger +to compare the utility values calculated by sharrow and the legacy evaluator. +ActivitySim also includes error handler code that will attempt to find the +problematic utility expression and print it to the console or log file, under the +heading "possible problematic expressions". This can be helpful in quickly narrowing +down which lines of a specification file are causing the error. + +Common causes of the "utility not aligned" error include: + +- model data includes `NaN` values but the component settings do not + disable `fastmath` (see [Performance Considerations](#performance-considerations)) +- incorrect use of arithmatic on logical values (see + [Arithmetic on Logical Values](#arithmetic-on-logical-values)) + +### Insufficient system resources + +For large models run on large servers, it is possible to overwhelm the system +with too many processes and threads, which can result in the following error: + +``` +OSError: Insufficient system resources exist to complete the requested service +``` + +This error can be resolved by reducing the number of processes and/or threads per +process. See [Multiprocessing](../users-guide/performance/multiprocessing.md) and +[Multithreading](../users-guide/performance/multithreading.md) in the User's Guide +for more information on how to adjust these settings. + +### Permission Error + +If running a model using multiprocessing with sharrow enabled, it is necessary +to have pre-compiled all the utility specifications to prevent the multiple +processes from competing to write to the same cache location on disk. Failure +to do this can result in a permission error, as some processes may be unable to +write to the cache location. + +``` +PermissionError: The process cannot access the file because it is being used by another process +``` + +To resolve this error, run the model with sharrow enabled in single-process mode +to pre-compile all the utility specifications. If that does not resolve the error, +it is possible that some compiling is being triggered in multiprocess steps that +is not being handled in the single process mode. This is likely due to the presence +of string or categorical columns created in a preprocessor that are not being +stored in a stable data format. To resolve this error, ensure that all expressions +in pre-processors are written in a manner that results in stable data types (e.g. +integers, floats, or categorical columns with a fixed set of categories). See +see [Performance Considerations](#performance-considerations)) for examples. diff --git a/v1.3.0/_sources/dev-guide/workflows.md.txt b/v1.3.0/_sources/dev-guide/workflows.md.txt new file mode 100644 index 000000000..133ad6435 --- /dev/null +++ b/v1.3.0/_sources/dev-guide/workflows.md.txt @@ -0,0 +1,70 @@ +(workflows)= +# Workflows + +ActivitySim workflows use the [`pypyr`](https://pypyr.io/) library. This +task runner is more flexible than orca, and relies on isolated 'context' +namespaces rather than storing tables and configurations in Python's +global state. Workflows are activated using the `activitysim workflow` +command line interface. + +You can run a workflow from a local working directory, or one of +a number of pre-packaged workflows that are included with ActivitySim. + + +## Workflows for Performance Monitoring + +A collection of workflows used to compare the new *sharrow* code against +legacy implementations can be found in the +[sharrow-contrast](https://github.com/ActivitySim/activitysim/tree/main/activitysim/workflows/sharrow-contrast) +workflow subdirectory. Each of these first runs the relevant example model in +test mode to compile the relevant functions, and then runs in production mode +to measure runtime and memory usage. This is followed by another run in +"legacy" mode that does not use sharrow, as well as a run in a reference +implementation (version 1.1.3). Finally, a report is generated comparing the +results of these various runs, to illustrate performance and validiate output +quality. + +### Mini Examples + +A collection of "mini" example workflows is provided for typical performance analysis. +Each mini example is based on a small or medium size subarea for each model, +and each runs in single-process mode to illustrate the performance and memory +usage succinctly. These mini examples are sized so they should run on a typical +modeler's laptop (e.g. a modern CPU, 32 GB of RAM). + +| Workflow | Description | +|---------------------|:---------------------------------------------------------------------------------------| +| mtc_mini | Prototype MTC model on 50K households in San Francisco (190 zones) | +| arc_mini | Prototype ARC model on 10K households in Fulton County (1,296 zones) | +| sandag_1zone_mini | Placeholder SANDAG 1-Zone model on 50K households in a test region (90 zones) | +| sandag_2zone_mini | Placeholder SANDAG 2-Zone model on 50K households in a test region (90 TAZs, 690 MAZs) | +| sandag_3zone_mini | Placeholder SANDAG 3-Zone model on 50K households in a test region (90 TAZs, 690 MAZs) | +| sandag_xborder_mini | Prototype SANDAG Cross-Border model on 50K tours in a test region (94 TAZs, 586 MAZs) | +| psrc_mini | Placeholder PSRC Model on 50K households in Seattle (8400 MAZs) | +| comprehensive-mini | Runs all "mini" workflows listed above (warning, this takes a long time!) | + +To invoke a pre-packaged workflow, you can provide the workflow's +name and location within the `activitysim/workflows` directory. +For example, to run the workflow of all "mini" examples, run: + +```shell +activitysim workflow sharrow-contrast/comprehensive-mini +``` + +### Full Size Examples + +Running a "full size" example of an ActivitySim model generally requires more +compute resources than the smaller performance tests shown above. These models +generally require [chunking](chunk_size) to run, and servers with substantial +amounts of RAM. + +The "mp" workflows listed below will run each listed example in multiprocess mode. +They will attempt to automatically scale the number of processes and the chunk +size to the available resources of the server where they are run, but some models +require substantial resources and may not run correctly on inadequate hardware. + +| Workflow | Description | +|-----------------|:-----------------------------------------------------------------| +| mtc_mp | Prototype MTC model | +| arc_mp | Prototype ARC model, 5,922 zones | +| sandag_1zone_mp | Placeholder SANDAG 1-Zone model, 1.2M households and 4,984 zones | diff --git a/v1.3.0/_sources/development.rst.txt b/v1.3.0/_sources/development.rst.txt new file mode 100644 index 000000000..8ba941f24 --- /dev/null +++ b/v1.3.0/_sources/development.rst.txt @@ -0,0 +1,433 @@ + +Software Development +==================== + +This page documents the ActivitySim software design and how to contribute to the project. + +Software Design +--------------- + +The core software components of ActivitySim are described below. ActivitySim is +implemented in Python, and makes heavy use of the vectorized backend C/C++ libraries in +`pandas `__ and `numpy `__ in order to be quite performant. +The core design principle of the system is vectorization of for loops, and this principle +is woven into the system wherever reasonable. As a result, the Python portions of the software +can be thought of as more of an orchestrator, data processor, etc. that integrates a series of +C/C++ vectorized data table and matrix operations. The model system formulates +each simulation as a series of vectorized table operations and the Python layer +is responsible for setting up and providing expressions to operate on these large data tables. + +In developing this software platform, we strive to adhere to a best practices approach to scientific computing, +as summarized in `this article. `__ + +Model Orchestrator +~~~~~~~~~~~~~~~~~~ + +An ActivitySim model is a sequence of model / data processing steps, commonly known as a data pipeline. +A well defined data pipeline has the ability to resume jobs at a known point, which facilitates +debugging of problems with data and/or calculations. It also allows for checkpointing model +resources, such as the state of each person at a point in the model simulation. Checkpointing also +allows for regression testing of results at specified points in overall model run. + +ActivitySim's model orchestrator makes use of depedency injection, which is where one object (or method) +supplies the dependencies of another object. Dependency injection is done by the :mod:`activitysim.core.inject` +module, which wraps `ORCA `__, an orchestration/pipeline tool. Inject defines model +steps, dynamic data sources, and connects them to processing functions. It also defines dynamic data tables +based on pandas DataFrames, columns based on pandas Series, and injectables (functions). Model steps are executed +as steps registered with the model orchestration engine. Over time Inject has extended ORCA's functionality by +adding a :ref:`pipeline_in_detail` that runs a series of model steps, manages the state of the data +tables throughout the model run, allows for restarting at any model step, and integrates with the +random number generation procedures (see :ref:`random_in_detail`). + +Data Handling +~~~~~~~~~~~~~ + +ActivitySim works with three open data formats, `HDF5 `__ +, `Open Matrix (OMX) `__, and `CSV `__ . +The HDF5 binary data container is used for the :ref:`pipeline_in_detail` data store. +OMX, which is based on HDF5, is used for input and output matrices (skims and demand matrices). CSV files +are used for various inputs and outputs as well. + +Three key data structures in ActivitySim are: + +* `pandas.DataFrame `__ - A data table with rows and columns, similar to an R data frame, Excel worksheet, or database table +* `pandas.Series `__ - a vector of data, a column in a DataFrame table or a 1D array +* `numpy.array `__ - an N-dimensional array of items of the same type, and is often a network skim matrix or collection of skim matrices by time-period or mode for example + +Expressions +~~~~~~~~~~~ + +ActivitySim exposes all model expressions in CSV files. These model expression CSV files +contain Python expressions, mainly pandas/numpy expression, and reference input data tables +and network skim matrices. With this design, the Python code, which can be thought of as a generic expression +engine, and the specific model calculations, such as the utilities, are separate. This helps to avoid +modifying the actual Python code when making changes to the models, such as during model calibration. An +example of model expressions is found in the example auto ownership model specification file - +`auto_ownership.csv `__. +Refer to the :ref:`expressions` section for more detail. + +Many of the models have pre- and post-processor table annotators, which read a CSV file of expression, calculate +required additional table fields, and join the fields to the target tables. An example table annotation expressions +file is found in the example configuration files for households for the CDAP model - +`annotate_households_cdap.csv `__. +Refer to :ref:`table_annotation` for more information and the :func:`activitysim.abm.models.util.expressions.assign_columns` function. + +Choice Models +~~~~~~~~~~~~~ + +ActivitySim currently supports multinomial (MNL) and nested logit (NL) choice models. Refer to :ref:`logit_in_detail` +for more information. It also supports custom expressions as noted above, which can often be used to +code additional types of choice models. In addition, developers can write their own choice models +in Python and expose these through the framework. + +Person Time Windows +~~~~~~~~~~~~~~~~~~~ + +The departure time and duration models require person time windows. Time windows are adjacent time +periods that are available for travel. ActivitySim maintains time windows in a pandas table where each row is +a person and each time period is a column. As travel is scheduled throughout the simulation, the relevant +columns for the tour, trip, etc. are updated as needed. Refer to :ref:`time_windows` for more information. + +Models +~~~~~~ + +An activitysim travel model is made up of a series of models, or steps in the data pipeline. A model +typically does the following: + + * registers an Inject step that is called by the model runner + * sets up logging and tracing + * gets the relevant input data tables from Inject + * gets all required settings, config files, etc. + * runs a data preprocessor on each input table that needs additional fields for the calculation + * solves the model in chunks of data table rows if needed + * runs a data postprocessor on the output table data that needs additional fields for later models + * writes the resulting table data to the pipeline + +See :ref:`models` for more information. + + +Development Install +------------------- + +The development version of ActivitySim can be installed as follows: + +* Clone or fork the source from the `GitHub repository `__ +* Navigate to your local activitysim git directory +* Create a development environment by running + ``conda env create --file=conda-environments/activitysim-dev.yml --name ASIM_DEV``. + This will create a new conda environment named "ASIM_DEV" (change the name in + the command if desired). ActivitySim will be installed in "editable" mode, so + any changes you make in the code in your git directory will be reflected. +* Activate the new conda environment ``conda activate ASIM_DEV`` + + +Development Guidelines +---------------------- + +ActivitySim development adheres to the following standards. + +Style +~~~~~ + +* Python code should follow the `black code style `__ +* Python docstrings should follow the `numpydoc documentation format `__ + +Imports +~~~~~~~ + +* Imports should be one per line. +* Imports should be grouped into standard library, third-party, and intra-library imports. +* ``from`` import should follow regular ``imports``. +* Within each group the imports should be alphabetized. +* Imports of scientific Python libraries should follow these conventions: + +:: + + import numpy as np + import pandas as pd + + +Working Together in the Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We use `GitHub Flow `__. The key points to +our GitHub workflow are: + +* The ``main`` branch contains the latest release version of the ActivitySim resources +* The ``develop`` branch contains new features or revisions planned for the next release. + Generally, developers should not work directly in the ``develop`` branch. +* Work to implement new features or other revisions is done in an issue/feature branch + (or a fork) and developers can open a pull request (PR) to merge their work into ``develop``. +* The test system automatically runs the tests on PR's. PR's do not necessarily need to pass + all tests to be merged into ``develop``, but any failures should be cause by known existing + problems -- PR's should strive to not break anything beyond what was broken previously. +* Upon review and agreement by a consortium member or committer other than the author, + and barring any objection raised by a consortium member, PR's can be merged into the + ``develop`` branch. +* If tests pass for the ``develop`` branch, new features are suitably documented, and on approval of + `a lazy majority of the PMC `__, + a repository administrator can approve a manual pull request to merge ``develop`` into ``main``, + and otherwise make a `product release `__. + + +Versioning +~~~~~~~~~~ + +ActivitySim uses the following `versioning convention `__: + +:: + + MAJOR.MINOR.PATCH[.devN] + +* where MAJOR designates a major revision number for the software, like 2 or 3 for Python. + Usually, raising a major revision number means that you are adding a lot of features, + breaking backward-compatibility or drastically changing the APIs (Application Program + Interface) or ABIs (Application Binary Interface). +* MINOR usually groups moderate changes to the software like bug fixes or minor improvements. + Most of the time, end users can upgrade with no risks their software to a new minor release. + In case an API changes, the end users will be notified with deprecation warnings. In other + words, API and ABI stability is usually a promise between two minor releases. +* PATCH releases are made principally to address bugs or update non-core parts of the + ActivitySim codebase (e.g. dependency requirements, distribution channels). End users + should expect no changes at all in how the software works between two patch releases. +* DEVELOPMENT pre-releases are used to test and prepare integration with other external + services that require a "release". End users should not typically install or use a development + release other than for a specific well-defined purpose. + +Testing +~~~~~~~ + +ActivitySim testing is done with several tools: + +* `black `__, a tool to check and enforce black + code style on Python code +* `isort ` to organize imports +* `pytest `__, a Python testing tool +* `coveralls `__, a tool for measuring code coverage and publishing code coverage stats online + +To run the tests locally, first make sure the required packages are installed. Next, run the tests with the following commands: + +:: + + black --check + py.test + +These same tests are run by Travis with each push to the repository. These tests need to pass in order +to merge the revisions into main. + +In some cases, test targets need to be updated to match the new results produced by the code since these +are now the correct results. In order to update the test targets, first determine which tests are +failing and then review the failing lines in the source files. These are easy to identify since each +test ultimately comes down to one of Python's various types of `assert` statements. Once you identify +which `assert` is failing, you can work your way back through the code that creates the test targets in +order to update it. After updating the test targets, re-run the tests to confirm the new code passes all +the tests. + +See :ref:`adding_agency_examples` for more information on testing, most notably, agency example models. + +Profiling +~~~~~~~~~ + +A handy way to profile ActivitySim model runs is to use `snakeviz `__. +To do so, first install snakeviz and then run ActivitySim with the Python profiler (cProfile) to create +a profiler file. Then run snakeviz on the profiler file to interactively explore the component runtimes. + +Documentation +~~~~~~~~~~~~~ + +See :ref:`Documentation `. + + +.. _release_steps : + +Releases +~~~~~~~~ + +With the agreement of the PMC, a project administrator will handle making releases, following the detailed +steps outlined in the `HOW_TO_RELEASE `__ +document. + + +Issues and Support +~~~~~~~~~~~~~~~~~~ + +Issue tracking and support is done through GitHub `issues `__. + +License +~~~~~~~ + +ActivitySim is provided "as is." See the +`License `__ for more information. + +Contribution Review Criteria +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When contributing to ActivitySim, the set of questions below will be asked of the contribution. Make sure to also +review the documentation above before making a submittal. The automated test system also provides some helpful +information where identified. + +To submit a contribution for review, issue a pull request with a comment introducing your contribution. The comment +should include a brief overview, responses to the questions, and pointers to related information. The entire submittal +should ideally be self contained so any additional documentation should be in the pull request as well. +The `PMC `__ and/or its Contractor will handle the review request, comment on each +question, complete the feedback form, and reply to the pull request. If accepted, the commit(s) will +be `squashed and merged `__. +Its a good idea to setup a pre-submittal meeting to discuss questions and better understand expectations. + +**Review Criteria** + + 1. Does it contain all the required elements, including a runnable example, documentation, and tests? + 2. Does it implement good methods (i.e. is it consistent with good practices in travel modeling)? + 3. Are the runtimes reasonable and does it provide documentation justifying this claim? + 4. Does it include non-Python code, such as C/C++? If so, does it compile on any OS and are compilation instructions included? + 5. Is it licensed with the ActivitySim license that allows the code to be freely distributed and modified and includes attribution so that the provenance of the code can be tracked? Does it include an official release of ownership from the funding agency if applicable? + 6. Does it appropriately interact with the data pipeline (i.e. it doesn't create new ways of managing data)? + 7. Does it include regression tests to enable checking that consistent results will be returned when updates are made to the framework? + 8. Does it include sufficient test coverage and test data for existing and proposed features? + 9. Any other comments or suggestions for improving the developer experience? + +**Feedback** + +The PMC and/or its Contractor will provide feedback for each review criteria above and tag each submittal category as follows: + ++-----------------------------------+-------------+-------------------+-------------------+ +| Status | Code | Documentation | Tests/Examples | ++===================================+=============+===================+===================+ +| Accept | | | | ++-----------------------------------+-------------+-------------------+-------------------+ +| Accept but recommend revisions | | | | ++-----------------------------------+-------------+-------------------+-------------------+ +| Do not accept | | | | ++-----------------------------------+-------------+-------------------+-------------------+ + +.. _adding_agency_examples : + +Adding Agency Examples +---------------------- + +ActivitySim includes several mature or in-development full scale agency :ref:`examples`. Adding an agency example to +ActivitySim adds additional assurances that future updates to ActivitySim will more easily work for users. At the same +time, with each additional implementation, the need for additional test coverage increases. This increased need for +test coverage relates to when setting up a new model, with differences in inputs and configurations, when adding new +model components (and/or revisions to the core) in order to implement new features, and when implementing model +components at a scale previously untested. The following section describes the process to add an agency example model +to ActivitySim. + +Examples +~~~~~~~~ + +Generally speaking, there are two types of ActivitySim examples: test examples and agency examples. + +* Test examples - these are the core ActivitySim maintained and tested examples developed to date. The current test + examples are :ref:`prototype_mtc`, :ref:`example_estimation`, :ref:`placeholder_multiple_zone`, and :ref:`prototype_marin`. + These examples are owned and maintained by the project. +* Agency examples - these are agency partner model implementations currently being setup. The current agency examples + are :ref:`prototype_arc`, :ref:`prototype_semcog`, :ref:`placeholder_psrc`, :ref:`placeholder_sandag`, and :ref:`prototype_sandag_xborder`. These examples can be + configured in ways different from the test examples, include new inputs and expressions, and may include new planned + software components for contribution to ActivitySim. These examples are owned by the agency. + +Furthermore, multiple versions of these examples can exist, and be used for various testing purposes: + +* Full scale - a full scale data setup, including all households, zones, skims, time periods, etc. This is a "typical" + model setup used for application. This setup can be used to test the model results and performance since model + results can be compared to observed/known answers and runtimes can be compared to industry experience. It can also + be used to test core software functionality such as tracing and repeatability. +* Cropped - a subset of households and zones for efficient / portable running for testing. This setup can really only + be used to test the software since model results are difficult to compare to observed/known answers. This version of + an example is not recommended for testing overall runtime since it's a convenience sample and may not represent the + true regional model travel demand patterns. However, depending on the question, this setup may be able to answer + questions related to runtime, such as improvements to methods indifferent to the size of the population and number of + zones. +* Other - a specific route/path through the code for testing. For example, the estimation example tests the estimation + mode functionality. The estimation example is a version of the example prototype MTC example - it inherits most settings from + prototype_mtc and includes additional settings for reading in survey files and producing estimation data bundles. + +Regardless of the type or version, all functioning examples are described in a common list stored in +`example_manifest.yaml `_. +Each item included in this file represents one example, and each includes the following tags: + +* *name*: A unique name for the example, used to identify the example when using the `activitysim create` command. The + naming convention used is to give each example a name that is all lower case, and which uses underscores to separate + words. +* *description*: A short sentence describing the example. +* *include*: A list of files or directories to include in the example. For smaller input files (e.g. configuration + files, or data files used on "test" sized examples), each file or directory to include can be given as a simple + string, which specifies the subdirectory of the embedded ActivitySim examples to be copied into a working directory. + For larger files that are not embedded into the main ActivitySim GitHub repository, items are given as a 3-tuple: + (url, target_path, sha256). The `url` points to a publicly available address where the file can be downloaded, the + `target_path` gives the relative filepath where the file should be installed in the working directory, and the + `sha256` is a checksum used to verify the file was downloaded correctly (and to prevent re-downloading when the file + is already available). For defining new examples, use the `sha256_checksum` function to get a file's checksum that + should be included in the example manifest. + +Testing +~~~~~~~ + +The test plan for test examples versus agency examples is different: + +* Test examples test software features such as stability, tracing, expression solving, etc. This set of tests is run + by the TravisCI system and is a central feature of the software development process. +* Agency examples test a complete run of the cropped version to ensure it runs and the results are as expected. This + is done via a simple run model test that runs the cropped version and compares the output trip list to the expected + trip list. This is what is known as a regression test. This test is also run by TravisCI. + +Both types of examples are stored in the ActivitySim repositories for version control and collaborative maintenance. +There are two storage locations: + +* The `activitysim package example folder `_, + which stores the test and agency example setup files, cropped data and cropping script, regression test script, + expected results, and a change log to track any revisions to the example to get it working for testing. These + resources are the resources automatically tested by the TravisCI test system with each revision to the software. +* The `activitysim_resources repository `_, which stores just the + full scale example data inputs using `Git LFS `_. This repository has a monthly cost and + takes time to upload/download and so the contents of it are separate from the main software repository. These + resources are the resources periodically and manually tested (for now). + +This two-part solution allows for the main activitysim repo to remain relatively lightweight, while providing an +organized and accessible storage solution for the full scale example data. The ActivitySim command line interface for +creating and running examples makes uses the +`example_manifest.yaml `_ +to maintain the dictionary of the examples and how to get and run them. + +Running the Test System +~~~~~~~~~~~~~~~~~~~~~~~ + +The automatic TravisCI test system runs the test examples and the cropped agency examples. Examples of the testing +resources for each agency example that need to be up-to-date are: + +* `scripts folder (including crop script) `_ +* `test folder (including test script) `_ +* `regress folder (including expected outputs) `_ + +For the time being, running the full scale examples is done manually since it involves getting and running several large examples that take many hours to run. The entire system could be fully automated, and either run in the cloud or on a local server. + +Update Use Cases +~~~~~~~~~~~~~~~~ + +To better illustrate the workflow for adding agency examples, a series of use cases is discussed. + +When a new version of the code is pushed to develop: + +* The automatic test system is run to ensure the tests associated with the test examples pass. If any of the tests do not pass, then either the code or the expected test results are updated until the tests pass. +* The automatic test system also runs each cropped agency example regression test to ensure the model runs and produces the same results as before. If any of the tests do not pass, then either the code or the expected test results are updated until the tests pass. However, the process for resolving issues with agency example test failure has two parts: + + * If the agency example previous ran without error or future warnings (i.e. deprecation warnings and is therefore up-to-date), then the developer will be responsible for updating the agency example so it passes the tests + * If the agency example previously threw errors or future warnings (i.e. is not up-to-date), then the developer will not update the example and the responsibility will fall to the agency to update it when they have time. This will not preclude development from advancing since the agency specific test can fail while the other tests continue to pass. If the agency example is not updated within an agreed upon time frame, then the example is removed from the test system. + +To help understand this case, the addition of support for representative logsums to :ref:`prototype_mtc` is discussed. prototype_mtc was selected as the test case for development of this feature because this feature could be implemented and tested against this example, which is the primary example to date. With the new feature configured for this example, the automatic test system was run to ensure all the existing test examples pass their tests. The automatic test system was also run to ensure all the cropped agency examples passed their tests, but since not of them include this new feature in their configuration, the test results were the same and therefore the tests passed. + +When an agency wants to update their example: + +* It is recommended that agencies keep their examples up-to-date to minimize the cost/effort of updating to new versions of ActivitySim. However, the frequency with which to make that update is a key issue. The recommended frequency of ensuring the agency example is up-to-date depends on the ActivitySim development roadmap/phasing and the current features being developed. Based on past project experience, it probably makes sense to not let agency examples fall more than a few months behind schedule, or else updates can get onerous. + +* When making an agency model update, agencies update their example through a pull request. This pull request changes nothing outside their example folder. The updated resources may include updated configs, inputs, revisions to the cropped data/cropping script, and expected test results. The automatic cropped example test must run without warnings. The results of the full scale version is shared with the development team in the PR comments. + +To help understand this case, the inclusion of :ref:`placeholder_psrc` as an agency example is discussed. This model is PSRC's experimentation of a two zone model and is useful for testing the two zone features, including runtime. A snapshot of PSRC's efforts to setup an ActivitySim model with PSRC inputs was added to the test system as a new agency example, called placeholder_psrc. After some back and forth between the development team and PSRC, a full scale version of placeholder_psrc was successfully run. The revisions required to create a cropped version and full scale version were saved in a change log included with the example. When PSRC wants to update placeholder_psrc, PSRC will pull the latest develop code branch and then update placeholder_psrc so the cropped and full scale example both run without errors. PSRC also needs to update the expected test results. Once everything is in good working order, then PSRC issues a pull request to develop to pull their updated example. Once pulled, the automatic test system will run the cropped version of placeholder_psrc. + +When an agency example includes new submodels and/or contributions to the core that need to be reviewed and then pulled/accepted: + +* First, the agency example must comply with the steps outlined above under "When an agency wants to update their example". +* Second, the agency example must be up-to-date with the latest develop version of the code so the revisions to the code are only the exact revisions for the new submodels and/or contributions to the core. +* The new submodels and/or contributions to the core will then be reviewed by the repository manager and it's likely some revisions will be required for acceptance. Key items in the review include python code, user documentation, and testable examples for all new components. If the contribution is just new submodels, then the agency example that exercises the new submodel is sufficient for test coverage since TravisCI will automatically test the cropped version of the new submodel. If the contribution includes revisions to the core that impact other test examples, then the developer is responsible for ensuring all the other tests that are up-to-date are updated/passing as well. This includes other agency examples that are up-to-date. This is required to ensure the contribution to the core is adequately complete. + +To help understand this case, the addition of the parking location choice model for :ref:`prototype_arc` is discussed. First, ARC gets their example in good working order - i.e. updates to develop, makes any required revisions to their model to get it working, creates a cropped and full scaled example, and creates the expected test results. In addition, this use case includes additional submodel and/or core code so ARC also authors the new feature, including documentation and any other relevant requirements such as logging, tracing, support for estimation, etc. With the new example and feature working offline, then ARC issues a pull request to add prototype_arc and the new submodel/core code and makes sure the automatic tests are passing. Once accepted, the automatic test system will run the test example tests and the cropped agency examples. Since the new feature - parking location choice model - is included in prototype_arc, then new feature is now tested. Any testing of downstream impacts from the parking location choice model would also need to be implemented in the example. diff --git a/v1.3.0/_sources/estimation.rst.txt b/v1.3.0/_sources/estimation.rst.txt new file mode 100644 index 000000000..faffde5f5 --- /dev/null +++ b/v1.3.0/_sources/estimation.rst.txt @@ -0,0 +1,181 @@ + +.. _estimation_old : + +Estimation +---------- + +ActivitySim includes the ability to re-estimate submodels using choice model estimation tools +such as `larch `__. To do so, ActivitySim adopts the concept of an estimation +data bundle (EDB), which is a collection of the necessary data to re-estimate a submodel. For example, for the auto ownership submodel, +the EDB consists of the following files: + +* model settings - the auto_ownership_model_settings.yaml file +* coefficients - the auto_ownership_coefficients.csv file with each coefficient name, value, and constrain set to True or False if the coefficient is estimatable +* utilities specification - the auto_ownership_SPEC.csv utility expressions file +* chooser and alternatives data - the auto_ownership_values_combined.csv file with all chooser and alternatives data such as household information, land use information, and the utility data components for each alternative + +ActivitySim also includes Jupyter :ref:`estimation_example_notebooks` for estimating submodels with larch, as well as an ``activitysim.estimation.larch`` submodule that transforms EDBs into larch models. Additional estimation software translators can be added later if desired. + +The combination of writing an EDB for a submodel + a larch estimation notebook means users can easily re-estimate submodels. This +combination of functionality means: + +* There is no duplication of model specifications. ActivitySim owns the specification and larch pivots off of it. Users code model specifications and utility expressions in ActivitySim so as to facilitate ease of use and eliminate inconsistencies and errors between the code used to estimate the models and the code used to apply the models. +* The EDB includes all the data and model structure information and the ``activitysim.estimation.larch`` submodule used by the example notebooks transforms the EDB to larch's data model for estimation. +* Users are able to add zones, alternatives, new chooser data, new taz data, new modes, new coefficients, revise utilities, and revise nesting structures in ActivitySim and larch responds accordingly. +* Eventually it may be desirable for ActivitySim to automatically write larch estimators (or other types of estimators), but for now the integration is loosely coupled rather than tightly coupled in order to provide flexibility. + +Workflow +~~~~~~~~ + +The general workflow for estimating models is shown in the following figures and explained in more detail below. + +.. image:: images/estimation_tools.jpg + +* The user converts their household travel survey into ActivitySim format households, persons, tours, joint tour participants, and trip tables. The households and persons tables must have the same fields as the synthetic population input tables since the surveyed households and persons will be run through the same set of submodels as the simulated households and persons. +* The ActivitySim estimation example ``scripts\infer.py`` module reads the ActivitySim format household travel survey files and checks for inconsistencies in the input tables versus the model design + calculates additional fields such as the household joint tour frequency based on the trips and joint tour participants table. Survey households and persons observed choices much match the model design (i.e. a person cannot have more work tours than the model allows). +* ActivitySim is then run in estimation mode to read the ActivitySim format household travel survey files, run the ActivitySim submodels to write estimation data bundles (EDB) that contains the model utility specifications, coefficients, chooser data, and alternatives data for each submodel. Estimation mode runs single-processed and without destination sampling. +* The relevant EDBs are read and transformed into the format required by the model estimation tool (i.e. larch) and then the coefficients are re-estimated. The ``activitysim.estimation.larch`` library is included for integration with larch and there is a Jupyter Notebook estimation example for each core submodel. No changes to the model specification are made in the process. +* The user can then update the ActivitySim model coefficients file(s) for the estimated submodel and re-run the model in simulation mode. The user may want to use the restartable pipeline feature of ActivitySim to just run the submodel of interest. + +.. image:: images/estimation_example.jpg + + +.. _estimation_example: + +Example +~~~~~~~ + +.. note:: + The estimation_mode.ipynb Jupyter :ref:`estimation_example_notebooks` also introduces estimation mode and walks the user through the process. + +To run the estimation example, do the following: + +* Activate the correct conda environment if needed +* Create a local copy of the estimation example folder + +:: + + activitysim create -e example_estimation_sf -d test_example_estimation_sf + +* Run the example + +:: + + cd test_example_estimation_sf + activitysim run -c configs_estimation/configs -c configs -o output -d data_sf + + +* ActivitySim should log some information and write outputs to the output folder, including EDBs for each submodel. The estimation example runs for about 15 minutes and writes EDBs for 2000 households. +* Open :ref:`estimation_example_notebooks` for a specific submodel and then step through the notebook to re-estimate the sub-model. + +The estimation example assumes the machine has sufficient RAM to run with chunking disabled (`chunk_training_mode: disabled`). See :ref:`chunk_size` for more information. + +Settings +~~~~~~~~ + +Additional settings for running ActivitySim in estimation mode are specified in the ``estimation.yaml`` file. The settings are: + +* ``enable`` - enable estimation, either True or False +* ``bundles`` - the list of submodels for which to write EDBs +* ``survey_tables`` - the list of input ActivitySim format survey tables with observed choices to override model simulation choices in order to write EDBs. These tables are the output of the ``scripts\infer.py`` script that pre-processes the ActivitySim format household travel survey files for the example data and submodels + + +.. _estimation_example_notebooks_old: + +Estimation Notebooks +~~~~~~~~~~~~~~~~~~~~ + +ActivitySim includes a `Jupyter Notebook `__ recipe book with interactive re-estimation examples for each estimatable submodel. To run a Jupyter notebook, do the following: + +* Open a conda prompt and activate the conda environment with ActivitySim installed +* If needed, ``conda install jupyterlab`` so you can run jupyter notebooks +* Type ``jupyter notebook`` to launch the web-based notebook manager +* Navigate to the ``examples/examples_estimaton/notebooks`` folder and select a notebook from the table below +* Save the updated coefficient file(s) to the configs folder and run the model in simulation mode + ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Example | Notebook | ++=====================================+=====================================================================================================================================================================================+ +| Estimation mode overview | `01_estimation_mode.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| School location | `02_school_location.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Work location | `03_work_location.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Auto ownership | `04_auto_ownership.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Free parking | `05_free_parking.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| CDAP | `06_cdap.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Mandatory tour frequency | `07_mand_tour_freq.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Work tour scheduling | `08_work_tour_scheduling.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| School tour scheduling | `09_school_tour_scheduling.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Joint tour frequency | `10_joint_tour_freq.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Jointatory tour composition | `11_joint_tour_composition.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Jointatory tour participation | `12_joint_tour_participation.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Joint nonmandatory tour destination | `13_joint_nonmand_tour_dest.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Joint tour scheduling | `14_joint_tour_scheduling.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Non mandatory tour frequency | `15_non_mand_tour_freq.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Non mandatory tour scheduling | `16_nonmand_tour_scheduling.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Tour mode choice | `17_tour_mode_choice.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Atwork subtour frequency | `18_atwork_subtour_freq.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Atwork subtour destination | `19_atwork_subtour_dest.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Atwork subtour scheduling | `20_atwork_subtour_scheduling.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Stop frequency | `21_stop_frequency.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Trip destination | `22_trip_dest.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Trip mode choice | `23_trip_mode_choice.ipynb `_ | ++-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +General API +~~~~~~~~~~~ + +.. automodule:: activitysim.estimation.larch.general + :members: + +.. automodule:: activitysim.estimation.larch.data_maker + :members: + +.. automodule:: activitysim.estimation.larch.simple_simulate + :members: + +Models API +~~~~~~~~~~ + +.. automodule:: activitysim.estimation.larch.auto_ownership + :members: + +.. automodule:: activitysim.estimation.larch.cdap + :members: + +.. automodule:: activitysim.estimation.larch.location_choice + :members: + +.. automodule:: activitysim.estimation.larch.mode_choice + :members: + +.. automodule:: activitysim.estimation.larch.nonmand_tour_freq + :members: + +.. automodule:: activitysim.estimation.larch.scheduling + :members: + +.. automodule:: activitysim.estimation.larch.stop_frequency + :members: diff --git a/v1.3.0/_sources/gettingstarted.rst.txt b/v1.3.0/_sources/gettingstarted.rst.txt new file mode 100644 index 000000000..3dcb27bad --- /dev/null +++ b/v1.3.0/_sources/gettingstarted.rst.txt @@ -0,0 +1,262 @@ + +Getting Started +=============== + +This page describes how to get started with ActivitySim. + +.. note:: + ActivitySim is under active development + + +.. index:: installation + + +Pre-packaged Installer +---------------------- + +Beginning with version 1.2, ActivitySim is now available for Windows via a +pre-packaged installer. This installer provides everything you need to run +ActivitySim, including Python, all the necessary supporting packages, and +ActivitySim itself. You should only choose this installation process if you +plan to use ActivitySim but you don't need or want to do other Python +development. Note this installer is provided as an "executable" which (of course) +installs a variety of things on your system, and it is quite likely to be flagged by +Windows, anti-virus, or institutional IT policies as "unusual" software, which +may require special treatment to actually install and use. + +Download the installer from GitHub `here `_. +It is strongly recommended to choose the option to install "for me only", as this +should not require administrator privileges on your machine. Pay attention +to the *complete path* of the installation location. You will need to know +that path to run ActivitySim in the future, as the installer does not modify +your "PATH" and the location of the `ActivitySim.exe` command line tool will not +be available without knowing the path to where the install has happened. + +Once the install is complete, ActivitySim can be run directly from any command +prompt by running `/Scripts/ActivitySim.exe`. + + +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. + +Alternatively, if you prefer a package installer backed by corporate tech +support available (for a fee) as necessary, you can install +`Anaconda 64bit Python 3 `__, +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. + +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 +home installation folder, such as: + +:: + + proxy_servers: + http: http://myproxy.org:8080 + https: https://myproxy.org:8080 + ssl_verify: false + +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 + +This command will create the environment and install all the dependencies +required for running ActivitySim. It is only necessary to create the environment +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 + +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 + +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 + + # packages for building documentation + mamba 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 + + # packages for example notebooks + mamba 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 + +4. To use the **asim** environment, you need to activate it + +:: + + 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`. + +Alternative Installation Methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you prefer to install ActivitySim without 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 + + # required for ActivitySim version 1.0.1 and earlier + pip install zbox + +And then simply install just activitysim with pip. + +:: + + python -m pip install activitysim + +If you are using a firewall you may need to add ``--trusted-host pypi.python.org --proxy=myproxy.org:8080`` to this command. + +For development work, can also install ActivitySim directly from source. Clone +the ActivitySim repository, and then from within that directory run:: + + python -m pip install . -e + +The "-e" will install in editable mode, so any changes you make to the ActivitySim +code will also be reflected in your installation. + +Installing from source is easier if you have all the necessary dependencies already +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 + +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 +ActivitySim itself in editable mode as described above. + +.. note:: + + ActivitySim is a 64bit Python 3 library that uses a number of packages from the + scientific Python ecosystem, most notably `pandas `__ + and `numpy `__. + + As mentioned above, the recommended way to get your own scientific Python installation is to + install 64 bit Anaconda, which contains many of the libraries upon which + ActivitySim depends + some handy Python installation management tools. + + Anaconda includes the ``conda`` command line tool, which does a number of useful + things, including creating `environments `__ + (i.e. stand-alone Python installations/instances/sandboxes) that are the recommended + way to work with multiple versions of Python on one machine. Using conda + environments keeps multiple Python setups from conflicting with one another. + + You need to activate the activitysim environment each time you start a new command + session. You can remove an environment with ``conda remove -n asim --all`` and + check the current active environment with ``conda info -e``. + + For more information on Anaconda, see Anaconda's `getting started + `__ guide. + +Run the Primary Example +----------------------- + +ActivitySim includes a :ref:`cli` for creating examples and running the model. + +To setup and run the primary example (see :ref:`examples`), do the following: + +* Open a command prompt +* If you installed ActivitySim using conda environments, activate the conda + environment with ActivitySim installed (i.e. ``conda activate asim``) +* 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 + like ``c:\programdata\activitysim\scripts\activitysim.exe``. +* Type ``activitysim create -e prototype_mtc -d test_prototype_mtc`` to copy + the very small prototype_mtc example to a new test_prototype_mtc directory +* Change to the test_prototype_mtc directory +* Type ``activitysim run -c configs -o output -d data`` to run the example +* Review the outputs in the output directory + +.. note:: + Common configuration settings can be overridden at runtime. See ``activitysim -h``, ``activitysim create -h`` and ``activitysim run -h``. + ActivitySim model runs can be configured with settings file inheritance to avoid duplicating settings across model configurations. See :ref:`cli` for more information. + +Additional examples, including the full scale prototype MTC regional demand model, estimation integration examples, multiple zone system examples, +and examples for agency partners are available for creation by typing ``activitysim create -l``. To create these examples, ActivitySim downloads the (large) input files from +the `ActivitySim resources `__ repository. See :ref:`examples` for more information. + +Try the Notebooks +----------------- + +ActivitySim includes a `Jupyter Notebook `__ recipe book with interactive examples. To run a Jupyter notebook, do the following: + +* Open a conda prompt and activate the conda environment with ActivitySim installed +* If needed, ``conda install jupyterlab`` so you can run jupyter notebooks +* Type ``jupyter notebook`` to launch the web-based notebook manager +* Navigate to the ``examples/prototype_mtc/notebooks`` folder and select a notebook to learn more: + + * `Getting started `__ + * `Summarizing results `__ + * `Testing a change in auto ownership `__ + * `Adding TNCs `__ + * `Memory usage `__ + +Hardware +-------- + +The computing hardware required to run a model implemented in the ActivitySim framework generally depends on: + +* The number of households to be simulated for disaggregate model steps +* The number of model zones (for each zone system) for aggregate model steps +* The number and size of network skims by mode and time-of-day +* The number of zone systems, see :ref:`multiple_zone_systems` +* The desired runtimes + +ActivitySim framework models use a significant amount of RAM since they store data in-memory to reduce +data access time in order to minimize runtime. For example, the prototype MTC example model has 2.7 million +households, 7.5 million people, 1475 zones, 826 network skims and has been run between one hour and one day depending +on the amount of RAM and number of processors allocated. See :ref:`multiprocessing` and :ref:`chunk_size` for more information. + +.. note:: + ActivitySim has been run in the cloud, on both Windows and Linux using + `Microsoft Azure `__. Example configurations, + scripts, and runtimes are in the ``other_resources\example_azure`` folder. + +.. _mkl_settings : + +MKL Settings +~~~~~~~~~~~~ + +Anaconda Python on Windows uses the `Intel Math Kernel Library `__ for +many of its computationally intensive low-level C/C++ calculations. By default, MKL threads many of its routines +in order to be performant out-of-the-box. However, for ActivitySim multiprocessing, which processes households in +parallel since they are largely independent of one another, it can be advantageous to override threading within +processes and instead let ActivitySim run each process with one computing core or thread. In order to do so, +override the MKL number of threads setting via a system environment variable that is set before running the model. +In practice, this means before running the model, first set the MKL number of threads variable via the command +line as follows: ``SET MKL_NUM_THREADS=1`` diff --git a/v1.3.0/_sources/howitworks.rst.txt b/v1.3.0/_sources/howitworks.rst.txt new file mode 100644 index 000000000..00102fa7e --- /dev/null +++ b/v1.3.0/_sources/howitworks.rst.txt @@ -0,0 +1,260 @@ + +How the System Works +==================== + +This page describes how the software works, how multiprocessing works, and the primary example model data schema. The code snippets below may not exactly match the latest version of the software, but they are close enough to illustrate how the system works. + +.. _how_the_system_works: + +Execution Flow +-------------- + +An example model run starts by running the steps in :ref:`example_run`. The following flow chart represents steps of ActivitySim, but specific implementations will have different individual model components in their execution. + +.. image:: images/example_flowchart.png + +Initialization +~~~~~~~~~~~~~~ + +The first significant step of the ``run`` command is: + +:: + + from activitysim import abm + +which loads :mod:`activitysim.abm.__init__`, which calls: + +:: + + import misc + import tables + import models + +which then loads the misc, tables, and models class definitions. Loading :mod:`activitysim.abm.misc` calls: + +:: + + from activitysim.core import config + from activitysim.core import inject + +which loads the config and inject classes. These define Inject injectables (functions) and +helper functions for running models. For example, the Python decorator ``@inject.injectable`` overrides the function definition ``settings`` to +execute this function whenever the ``settings`` object is called by the system. The :mod:`activitysim.core.inject` manages the data +pipeline. + +:: + + @inject.injectable(cache=True) + def settings(): + settings_dict = read_settings_file('settings.yaml', mandatory=True) + return settings_dict + +Next, the tables module executes the following import statements in :mod:`activitysim.abm.tables.__init__` to +define the dynamic inject tables (households, persons, skims, etc.), but does not load them. It also defines the +core dynamic injectables (functions) defined in the classes. The Python decorator ``@inject.table`` override the function +definitions so the name of the function becomes the name of the table when dynamically called by the system. + +:: + + from . import households + from . import persons + #etc... + + #then in households.py + @inject.table() + def households(households_sample_size, override_hh_ids, trace_hh_id): + +The models module then loads all the sub-models, which are registered as model steps with +the ``@inject.step()`` decorator. These steps will eventually be run by the data pipeliner. + +:: + + from . import accessibility + from . import atwork_subtour_destination + from . import atwork_subtour_frequency + #etc... + + #then in accessibility.py + @inject.step() + def compute_accessibility(accessibility, network_los, land_use, trace_od): + +Back in the main ``run`` command, the next steps are to load the tracing, configuration, setting, and pipeline classes +to get the system management components up and running. + +:: + + from activitysim.core import tracing + from activitysim.core import config + from activitysim.core import pipeline + + +The next step in the example is to define the ``run`` method, call it if the script is being run as the program entry point, and handle the +arguments passed in via the command line. + +:: + + def run(): + #etc... + + if __name__ == '__main__': + run() + + +.. note:: + For more information on run options, type ``activitysim run -h`` on the command line + + +The first key thing that happens in the ``run`` function is ``resume_after = setting('resume_after', None)``, which causes the system +to go looking for ``setting``. Earlier we saw that ``setting`` was defined as an injectable and so the system gets this object if it +is already in memory, or if not, calls this function which loads the ``config/settings.yaml`` file. This is called lazy loading or +on-demand loading. Next, the system loads the models list and starts the pipeline: + +:: + + pipeline.run(models=setting('models'), resume_after=resume_after) + +The :func:`activitysim.core.pipeline.run` method loops through the list of models, calls ``inject.run([step_name])``, +and manages the data pipeline. The first disaggregate data processing step (or model) run is ``initialize_households``, defined in +:mod:`activitysim.abm.models.initialize`. The ``initialize_households`` step is responsible for requesting reading of the raw +households and persons into memory. + +Initialize Households +~~~~~~~~~~~~~~~~~~~~~ + +The initialize households step/model is run via: + +:: + + @inject.step() + def initialize_households(): + + trace_label = 'initialize_households' + model_settings = config.read_model_settings('initialize_households.yaml', mandatory=True) + annotate_tables(model_settings, trace_label) + +This step reads the ``initialize_households.yaml`` config file, which defines the :ref:`table_annotation` below. Each table +annotation applies the expressions specified in the annotate spec to the relevant table. For example, the ``persons`` table +is annotated with the results of the expressions in ``annotate_persons.csv``. If the table is not already in memory, then +inject goes looking for it as explained below. + +:: + + #initialize_households.yaml + annotate_tables: + - tablename: persons + annotate: + SPEC: annotate_persons + DF: persons + TABLES: + - households + - tablename: households + column_map: + PERSONS: hhsize + workers: num_workers + annotate: + SPEC: annotate_households + DF: households + TABLES: + - persons + - land_use + - tablename: persons + annotate: + SPEC: annotate_persons_after_hh + DF: persons + TABLES: + - households + + #initialize.py + def annotate_tables(model_settings, trace_label): + + annotate_tables = model_settings.get('annotate_tables', []) + + for table_info in annotate_tables: + + tablename = table_info['tablename'] + df = inject.get_table(tablename).to_frame() + + # - annotate + annotate = table_info.get('annotate', None) + if annotate: + logger.info("annotated %s SPEC %s" % (tablename, annotate['SPEC'],)) + expressions.assign_columns( + df=df, + model_settings=annotate, + trace_label=trace_label) + + # - write table to pipeline + pipeline.replace_table(tablename, df) + + +Remember that the ``persons`` table was previously registered as an injectable table when the persons table class was +imported. Now that the ``persons`` table is needed, inject calls this function, which requires the ``households`` and +``trace_hh_id`` objects as well. Since ``households`` has yet to be loaded, the system run the households inject table operation +as well. The various calls also setup logging, tracing, stable random number management, etc. + +:: + + #persons in persons.py requires households, trace_hh_id + @inject.table() + def persons(households, trace_hh_id): + + df = read_raw_persons(households) + + logger.info("loaded persons %s" % (df.shape,)) + + df.index.name = 'person_id' + + # replace table function with dataframe + inject.add_table('persons', df) + + pipeline.get_rn_generator().add_channel('persons', df) + + if trace_hh_id: + tracing.register_traceable_table('persons', df) + whale.trace_df(df, "raw.persons", warn_if_empty=True) + + return df + + #households requires households_sample_size, override_hh_ids, trace_hh_id + @inject.table() + def households(households_sample_size, override_hh_ids, trace_hh_id): + + df_full = read_input_table("households") + + +The process continues until all the dependencies are resolved. It is the ``read_input_table`` function that +actually reads the input tables from the input HDF5 or CSV file using the ``input_table_list`` found in ``settings.yaml`` + +:: + + input_table_list: + - tablename: households + filename: households.csv + index_col: household_id + column_map: + HHID: household_id + + +Running Model Components +~~~~~~~~~~~~~~~~~~~~~~~~ + +The next steps include running the model components specific to the individual implementation that you are running and as specified in the ``settings.yaml`` file. + +Finishing Up +~~~~~~~~~~~~ + +The last models to be run by the data pipeline are: + +* ``write_data_dictionary``, which writes the table_name, number of rows, number of columns, and number of bytes for each checkpointed table +* ``track_skim_usage``, which tracks skim data memory usage +* ``write_tables``, which writes pipeline tables as CSV files as specified by the output_tables setting + +Back in the main ``run`` command, the final steps are to: + +* close the data pipeline (and attached HDF5 file) + + +Components +---------- + +Individual models and components are defined and described in the Developers Guide. Please refer to the :ref:`Components` section. diff --git a/v1.3.0/_sources/index.rst.txt b/v1.3.0/_sources/index.rst.txt new file mode 100644 index 000000000..421d776e7 --- /dev/null +++ b/v1.3.0/_sources/index.rst.txt @@ -0,0 +1,43 @@ +=========== +ActivitySim +=========== + +The mission of the ActivitySim project is to create and maintain advanced, open-source, +activity-based travel behavior modeling software based on best software development +practices for distribution at no charge to the public. + +The ActivitySim project is led by a consortium of Metropolitan Planning Organizations +(MPOs) and other transportation planning agencies, which provides technical direction +and resources to support project development. New member agencies are welcome to join +the consortium. All member agencies help make decisions about development priorities +and benefit from contributions of other agency partners. Additional information about +the development and management of the ActivitySim is on the `project site `__. + +.. grid:: 2 + + .. grid-item-card:: + + :fa:`book` |nbsp| |nbsp| :ref:`User's Guide ` + + ^^^ + + Start here to learn about using ActivitySim, including how to install, + the software, and how to configure and run models. + + .. grid-item-card:: + + :fa:`terminal` |nbsp| |nbsp| :ref:`Developer's Guide ` + + ^^^ + + Start here to learn about developing ActivitySim, including creating + model components, or changing the codebase. + +.. toctree:: + :hidden: + + users-guide/index + dev-guide/index + +.. |nbsp| unicode:: 0xA0 + :trim: diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.DigitalEncoding.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.DigitalEncoding.rst.txt new file mode 100644 index 000000000..01a2d7918 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.DigitalEncoding.rst.txt @@ -0,0 +1,6 @@ +DigitalEncoding +=============== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: DigitalEncoding \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.FileSystem.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.FileSystem.rst.txt new file mode 100644 index 000000000..d11d851d2 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.FileSystem.rst.txt @@ -0,0 +1,6 @@ +FileSystem +========== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: FileSystem \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.InputTable.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.InputTable.rst.txt new file mode 100644 index 000000000..46e0e866d --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.InputTable.rst.txt @@ -0,0 +1,6 @@ +InputTable +========== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: InputTable \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStep.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStep.rst.txt new file mode 100644 index 000000000..f0f2e3fcc --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStep.rst.txt @@ -0,0 +1,6 @@ +MultiprocessStep +================ + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: MultiprocessStep \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStepSlice.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStepSlice.rst.txt new file mode 100644 index 000000000..7779a42de --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.MultiprocessStepSlice.rst.txt @@ -0,0 +1,6 @@ +MultiprocessStepSlice +===================== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: MultiprocessStepSlice \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.NetworkSettings.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.NetworkSettings.rst.txt new file mode 100644 index 000000000..5120e12c7 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.NetworkSettings.rst.txt @@ -0,0 +1,6 @@ +NetworkSettings +=============== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: NetworkSettings \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTable.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTable.rst.txt new file mode 100644 index 000000000..0effe3c15 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTable.rst.txt @@ -0,0 +1,6 @@ +OutputTable +=========== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: OutputTable \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTables.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTables.rst.txt new file mode 100644 index 000000000..e890859dc --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.OutputTables.rst.txt @@ -0,0 +1,6 @@ +OutputTables +============ + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: OutputTables \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.Settings.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.Settings.rst.txt new file mode 100644 index 000000000..a99e6c62b --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.Settings.rst.txt @@ -0,0 +1,6 @@ +Settings +======== + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: Settings \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.TAZ_Settings.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.TAZ_Settings.rst.txt new file mode 100644 index 000000000..1e0250539 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.core.configuration.TAZ_Settings.rst.txt @@ -0,0 +1,6 @@ +TAZ\_Settings +============= + +.. currentmodule:: activitysim.core.configuration + +.. autopydantic_model:: TAZ_Settings \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.default_cache_dir.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.default_cache_dir.rst.txt new file mode 100644 index 000000000..90bba8ed2 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.default_cache_dir.rst.txt @@ -0,0 +1,6 @@ +default\_cache\_dir +=================== + +.. currentmodule:: activitysim.examples.external + +.. autofunction:: default_cache_dir \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.download_external_example.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.download_external_example.rst.txt new file mode 100644 index 000000000..d9ad39dd1 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.download_external_example.rst.txt @@ -0,0 +1,6 @@ +download\_external\_example +=========================== + +.. currentmodule:: activitysim.examples.external + +.. autofunction:: download_external_example \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.exercise_external_example.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.exercise_external_example.rst.txt new file mode 100644 index 000000000..c4560dc6a --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.exercise_external_example.rst.txt @@ -0,0 +1,6 @@ +exercise\_external\_example +=========================== + +.. currentmodule:: activitysim.examples.external + +.. autofunction:: exercise_external_example \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.list_registered_examples.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.list_registered_examples.rst.txt new file mode 100644 index 000000000..e1ab09b6a --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.list_registered_examples.rst.txt @@ -0,0 +1,6 @@ +list\_registered\_examples +========================== + +.. currentmodule:: activitysim.examples.external + +.. autofunction:: list_registered_examples \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.registered_external_example.rst.txt b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.registered_external_example.rst.txt new file mode 100644 index 000000000..b6e8eac99 --- /dev/null +++ b/v1.3.0/_sources/users-guide/_generated/activitysim.examples.external.registered_external_example.rst.txt @@ -0,0 +1,6 @@ +registered\_external\_example +============================= + +.. currentmodule:: activitysim.examples.external + +.. autofunction:: registered_external_example \ No newline at end of file diff --git a/v1.3.0/_sources/users-guide/cli-tools.rst.txt b/v1.3.0/_sources/users-guide/cli-tools.rst.txt new file mode 100644 index 000000000..84feb4070 --- /dev/null +++ b/v1.3.0/_sources/users-guide/cli-tools.rst.txt @@ -0,0 +1,31 @@ +================== +Command Line Tools +================== + + +activitysim run +--------------- + +.. argparse:: + :module: activitysim.cli.main + :func: parser + :prog: activitysim + :path: run + + +activitysim create +------------------ + +.. argparse:: + :module: activitysim.cli.main + :func: parser + :prog: activitysim + :path: create + + -d --destination : @replace + Path to new project directory. If this directory already exists, the + newly created example will be copied to a subdirectory within the + existing directory, and named according to the example name. Otherwise, + a new directory is created with this name and the newly created example + will be copied directly into it. + diff --git a/v1.3.0/_sources/users-guide/configuration.rst.txt b/v1.3.0/_sources/users-guide/configuration.rst.txt new file mode 100644 index 000000000..9c1557908 --- /dev/null +++ b/v1.3.0/_sources/users-guide/configuration.rst.txt @@ -0,0 +1,53 @@ + +.. index:: configuration +.. _configuration: + +============= +Configuration +============= + +The ``configs`` folder for a model implementation contains settings, expressions +files, and other files required for specifying model utilities and form. Each +component will have one or more files that control the operation of that +component. + +.. currentmodule:: activitysim.core.configuration + +Top Level Settings +------------------ + +.. autosummary:: + :toctree: _generated + :template: autopydantic.rst + :recursive: + + Settings + InputTable + OutputTable + OutputTables + MultiprocessStep + MultiprocessStepSlice + + +File System +----------- + +.. autosummary:: + :toctree: _generated + :template: autopydantic.rst + :recursive: + + FileSystem + + +Network Level of Service +------------------------ + +.. autosummary:: + :toctree: _generated + :template: autopydantic.rst + :recursive: + + NetworkSettings + TAZ_Settings + DigitalEncoding diff --git a/v1.3.0/_sources/users-guide/example_models.rst.txt b/v1.3.0/_sources/users-guide/example_models.rst.txt new file mode 100644 index 000000000..fbb727f62 --- /dev/null +++ b/v1.3.0/_sources/users-guide/example_models.rst.txt @@ -0,0 +1,3254 @@ + +.. index:: tutorial +.. index:: example +.. _example : +.. _examples : + +Example Models +============== + +The ActivitySim consortium maintains two supported "canonical" example +implementations: + +- the `SANDAG Model `__ is a two-zone + model based on the SANDAG ABM3 model, and +- the `MTC Model `__ is a + one-zone model based on the MTC's Travel Model One. + +Each example implementation includes a complete set of model components, input data, +and configuration files, and is intended to serve as a reference for users to build +their own models. They are provided as stand-alone repositories, to highlight the +fact that model implementations are separate from the ActivitySim core codebase, +and to make it easier for users to fork and modify the examples for their own use +without needing to modify the ActivitySim core codebase. The examples are maintained +by the ActivitySim Consortium and are kept up-to-date with the latest version of +ActivitySim. + +.. note: + + The two example models are not identical to the original agency models from which + they were created. They are generally similar to those models, and have been calibrated + and validated to reproduce reasonable results. They are intended to demonstrate the + capabilities of ActivitySim and to provide a starting point for users to build their own + models. However, they are not intended to be used as-is for policy analysis or forecasting. + +A discussion of the runtime performance of the example models is available in the +:ref:`example performance benchmarking ` section. + +This page describes the structure of the MTC example model in more detail. + +.. _prototype_mtc : + +prototype_mtc +------------- + +Introduction +~~~~~~~~~~~~ + +The initial example implemented in ActivitySim was prototype_mtc. This section described the prototype_mtc +model design, how to setup and run the example, and how to review outputs. The default configuration of the +example is limited to a small sample of households and zones so that it can be run quickly and require +less than 1 GB of RAM. The full scale example can be configured and run as well. + +Model Design +~~~~~~~~~~~~ + +Overview +________ + +The prototype_mtc example is based on (but has evolved away from) the +`Bay Area Metro Travel Model One `__ (TM1). +TM1 has its roots in a wide array of analytical approaches, including discrete +choice forms (multinomial and nested logit models), activity duration models, time-use models, +models of individual micro-simulation with constraints, entropy-maximization models, etc. +These tools are combined in the model design to realistically represent travel behavior, +adequately replicate observed activity-travel patterns, and ensure model sensitivity to +infrastructure and policies. The model is implemented in a micro-simulation framework. Microsimulation +methods capture aggregate outcomes through the representation of the behavior of +individual decision-makers. + +Zone System +___________ + +The prototype MTC model uses the 1454 TAZ zone system developed for the MTC trip-based model. The zones are fairly large for the region, +which may somewhat distort the representation of transit access in mode choice. To ameliorate this problem, the +original model zones were further sub-divided into three categories of transit access: short walk, long walk, and not +walkable. However, support for transit subzones is not included in the activitysim implementation since the latest generation +of activity-based models typically use an improved approach to spatial representation called multiple zone systems. See +:ref:`multiple_zone_systems` for more information. + +Decision-making units +_____________________ + +Decision-makers in the model system are households and persons. These decision-makers are +created for each simulation year based on a population synthesis process such as +`PopulationSim `__. The decision-makers are used in the +subsequent discrete-choice models to select a single alternative from a list of available +alternatives according to a probability distribution. The probability distribution is generated +from various logit-form models which take into account the attributes of the decision-maker and +the attributes of the various alternatives. The decision-making unit is an important element of +model estimation and implementation, and is explicitly identified for each model. + +Person type segmentation +________________________ + +TM1 is implemented in a micro-simulation framework. A key advantage of the +micro-simulation approach is that there are essentially no computational constraints on the +number of explanatory variables which can be included in a model specification. However, even +with this flexibility, the model system includes some segmentation of decision-makers. +Segmentation is a useful tool both to structure models and also as a way to characterize person +roles within a household. + +The person types shown below are used for the example model. The person types are mutually exclusive +with respect to age, work status, and school status. + ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| Person Type Code | Person Type | Age | Work Status | School Status | ++==================+===========================================================+=========+==================+===============+ +| 1 | Full-time worker (30+ hours a week) | 18+ | Full-time | None | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 2 | Part-time worker (<30 hours but works on a regular basis) | 18+ | Part-time | None | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 3 | College student | 18+ | Any | College | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 4 | Non-working adult | 18 - 64 | Unemployed | None | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 5 | Retired person | 65+ | Unemployed | None | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 6 | Driving age student | 16 - 17 | Any | Pre-college | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 7 | Non-driving student | 6 - 16 | None | Pre-college | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ +| 8 | Pre-school child | 0 - 5 | None | Preschool | ++------------------+-----------------------------------------------------------+---------+------------------+---------------+ + +Household type segments are useful for pre-defining certain data items (such as destination +choice size terms) so that these data items can be pre-calculated for each segment. Precalculation +of these data items reduces model complexity and runtime. The segmentation is based on household income, +and includes four segments - low, medium, high, very high. + +In the model, the persons in each household are assigned a simulated but fixed value of time +that modulates the relative weight the decision-maker places on time and cost. The probability +distribution from which the value of time is sampled was derived from a toll choice model +estimated using data from a stated preference survey performed for the SFCTA Mobility, Access, and +Pricing Study, and is a lognormal distribution with a mean that varies by income segment. + +Activity type segmentation +__________________________ + +The activity types are used in most model system components, from developing daily activity patterns +and to predicting tour and trip destinations and modes by purpose. The set of activity types is shown below. +The activity types are also grouped according to whether the activity is mandatory or non-mandatory and +eligibility requirements are assigned determining which person-types can be used for generating each +activity type. The classification scheme of each activity type reflects the relative importance or +natural hierarchy of the activity, where work and school activities are typically the most inflexible +in terms of generation, scheduling and location, and discretionary activities are typically the most +flexible on each of these dimensions. Each out-of-home location that a person travels to in the +simulation is assigned one of these activity types. + ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Purpose | Description | Classification| Eligibility | ++=====================+==========================================================================+===============+=======================================+ +| Work | Working at regular workplace or work-related activities outside the home | Mandatory | Workers and students | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| University | College or university | Mandatory | Age 18+ | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| High School | Grades 9-12 | Mandatory | Age 14-17 | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Grade School | Grades preschool, K-8 | Mandatory | Age 0-13 | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Escorting | Pick-up/drop-off passengers (auto trips only) | NonMandatory | Age 16+ | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Shopping | Shopping away from home | NonMandatory | Age 5+ (if joint travel, all persons) | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Other Maintenance | Personal business/services and medical appointments | NonMandatory | Age 5+ (if joint travel, all persons) | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Social/Recreational | Recreation, visiting friends/family | NonMandatory | Age 5+ (if joint travel, all persons) | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Eat Out | Eating outside of home | NonMandatory | Age 5+ (if joint travel, all persons) | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ +| Other Discretionary | Volunteer work, religious activities | NonMandatory | Age 5+ (if joint travel, all persons) | ++---------------------+--------------------------------------------------------------------------+---------------+---------------------------------------+ + +Treatment of time +_________________ + +The TM1 example model system functions at a temporal resolution of one hour. These one hour increments +begin with 3 AM and end with 3 AM the next day. Temporal integrity is ensured so that no +activities are scheduled with conflicting time windows, with the exception of short +activities/tours that are completed within a one hour increment. For example, a person may have +a short tour that begins and ends within the 8 AM to 9 AM period, as well as a second longer tour +that begins within this time period, but ends later in the day. + +A critical aspect of the model system is the relationship between the temporal resolution used for +scheduling activities and the temporal resolution of the network assignment periods. Although +each activity generated by the model system is identified with a start time and end time in one hour +increments, LOS matrices are only created for five aggregate time periods. The trips occurring in each time period +reference the appropriate transport network depending on their trip mode and the mid-point trip +time. The definition of time periods for LOS matrices is given below. + ++---------------+------------+ +| Time Period | Start Hour | ++===============+============+ +| EA | 3 | ++---------------+------------+ +| AM | 5 | ++---------------+------------+ +| MD | 9 | ++---------------+------------+ +| PM | 14 | ++---------------+------------+ +| EV | 18 | ++---------------+------------+ + +Trip modes +__________ + +The trip modes defined in the example model are below. The modes include auto by +occupancy and toll/non-toll choice, walk and bike, walk and drive access to five different +transit line-haul modes, and ride hail with taxi, single TNC (Transportation Network Company), and shared TNC. + + * Auto + + * SOV Free + * SOV Pay + * 2 Person Free + * 2 Person Pay + * 3+ Person Free + * 3+ Person Pay + + * Nonmotorized + + * Walk + * Bike + + * Transit + + * Walk + + * Walk to Local Bus + * Walk to Light-Rail Transit + * Walk to Express Bus + * Walk to Bus Rapid Transit + * Walk to Heavy Rail + + * Drive + + * Drive to Local Bus + * Drive to Light-Rail Transit + * Drive to Express Bus + * Drive to Bus Rapid Transit + * Drive to Heavy Rail + + * Ride Hail + + * Taxi + * Single TNC + * Shared TNC + +Sub-models +__________ + +The general design of the prototype_mtc model is presented below. Long-term choices that relate to +the usual workplace/university/school for each worker and student, household car ownership, and the +availability of free parking at workplaces are first. + +The coordinated daily activity pattern type of each household member is the first travel-related +sub-model in the hierarchy. This model classifies daily patterns by three types: + + * Mandatory, which includes at least one out-of-home mandatory activity (work or school) + * Non-mandatory, which includes at least one out-of-home non-mandatory activity, but does not include out-of-home mandatory activities + * Home, which does not include any out-of-home activity or travel + +The pattern type sub-model leaves open the frequency of tours for mandatory and nonmandatory +purposes since these sub-models are applied later in the model sequence. Daily +pattern-type choices of the household members are linked in such a way that decisions made by +members are reflected in the decisions made by the other members. + +After the frequency and time-of-day for work and school tours are determined, the +next major model component relates to joint household travel. This component produces a +number of joint tours by travel purpose for the entire household, travel party composition +in terms of adults and children, and then defines the participation of each household +member in each joint household tour. It is followed by choice of destination and time-of-day. + +The next stage relates to maintenance and discretionary tours that are modeled at the individual +person level. The models include tour frequency, choice of destination and time +of day. Next, a set of sub-models relate tour-level details on mode, exact number of +intermediate stops on each half-tour and stop location. It is followed by the last set of +sub-models that add details for each trip including trip departure time, trip mode details and parking +location for auto trips. + +.. image:: images/abmexample.jpg + +The output of the model is a disggregate table of trips with individual attributes for custom analysis. The trips +can be aggregated into travel demand matrices for network loading. + +Setup +~~~~~ + +The following describes the prototype_mtc model setup. + + +Folder and File Setup + +The prototype_mtc has the following root folder/file setup: + + * configs - settings, expressions files, etc. + * configs_mp - override settings for the multiprocess configuration + * data - input data such as land use, synthetic population files, and network LOS / skims + * output - outputs folder + +Inputs +______ + +In order to run prototype_mtc, you first need the input files in the ``data`` folder as identified in the ``configs\settings.yaml`` file and the ``configs\network_los.yaml`` file: + +* input_table_list: the input CSV tables for MTC (see below for column definitions): + + * households - Synthetic population household records for a subset of zones. + * persons - Synthetic population person records for a subset of zones. + * land_use - Zone-based land use data (population and employment for example) for a subset of zones. + +* taz_skims: skims.omx - an OMX matrix file containing the MTC TM1 skim matrices for a subset of zones. The time period for the matrix must be represented at the end of the matrix name and be seperated by a double_underscore (e.g. BUS_IVT__AM indicates base skim BUS_IVT with a time period of AM). + +These files are used in the tests as well. The full set +of MTC households, persons, and OMX skims are on the ActivitySim `resources repository `__. + + + +Additional details on these files is available in the original `Travel Model 1 repository `_, +although many of the files described there are not used in ActivitySim. + +Data Schema ++++++++++++ + +The following table lists the pipeline data tables, field names, the data types and other details associated with each table in the model: + + ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| Table | Field | DType | Creator |NCol |NRow | ++============================+===============================+=========+==============================+======+======+ +| accessibility | auPkRetail | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | auPkTotal | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | auOpRetail | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | auOpTotal | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | trPkRetail | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | trPkTotal | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | trOpRetail | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | trOpTotal | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | nmRetail | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| accessibility | nmTotal | float32 | compute_accessibility | 10 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | TAZ | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | SERIALNO | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | PUMA5 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | income | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hhsize | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | HHT | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | UNITTYPE | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | NOC | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | BLDGSZ | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | TENURE | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | VEHICL | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hinccat1 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hinccat2 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hhagecat | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hsizecat | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hfamily | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hunittype | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hNOCcat | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hwrkrcat | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h0004 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h0511 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h1215 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h1617 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h1824 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h2534 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h3549 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h5064 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h6579 | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | h80up | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_workers | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hwork_f | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hwork_p | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | huniv | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hnwork | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hretire | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hpresch | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hschpred | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hschdriv | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | htypdwel | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hownrent | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hadnwst | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hadwpst | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hadkids | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | bucketBin | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | originalPUMA | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hmultiunit | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | chunk_id | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | income_in_thousands | float64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | income_segment | int32 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | median_value_of_time | float64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hh_value_of_time | float64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_non_workers | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_drivers | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_adults | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_children | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_young_children | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_children_5_to_15 | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_children_16_to_17 | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_college_age | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_young_adults | int8 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | non_family | bool | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | family | bool | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | home_is_urban | bool | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | home_is_rural | bool | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | auto_ownership | int64 | initialize_households | 65 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | hh_work_auto_savings_ratio | float32 | workplace_location | 66 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_under16_not_at_school | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_travel_active | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_travel_active_adults | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_travel_active_preschoolers| int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_travel_active_children | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households |num_travel_active_non_presch | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | participates_in_jtf_model | int8 | cdap_simulate | 73 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | joint_tour_frequency | object | joint_tour_frequency | 75 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| households | num_hh_joint_tours | int8 | joint_tour_frequency | 75 | 100 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| joint_tour_participants | tour_id | int64 | joint_tour_participation | 4 | 13 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| joint_tour_participants | household_id | int64 | joint_tour_participation | 4 | 13 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| joint_tour_participants | person_id | int64 | joint_tour_participation | 4 | 13 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| joint_tour_participants | participant_num | int64 | joint_tour_participation | 4 | 13 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | DISTRICT | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | SD | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | county_id | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TOTHH | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HHPOP | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TOTPOP | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | EMPRES | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | SFDU | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | MFDU | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HHINCQ1 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HHINCQ2 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HHINCQ3 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HHINCQ4 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TOTACRE | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | RESACRE | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | CIACRE | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | SHPOP62P | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TOTEMP | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGE0004 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGE0519 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGE2044 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGE4564 | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGE65P | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | RETEMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | FPSEMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HEREMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | OTHEMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | AGREMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | MWTEMPN | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | PRKCST | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | OPRKCST | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | area_type | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | HSENROLL | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | COLLFTE | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | COLLPTE | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TOPOLOGY | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | TERMINAL | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | ZERO | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | hhlds | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | sftaz | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | gqpop | int64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | household_density | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | employment_density | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| land_use | density_index | float64 | initialize_landuse | 44 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 4 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 5 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 6 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 7 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 8 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 9 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 10 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 11 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 12 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 13 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 14 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 15 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 16 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 17 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 18 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 19 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 20 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 21 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 22 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 23 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| person_windows | 24 | int8 | initialize_households | 21 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | household_id | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | age | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | RELATE | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | ESR | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | GRADE | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | PNUM | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | PAUG | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | DDP | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | sex | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | WEEKS | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | HOURS | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | MSP | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | POVERTY | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | EARNS | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | pagecat | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | pemploy | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | pstudent | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | ptype | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | padkid | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | age_16_to_19 | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | age_16_p | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | adult | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | male | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | female | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_non_worker | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_retiree | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_preschool_kid | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_driving_kid | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_school_kid | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_full_time | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_part_time | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_university | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | student_is_employed | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | nonstudent_to_school | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | is_student | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | is_gradeschool | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | is_highschool | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | is_university | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | school_segment | int8 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | is_worker | bool | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | home_taz | int64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | value_of_time | float64 | initialize_households | 42 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | school_taz | int32 | school_location | 45 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | distance_to_school | float32 | school_location | 45 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | roundtrip_auto_time_to_school | float32 | school_location | 45 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | workplace_taz | int32 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | distance_to_work | float32 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | workplace_in_cbd | bool | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | work_zone_area_type | float64 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | roundtrip_auto_time_to_work | float32 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | work_auto_savings | float32 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | work_auto_savings_ratio | float32 | workplace_location | 52 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | free_parking_at_work | bool | free_parking | 53 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | cdap_activity | object | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | cdap_rank | int64 | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | travel_active | bool | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | under16_not_at_school | bool | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_preschool_kid_at_home | bool | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | has_school_kid_at_home | bool | cdap_simulate | 59 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | mandatory_tour_frequency | object | mandatory_tour_frequency | 64 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | work_and_school_and_worker | bool | mandatory_tour_frequency | 64 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | work_and_school_and_student | bool | mandatory_tour_frequency | 64 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_mand | int8 | mandatory_tour_frequency | 64 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_work_tours | int8 | mandatory_tour_frequency | 64 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_joint_tours | int8 | joint_tour_participation | 65 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | non_mandatory_tour_frequency | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_non_mand | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_escort_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_eatout_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_shop_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_maint_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_discr_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_social_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| persons | num_non_escort_tours | int8 | non_mandatory_tour_frequency | 74 | 271 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_destination_size | gradeschool | float64 | initialize_households | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_destination_size | highschool | float64 | initialize_households | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_destination_size | university | float64 | initialize_households | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_modeled_size | gradeschool | int32 | school_location | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_modeled_size | highschool | int32 | school_location | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| school_modeled_size | university | int32 | school_location | 3 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | person_id | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_type | object | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_type_count | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_type_num | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_num | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_count | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_category | object | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | number_of_participants | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | destination | int32 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | origin | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | household_id | int64 | mandatory_tour_frequency | 11 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | start | int8 | mandatory_tour_scheduling | 15 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | end | int8 | mandatory_tour_scheduling | 15 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | duration | int8 | mandatory_tour_scheduling | 15 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tdd | int64 | mandatory_tour_scheduling | 15 | 153 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | composition | object | joint_tour_composition | 16 | 159 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | tour_mode | object | tour_mode_choice_simulate | 17 | 319 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | atwork_subtour_frequency | object | atwork_subtour_frequency | 19 | 344 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | parent_tour_id | float64 | atwork_subtour_frequency | 19 | 344 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | stop_frequency | object | stop_frequency | 21 | 344 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| tours | primary_purpose | object | stop_frequency | 21 | 344 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | person_id | int64 | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | household_id | int64 | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | tour_id | int64 | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | primary_purpose | object | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | trip_num | int64 | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | outbound | bool | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | trip_count | int64 | stop_frequency | 7 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | purpose | object | trip_purpose | 8 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | destination | int32 | trip_destination | 11 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | origin | int32 | trip_destination | 11 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | failed | bool | trip_destination | 11 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | depart | float64 | trip_scheduling | 11 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| trips | trip_mode | object | trip_mode_choice | 12 | 859 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_destination_size | work_high | float64 | initialize_households | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_destination_size | work_low | float64 | initialize_households | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_destination_size | work_med | float64 | initialize_households | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_destination_size | work_veryhigh | float64 | initialize_households | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_modeled_size | work_high | int32 | workplace_location | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_modeled_size | work_low | int32 | workplace_location | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_modeled_size | work_med | int32 | workplace_location | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ +| workplace_modeled_size | work_veryhigh | int32 | workplace_location | 4 | 1454 | ++----------------------------+-------------------------------+---------+------------------------------+------+------+ + + + + + +Households +++++++++++ + +The households table contains the following synthetic population columns: + +* household_id: numeric ID of this household, used in persons table to join with household characteristics +* TAZ: zone where this household lives +* income: Annual household income, in 2000 dollars +* hhsize: Household size +* HHT: Household type (see below) +* auto_ownership: number of cars owned by this household (0-6) +* num_workers: number of workers in the household +* sample_rate + +Household types +""""""""""""""" + +These are household types defined by the Census Bureau and used in `ACS table B11001 `_. + ++------+------------------------------------------+ +| Code | Description | ++======+==========================================+ +| 0 | None | ++------+------------------------------------------+ +| 1 | Married-couple family | ++------+------------------------------------------+ +| 2 | Male householder, no spouse present | ++------+------------------------------------------+ +| 3 | Female householder, no spouse present | ++------+------------------------------------------+ +| 4 | Nonfamily household, male alone | ++------+------------------------------------------+ +| 5 | Nonfamily household, male not alone | ++------+------------------------------------------+ +| 6 | Nonfamily household, female alone | ++------+------------------------------------------+ +| 7 | Nonfamily household, female not alone | ++------+------------------------------------------+ + + +Persons ++++++++ + +This table describes attributes of the persons that constitute each household. This file contains the following columns: + +* person_id: Unique integer identifier for each person. This value is globally unique, i.e. + no two individuals have the same person ID, even if they are in different households. +* household_id: Household identifier for this person, foreign key to households table +* age: Age in years +* PNUM: Person number in household, starting from 1. +* sex: Sex, 1 = Male, 2 = Female +* pemploy: Employment status (see below) +* pstudent: Student status (see below) +* ptype: Person type (see person type segmentation above) + +Employment status +""""""""""""""""" + ++------+------------------------------------------+ +| Code | Description | ++======+==========================================+ +| 1 | Full-time worker | ++------+------------------------------------------+ +| 2 | Part-time worker | ++------+------------------------------------------+ +| 3 | Not in labor force | ++------+------------------------------------------+ +| 4 | Student under 16 | ++------+------------------------------------------+ + +Student status +"""""""""""""" + ++------+------------------------------------------+ +| Code | Description | ++======+==========================================+ +| 1 | Preschool through Grade 12 student | ++------+------------------------------------------+ +| 2 | University/professional school student | ++------+------------------------------------------+ +| 3 | Not a student | ++------+------------------------------------------+ + +Land use +++++++++ + +All values are raw numbers and not proportions of the total. + +* TAZ: Zone which this row describes +* DISTRICT: Superdistrict where this TAZ is (34 superdistricts in the Bay Area) +* SD: Duplicate of DISTRICT +* COUNTY: County within the Bay Area (see below) +* TOTHH: Total households in TAZ +* TOTPOP: Total population in TAZ +* TOTACRE: Area of TAZ, acres +* RESACRE: Residential area of TAZ, acres +* CIACRE: Commercial/industrial area of TAZ, acres +* TOTEMP: Total employment +* AGE0519: Persons age 5 to 19 (inclusive) +* RETEMPN: NAICS-based total retail employment +* FPSEMPN: NAICS-based financial and professional services employment +* HEREMPN: NAICS-based health, education, and recreational service employment +* AGREMPN: NAICS-based agricultural and natural resources employment +* MWTEMPN: NAICS-based manufacturing and wholesale trade employment +* OTHEMP: NAICS-based other employment +* PRKCST: Hourly cost paid by long-term (8+ hours) parkers, year 2000 cents +* OPRKCST: Hourly cost paid by short term parkers, year 2000 cents +* area_type: Area type designation (see below) +* HSENROLL: High school students enrolled at schools in this TAZ +* COLLFTE: College students enrolled full-time at colleges in this TAZ +* COLLPTE: College students enrolled part-time at colleges in this TAZ +* TERMINAL: Average time to travel from automobile storage location to origin/destination (floating-point minutes) + +Counties +"""""""" + ++------+------------------------------------------+ +| Code | Name | ++======+==========================================+ +| 1 | San Francisco | ++------+------------------------------------------+ +| 2 | San Mateo | ++------+------------------------------------------+ +| 3 | Santa Clara | ++------+------------------------------------------+ +| 4 | Alameda | ++------+------------------------------------------+ +| 5 | Contra Costa | ++------+------------------------------------------+ +| 6 | Solano | ++------+------------------------------------------+ +| 7 | Napa | ++------+------------------------------------------+ +| 8 | Sonoma | ++------+------------------------------------------+ +| 9 | Marin | ++------+------------------------------------------+ + +Area types +"""""""""" + ++------+------------------------------------------+ +| Code | Description | ++======+==========================================+ +| 0 | Regional core | ++------+------------------------------------------+ +| 1 | Central business district | ++------+------------------------------------------+ +| 2 | Urban business | ++------+------------------------------------------+ +| 3 | Urban | ++------+------------------------------------------+ +| 4 | Suburban | ++------+------------------------------------------+ +| 5 | Rural | ++------+------------------------------------------+ + +.. note:: + + ActivitySim can optionally build an HDF5 file of the input CSV tables for use in subsequent runs since + HDF5 is binary and therefore results in faster read times. see :ref:`configuration` + + OMX and HDF5 files can be viewed with the `OMX Viewer `__ or + `HDFView `__. + + The ``other_resources\scripts\build_omx.py`` script will build one OMX file containing all the skims. The original MTC TM1 skims were converted for the prototype from + Cube to OMX using the ``other_resources\scripts\mtc_tm1_omx_export.s`` script. + + The prototype_mtc_sf inputs were created by the ``other_resources\scripts\create_sf_example.py`` script, which creates the land use, synthetic population, and + skim inputs for a subset of user-defined zones. + + +.. index:: skims +.. index:: omx_file +.. index:: skim matrices +.. _skims: + +Skims +_____ + +The injectables and omx_file for the example are listed below. +The skims are float64 matrix. + +Skims are named ___