path: root/src/driver/driver.hh

// driver.hh -- header file for driver code
// $Header$

//
// prerequisites:
//	<stdio.h>
//

//******************************************************************************

//
// this enum holds the decoded  method  parameter, i.e. it specifies
// our top-level method
//
enum	method
	{
	method__evaluate_expansion,
	method__test_expansion_Jacobian,
	method__find_horizon // no comma
	};

//
// this enum holds the decoded  verbose_method  parameter, i.e. it
// specifies which (how many) informational messages we should print
//
enum	verbose_level
	{
	verbose_level__physics_highlights,
	verbose_level__physics_details,
	verbose_level__algorithm_highlights,
	verbose_level__algorithm_details // no comma
	};

//
// this enum holds the (a) decoded  initial_guess_method  parameter,
// i.e.  it specifies how we should set up the initial guess for a
// single apparent horizon
//
enum	initial_guess_method
	{
	initial_guess__read_from_file,
	initial_guess__Kerr_Kerr,
	initial_guess__Kerr_KerrSchild,
	initial_guess__coord_sphere,
	initial_guess__coord_ellipsoid // no comma
	};

//******************************************************************************

//
// This struct holds parameters for setting up the initial guess
// for a single apparent horizon.
//
struct	initial_guess_info
	{
	enum initial_guess_method method;

	// parameters for method == initial_guess__Kerr_Kerr
	struct	{
		fp x_posn, y_posn, z_posn;
		fp mass, spin;
		} Kerr_Kerr_info;

	// parameters for method == initial_guess__Kerr_KerrSchild
	struct	{
		fp x_posn, y_posn, z_posn;
		fp mass, spin;
		} Kerr_KerrSchild_info;

	// parameters for method == initial_guess__coord_sphere
	struct	{
		fp x_center, y_center, z_center;
		fp radius;
		} coord_sphere_info;

	// parameters for method == initial_guess__coord_ellipsoid
	struct	{
		fp x_center, y_center, z_center;
		fp x_radius, y_radius, z_radius;
		} coord_ellipsoid_info;
	};

//
// This struct holds parameters for solving the Theta(h) = 0 equations.
//
struct	solver_info
	{
	bool debugging_output_at_each_Newton_iteration;
	int max_Newton_iterations__initial,
	    max_Newton_iterations__subsequent;
	fp max_Delta_h_over_h;
	fp Theta_norm_for_convergence;
	fp Delta_h_norm_for_convergence;
	bool final_Theta_update_if_Delta_h_converged;
	};

//
// This struct holds info for computing black hole diagnostics.
//
struct	BH_diagnostics_info
	{
	enum patch::integration_method integral_method;
	};

//******************************************************************************

//
// this enum holds the decoded  horizon_file_format  parameter, i.e.
// it specifies what format of input/output file(s) we should use
// for h and H (and other angular grid functions)
//
enum	horizon_file_format
	{
	horizon_file_format__ASCII_gnuplot,
	horizon_file_format__HDF5 // no comma
	};

//
// This struct holds info for I/O
//
struct	IO_info
	{
	enum horizon_file_format horizon_file_format;
	bool output_initial_guess;
	int how_often_to_output_h,
	    how_often_to_output_Theta;
	bool output_ghost_zones_for_h;
	const char* ASCII_gnuplot_file_name_extension;
	const char* HDF5_file_name_extension;
	const char* h_base_file_name;
	const char* Theta_base_file_name;
	const char* Delta_h_base_file_name;
	const char* Jacobian_base_file_name;

	bool output_BH_diagnostics;
	const char* BH_diagnostics_base_file_name;
	const char* BH_diagnostics_file_name_extension;

	// this is used to choose file names
	int time_iteration;	// the Cactus time interation number
				// (cctk_iteration)
	fp time;		// the Cactus time coordinate (cctk_time)
	};

