// 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_expansions,
	method__test_expansion_Jacobians,
	method__find_horizons // 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_allowable_Delta_h_over_h;
	fp Theta_norm_for_convergence;
	};

//
// 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;

	// constructor initializes all diagnostics to 0.0
	BH_diagnostics();
	};

//
// (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;

	// are we finding this horizon "from scratch"?
	// ... true if this is the first time we've tried to find it,
	//          or if we've tried before but failed to find it the
	//          last time
	//     false if we've tried before and succeeded the last time
	//           (so we have that position as a very good initial guess)
	bool initial_find_flag;

	struct initial_guess_info initial_guess_info;

	bool found_flag;	// did we find this horizon (successfully)
	struct BH_diagnostics BH_diagnostics;
	FILE *BH_diagnostics_fileptr;
	};

//
// (A single copy of) this struct holds all of our state on this processor
// 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 N_procs;			// total number of processors
	int my_proc;			// processor number of this processor
					// (0 to N_procs-1)

	int N_horizons;			// total number of genuine horizons
					// being searched for
	int N_active_procs;		// total number of active processors
					// (the active processors are processor
					//  numbers 0 to N_active_procs-1)

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

	struct BH_diagnostics_info BH_diagnostics_info;

	horizon_sequence *my_hs;	// --> new-allocated object describing
					//     the sequence of horizons
					//     assigned to this processor

	// horizon numbers ("hn") run from 1 to N_horizons inclusive
	struct AH_info** my_AH_info;	// --> new[]-allocated array of size
					//     N_horizons+1, subscripted by hn,
					//     of --> info or NULL for horizons
					//            not assigned to this
					//            processor
	};

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

//
// 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
void Newton(cGH* GH,
	    int N_procs, int N_active_procs, int my_proc,
	    horizon_sequence& hs, struct AH_info* const my_AH_info[],
	    const struct cactus_grid_info& cgi,
	    const struct geometry_info& gi,
	    const struct Jacobian_info& Jacobian_info,
	    const struct solver_info& solver_info,
	    const struct IO_info& IO_info,
	    const struct BH_diagnostics_info& BH_diagnostics_info,
	    const struct verbose_info& verbose_info);

// BH_diagnostics.cc
void compute_BH_diagnostics
	(const patch_system& ps,
	 const struct BH_diagnostics_info& BH_diagnostics_info,
	 const struct verbose_info& verbose_info,
	 struct BH_diagnostics& BH_diagnostics);
void print_BH_diagnostics(const struct BH_diagnostics& BH_diagnostics,
			  int N_horizons, int hn,
			  const struct verbose_info& verbose_info);
FILE* setup_BH_diagnostics_output_file(const struct IO_info& IO_info,
				       int N_horizons, int hn);
void output_BH_diagnostics_fn(const struct BH_diagnostics& BH_diagnostics,
			      const struct IO_info& IO_info,
			      int hn, FILE* fileptr);

// 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 output_Jacobians(const patch_system& ps,
		      const Jacobian* Jac_NP_ptr,
		      const Jacobian* Jac_SD_FDdr_ptr,
		      const struct IO_info& IO_info, const char base_file_name[],
		      int hn, bool print_msg_flag, int AHF_iteration = 0);