OPAL (Object Oriented Parallel Accelerator Library) 2024.2
OPAL
CoreFitSC.h
Go to the documentation of this file.
1//
2// Namespace CoreFitSC
3// Core selection and far-field model for a space-charge mesh fitted to the bunch core
4// (OPAL-cycl, FFT solver).
5//
6// The mesh is fitted to the core: the live particles within nSigma clipped rms widths of
7// the clipped mean in every axis of the local space-charge frame. The clipped mean and rms
8// come from an iterated clip at clip rms widths that starts from the plain rms, so a few
9// particles far out in the halo neither stretch the mesh nor inflate its cell size. The
10// other particles ("far") are not deposited. Within the range of the mesh's cell centres
11// they are gathered from the mesh, as the core is. Outside it they get the rest-frame
12// monopole and quadrupole field of the core charge, or, where that expansion is not valid,
13// a direct sum over the core particles. Every far particle also gets a direct sum over the
14// other live far particles. The lab-frame transform is the one of the mesh field.
15//
16// Everything here is a pure function of its arguments. Global sums and minima go through
17// an injected Reducer, so the same code runs serially in the unit tests and on all ranks
18// in OPAL. Nothing is kept between calls: every selection starts from the plain rms, and
19// the result depends on the particle set only (and on the rank count only at round-off).
20// Positions are in the local space-charge frame in m, charges in C, and fields are
21// rest-frame fields without the coupling constant, sum q d / |d|^3 in C/m^2.
22//
23// Created by: Daniel Winklehner, MIT (2026)
24//
25// This file is part of OPAL.
26//
27// OPAL is free software: you can redistribute it and/or modify
28// it under the terms of the GNU General Public License as published by
29// the Free Software Foundation, either version 3 of the License, or
30// (at your option) any later version.
31//
32// You should have received a copy of the GNU General Public License
33// along with OPAL. If not, see <https://www.gnu.org/licenses/>.
34//
35#ifndef CLASSIC_COREFITSC_H
36#define CLASSIC_COREFITSC_H
37
38#include "Algorithms/Vektor.h"
39
40#include <array>
41#include <cstddef>
42#include <cstdint>
43#include <utility>
44#include <vector>
45
46namespace CoreFitSC {
47
50 constexpr unsigned int maxClipPasses = 8;
52 constexpr double clipTolerance = 1e-3;
54 constexpr double haloSigma = 10.0;
59 constexpr double flatWidth = 1e-10;
62 constexpr double indicatorThreshold = 0.1;
66 constexpr double maxFarFarPairs = 1e8;
72 constexpr double maxCorePairsPerCore = 8;
75 constexpr double coreShellFraction = 0.25;
77 constexpr double warnFarFraction = 0.01;
78
84 constexpr double minCoreParticles = 1000;
85 constexpr double minCoreFraction = 0.5;
86 constexpr double returnCoreFraction = 0.6;
87 constexpr double returnFarFactor = 0.5;
88
93 class Reducer {
94 public:
95 virtual ~Reducer() = default;
97 virtual void sum(double* values, unsigned int count) const = 0;
99 virtual void min(double* values, unsigned int count) const = 0;
100 };
101
103 class SerialReducer: public Reducer {
104 public:
105 void sum(double*, unsigned int) const override { }
106 void min(double*, unsigned int) const override { }
107 };
108
110 class IpplReducer: public Reducer {
111 public:
112 void sum(double* values, unsigned int count) const override;
113 void min(double* values, unsigned int count) const override;
114 };
115
123 std::size_t numLive = 0;
124 std::size_t numCore = 0;
125 std::size_t numFar = 0;
126 std::size_t numHalo = 0;
127 double chargeLive = 0.0;
128 double chargeFar = 0.0;
129 double farMaxDistance = 0.0;
131 unsigned int passes = 0;
132 bool converged = false;
133
135 double getFarChargeFraction() const;
136 };
137
151 CoreSelection selectCore(const Vector_t* R, const double* Q, const int* bin,
152 std::size_t localNum, double nSigma, double clip,
153 const Reducer& reducer);
154
166 void getMeshBox(const Vector_t* R, const int* bin, std::size_t localNum,
167 const CoreSelection& selection, double nSigma, const Reducer& reducer,
168 Vector_t& boxMin, Vector_t& boxMax);
169
171 inline bool isInside(const Vector_t& r, const Vector_t& lower, const Vector_t& upper) {
172 return (r[0] >= lower[0] && r[0] <= upper[0] &&
173 r[1] >= lower[1] && r[1] <= upper[1] &&
174 r[2] >= lower[2] && r[2] <= upper[2]);
175 }
176
179 enum class ParticleClass: short {
180 CORE,
181 INSIDE,
182 MESH,
184 FAR
185 };
186
191 ParticleClass classify(int bin, const Vector_t& r,
192 const Vector_t& boundsMin, const Vector_t& boundsMax,
193 const Vector_t& meshMin, const Vector_t& meshMax);
194
198 inline Vector_t toRestFrame(const Vector_t& r, const Vector_t& r0, double gamma) {
199 return Vector_t({r[0] - r0[0], gamma * (r[1] - r0[1]), r[2] - r0[2]});
200 }
201
205 inline Vector_t toLabFrame(const Vector_t& E, double gamma) {
206 return Vector_t({gamma * E[0], E[1], gamma * E[2]});
207 }
208
210 struct CoreMoments {
211 double charge = 0.0;
213 std::array<Vector_t, 3> quadrupole;
215 };
216
220 public:
221 MomentSums(const Vector_t& centre, double gamma);
222
224 void add(double q, const Vector_t& r);
225
227 CoreMoments reduce(const Reducer& reducer) const;
228
229 private:
231 double gamma_m;
232 std::array<double, 10> sums_m;
233 };
234
245 void computeMultipoleField(const CoreMoments& moments, const std::vector<Vector_t>& position,
246 std::size_t begin, std::size_t end, bool withQuadrupole,
247 std::vector<Vector_t>& field, std::vector<double>& indicator);
248
252 inline bool needsExactCoreField(ParticleClass c, double indicator) {
253 return c == ParticleClass::FAR && indicator > indicatorThreshold;
254 }
255
263 void addDirectField(const std::vector<Vector_t>& target, std::size_t begin, std::size_t end,
264 const std::vector<Vector_t>& source, const std::vector<double>& charge,
265 double eps, std::vector<Vector_t>& field);
266
269 std::pair<std::size_t, std::size_t> getTableRange(std::size_t n, int rank, int numRanks);
270
275 std::size_t getSampleStride(std::size_t numTargets, std::size_t numSources,
276 double maxPairs);
277
281 bool isInCoreShell(const Vector_t& r, const Vector_t& lower, const Vector_t& upper);
282
290 inline bool isSampled(std::size_t id, std::size_t stride) {
291 if (stride <= 1) {
292 return true;
293 }
294 std::uint64_t z = id + 0x9E3779B97F4A7C15ULL;
295 z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9ULL;
296 z = (z ^ (z >> 27)) * 0x94D049BB133111EBULL;
297 return (z ^ (z >> 31)) % stride == 0;
298 }
299
302 enum class Mode: short {
303 FULL = 0,
304 CORE = 1
305 };
306
311 struct ModeState {
313 unsigned int dwell = 0;
314 };
315
324 ModeState decideMode(const ModeState& previous, std::size_t numCore, std::size_t numLive,
325 double farChargeFraction, double maxFarFraction, unsigned int minDwell);
326}
327
328#endif
PartBunchBase< T, Dim >::ConstIterator end(PartBunchBase< T, Dim > const &bunch)
PartBunchBase< T, Dim >::ConstIterator begin(PartBunchBase< T, Dim > const &bunch)
constexpr double returnCoreFraction
Definition CoreFitSC.h:86
CoreSelection selectCore(const Vector_t *R, const double *Q, const int *bin, std::size_t localNum, double nSigma, double clip, const Reducer &reducer)
Definition CoreFitSC.cpp:89
constexpr double returnFarFactor
Definition CoreFitSC.h:87
constexpr double coreShellFraction
Definition CoreFitSC.h:75
bool isInside(const Vector_t &r, const Vector_t &lower, const Vector_t &upper)
True if r lies in [lower, upper] in every axis.
Definition CoreFitSC.h:171
constexpr double maxFarFarPairs
Definition CoreFitSC.h:66
constexpr double flatWidth
Definition CoreFitSC.h:59
constexpr double indicatorThreshold
Definition CoreFitSC.h:62
constexpr double maxCorePairsPerCore
Definition CoreFitSC.h:72
constexpr double warnFarFraction
The solve warns when the far charge fraction exceeds this.
Definition CoreFitSC.h:77
void addDirectField(const std::vector< Vector_t > &target, std::size_t begin, std::size_t end, const std::vector< Vector_t > &source, const std::vector< double > &charge, double eps, std::vector< Vector_t > &field)
ModeState decideMode(const ModeState &previous, std::size_t numCore, std::size_t numLive, double farChargeFraction, double maxFarFraction, unsigned int minDwell)
constexpr double haloSigma
The halo proper: live particles beyond haloSigma clipped rms widths in any axis.
Definition CoreFitSC.h:54
ParticleClass classify(int bin, const Vector_t &r, const Vector_t &boundsMin, const Vector_t &boundsMax, const Vector_t &meshMin, const Vector_t &meshMax)
constexpr double minCoreFraction
Definition CoreFitSC.h:85
void computeMultipoleField(const CoreMoments &moments, const std::vector< Vector_t > &position, std::size_t begin, std::size_t end, bool withQuadrupole, std::vector< Vector_t > &field, std::vector< double > &indicator)
std::pair< std::size_t, std::size_t > getTableRange(std::size_t n, int rank, int numRanks)
bool isInCoreShell(const Vector_t &r, const Vector_t &lower, const Vector_t &upper)
constexpr unsigned int maxClipPasses
Definition CoreFitSC.h:50
constexpr double minCoreParticles
Definition CoreFitSC.h:84
bool needsExactCoreField(ParticleClass c, double indicator)
Definition CoreFitSC.h:252
void getMeshBox(const Vector_t *R, const int *bin, std::size_t localNum, const CoreSelection &selection, double nSigma, const Reducer &reducer, Vector_t &boxMin, Vector_t &boxMax)
@ FAR
outside that range: multipole (or exact core) field, plus far-far
@ INSIDE
lost (Bin < 0), inside the core bounds: gathered, not deposited
@ CORE
live, inside the core bounds: deposited, field gathered from the mesh
bool isSampled(std::size_t id, std::size_t stride)
Definition CoreFitSC.h:290
std::size_t getSampleStride(std::size_t numTargets, std::size_t numSources, double maxPairs)
Vector_t toRestFrame(const Vector_t &r, const Vector_t &r0, double gamma)
Definition CoreFitSC.h:198
constexpr double clipTolerance
The clipped passes stop when |dsigma_d| < clipTolerance * sigma_d in every axis.
Definition CoreFitSC.h:52
Vector_t toLabFrame(const Vector_t &E, double gamma)
Definition CoreFitSC.h:205
virtual ~Reducer()=default
virtual void sum(double *values, unsigned int count) const =0
Sums over all ranks.
virtual void min(double *values, unsigned int count) const =0
Minima over all ranks (maxima are the minima of the negated values)
All particles on one process: the reductions do nothing.
Definition CoreFitSC.h:103
void min(double *, unsigned int) const override
Minima over all ranks (maxima are the minima of the negated values)
Definition CoreFitSC.h:106
void sum(double *, unsigned int) const override
Sums over all ranks.
Definition CoreFitSC.h:105
All IPPL nodes, through allreduce().
Definition CoreFitSC.h:110
void sum(double *values, unsigned int count) const override
Sums over all ranks.
Definition CoreFitSC.cpp:74
void min(double *values, unsigned int count) const override
Minima over all ranks (maxima are the minima of the negated values)
Definition CoreFitSC.cpp:79
Result of selectCore(), the same on every rank.
Definition CoreFitSC.h:117
unsigned int passes
clipped passes done, 0 to maxClipPasses
Definition CoreFitSC.h:131
double getFarChargeFraction() const
Far charge over live charge, 0 without live charge.
Definition CoreFitSC.cpp:84
bool converged
false if the passes stopped at maxClipPasses
Definition CoreFitSC.h:132
std::size_t numLive
particles with Bin >= 0
Definition CoreFitSC.h:123
double chargeFar
charge of the far live particles [C]
Definition CoreFitSC.h:128
Vector_t boundsMin
minimum over the core particles [m]
Definition CoreFitSC.h:120
Vector_t mean
clipped mean [m]
Definition CoreFitSC.h:118
std::size_t numFar
the other live particles
Definition CoreFitSC.h:125
Vector_t sigma
clipped rms [m]
Definition CoreFitSC.h:119
std::size_t numHalo
live particles beyond haloSigma * sigma in any axis
Definition CoreFitSC.h:126
double chargeLive
charge of the live particles [C]
Definition CoreFitSC.h:127
std::size_t numCore
live particles within nSigma * sigma in every axis
Definition CoreFitSC.h:124
Rest-frame moments of the core charge.
Definition CoreFitSC.h:210
Vector_t centroid
c', rest frame, about the centre [m]
Definition CoreFitSC.h:212
double charge
Q_c [C].
Definition CoreFitSC.h:211
std::array< Vector_t, 3 > quadrupole
Definition CoreFitSC.h:213
void add(double q, const Vector_t &r)
Adds a particle of charge q at r (local frame, not rest frame)
std::array< double, 10 > sums_m
Definition CoreFitSC.h:232
CoreMoments reduce(const Reducer &reducer) const
Moments of all ranks' particles: one sum of 10 doubles.
unsigned int dwell
Definition CoreFitSC.h:313
Vektor< double, 3 > Vector_t
Definition Vektor.h:6