BLCMDspacecharge Class Reference

Inheritance diagram for BLCMDspacecharge:

List of all members.

---

Detailed Description

class BLCMDspacecharge - space-charge computation This computation works within the Geant4 tracking framework, and does the computation in the various callbacks.

The algorithm tracks individual particles, and computes their field using macro-particles that are co-located with the tracked particles. So it computes E and B fields from the macro-particles and adds this in to the BLGlobalField, which Geant4 uses for tracking.

This computation uses a Poisson solver in the beam frame. The beam frame is determined from the reference particle's position and 4-momentum.

It is best to terminate the simulation with "trackcuts maxTime=...", or minActive=.... If it is terminated because particles leave the world or hit an object with kill=1, when the # particles in the bunch gets very low PoissonConvolve3D may not converge, aborting the run. Fortunately the NTuples wre written, so this is OK, it just looks ugly.

Note that fewer than minActive particles in the bunch is treated as a NORMAL way to end the simulation, not an error. But messages beginning with "***" are printed to alert the user that this happened.

This version requires the reference particle's momentum to be parallel to the z axis.

Public Member Functions
	BLCMDspacecharge ()
G4String	commandName ()
int	command (BLArgumentVector &argv, BLArgumentMap &namedArgs)
void	defineNamedArgs ()
virtual void	beginCollectiveTracking (std::vector< BLTrackData > &v)
virtual void	collectiveStep (std::vector< BLTrackData > &v)
virtual void	endCollectiveTracking (std::vector< BLTrackData > &v)
virtual void	PreUserTrackingAction (const G4Track *track)
	TrackingAction and SteppingAction are used only to get the points of each reference trajectory into bunch[]. PreUserTrackingAction() creates each Bunch object, seting currentBunch which is used by the others.
virtual void	PostUserTrackingAction (const G4Track *track)
virtual void	UserSteppingAction (const G4Step *step)
virtual void	addFieldValue (const G4double point[4], G4double field[6]) const
Private Attributes
G4double	deltaT
G4double	charge
G4int	nx
G4int	ny
G4int	nz
G4double	dx
G4double	dy
G4double	dz
G4double	maxBeta
G4int	verbose
G4int	ignoreFieldWhenTracking
G4int	useApproximationOnly
G4int	fixedGrid
double	percentile
int	nxApprox
int	nyApprox
int	nzApprox
int	minActive
BLManager *	manager
BLRunManager *	runManager
int	nstep
std::vector< Bunch >	bunch
Bunch *	currentBunch
bool	tracking

---

Constructor & Destructor Documentation

BLCMDspacecharge::BLCMDspacecharge

(

)

