13  Cyclotron Modelling

Cyclotron modelling in OPALX uses explicit sector magnets, optional trim coils, optional single-gap RF cavities, and a RING sequence. The current implementation is aimed at PSI-style separated-sector cyclotrons with field-map sectors in the horizontal X-Z plane and Y as the vertical direction.

13.1 Coasting Beam

A coasting-beam model contains magnetic sectors and no RF acceleration. Define named trim coils when needed, place each sector explicitly, assemble the sectors into a RING, and track a fixed number of directed returns.

TC1: TRIMCOIL, TYPE="PSI-BFIELD-MIRRORED",
     RMIN=4.350, RMAX=4.470, BMAX=1.4E-3, SLPTC=600.0;

SM0: CYCLOTRONSECTOR, FMAPFN="bfield.dat", SYM=8,
     RMIN=1.9, RMAX=4.7, VMIN=-0.05, VMAX=0.05,
     BSCALE=1, TRIMCOIL={"TC1"}, X=3.3, Y=0, Z=0,
     THETA=0, PHI=0, PSI=0;

MYCYCL: RING = (SM0, SM1, SM2, SM3, SM4, SM5, SM6, SM7);

FMAPFN names a PSI median-plane sector field map. SYM is the integer sector symmetry and must match the map span. If RMIN or RMAX is given, it must match the map bounds. VMIN and VMAX define the accepted vertical support. BSCALE multiplies only the base map; trim-coil fields are added after that scaling.

The sector pose is the entrance tangent at the map midpoint radius Rm=(RMIN+RMAX)/2. In an identity ring frame, sector k is placed at X=Rm*cos(k*2*pi/SYM), Z=Rm*sin(k*2*pi/SYM), and THETA=-k*2*pi/SYM. If the enclosing RING has a translated or rotated source frame, compose the sector pose with that frame.

Normal coasting tracking uses RUN,TURNS=n. The turn count is the number of directed reference-particle crossings of the launch plane, not a promise that the nominal geometry is exactly closed. The final step is shortened to the reference crossing, and the bunch advances to the same time. This requires completed emission, one beam and FIELDSOLVER, TYPE=NONE; repeat with smaller DT to establish transverse-orbit convergence.

13.2 Coasting Beam with Space Charge

Add a named binning definition and an open field solver to track a finite cyclotron bunch with space charge. The following fragment extends the magnetic MYCYCL ring defined above:

Dist0: DISTRIBUTION, TYPE=FROMFILE,
       FNAME="cyclotron-bunch.dat", NPARTDIST=262144;
Source0: EMISSIONSOURCE, DISTRIBUTION=Dist0;
Sources0: EMISSIONSOURCELIST=(Source0);

SCBin: BINNING, MAXBINS=1, PARAMETER=GAMMAZ,
       ADAPTIVEBINNING=FALSE;

FSOpen: FIELDSOLVER, TYPE=OPEN, BINS=SCBin,
        NX=32, NY=32, NZ=32,
        PARFFTX=TRUE, PARFFTY=TRUE, PARFFTZ=TRUE,
        BCFFTX=OPEN, BCFFTY=OPEN, BCFFTZ=OPEN,
        GREENSF=STANDARD, BBOXINCR=2;

Beam0: BEAM, PARTICLE=PROTON, NALLOC=262144,
       BCHARGE=3.9486673248e-11, SOURCES=Sources0, CHARGE=1;

TRACK, LINE=MYCYCL, BEAM=Beam0,
       DT=1.645278052e-10, MAXSTEPS=1600, ZSTOP=1e6;
  RUN, METHOD="PARALLEL", FIELDSOLVER=FSOpen,
       SCFIELDUPDATE="MIDPOINT";
ENDTRACK;

Explicit TURNS stopping is not supported with space charge. This example stops after the configured 1600 steps unless it reaches ZSTOP earlier; that schedule does not promise an exact return-plane crossing.

The example uses one explicit momentum bin so that positions and momenta are treated consistently in the beam-aligned space-charge frame. The quoted bunch charge corresponds to 2 mA at 50.65 MHz. The distribution file must contain the absolute launch coordinates and normalized momenta expected by OPALX.

The \(32^3\) mesh is deliberately coarse. Repeat the calculation with larger particle counts and independently refined mesh dimensions before drawing a physics conclusion. SCFIELDUPDATE="PRESTEP" selects the historical OPAL self-field sampling point for comparison; MIDPOINT remains the OPALX default. See Field Solvers and Space-charge field update point.

13.3 Accelerated Beam

