Implement multirate simulation scaffolding and update documentation

[VEZY]

This pull request introduces major improvements to PlantSimEngine’s architecture, documentation, and core interfaces to support upcoming features like multi-rate simulation, scoped model instances, and advanced scheduling policies.

Documentation enhancements:

• Added a detailed internal summary (AI_PACKAGE_SUMMARY.md) explaining PlantSimEngine’s architecture, data structures, dependency graph, multiscale mapping, MTG integration, execution flow, and known pain points.
• Updated planned features documentation to reference the new multi-rate and scoped simulation draft.

Core scaffolding for multi-rate and scoped simulation:

• Added new includes in src/PlantSimEngine.jl for multi-rate scaffolding (time/multirate.jl) and model specification (mtg/ModelSpec.jl). [1] [2]
• Expanded exports to include new types and interfaces for scope, clock, model/output keys, scheduling policies, temporal state, model specification, input bindings, and output routing.

GraphSimulation struct extension:

• Extended the GraphSimulation struct to include model_specs and temporal_state fields, enabling support for normalized model usage specifications and multi-rate temporal storage.

These changes collectively prepare PlantSimEngine for more flexible and robust simulation workflows, including multi-rate execution and scoped modeling.

[github-actions]

Benchmark Results (Julia v1.10)

Time benchmarks

	main	469db26...	main / 469db26...
bench_linux/PBP	14.4 ± 2.2 ms	14.8 ± 2.1 ms	0.969 ± 0.2
bench_linux/PBP_multiple_timesteps_MT	0.256 ± 0.014 s	0.232 ± 0.0054 s	1.1 ± 0.067
bench_linux/PBP_multiple_timesteps_ST	0.236 ± 0.0048 s	0.238 ± 0.0066 s	0.99 ± 0.034
bench_linux/PSE	4.37 ± 0.44 s	4.73 ± 0.51 s	0.924 ± 0.14
bench_linux/XPalm_convert_outputs	0.751 ± 0.0099 s	0.77 ± 0.0097 s	0.975 ± 0.018
bench_linux/XPalm_run	0.0168 ± 0.01 h	0.0199 ± 0.01 h	0.843 ± 0.66
bench_linux/XPalm_setup	16.3 ± 2.5 ms	16 ± 2.5 ms	1.02 ± 0.22
time_to_load	2.01 ± 0.021 s	2 ± 0.029 s	1 ± 0.018

Memory benchmarks

	main	469db26...	main / 469db26...
bench_linux/PBP	0.0913 M allocs: 6.16 MB	0.0913 M allocs: 6.16 MB	1
bench_linux/PBP_multiple_timesteps_MT	3.46 M allocs: 0.714 GB	3.46 M allocs: 0.714 GB	1
bench_linux/PBP_multiple_timesteps_ST	3.32 M allocs: 0.217 GB	3.32 M allocs: 0.217 GB	1
bench_linux/PSE	0.0496 G allocs: 2.31 GB	0.0496 G allocs: 2.38 GB	0.972
bench_linux/XPalm_convert_outputs	6.59 M allocs: 0.436 GB	6.59 M allocs: 0.436 GB	1
bench_linux/XPalm_run	0.571 G allocs: 28.9 GB	0.576 G allocs: 30.3 GB	0.953
bench_linux/XPalm_setup	0.168 M allocs: 9.16 MB	0.168 M allocs: 9.16 MB	1
time_to_load	0.153 k allocs: 14.5 kB	0.153 k allocs: 14.5 kB	1

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	main	469db26...	main / 469db26...
bench_linux/PBP	17.5 ± 2.2 ms	20 ± 2.7 ms	0.875 ± 0.16
bench_linux/PBP_multiple_timesteps_MT	0.328 ± 0.013 s	0.342 ± 0.01 s	0.959 ± 0.047
bench_linux/PBP_multiple_timesteps_ST	0.22 ± 0.017 s	0.236 ± 0.031 s	0.933 ± 0.14
bench_linux/PSE	4.57 ± 0.58 s	4.82 ± 0.46 s	0.949 ± 0.15
bench_linux/XPalm_convert_outputs	0.782 ± 0.092 s	1.09 ± 0.077 s	0.718 ± 0.099
bench_linux/XPalm_run	53.4 ± 19 s	0.0177 ± 0.0077 h	0.837 ± 0.48
bench_linux/XPalm_setup	16.7 ± 0.64 ms	16.6 ± 0.96 ms	1.01 ± 0.07
time_to_load	3.08 ± 0.037 s	3.2 ± 0.033 s	0.962 ± 0.015

Memory benchmarks

	main	469db26...	main / 469db26...
bench_linux/PBP	0.0911 M allocs: 5.48 MB	0.0911 M allocs: 5.48 MB	1
bench_linux/PBP_multiple_timesteps_MT	3.97 M allocs: 0.746 GB	3.97 M allocs: 0.746 GB	1
bench_linux/PBP_multiple_timesteps_ST	3.5 M allocs: 0.239 GB	3.5 M allocs: 0.239 GB	1
bench_linux/PSE	0.0497 G allocs: 2.3 GB	0.0498 G allocs: 2.37 GB	0.972
bench_linux/XPalm_convert_outputs	6.62 M allocs: 0.436 GB	6.62 M allocs: 0.436 GB	1
bench_linux/XPalm_run	0.573 G allocs: 28.9 GB	0.576 G allocs: 30.2 GB	0.956
bench_linux/XPalm_setup	0.165 M allocs: 8.87 MB	0.165 M allocs: 8.87 MB	1
time_to_load	0.149 k allocs: 11.1 kB	0.149 k allocs: 11.1 kB	1