References BLCMDTYPE_PHYSICS, charge, currentBunch, deltaT, dx, dy, dz, fixedGrid, ignoreFieldWhenTracking, manager, maxBeta, minActive, nstep, nx, nxApprox, ny, nyApprox, nz, nzApprox, percentile, BLCommand::registerCommand(), runManager, BLCommand::setDescription(), BLCommand::setSynopsis(), tracking, useApproximationOnly, and verbose.

                                   : BLCollectiveComputation(),
                BLManager::SteppingAction(), BLManager::TrackingAction(),
                BLElementField(), bunch()
{
        registerCommand(BLCMDTYPE_PHYSICS);
        setSynopsis("Beam-frame Green's function space charge computation");
        setDescription("This is a space charge computation for bunched beams. "
                "It uses a grid in the beam frame to solve Poisson's equation "
                "via a Green's function with infinite boundary conditions; "
                "the E field is boosted back to the lab frame E and B for "
                "tracking.\n\n"
                "Macro-particles are used to enable the simulation of larger "
                "bunches than can be feasibly simulated as individual "
                "particles; the macro-particles have zero radius, "
                "but are pro-rated into the nearest eight grid points when "
                "placed into the grid. This computation can handle up to about "
                "a million macro-particles, but 100,000 is more sensible for "
                "all but the simplest physical situations.\n\n"
                "The bunch is created from the beam tracks before tracking "
                "begins. There is one bunch for each reference particle. "
                "Particles in the bunch must be the same particle as the "
                "reference, must initially be within {dx,dy,dz} of the "
                "reference particle, and when boosted to the reference "
                "particle's rest frame must initially have beta < maxBeta.\n\n"
                "After boosting the particles to the beam frame, they are "
                "placed into the grid, pro-rating to the eight nearest grid "
                "points. The grid is dynamically re-sized to keep the "
                "99th percentile of the particles between 0.5 and 0.67 of "
                "the grid size. This maintains a reasonable balance between "
                "resolution of grid points within the bunch and covering all "
                "of the particles. Particles located at >85% of the grid size "
                "do not contribute to the field computation, but are tracked "
                "using the field of the rest of the bunch (and other bunches)."
                "\n\n"
                "The grid has {nx,ny,nz} points; there is a small "
                "computational advantage to using powers of 2, but any values "
                ">1 can be used. For efficiency, the convolution of the "
                "Green's function with the charge grid is performed using "
                "FFTs; the grid is doubled in each dimension with the proper "
                "symmetry applied to the Green's function, so the cyclical "
                "convolution of the FFTs gives the proper potential with "
                "infinite boundary conditions.\n\n"
                "Outside the grid an approximation is used. An approximation "
                "grid is constructed, with the same size of the Poisson grid, "
                "but using {nxApprox,nyApprox,nzApprox} points. Particles are "
                "placed into this approximation grid, and the mean position "
                "is kept as well as the charge. Approximation grid points "
                "with less than 1% of the total charge are "
                "consolidated with their inner neighbors. The non-zero "
                "approximation grid points are treated as point charges when "
                "computing the potential outside the grid. For reasonably "
                "Gaussian bunches, {7,7,7} are reasonable values for the "
                "approximation grid sizes.\n\n"
                "The E field in the beam frame is computed via the derivatives "
                "of the linear interpolating function using the eight nearest "
                "grid points, and is boosted back to the lab "
                "frame E and B for tracking by the usual Geant4 routines.\n\n"
                "Bunch particles that get destroyed cease contributing to the "
                "bunch. As the bunch particles are selected during start-up, "
                "no additional particles are ever added to a bunch. This "
                "algorithm handles multiple bunches of any particle types.\n\n"
                "NOTE: For now, the reference MUST be parallel to the Z "
                "axis.");

        // initialize class variables here
        deltaT = -1.0;
        charge = -1.0;
        nx = 65;
        ny = 65;
        nz = 65;
        dx = -1.0;
        dy = -1.0; 
        dz = -1.0;
        maxBeta = 0.1;
        verbose = -1;
        ignoreFieldWhenTracking = 0;
        useApproximationOnly = 0;
        fixedGrid = 0;
        percentile = 99;
        nxApprox = 7;
        nyApprox = 7;
        nzApprox = 7;
        minActive = -95;
        manager = 0;    // not available yet -- set in command(...)
        runManager = 0; // not available yet -- set in command(...)
        nstep = 0;
        currentBunch = 0;
        tracking = false;
}

---

Member Function Documentation

G4String BLCMDspacecharge::commandName

(

)

[inline, virtual]

Implements BLCommand.

{ return "spacecharge"; }

int BLCMDspacecharge::command	(	BLArgumentVector &	argv,
		BLArgumentMap &	namedArgs
	)			[virtual]

Implements BLCommand.

References BLGlobalField::addElementField(), charge, deltaT, dx, dy, dz, BLParam::getInt(), BLGlobalField::getObject(), BLRunManager::getObject(), BLManager::getObject(), BLCommand::handleNamedArgs(), manager, nx, nxApprox, ny, nyApprox, nz, nzApprox, Param, BLCommand::print(), BLCommand::printError(), BLRunManager::registerCollectiveComputation(), BLManager::registerSteppingAction(), BLManager::registerTrackingAction(), runManager, BLRunManager::setCollectiveMode(), BLRunManager::setDeltaT(), Bunch::setUseApproximationOnly(), Bunch::setVerbose(), Bunch::testBfield(), Bunch::testEfield(), useApproximationOnly, and verbose.

