Merge pull request #289 from radical-collaboration/global_only

Global_only merged into main

Author: AlexReedy

CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 message: "If you use this software, please cite it using the meta-data from 'preferred-citation'."
 license: MIT
 title: "Framework for Assessing Changes To Sea-Level (FACTS)"
-version: 1.1.0
+version: 1.1.2
 url: "https://github.com/radical-collaboration/facts"
 authors:
 - family-names: "Kopp"

FACTS.py

@@ -92,7 +92,11 @@ def GenerateTask(tcfg, ecfg, pipe_name, stage_name, task_name, workflow_name="",
 
     if 'climate_data_file' in ecfg['options'].keys():
         mvar_dict["CLIMATE_DATA_FILE"]=ecfg['options']['climate_data_file']
+
+    if 'climate_gsat_data_file' in ecfg['options'].keys():
         mvar_dict["CLIMATE_GSAT_FILE"]=ecfg['options']['climate_gsat_data_file']
+
+    if 'climate_ohc_data_file' in ecfg['options'].keys():
         mvar_dict["CLIMATE_OHC_FILE"]=ecfg['options']['climate_ohc_data_file']
 
     # Give this task object a name
@@ -303,9 +307,12 @@ def match_options(wopts, eopts):
 def ParsePipelineConfig(this_mod, modcfg, global_options={}, relabel_mod=''):
 
     # Load the pipeline configuration file for this module
-
     if not "pipeline_file" in modcfg.keys():
-        modcfg['pipeline_file'] = "pipeline.yml" 
+        # Checks if there is a global option called 'pipeline_name'
+        if not 'pipeline_file' in global_options.keys():
+            modcfg['pipeline_file'] = "pipeline.yml"
+        if 'pipeline_file' in global_options.keys():
+            modcfg['pipeline_file'] = global_options['pipeline_file']
 
     if 'module_set' in modcfg.keys():
         pcfg_file = os.path.join(os.path.dirname(__file__), "modules",

docker/Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:focal
+FROM ubuntu:focal AS facts-core
 
 # set env variables for RCT and apt
 ENV DEBIAN_FRONTEND="noninteractive"
@@ -25,18 +25,40 @@ RUN python3 -m venv --system-site-packages factsVe &&\
     source factsVe/bin/activate
 
 # installs required FACTS packages
-RUN pip install --upgrade \
-        setuptools pip wheel \
-        radical.entk \
-        pyyaml==6.0
+RUN pip install --no-cache-dir --upgrade \
+        setuptools==69.0.2 pip==23.3.1 wheel==0.42.0
 
+RUN pip install --no-cache-dir \
+        radical.entk==1.42.0 \
+        pyyaml==6.0.1 \
+        xarray==2023.1.0 \
+        numpy==1.24.4 \
+        netcdf4==1.6.5
+        
 # installs R for ubuntu2 0.04 Focal
 RUN apt-get update &&\
     apt-get install -y --no-install-recommends r-base \
         cmake \
         libopenblas-dev \
         gfortran
 
+
+ARG NB_USER=jovyan
+ARG NB_UID=1000
+ENV USER ${NB_USER}
+ENV NB_UID ${NB_UID}
+ENV HOME /home/${NB_USER}
+
+RUN adduser --disabled-password \
+    --gecos "Default user" \
+    --uid ${NB_UID} \
+    ${NB_USER}
+
+# Make sure the contents of our repo are in ${HOME}
+USER root
+RUN chown -R ${NB_UID} ${HOME}
+USER ${NB_USER}
+
 # make directory for radical pilot sandbox
 RUN mkdir -p ~/radical.pilot.sandbox
 
@@ -45,3 +67,17 @@ RUN echo -e ". /factsVe/bin/activate" > ~/.bashrc
 
 # return a shell to the user
 CMD /bin/bash
+
+FROM facts-core AS facts-jupyter
+
+USER root
+RUN pip install --no-cache-dir \
+	matplotlib==3.7.4 \
+	notebook==7.0.6 \
+	jupyterlab==4.0.9 \
+	jupyter==1.0.0
+
+EXPOSE 8888
+USER ${NB_USER}
+
+#ENTRYPOINT ["jupyter", "lab","--ip=0.0.0.0","--allow-root"]

docker/develop.sh

@@ -3,4 +3,8 @@
 TAG="facts"
 
 echo "Build docker container $TAG"
-docker build -t "$TAG" .
+docker build --target facts-core -t "$TAG" .
+
+TAG="facts-jupyter"
+echo "Build docker container $TAG"
+docker build --target facts-jupyter -t "$TAG" .

docs/source/conf.py

@@ -22,7 +22,7 @@
 author = ''
 
 # The full version, including alpha/beta/rc tags
-release = '1.1.1'
+release = '1.1.2'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/configurationfiles.rst

@@ -17,6 +17,7 @@ The **global-options** section of config.yml specifies options that should, by d
 * **pyear_step**: step size between projection years
 * **pyear_end**: year in which to end projections
 * **baseyear**: zero point for sea level projections
+* **pipeline_file**: default pipeline file name (optional; defaults to 'pipeline.yml'). See *pipeline_file* under experiment step configuration.
 
 In addition, this section can specify:
 
@@ -50,7 +51,7 @@ The following third-level entries are used under the module label:
 
 * **stages**: Specifies stages from the pipeline.yml file to be run. Defaults to 'preprocess', 'fit', 'project', 'postprocess'.
 
-* **pipeline_file**: Pipeline file name. Defaults to 'pipeline.yml'. Alternatives can be useful for special cases (e.g., using only Antarctic ice sheet output from a module that produces both Greenland and Antarctic ice sheet output.)
+* **pipeline_file**: Pipeline file name. Defaults to 'pipeline.yml'. Alternatives can be useful for special cases (e.g., using only Antarctic ice sheet output from a module that produces both Greenland and Antarctic ice sheet output.) Many modules include a 'pipeline.global.yml' file for running the module without producing localized output.
 
 * **include_in_workflow**: A list of all workflows the module output should be included in at the totaling steps.
 

docs/source/misc.rst

@@ -27,3 +27,11 @@ it is broken into many files. You may either want to adjust
 the pipeline to use the full data file or produce
 your own trimmed data file that includes the GESLA sites
 of interest to you. 
+
+On the Rutgers Amarel system, some modules --
+especially emulandice -- exhibit hard-to-trace problems that appear to 
+be sensitive to the version of Python used. On Amarel, runs have been 
+successfully completed with Python 3.9.6 and 3.10.12, but not 3.6.8. In 
+the Docker container, 3.8.10 is know to run successfully. If you are
+having hard-to-identify run issues, consider checking the version of Python you are using. 
+

docs/source/quickstart.rst

@@ -22,11 +22,19 @@ Installing and Using FACTS on a GNU/Linux Workstation
    two Zenodo entries because of size limitations). (If you have multiple users of FACTS, you might want to put
    these ~60 GB of files in a common location and soft-link to each user's directory.)
 
+   Rather than installing the data files for all modules, some of which are many gigabytes in size, 
+   you might wish to create a custom version of ``modules-data.urls.txt`` that includes only the data files for modules you intended to use.
+   For example, if you are only planning on doing global projections with the modules used in the Kopp et al. (2023) manuscript, you
+   could use the ``modules-data.global-only.urls.txt`` file instead::
+
+    wget -P facts/modules-data -i facts/modules-data/modules-data.global-only.urls.txt
+
 3. Create and activate a Python virtual environment, and install FACTS's Python dependences in it. You can use `venv`, `conda` or `virtualenv` to create your Python virtual environment. See `these instructions <https://radicalpilot.readthedocs.io/en/stable/getting_started.html#Installation>`_ for further details. Using `venv`::
 
     python3 -m venv ve3
     . ve3/bin/activate
-    pip install --upgrade setuptools pip wheel radical.entk pyyaml
+    pip install --upgrade setuptools pip wheel
+    pip install radical.entk pyyaml
 
 4. Test your install by running the dummy experiment::
 
@@ -46,13 +54,18 @@ Installing and Using FACTS on a GNU/Linux Workstation
 
     python3 runFACTS.py test
 
-Note that if you are running FACTS using localhost as a resource, all the input files for the experiment (which can be tens of GB) will get copied to ``~/radical.pilot.sandbox``. If you have space limits on your home directory, you may want to make this a symlink to a directory with fewer space limits prior to running FACTS.
 
-Note that the data files for a FACTS experiment and transfered to the compute
+Note that all the input files for the experiment (which can be tens of GB if you are doing local sea-level projections that rely upon CMIP output) will get copied to a sandbox
+created for each run. If you are running FACTS using localhost as a resource, this sandbox directory is ``~/radical.pilot.sandbox``. If you have space limits on your home directory, you may want to make this a symlink to a directory with fewer space limits prior to running FACTS. The task-level ``.out`` and ``.err`` files in the sandbox are key to debugging module-level code failures; thus, this sandbox is not deleted by default. However, if you wish to save space and do not need these files for debugging, you may wish to save space by deleting the subdirectories of the sandbox folder after each run.
+
+Note that the data files for a FACTS experiment are transfered to the compute
 resource with each experiment run. Thus, while it might in principle be possible
 to run FACTS on your desktop and use a remote HPC resource, you probably don't
-want to do this. At a minimum, you will want to have a fast, high-capacity
-network connection to the resource.
+want to do this. Most likely, you want to install and run FACTS directly on the remote resource.
+At a minimum, you will want to have a fast, high-capacity network connection to the resource.
+
+If you need to run on a HPC resource not previously configured for RADICAL-Pilot (see the `RADICAL-Pilot documentation <https://radicalpilot.readthedocs.io/en/stable/supported.html>`_) ,
+the resource will need to be configured. To get assistance with this, create an `issue <https://github.com/radical-cybertools/radical.pilot/issues>`_ on the RADICAL-Pilot repo.
 
 Installing and Using FACTS on a GNU/Linux Container
 ----------------------------------------------------------------------
@@ -67,6 +80,8 @@ assume FACTS resides outside the container in ``$HOME/facts`` and mounts it with
 ``/opt/facts``. At the moment, the docker environment appears to work fairly reliably when
 using localhost as the resource, but working with remote resources will require additional configuration. 
 
+The sandbox directory resides within the container at ``~/radical.pilot.sandbox``. You will likely wish to keep an eye on the size of this directory if you are doing runs that involve large files.
+
 To install FACTS through Docker please follow the steps below:
 
 1. Clone the FACTS repository::
@@ -94,6 +109,9 @@ To install FACTS through Docker please follow the steps below:
 
     modules/emulandice/emulandice_config.sh
 
+The Dockerfile also creates a ``facts-jupyter`` image, should you wish to run FACTS from a Jupyter notebook rather than the commandline. This Docker image can be launched::
+
+     docker run -it --volume=$HOME/facts:/opt/facts -w /opt/facts -p 8888:8888 facts-jupyter jupyter lab  --ip=0.0.0.0 --port=8888
 
 Testing a module with a shell script
 ------------------------------------

environment.yml

@@ -0,0 +1,13 @@
+name: ve3FACTS
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - numpy==1.24.4
+  - pyyaml==6.0.1
+  - xarray==2023.1.0
+  - netcdf4==1.6.5
+  - matplotlib==3.8.2
+  - pip==21.2.4
+  - pip:
+    - radical.entk==1.42.0

experiments/emulandice.ssp585/config.yml

@@ -5,16 +5,13 @@ global-options:
     pyear_end: 2150
     pyear_step: 10
     baseyear: 2005
+    pipeline_file: "pipeline.global.yml"
 
 climate_step:
     temperature:
         module_set: "fair"
         module: "temperature"
         generates_climate_output: true
-#        input_data_file:
-#              - "emissions.csv"
-#        options:
-#              rcmip_file: emissions.csv
 
 sealevel_step: