Skip to content

PREPARATION.md

Latest commit

 

History

History
138 lines (97 loc) · 6.72 KB

PREPARATION.md

File metadata and controls

138 lines (97 loc) · 6.72 KB

Preparatory steps for the 4C and QUEENS workshop

This document describes the preparatory steps necessary to participate in the 4C and QUEENS workshop during the UKACM-GACM autumn school 2025. It is recommended to go through these steps at least one day before the tutorial starts, so that any issues can be resolved in time.

For the workshop, it is not necessary to install 4C and QUEENS on your own computer. Different software containers with the necessary software already pre-installed are provided (virtual machine appliance, docker container).

The choice between a virtual machine or docker containers is either based on personal preference or might be determined by your available hardware.

  • The virtual machine only works for x86_64 architectures.
  • Participants with arm architecture, e.g. Mac users with Apple Silicon, must resort to the docker container.

We cannot provide support during the workshop on the installation of virtual machine frameworks or docker. Please test it in advance.

This document describes both scenarios:

Virtual machine

Prerequisites

This VM can be installed on any x86_64 architecture. The installation to computers with ARM processors appears to be problematic.

It is beneficial to have a powerful computer with at least 4 physical cores (better 8 or more) and 16 GB RAM, and 50 GB free space on the hard disk.

The only software needed here is Oracle VirtualBox (in the following denoted as VB). The VB version tested is 7.1. If you don't have it already, please download VB from https://www.virtualbox.org/wiki/Downloads and install it on your computer.

Installation

The virtual machine appliance is the file 4C_ukacm_gacm.ova. Note that the size of the file is about 12 Gb, so the download should be done with a solid and fast connection.

After receiving the repository locally,

  1. start VB,
  2. import the appliance into VB,
  3. adjust the setting to memory and number of CPUs, which fits to your hardware environment (note that the VM should have at least 16 GB RAM and 4 CPUs assigned),
  4. start the VM
  5. You should not be asked for a username/password. In case you are, click on the username participant. If asked for credentials, type 4C.workshop
  6. After the VM has started, please open a terminal window (you'll find the terminal icon on the left icon bar of the main window).
  7. Download the repository with the tutorial material by typing the command 
    git clone https://github.com/mayrmt/UKACM_GACM_Tutorial_4C_QUEENS.git

Test 4C Executable within VM

  1. Navigate to build folder

    cd /home/participant/4C/build/release

  2. Test exectution of one exemplary test file

    ctest -V -R ssi_mono_3D_6hex8_elch_s2i_butlervolmer.4C.yaml-p3

    if the output looks like:

    100% tests passed, 0 tests failed out of 2

    → You're finished!

    in case of failure, you should try the following steps:

  3. Reconfigure the code using:

    cmake --fresh --preset=release ../../

  4. Rebuild the 4C executable using:

    ninja full

Docker container

Prerequisites

The following software must be installed on your machine:

  • Docker to run 4C and QUEENS (Note: this might require root access)
  • ParaView to inspect 4C simulation results (Download here.)
  • A text editor or integrated development environment (IDE) of your choice to modify input files and scripts.

Getting the tutorial materials

The tutorial material is provided in a public GitHub repository.

To clone the repository to your machine, open a terminal and navigate to a directory of your choice, where the data should be stored. Then clone the repository with one of these options:

  • If you have git, a GitHub account and ssh credentials on GitHub:

    git clone git@github.com:mayrmt/UKACM_GACM_Tutorial_4C_QUEENS.git

  • If you have git, but no GitHub account:

    git clone https://github.com/mayrmt/UKACM_GACM_Tutorial_4C_QUEENS.git

  • If you do not have git on your machine: Open the GitHub repository in your browser. Then click the green <> Code button and select "Download ZIP" from the menu. Unpack/unzip the directory using the method of your choice.

Getting and running a docker container

To download and run the pre-compiled docker container for the 4C tutorial, follow the instructions for your operating system:

  • MacOS / Linux: Open a terminal and navigate into the top level directory of the tutorial repository. Then, start the docker container as follows:

    docker run -i -t -v `pwd`:/home/user/tutorial ghcr.io/4c-multiphysics/4c:latest /bin/bash

    When you execute this command for the first time, this will download the docker container from the internet. It will then start the container and open a bash shell. You will find yourself in the home/ directory of the user user with two directories, 4C (pre-installed 4C executable) and tutorial (mount point of the tutorial files on your machine that you have cloned in the previous step).

  • Windows: On Windows, there are two options to get access to the docker container. Both options require admin rights for installation, so please make sure to have one of the solutions available when starting the tutorials:

    • Windows Subsystem for Linux (wsl): Please refer to this documentation how to setup wsl. Switch to WSL 2 as described in the provided link. Then, follow the instructions for Linux (see above).

    • Docker Desktop: You may install it via the Microsoft Store of your system. Start the Docker Desktop app.

      To download and run the provided docker container,

      1. know the C:\path\to\top\level\directory\tutorial\repo
      2. Insert this path into the following command and execute it in the Command Prompt:
      docker run -i -t -v "C:\path\to\top\level\directory\tutorial\repo":/home/user/tutorial ghcr.io/4c-multiphysics/4c:latest /bin/bash

      This mounts the repository folder from your Windows environment into the docker container under /home/user/tutorial. You can edit the files in the tutorial repository in your Windows environment, but they will also be available to the docker container. Within the docker container, you will run the simulations in the Linux environment. Output can be written back to the Windows system for further inspection.