10.65 MATR—Explicit matrix input from a text file, in the format written by the print_matrix command.

Explicit matrix input from a text file, in the format written by the print_matrix command.
Parallel capable? : yes
GPU capable? : yes
Back-tracking capable? : no

The input file for this element uses a simple text format. It is nearly identical to the output in the printout file generated by the matrix_output and analyze_map commands. For example, for a 1st-order matrix, the file would have the following appearance:
C: C1 C2 C3 C4 C5 C6
R1: R11 R12 R13 R14 R15 R16
R2: R21 R22 R23 R24 R25 R26
R3: R31 R32 R33 R34 R35 R36
R4: R41 R42 R43 R44 R45 R46
R5: R51 R52 R53 R54 R55 R56
R6: R61 R62 R63 R64 R65 R66

Items in normal type must be entered exactly as shown, whereas those in italics must be provided by the user. The colons are important! For this particular example, one would set ORDER=1 in the MATR definition. Typically, the Ci are zero, except for C5, which is usually equal to the length of the element (which must be specified with the L parameter in the MATR definition).

As of release 2019.2, the required format changed slightly. In the new version, the start of the matrix is determined by reading through the file until a line starting with C: is found. In the past, instead of starting with C:, the first line of the matrix could start with any string terminated by a colon, but that line had to be the first line in the file, which conflicted with the format emitted by analyze_map.

The FRACTION parameter can be used to interpolate the matrix elements between the matrix M₀ read from FILENAME and the identity matrix I, according to

(91)

This can be used, for example, to gradually ramp in the effect as part of an optimization. N.B.: in general, the matrix does not have unit determinant unless f = 0 or f = 1, so this feature should be used only as a knob to assist finding a solution with f = 1. Exceptions are when M₀ is a drift space or thin-lens quadrupole matrix, in which cases the determinant of M is always 1.