{
        if(manager != 0) {
                printError("spacecharge - can be used at most once.");
                return -1;
        }

        handleNamedArgs(namedArgs);

        manager = BLManager::getObject();
        runManager = BLRunManager::getObject();

        if(verbose < 0) verbose = Param.getInt("steppingVerbose");
        if(verbose < 0) verbose = 0;
        Bunch::setVerbose(verbose);
        Bunch::setUseApproximationOnly(useApproximationOnly);

        if(nxApprox < 0) nxApprox = nx;
        if(nyApprox < 0) nyApprox = ny;
        if(nzApprox < 0) nzApprox = nz;

        if(charge <= 0.0 || deltaT <= 0.0)
                printError("spacecharge: charge and deltaT must both be > 0");
        if(dx <= 0.0 || dy <= 0.0 || dz <= 0.0)
                printError("spacecharge: dx, dy, and dz must all be > 0");

        runManager->registerCollectiveComputation(this);
        runManager->setCollectiveMode(true);
        runManager->setDeltaT(deltaT);

        manager->registerSteppingAction(this);
        manager->registerTrackingAction(this);

        BLGlobalField::getObject()->addElementField(this); // infinite bounding
                                                           // box 
        print("");

        Bunch::testEfield();
        Bunch::testBfield();

        return 0;
}

void BLCMDspacecharge::defineNamedArgs

(

)

[virtual]

Reimplemented from BLCommand.

References BLCommand::argDouble(), BLCommand::argInt(), charge, deltaT, dx, dy, dz, fixedGrid, ignoreFieldWhenTracking, maxBeta, minActive, nx, nxApprox, ny, nyApprox, nz, nzApprox, percentile, useApproximationOnly, and verbose.

{
        argDouble(deltaT,"deltaT","Time step (ns).",ns);
        argDouble(charge,"charge","Charge of macro particles (times particle charge).");
        argInt(nx,"nx","Number of grid points in x (65).");
        argInt(ny,"ny","Number of grid points in y (65).");
        argInt(nz,"nz","Number of grid points in z (65).");
        argDouble(dx,"dx","Max distance of particle to reference in x (mm)",mm);
        argDouble(dy,"dy","Max distance of particle to reference in y (mm)",mm);
        argDouble(dz,"dz","Max distance of particle to reference in z (mm)",mm);
        argInt(nxApprox,"nxApprox","# bins in x in approximation (7).");
        argInt(nyApprox,"nyApprox","# bins in y in approximation (7).");
        argInt(nzApprox,"nzApprox","# bins in z in approximation (7).");
        argDouble(maxBeta,"maxBeta","Max beta (v/c) of particle in beam frame (0.1).");
        argInt(verbose,"verbose","Non-zero for verbose prints (0).");
        argInt(ignoreFieldWhenTracking,"ignoreFieldWhenTracking","For testing only (0).");
        argInt(useApproximationOnly,"useApproximationOnly","For testing only (0).");
        argInt(fixedGrid,"fixedGrid","Nonzero prevents re-sizing the grid (0).");
        argDouble(percentile,"percentile","Percentile of charge distribution used for grid sizing (99).");
        argInt(minActive,"minActive","Minimum # active tracks in bunch; if "
             "< 0 is % of initial bunch size (-95).");
}       

void BLCMDspacecharge::beginCollectiveTracking

(

std::vector< BLTrackData > &

v

)

[virtual]

Reimplemented from BLCollectiveComputation.

References BLAssert, bunch, deltaT, nstep, nx, nxApprox, ny, nyApprox, nz, nzApprox, runManager, BLRunManager::setDeltaT(), and verbose.

