{ "cells": [ { "cell_type": "raw", "id": "0", "metadata": { "editable": true, "raw_mimetype": "text/restructuredtext", "slideshow": { "slide_type": "" }, "tags": [] }, "source": [ ".. _notebooks-cavities-reference-phase:" ] }, { "cell_type": "markdown", "id": "1", "metadata": {}, "source": [ "# Cavities reference phase" ] }, { "cell_type": "markdown", "id": "2", "metadata": {}, "source": [ "## Definitions" ] }, { "cell_type": "markdown", "id": "3", "metadata": {}, "source": [ "There are three ways to define the reference phase of a cavity:\n", "- by its relative entry phase $\\phi_{0,\\,\\mathrm{rel}}$,\n", "- its absolute entry phase $\\phi_{0,\\,\\mathrm{abs}}$,\n", "- its synchronous phase $\\phi_s$." ] }, { "cell_type": "markdown", "id": "4", "metadata": {}, "source": [ "A cavity reference phase controls its behavior when the beam phase differs from the baseline, which happens downstream of a failure if the beam absolute phase was not recovered.\n", "- `\"phi_0_abs\"`: the cavity is not rephased.\n", "- `\"phi_0_rel\"`: $\\phi_{0,\\,\\mathrm{rel}}$ is preserved, so that the beam always \"sees\" the same RF phase.\n", "- `\"phi_s\"`: $\\phi_s$ is preserved, so that the cavity acceptance stays the same." ] }, { "cell_type": "markdown", "id": "5", "metadata": {}, "source": [ "The relation between relative and entry phases is:\n", "\\begin{equation}\n", "E_0\\cos{\\phi_{0,\\,\\mathrm{abs}}} = E_0\\cos{(\\phi_{0,\\,\\mathrm{rel}} + \\phi_\\mathrm{in})}\n", "\\end{equation}\n", "where $\\phi_\\mathrm{in}$ is the phase at which the synchronous particle enters the cavity, $E_0$ is the amplitude of the electric field." ] }, { "cell_type": "markdown", "id": "6", "metadata": {}, "source": [ "There is no analytic relation between $phi_s$ and the RF phases $\\phi_{0,\\,\\mathrm{rel}}$, $\\phi_{0,\\,\\mathrm{abs}}$. Hereby, when the reference phase of a cavity is $phi_s$, calculations are performed to find the actual RF phase allowing to retrieve $phi_s$. Those calculations can take some time." ] }, { "cell_type": "markdown", "id": "7", "metadata": {}, "source": [ "The cavities reference phases are set by the `reference_phase_policy` entry in the `beam_calculator` section of the `TOML` file:\n", "- `\"phi_0_rel\"`, `\"phi_0_abs\"` or `\"phi_s\"`: use this phase as reference\n", "- `\"as_in_original_dat\"`: keep the reference stated in the `DAT` file, following the `SET_SYNC_PHASE` and the `FLAG_PHI_ABS` value of the `FIELD_MAP` commands.\n", " - Different cavities can have different reference phase!" ] }, { "cell_type": "markdown", "id": "8", "metadata": {}, "source": [ "In the rest of this notebook, we illustrate these differences and their impact on the beam dynamics." ] }, { "cell_type": "markdown", "id": "9", "metadata": {}, "source": [ "## Preparation" ] }, { "cell_type": "markdown", "id": "10", "metadata": {}, "source": [ "### Load libraries" ] }, { "cell_type": "code", "execution_count": null, "id": "11", "metadata": {}, "outputs": [], "source": [ "import logging\n", "from pathlib import Path\n", "\n", "import matplotlib.pyplot as plt\n", "\n", "from lightwin.config.config_manager import process_config\n", "from lightwin.beam_calculation.beam_calculator import BeamCalculator\n", "from lightwin.beam_calculation.factory import BeamCalculatorsFactory\n", "from lightwin.beam_calculation.simulation_output.simulation_output import SimulationOutput\n", "from lightwin.core.accelerator.accelerator import Accelerator\n", "from lightwin.core.accelerator.factory import NoFault, WithFaults\n", "from lightwin.failures.fault_scenario import FaultScenario, fault_scenario_factory\n", "from lightwin.visualization import plot\n", "from lightwin.constants import example_config, example_results\n", "from lightwin.util.log_manager import set_up_logging\n", "\n", "plt.rcParams[\"figure.figsize\"] = (15, 5)" ] }, { "cell_type": "markdown", "id": "12", "metadata": {}, "source": [ "### Set the different solvers" ] }, { "cell_type": "code", "execution_count": null, "id": "13", "metadata": {}, "outputs": [], "source": [ "CONFIG_KEYS = {\n", " 'files': 'files',\n", " 'beam_calculator': 'generic_envelope1d',\n", " 'beam': 'beam',\n", " 'plots': 'plots_minimal',\n", " 'wtf': 'generic_wtf',\n", " 'design_space': 'generic_design_space',\n", "}" ] }, { "cell_type": "markdown", "id": "14", "metadata": {}, "source": [ "#### Linac with absolute reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "15", "metadata": {}, "outputs": [], "source": [ "override = {\n", " 'beam_calculator': {'reference_phase_policy': \"phi_0_abs\"},\n", " 'plots': {'energy': False, \"add_objectives\": False, \"twiss\": False},\n", " 'wtf': {'objective_preset': 'EnergyPhaseMismatch'},\n", "}\n", "config_abs = process_config(example_config, CONFIG_KEYS, warn_mismatch=True, override=override)\n", "\n", "# We will use this for plots representing cavity settings, phase\n", "plots_phase = config_abs['plots']\n", "\n", "factory = BeamCalculatorsFactory(**config_abs)\n", "solver_abs = factory.run_all()[0]" ] }, { "cell_type": "markdown", "id": "16", "metadata": {}, "source": [ "#### Linac with relative reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "17", "metadata": {}, "outputs": [], "source": [ "override = {\n", " 'beam_calculator': {'reference_phase_policy': \"phi_0_rel\"},\n", " 'plots': {'cav': True, \"add_objectives\": False, \"twiss\": False},\n", " 'wtf': {'objective_preset': 'EnergyMismatch'},\n", "}\n", "config_rel = process_config(example_config, CONFIG_KEYS, warn_mismatch=True, override=override)\n", "\n", "# We will use this for plots representing cavity settings, phase, energy\n", "plots_complete = config_rel['plots']\n", "\n", "factory = BeamCalculatorsFactory(**config_rel)\n", "solver_rel = factory.run_all()[0]" ] }, { "cell_type": "markdown", "id": "18", "metadata": {}, "source": [ "### Linac with synchronous reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "19", "metadata": {}, "outputs": [], "source": [ "override = {\n", " 'beam_calculator': {'reference_phase_policy': \"phi_s\"},\n", " 'wtf': {'objective_preset': 'EnergyMismatch'},\n", "}\n", "config_sync = process_config(example_config, CONFIG_KEYS, warn_mismatch=True, override=override)\n", "\n", "factory = BeamCalculatorsFactory(**config_sync)\n", "solver_sync = factory.run_all()[0]" ] }, { "cell_type": "markdown", "id": "20", "metadata": {}, "source": [ "### Set Accelerator objects" ] }, { "cell_type": "code", "execution_count": null, "id": "21", "metadata": {}, "outputs": [], "source": [ "logging.getLogger().setLevel(logging.WARNING)\n", "\n", "factory = WithFaults(beam_calculators=solver_abs, **config_abs)\n", "accelerators_abs = factory.run_all()\n", "for acc in accelerators_abs:\n", " acc.name += r' (absolute $\\phi_0$)'\n", "working_abs = accelerators_abs[0]\n", "broken_abs = accelerators_abs[1]\n", "\n", "factory = WithFaults(beam_calculators=solver_rel, **config_rel)\n", "accelerators_rel = factory.run_all()\n", "for acc in accelerators_rel:\n", " acc.name += r' (relative $\\phi_0$)'\n", "working_rel = accelerators_rel[0]\n", "broken_rel = accelerators_rel[1]\n", "\n", "factory = WithFaults(beam_calculators=solver_sync, **config_sync)\n", "accelerators_sync = factory.run_all()\n", "for acc in accelerators_sync:\n", " acc.name += r' ($\\phi_s$)'\n", "working_sync = accelerators_sync[0]\n", "broken_sync = accelerators_sync[1]\n", "\n", "working_linacs = (working_abs, working_rel, working_sync)\n", "broken_linacs = (broken_abs, broken_rel, broken_sync)\n", "solvers = (solver_abs, solver_rel, solver_sync)" ] }, { "cell_type": "markdown", "id": "22", "metadata": {}, "source": [ "## Propagate the beam" ] }, { "cell_type": "markdown", "id": "23", "metadata": {}, "source": [ "### Nominal linac" ] }, { "cell_type": "code", "execution_count": null, "id": "24", "metadata": {}, "outputs": [], "source": [ "for solver, linac in zip(solvers, working_linacs):\n", " _ = solver.compute(linac)\n", "figs = plot.factory(working_linacs, plots_phase, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "25", "metadata": {}, "source": [ "In the nominal linac, there is no difference between the different reference phases." ] }, { "cell_type": "markdown", "id": "26", "metadata": {}, "source": [ "
\n", "The reference $\\phi_0$ that is used is the one defined in the `DAT`.\n", "As a matter of a fact, we need to propagate the beam a first time to know the entry phase of the synchronous particle in every cavity.\n", "This quantity is necessary to link $\\phi_{0,\\,\\mathrm{abs}}$ with $\\phi_{0,\\,\\mathrm{rel}}$.\n", "
" ] }, { "cell_type": "markdown", "id": "27", "metadata": {}, "source": [ "## Linac with one broken cavity" ] }, { "cell_type": "markdown", "id": "28", "metadata": {}, "source": [ "### Absolute reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "29", "metadata": {}, "outputs": [], "source": [ "fault_scenarios_abs = fault_scenario_factory(accelerators_abs, solver_abs, config_abs['wtf'], config_abs['design_space'])" ] }, { "cell_type": "code", "execution_count": null, "id": "30", "metadata": {}, "outputs": [], "source": [ "_ = solver_abs.compute(broken_abs)\n", "figs = plot.factory(accelerators_abs, plots_complete, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "31", "metadata": {}, "source": [ "Cavities in their nominal tuning are green, and the failed cavity is represented in red.\n", "Here the beam energy and phase remain very close to the baseline. However, the positive synchronous phases show that high losses would be to expect." ] }, { "cell_type": "markdown", "id": "32", "metadata": {}, "source": [ "### Relative reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "33", "metadata": {}, "outputs": [], "source": [ "fault_scenarios_rel = fault_scenario_factory(accelerators_rel, solver_rel, config_rel['wtf'], config_rel['design_space'])" ] }, { "cell_type": "code", "execution_count": null, "id": "34", "metadata": {}, "outputs": [], "source": [ "_ = solver_rel.compute(broken_rel)\n", "figs = plot.factory(accelerators_rel, plots_complete, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "35", "metadata": {}, "source": [ "In this example, the error on the beam energy is progressively damped. In LightWin, rephased cavities are represented with olive color." ] }, { "cell_type": "markdown", "id": "36", "metadata": {}, "source": [ "### Synchronous reference phase" ] }, { "cell_type": "code", "execution_count": null, "id": "37", "metadata": {}, "outputs": [], "source": [ "fault_scenarios_sync = fault_scenario_factory(accelerators_sync, solver_sync, config_sync['wtf'], config_sync['design_space'])" ] }, { "cell_type": "code", "execution_count": null, "id": "38", "metadata": {}, "outputs": [], "source": [ "_ = solver_sync.compute(broken_sync)\n", "figs = plot.factory(accelerators_sync, plots_complete, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "39", "metadata": {}, "source": [ "Notice that the synchronous phases are unaffected by failed cavity." ] }, { "cell_type": "markdown", "id": "40", "metadata": {}, "source": [ "## Fixing the fault" ] }, { "cell_type": "markdown", "id": "41", "metadata": {}, "source": [ "### Absolute phase linac" ] }, { "cell_type": "markdown", "id": "42", "metadata": {}, "source": [ "For the absolute phase linac, we try to retrieve the energy and the phase at the end of the compensation zone, as well as to minimize the mismatch factor." ] }, { "cell_type": "code", "execution_count": null, "id": "43", "metadata": {}, "outputs": [], "source": [ "for scenario in fault_scenarios_abs:\n", " scenario.fix_all()\n", "figs = plot.factory(accelerators_abs, plots_complete, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "44", "metadata": {}, "source": [ "### Relative phase linac" ] }, { "cell_type": "markdown", "id": "45", "metadata": {}, "source": [ "When downstream cavities are rephased, it is no longer mandatory to retrieve nominal beam phase at the exit of the compensation zone. Here, we try to retrieve the kinetic energy and to minimize the mismatch factor." ] }, { "cell_type": "code", "execution_count": null, "id": "46", "metadata": {}, "outputs": [], "source": [ "for scenario in fault_scenarios_rel:\n", " scenario.fix_all()\n", "figs = plot.factory(accelerators_rel, plots_complete, save_fig=False, clean_fig=False)" ] }, { "cell_type": "markdown", "id": "47", "metadata": {}, "source": [ "### Synchronous phase linac" ] }, { "cell_type": "markdown", "id": "48", "metadata": {}, "source": [ "Results will be very similar to the relative phase linac." ] }, { "cell_type": "code", "execution_count": null, "id": "49", "metadata": {}, "outputs": [], "source": [ "for scenario in fault_scenarios_sync:\n", " scenario.fix_all()\n", "figs = plot.factory(accelerators_sync, plots_complete, save_fig=False, clean_fig=False)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.2" } }, "nbformat": 4, "nbformat_minor": 5 }