WIP: New tutorial

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2016-2022, Swiss National Supercomputing Center (CSCS/ETH Zurich)
+Copyright (c) 2016-2023, Swiss National Supercomputing Center (CSCS/ETH Zurich)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/howto.rst

@@ -0,0 +1,4 @@
+ReFrame How Tos
+===============
+
+This is a collection of "How To" articles on specific ReFrame usage topics.

docs/index.rst

@@ -44,11 +44,11 @@ Webinars and Tutorials
 
 .. toctree::
    :caption: Table of Contents
-   :maxdepth: 2
 
    started
    whats_new_40
-   tutorials
+   tutorial
+   howto
    configure
    topics
    manuals

docs/started.rst

@@ -105,6 +105,10 @@ The ``./bootstrap.sh`` has two additional variant options:
       The bootstrap script for ReFrame was added.
       For previous ReFrame versions you should install its requirements using ``pip install -r requirements.txt`` in a Python virtual environment.
 
+   .. versionchanged:: 4.5
+      ReFrame supports now multiarch builds and it will place all of its dependencies in an arch-specific directory under its prefix.
+      Also, ``pip`` is no more required, as the bootstrap script will start a virtual environment without ``pip`` and will fetch a fresh ``pip``, which will be used to install the dependencies.
+
 
 Enabling auto-completion
 ------------------------

docs/tutorials.rst

@@ -1,6 +1,5 @@
-=================
-ReFrame Tutorials
-=================
+Tutorials & How To
+==================
 
 
 .. toctree::

examples/tutorial/config/01_settings.py

@@ -0,0 +1,29 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+site_configuration = {
+    'systems': [
+        {
+            'name': 'tutorialsys',
+            'descr': 'Example system',
+            'hostnames': ['myhost'],
+            'partitions': [
+                {
+                    'name': 'default',
+                    'descr': 'Example partition',
+                    'scheduler': 'local',
+                    'launcher': 'local',
+                    'environs': ['baseline']
+                }
+            ]
+        }
+    ],
+    'environments': [
+        {
+            'name': 'baseline',
+            'features': ['stream']
+        }
+    ]
+}

examples/tutorial/config/02_settings.py

@@ -0,0 +1,43 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+site_configuration = {
+    'systems': [
+        {
+            'name': 'tutorialsys',
+            'descr': 'Example system',
+            'hostnames': ['myhost'],
+            'partitions': [
+                {
+                    'name': 'default',
+                    'descr': 'Example partition',
+                    'scheduler': 'local',
+                    'launcher': 'local',
+                    'environs': ['baseline', 'gnu-11.4.0', 'clang-14.0.0']
+                }
+            ]
+        }
+    ],
+    'environments': [
+        {
+            'name': 'baseline',
+            'features': ['stream']
+        },
+        {
+            'name': 'gnu-11.4.0',
+            'cc': 'gcc',
+            'cxx': 'g++',
+            'features': ['openmp'],
+            'extras': {'omp_flag': '-fopenmp'}
+        },
+        {
+            'name': 'clang-14.0.0',
+            'cc': 'clang',
+            'cxx': 'clang++',
+            'features': ['openmp'],
+            'extras': {'omp_flag': '-fopenmp'}
+        }
+    ]
+}

examples/tutorial/dockerfiles/singlenode.Dockerfile

@@ -0,0 +1,31 @@
+FROM ubuntu:22.04
+
+RUN apt-get -y update && \
+    apt-get -y install curl && \
+    apt-get -y install sudo && \
+    apt-get -y install python3-pip && \
+    apt-get -y install clang gcc git jq libomp-dev tree vim
+
+# Install reframe
+ARG REFRAME_TAG=develop
+WORKDIR /usr/local/share
+RUN git clone --depth 1 --branch $REFRAME_TAG https://github.com/reframe-hpc/reframe.git && \
+    cd reframe/ && ./bootstrap.sh
+ENV PATH=/usr/local/share/reframe/bin:$PATH
+
+# Install stream
+RUN mkdir -p stream/bin && \
+    cd stream && \
+    curl -fsSLJO https://www.cs.virginia.edu/stream/FTP/Code/stream.c && \
+    gcc -DSTREAM_ARRAY_SIZE=100000000 -O3 -Wall -fopenmp -o bin/stream.x stream.c
+ENV PATH=/usr/local/share/stream/bin:$PATH
+
+# Add tutorial user
+RUN useradd -ms /bin/bash -G sudo user && \
+    echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+
+COPY examples /home/user/reframe-examples
+RUN chown -R user:user /home/user/reframe-examples
+WORKDIR /home/user
+
+USER user

examples/tutorial/dummy/params.py

