A Guide to Fondue
Fondue is part of the Fondue Family. The Fondue source code can be downloaded here Watch out for these bugs.If you are looking for something in particular, you might want to look at the index for the documentation of Fondue. There is an associated program called Digest that will extract the information from Fondue's binary file. There is another associated program called Dessert that will extract the information from Fondue's save_disk file. For some assistance in generating input files for modeling niobium, you might want to check out the NbGenerator page. All of these programs are free and can be re-distributed under the terms of GNU General Public License. This is an implementation of the Copyleft concept provided by the Free Software Foundation.
Overview
Fondue computes the temperature evolution of the elements in a disk. The model is axisymmetric and one can define special Ohmic and/or field emission heating regions at the origin. The bottom surface is in contact with liquid helium and the top surface is exposed to an RF magnetic field. The outer edge (maximum radius) of the disk has an insulating boundary. These boundary conditions can be overridden as specified below.- Fondue is invoked from the command line by
fondue [options] inputfileThe options and the inputfile can appear in any order on the command line. In the inputfile, the simulation's input parameters are specified.
- External files are used to enter the parameters for Fondue. For the most part, the format of these files is similar. The file parser is rather forgiving. The input is insensitive to the number of spaces and/or tabs separating the items on a line. A "#" is used to indicate that the rest of the line is a comment and should be ignored. Blank lines are ignored.
Command line options
- --default
-
All of the available input parameters and their default values will be printed to
stdout
. This will be done instead of performing any computation. The format for this output is the same format as required for the parameter input file. This option is most often used to generate a starter input file by doingfondue --default > myinputs.in
One can then go on to modify the values inmyinputs.in
. A word about notation: The default values for the filenames are NULL. This is represented by the commented line beginning with#Empty
. - --help
- A help message will be printed to
stdout
. This will be done instead of performing any computation. The brief "usage" statement will be printed along with a one-line description of the command line arguments. - --version
- A message stating the version will be printed to
stdout
. This will be done instead of performing any computation. - --copying
- A message stating the GNU Copying info will be printed to
stdout
. This will be done instead of performing any computation. - --warranty
- A message stating the GNU No Warranty info will be printed to
stdout
. This will be done instead of performing any computation. - --output filename_stem
- -o filename_stem
-
With this option you specify the stem for the filenames that will be constructed to write Fondue's output, if any. A three letter extension will be added to this stem for each type
of output file. If all forms of output are selected, then one would expect the following to be created.
- filename_stem
.sum
- filename_stem
.bin
- filename_stem
.log
- filename_stem
.sav
If this option is not specified, the default stem ofdata
will be used.
- filename_stem
- --verbosity level
- -v level
- This option is used to set the level of output going to
stdout
. The following values for levelare currently supported.- No output.
- Only output at the beginning and the end of the calulation.
- Output once every
Decimation
timesteps.
- --dryrun (--nodryrun)
- -d (+d)
-
This flag causes no computation to be done. Fondue will do everything except perform its heat computation. This option is mainly used when a run
is going to be submitted a batch job and the user doesn't want to find out later that the run had trouble due to a typo or other careless mistake.
The input files will all be read and parsed. Output files will be opened, header information will be written, and then the files will be closed. The
option
--nodryrun
is default. The option--dryrun
would turn on the flag. - --clobber (--noclobber)
- -c (+c)
-
This flag allows files to be overwritten. The
--noclobber
option will prevent old files from being overwritten. If you have data from a previous run of Fondue that you don't want to have "clobbered" by a new run, use--noclobber
to avoid an accidental overwrite. The default is--clobber
. - --adaptive (--noadaptive)
- -a (+a)
-
This flag turns on and off the adaptive stepsize routine in Fondue. When
--noadaptive
is used, DeltaTime is the only stepsize that will be used. If there is a problem with numeric stability or the temperature rise exceeds the limit specified by MaxDeltaTemp the program will exit. When--adaptiveis used, the step size can be reduced to accomodate those cases. The step size will also be allowed to grow back up to the original DeltaTime as the calculation permits. - --summary (--nosummary)
- -s (+s)
-
This flag specifies whether or not a summary file will be written as output. Since the binary output file is useless without the summary file,
when you turn off output of a summary file with
--nosummary
, the option--summary
will also be invoked. The default is--binary
. - --binary
- -b (+b)
-
This flag specifies whether or not a binary file will be written as output. Since the binary output file is useless without the
summary file, when you turn on output of a binary file with
--binary
, the option--summary
will also be invoked. The default is--binary
. - --save_disk (--nosave_disk)
-
This flag specifies whether or not a save_disk file will be written. This file will have the suffix
.sav<
. The save_disk file contains the current temperatures of the calculation. This file can be post-processed using Dessert. This file is overwritten each time it is created. In the future, this file will be used to restart an interupted calculation. The default is--nosave_disk
. - --logfile (--nologfile)
- -l (+l)
-
This flag specifies whether or not a log file will be written as output. The log file contains a brief human readable of the development of the calculation.
Its format is compatable for use as a data file for
gnuplot
for example. The default is--logfile
. - --matrix_output (--nomatrix_output)
-
This flag specifies whether or not all of the temperatures in the computation will be printed to the console. This flag is intended for debugging purposes only
-- any serious modeling will generate copious output. This option is currently the only method for the user to access all the temperatures in the model for all
time steps. This feature may prove useful if the Fondue output is piped to a plotting program to give feedback during the calculation. (My first attempts at
this involved piping this copious output to a Tcl/Tk script to generate a grayscale plot. I didn't have much success.) The default is
--nomatrix_output
.
Input Parameters
These parameters appear in the input file to Fondue. The format for that file is most easily seen by using the --default command line option. The format for entering parameters isvalue ParameterNameon the same line. Here
ParameterName
is any of the input parameters described below. Not all parameters need to be specified. Those unassigned in the input file will keep their default values.
It is recommended that all parameters be specified to remain compatible with future versions of Fondue that may have different default values. Excess spaces and tabs around both of these is ignored.
The character#specifies that the rest of the line will be ignored as a comment. Blank lines in the file will also be ignored.
- Radius
- This specifies the radius of the modeled disk. This is its extent in the r-direction. It has units of meters.
- Depth
- This specifies the depth of the modeled disk. This is its extent in the z-direction. It has units of meters.
- Rpoints
- This specifies the number of mesh elements in the r-direction. The minimum value for this is 2. The maximum depends upon the available memory of the system.
- Zpoints
- This specifies the number of mesh elements in the z-direction. The minimum value for this is 2. The maximum depends upon the available memory of the system.
- DeltaTime
-
This specifies the time step that will be used for each iteration of the calculation. Its units are seconds.
If the --adaptive option is used, then
DeltaTime
is the maximum time step that may be used. The calculation will attempt to use the largest time step it can get away with up to the limit ofDeltaTime
. - MinDeltaTime
- This specifies the minimum time step that can be used. Its units are seconds. This parameter is only used when the --adaptive option is used. If the adaptive time step routine requires a time step that is smaller thanMinDeltaTime, the calculation will end with an EndCondition of "Time step has become too small." Setting this to a value which is <=0 will ensure that the calculation would never terminate due to this condition.
- MinRateTempChange
-
This specifies the minimum allowable rate of temperature change for the disk in an iteration. It has units of Kelvins. This is used to detect if the disk has come to
equilibrium. For each time step, the maximum temperature change of any mesh element is recorded. For the calculation to continue, this maximum temperature
change divided by the current
DeltaTime
must be greater thanMinRateTempChange
. If this condition is not met, the calculation will end with an EndCondition of "Convergence." - MaxDeltaTemp
-
This specifies the maximum allowable temperature change for the disk in one iteration. It has units of Kelvins. If the --adaptive option is used,
Fondue will reduce the time step to make sure that
MaxDeltaTemp
is not exceeded. If the [#AdaptiveOption][--noadaptive]] option is used and MaxDeltaTemp is exeeded in an iteration, then the calculation will terminate with an EndCondition of "Temperature jump between time steps is too large." - NormalRs
-
This specifies the constant RF surface resistance of elements outside the Ohmic defect region that have a temperature
above Tc.
NormalRs
has units of Ohms. If FileRs is provided,NormalRs
is not used. - Tc
-
This specifies the transition temperature for the material of the disk. It has units of Kelvins.
Tc
may come into play in two ways. - OhmicDefectRadius
- This specifies the radius of the Ohmic defect region. The units of this are radial mesh elements. The length of a radial mesh element is Radius divided by Rpoints. A radius of 0 mesh elements specifies that no Ohmic defect will be used. A nonzero value creates a region that will have a constant surface resistance of OhmicDefectRs. Note that this may be in addition to a field emission defect.
- OhmicDefectRs
- This specifies the surface resistance of any elements within the OhmicDefectRadius. Its units are Ohms.
- FEDefectRadius
-
This specifies radius of a field emission defect region. The units of this are radial mesh elements. The length of a radial mesh element is Radius
divided by Rpoints. A radius of 0 mesh elements specifies that no field emission defect will be used. A nonzero value creates a region that will
have heating due to field emission. Actually, this just creates a region that has supplementary heating. Field emission is just one possible interpretation.
If FileFieldEmissionHeating is provided, then the heat specified there will be used and spread evenly across the area within
FEDefectRadius
. If no external file is provided, the constant heat in FieldEmissionHeating will be used. - Frequency
- This specifies the frequency of the RF being applied to the surface. It has units of Hertz. This parameter is only used if the cavity fields are being evolved in time through the use of HarmonicVariation and/or FilePf.
- MaxIterations
- This specifies the maximum number of iterations allowed in the computation. Should this limit be reached, the calculation will stop with an EndCondition of "Maximum iterations reached."
- MaxTime
- This specifies the maximum simulation time allowed in the computation. It has units of seconds. Should this limit be reached, the calculation will stop with an EndCondition of "Maximum simulation time reached."
- TBath
- This specifies the temperature of the liquid helium bath that is touching the bottom side of the disk. It has units of Kelvins. This parameter is used in computing the heat flow conducted through the bottom side of the disk via KapitzaConductivity and FileKapitzaConductivity.
- Decimation
-
This specifies how often the results of the calcuation will be recorded. It is an integer value. When
Decimation
is 1, every iteration will be recorded. WhenDecimation
is 10, only 1 in 10 iterations will be recorded. No I/O operations will regularly be done except at the interval defined byDecimation
. This the way to keep the output file sizes from becoming unwieldy for calculations with a large number of iterations. - HeatCapacity
- This specifies the constant heat capacity of the material of the disk. It has units of J/K/m^3. This value is ignored if FileHeatCapacity is specified.
- FileHeatCapacity
- This specifes the name of the external file containing heat capacity [J/K/m^3] as a function of temperature [K]. The program will end if a value is required that is outside the range of the file.
- ThermalConductivity
- This specifies the constant thermal conductivity of the material of the disk. It has units of W/m/K. This value is ignored if FileThermalConductivityParameter is specified.
- FileThermalConductivity
- This specifies the name of the external file containing thermal conductivity [W/m/K] as a function of temperature [K]. The program will end if a value is required that is outside the range of the file.
- KapitzaConductivity
- This specifies the constant Kapitza conductivity of the bottom surface of the disk. It has units of W/K. This value is ignored if FileKapitzaConductivity is specified.
- FileKapitzaConductivity
- This specifies the name of the external file containing Kapitza conductivity [W/K] as a function of temperature [K] for a given bath temperature. Note that if you change Tc you will generally want to change the contents of this file. The program will end if a value is required that is outside the range of the file.
- SuperRs
-
This specifies the constant RF surface resistance of elements outside the Ohmic defect region that have a temperature below
Tc.
SuperRs
has units of Ohms. If FileRs is provided,SuperRs
is not used. - FileRs
- This specifies the name of the external file containing surface resistance [Ohms] as a function of temperature [K]. The program will end if a value is required that is outside the range of the file.
- FieldEmissionHeating
-
This specifies the constant heating due to field emission. It has units of Watts. If FileFieldEmissionHeating is provided,
FieldEmissionHeating
is not used. - FileFieldEmissionHeating
- This specifies the name of the external file containing heat [W] as a function of magnetic (H) field [A/m]. The program will end if a value is required that is outside the range of the file.
- Hfield
-
This specifies the constant RF magnetic (H) field amplitude applied to the surface of the disk. It has units of A/m. If FilePf is provided,
Hfield
is the initial value of the magnetic field that will be evolved in time. - Hsh
- This specifies the superheating critical field (Hsh). It has units of A/m. When the applied magnetic field exceeds this value, the surface resistance (Rs) will be the value of NormalRs. If FileRs is provided and T < Tc, then Rs will be taken to be Rs(Tc + 0.1 K) as provided in FileRs.
- HarmonicVariation
- This specifies that the magnetic field will oscillate at the frequency of Frequency. The oscillation is performed with a sine function so the magnetic field starts out at zero.
- KappaH
- This specifies the relationship between the peak surface magnetic field and the total stored energy in a cavity. This has units of A/m/sqrt(J). This is used to evolve the magnetic fields in time so it is only used when FilePf is provided.
- Qext
- This specifies the external Q of the input (drive) coupler. This is used to evolve the magnetic fields in time so it is only used when FilePf is provided.
- Qext2
- This specifies the external Q of an output coupler. If there is more than one output coupler, this would be the external Q of a coupler equivalent to the sum of the other external couplers (added in parallel). This provides another method of introducing losses that affect the evolution of magnetic field but these losses do not show up as surface heating like the losses of field emission. This is used to evolve the magnetic fields in time so it is only used when FilePf is provided.
- FilePf
-
This specifies the name of the external file containing incident RF power [W] as a function of time [s]. When the simulation time is outside the bounds
of this file, the power is assumed to be zero. When this file is specified, the amplitude of the magnetic field is evolved in time as if it were a real cavity being
driven by RF through an input coupler. The following parameters are only used when
FilePf
is specified. Hfield is used as the intial value for the magnetic field. The loaded Q of the cavity is computed using the external Q values and the internal Q. The interal Q is computed summing the RF losses and the field emission losses. - ClampEdgeTemp
- This flag specifies whether or not the edge of model (R = maximum) is held at a fixed temperature. A value of 1 means to keep the temperature fixed at the temperature specified by EdgeTemp. A value of 0 means to insulate the edge. The default value is 0.
- EdgeTemp
- This specifies temperature [K] at which the edge of the model (R = maximum) is held fixed. This value is used only if ClampEdgeTemp has a value of 1.
- \ClampBottomTemp\
- This flag specifies whether or not the bottom of the model (Z = maximum) is held at a fixed temperature. A value of 1 means to keep the temperature fixed at the temperature specified by BottomTemp. A value of 0 means to let the temperature be determined by neighboring temperatures and the Kapitza flow across the boundary. The default value is 0.
- BottomTemp
- This specifies temperature [K] at which the bottom of the model (Z = maximum) is held fixed. This value is used only if ClampBottomTemp has a value of 1.
Output Files
- Summary File
- When the --summary flag is set a summary file will be rewritten at every save interval. This is a text file that contains the essential information needed to interpret the binary file. The summary file also contains the EndCondition parameter. This is the reason that the calculation terminated (if it did). A comment on that line gives the text of the message describing that EndCondition value. The current possible values of this parameter and their messages are: 0. "No Error (aborted early?)" 1. "Maximum iterations reached." 2. "Maximum simulation time reached." 3. "Temperature out of range for Super Rs (T)" 4. "Temperature out of range for Heat Capacity (T)" 5. "Temperature out of range for Thermal Conductivity (T)" 6. "Temperature out of range for Kapitza Conductivity (T)" 7. "H field out of range for Field Emission Heating (H)" 8. "Matrix is not diagonal." 9. "Diagonal entry of matrix is zero." 10. "Temperature jump between time steps is too large." 11. "Time step has become too small." 12. "Convergence." 13. "This was a dry run." Note that items may be added to this message list in future revisions. It is unlikely, but possible that the message numbers can change in the future. Look to the message printed in the summary file for the final word.
- Binary File
-
When the --binary flag is set, a binary file is created and updated at each save interval. The binary file consists of a number of "records".
Each record contains information at a particular time in the simulation. The each record has this sequence of floating point values.
- time
- cavity Q
- magnetic field
- temperatures along the z=0 (top) surface
- temperatures along the z=max (bottom) surface
- temperatures along the r=0 (left) surface
- temperatures along the r=max (right) surface
- Log File
-
When the --logfile flag is set, a log file is created and updated at each save interval. The log file is a text file written with distinct
columns that are easily plotted. The information currently written to the log file consists of the following.
- time
- magnetic field
- cavity Q
- temperature at the model's origin
- number of surface mesh elements above Tc.
- Save_Disk File
- When the --save_disk flag is set, a Save_Disk file is created and updated at each save interval. This binary file contains the full 2D array of temperatures at the current time slice. Each time this file is written, it overwrites the previous information. Since this file contains all of the temperatures of the slab, it will be used in the future to allow the user to resume a calculation from a saved state. The post-processor for this file is called Dessert.
Index#FondueIndex
- overview
- command line options
- input parameters
- Radius
- Depth
- Rpoints
- Zpoints
- DeltaTime
- MinDeltaTime
- MinRateTempChange
- MaxDeltaTemp
- OhmicDefectRadius
- OhmicDefectRs
- FEDefectRadius
- Frequency
- MaxIterations
- MaxTime
- TBath
- Decimation
- HeatCapacity
- FileHeatCapacity
- ThermalConductivity
- FileThermalConductivity
- KapitzaConductivity
- FileKapitzaConductivity
- SuperRs
- NormalRs
- Tc
- FileRs
- FieldEmissionHeating
- FileFieldEmissionHeating
- Hfield
- Hsh
- HarmonicVariation
- KappaH
- Qext
- Qext2
- FilePf
- ClampEdgeTemp
- EdgeTemp
- ClampBottomTemp
- BottomTemp
- Output Files