==================== Flexpart WRF Install ==================== Overview ======== The directory (with respect to the top of the repository) **nwp_install/install-flxwrf/** is set up to support installation of Flexpart WRF distributions. Current work has focused specifically on the installation of the Flexpart WRF v3.3 packages in a CTBTO-like CentOS 7 environment. However, I have used this kind of approach for many years on many systems for many distributions, so I think it is "generally portable." The components of this directory consist of * **flxwrfv3.3-2022-01-24/**, **flxwrfv3.3_2023-05-07/** -- these are the subdirectories with all of the installation code, one for each version [**NEED TO EXPLAIN THE DIFFERENCES IN THESE VERSIONS** -- *I believe that the newer one simply adds in the SRM flexpart2ctbt installation, but need to doublecheck this*]. My intent is to package other versions, or significant modifications to existing versions, in much the same way, with descriptive title and date of implementation. In this way, it is expected that users will be able to create their own custom distributions or have a choice of other distributions. * **test/** -- this subdirectory contains met data, configuration files, and sample output for testing an installed distribution. All of the above are explained in more detail below, focusing on one of the Flexpart WRF distributions. ---- flxwrfv3.3_2023-05-07 ====================== This is the set of resources which will install and setup, in user space (if desired) a complete Flexpart WRF distribution with a user setup script to facilitate creation of custom domains and simulations, each isolated from each other. * **setup_install_env.sh** - sets up the system-specific environment variables needed for successful installation. Most importantly, this includes paths to libraries and executables needed for Flexpart WRF installation. * **flxwrfinstall.py** - evolving script for installing and testing Flexpart WRF in a CTBTO CentOS 7 environment * Fetches tar-zipped source files * Compiles in specified location * Copies in a `flxwrfusersetup` script that allows users to create unlimited custom modeling domains based on this distribution * Installs SRM production executable * Runs a sample Flexpart WRF test case to verify things work. * **flxwrfusersetup/** - directory with Python driver to create a user-executed script for installing custom Flexpart WRF run directories based on links and copies of pertinent files from the main Flexpart WRF distribution Sample usage ------------ To install in a new dir, the base dir will be created (not recursively) if the path to it is valid. So, for example, if the user specifies installation in directory ``/home/morton/simulations/FLEXWRF3.3``, the directory ``/home/morton/simulations/`` must already exist, and the subdirectory ``FLEXWRF3.3`` will be created as part of the installation process. Basic help: .. code-block:: bash $ ./flxwrfinstall.py -h usage: flxwrfinstall.py [-h] --baseinstalldir BASEINSTALLDIR [--forceinstall] optional arguments: -h, --help show this help message and exit --baseinstalldir BASEINSTALLDIR, -b BASEINSTALLDIR (Required) Base directory for installed components --forceinstall (Optional, defaults to False if not specified) Full install over any existing installation The ``--forceinstall`` flag is there to help the user bypass compilation if desired (for example, for development of the *flxwrfinstallscript* or for performing basic tests on the installation). By default, if ``--forceinstall`` is not specified on the command-line, and the **executables already exist** in the base installation directory, then reinstallation will be skipped. We can think of this as kind of a safety device that keeps us from accidentally removing a good installation and having to go through the full compilation process again. On the other hand, there may be times when the user wants to re-install over an existing installation, with recompilation. In this case, using the ``--forceinstall`` flag will enable the recompilation. So, to perform a basic first installation, the user would first edit ``setup_install_env.sh`` and ensure the paths to libraries, etc. are specified correctly, and would then: .. code-block:: bash $ . setup_install_env.sh $ ./flxwrfinstall.py --baseinstalldir ~/FLEXWRF3.3-Distribution . . . timemanager_serial: End of simulation reached, closing output file CONGRATULATIONS: YOU HAVE SUCCESSFULLY COMPLETED A FLEXPART_WRF MODEL RUN! 2023-07-31 00:49:51,556 - INFO - flxwrfinstall.py:sicily_2hr_test:816 --> All expected output files are present 2023-07-31 00:49:51,557 - INFO - flxwrfinstall.py:sicily_2hr_test:818 --> Apparent successful completion of sicily_2hr_test... If I try it again, it will bypass the existing installation of Flexpart WRF (which is where all the compile time is spent), since, by default, the ``--forceinstall`` option is set to False). flxwrfusersetup program ----------------------- The ``flxwrfusersetup.py`` program is copied into the new distribution directory, and allows the user to create isolated, custom run directories based on this new distribution. The new run directories contain links to the large files and executables of the distribution directory, and copies of other files. It is invoked as in the following example. Assuming that the Flexpart WRF distribution was installed into ``/home/ctbtuser/FLEXWRF3.3-Distribution``, I can use this program to create a run dir as follows .. code-block:: bash $ /home/ctbtuser/FLEXWRF3.3-Distribution/flxwrfusersetup.py MyNewFlexWRFCase FLXWRF src distribution directory: /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code Creating domain: MyNewFlexWRFCase Setting up FLEXWRF run dir: MyNewFlexWRFCase/flexwrf_rundir and I can verify a full run directory as follows (a knowledgeable user would need to customise **AVAILABLE** and config files). .. code-block:: bash $ tree -L 2 MyNewFlexWRFCase MyNewFlexWRFCase └── flexwrf_rundir ├── AVAILABLE2.sample ├── AVAILABLE3.sample ├── flexwrf.input.backward1.sample ├── flexwrf.input.backward2.sample ├── flexwrf.input.forward1.sample ├── flexwrf.input.forward2.sample ├── flexwrf_mpi -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/flexwrf_mpi ├── flexwrf_omp -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/flexwrf_omp ├── flexwrf_serial -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/flexwrf_serial ├── IGBP_int1.dat -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/data/IGBP_int1.dat ├── OH_7lev_agl.dat -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/data/OH_7lev_agl.dat ├── README_FIRST.txt.sample ├── surfdata.t -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/data/surfdata.t └── surfdepo.t -> /home/ctbtuser/FLEXWRF3.3-Distribution/flexwrf_code/data/surfdepo.t 1 directory, 14 files **[WARNING - THIS DOESN'T SEEM TO HAVE THE flexpart2ctbt EXECUTABLE IN IT. I NEED TO COME BACK AND LOOK AT THIS]** ---- Summary ======= This set of installation programs has been created to make it somewhat easy to deploy a wide range of versions of Flexpart WRF, allowing for great flexibility in modeling environments. The ``flxwrfusersetup.py`` script allows the user to create a number of custom run directories based on the distribution of their choice. Please refer to the :doc:`Flexpart WRF Install Technical Notes ` section if more detail is needed. .. toctree:: TechNotes/index