Expression profiling (legacy mode)

[jpn--]

This pull request introduces a new performance profiling feature for expression evaluation in the ActivitySim framework. The feature allows developers to track and log the runtime of individual expressions, providing insights into potential bottlenecks in complex models. Key changes include the integration of a performance timer, updates to various core functions to support profiling, and new configuration settings for controlling profiling behavior.

Performance Profiling Feature

• Integration of Performance Timer:

  • Added the EvalTiming class to measure and log the execution time of expressions. The timer is initialized conditionally based on the new expression_profile setting. (activitysim/abm/models/summarize.py, activitysim/core/assign.py, activitysim/core/interaction_simulate.py, activitysim/core/simulate.py) [1] [2] [3] [4]

• Expression Timing Wrappers:

  • Wrapped key expression evaluations with performance_timer.time_expression to measure the execution time of individual expressions. (activitysim/core/assign.py, activitysim/core/interaction_simulate.py, activitysim/core/simulate.py) [1] [2] [3]

• Log Writing:

  • Added functionality to write performance logs to a file after the evaluation process is complete. (activitysim/abm/models/summarize.py, activitysim/core/assign.py, activitysim/core/interaction_simulate.py, activitysim/core/simulate.py) [1] [2] [3] [4]

Configuration Updates

• New Profiling Settings:

  • Introduced expression_profile and expression_profile_cutoff settings to enable/disable profiling globally or for specific components, and to filter out expressions based on runtime thresholds. (activitysim/core/configuration/top.py)

• Documentation for Profiling:

  • Added docstrings to explain the purpose and usage of the new profiling settings and performance log file. (activitysim/core/configuration/base.py, activitysim/core/configuration/top.py) [1] [2]

Core Function Enhancements

• Trace Label Support:

  • Extended several core functions to accept a trace_label parameter for more granular logging and profiling. (activitysim/core/simulate.py) [1] [2]

• Performance Reporting:

  • Added a summary report generation step to analyze and output the slowest expressions across all models. (activitysim/cli/run.py)

This enhancement is primarily aimed at developers and advanced users who need to optimize model performance. While it introduces some overhead during execution, it provides valuable insights for debugging and improving complex expressions.

[Copilot]

Pull Request Overview

This PR implements a new performance profiling feature that enables detailed tracking and logging of expression evaluation runtimes in ActivitySim.

• Integrated a performance timer via the EvalTiming class.
• Extended core functions to wrap expression evaluations with performance measurement.
• Added new configuration settings and documentation to support and explain expression profiling.

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/users-guide/performance/index.md	Added a link to the new Expression Profiling section.
docs/users-guide/performance/expr-profiling.md	Created documentation explaining expression profiling.
activitiesim/core/simulate.py	Integrated performance timing in expression evaluation.
activitiesim/core/interaction_simulate.py	Enabled profiling timer for interaction simulations.
activitiesim/core/expressions.py	Passed trace_label parameter to compute_columns.
activitiesim/core/configuration/top.py	Added new profiling settings and descriptive docstrings.
activitiesim/core/configuration/base.py	Added a performance_log configuration field.
activitiesim/core/assign.py	Wrapped several expression evaluations with profiling.
activitiesim/cli/run.py	Generated reporting on profiling summary data.
activitiesim/abm/models/summarize.py	Integrated performance timing in summarizing expressions.

Comments suppressed due to low confidence (1)

activitysim/core/assign.py:250

• The variable 'trace_label' is used to create the performance log filename but is not defined in the current scope. Consider updating the function signature to accept a 'trace_label' parameter or use an alternative identifier available in context.

if state.settings.expression_profile:

[jpn--]

Example outputs from the SANDAG test model:

• Component-level profile
• Subcomponent-level profile

Or: Linked here. Note: if you want to see the results, you'll need to click the first links, or download the HTML files, the content is rendered as embedded JavaScript and the OneDrive preview probably won't show anything.