v1.3.2

This bug fix release should fix problems with changing the location of the sharrow cache directory.

What's Changed

• Fix installer by @jpn-- in #887
• Bump actions/download-artifact from 3 to 4.1.7 in /.github/workflows by @dependabot in #888
• Sharrow Cache Dir Setting by @dhensle in #893

New Contributors

• @dependabot made their first contribution in #888

Full Changelog: v1.3.1...v1.3.2

v1.3.1

Version 1.3.1 fixes the list of installation dependencies, and is otherwise identical to 1.3.0.

ActivitySim version 1.3 brings some significant new features to the platform. Users may need to
make some small changes to configuration files to take full advantage of the version.

New Canonical Examples

Beginning with version 1.3, ActivitySim provides 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.

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:

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:

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:

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:

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.

Chunking

Version 1.3 introduces a new "explicit" 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):

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, for
vehicle type choice, non-mandatory tour frequency, school escorting, and
joint tour frequency in PR #804,
and all remaining interaction-simulate components in
PR #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
to False in the compute_settings
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
setting under compute_settings.
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:

compute_settings:
  protect_columns:
  - origin_destination

Code updates to drop unused columns are in
PR #833 and to protect
columns in PR #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
and PR #863

Alternatives preprocessors for trip destination.

Added alternatives preprocessor in
PR #865,
and converted to separate preprocessors for sample (at the TAZ level) and
simulate (at the MAZ level for 2 zone systems) in
PR #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:

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 value...

v1.3.0

ActivitySim version 1.3 brings some significant new features to the platform. Users may need to
make some small changes to configuration files to take full advantage of the version.

New Canonical Examples

Beginning with version 1.3, ActivitySim provides 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.

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:

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:

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:

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:

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.

Chunking

Version 1.3 introduces a new "explicit" 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):

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, for
vehicle type choice, non-mandatory tour frequency, school escorting, and
joint tour frequency in PR #804,
and all remaining interaction-simulate components in
PR #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
to False in the compute_settings
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
setting under compute_settings.
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:

compute_settings:
  protect_columns:
  - origin_destination

Code updates to drop unused columns are in
PR #833 and to protect
columns in PR #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
and PR #863

Alternatives preprocessors for trip destination.

Added alternatives preprocessor in
PR #865,
and converted to separate preprocessors for sample (at the TAZ level) and
simulate (at the MAZ level for 2 zone systems) in
PR #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:

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_C...

v1.3.0-beta0

This update offers numerous significant enhancements to how ActivitySim works, including:

• Removal of ORCA. 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 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. #654
• Pydantic for model settings. In prior versions, model settings were specifies as YAML input files and could contain arbitrary content, both for ActivitySim at a global level as well as for individual components. This update now uses Pydantic to validate settings. #758
• Input checker. This new component allows for configuring checks on the validity of data input files. #753
• Data Type Optimization. A variety of internal data type optimization changes in #782
• BayDAG Contributions in #657

Other smaller enhancements include:

• add model_settings to estimator.write_coefficients by @bwentl in #651
• docs: apply a minor correction to user guides by @asiripanich in #659
• Trip scheduling logic by @jpn-- in #660
• Pin Dependencies by @jpn-- in #665
• Updated SEMCOG Example by @dhensle in #603
• syncronize by @jpn-- in #680
• Fix memory usage by @jpn-- in #751
• orca residual cleanup by @jpn-- in #694
• Disable unstable estimation mode test by @jpn-- in #765
• Overflow protection by @jpn-- in #764
• Fixes windows error on large MAZ systems by @jpn-- in #760
• update repo test pointers by @jpn-- in #783
• Explicit chunking by @jpn-- in #759
• Selecting choices from joint tour participant ID column explicitly; by @bricegnichols in #653
• Option to write output tables as parquet files by @stefancoe in #763
• Moved 'tot_tours' from nm tour frequency script to alternatives file by @JoeJimFlood in #661
• Add options to handle larger dataset for location models by @bwentl in #687
• Pydantic 2 by @jpn-- in #796
• added stricter joining of annotated fields by @nick-fournier-rsg in #672
• Vehicle Type Alts Filtering Bug Fix by @dhensle in #790
• Alt col name bug fix for option to handle larger dataset for location models by @bwentl in #798

v1.2.2

There are no actual changes in this release. We are issuing a patch update because the prior 1.2.1 update was built in coda-forge but isn't there now.

v1.2.1

This release is being made to ensure that user installing the latest version of ActivitySim do so in an environment without Pandas 2.0, which is not yet compatible with ActivitySim.

What's Changed

• add scikit-learn to formal dependencies by @jpn-- in #639
• maintenance release by @jpn-- in #666

Full Changelog: v1.2.0...v1.2.1

v1.2.0

This 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
• Various other small enhancements and bug fixes

What's Changed

• Psutil memory info runtime error workaround by @i-am-sijia in #625
• Develop got out of sync with main by @jpn-- in #626
• Flexible Number of Tour & Trip IDs by @dhensle in #581
• Fixed random seed generator to generate unsigned integers instead of … by @JoeJimFlood in #577
• Fix for pandas 1.5 by @jpn-- in #629
• docs: correct the unit of chunk_size. by @jpn-- in #630
• Add github workflow for windows installer creation by @Chronial in #600
• Parking location bug fix by @i-am-sijia in #622
• Revised shadow pricing mechanism by @aletzdy in #613
• Operational updates by @jpn-- in #612
• Estimation fix by @jpn-- in #591
• [Phase 7] Complete Sharrow by @jpn-- in #611
• Adding fixed-origin to fixed-primary-destination skim wrapper by @dhensle in #606
• Composite - Disaggregate Accessibility by @jpn-- in #635
• School Escorting by @dhensle in #574
• Dev accessibilities by @nick-fournier-rsg in #614
• ARC Example Trip Destination UEC Correction by @i-am-sijia in #634
• code for 1.2 release by @jpn-- in #636

New Contributors

• @i-am-sijia made their first contribution in #625
• @dhensle made their first contribution in #581
• @JoeJimFlood made their first contribution in #577
• @Chronial made their first contribution in #600
• @aletzdy made their first contribution in #613
• @nick-fournier-rsg made their first contribution in #614

Full Changelog: v1.1.3...v1.2.0

v1.1.3

What's Changed

Almost nothing, just trying to make the documentation build work

Full Changelog: v1.1.2...v1.1.3

v1.1.2

What's Changed

This release is to apply and check fixes for the automated documentation build only.

• Release instructions by @jpn-- in #602

Full Changelog: v1.1.1...v1.1.2

v1.1.1

What's Changed

There are no changes to the main body of ActivitySim code in this release, just changes to the package release and delivery, and ancillary parts.

• Infrastructure by @jpn-- in #586
• Infrastructure fixes by @jpn-- in #588
• Adding small MWCOG example/prototype by @AndrewTheTM in #585
• Repair tests and examples by @jpn-- in #594
• Infrastructure changes by @jpn-- in #592

New Contributors

• @AndrewTheTM made their first contribution in #585

Full Changelog: v1.1.0...v1.1.1