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/container, and the restrictions listed under TURNS. Space charge is supported. 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 supported with space charge under the documented restrictions. The stopping plane is determined by the external-field reference particle. 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

Cyclotron with acceleration includes RFCAVITY, TYPE="SINGLEGAP" elements in the tracked RING together with its magnetic sectors. Each particle receives a radial voltage-profile kick at its own positive local-z crossing of the gap plane. The separately tracked reference determines an EKINSTOP event.

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 makes the reference reach or exceed the requested kinetic energy. The energy is not clamped to the target value. All physical particles finish the same accepted reference duration; reaching the target earlier does not stop an individual particle. The final RF endpoint includes a small floating-point allowance, described in energy-target semantics. 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.3.1 Accelerating bunch with space charge

Define the magnetic sectors and RF gaps in the same RING, then attach the solver on RUN. For accelerating runs, use the tracking schedule or EKINSTOP; omit explicit RUN,TURNS.

The configuration below extends the complete accelerating cyclotron input. Retain its sector and gap definitions, poses, RF settings, and the three map files bfield.dat, rffield1.dat, and rffield2.dat. Replace its distribution, source, beam, field-solver and tracking definitions with the following block. Provide cyclotron-bunch.dat FROMFILE distribution in the same launch coordinate frame; the map and distribution files are required inputs.

DistSC: DISTRIBUTION, TYPE=FROMFILE,
        FNAME="cyclotron-bunch.dat", NPARTDIST=64;
SourceSC: EMISSIONSOURCE, DISTRIBUTION=DistSC, T0=0;
SourcesSC: EMISSIONSOURCELIST=(SourceSC);

SCBin: BINNING, MAXBINS=1, PARAMETER=GAMMAZ,
       ADAPTIVEBINNING=FALSE;
FSOpen: FIELDSOLVER, TYPE=OPEN, BINS=SCBin,
        NX=16, NY=16, NZ=16,
        PARFFTX=TRUE, PARFFTY=TRUE, PARFFTZ=TRUE,
        BCFFTX=OPEN, BCFFTY=OPEN, BCFFTZ=OPEN,
        GREENSF=STANDARD, BBOXINCR=2;

BeamSC: BEAM, PARTICLE=PROTON, CHARGE=1,
        NALLOC=64, BCHARGE=1e-12, SOURCES=SourcesSC;

TRACK, LINE=MYCYCL, BEAM=BeamSC,
       DT=4.113195129976966e-11,
       MAXSTEPS=20000, ZSTOP=1e6, EKINSTOP=0.073;
  RUN, METHOD="PARALLEL", FIELDSOLVER=FSOpen,
       SCFIELDUPDATE="MIDPOINT";
ENDTRACK;

BCHARGE is in coulombs and NALLOC must match the intended charge. This coarse mesh and small sample illustrate the configuration; converge the mesh, particle count and timestep for the observables of interest.

The current accelerating-bunch implementation requires:

  • One positive-proton beam/container, with the default proton mass and no POLARIZATION attribute.
  • Magnetic CYCLOTRONSECTOR elements and at most 64 SINGLEGAP cavities.
  • A nonzero bunch charge for an active solver. Self fields are evaluated only when the particle count exceeds MINBINEMITTED, whose default is 10.
  • For EKINSTOP, a RING, one positive timestep segment, no explicit TURNS, and a target above the reference’s launch kinetic energy.

MIDPOINT samples self fields at predicted half-step positions; PRESTEP samples them at the step start. The reference is advanced in the applied fields and receives no space-charge kick. See the collective split and RF model and energy-target semantics.

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; an existing file is rejected. Omit it for an in-memory result. See the complete COF attribute table for solver defaults, tolerances, and iteration controls. 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. Use one positive DT segment, positive STEPSPERTURN, and integer TURNS and TUNESAMPLE values from 1 to 100000. Set MAXSTEPS to at least TURNS * STEPSPERTURN and retain at least 12 tune samples. 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.