docs: Simulation execution and shutdown chapter of The Ixa Book

[RobertJacobsonCDC]

A new chapter of the Ixa Book that covers everything related to simulation execution and showdown. GitHub's partial rendering of it is here.

1. Execution and Shutdown
   1. Syntax Summary
   2. The Execution Lifecycle
      1. Beginning Execution
      2. During Normal Event-loop Execution
      3. Ending Execution
         1. Automatic Shutdown
         2. Normal Shutdown
            1. What Runs During Normal Shutdown
            2. Current-Time Plans Across Phases
            3. Shutdown-Time Plans
            4. What Remains Queued After Shutdown
         3. Aborting Execution
         4. Common Shutdown Patterns
   3. Execution Outside of the Event-loop
      1. Executing Again After execute() Returns
      2. Single-Step Execution

To Do Before Merging:

• Update to acknowledge the new triggers module (about to be merged, feat: Triggers #962).
• Update to reflect decision to exclude "active plan" terminology from user-facing API and docs. We only have (regular) plans and "passive plans."
• Update to include "schedule shutdown" helper of Add schedule shutdown helper method #984 if it lands first.

[RobertJacobsonCDC]

Clarify that there are three work queues:

1. The callback queue
2. The plan queue, sometimes called the timeline
3. The shutdown-time plan queue

[github-actions]

Benchmark Results

Hyperfine

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
large_sir::baseline	3.3 ± 0.1	3.2	3.5	1.00
large_sir::baseline_households	3.3 ± 0.1	3.2	3.7	1.01 ± 0.04
large_sir::entities	7.4 ± 0.3	7.1	8.5	2.25 ± 0.09
large_sir::households	7.7 ± 0.4	7.1	9.0	2.32 ± 0.13

Criterion

Regressions (slower)

Group	Bench	Param	Change	CI Lower	CI Upper
indexing	query_people_single_indexed_property_entities		15.516%	12.039%	18.646%
sample_entity	sample_entity_single_property_unindexed	10000	12.677%	10.444%	14.694%
sample_entity	sample_entity_single_property_unindexed	1000	6.084%	3.141%	9.188%
large_dataset	bench_query_population_multi_indexed_entities		3.321%	1.645%	4.997%
indexing	query_people_multiple_individually_indexed_properties_entities		2.833%	2.663%	3.045%
sampling	sampling_multiple_unindexed_entities		2.462%	2.284%	2.666%
sampling	sampling_multiple_l_reservoir_entities		1.769%	1.581%	1.955%

Improvements (faster)

Group	Bench	Param	Change	CI Lower	CI Upper
sample_entity	sample_entity_whole_population	100000	-4.741%	-5.981%	-3.371%
sample_entity	sample_entity_whole_population	10000	-4.273%	-4.852%	-3.684%
sample_entity	sample_entity_multi_property_indexed	1000	-3.996%	-4.990%	-2.893%
sample_entity	sample_entity_whole_population	1000	-3.610%	-4.193%	-3.021%
sample_entity	sample_entity_multi_property_indexed	100000	-2.254%	-2.717%	-1.781%
counts	reindex_after_adding_more_entities		-1.830%	-2.099%	-1.554%
examples	example-births-deaths		-1.601%	-1.779%	-1.423%
sample_entity	sample_entity_single_property_indexed	1000	-1.590%	-2.185%	-1.052%

Unchanged / inconclusive (CI crosses 0%)

Group	Bench	Param	Change	CI Lower	CI Upper
large_dataset	bench_match_entity		1.974%	-0.153%	4.122%
large_dataset	bench_query_population_indexed_property_entities		1.632%	-1.437%	4.663%
large_dataset	bench_query_population_derived_property_entities		-1.148%	-2.099%	-0.179%
indexing	query_people_indexed_multi-property_entities		1.125%	0.154%	2.162%
sampling	sampling_single_unindexed_concrete_plus_derived_entities		1.080%	0.833%	1.329%
sample_entity	sample_entity_single_property_indexed	100000	0.930%	0.384%	1.625%
counts	multi_property_indexed_entities		0.853%	0.531%	1.191%
examples	example-basic-infection		0.832%	-0.884%	3.167%
sample_entity	sample_entity_single_property_indexed	10000	-0.746%	-1.396%	-0.075%
sampling	sampling_single_l_reservoir_entities		0.745%	0.221%	1.172%
sample_entity	sample_entity_single_property_unindexed	100000	0.745%	0.474%	1.128%
indexing	with_query_results_single_indexed_property_entities		-0.720%	-1.308%	-0.280%
algorithm_benches	algorithm_sampling_single_rand_reservoir		-0.705%	-0.959%	-0.455%
sampling	sampling_single_unindexed_entities		0.655%	0.378%	0.946%
indexing	query_people_count_single_indexed_property_entities		0.604%	0.293%	0.872%
algorithm_benches	algorithm_sampling_multiple_l_reservoir		0.366%	-0.146%	0.890%
counts	single_property_indexed_entities		-0.360%	-0.786%	-0.083%
large_dataset	bench_filter_unindexed_entity		-0.350%	-3.327%	2.969%
indexing	with_query_results_indexed_multi-property_entities		-0.308%	-0.915%	0.252%
sampling	sampling_multiple_known_length_entities		-0.244%	-0.582%	0.064%
sample_entity	sample_entity_multi_property_indexed	10000	-0.224%	-0.846%	0.437%
indexing	with_query_results_multiple_individually_indexed_properties_enti		-0.173%	-0.757%	0.370%
counts	index_after_adding_entities		0.164%	-0.212%	0.481%
sampling	count_and_sampling_single_unindexed_concrete_plus_derived_entiti		0.141%	-0.081%	0.364%
indexing	query_people_count_indexed_multi-property_entities		-0.139%	-0.545%	0.186%
large_dataset	bench_query_population_property_entities		-0.135%	-0.570%	0.174%
algorithm_benches	algorithm_sampling_single_l_reservoir		-0.097%	-0.451%	0.331%
indexing	query_people_count_multiple_individually_indexed_properties_enti		0.092%	-0.090%	0.278%
algorithm_benches	algorithm_sampling_multiple_known_length		-0.092%	-0.459%	0.309%
counts	concrete_plus_derived_unindexed_entities		0.068%	-0.260%	0.488%
sampling	count_and_sampling_single_known_length_entities		-0.065%	-0.618%	0.470%
algorithm_benches	algorithm_sampling_single_known_length		0.035%	-4.073%	4.344%
large_dataset	bench_filter_indexed_entity		-0.028%	-1.926%	1.816%
sampling	sampling_single_known_length_entities		0.027%	-0.352%	0.516%
counts	multi_property_unindexed_entities		0.022%	-0.267%	0.396%
large_dataset	bench_query_population_multi_unindexed_entities		0.020%	-0.282%	0.473%
counts	single_property_unindexed_entities		-0.012%	-0.589%	0.578%

Not Compared (no baseline yet)

Group	Bench	Reason
(none)

[RobertJacobsonCDC]

We changed the language of the "passive plans" implementation to avoid calling non-passive plans "active." We just have plans, and then we have a special kind of "passive plan." This is just a language change, not a change in underlying functionality.

This new chapter needs to be updated to reflect this new language. Looks like it also needs to be rebased.