{
        if(verbose >= 1) printf("BLCMDspacecharge::beginCollectiveTracking v.size=%d\n",(int)v.size());

        runManager->setDeltaT(deltaT);
        nstep = 0;

        // add tracks to Bunch-es
        std::map<G4ParticleDefinition*,int> orphans;
        int nactive=0, norphan=0;
        for(unsigned j=0; j<v.size(); ++j) {
                G4Track *track = v[j].track;
                G4TrackStatus trackStatus = track->GetTrackStatus();
                if(trackStatus != fAlive && trackStatus != fStopButAlive)
                        continue;
                ++nactive;
                bool match=false;
                for(unsigned i=0; i<bunch.size(); ++i) {
                        if(bunch[i].addTrack(track))
                                goto found;
                        if(track->GetDefinition() == bunch[i].getDefinition())
                                match = true;
                }
                ++orphans[track->GetDefinition()];
                if(match) ++norphan;
found:          continue;
        }


        for(unsigned i=0; i<bunch.size(); ++i) {
                BLAssert(bunch[i].init());
                printf("Bunch %d:\n",i);
                printf("        Bunch has %d tracks, minActive=%d\n",
                                    bunch[i].size(),bunch[i].getMinActive());
                G4ThreeVector b=bunch[i].getBound();
                printf("        Grid has nx,ny,nx=%d,%d,%d\n",nx,ny,nz);
                printf("        Initial Grid size: %.3f,%.3f,%.3f\n",
                                    b.x(),b.y(),b.z());
                printf("        Initial Approximation has nx,ny,nx=%d,%d,%d "
                                    " %d charges\n",nxApprox,nyApprox,nzApprox,
                                    bunch[i].getNapprox());
        }

        if(orphans.size() > 0) {
                printf("spacecharge: orphan tracks:");
                std::map<G4ParticleDefinition*,int>::iterator i;
                char sep=' ';
                for(i=orphans.begin(); i!=orphans.end(); ++i) {
                        printf("%c%d*%s",sep,i->second,
                                        i->first->GetParticleName().c_str());
                        sep = ',';
                }
                printf("\n");
        }
        if(norphan > nactive/1000)
                G4Exception("spacecharge","Too many orphan tracks",JustWarning,
                        "More than 0.1% of matching tracks not in any Bunch");
}

void BLCMDspacecharge::collectiveStep

(

std::vector< BLTrackData > &

v

)

[virtual]

Implements BLCollectiveComputation.

References bunch, nstep, and runManager.

{
        for(unsigned i=0; i<bunch.size(); ++i) {
                if(!bunch[i].computeField()) {
                        printf("***Ending computation\n");
                        runManager->AbortRun();
                        break;
                }
        }

        ++nstep;
}

void BLCMDspacecharge::endCollectiveTracking

(

std::vector< BLTrackData > &

v

)

[virtual]

Reimplemented from BLCollectiveComputation.

References nstep.

{
        printf("BLCMDspacecharge::endCollectiveTracking after %d time steps, v.size=%d\n",
                nstep,(int)v.size());
}

void BLCMDspacecharge::PreUserTrackingAction

(

const G4Track *

track

)

[virtual]

TrackingAction and SteppingAction are used only to get the points of each reference trajectory into bunch[]. PreUserTrackingAction() creates each Bunch object, seting currentBunch which is used by the others.

Implements BLManager::TrackingAction.

References bunch, charge, currentBunch, dx, dy, dz, fixedGrid, BLManager::getState(), manager, maxBeta, minActive, nx, nxApprox, ny, nyApprox, nz, nzApprox, percentile, REFERENCE, tracking, and verbose.

{
        tracking = true;
        currentBunch = 0;
        if(manager->getState() == REFERENCE && 
           track->GetDefinition()->GetPDGCharge() != 0.0) {
              bunch.push_back(Bunch(track->GetDefinition(),nx,ny,nz,dx,dy,dz,
                                charge,maxBeta,fixedGrid,percentile,
                                nxApprox,nyApprox,nzApprox,minActive));
              currentBunch = &bunch[bunch.size()-1];
              if(verbose >= 1) printf("spacecharge: starting Reference\n");
        }
}

void BLCMDspacecharge::PostUserTrackingAction

(

const G4Track *

track

)

[virtual]

Implements BLManager::TrackingAction.

References currentBunch, Bunch::nTrajectoryPoints(), tracking, and verbose.

{
        tracking = false;
        if(currentBunch == 0) return;

        if(currentBunch->nTrajectoryPoints() < 2)
                G4Exception("BLCMDspacecharge","Too few reference steps",
                        FatalException, "Reference particle took < 2 steps");
        currentBunch = 0;

        if(verbose >= 1) printf("spacecharge: ending Reference\n");
}