//
// This struct holds info describing how verbose we should be
//
struct	verbose_info
	{
	// decoded from verbose_level parameter
	enum verbose_level verbose_level;

	// derived Boolean flags saying whether or not
	// verbose_level is >= the appropriate level
	bool print_physics_highlights;
	bool print_physics_details;
	bool print_algorithm_highlights;
	bool print_algorithm_details;
	};

//******************************************************************************

//
// (A single copy of) this struct holds all of our black hole diagnostics
// for a single apparent horizon.  These diagnostics are only meaningful
// if the apparent horizon has indeed been found.
//
struct	BH_diagnostics
	{
	fp centroid_x, centroid_y, centroid_z;
	fp mean_radius;
	fp circumference_xy, circumference_xz, circumference_yz;
	fp area;
	fp m_irreducible;
	};

//
// (A single copy of) this struct holds all of our information about
// a single apparent horizon.
//
struct	AH_info
	{
	patch_system* ps_ptr;
	Jacobian* Jac_ptr;

	struct initial_guess_info initial_guess_info;

	bool AH_found;
	struct BH_diagnostics BH_diagnostics;
	FILE *BH_diagnostics_fileptr;
	};

//
// (A single copy of) this struct holds all of our state that's
// persistent across Cactus scheduler calls.  This copy lives in "state.cc".
//
struct	state
	{
	enum method method;
	struct verbose_info verbose_info;
	int timer_handle;
	int my_proc;			// our processor number

	struct IO_info IO_info;
	struct Jacobian_info Jac_info;
	struct solver_info solver_info;
	struct cactus_grid_info cgi;
	struct geometry_info gi;

	struct BH_diagnostics_info BH_diagnostics_info;

	int N_horizons;

	// --> array of size N_horizons+1,
	// indexed with "horizon number" hn (should be in range [1,N_horizons]
	AH_info* AH_info_array;
	};

//******************************************************************************

//
// prototypes for functions visible outside their source files
//

// setup.cc
// ... called from Cactus Scheduler
extern "C"
  void AHFinderDirect_setup(CCTK_ARGUMENTS);

// find_horizons.cc
// ... called from Cactus Scheduler
extern "C"
  void AHFinderDirect_find_horizons(CCTK_ARGUMENTS);

// initial_guess.cc
void setup_initial_guess(patch_system& ps,
			 const struct initial_guess_info& igi,
			 const struct IO_info& IO_info,
			 int hn, int N_horizons,
			 const struct verbose_info& verbose_info);
enum initial_guess_method
  decode_initial_guess_method(const char initial_guess_method_string[]);

// Newton.cc
// returns true for success, false for failure to converge
bool Newton_solve(patch_system& ps,
		  Jacobian& Jac,
		  const struct cactus_grid_info& cgi,
		  const struct geometry_info& gi,
		  const struct Jacobian_info& Jacobian_info,
		  const struct solver_info& solver_info,
		  bool initial_find_flag,
		  const struct IO_info& IO_info,
		  int hn, const struct verbose_info& verbose_info);

// io.cc
void input_gridfn(patch_system& ps, int unknown_gfn,
		  const struct IO_info& IO_info, const char base_file_name[],
		  int hn, bool print_msg_flag, int AHF_iteration = 0);
void output_gridfn(patch_system& ps, int unknown_gfn,
		   const struct IO_info& IO_info, const char base_file_name[],
		   int hn, bool print_msg_flag, int AHF_iteration = 0);
void print_Jacobians(const patch_system& ps,
		     const Jacobian* Jac_NP, const Jacobian* Jac_SD_FDdr,
		     const struct IO_info& IO_info, const char base_file_name[],
		     int hn, bool print_msg_flag, int AHF_iteration = 0);
FILE* setup_BH_diagnostics_output_file(const struct IO_info& IO_info,
				       int hn, int N_horizons);
void output_BH_diagnostics_fn(const struct BH_diagnostics& BH_diagnostics,
			      const struct IO_info& IO_info,
			      int hn, FILE* fileptr);
enum horizon_file_format
  decode_horizon_file_format(const char horizon_file_format_string[]);