An accelerated cyclotron model adds RFCAVITY, TYPE="SINGLEGAP" elements to the same RING. This model applies a radial voltage-profile kick when the reference particle crosses the gap plane in the positive local-z direction.

GAP0: RFCAVITY, TYPE="SINGLEGAP", FMAPFN="gap-profile.dat",
      VOLT=0.75, FREQ=50.6328, PHI0=35.0,
      RMIN=1.9, RMAX=4.7, GAPWIDTH=0.04,
      X=0.2386, Y=0, Z=-0.3407, THETA=-0.6108652382;

For a single-gap cavity, FMAPFN is a normalized voltage and derivative profile, not a 3D RF field map. VOLT is in MV, FREQ is in MHz, and PHI0 is in degrees. RMIN and RMAX are local-x profile bounds in metres. GAPWIDTH is the transit-time width in metres. ANGLE and PDIS must remain zero for this model, and automatic phasing is not used.

Use TRACK,EKINSTOP=<kinetic energy in GeV> when the run should stop at an energy target:

TRACK, LINE=MYCYCL, BEAM=BEAM0,
       DT=4.113195129976966e-11, MAXSTEPS=633600, EKINSTOP=0.590;
RUN, METHOD="PARALLEL", FIELDSOLVER=FS0;
ENDTRACK;

Tracking stops after the first complete RF kick that reaches or exceeds the requested kinetic energy. The energy is not clamped to the target value. The current energy-stop mode requires a non-restarted RING, one positive DT segment, no explicit RUN,TURNS, and a single cyclotron particle container.

13.4 Closed Orbit Finder

COF finds a fixed-energy closed orbit for a static magnetic RING. It is a named single-statement command, separate from TRACK. All tracking and solver settings belong on the same command; no RUN or ENDCOF is needed.

ic: COF, LINE=MYCYCL, BEAM=BEAM0,
     DT=1.0e-12, MAXSTEPS=200000, MAXPATH=40.0,
     TIMEINTEGRATOR="RK4", GEOMTOL=1e-9, ANGLETOL=1e-10,
     METHOD="NEWTON", X=0, PX=-0.00024, Y=0, PY=0,
     FDSTEP={1e-5,1e-6,1e-5,1e-6};

OUTPUT is optional and names one JSON file. Omit it for an in-memory result. Use TRACK, INITIALORBIT=ic for an orbit-local generated bunch; see the handover rules.

LINE must name a RING. BEAM must define an explicit reference momentum or energy through PC, ENERGY, or GAMMA, and must not use global processes. MAXPATH is required and bounds the return search. SECTION may override the return section as global X,Y,Z,THETA,PHI,PSI; otherwise the RING frame is used. The supported ray integrators are BORIS, LF2, RK4, and DOP853.

The current COF implementation supports static magnetic transport elements and CYCLOTRONSECTOR; it does not support restart mode, RF acceleration, space charge, or global particle processes.

13.5 Tune Calculation

RUN,SPECTRALTUNES=TRUE selects a serial two-ray coasting tune diagnostic. It uses fixed-energy rays in sector fields and bypasses normal bunch tracking and linear-map construction.

BEAM0: BEAM, PARTICLE=PROTON, NALLOC=1,
       BCHARGE=1.602176634e-19, SOURCES=SOURCES0, CHARGE=1,
       TUNEINITIAL={0.072,2.1314,-0.000240,
                    0.074,2.1551,-0.000296};

TRACK, LINE=MYCYCL, BEAM=BEAM0, MAXSTEPS=72000,
       DT=1.64527805199081e-10, STEPSPERTURN=720;
RUN, METHOD="PARALLEL", FIELDSOLVER=FS0, SPECTRALTUNES=TRUE,
     TURNS=100, TUNESAMPLE=50, TUNEINTEGRATOR="RK4", TUNESECTOR="SM0";
ENDTRACK;

TUNEINITIAL is a flat list of triples: kinetic energy in GeV, radius in metres, and radial momentum in units of mc. Each row launches a reference ray plus a second ray displaced radially and vertically. TUNESECTOR defines the launch centre and axes. There is no closed-orbit solve in this mode, so the supplied radius and radial momentum must already be appropriate for the requested energy.

The diagnostic currently requires one proton beam, one MPI rank, FIELDSOLVER TYPE=NONE, a non-restarted RING containing only CYCLOTRONSECTOR elements, and no RF elements or global particle processes. TURNS means nominal tune record length, not directed-return tracking. The output files are documented in File Formats.

See cyclotron physics for coordinate, interpolation, RF-kick, and spectral-analysis details.