======================================================== Technical notes on the Flexpart WRF installation program ======================================================== .. _FWRFRST Overview: Overview ======== This section addresses some of the underlying details of the Flexpart WRF installation component. It is assumed to be of interest to developers and those with a need or interest in going beyond "cookbook" usage. The distribution install directory for any given distribution looks something like the following: .. code-block:: bash $ tree -L 3 -F nwp_install/install-flxwrf/flxwrfv3.3_2023-05-07 nwp_install/install-flxwrf/flxwrfv3.3_2023-05-07 ├── flxwrfinstall.py* ├── flxwrfusersetup/ │   └── flxwrfusersetup.py* ├── setup_install_env.sh └── srm/ └── flexpart2ctbt/ ├── flexpart2ctbt.f └── Makefile 3 directories, 5 files The core of the installation process is the **flxwrfinstall.py** found in each distribution directory. For example, ``nwp_install/install-flxwrf/flxwrf3.3_2023-05-07/flxwrfinstall.py``. Although the program is almost identical in each of the distributions, there are typically some minor differences - that's why each distribution has its own copy. Compile flags may be slightly different if one distribution is intended to have features that differ from another. Particularly in an experimental distribution, certain source files may come from non-standard places, or require some text modifications before being built. In general, the **flxwrfinstall.py** will be executed after ensuring that the environment is set up (see :doc:`Setup`), specifying the name of the base installation directory .. code-block:: bash $ ./flxwrfinstall.py --baseinstalldir ~/FLEXWRF3.3-Distribution With a successful distribution install in place, users will be able to create any number of independent virtual Flexpart WRF environments by using the *flxwrfusersetup.py* script within the distribution. For example, one can create a virtual WPS/WRF environment named ``MyNewFlexWRFCase`` .. code-block:: bash $ /home/ctbtuser/FLEXWRF3.3-Distribution/flxwrfusersetup.py MyNewFlexWRFCase and this will result in a local directory, ``MyNewFlexWRFCase`` consisting of the same directories one would expect in a typical Flexpart WRF runtime environment. This directory may then be modified to create a custom Flexpart WRF simulation. .. 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 Most of the contents of these directories are symbolic links into the installed distribution, though certain files, like namelists, are copies, allowing users to edit for their particular case. Usage of this environment is described in more detail in :doc:`DemoVirtualUsage`. A brief walkthrough of *flxwrfinstall.py* ========================================= The program *flxwrfinstall.py*, found in each distribution install directory, is customised for a specific distribution to be installed. When a new distribution is to be incorporated into this *nwp_install* environment, this is the file that needs to be modified for the specifics of the distribution, so this section tries to highlight the areas of importance. Just before the ``main()`` function is the first opportunity to customise the program .. code-block:: bash FLEXWRF_TARBALL_URL = 'https://www.flexpart.eu/downloads/56' DEFAULT_TESTRUN_ROOTDIR = '/tmp' We specify the location for the Flexpart WRF tar file. Additionally, since a successful installation will conclude with a runtime test, we specify the root directory where temporary test run directories will be created. *main()* -------- In short, the ``main()`` function checks a lot of environment variables and expected filesystems, calls ``srm_flexpart2ctbt_install()`` to compile and install the custom ``flexpart2ctbt`` executable for SRM generation, calls ``flexwrf_install()`` to retrieve, customise, compile and install the Flexpart WRF version, creates a *flxwrfusersetup.py* script for this new installation, and then calls ``run_tests()`` to verify that the simulation will run. It does not try to verify results, but simply reports whether execution of the pieces was successful from an operating system perspective. Note that SRM source code is available in the install directory (e.g. *nwp_install/install-flxwrf/flxwrfv3.3-2023-05-07/srm/*) for each distribution and should be included in any new distributions that are created. I don't see anything in this function that people would really want to customise other than the location of the Flexpart WRF tar zipped file. However, people who dig into this should be sure that they continue to use the same directory name prefixes defined in here, in order to avoid confusion. I think that if you want to create a new distribution, your best bet is to simply copy one of the existing ones and then modify carefully. *srm_flexpart2ctbt_install()* ------------------------------ This function takes as argument the local location of *flexpart2ctbt* source code and the location for installation. Its purpose is simply to copy this source into the new installation directory, compile, and ensure that the expected executable is found. If not, an exception is raised. *run_flexpart2ctbt_tests()* ------------------------------ There is a simple set of test case data in *nwp_install/install-flxwrf/test/*, .. code-block:: bash . ├── simple_sicily_2hr/ │   ├── AVAILABLE1 │   └── flxp_input.txt ├── test_case_flexwrf_output/ │   └── gridconc_2017-10-23/ │   ├── dates │   ├── grid_conc_20171023010000_001 │   ├── grid_conc_20171023020000_001 │   └── header └── test_case_wrfoutdata/ └── WRFOUT_2017-10-23/ ├── wrfout_d01_2017-10-23_00:00:00 ├── wrfout_d01_2017-10-23_01:00:00 └── wrfout_d01_2017-10-23_02:00:00 which provides the input data and configuration files for the test case. This function takes as argument the root dir of this test hierarchy and uses it to set up the test and run it, performing a quick, simple spot check on the output. *flexwrf_install()* ------------------- We start by looking at the ``--forceinstall`` flag to the script. If this is ``False`` (the default), then if expected executables are already present, no installation is performed. This is useful in testing/debugging the program where we might not want to wait for a full installation, or risk overwriting a working installation, each time we call the script. If it is set to ``True`` then any existing installation will be removed, and we will start from scratch Next, we retrieve the source code from the specified (``FLEXWRF_TARBALL_URL``, specified at top of source file) URL, unpack it, and perform a "spot check" on one or two files that we expect to find. We then call ``flexwrfv33_precompile_mods()`` to make customised modifications to one or more of the source and config files, relative to the original source code. The code in this function will be extremely specific to the particular distribution we're trying to create, and should be rigorously tested. Once tested, we can be assured that the changes will be faithfully made - the same way - each time we run the install program. Finally, we call ``compile()`` for compilation. It attempts to compile three versions - serial, OpenMP and MPI - testing for presence of executable after each one. If the executable is not found, an exception is raised. *run_tests()* ------------- This is set up so that we can run a list of full Flexpart WRF simulations, but currently there is only one test, ``sicity_2hr_test()``. This is just a simple test to ensure that we can take some archived test input data and configure and execute a Flexpart WRF simulation, ultimately producing the expected Flexpart WRF output files. If these files are present, it's highly likely (but not definitive), that our installation is good. If the tests generate an error, then logging output will allow us to find the run directory and try to debug the program manually. Again, this is where somebody experienced with Flexpart WRF would be of great value. Someone without this experience might struggle a lot. There is a simple set of test case data in *nwp_install/install-flxwrf/test/*, .. code-block:: bash . ├── simple_sicily_2hr/ │   ├── AVAILABLE1 │   └── flxp_input.txt ├── test_case_flexwrf_output/ │   └── gridconc_2017-10-23/ │   ├── dates │   ├── grid_conc_20171023010000_001 │   ├── grid_conc_20171023020000_001 │   └── header └── test_case_wrfoutdata/ └── WRFOUT_2017-10-23/ ├── wrfout_d01_2017-10-23_00:00:00 ├── wrfout_d01_2017-10-23_01:00:00 └── wrfout_d01_2017-10-23_02:00:00 which provides the input data and configuration files for the test case. The *flxwrfusersetup.py* script ---------------------------------------- Within the ``main()`` function are some lines of code that set up the *flxwrfusersetup.py* script. To review, this is the script that a general user will run to create a fully functional virtual Flexpart WRF environment in their local directory (see the :ref:`FWRFRST Overview` section). This allows many users access to a centrally-installed Flexpart WRF distribution (many users install their own versions, which leads to high disc usage and often a lot of confusion). Because this script is based on the creation of many symbolic links, and the copying of some files, into a new user directory, it is somewhat specific to the Flexpart WRF version being used. One version might have a slightly different set of files used for the execution environment than another version. So, somebody that wants to develop a new distribution within this **nwp_install** environment will need to go through some of the details and modify where necessary. Again, an experienced Flexpart WRF user would be valuable for this. ---- Summary ======= The **flxwrfinstall.py** script has been outlined above. Each Flexpart WRF distribution supported by this **nwp_install** environment has its own install directory, containing a set of environment variable definitions, the **flxwrfinstall.py** script customised for the desired distribution, and a **flxwrfusersetup.py** script customised for the desired distribution. In general, once the distribution directory files have been set up, it should be possible to install the distribution in a specified, centralised directory, and repeated installations should all be identical, leaving little room for questions about whether certain configuration files were set up correctly. Once the centralised distribution is set up, users may run the distribution's **flxwrfusersetup.py** script to create one more more independent virtual Flexpart WRF run environments within their own filesystems. .. toctree::