{
    "$id": "https://www.istp-cnr.it/gray/schemas/beam",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Gaussian beam",
    "description": "Gaussian beam characterization at the launch point.",
    "type": "object",
    "properties": {
        "cocos": {"$ref": "cocos"},
        "power": {
            "description": "Beam power at launch. Units [MW]",
            "type": "number",
            "minimum": 0
        },
        "freq": {
            "description": "Wave frequency. Units [GHz]",
            "type": "number",
            "exclusiveMinimum": 0
        },
        "polarization": {
            "description": "Beam polarization.\\nIt can be one of the plasma modes, or an arbitrary polarization,\\ncharacterized via the polarization ellipse parameters, that in general\\nwill couple to both OM and XM",
            "type": "object",
            "properties": {
                "mode": {
                    "description": "The propagation mode the beam couples to. One of:\\n  - `OM`: Ordinary mode\\n  - `XM`: eXtraordinary mode\n  - `ANY`: arbitrary polarization",
                    "enum": ["OM", "XM", "ANY"]
                },
                "ellipse": {"$ref": "#/$defs/polEllipse"}
            }
        },
        "pos": {
            "description": "Point where the beam is defined",
            "$ref": "coordscyl"
        },
        "dir": {
            "description": "Beam direction at launch",
            "type": "object",
            "properties": {
                "cocos": {"$ref": "cocos"},
                "alpha": {
                    "description": "Poloidal angle. alpha = atan2(-k_z, -k_R), with k the unit wavevector at launch. Units [deg]",
                    "type": "number"
                },
                "beta": {
                    "description": "Toroidal angle. beta = asin(k_phi), with k the unit wavevector at launch. Units [deg]",
                    "type": "number"
                }
            }
        },
        "shape": {
            "description": "Beam shape at launch",
            "type": "object",
            "properties": {
                "amplitude": {
                    "description": "Amplitude ellipse (E-field amplitude 1/e-fold on-axis value)",
                    "type": "object",
                    "properties": {
                        "w": {
                            "description": "Semi-axes of the ellipse. Units [m]",
                            "type": "array",
                            "items": {"type": "number", "exclusiveMinimum": 0},
                            "minItems": 2,
                            "maxItems": 2
                        },
                        "phi": {"$ref": "#/$defs/rotAngle"}
                    }
                },
                "phase": {
                    "description": "Phase ellipse (wavefront curvature)",
                    "type": "object",
                    "properties": {
                        "invR": {
                            "description": "Principal curvatures of the phase front. Units [m^-1]",
                            "type": "array",
                            "items": {"type": "number"},
                            "minItems": 2,
                            "maxItems": 2
                        },
                        "phi": {"$ref": "#/$defs/rotAngle"}
                    }
                }        
            }
        }
    },
    "$defs": {
        "polEllipse": {
            "description": "Angles defining an elliptical polarization",
            "type": "object",
            "properties": {
                "psi": {
                    "description": "Polarization ellipse orientation.\\nThe angle is measured counter-clockwise angle from x' to the polarization\\nellipse major axis in a local right-handed Cartesian frame (x',y',z')\\nwith z' parallel to the beam axis direction k, and x' in the horizontal\\nplane of the global frame (i.e., x'.z=0). Units [deg]",
                    "type": "number"
                },
                "chi": {
                    "description": "Polarization ellipticity.\\n|tan(chi)| = b/a ≤ 1 is the ratio of the polarization ellipse semi-axes\\nsign(chi) = +1 for a right-handed wave (i.e., electric field rotating\\nfrom x' to y' at fixed z') and -1 for a left-handed wave. Units [deg]",
                    "type": "number"
                }
            }
        },
        "rotAngle": {
            "description": "Ellipse orientation. The angle is measured counter-clockwise from x' to\\nthe first principal direction, in a local right-handed Cartesian frame\\n(x',y',z') with z' parallel to the beam axis direction k, and x' in the\\nhorizontal plane of the global frame (i.e., x'.z=0). Units [deg]",
            "type": "number"
        }
    }
}