skip superimposed element flattening flag

[roussel-ryan]

Description

Add the flag skip_superimposed to segment.flatten() which allows the user to flatten segments without flattening superimposed elements (which are useful when not flattened).

Motivation and Context

This flag is helpful for flattening SLAC accelerator segments (which have many sub segments) into a single line, without removing the advantages of superimposed element definitions.

• I have raised an issue to propose this change (required for new features and bug fixes)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (update in the documentation)

Checklist

• I have updated the changelog accordingly (required).
• My change requires a change to the documentation.
• I have updated the tests accordingly (required for a bug fix or a new feature).
• I have updated the documentation accordingly.
• I have reformatted the code and checked that formatting passes (required).
• I have have fixed all issues found by flake8 (required).
• I have ensured that all pytest tests pass (required).
• I have run pytest on a machine with a CUDA GPU and made sure all tests pass (required).
• I have checked that the documentation builds (required).

Note: We are using a maximum length of 88 characters per line.

[jp-ga]

@cr-xu this is also ready for review