.cut File Format ================ Introduction ------------ The `.cut` file format is used for storing field data generated by objects of the Grasp classes `Spherical Cut`, `Planar Cut`, `Surface Cut`, and `Cylindrical Cut`. Currently supported formats --------------------------- The following table shows the formats that `grasp2alm` can read. +-------+------+-------+-------------------------------------------------------------------+ | ICOMP | ICUT | NCOMP | Description | +=======+======+=======+===================================================================+ | 3 | 1 | 2 | Spherical cut far field, linear :math:`E_{co}` and :math:`E_{cx}` | +-------+------+-------+-------------------------------------------------------------------+ File Structure -------------- A `.cut` file consists of a series of records that describe the characteristics and data of field cuts. Each file may contain multiple cuts, and for each cut, all records must be repeated. There are three primary types of records: 1. **Record Type 1: TEXT** This record contains identification text to label and describe the cut. It is represented by a string of characters. 2. **Record Type 2: Parameters** This record defines the parameters for the cut: - **V_INI**: Initial value (real number) - **V_INC**: Increment value (real number) - **V_NUM**: Number of values in the cut (integer) - **C**: Constant value (real number) - **ICOMP**: Polarization control parameter (integer) - **ICUT**: Control parameter of the cut (integer) - **NCOMP**: Number of field components (integer) See :ref:`cut:Parameter Definitions for Spherical Cuts` for more information about `Sperical Cuts`. 3. **Record Type 3: Field Values** These records contain the actual field values for each point in the cut. The number of components stored depends on the value of **NCOMP**: - If **NCOMP = 2**: the record contains two components of the field, F1 and F2. - If **NCOMP = 3**: the record includes an additional third field component, F3. For each data point I (single row): - the parameter **V** is :math:`\mathrm{V\_INI}+\mathrm{V\_INC} \cdot (\mathrm{I}-1)` - **F1, F2** (and **F3** if applicable) store the real and imaginary parts of the field components in the direction associated to **V** and **C**. See :ref:`cut:Field Component Details Based on ICOMP` for more information **Example of a typical .cut file:** :: identification text V_INI V_INC V_NUM C ICOMP ICUT NCOMP F1.real F1.img F2.real F2.img F3.real F3.img ... Parameter Definitions for Spherical Cuts ---------------------------------------- The **V** and **C** values are angles in **degrees** whose definition is controlled by the parameter **ICUT**: - **ICUT = 1**: A standard polar cut where :math:`\phi` is fixed (**C**) and :math:`\theta` varies (**V**) - **ICUT = 2**: A conical cut where :math:`\theta` is fixed (**C**) and :math:`\phi` varies (**V**) Regarding **ICOMP**, it could be one of the following values: - **1**: Linear :math:`E_\theta` and :math:`E_\phi` - **2**: Right hand and left hand circular (:math:`E_{rhc}` and :math:`E_{lhc}`) - **3**: Linear :math:`E_{co}` and :math:`E_{cx}` (Ludwig's third definition) - **4**: Linear along major and minor axes of the polarization ellipse, :math:`E_{maj}` and :math:`E_{min}` - **5-8**: Various XPD (Cross-Polar Discrimination) fields - **9**: Total power :math:`|\vec{E}|` and :math:`\sqrt{E_{rhc}/E_{lhc}}` Finally, when the field is a near field, **NCOMP** is equal to 3 and the file contains also a third radial component :math:`E_{r}`. Field Component Details Based on ICOMP -------------------------------------- - **ICOMP = 1, 2, 3, 5, 6, or 7**: - F1, F2 (and optionally F3) contain the real and imaginary parts of the field in a linear scale. - **ICOMP = 4**: - Real part of F1: Major axis of the polarization ellipse (linear scale) - Real part of F2: Minor axis of the polarization ellipse (linear scale) - Imaginary parts of F1 and F2 are zero. - **ICOMP = 8**: - Real part of F1: Major axis divided by the minor axis of the polarization ellipse (linear scale) - Real part of F2: Minor axis divided by the major axis of the polarization ellipse (linear scale) - Imaginary parts of F1 and F2 are zero. - **ICOMP = 9**: - Real part of F1: Total power :math:`|\vec{E}|` of the field (linear scale) - The imaginary part of F1 is zero. - F2: Complex square root of the ratio rhc/lhc. The phase indicates the rotation angle of the polarization ellipse.