Facet dev

[roussel-ryan]

This pull request introduces several improvements and new features related to the FACET-II lattice and surrogate model integration, as well as updates to the test workflows to support these changes. The most important updates are the addition of a staged model for FACET-II, enhancements to the injector surrogate for better compatibility, and workflow changes to ensure the new lattice is available in CI.

FACET-II Model and Surrogate Integration:

• Added get_facet_staged_model to virtual_accelerator/models/facet2.py, allowing construction of a StagedModel that combines the FACET-II lattice with an injector surrogate model. This enables more flexible and modular simulation setups.
• Enhanced BeamOutputModel in virtual_accelerator/surrogates/injector_surrogate.py:
  • Now inherits from FinalParticlesMixIn for compatibility with staged models. [1] [2]
  • Added t0 and z0 parameters to control reference time and position, and updated internal logic to use these values in the generated beam data. [1] [2] [3]
  • Implements a final_particles property to expose the final particle distribution for downstream models.

Continuous Integration and Testing:

• Updated all relevant GitHub Actions workflows (tests.yml, test-bmad.yml, test-cheetah.yml) to check out the new facet2-lattice repository and set the FACET2_LATTICE environment variable, ensuring that tests requiring the FACET-II lattice have access to it. [1] [2] [3] [4] [5] [6]
• Clarified and updated workflow descriptions to better reflect which tests are run or skipped, especially regarding BMAD-backed and FACET2-specific tests.

Testing Enhancements:

• Added a test_short_tracking test to virtual_accelerator/tests/test_facet.py for the FACET-II BMAD model, verifying initialization and short tracking with a custom beam. [1] [2]