MagneticFieldMaps
Introduction
The Mu2e magnetic field maps are found in two places
/grid/fermiapp/mu2e/DataFiles/BFieldMaps /cvmfs/mu2e.opensciencegrid.org/DataFiles/BFieldMaps
The first location is deprecated and will eventually go away. Both locations are visible on detsim, GPCF and all GPGrid worker nodes. All Mu2e code, including Offline, G4beamline and MARS should use these magnetic field maps and not field maps stored in private disk space.
The Mu2e cvmfs partition is mounted on all OSG worker nodes, including off-site nodes. You may mount the Mu2e cvmfs partition at remote sites such as your home institution or your laptap. For details see the Mu2e cvmfs page .
As of August December 2015, the recommended magnetic field maps are in:
/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau9 /cvmfs/mu2e.opensciencegrid.org/DataFiles/BFieldMaps/Mau9
What's up with the "b"? What happened to plain old Mau7? The answer is that the field map .txt files in Mau7b are identical to those in Mau7. However there has been a change in the format of the binary files that are dervied from the .txt files; these issues are described in Appendix II and Appendix III .
The Mau7 (and Mau7b) field maps are
the first maps computed after the removal of the return yoke and the tilting of
the coils around the y axis to compensate for the absence of the iron.
The other magnetic field maps are of
#appendixI historical interest and will be described below .
The Mau series of maps are named after Mauricio Lopes from Fermilab
Technical Division (TD) who computed them using Opera3D.
Within the Mau7b subdirectory there are ten .txt files, each of which contains a magnetic field map for some region of the Mu2e detector or hall. These files are organized into three groups. The first group includes the files:
Mu2e_DSMap.txt Mu2e_PSMap.txt Mu2e_TSdMap.txt Mu2e_TSuMap.txt
Each of these files contains a field map consisting of field values specified on a 3D grid; each map describes the field in a region of the muon beamline encoded in the name of the file; these regions of validity include the vacuum volume, the surrounding coils and a small amount of the space surrounding that. The four field map regions touch each other but do not overlap. These files are written in a format defined by G4beamline but all Mu2e code is capable of reading this format.
The second group of files includes,
ProtonDumpAreaMap.txt PStoDumpAreaMap.txt
These files are also touching but not overlapping with the other four files and with each other; they extend the field map from the PS to the proton dump and extinction monitor areas. Together these six files should be viewed as making a continguous map with an odd shaped outer boundary. The last two files specify the field on a coarser grid than do the first four files; in these regions the fields have shallow gradients so a coarser map is adequate.
The third group of files includes,
BFieldMaps/Mau7b/ExtMonUCIInternal1AreaMap.txt BFieldMaps/Mau7b/ExtMonUCIInternal2AreaMap.txt BFieldMaps/Mau7b/ExtMonUCIAreaMap.txt BFieldMaps/Mau7b/PSAreaMap.txt
These four field maps may overlap, both with each other and with the field maps in the first two groups. The first two of these four maps are used in the region of the extinction monitor that is being designed by the UC Irvine group; these files use a fine grid. The last two files are used to track cosmic rays and to look up the field in regions of the hall where electronics or photosensors may be located; these files use a coarse grid.
The file ExtMonUCIAreaMap.txt does not overlap any of the maps in groups 1 or 2; it does, however, overlap the two ExtMonUCIInternal maps. Therefore, when the two UCI internal maps are present, ExtMonUCIAreaMap belongs in group 3, not group 2.
Additional information about these field maps, including drawings of the regions of validity, is available in Mu2e-doc-2072 .
These .txt files are the single authoritative source for our magnetic field maps and they are used by all of our software, Offline, G4beamlnie and MARS.
Starting with version Mau10, the UCI field maps will no longer be made because they are no longer needed. There will never be UCI field maps in the GA series of maps.
Definition: Inner and Outer Maps
The Mu2e code and run-time configuration uses the notation "inner" and "outer" maps. By defintion, an inner map does not overlap with any other inner map while an outer map may overlap both with other outer maps and with any inner map. Therefore the first six maps listed above are inner maps while the last four maps listed above are outer maps.
This distinction of inner and outer maps is important in the algorithm used to look up the magnetic field at a given point. The Mu2e code first checks the inner maps to see if the point is inside one of those maps; if the code finds the point within a map, it computes the field value and returns it. By definition, the code will find the requested point in either none or exactly one of the inner maps. If the Mu2e code does not find the point inside one of the inner maps, it will then search the outer maps. While it is possible for the point to be inside more than one outer map, the Mu2e code will accept the first positive result and will return the field computed from that map.
When looking up the field value in the inner maps, the Mu2e code first checks the most recently used inner map and, if that fails, the code tries the remaining inner maps in the order specified in the run-time configuration file. Almost always the code will find the point in the most recently used map.
Variants on the Standard Field Maps
As of August 2012, there are five variants on the Mau7b magnetic field maps. There are found in the following directories,
/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7b/4T
Mau7b/5T
Mau7b/DS_70Percent
Mau7_NegativeGradient_v1
Mau7b/ExtMonUCIInternal1
The files in these directories were created as needed for particular studies; only the maps needed for those studies were recreated. The directories 4T and 5T each contain a subset of the Mau7b field maps, recomputed with magnet currents such that the peak field in the PS is, respectively, 4 Tesla or 5 Tesla; these field maps are used to study the change in the stopped muon yield if we can run the PS at higher than design field or if we are forced to run it at lower than design field. According to Mau, the DS field map from the standard Mau7b area can be used with either the 4T or 5T files; the PS coils are too far from the DS to significantly affect the field in the DS.
The directory DS_70Percent contains a subset of the Mau7b field maps, recomputed with the currents such that the field in the uniform-field region DS is 70 percent of its nominal value. This field map is used to study calibration of the absolute momentum scale of the detector using the monoenergetic positrons produced from pi+ decay at rest from pi+ that range out in the foils of the stopping target. According to May, the PS field map from the standard Mau7b area can be used with these maps.
The directory Mau7_NegativeGradient_v1 contains a map of the DS field in which the coil currents have been changed to create a small negative gradient in the region of the DS that has a nominally uniform field. This field has been used in a study to see if the adding a small negative gradient signifcantly reduces the incidence of particles that become trapped in the (very shallow) wells in Bz.
The files in the subdirectory Mau7b/ExtMonUCIInternal1 are used by the extinction monitor group at UC Irvine. See Zhengyun You for details.
File Formats
Text Format
The G4beamline defined format is an all text format that consists of a header, terminated by a line that contains only the word "data", followed by a series of lines in the format
x y z Bx By Bz
where the positions are given in mm and the field values in T. Starting with Mau7, the positions are given in the [1] Mu2e coordinate system</a>. Previously they were given in the Mu2e G4beamline coordinate system, whose origin, specified in the Mu2e Coordinate system is at (3904.,0.,-7929) mm. These coordinate system have parallel axes. For all files, the magnetic field components have they same meaning ( since the axes of the two coordinate systems are parallel ).
In the header,
comments begin with a # sign in the first column. The comment
# Origin shift for Mu2e: 0. 0. 0.
is meaningful for the Offline but not for G4beamline. I don't know if it is meaningful for MARS. This comment informs the Mu2e Offline program that space point in the map are specified in a coordinate system whose origin, as specified in the Mu2e system, is the value indicated.
If this structured comment is absent, the Mu2e Offline software uses a default value of (3904,0.,-7929.). In versions of the field maps prior to Mau7, the comment is absent and the space points are specified in the Mu2e G4beamline system. The convention defined here allows the old field map files to be usable, without modification, by both old and new versions of Offline.
In the header, I don't know the meaning of the line that begins with "param". The line that begins with "grid" defines the grid points. The grid spacing is regular and the points form a complete box. The line that begins "extendY" says that the grid points are given only for values of y greater than or equal to 0.; to compute the field at -y, the algorithm is to compute the field at +y and flip the sign of By. This sign flip algorithm is hard coded into the Offline code but, in G4beamline, is driven by the value of the extendY keyword. I don't know whether MARS has this hardcoded or not.
When the field map files are delivered by Mau they only contain the grid points and field values. We insert the headers by hand.
Binary Format
For Mu2e Offline there is a second file format, the binary format. This format is useful because reading the text files takes about one minute of CPU time while reading the binary format files takes seconds. The .txt files remain the authoritative format and the binary files are derived from them.
For each .txt file, the binary format consists of two files that have the same base name as the .txt file, for example from the Mau7 maps:
Mu2e_PSMap.bin Mu2e_PSMap.header
The file Mu2e_PSMap.header is simply a copy of the header information from Mu2e_PSMap.txt, up to and including the "data" line. The .bin file contains the field values at the grid points in binary format; it is simply an image of these numbers in memory. The details of the binary file format are given in #appendixII Appendix II .
BZipped Format
The Offline code is also capable of reading bzipped text files. For example, from the Mau5 maps:
Mu2e_DSMap.txt.bz2 Mu2e_PSMap.txt.bz2 Mu2e_TSdMap.txt.bz2 Mu2e_TSuMap.txt.bz2
These files were made by bzipping the .txt files. Compared to the .txt files, it takes much longer to read these files; however they could be useful in the event of a slow network connection.
As of Mau7, we no longer routinely make the .bz2 files. We can make them on request. We reserve the right to delete the existing .bz2 files without notice should we need to recover disk space.
Selecting Field Maps
Selecting Field Maps in Mu2e Offline
The following fragment from Mu2eG4/test/geom_01.txt shows the default choice of magnetic field maps:
string bfield.format = "G4BL";
vector<string> bfield.innerMaps = {
"BFieldMaps/Mau7b/Mu2e_DSMap.header",
"BFieldMaps/Mau7b/Mu2e_PSMap.header",
"BFieldMaps/Mau7b/Mu2e_TSuMap.header",
"BFieldMaps/Mau7b/Mu2e_TSdMap.header",
"BFieldMaps/Mau7b/PStoDumpAreaMap.header",
"BFieldMaps/Mau7b/ProtonDumpAreaMap.header"
};
vector<string> bfield.outerMaps = {
"BFieldMaps/Mau7b/ExtMonUCIInternal1AreaMap.header",
"BFieldMaps/Mau7b/ExtMonUCIInternal2AreaMap.header",
"BFieldMaps/Mau7b/ExtMonUCIAreaMap.header",
"BFieldMaps/Mau7b/PSAreaMap.header"
};
The bfield.format variable says that the field is given in the G4beamline format; this includes all three of the text, binary and bzipped representations. The alternative value is obsolete and selects an ancient MECO binary format ( which is very different from our binary format ).
The bfield.innerMaps and bfield.outerMaps variables specify the list of field map files to read; the meaning of #innerOuter inner and outer maps is defined above. In principal one need only include the field maps for the spatial regions of interest for a particular job; however the present recommendation is to always read all maps.
The Mu2e Offline program searches for the map files in the path defined by the environment variable [FileSearchPaths.shtml MU2E_SEARCH_PATH] .
If a filename ends in .txt, then the code will simply open the .txt file, read it and build the in-memory map. If a filename ends in .header, then the code will open the file and read it to extract the meta data; it will then reserve enough space to hold the in-memory map and read the corresponding .bin file directly into the reserved memory. If a filename ends in .bz2, then the code will decompress the file memory and read it to build the in-memory map.
By far the fastest method is to chose the binary files by specifying the header file in the above lists.
Selecting Field Maps in G4beamline
See the Mu2e G4beamline Manual .
Selecting Field Maps in MARS
Contact Vitaly Pronskikh.
Installing New Files and Making the Binary Files
Do not delete or overwrite old versions of the field maps: disk space is cheap and the ability to reproduce previous results is critical. Always add new files following the version pattern that is already present.
- If Mau sends us a variant on an existing field, make a subdirectory and put the new files in there. For example, Mau7b/4T and Mau7b/5T.
- If Mau sends us a new field, increment the counter in the name, Mau4, Mau4, Mau7 and so on.
- If we produce variants of our derived file formats, increment the version character, Mau7b, Mau7c and so on.
To install a new field map, and to make the binary files for that map, follow
these steps:
- Get the .txt files from Mau.
- If necessary, construct the headers and insert them at the start of the .txt files. Don't blindly copy the headers from previous files: check to see whether or not they actually describe the new file correctly.
- Put the .txt files in /grid/fermiapp/mu2e/DataFiles/BFieldMaps/XXXX, where XXXX is the directory name for the new map.
- Edit geom_01.txt
- Specify the new .txt files.
- Add the parameter: bool bfield.writeG4BLBinaries = true;
- Run mu2e using the modified geom_01.txt. It will write the .bin files to the local directory. You should use one of the standard test jobs, such as Mu2eG4/test/g4test_03.fcl and check that the output makes sense.
- Move the .bin files to /grid/fermiapp/mu2e/DataFiles/BFieldMaps/XXXX.
- Extract the header information from each .txt file to make the corresponding .header files.
- Edit geom_01.txt to replace .txt with .header for the files listed in bfield.innerMaps and bfield.outerMaps.
- Test that mu2e runs correctly with the binary files. You can do this by comparing the output of this step with the output of step 5.
- Commit geom_01.txt and announce to mu2e-sim.
Appendix I: Ancient History
This section describes obsolete BField maps. They are arranged in chronological order of their creation. The names below are subdirectories within /grid/fermiapp/mu2e/DataFiles/BFieldMaps
MECO
These files are the GMC field maps taken from MECO in June 2009. They are in a MECO defined format that is used by no other set of Mu2e field maps.
These files have B_z along the -z direction; this is the opposite of all other Mu2e field maps. Also the bend radius of the TS is 2926 mm for these maps but 2929 mm for all other maps.
To read these files, you need to use the geometry file:
Mu2eG4/test/geom_mecofield.txt
This file includes the standard geom_01.txt and makes the changes necessary to use the MECO field maps. The comments in the file explain which changes need to be made and why.
These files are also specified on a box-shaped grid but not every grid point in the box is present in the map. In each file the grid points define a box but only the stepped approximation to the inside of a cylinder has grid points present; the outer parts are missing.
There is no additional documentation about the format of these files, other than that found in the code itself.
G4BL_v0
These files are G4beamline format files that were created by Mike Martens in 2007 or 2008. The field was computed by Mike from the MECO coil placements and currents. There is no iron in this field model.
In this model, and all subsequent models, B_z is along the +z direction and the bend radius of the TS is 2929 mm.
MECO_RotatedCoils
This might be the short PS version? The DS map is identical to the G4BL_v0 version. Check with Rick Coleman to be sure.
Mau3, Mau4 and Mau5
Various versions of the field calculations by Mau. Contact Mau, or perhaps Rick Coleman, for details. I know that the variations include the shorter PS, different coil positions and fewer coilse. I believe that all versions have some iron present.
There is no Mau6 map; before it was finalized, the decision was made to remove the return yoke. So that calculation was suspended and the version with no return yoke is Mau7 (and Mau7b).
Appendix II: Details of the Binary Files
Starting with the Mau7b field maps, the in-memory representation of each field map is:
mu2e::Container3D<CLHEP::Hep3Vector> _field;
where mu2e::Container3D is a very crude 3D-array class template. Internally mu2e::Container3D<T> holds its information as
std::vector<T>
and it has accessors/modifers to manage the transformation between a 3D index and a location in the 1D std::vector.
The binary files are written using 2 calls to cstdio write. The first write is the 4 bytes:
unsigned int deadbeef(0XDEADBEEF);
This serves as an endian marker. The second call writes out all of the _field std::vector in a single call to cstdio write.
On readback, the code first reads the endian marker and checks it. If the check fails, the job stops with an appropriate error message. The code then allocates an object of type mu2e::Container3D<CLHEP::Hep3Vector> with the internal std::vector sized correctly. It then uses a calls to cstdio read to move the contents of the disk file into memory. There is no attempt to dynamically correct wrong-endian-ness; we can add that if it becomes necessary.
There is no attempt to detector correct the following problem: the binary files are written on one machine that has a particular representation of the built-in type double but are read on a second machine that uses a different representation for double. Here "different representation" refers to more than just an endian difference. Should this become an issue, we will deal with it at that time.
=The Old Binary Format
Up to and including the Mau7 field maps, the in-memory representation of each field map contained contained both the field value and the associated grid point:
mu2e::Container3D<CLHEP::Hep3Vector> _gridPoint; mu2e::Container3D<CLHEP::Hep3Vector> _fieldValue;
This representation is wasteful of memory: because the grid is regular and has no holes, the postion of any grid point can always be computed using the parameters of the grid and the 3-integer index of the point. The code was changed to exploit this feature and to remove the need for the array of grid points.
Binary files of this format are written with 3 calls to stdio write: one for the endian marker, one for the array of grid point positions and one for the array of field values. The readback is done as above with the addition of one extra call to stdio read to read in the positions of the grid points.
Appendix III: Mau7 vs Mau7b
The four core authoritative files
Mu2e_DSMap.txt Mu2e_PSMap.txt Mu2e_TSdMap.txt Mu2e_TSuMap.txt
are identical in Mau7 and Mau7b. The binary file format was updated between Mau7 and Mau7b; see #appendixII Appendix II .
We have kept both Mau7 and Mau7b so that it is possible to reproduce results that used the Mau7 field without having to produce a hacked version of the old code that allows it to read the new binary field map format.
Appendix IV: Variants on Mau7
Mau has prepared several variants on the Mau7 field. These are stored in:
/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7_NegativeGradient_v1 /grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7_NegativeGradient_v2 /grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7b/4T/ /grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7b/5T/ /grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau7b/DS_70Percent
In all cases, the binary files are in the same format as Mau7b.
In the first two cases, only the DSMap is present, in both text and binary formats. The changes to the other maps are small enough that there is no reason to recompute them. It is legal to load the DSMap from one of these two areas and all other files from Mau7b.
In the region of the tracker and calorimeter, the standard Mau7 field is designed to be as close to uniform as possible. In the variant v1, the field is designed to have a negative gradient in Bz of approximately 2%. In the variant v2, the field is designed to have a negative gradient in Bz of approximately 5%.
The last three files have complete sets of DS, PS, TSu and TSd maps. The 4T (5T) files describe a PS in which the peak field is 4T (5T); the DS_70Percent files describe a DS in which the uniform region of the field is 0.7T. If you load either the 4T or 5T files, it probably does not make much sense to load the other 6 files from Mau7b.
Appendix V: Mau8
This field was released in January 2013 and has been available for use since January 18, 2013. It is similar to the Mau7 field but has approximately a 4% gradient across the nominal uniform region of the DS. All 10 maps are present.
It has not yet been made the
default in any of our codes. It will become the default after it has been tested more thoroughly and after people who need to continue to use the older field are told how to do so.
Appendix VI: Mau8a
This release fixes a small bug in Mau8.
Appendix VII: Mau9
This field map was release on July 5, 2013:
We have just updated the mu2e magnetic design. In this new release (version 9) we modified the angle of 16 coils of the second curve to have the beam better centered with respect to the DS axis, per request of Jim Miller. The details of the coils geometries as well as the Lorentz forces under different power scenarios can be found in docdb#2632. The field maps can be found in docdb#1760. Rob Kutschke will make those field maps available in the framework. If you have any question, please let me know.
The available variants on Mau9 are:
- DS coils powered at 50% strength: BFieldMaps/Mau9/50Percent
- DS coils powered at 70% strength: BFieldMaps/Mau9/DS_70Percent
- DS coils powered at 85% strength: BFieldMaps/Mau9/DS_70Percent
- Mau did a study in which he randomized DS coil locations (and currents?)
within nominal tolerances. He computed the DS field maps for 100 trials
and looked for examples that had extreme gradients.
He chose 3 maps as representative of the exteme cases: one that with
a maximum gradiant and two with a minimum gradient. These maps are:
- BFieldMaps/Mau9/MisAlignedCoils/Mu2e_DSMap_MaxGradient.txt
- BFieldMaps/Mau9/MisAlignedCoils/Mu2e_DSMap_MinGradient_1.txt
- BFieldMaps/Mau9/MisAlignedCoils/Mu2e_DSMap_MinGradient_2.txt
Appendix VIII: Mau10
This field map was made available Dec 17, 2015. Mau's statement about the physics content of Mau10 is:
The magnetic design V10 had a slightly change in geometry and position of a few coils in TS1, TS3 and TS5 region to conform with mechanical aspects of the housing supports or the interference with the cryostat. No changes in any other magnets! Attention: V10 does not include any of the on-going modification proposed by General Atomics on the DS coils. The maps were generated using ideal solenoids.
The files can be found at:
/grid/fermiapp/mu2e/DataFiles/BFieldMaps/Mau10 /cvmfs/mu2e.opensciencegrid.org/DataFiles/BFieldMaps/Mau10
For Mau10 the three field maps used by the UCI design of the extinction monitor are no longer needed and have not been provided.
There has been a small reorganization of the Mau10 field map directory. All of the standard maps have been moved into the subdirectory:
BFieldMaps/Mau10/Standard_Maps
These include:
Standard_Maps/Mu2e_DSMap.txt Standard_Maps/Mu2e_PSMap.txt Standard_Maps/Mu2e_TSdMap.txt Standard_Maps/Mu2e_TSuMap.txt Standard_Maps/DSExtension.txt Standard_Maps/PSAreaMap.txt Standard_Maps/ProtonDumpAreaMap.txt Standard_Maps/PStoDumpAreaMap.txt
The variants of Mau10 that have been provided are:
- DS coils powered at 50% strength: Mau10/Calibration/DS_at_50_percent/
- DS coils powered at 70% strength: Mau10/Calibration/DS_at_70_percent/
- DS coils powered at 85% strength: Mau10/Calibration/DS_at_85_percent/
- Coils off - see below for description:
- Mau10/Coils_Off/DS_OFF
- Mau10/Coils_Off/PS_OFF
- Mau10/Coils_Off/TS_OFF
- Mau10/Coils_Off/TS_and_DS_OFF
- Mau10/Coils_Off/TS_and_PS_OFF
- Random points - see below
The coils off maps are most easily described by an example. To compute the DS_Off maps, the current in all DS coils was set to zero and 4 maps were computed: DS, PS, TSu and TSd. We will ask General Atomics to provide the same 4 maps but with the PS, and TS currents set to zero. This will allow us to combine the Mau10 DS_Off maps with the GA maps to form complete maps that have contributions from two sources. This allows designers of the different subsystems to work independently, without knowledge of the details of the other subsystems. Hopefully the directory names are self descriptive; in some directories, not all maps are provided because some are the field values are so low as to be uninteresting.
In order to test interpolation algorithms Mau has provided a file with the BField evaluated at 10,000 random points within the vaccum volume of the DS. This file is intended to be used to tool up these tests. Mau will provided additional files upon request.