read an existing PEST-type structure file into a GeoStruct instance

    Parameters
    ----------
    struct_file : (str)
        existing pest-type structure file
    return_type :  (object)
        the instance type to return.  Default is GeoStruct

    Returns
    -------
    GeoStruct : list or GeoStruct

    Note
    ----
    if only on structure is listed in struct_file, then return type
    is GeoStruct.  Otherwise, return type is a list of GeoStruct

    Example
    -------
    ``>>>import pyemu``

    ``>>>gs = pyemu.utils.geostats.reads_struct_file("struct.dat")``

def read_struct_file(struct_file,return_type=GeoStruct):
    """read an existing PEST-type structure file into a GeoStruct instance

    Parameters
    ----------
    struct_file : (str)
        existing pest-type structure file
    return_type :  (object)
        the instance type to return.  Default is GeoStruct

    Returns
    -------
    GeoStruct : list or GeoStruct

    Note
    ----
    if only on structure is listed in struct_file, then return type
    is GeoStruct.  Otherwise, return type is a list of GeoStruct

    Example
    -------
    ``>>>import pyemu``

    ``>>>gs = pyemu.utils.geostats.reads_struct_file("struct.dat")``


    """

    VARTYPE = {1:SphVario,2:ExpVario,3:GauVario,4:None}
    assert os.path.exists(struct_file)
    structures = []
    variograms = []
    with open(struct_file,'r') as f:
        while True:
            line = f.readline()
            if line == '':
                break
            line = line.strip().lower()
            if line.startswith("structure"):
                name = line.strip().split()[1]
                nugget,transform,variogram_info = _read_structure_attributes(f)
                s = return_type(nugget=nugget,transform=transform,name=name)
                s.variogram_info = variogram_info
                # not sure what is going on, but if I don't copy s here,
                # all the structures end up sharing all the variograms later
                structures.append(copy.deepcopy(s))
            elif line.startswith("variogram"):
                name = line.strip().split()[1].lower()
                vartype,bearing,a,anisotropy = _read_variogram(f)
                if name in variogram_info:
                    v = VARTYPE[vartype](variogram_info[name],a,anisotropy=anisotropy,
                                         bearing=bearing,name=name)
                    variograms.append(v)

    for i,st in enumerate(structures):
        for vname in st.variogram_info:
            vfound = None
            for v in variograms:
                if v.name == vname:
                    vfound = v
                    break
            if vfound is None:
                raise Exception("variogram {0} not found for structure {1}".\
                                format(vname,s.name))

            st.variograms.append(vfound)
    if len(structures) == 1:
        return structures[0]
    return structures