x is depth at nodes with respect to a nominal reference surface (which may be greater than sea level in upstream locations).
Regularization:
 close to the original values for all nodes: damp
 minimize the 1st derivative of node elevation along land boundaries: damp_shoreline
Notes:
 The function “cal_z_ref” only applies to the Bay Delta grid and need to be modified for other grids.
 This script create an optimized gr3 file (_opt.gr3) only when one set of optimization parameters is specified.
First version, completed on 9/11/2013
Define reference water surface at locations specified in xy_coor based on the assumptions, which only appliable to Bay Delta grid (1) zref increases linerly from west (ocean) to east (2) east of (x_old_river, y_old_river), zref increases lineraly towards the south
construct matrix A and vector b based on specified optimization parameters damp: regularization to initial values A_bnd, damp_bnd: regularization to minimize gradient along the shoreline A_face, face_coeff: related to vertical faces of elements A_tri, vol_coeff: related to volumes of elements depth_q, face_hq: quadrature depths derived from elements and and faces bnd_h: target depth along the shoreline h0_node: original depth at nodes nnode: node number solver: either LBFGSB or lsqr
Create a shapefile representing elements as polygons Each element one is defined by a series of nodes (zerobased in element_data), where xy coordinates are provided in node_data.
Parameters :  file_path : str
element_data : array
node_data : array
n_node_per_elm : int
n_attribute : int
attribute_def : List
valid datatype: float (=> OFTReal), int (=> OFTInteger), str (=>OFTString) :


Create a shapefile for edges
Shapefile is based on based on node # specified in face_data and xy coordinates specifed in node_data, FID is zerobased, i.e. starting at 0
Parameters :  file_path : str
face_data : array
node_data : array
n_attribute : int
attribute_def : List


Create shapefile for nodes
Parameters :  file_path : str
nodes : array


Select nodes, elements, and land_boundaries based on specified polygon
Create point shapefile based on xy coordinates specifed in point_data, FID is zerobased, i.e. starting at 0
Parameters :  file_path : str
attribute_def : str
point_data : array


create reference surface at individual nodes: step 1: derive max levation within connected elements setp 2: compare with zref calculated by cal_z_ref() and use the higher value between the two
The gradient of the objective function with respect to the heights (x). This gradient is a vector the same size as x. A^T (Axb)
Perform grid optimization with two solvers: (1) LBFGSB (default): minimize function 1/2*Axb^2 (2) linear least square solver (Ax=b). nodes: (x,y,z) for each node, numpy array, z is elevation (a place holder, valuse not used) elements: node numbers (3) for each element, numpy array land_boundaries: (land boubdary node pair index, node 1, node 2, segment no, sequence in segment), numpy array dem_list_file: a text file, containing a list of DEM used to derive elevation opt_parms: [[damp, damp_shoreline, face_coeff, volume_coeff]], list output_files: True or False, whether to create output files outfile_prefix: Prefix used for names of output files
define the function to be minimize using LBFGSB algorithm 1/2*Axb^2
check whether specified optimization parameters are valid
Decide if a point is inside a polygon using the ray casting method
Parameters :  x,y : float
poly: List :


Returns :  inside : boolean

Read boundary node list file Reads as (no of adjacent node pairs, 1st node no, 2nd node no, boundary segment, sequence in segment) usually generated by other scripts, can be used with .2dm or .gr3 file without boundary node information. Mainly used during the developmnet phase, kept for debugging purpose
create a .gr3 file with optimized elevations, but no boundary information