ptfsf.h

The code assumes a two-dimensional computational domain with TMz polarization (i.e., non-zero field

/*
 * ptfsf.h: Header file for the "perfect" total-field/scattered-field
 *      boundary routines.
 *
 * Copyright (C) 2004  John B. Schneider
 * 
 *********************************************************************
 * This program is free software; you can redistribute it and/or     *
 * modify it under the terms of the GNU General Public License       *
 * as published by the Free Software Foundation (FSF) version 2      *
 * of the License.                                                   *
 *                                                                   *
 * This program is distributed in the hope that it will be useful,   *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of    *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     *
 * GNU General Public License for more details.                      *
 *                                                                   *
 * You should have received a copy of the GNU General Public License *
 * along with this program; if not, write to the Free Software       *
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA         *
 * 02111-1307, USA.  You may also visit the FSF web site at          *
 * www.fsf.org.  The license under which this software is publish    *
 * is available from www.fsf.org/copyleft/gpl.html or                *
 * www.fsf.org/copyleft/gpl.txt.                                     *
 *********************************************************************
 */

/* flags used to control mostly display of informational messages */
enum PTFSF_FLAGS {PTFSF_PROGRESS=1,  // report progress
		  PTFSF_INFO=2,      // provide any informational messages
		  PTFSF_SILENT=4,    // turn other optional messages
		  PTFSF_ESTIMATE=8,  // FFTW flags for the plans
		  PTFSF_MEASURE=16,
		  PTFSF_PATIENT=32,
		  PTFSF_ASCII_DUMP=64, // set for ASCII dump file of inc. field
		  PTFSF_NULL_OK=128    // don't worry about NULL field pointers
};


/* Data structure returned by the init routines which contains all the
 * relevant parameters about the TFSF boundary.  This data structure
 * isn't really used internally but is here for the sake of packaging
 * all this information together for the calling function (and some of
 * this information wouldn't be known by the calling function until
 * the file is read that stores the incident field).
 */
typedef struct {
      int time_end;         // time steps inc field non-zero
      int x_ll; int y_ll;   // indices of lower-left corner of TF region
      int x_ur; int y_ur;   // indices of upper-right corner of TF region
      int x_ref; int y_ref; // indices of "reference" point
      int lim_x; int lim_y; // size of computational domain
      double phi;           // incident angle [degrees]		      
      double cdtds;         // Courant number
      double eta;           // characteristic impedance
      double *ez; double *hx; double *hy; // field arrays
      double (*time_func)(double); // time-stepping function 
      char *file_name;      // input file name
      int flags;            // flags to control (mostly peripheral) behavior
} ptfsf_parameters;


/* Routine to initialize TF/SF code.
 *
 * Note: Time-stepping function must return a double a take a single
 * double argument.
 */
ptfsf_parameters *ptfsf_init(
      int time_end,         // time steps inc field non-zero
      int x_ll, int y_ll,   // indices of lower-left corner of TF region
      int x_ur, int y_ur,   // indices of upper-right corner of TF region
      int x_ref, int y_ref, // indices of "reference" point
      int lim_x, int lim_y, // size of computational domain
      double phi,           // incident angle [degrees]
      double cdtds,         // Courant number
      double eta,           // characteristic impedance
      double *ez, double *hx, double *hy, // field arrays
      double (*time_func)(double), // time-stepping function 
      int flags             // flags to control (mostly peripheral) behavior
);


/* incident fields are calculated and then sent to specified output file */
void ptfsf_generate_file(
      int time_end,                // time steps incident field non-zero
      int x_size, int y_size,      // size of TF region
      int x_ref, int y_ref,        // indices of "reference" point
      double phi,                  // incident angle [degrees]		      
      double cdtds,                // Courant number
      double eta,                  // characteristic impedance
      double (*time_func)(double), // time-stepping function 
      char *file_name,             // output file name
      int the_flags                // controlling flags
      );


/* called between update of E and H */
void ptfsf_update(int n_time);


/* initialization function for case where incident field stored in data file */
ptfsf_parameters *ptfsf_init_file(
    int x_ll,  int y_ll,      // indices of lower-left corner of TF region
    int lim_x, int lim_y,     // size of computational domain
    double cdtds,             // Courant number
    double eta,               // characteristic impedance
    double *ez, double *hx, double *hy, // field arrays
    char *file_name,          // input file name
    int flags                 // flags to control (mostly peripheral) behavior
   );


/* called between update of E and H if incident fields stored
 * in a file
 */
void ptfsf_update_file(int n_time);


/* dumps incident fields to the named file -- can be called after
 * incident fields have been found using ptfsf_init() but before the
 * end of time stepping (well, end of when incident fields used in
 * time stepping at which point incident fields arrays are freed)
 */
void ptfsf_dump_file(char *filnam);


/* display parameter values -- at least some of them */
void ptfsf_parameters_display(ptfsf_parameters *params);


/* convert a binary incident-field file to an ASCII one */
void ptfsf_binary_to_ascii(char *file_name_in, char *file_name_out);