polaris.runs.convergence.convergence_config.ConvergenceConfig#
- pydantic model polaris.runs.convergence.convergence_config.ConvergenceConfig#
Bases:
BaseModelConfiguration class for the POLARIS iterative convergence process
Show JSON schema
{ "title": "ConvergenceConfig", "description": "Configuration class for the POLARIS iterative convergence process", "type": "object", "properties": { "uuid": { "default": null, "title": "Uuid", "type": "string" }, "data_dir": { "default": ".", "format": "path", "title": "Data Dir", "type": "string" }, "backup_dir": { "anyOf": [ { "format": "path", "type": "string" }, { "type": "null" } ], "default": null, "title": "Backup Dir" }, "archive_dir": { "default": "archive", "format": "path", "title": "Archive Dir", "type": "string" }, "results_dir": { "default": null, "format": "path", "title": "Results Dir", "type": "string" }, "db_name": { "default": null, "title": "Db Name", "type": "string" }, "polaris_exe": { "anyOf": [ { "format": "path", "type": "string" }, { "type": "null" } ], "default": null, "title": "Polaris Exe" }, "cristal_exe": { "anyOf": [ { "format": "path", "type": "string" }, { "type": "null" } ], "default": null, "title": "Cristal Exe" }, "scenario_skim_file": { "default": "scenario_abm.json", "format": "path", "title": "Scenario Skim File", "type": "string" }, "scenario_main_init": { "default": "scenario_abm.json", "format": "path", "title": "Scenario Main Init", "type": "string" }, "scenario_main": { "default": "scenario_abm.json", "format": "path", "title": "Scenario Main", "type": "string" }, "async_inline": { "default": false, "title": "Async Inline", "type": "boolean" }, "num_threads": { "default": 48, "title": "Num Threads", "type": "integer" }, "num_abm_runs": { "default": 2, "title": "Num Abm Runs", "type": "integer" }, "num_dta_runs": { "default": 0, "title": "Num Dta Runs", "type": "integer" }, "num_outer_loops": { "default": 1, "title": "Num Outer Loops", "type": "integer" }, "start_iteration_from": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Start Iteration From" }, "num_retries": { "default": 1, "title": "Num Retries", "type": "integer" }, "use_numa": { "default": true, "title": "Use Numa", "type": "boolean" }, "do_skim": { "default": false, "title": "Do Skim", "type": "boolean" }, "do_cristal": { "default": false, "title": "Do Cristal", "type": "boolean" }, "hdt_external_sample_for_cristal": { "default": 0.25, "title": "Hdt External Sample For Cristal", "type": "number" }, "do_abm_init": { "default": false, "title": "Do Abm Init", "type": "boolean" }, "do_pop_synth": { "default": false, "title": "Do Pop Synth", "type": "boolean" }, "workplace_stabilization": { "$ref": "#/$defs/WorkplaceStabilizationConfig", "default": { "enabled": false, "schedule": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 31, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] } } }, "calibration": { "$ref": "#/$defs/CalibrationConfig", "default": { "enabled": false, "target_csv_dir": "calibration_targets", "calibration_schedule": { "activity": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "destination": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "mode": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "timing": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] } }, "destination_vot_max_adj": 0.2, "num_planned_activity_iterations": 0, "step_size": 2.0 } }, "do_routing_MSA": { "default": false, "title": "Do Routing Msa", "type": "boolean" }, "realtime_informed_vehicle_market_share": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Realtime Informed Vehicle Market Share" }, "skim_averaging_factor": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Skim Averaging Factor" }, "capacity_expressway": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Capacity Expressway" }, "capacity_arterial": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Capacity Arterial" }, "capacity_local": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Capacity Local" }, "population_scale_factor": { "default": 1.0, "title": "Population Scale Factor", "type": "number" }, "trajectory_sampling": { "default": 0.01, "title": "Trajectory Sampling", "type": "number" }, "add_rsus": { "default": false, "title": "Add Rsus", "type": "boolean" }, "rsu_highway_pr": { "default": 0.0, "title": "Rsu Highway Pr", "type": "number" }, "rsu_major_pr": { "default": 0.0, "title": "Rsu Major Pr", "type": "number" }, "rsu_minor_pr": { "default": 0.0, "title": "Rsu Minor Pr", "type": "number" }, "rsu_local_pr": { "default": 0.0, "title": "Rsu Local Pr", "type": "number" }, "rsu_enabled_switching": { "default": false, "title": "Rsu Enabled Switching", "type": "boolean" }, "fixed_connectivity_penetration_rates_for_cv": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Fixed Connectivity Penetration Rates For Cv" }, "highway_skim_file_name": { "default": "highway_skim_file.omx", "title": "Highway Skim File Name", "type": "string" }, "transit_skim_file_name": { "default": "transit_skim_file.omx", "title": "Transit Skim File Name", "type": "string" }, "skim_interval_endpoints": { "default": [ 240, 360, 420, 480, 540, 600, 720, 840, 900, 960, 1020, 1080, 1140, 1200, 1320, 1440 ], "items": { "type": "integer" }, "title": "Skim Interval Endpoints", "type": "array" }, "user_data": { "anyOf": [ {}, { "type": "null" } ], "default": null, "title": "User Data" } }, "$defs": { "CalibrationConfig": { "description": "Configuration class for the POLARIS calibration procedure.\n\nCalibration in POLARIS occurs by determining a delta from observed counts for key models (activity generation,\nmode choice, destination choice, timing choice) and using this to adjust the Alternative Specific Constants\n(ASC) of that model. This is done by modifying the JSON files in the root of the project at specified\n'calibration' iterations and then allowing the model to stabilise before re-evaluating.", "properties": { "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "target_csv_dir": { "default": "calibration_targets", "format": "path", "title": "Target Csv Dir", "type": "string" }, "calibration_schedule": { "$ref": "#/$defs/CalibrationSchedule", "default": { "destination": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "mode": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "activity": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] }, "timing": { "every_x_iter": 5, "first_iteration": 1, "last_iteration": 21, "on_abm_init": false, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ] } } }, "destination_vot_max_adj": { "default": 0.2, "title": "Destination Vot Max Adj", "type": "number" }, "num_planned_activity_iterations": { "default": 0, "title": "Num Planned Activity Iterations", "type": "integer" }, "step_size": { "default": 2.0, "title": "Step Size", "type": "number" } }, "title": "CalibrationConfig", "type": "object" }, "CalibrationSchedule": { "properties": { "destination": { "$ref": "#/$defs/IterationSchedule" }, "mode": { "$ref": "#/$defs/IterationSchedule" }, "activity": { "$ref": "#/$defs/IterationSchedule" }, "timing": { "$ref": "#/$defs/IterationSchedule" } }, "required": [ "destination", "mode", "activity", "timing" ], "title": "CalibrationSchedule", "type": "object" }, "IterationSchedule": { "properties": { "first_iteration": { "default": 1, "title": "First Iteration", "type": "integer" }, "last_iteration": { "title": "Last Iteration", "type": "integer" }, "every_x_iter": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Every X Iter" }, "pattern": { "items": { "type": "boolean" }, "title": "Pattern", "type": "array" }, "on_abm_init": { "default": false, "title": "On Abm Init", "type": "boolean" } }, "required": [ "last_iteration", "every_x_iter", "pattern" ], "title": "IterationSchedule", "type": "object" }, "WorkplaceStabilizationConfig": { "description": "Configuration class for the POLARIS workplace stabilization process.\n\nWorkplace stabilization in POLARIS is the process by which long-term decisions regarding work location\nare introduced to an overall iterative process. Work places are allowed to be updated based on current\ncongestion conditions on specified iterations, a number of iterations are then run using those updated\nchoices to allow the congestion to stabilize before repeating the process.", "properties": { "enabled": { "default": false, "title": "Enabled", "type": "boolean" }, "schedule": { "$ref": "#/$defs/IterationSchedule", "default": { "first_iteration": 1, "last_iteration": 31, "every_x_iter": 5, "pattern": [ true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true, false, false, false, false, true ], "on_abm_init": false } } }, "title": "WorkplaceStabilizationConfig", "type": "object" } } }
- Config:
ignored_types: tuple = (<class ‘function’>,)
validate_assignment: bool = True
- Fields:
- Validators:
- field data_dir: Path = PosixPath('.')#
The root directory of the model, defaults to the directory in which the convergence_control.yaml is located
- field backup_dir: Path | None = None#
Deprecated: Folder where backup of the model data is created before running the model
- field archive_dir: Path = PosixPath('archive')#
Deprecated: Folder from where to retrive archived data
- field results_dir: Path = None#
Deprecated: Folder to where the results of the model are saved
- Validated by:
- field db_name: str = None#
The filename prefix used in each of the database filenames (i.e. Chicago => Chicago-Supply.sqlite, etc)
- field polaris_exe: Path | None = None#
Path to the POLARIS executable to use. Three special values are supported for this: “model” - the binary that is located at ${data_dir}/bin/Integrated_Model, “polaris-studio” - the binary that ships with polaris-studio and “ci” - the latest CI executable (if available from your machine). If not specified will default to “model” if such exists, or to “polaris-studio” otherwise.
- Validated by:
- field cristal_exe: Path | None = None#
Path to the CRISTAL executable to use when running cristal iteration. In future releases, funcitonality will be combined with the polaris_exe
- field scenario_skim_file: Path = 'scenario_abm.json'#
Deprecated: File with scenario configuration for skimming
- field scenario_main_init: Path = 'scenario_abm.json'#
Deprecated: File with scenario configuration for model initialization
- field scenario_main: Path = 'scenario_abm.json'#
File containing the template scenario configuration which will be adapted based on the current iteration
- Validated by:
- field async_inline: bool = False#
Flag which controls if normally asynchronous post-processing steps (which aren’t needed for subsequent iterations) should be processed “in-line” to minimize the memory footprint. Set to True if you are having “Out of Memory” issues
- field num_threads: int = 48#
Number of CPU threads to use during simulation
- field num_abm_runs: int = 2#
Number of normal runs (ABM + DTA) to perform
- field num_dta_runs: int = 0#
Number of DTA-only runs to perform for a fixed demand from a previous normal iteration
- field num_outer_loops: int = 1#
Number of times a sequence of ABM+DTA and DTA-only runs will take place. For each num_outer_loop, num_abm_runs of ABM+DTA runs and num_dta_runs of DTA-only runs are simulated
- field start_iteration_from: int | str | None = None#
If a model run was interrupted, start_iteration_from can be set to restart a particular iteration (i.e. 5, iteration_5, 00_skim_iteration)
- field num_retries: int = 1#
Number of simulation crashes that are allowed before aborting the convergence process
- field use_numa: bool = True#
Flag that controls whether we apply numa options to the POLARIS executable when it is run
- field do_skim: bool = False#
Flag which controls whether a freeflow skimming iteration is undertaken at the beginning of the process. Note that this is rarely a good idea (compared to starting from existing skims) as POLARIS can take a considerable number of iterations to converge from a freeflow state
- Validated by:
- field do_cristal: bool = False#
Flag which controls whether a CRISTAL model run is undertaken at the beginning of the set of ABM runs. Cristal runs include abm_init so there are some internal flags to check that only one of the two can run at a time.
- field hdt_external_sample_for_cristal: float = 0.25#
Fractional sample of HDT trips from the fixed external input which should be kept and combind with synthetic Cristal trips
- field do_abm_init: bool = False#
Flag which controls whether a model initialization iteration is run at the beginning of the process. This iteration will synthesize population, generates demand, and assigns demand to the network
- field do_pop_synth: bool = False#
Flag which controls whether a separate population synthesis iteration is run at the beginning of the process
- Validated by:
- field workplace_stabilization: WorkplaceStabilizationConfig = WorkplaceStabilizationConfig(enabled=False, schedule=IterationSchedule(first_iteration=1, last_iteration=31, every_x_iter=5, pattern=[True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True], on_abm_init=False))#
Configuration related to the workplace stabilization process
- field calibration: CalibrationConfig = CalibrationConfig(enabled=False, target_csv_dir='calibration_targets', calibration_schedule=CalibrationSchedule(destination=IterationSchedule(first_iteration=1, last_iteration=21, every_x_iter=5, pattern=[True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True], on_abm_init=False), mode=IterationSchedule(first_iteration=1, last_iteration=21, every_x_iter=5, pattern=[True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True], on_abm_init=False), activity=IterationSchedule(first_iteration=1, last_iteration=21, every_x_iter=5, pattern=[True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True], on_abm_init=False), timing=IterationSchedule(first_iteration=1, last_iteration=21, every_x_iter=5, pattern=[True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True, False, False, False, False, True], on_abm_init=False)), destination_vot_max_adj=0.2, num_planned_activity_iterations=0, step_size=2.0)#
Configuration related to the calibration process
- field do_routing_MSA: bool = False#
Deprecated: Flag controlling the use of MSA averaging across routing iterations
Share of vehicles that have connectivity and receive realtime information about network (pass-through to scenario file)
- field skim_averaging_factor: float | None = None#
The proportional weight given to skims observed in the current iteration as they are mixed with previous iteration skims to produce the output skims for this iteration. Output = (1-w) * previous + w * current.
- field capacity_expressway: float | None = None#
Capacity of the expressway functional class to be used for the convergence run (pass-through to scenario file)
- field capacity_arterial: float | None = None#
Capacity of the arterial functional class to be used for the convergence run (pass-through to scenario file)
- field capacity_local: float | None = None#
Capacity of the local functional class to be used for the convergence run (pass-through to scenario file)
- field population_scale_factor: float = 1.0#
Population scaling factor
- field trajectory_sampling: float = 0.01#
Proportion of trajectories that are written to the database in each simulation iteration (pass-through to scenario file)
- field add_rsus: bool = False#
Deprecated
- field rsu_highway_pr: float = 0.0#
Deprecated
- field rsu_major_pr: float = 0.0#
Deprecated
- field rsu_minor_pr: float = 0.0#
Deprecated
- field rsu_local_pr: float = 0.0#
Deprecated
- field rsu_enabled_switching: bool = False#
Deprecated
- field fixed_connectivity_penetration_rates_for_cv: float | None = None#
- field highway_skim_file_name: str = 'highway_skim_file.omx'#
Name of the highway skim file
- field transit_skim_file_name: str = 'transit_skim_file.omx'#
Name of the transit skim file
- field skim_interval_endpoints: List[int] = [240, 360, 420, 480, 540, 600, 720, 840, 900, 960, 1020, 1080, 1140, 1200, 1320, 1440]#
An array of skimming intervals in minutes (since midnight) where each value denotes the end of the bin starting from the previous value or time 0
- field user_data: Any | None = None#
user_data is a general purpose storage location that can used to carry study-specific parameters which need to be accessible inside callback methods across multiple iterations
- __init__(*args, **kwargs)#
Create a new model by parsing and validating input data from keyword arguments.
Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.
self is explicitly positional-only to allow self as a field name.
- field uuid: str = None#
Unique identifier of the model run. Not normally specified and will be populated with a random UUID if not provided
- classmethod from_file(file: str | Path)#
- classmethod from_dir(dir: str | Path)#
- pretty_print(indent='')#
- normalise_paths(relative_to)#
- set_from_dict(_dict)#
Set underlying properties using an input dictionary of values. This is very useful when applying a batch of overrides programatically (i.e. via EQ/SQL). The given dictionary should have keys that correspond to named members (i.e. { “num_abm_runs”: 7 }) along with the desired state of that property. Nested members can be configured with nested dictionaries or using a.b syntax (i.e. {“workplace_stabilization.enabled”: False} or {“workplace_stabilization”: {“enabled”: True}} ).
- supply_file()#
- demand_file()#
- result_file()#
- iterations()#
- filter_based_on_start_iter(iterations, start_from=None)#
- check_exe()#
- validator val_results_dir » results_dir#
- validator default_polaris_exe » polaris_exe#
- validator default_scenario_main » scenario_main#
- validator default_do_pop_synth » do_pop_synth#