[Commits] [svn:einsteintoolkit] incoming/PITTNullCode/ (Rev. 47)
yosef at astro.rit.edu
yosef at astro.rit.edu
Thu Jun 30 14:02:19 CDT 2011
User: zlochower
Date: 2011/06/30 02:02 PM
Modified:
/PITTNullCode/SphericalHarmonicDecomp/doc/
documentation.tex
/PITTNullCode/SphericalHarmonicRecon/doc/
documentation.tex
Log:
Instructions for use
File Changes:
Directory: /PITTNullCode/SphericalHarmonicDecomp/doc/
=====================================================
File [modified]: documentation.tex
Delta lines: +151 -0
===================================================================
--- PITTNullCode/SphericalHarmonicDecomp/doc/documentation.tex 2011-06-30 15:44:22 UTC (rev 46)
+++ PITTNullCode/SphericalHarmonicDecomp/doc/documentation.tex 2011-06-30 19:02:19 UTC (rev 47)
@@ -99,6 +99,10 @@
% Add an abstract for this thorn's documentation
\begin{abstract}
+ This thorns provides a mechanism to decompose grid functions in terms
+of Spin Weighted spherical harmonics of arbitrary spin. This thorn will
+also decompose the ADM metric on spherical shells for use in a subsequent
+CCE null evolution.
\end{abstract}
@@ -106,13 +110,160 @@
% Remove them or add your own.
\section{Introduction}
+ The idea behind this thorn was to decompose GFs on 2D spheres and
+3D spherical shells in terms of spin-weighted spherical harmonics
+and Chebyshev or Legendre polynomials in radius. This was used for
+waveform extraction, compression of 3D data for visualization and CCE.
+The code uses more ``collocation'' points than spectral functions. The idea
+here was to try to smooth the data by using a least-squares fit to obtain
+the spectral coefficients. This thorn provides aliased functions to perform
+the decomposition. This will also dump the Cauchy metric.
\section{Physical System}
\section{Numerical Implementation}
\section{Using This Thorn}
+ \subsection{Dumping Cauchy Data for CCE}
+
+ The following is a section of a parfile appended to an ordinary Cauchy evolution run (see the par/ directory for the complete parfile)
+\begin{verbatim}
+ActiveThorns="SphericalHarmonicDecomp"
+
+SphericalHarmonicDecomp::extract_spacetime_metric_every=32
+SphericalHarmonicDecomp::num_radii=3
+SphericalHarmonicDecomp::EM_Rin[0]=18
+SphericalHarmonicDecomp::EM_Rout[0]=22
+SphericalHarmonicDecomp::EM_Rin[1]=47
+SphericalHarmonicDecomp::EM_Rout[1]=53
+SphericalHarmonicDecomp::EM_Rin[2]=94
+SphericalHarmonicDecomp::EM_Rout[2]=106
+SphericalHarmonicDecomp::num_l_modes=7
+SphericalHarmonicDecomp::num_n_modes=7
+SphericalHarmonicDecomp::num_mu_points=41
+SphericalHarmonicDecomp::num_phi_points=82
+SphericalHarmonicDecomp::num_x_points=28
+
+\end{verbatim}
+In this example we will extract the metric on 3 different shells
+ (num\_radii), the
+first between r=18 and r=22, the second between r=47 and r=53, and
+the third between r=94 and 106. The idea here is to make the shell
+small enough that we can accurately calculate the radial derivatives
+of the metric function, while also large enough that we can smooth out
+the grid noise. We decompose the metric functions in terms of
+7 $\ell$ modes (num\_l\_modes=7 or all modes from $\ell=0$ to $\ell=6$,
+ the m modes are automatically set)
+and 7 radial modes (num\_n\_mode=7). The grid functions are evaluated
+at 41 points in mu (mu=cos(theta)), 82 points in phi, and 28 points
+in radius. Minimally, we would need the number of angular points to be
+equal to the number of angular spectral functions $\ell^2 + 2\ell$,
+in this case we have many more angular modes ($41*82$) than angular
+spectral functions. Similarly num\_\x\_points must be greater than
+num\_n\_modes. The number of n modes is set by the need to accurately
+model the radial derivative of the mertric functions in the spherical
+shell. The larger the difference between EM\_Rin[] and EM\_Rout[] the
+more points required. The number of l modes is determined by the accuracy
+requiremnts of the final CCE waveoform. in this case, choosin
+num\_n\_modes=7 is marginally acceptable.
+
+Note that the parameters
+\begin{verbatim}
+SphericalHarmonicDecomp::Rin
+SphericalHarmonicDecomp::Rout
+\end{verbatim}
+are not used for CCE metric extraction. These parameters affect the
+3D decomposition of GFs using the
+
+ SphericalHarmonicDecomp\_3D\_Decompose aliased function mechanism
+
+
+\subsection{Aliased functions}
+ SphericalHarmonicDecomp provides a mechanism for other thorns to decompose
+GFs either on 2D surfaces or 3D shells via aliased functions.
+These two functions should be called in GLOBAL mode.
+
+\begin{verbatim}
+CCTK_INT SphericalHarmonicDecomp_3D_Decompose (
+ CCTK_POINTER_TO_CONST _GHp,
+ CCTK_POINTER_TO_CONST _name,
+ CCTK_INT re_gindx,
+ CCTK_INT im_gindx,
+ CCTK_INT spin )
+
+e.g.
+
+ SphericalHarmonicDecomp_3D_Decompose(cctkGH, "Psi4",
+ CCTK_VarIndex("WeylScal4::Psi4r"),
+ CCTK_VarIndex("WeylScal4::Psi4i"), -2);
+
+CCTK_INT FUNCTION sYlm_DecomposeField(\
+ CCTK_POINTER_TO_CONST IN cctkGH,\
+ CCTK_POINTER_TO_CONST IN name,\
+ CCTK_INT IN re_gindx,\
+ CCTK_INT IN im_gindx,\
+ CCTK_REAL IN radius,\
+ CCTK_INT IN spin)
+
+e.g.
+
+ SphericalHarmonicDecomp_DecomposeField(cctkGH, "Psi4",
+ CCTK_VarIndex("WeylScal4::Psi4r"),
+ CCTK_VarIndex("WeylScal4::Psi4i"), 50, -2);
+
+\end{verbatim}
+
+\subsection{Parameters}
+
+\begin{verbatim}
+SphericalHarmonicDecomp::extract_spacetime_metric_every how often
+ (in iterations) should the metric be decomposed and dumped.
+
+SphericalHarmonicDecomp::out_dir="" Output directory for all output,
+ usually set to "", which causes the
+ thorn to use IO::out_dir
+
+SphericalHarmonicDecomp::max_spin=2 Largest spin value. For most configuration
+ this should be set to 2.
+
+SphericalHarmonicDecomp::num_l_modes How many l modes. This affects all
+ output. Note this is not lmax-1 in general.
+ For spin-weight 2 GF, lmax will be num_l_modes+2-1
+
+SphericalHarmonicDecomp::num_mu_points number of points in the mu (cos(theta))
+ direction. Affects all output.
+
+SphericalHarmonicDecomp::num_phi_points number of points in phi direction.
+ Affects all output.
+
+SphericalHarmonicDecomp::num_x_points number of points in x (radial) direction.
+ Affects all 3D output including MetricDecomp
+
+SphericalHarmonicDecomp::Rin inner radius of 3D shell. Only affects fields
+ dumped using aliased function mechanism
+
+SphericalHarmonicDecomp::Rout outer radius of 3D shell. Only affects fields
+ dumped using aliased function mechanism
+
+SphericalHarmonicDecomp::EM_Rin an array of Rins used for the CCE Metric
+ extraction
+
+SphericalHarmonicDecomp::EM_Rout an array of Routs used for the CCE Metric
+ extraction
+
+SphericalHarmonicDecomp::output_m_max limit on the maximum abs(m) dumped to
+ output. These options are useful if you don't want to
+ dump all the m modes from -l to l.
+
+SphericalHarmonicDecomp::output_l_max limit on the maximum l dumped to
+ output. This option is useful if you want the maximum
+ l dumped to output to be independent of the spin of the
+ GF.
+\end{verbatim}
+
+
+
\subsection{Obtaining This Thorn}
\subsection{Basic Usage}
Directory: /PITTNullCode/SphericalHarmonicRecon/doc/
====================================================
File [modified]: documentation.tex
Delta lines: +167 -1
===================================================================
--- PITTNullCode/SphericalHarmonicRecon/doc/documentation.tex 2011-06-30 15:44:22 UTC (rev 46)
+++ PITTNullCode/SphericalHarmonicRecon/doc/documentation.tex 2011-06-30 19:02:19 UTC (rev 47)
@@ -99,14 +99,180 @@
% Add an abstract for this thorn's documentation
\begin{abstract}
-
+This thorn is used to reconstruct the metric data saved by
+SphericalHarmonicDecomp. It also provides aliased functions
+that are used by NullSHRExtract to construct the boundary data
+for CCE.
\end{abstract}
% The following sections are suggestive only.
% Remove them or add your own.
\section{Introduction}
+
+\section{Using and Filtering Cauchy data from SphericalHarmonicDecomp}
+The thorn SphericalHarmonicDecomp uses a least-squares fit of the metric
+data in some spherical shell to a set of spectral functions (Chebyshev in
+R and Ylm in angle). These data are dumped into files with names
+metric\_obs\_0\_Decomp.h5, metric\_obs\_1\_Decomp.h5, etc., where
+the 0,1,etc. refer to the spherical shell (several are allowed).
+This thorn takes the data in one of these files and passes it to
+NullSHRExtract, which uses them to construct the null boundary data.
+Several utilities are provided in order to view and modify these data
+files. These include a program to filter the data via an FFT and
+calculate a smooth time derivative, which may be important in order
+to obtain accurate waveforms.
+
+These utilities require the HDF5 and FFTW3 libraries and are
+compiled using the gamke CONFIGNAME-utils mechanism.
+
+To filter the Cauchy data:
+
+ In general a simulation will be run over multiple jobs, each one
+producing an individual metric\_decomp.h5 file. You will need to
+combine these files using hdf5\_merge.
+
+\begin{verbatim}
+For example
+ hdf5\_merge Run1/metric_obs\_0\_Decomp.h5 \
+ Run2/metric\_obs\_0\_Decomp.h5 \
+ metric\_obs\_0\_Decomp.h5
+\end{verbatim}
+
+Once the files are merged, you will need to find the last timestep
+using the "findlast" command
+
+\begin{verbatim}
+./findlast metric\_obs\_0\_Decomp.h5
+ 8086: 4.010913e+02
+\end{verbatim}
+
+Here 8086 is the last timestep, which corresponds to a time of 401.0913.
+
+Next it is a good idea to examine the data in one of the higher modes
+you will use. In this case we will examine the n=1, l=4,m=4 mode
+of gxx (the 0 below corresponds to gxx, see the source)
+
+\begin{verbatim}
+./ascii\_output 8086 1 4 4 0 metric\_obs\_0\_Decomp.h5 > test\_out
+\end{verbatim}
+
+We will use this data to ensure that only high-frequency junk is
+filtered. In this case it was found that the true signal frequency
+is smaller than 0.5 (omega). To be safe, we'll set the maximum
+allowed frequency to 2.
+
+\begin{verbatim}
+./fftwfilter 8086 2 1 metric\_obs\_0\_Decomp.h5
+\end{verbatim}
+
+Here the "2" corresponds to the maximum frequency, while the "1"
+corresponds to the damping length. Note that the maximum frequency is
+in units of 2*pi/(physical time), while the damping length is units of
+integer frequency. Choosing a large damping length can lead to suppression
+of the true signal.
+
+The output file is metric\_obs\_0\_Decomp\_ft.h5, which contains the
+filtered metric data and the time derivatives of these data (which the
+original file did not contain). The filtered data can now be used in a
+Characteristic evolution.
+
+In order to use the Cauchy extraction data in a subsequent Characteristic
+evolution, you need to know the timestep in the Cauchy data and
+the region in radius that the data cover. The program "readmeta" will
+give you this region.
+
+\begin{verbatim}
+./readmeta metric\_obs\_0\_Decomp\_ft.h5
+Run Parameters
+... nn = 7
+... na = 49
+... Rin = 1.800000e+01
+... Rout = 2.200000e+01
+\end{verbatim}
+
+Here we see that the data covers the interval 18<r<22. In this case,
+we would choose an extraction radius of 20 and set the following
+parameters in the parfile
+
+\begin{verbatim}
+ #Extraction radius---------------
+ SphericalHarmonicRecon::r\_extract=20.0
+ NullSHRExtract::cr = 20.0
+ NullGrid::null\_rwt = 20.0
+
+ SphericalHarmonicRecon::time\_derivative\_in\_file = "yes"
+ SphericalHarmonicRecon::metric\_data\_filename = "metric\_obs\_0\_Decomp\_ft.h5"
+\end{verbatim}
+
+Choosing a timestep for the characteristic evolution that is an integer
+multiple of the Cauchy dump times will remove time interpolation
+errors and can lead to smoother signals. To find these dump time,
+use the "printtime" command. The syntax is "printtime iteration file"
+
+\begin{verbatim}
+./printtime 1 metric\_obs\_0\_Decomp\_ft.h5
+1: 4.960317e-02
+\end{verbatim}
+
+In this case the dump times are separated by 0.04960317.
+
+For complete example parfiles for both the initial Cauchy evolution,
+and subsequent null evolution, see SphericalHarmonicDecomp/par/
+and SphericalHarmonicRecon/par/
+
+\subsection{Parameters}
+
+\begin{verbatim}
+SphericalHarmonicRecon::order order used in time interpolation /
+ differentiation. Options are 2 or 4.
+
+SphericalHarmonicRecon::r_extract the radius of the worldtube. This
+ must be consistent with the setup of the null grid
+
+SphericalHarmonicRecon::metric_data_filename filename for the cauchy
+ metric data
+
+SphericalHarmonicRecon::time_derivative_in_file flag that indicates if
+ the time derivative of the metric is in the cauchy file. The
+ time derivative may be generated via the fftwfilter program mentioned
+ above.
+
+# the following parameters should only be used if the
+# hdf5 was corrupted and extraction parameters
+# are not recoverable. Of course, we should actually
+# fix the extraction code so that this does not happen
+BOOLEAN override_extraction_parameters "never set this"
+{
+} no
+
+CCTK_INT override_spin "spin: never set this"
+{
+ *:* :: "anything, but you probably want 0"
+} 0
+
+CCTK_INT override_nn "number of Chabyshev coefficients: never use this"
+{
+ 1:* :: "positive: must actualy match the extraction run"
+} 1
+
+CCTK_INT override_na "number of angular coefficients: never use this"
+{
+ 1:* :: "positive: must actualy match the extraction run"
+} 1
+
+CCTK_REAL override_Rin "inner radius of extraction zone: ..."
+{
+ (0:* :: "positive"
+} 1
+
+CCTK_REAL override_Rout "outer radius of extraction zone: ..."
+{
+ (0:* :: "positive"
+} 1
+\end{verbatim}
+
\section{Physical System}
\section{Numerical Implementation}
More information about the Commits
mailing list