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}