Package: gflex
gFlexMultiple methods to solve elastic plate flexure, designed for applications to Earth's lithosphere.These instructions are meant to take an user familiar with computers but new to (or a beginner with) Python through the basics of how to get gFlex to work. The Python scripting part towards the end should be pretty straightforward as well, insofar as information is provided on how to get and set the chosen values inside gFlex.Please leave a message if you have trouble working with gFlex; your comments could assist both you and the more general improvement of this documentation.When you use gFlex, please cite:Wickert, A. D. (2016),Open-source modular solutions for flexural isostasy: gFlex v1.0,Geosci. Model Dev.,9(3), 997–1017, doi:10.5194/gmd-9-997-2016.If you additionally want an up-to-date citation for the latest source-code release, please see that given inCITATION.cff.Download and InstallationPythongFlex has been tested onPython 3.10+.In order to run properly, gFlex requires the following Python dependencies:numpyscipymatplotlibFor users who are new to Python, follow these directions to install the Python interpreters onto your computer.LinuxUse your package manager to download and install the required Python packages. For Debian/Ubuntu, it will be something like:# Basic packagessudoapt-getinstall\pythonpython-numpypython-scipy\python-setuptoolspython-matplotlib# pip (recommended for automatic installs via setuptools)sudoapt-getinstallpython-pip# iPython console -- very useful (optional)sudoapt-getinstallipython# Sypder IDE (I don't personally use it but many others like it: optional)sudoapt-getinstallspyderWindowsDownloadpython(x,y)or another full-featured distribution such asAnaconda; both of these distributions have been tested successfully with gFlex. Python(x,y) and several others also contain the required packages (including the numerical libraries), the iPython console, and the Spyder IDE;Spyderis a nice IDE that will provide a familiar-looking interface for users accustomed to Matlab.MacThe current recommendation is to use a package manager likehomebrew. With this you can install Python, and then move on to usingpip(orhomebrew) to install the Python modules. A good introduction to this can be found here:http://www.thisisthegreenroom.com/2011/installing-python-numpy-scipy-matplotlib-and-ipython-on-lion. See theLinuxinstructions for the list of packages that you will need; after installing pip, these commands can be substituted as follows, e.g.,# Homebrewsudobrewinstallpython-numpy# Pippipinstall-rrequirements.txtRecent efforts to download Python distributions (bothAnacondaandEnthought) have not met with success with both gFlex and GRASS, thoughAnacondahas been tested successfully with Windows. As a result, it should be more successful to keep the Python packages managed better by something likehomebrewwithpip.gFlexDownloading and Installing in One Step from PyPI using pipgFlex is downloadable from the Python Package Index (PyPI); seehttps://pypi.python.org/pypi/gFlex.If you havepip, you may simply type:pipinstall
pipinstallgflex# Or if the destination install folder requires sudo access# (for UNIX-like systems)sudopipinstallgflex# pip install gFlex works too -- install is caps-insensitiveand you will have a full, running copy of the latest release version of gFlex.DownloadinggFlex may be downloaded here at GitHub, by either:Copying the link at right and pasting it into the command prompt as follows:gitclone<LINK>Downloading and extracting the compressed ZIP file (link at right)Clicking on the link to add gFlex to your local GitHub desktop app (for Windows or Mac)InstallingInstall gFlex at the command prompt usingsetuptools. If you have administrator privileges, whichis often also the case when doing this install under Windows, you may drop the "sudo". For standard Linux or Mac users, the "sudo" will remain necessary, and you will have to enter your administrator password for the program to be added to your local set of applications (e.g., as "/usr/local/bin/gflex").# For standard Linux/Mac users:sudopythonsetup.pyinstall# ORsudopythonsetup.pydevelop# If you want the install to see instantly# any changes made in the source repository# For Windows users or Unix-type users with SuperUser privileges:pythonsetup.pyinstall# ORpythonsetup.pydevelop# If you want the install to see instantly# any changes made in the source repositoryRunningOnce gFlex is installed, it is possible to run it in four ways:With a configuration fileWithin a Python scriptWithin GRASS GISAs part of the Landlab Earth-surface modeling framework, including an interface to the the Community Surface Dynamics Modeling SystemComponent Model Interface (CMI)For options 1 and 2, there are pre-built methods that can be selected along the way to visualize results. These use Python's Matplotlib plotting library. For option 3, GRASS GIS is used for visualization. In Option 4, output from Landlab can be visualized with Matplotlib, and output from CSDMS sets of models can be visualized using tools such asVisIt(CSDMS page about VisIt) andParaView. ParaView also now hasPython bindings, which can further be used to visualize outputs produced with any of these methods.With configuration fileA configuration file can be generated to run gFlex; see examples in theinput/directory. To run gFlex using this file, one simply opens a terminal window and types:# run like this:gflex<path-to-configuration-file>This can be run from any directory, as the installation of gFlex adds the program "gflex" to the system path.For help constructing configuration files, see the blank template filesinput/template1Dandinput/template2D, as well as the other examples found in theinput/directory. Theinput/directory also containsinput/README.md, which provides a further local description of the files available.input/input_helpprovides a longer explanation of what the parameters are, and is therefore reproduced immediately below for reference:; input_help; All units are SI. Not all entries are needed.; Standard parameter values for Earth are included.[mode]; 1 (line) or 2 (surface) dimensionsdimension=2; Solution method: FD (Finite Difference), FFT (Fast Fourier; Transform, not yet implemented), SAS (Spatial domain analytical; solutions), or SAS_NG (SPA, but do not require a uniform grid; - NG = "no grid"); For SAS_NG, 1D data must be provided and will be returned in; two columns: (x,q0) --> (x,w). 2D data are similar, except; will be of the form (x,y,[q0/in or w/out]); I am working on gridded output for these, so this might change; in the future.; Both the FFT and SPA techniques rely on superposition; of solutions, because they can be combined linearly, whether in; the spectral or the spatial domain)method=SPA; Plate solutions can be:;  * vWC1994 (best), or;  * G2009 (from Govers et al., 2009; not bad, but not;           as robust as vWC1994)PlateSolutionType=vWC1994[parameter]YoungsModulus=65E9PoissonsRatio=0.25GravAccel=9.8MantleDensity=3300; This is the density of material (e.g., air, water); that is filling (or leaving) the hole that was; created by flexure. If you do not have a constant; density of infilling material, for example, at a; subsiding shoreline, you must instead iterate (see; [numerical], below).InfillMaterialDensity=0[input]; space-delimited array of loads; stresses (rho*g*h) if gridded (dx (and if applicable, dy)) will be applied;   to convert them into masses; forces (rho*g*h*Area) if not gridded (SAS_NG); If the solution method (above) is selected as "SAS_NG", then this file; will actually be of the format (x,[y],q0) and the code will sort it out.; (Once again, working on a gridded output option for ungridded inputs)Loads=q0_sample/2D/central_square_load.txt;; scalar value or space-delimited array of elastic thickness(es); array used for finite difference solutionsElasticThickness=Te_sample/2D/10km_const.txt;; xw and yw are vectors of desired output points for the SAS_NG method.; If they are not specified and a SAS_NG solution is run, the solution will be; calculated at the points with the loads.; they are ignored if a different solution method is chosen.xw=yw=[output]; DeflectionOut is for writing an output file.; If this is blank, no output is printed.; Otherwise, a space-delimited ASCII file of; outputs is with this file name (and path).DeflectionOut=tmpout.txt;; Acceptable inputs to "Plot" are q0 (loads), w (deflection), or both; any; other entry here will result in no plotting.; Automatically plots a 1D line or 2D surface based on the choice; of "dimension" variable in [mode]Plot=both[numerical]; dx [m]GridSpacing_x=;; Boundary conditions can be:; (FD): 0Slope0Shear, 0Moment0Shear, 0Displacement0Slope, Mirror, or Periodic; For SAS or SAS_NG, NoOutsideLoads is valid, and no entry defaults to thisBoundaryCondition_West=BoundaryCondition_East=;; Solver can be direct or iterativeSolver=; Tolerance between iterations [m]; If you have chosen an iterative solution type ("Solver"), it will iterate; until this is the difference between two subsequent iterations.; Set as 0 if you don't want to iterateconvergence=1E-3[numerical2D]; dy [m]GridSpacing_y=;; Boundary conditions can be:; (FD): 0Slope0Shear, 0Moment0Shear, 0Displacement0Slope, Mirror, or Periodic; For SAS or SAS_NG, NoOutsideLoads is valid, and no entry defaults to thisBoundaryCondition_North=BoundaryCondition_South=;; Flag to enable lat/lon input (true/false). By default, this is falselatlon=; radius of planet [m], for lat/lon solutionsPlanetaryRadius=[verbosity]; true/false. Defaults to true.Verbose=; true/false. Defaults to false.Debug=; true/false -- total silence if true. Defaults to false.Quiet=Within a Python script (with or without a configuration file)You may run gFlex from other Python programs. When you install it (above), this also produces a Python module that you may import to access it while scripting.With no configuration file (recommended)input/run_in_script_2D.py, reproduced below, is a good example of how to set the variables and run the model. This method requires no input file, as all of the values are set inside the Python script that imports gflex. This is essentially how the GRASS GIS interface was written, and is a way to embed the abilities of gFlex into another model. A one-dimensional example,input/run_in_script_1D.py, is also available.#! /usr/bin/env pythonimportgfleximportnumpyasnpfrommatplotlibimportpyplotaspltflex=gflex.F2D()flex.Quiet=Falseflex.Method='FD'# Solution method: * FD (finite difference)#                  * SAS (superposition of analytical solutions)#                  * SAS_NG (ungridded SAS)flex.PlateSolutionType='vWC1994'# van Wees and Cloetingh (1994)# The other option is 'G2009': Govers et al. (2009)flex.Solver='direct'# direct or iterative# convergence = 1E-3 # convergence between iterations, if an iterative solution# method is chosenflex.g=9.8# acceleration due to gravityflex.E=65E9# Young's Modulusflex.nu=0.25# Poisson's Ratioflex.rho_m=3300.# MantleDensityflex.rho_fill=0.# InfiillMaterialDensityflex.Te=35000.*np.ones((50,50))# Elastic thickness [m] -- scalar but may be an arrayflex.Te[:,-3:]=0.flex.qs=np.zeros((50,50))# Template array for surface load stressesflex.qs[10:40,10:40]+=1E6# Populating this templateflex.dx=5000.# grid cell size, x-oriented [m]flex.dy=5000.# grid cell size, y-oriented [m]# Boundary conditions can be:# (FD): 0Slope0Shear, 0Moment0Shear, 0Displacement0Slope, Mirror, or Periodic# For SAS or SAS_NG, NoOutsideLoads is valid, and no entry defaults to thisflex.BC_W='0Displacement0Slope'# west boundary conditionflex.BC_E='0Moment0Shear'# east boundary conditionflex.BC_S='0Displacement0Slope'# south boundary conditionflex.BC_N='0Displacement0Slope'# north boundary condition# latitude/longitude solutions are exact for SAS, approximate otherwise#latlon = # true/false: flag to enable lat/lon input. Defaults False.#PlanetaryRadius = # radius of planet [m], for lat/lon solutionsflex.initialize()flex.run()flex.finalize()# If you want to plot the outputflex.plotChoice='both'# An output file for deflections could also be defined here# flex.wOutFile =flex.output()# Plots and/or saves output, or does nothing, depending on# whether flex.plotChoice and/or flex.wOutFile have been set# TO OBTAIN OUTPUT DIRECTLY IN PYTHON, you can assign the internal variable,# flex.w, to another variable -- or as an element in a list if you are looping# over many runs of gFlex:deflection=flex.wWith a configuration fileIf you would like to use a Python script with a configuration file, this is also possible.importgflex# To use a configuration file:filename='../gflex/input/input_f1d_test'# it works for usage (1) and (2)obj=gflex.WhichModel(filename)## SET MODEL TYPE AND DIMENSIONS HERE ##########################################ifobj.dimension==1:obj=gflex.F1D(filename)elifobj.dimension==2:obj=gflex.F2D(filename)# Then run the code!obj.initialize(filename)obj.run()obj.finalize()# Standalone plotting output if you so desireflex.plotChoice='w'obj.output()Within GRASS GISTo run gFlex inside of GRASS GIS 7, run the following commands from within a GRASS GIS session:g.extensionr.flexure
g.extensionv.flexureThis will reach into the GRASS GIS subversion repository, download the source code, and install the packages.r.flexureis used for raster grids by either finite difference or analytical methods.v.flexuretakes advantage of the ungridded analytical method to solve for flexure at an aribtrary set of load points, albeit limited to cases with constant elastic thickness. These are stored at and have help files located at, respectively:r.flexureSource:http://trac.osgeo.org/grass/browser/grass-addons/grass7/raster/r.flexureManual page (HTML):http://grass.osgeo.org/grass70/manuals/addons/r.flexure.htmlv.flexureSource:http://trac.osgeo.org/grass/browser/grass-addons/grass7/vector/v.flexureManual page (HTML):http://grass.osgeo.org/grass70/manuals/addons/v.flexure.htmlWhen runningr.flexure, it is important to ensure that the elastic thickness map is at or properly interpolated to the computational region (g.region) resolution before solving. A nearest-neighbor interpolated Te map will cause perceived gradients in elastic thickness to be very sharp, and this will strongly affect (and misdirect) the flexural solutions.As part of Landlab and the CSDMS CMILandlab is an in-development (but nearing release) Earth-surface modeling framework built to facilitate easy integration of geomorphic, ecological, hydrological, geological, etc. Earth-surface related models to simulate and investigate the links between multiple processes. gFlex can be linked with Landlab, and the code to do this is available within the Landlab repository athttps://github.com/landlab/landlab/tree/master/landlab/components/gFlex.The Landlab interface to gFlex also provides gFlex with the Community Surface Dynamics Modeling System (CSDMS)Component Model Interface (CMI)interface. This allows it to be run as a coupled component across multiple programming languages and paradigms as part of the CSDMS community of models. For more information on model coupling with CSDMS, see the example presentation athttp://csdms.colorado.edu/w/images/CSDMS_lecture7.pdfand the paper on the model coupling published byPeckham et al., "A component-based approach to integrated modeling in the geosciences: The design of CSDMS".PlottingThere are four plot choices, defined viaself.plotChoice:'q': plots the load in mantle-density-equivalent units of length'w': plots the deflection in units of length'both': plots both deflection and loads in separate panels of a 2-subplot figure'combo': (1D only): plots lithospheric deflections and the deflected mantle-density-equivalent load atop it.Note that the load does not affect the area above/below the datum filled whenrho_fill != 0. This affects the buoyant balance associated with the motion of the plate, with no additional considerations for topogrpahy. If you would like to include topogrpahy, an iterative approach (e.g., finding areas below sea level, filling them, flexing, finding new areas below sea level, and so on) is recommended.UtilitiesThe "utilities" folder currently contains only one program,flexural_wavelength_calculator.py. Operating it is simple and fairly rudimentary: just edit the input variables directly in the calculator Python file, and then run it to see what the flexural parameter, first zero-crossing point (on the load-side of the forebulge), and the flexural wavelength.CreditsDevelopment LeadAndrew D. WickertContributorsEric W. H. HuttonRelease Notes1.1.1- 2021-06-26Updated PyPI support: twine upload, README.mdThrow meaningful error if a nonuniform self.Te grid is used with the
analytical solution1.1.0- 2018-05-28Support for both Python 2 and Python 3Main codeExamplesREADME.md updatesPATH updates inCode tests includedCode testing on commit by TravisUpdated on PyPI1.0.1- 2018-05-25Final Python 2 (only) releaseAdditional documentation added1.0.0- 2017-05-10This is the update is what is available now from pypi.Minor updates to the main gFlex codesAddition of a missing "12" in the flexural wavelength calculator in the utilities.1.0- 2016-01-28First full release of gFlex in association with the now-accepted GMD paper,
"Open-source modular solutions for flexural isostasy: gFlex v1.0", by A. D. Wickert.0.9- 2015-03-05Release submitted to GMD and that appears on PyPI; this is the same as v1.0a
on umn-earth-surface.0.8.1- 2015-03-04Fixed error in PyPI integration from v0.8 and updated README.md to include
PyPI integration.0.8- 2015-03-04First fully-functional and error-checked release, and therefore the first
true non-"pre-release".0.7- 2015-01-21This release may be short-lived, but is the turning point at which work
on gFlex will go from fixing deficiencies to adding new capabilities.
As such, it is receiving version 0.7 (the last version of its parent project,
"Flexure", was 0.6 back in 2012). It now seems to be functional and stable,
and thus this tagged release will be the basis for this stage of the model
to be pulled to @csdms-contrib and @umn-earth-surface.