void BLCMDspacecharge::UserSteppingAction

(

const G4Step *

step

)

[virtual]

require the reference be parallel to the z axis

Implements BLManager::SteppingAction.

References Bunch::addReferencePoint(), and currentBunch.

{
        if(currentBunch == 0) return;

        G4Track *track = step->GetTrack();

        /// require the reference be parallel to the z axis
        G4ThreeVector direction = track->GetMomentumDirection();
        if(direction.perp() > 1.0e-9)
                G4Exception("BLCMDspacecharge","Invalid Bunch momentum",
                        FatalException, "Reference not parallel to z axis.");

        currentBunch->addReferencePoint(track);
}

void BLCMDspacecharge::addFieldValue	(	const G4double	point[4],
		G4double	field[6]
	)			const [virtual]

Implements BLElementField.

References BEAM, bunch, BLManager::getState(), ignoreFieldWhenTracking, manager, and tracking.

{
        if(manager->getState() != BEAM) return;
        if(ignoreFieldWhenTracking != 0 && tracking) return;

        for(unsigned i=0; i<bunch.size(); ++i) {
                bunch[i].addFieldValue(point,field);
        }
}

---

Member Data Documentation

G4double BLCMDspacecharge::deltaT [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), and defineNamedArgs().

G4double BLCMDspacecharge::charge [private]

Referenced by BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4int BLCMDspacecharge::nx [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4int BLCMDspacecharge::ny [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4int BLCMDspacecharge::nz [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4double BLCMDspacecharge::dx [private]

Referenced by BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4double BLCMDspacecharge::dy [private]

Referenced by BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4double BLCMDspacecharge::dz [private]

Referenced by BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

G4double BLCMDspacecharge::maxBeta [private]

Referenced by BLCMDspacecharge(), defineNamedArgs(), and PreUserTrackingAction().

G4int BLCMDspacecharge::verbose [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), PostUserTrackingAction(), and PreUserTrackingAction().

G4int BLCMDspacecharge::ignoreFieldWhenTracking [private]

Referenced by addFieldValue(), BLCMDspacecharge(), and defineNamedArgs().

G4int BLCMDspacecharge::useApproximationOnly [private]

Referenced by BLCMDspacecharge(), command(), and defineNamedArgs().

G4int BLCMDspacecharge::fixedGrid [private]

Referenced by BLCMDspacecharge(), defineNamedArgs(), and PreUserTrackingAction().

double BLCMDspacecharge::percentile [private]

Referenced by BLCMDspacecharge(), defineNamedArgs(), and PreUserTrackingAction().

int BLCMDspacecharge::nxApprox [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

int BLCMDspacecharge::nyApprox [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

int BLCMDspacecharge::nzApprox [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), command(), defineNamedArgs(), and PreUserTrackingAction().

int BLCMDspacecharge::minActive [private]

Referenced by BLCMDspacecharge(), defineNamedArgs(), and PreUserTrackingAction().

BLManager* BLCMDspacecharge::manager [private]

Referenced by addFieldValue(), BLCMDspacecharge(), command(), and PreUserTrackingAction().

BLRunManager* BLCMDspacecharge::runManager [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), collectiveStep(), and command().

int BLCMDspacecharge::nstep [private]

Referenced by beginCollectiveTracking(), BLCMDspacecharge(), collectiveStep(), and endCollectiveTracking().

std::vector<Bunch> BLCMDspacecharge::bunch [private]

Referenced by addFieldValue(), beginCollectiveTracking(), collectiveStep(), and PreUserTrackingAction().

Bunch* BLCMDspacecharge::currentBunch [private]

Referenced by BLCMDspacecharge(), PostUserTrackingAction(), PreUserTrackingAction(), and UserSteppingAction().

bool BLCMDspacecharge::tracking [private]

Referenced by addFieldValue(), BLCMDspacecharge(), PostUserTrackingAction(), and PreUserTrackingAction().

---

The documentation for this class was generated from the following file:

• BLCMDspacecharge.cc