@@ -0,0 +1,49 @@
+# Copyright 2016-2024 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import reframe as rfm
+import reframe.utility.sanity as sn
+
+
+@rfm.simple_test
+class echo_test_v0(rfm.RunOnlyRegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['*']
+    executable = 'echo'
+    x = parameter([0, 1])
+    y = parameter([0, 1])
+
+    @run_after('init')
+    def skip_invalid(self):
+        self.skip_if(self.x == self.y, 'invalid parameter combination')
+
+    @run_after('init')
+    def set_executable_opts(self):
+        self.executable_opts = [f'{self.x}', f'{self.y}']
+
+    @sanity_function
+    def validate(self):
+        x = sn.extractsingle(r'(\d) (\d)', self.stdout, 1, int)
+        y = sn.extractsingle(r'(\d) (\d)', self.stdout, 2, int)
+        return sn.and_(sn.assert_eq(x, self.x), sn.assert_eq(y, self.y))
+
+
+@rfm.simple_test
+class echo_test_v1(rfm.RunOnlyRegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['*']
+    executable = 'echo'
+    xy = parameter([(0, 1), (1, 0)], fmt=lambda val: f'{val[0]}{val[1]}')
+
+    @run_after('init')
+    def set_executable_opts(self):
+        self.x, self.y = self.xy
+        self.executable_opts = [f'{self.x}', f'{self.y}']
+
+    @sanity_function
+    def validate(self):
+        x = sn.extractsingle(r'(\d) (\d)', self.stdout, 1, int)
+        y = sn.extractsingle(r'(\d) (\d)', self.stdout, 2, int)
+        return sn.and_(sn.assert_eq(x, self.x), sn.assert_eq(y, self.y))

examples/tutorial/stream/01_stream.py

@@ -0,0 +1,25 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import reframe as rfm
+import reframe.utility.sanity as sn
+
+
+@rfm.simple_test
+class stream_test(rfm.RunOnlyRegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['*']
+    executable = 'stream.x'
+
+    @sanity_function
+    def validate(self):
+        return sn.assert_found(r'Solution Validates', self.stdout)
+
+    @performance_function('MB/s')
+    def copy_bw(self):
+        return sn.extractsingle(r'Copy:\s+(\S+)', self.stdout, 1, float)
+
+    @performance_function('MB/s')
+    def triad_bw(self):
+        return sn.extractsingle(r'Triad:\s+(\S+)', self.stdout, 1, float)

examples/tutorial/stream/02_stream.py

@@ -0,0 +1,32 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import reframe as rfm
+import reframe.utility.sanity as sn
+
+
+@rfm.simple_test
+class stream_build_test(rfm.RegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['+openmp']
+    build_system = 'SingleSource'
+    sourcepath = 'stream.c'
+    executable = './stream.x'
+
+    @run_before('compile')
+    def prepare_build(self):
+        omp_flag = self.current_environ.extras.get('omp_flag')
+        self.build_system.cflags = ['-O3', omp_flag]
+
+    @sanity_function
+    def validate(self):
+        return sn.assert_found(r'Solution Validates', self.stdout)
+
+    @performance_function('MB/s')
+    def copy_bw(self):
+        return sn.extractsingle(r'Copy:\s+(\S+)', self.stdout, 1, float)
+
+    @performance_function('MB/s')
+    def triad_bw(self):
+        return sn.extractsingle(r'Triad:\s+(\S+)', self.stdout, 1, float)

examples/tutorial/stream/03_stream.py

@@ -0,0 +1,45 @@
+# Copyright 2016-2024 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import os
+import reframe as rfm
+import reframe.utility.sanity as sn
+
+
+class build_stream(rfm.CompileOnlyRegressionTest):
+    build_system = 'SingleSource'
+    sourcepath = 'stream.c'
+    executable = './stream.x'
+
+    @run_before('compile')
+    def prepare_build(self):
+        omp_flag = self.current_environ.extras.get('omp_flag')
+        self.build_system.cflags = ['-O3', omp_flag]
+
+    @sanity_function
+    def validate(self):
+        return True
+
+
+@rfm.simple_test
+class stream_test(rfm.RunOnlyRegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['+openmp']
+    stream_binary = fixture(build_stream, scope='environment')
+
+    @run_after('setup')
+    def set_executable(self):
+        self.executable = os.path.join(self.stream_binary.stagedir, 'stream.x')
+
+    @sanity_function
+    def validate(self):
+        return sn.assert_found(r'Solution Validates', self.stdout)
+
+    @performance_function('MB/s')
+    def copy_bw(self):
+        return sn.extractsingle(r'Copy:\s+(\S+)', self.stdout, 1, float)
+
+    @performance_function('MB/s')
+    def triad_bw(self):
+        return sn.extractsingle(r'Triad:\s+(\S+)', self.stdout, 1, float)

examples/tutorial/stream/04_stream.py

@@ -0,0 +1,51 @@
+# Copyright 2016-2024 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import os
+import reframe as rfm
+import reframe.utility.sanity as sn
+
+
+class build_stream(rfm.CompileOnlyRegressionTest):
+    build_system = 'SingleSource'
+    sourcepath = 'stream.c'
+    executable = './stream.x'
+
+    @run_before('compile')
+    def prepare_build(self):
+        omp_flag = self.current_environ.extras.get('omp_flag')
+        self.build_system.cflags = ['-O3', omp_flag]
+
+    @sanity_function
+    def validate(self):
+        return True
+
+
+@rfm.simple_test
+class stream_test(rfm.RunOnlyRegressionTest):
+    valid_systems = ['*']
+    valid_prog_environs = ['+openmp']
+    stream_binary = fixture(build_stream, scope='environment')
+    num_threads = variable(int, value=0)
+
+    @run_after('setup')
+    def set_executable(self):
+        self.executable = os.path.join(self.stream_binary.stagedir, 'stream.x')
+
+    @run_before('run')
+    def set_num_threads(self):
+        if self.num_threads:
+            self.env_vars['OMP_NUM_THREADS'] = self.num_threads
+
+    @sanity_function
+    def validate(self):
+        return sn.assert_found(r'Solution Validates', self.stdout)
+
+    @performance_function('MB/s')
+    def copy_bw(self):
+        return sn.extractsingle(r'Copy:\s+(\S+)', self.stdout, 1, float)
+
+    @performance_function('MB/s')
+    def triad_bw(self):
+        return sn.extractsingle(r'Triad:\s+(\S+)', self.stdout, 1, float)