README.SOWFA

All of these files compose the current version of the SOWFA (Simulator for 
Offshore Wind Farm Applications), created at the National Renewable Energy 
Laboratory (NREL).  The files are based on the OpenFOAM software and are 
either new files or modifications of files in the OpenFOAM source code 
distribution. Please see the included OpenFOAM readme file 
("README.OpenFOAM") and the GPL licence information ("COPYING"). Access
to and use of SOWPA imposes obligations on the user, as set forth in the 
NWTC Design Codes DATA USE DISCLAIMER AGREEMENT that can be found at
<https://nwtc.nrel.gov/disclaimer>.



Required OpenFOAM Version:  2.3.x or 2.4.x
Optional OpenFAST Version:  dev




Solvers and Codes Included:
A.  Solvers
    1.  ABLSolver - A  solver, primarily for performing large-eddy simulation
        (LES), for computing atmospheric boundary layer turbulent flow with
        the ability to specify surface roughness, stability, and wind speed
        and direction. It must be used with hexahedral meshes (like those
        created by OpenFOAM's blockMesh utility) in order for it to perform
        the planar averaging it does.
    2.  ABLTerrainSolver - Basically the same as ABLSolver, but the planar
        averaging done in ABLSolver is replaced with time averaging since
        planar averaging does not make sense for terrain.
    3.  windPlantSolver.<X> - A specialized version of ABLTerrainSolver for
        performing LES of wind plant flow.  It includes the ability to
        include actuator line turbine models with local grid refinement
        around the turbine. The <X> corresponds to the turbine type and is
        "ALM", "ADM", "ALMAdvanced", or "ALMAdvancedFASTv8".
    5.  pisoFoamTurbine.<X> - OpenFOAM's standard pisoFoam solver, but with the
        actuator turbine models included.  This is useful for simple cases, or
        for cases where atmospheric effects are not important, like turbines
        in wind tunnels.
    6.  turbineTestHarness.<X> - A simple code coupled to the actuator line model
        that allows you to quickly test a actuator line model setup.  It mimics
        pisoFoam, but the governing equations are not actually solved, the
        velocity field is constant through the domain, but can change as a 
        function of time.  Therefore, no axial induction is computed.  But, it
        lets one quickly test out a new actuator line model setup to see if 
        things like pitch control gains are appropriate.

    NOTE:  These solvers have been primarily tested for flow over flat terrain.
    We have tested the non-flat terrain capabilities less, but will do so in the
    future.  It is important to remember, though, that you may couple the
    actuator line models with any standard OpenFOAM solver, such as pisoFoam.



B.  Utilities
    1.  setFieldsABL - A utility to initialize the flow field for performing
        atmospheric boundary layer LES.  With the utility, you can specify
        an initial mean profile and perturbations that accelerate the
        development of turbulence will be superimposed.  You may also 
        specify the initial temperature profile and location and strength
        of the capping inversion.



C.  Libraries
    1.  finiteVolume - Contains custom boundary conditions for:
            *surface shear stress - Schumann model
            *surface temperature flux / heating - Specify a surface cooling/
             heating rate and the appropriate temperature flux is calculated
            *surface velocity - For use with surface shear stress model,
             which requires no wall-parallel velocity, but that velocity
             is required for specification of the gradient for the SGS
             model, and setting it to no-slip is not appropriate for rough
             walls
            *inflow velocity - an inflow condition that applies a log-law
             with fluctuations and drives flow to a certain speed at a 
             specified location
            *inflow temperature - an inflow temperature condition that 
             attempts to recreate a typical ABL potential temperature
             profile
            *time varying mapped fixed value with organized random
             perturbations.  Useful for taking inflow from a mesoscale
             weather model and applying temperature perturbations to
             create resolved-scale turbulence.
    2.  incompressible LES models - 
            *a modified version of OpenFOAM standard Smagorinsky model
             with Pr_t sensitization to atmospheric stability.
            *Deardorff-Lilly one-equation model.
            *Kosovic nonlinear backscatter anisotropy one-equation model.
            *a modified version of OpenFOAM standard dynamic 
             Lagrangian model of Meneveau et al. but  that writes out
             the Cs field.  Also, contains a modified version of
             that same model that clips the Cs field.
    3.  turbineModelsStandard - Contains the actuator line/disk turbine 
        models similar to that outlined by Sorensen and Shen (2002).
    4.  turbineModelsFASTv8 - Actuator line model with coupling to FAST 8
        (see http://wind.nrel.gov/designcodes/simulators/fast/) meant for
        coupling with the windPlantSolver.ALMAdvancedFASTv8 solver.
    5.  postProcessing - Function objects to simulate the sampling patterns
        of scanning lidar.  Useful for simulating lidar to understand its
        capabilities and limitations. 
    6.  fileFormats - Adds a structured VTK file format that cuts down
        on file size by greatly eliminating the write out of x,y,z points.
    7.  sampling - Adds a sampling set that defines an annulus.  Useful
        for sampling annuli in rotor plane to see blade-local flow.  Also
        adds a sampling set that does a structured array in a more
        straightforward way than the standard OpenFOAM structured array.




Installation/Compiling:
OpenFOAM:
   The included codes work only with the OpenFOAM CFD Toolbox.  The SOWFA
   repository does not include OpenFOAM.  Please visit 
   github.com/OpenFOAM/OpenFOAM-2.4.x and github.com/OpenFOAM/ThirdParty-2.4.x
   to download and install OpenFOAM.  This release of SOWFA is meant to work
   with up to OpenFOAM-2.4.x.  Making SOWFA work with versions 3.0 and higher
   may come in the near future.  

OpenFAST: 
   If you want to use the optional OpenFAST coupling (OpenFAST is NREL wind 
   turbine aero/structural/system dynamics tool), you will also need to 
   download and install this from github.com/OpenFAST/openfast making sure
   to use the dev branch.

SOWFA:
   Once OpenFOAM and OpenFAST (optional) are installed and SOWFA downloaded, 
   please follow these steps:
   1.  Put the SOWFA directory where you want it using git clone.
   2   The SOWFA repository includes a .bash_profile example file with a
       function to load the environment variables for your version of OpenFOAM
       and SOWFA.  Please adapt this and use it as necessary and get the 
       environment variables properly loaded.  One point is that the variable
       WM_PROJECT_USER_DIR will be where SOWFA gets compiled.  For example,
       WM_PROJECT_USER_DIR might get set to SOWFA-2.4.x.  Then you will have
       your original SOWFA clean repository and a compilation repository
       specific to the version of OpenFOAM you are using. (This may be helpful
       when we make SOWFA compatible with 5.0.x or v1712 within the near
       future).  Or, you can just set WM_PROJECT_USER_DIR to SOWFA so that
       compilation happens in the SOWFA repository that you downloaded from
       github.
   3.  Run ./Allwclean
   4.  Run ./Allwmake
   5.  Optionally run ./Allwclean again to clean up any extraneous files.
   6.  Make sure that no error messages appeared and that all libraries and
       applications are listed as "up to date."  



Running Tutorials:
Tutorial example cases are provide for each solver. The tutorials are
as follows
1.  example.ABL.flatTerrain.neutral
    example.ABL.flatTerrain.unstable
    example.ABL.flatTerrain.stable
    -Example cases for computing flat-terrain laterally periodic precursor
     atmospheric large-eddy simulations under the full range of stability.
    -Uses ABLSolver

2.  example.ALM
    example.ALMAdvanced
    example.ADM
    -Example cases that use the actuator turbine models using the 
     windPlantSolver.<X> solvers.  These cases assume that a precursor
     case has been run to generate inflow velocity and temperature 
     data.  Because the inflow data is large, we did not include it here.
    -Uses windPlantSolver.ALM
          windPlantSolver.ADM
          windPlantSolver.ALMAdvanced

3.  example.NREL5MW.ALMAdvancedFAST8
    -Example case that uses the FAST 8 coupled actuator line turbine model.
     The example is a single rotor in uniform, non-turbulent inflow.
    -Uses pisoFoamTurbine.ALMAdvancedFAST8 
 
4.  example.UAE_PhaseVI.ALMAdvanced/
    -A case with the setup of the NREL Unsteady Aerodynamics Experiment
     Phase VI, in the NASA Ames 80'x120' wind tunnel.
    -Uses pisoFoamTurbine.ALMAdvanced

5.  example.mesoscaleInfluence.SWiFTsiteLubbock.11Nov2013Diurnal
    -An example of using mesoscale influence to drive the atmospheric
     boundary layer LES.  This case is driven by WRF model output
     for the DOE/Sandia Scaled Wind Farm Technology (SWiFT) site in 
     Lubbock, Texas.  The terrain is flat with laterally periodic
     boundaries in this example.  The case has enough WRF output
     contained in the "forcing" directory to simulate two diurnal
     cycles starting November 11, 2013 at 00:00:00 UTC.   

To run a tutorial, change to that tutorial directory and run the
"runscript.preprocess" script to set up the mesh, etc.  Then run the
"runscript.solve.1" script to run the solver.

These are basic tutorials meant to familiarize the user with the
general file structure of a case and the various input files.  They
can be run on a small amount of processors with coarse meshes, but if 
that is done, they will generate poor results.