The standalone and Python (Pype) method is described in detail in the tutorial section of VMTK official site. Here we provide the instruction for C++ users to integrate VMTK with CMake medical image processing toolchain.

Compile C++ Interface from Source

For developers interested to develop vascular modeling toolkit with CMake medical image processing toolchain, you should first get familiar with CMake and the Qt-VTK-ITK build procedures.

CMake Configuration

VMTK provide SuperBuild options for standalone build. Here we would prefer to use our own VTK-ITK toolchain for greater control on dependencies.

ITK Configuration

Make sure ITK is built with Module_ITKVtkGlue:BOOL=ON to have ITK-VTK bind. Following options are necessary for VMTK dependency or else built error will appear:

Module_ITKReview:BOOL=ON
ITK_USE_SYSTEM_DOUBLECONVERSION=ON

VMTK Configuration

BUILD_DOCUMENTATION:BOOL=OFF
BUILD_SHARED_LIBS:BOOL=ON
VTK_VMTK_WRAP_PYTHON:BOOL=OFF

# Use system VTK and ITK
VMTK_USE_SUPERBUILD:BOOL=OFF
USE_SYSTEM_VTK:BOOL=ON
USE_SYSTEM_ITK:BOOL=ON

VMTK in C++ and Python

You should first get yourself familiar with VTK coding in C++. VMTK works very similar to VTK smartpointer syntax (VTK C++ Example). Once you understand the working principle of VTK, you will get used to VMTK.

vmtkScripts

VMTK work as standalone software with PypeS script. The VMTK PypeS script are available on the Github repo and you may checkout the basic tutorial here.

Change from Python to C++

As a basic illustration on converting vmtkScripts to C++ development, we use the example of centerline extraction filter (https://github.com/vmtk/vmtk/blob/master/vmtkScripts/vmtkcenterlines.py).

What we most concern is the Execute function, where PypeS actually call VMTK functions. PypeS glue VTK and VMTK functions in Python. The function name of VTK and VMTK are the same in both Python and C++ interface. To calculate polydata centerline, the class vtkvmtkPolyDataCenterlines is the core part to do the work. The class documentation (http://www.vmtk.org/doc/html/classvtkvmtkPolyDataCenterlines.html) does not provide detail description of like VTK. Therefore we need to refer the class functions from python examples.

Follow illustrate the class in both languages:

Python

from vmtk import vtkvmtk

centerlineFilter = vtkvmtk.vtkvmtkPolyDataCenterlines()
centerlineFilter.SetInputData(centerlineInputSurface)
centerlineFilter.SetSourceSeedIds(inletSeedIds)
centerlineFilter.SetTargetSeedIds(outletSeedIds)
centerlineFilter.SetRadiusArrayName("Radius")
centerlineFilter.SetEdgeArrayName("Edge")
centerlineFilter.SetEdgePCoordArrayName("PCoord")
centerlineFilter.SetAppendEndPointsToCenterlines(True)
centerlineFilter.SetCenterlineResampling(True)
centerlineFilter.SetResamplingStepLength(1)
centerlineFilter.Update()

C++

#include <vtkvmtkPolyDataCenterlines.h>

vtkSmartPointer<vtkvmtkPolyDataCenterlines> centerlineFilter = vtkSmartPointer<vtkvmtkPolyDataCenterlines>::New();
centerlineFilter->SetInputData(centerlineInputSurface);
centerlineFilter->SetSourceSeedIds(inletSeedIds);
centerlineFilter->SetTargetSeedIds(outletSeedIds);
centerlineFilter->SetAppendEndPointsToCenterlines(true);
centerlineFilter->SetCenterlineResampling(true);
centerlineFilter->SetResamplingStepLength(1);
centerlineFilter->SetRadiusArrayName("Radius");
centerlineFilter->SetEdgeArrayName("Edge");
centerlineFilter->SetEdgePCoordArrayName("PCoord");
centerlineFilter->Update();

The full VMTK class list can be checked here.

Associate Software

VMTK Slicer Module

VMTK is available through the extension manager for 3D Slicer from version 4.6.2. Main difference to the Slicer3 version is that now all VMTK modules come as one extension bundle.

VMTKLab

VMTKLab is a workflow oriented application for image-based modeling and computational hemodynamics on the cloud powered by Rescale.

Vessel Centerline Extraction

An interactive CLI software to extract vessel centerline.

Vessel Clipper

Clip vessel surface with user input centerlines. This software is a GUI version of the Vessel Centerline Extraction. Extra functions like surface clipping, domain defining are also included for CFD and morphological analysis purposes.

An interactive CLI software to extract vessel centerline.

References

• VMTK official site
• VMTK Github
• VMTK class references

The toolchain we recommended is cross platform applicable (Windows, MacOS, Linux). The procedure works almost the same on different OS. Also the suggested library packages also provide Python interface for users who are not familiar with C++ coding.

Dependencies

Beware of software version and build sequence. Wrong version may cause compilation error.

• CMake
• Qt 5.10.1
• VTK 8.2.0
• OpenCV 3.4
• ITK 4.13.3

If trying to build with Qt-5.12 and Microsoft Visual Studio 2019, then build will fail with the error error LNK2019: unresolved external symbol "__declspec(dllimport) public: __cdecl QLinkedListData::QLinkedListData(void)". The solution is to either change the toolset version to an earlier one (e.g., Visual Studio 2015) or upgrade Qt (e.g., use Qt-5.15 with Visual Studio 2019).

It is known that newer version of ITK and VTK is not compatible with VMTK 1.4.

Since the libraries relies on one another, sequence of build is also essential to bind the toolchain. Recommended flow is Qt->VTK->OpenCV->DCMTK(optnional)->ITK->others

Associate Python Versions

For users who would like to develop with Python interface, Anaconda would include most of the dependent libraries like pyqt and vtk. You may install other necessary packages like OpenCV or ITK via pip or conda.

Note that SimpleITK is a lite version of ITK that provides convenient manipulation methods for Python users. ITK also provide Python interface yet is not a popular choice for its relative complex syntax.

Install Process

Here we will demonstrate the install procedures for MSVC 2015. For Unix you may follow the CMake terminal build guild.

We recommend to build the toolchain with following folder hierarchy:

• Style 1:

    .
    ├── source
    │   ├── qt-installer.exe
    │   ├── vtk
    │   ├── itk
    │   └── ...
    ├── build
    │   ├── qt
    │   ├── vtk
    │   ├── itk
    │   └── ...
  

• Style 2:

    .
    ├── qt
    ├── vtk
    │   ├── build
    │   ├── <source-code>
    │   └── ...
    ├── itk
    │   ├── build
    │   ├── <source-code>
    │   └── ...
    ├── ...
  

Qt

1. Download Open Source Qt installer from official site
2. Follow the install instruction with the correct compiler version.

Note: Qt does not provide 64bit MinGW pre-compiled version.

VTK

1. Clone the source code

    git clone -b v8.2.0  https://github.com/Kitware/VTK.git
   

2. Open CMake and choose the source code directory and binary build directory. Here we choose Style 1 folder structure.

   

3. Press Configure and choose Visual Studio 14 2015 Win64 for 64bit build. Wait until first time configuration complete. This step may take around 10 min.

   

4. Change the following build options. Then press Configure again to take effective. Some options like Qt5_DIR and VTK_QT_VERSION will only appear after VTK_Group_Qt is checked and configured. You may need to configure several times before all the necessary values are set.

    # speed up the build
    BUILD_DOCUMENTATION:BOOL=OFF 
    BUILD_EXAMPLES:BOOL=OFF
    BUILD_TESTING:BOOL=OFF 
    # must check shared library build to export for future use
    BUILD_SHARED_LIBS:BOOL=ON
    # OpenGL stuff
    Module_vtkImagingOpenGL2:BOOL=ON
    Module_vtkIOExportOpenGL2:BOOL=ON
    Module_vtkRenderingLICOpenGL2:BOOL=ON
    #
    VTK_QT_VERSION:STRING=5
    VTK_Group_Qt:BOOL=ON
    Module_vtkGUISupportQt:BOOL=ON
    Module_vtkGUISupportQtOpenGL:BOOL=ON
    Module_vtkGUISupportQtSQL:BOOL=ON
    Module_vtkGUISupportQtWebkit:BOOL=OFF
    Qt5_DIR:PATH=${Qt5_DIR}
    Qt5Core_DIR:PATH=${Qt5_DIR}/Core
    Qt5Gui_DIR:PATH=${Qt5_DIR}/Gui
    Qt5OpenGL_DIR:PATH=${Qt5_DIR}/OpenGL
    Qt5Sql_DIR:PATH=${Qt5_DIR}/Sql
    Qt5UiPlugin_DIR:PATH=${Qt5_DIR}/UiPlugin
    Qt5Widgets_DIR:PATH=${Qt5_DIR}/Widgets
   

   

   Error box will popup after choosing VTK_Group_Qt. You need to provide the correct path to make the configuration success.

   ${Qt5_DIR} is located at <qt-install-directory>/5.10.1/msvc2015_64/lib/cmake if you are using Qt 5.10.1 and MSVC 2015.

   The new values are highlighted in red. If the configuration is complete you will see Configuring done at the lower part output, or else error messages will be displayed.

   

5. Click Generate for C++ build.
6. Double click the resulting .sln file in the binary build folder and choose build version Debug and x64.
7. Press Build -> Build Solution and wait until all build success.
8. Choose Release build type and redo step 7 again.
9. For Unix Makefile (Linux/Unix) users, after step 5 you can use make command to build the library. Similar build method applies for XCode.

OpenCV

1. Clone the source code

    git clone -b v3.4  https://github.com/opencv/opencv
   

2. Open CMake and choose the source code directory and binary build directory. Here we choose Style 1 folder structure.

3. Press Configure and choose Visual Studio 14 2015 Win64 for 64bit build. Wait until first time configuration complete. This step may take around 10 min.

4. Change the following build options. Then press Configure again to take effective.

    BUILD_DOCS:BOOL=OFF
    BUILD_EXAMPLES:BOOL=OFF
    BUILD_TESTS:BOOL=OFF
    BUILD_SHARED_LIBS:BOOL=ON
    BUILD_WITH_STATIC_CRT:BOOL=ON
    BUILD_opencv_java:BOOL=OFF
    BUILD_opencv_python3:BOOL=OFF
    WITH_MATLAB:BOOL=OFF
       
    # Choose ON if you need OpenCV with CUDA acceleration
    WITH_CUDA:BOOL=OFF
   

ITK

1. Clone the source code

    git clone -b v4.13.3  https://github.com/Kitware/ITK.git
   

2. Open CMake and choose the source code directory and binary build directory. Here we choose Style 1 folder structure.

3. Press Configure and choose Visual Studio 14 2015 Win64 for 64bit build. Wait until first time configuration complete. This step may take around 10 min.

4. Change the following build options. Then press Configure again to take effective.

    BUILD_DOCUMENTATION:BOOL=OFF
    BUILD_EXAMPLES:BOOL=OFF
    BUILD_SHARED_LIBS:BOOL=ON
    BUILD_TESTING:BOOL=OFF
   
    # VTK
    Module_ITKVtkGlue:BOOL=ON
    VTK_DIR:PATH=${CMAKE_BINARY_DIR}/VTK-build
   
    # OpenCV
    Module_ITKVideoBridgeOpenCV:BOOL=ON
    OpenCV_DIR:PATH=${CMAKE_BINARY_DIR}/OpenCV-build
   
    # VMTK requires class in ITKReview
    Module_ITKReview:BOOL=ON
    ITK_USE_SYSTEM_DOUBLECONVERSION=ON
   

5. Generate the solution and build

Other Medical Image Libraries

You can extend the toolchain with other medical image related libraries

Common Toolkit (CTK)

A set of common support code for medical imaging, surgical navigation, and related purposes.

BUILD_DOCUMENTATION:BOOL=OFF
CTK_BUILD_EXAMPLES:BOOL=OFF
CTK_BUILD_SHARED_LIBS:BOOL=ON
BUILD_TESTING:BOOL=OFF
CTK_ENABLE_DICOM:BOOL=ON
CTK_LIB_DICOM/Core:BOOL=ON
CTK_LIB_DICOM/Widgets:BOOL=ON
CTK_QT_VERSION:STRING=5
Qt5_DIR:PATH=${Qt5_DIR}

DCMTK

DCMTK is a collection of libraries and applications implementing large parts the DICOM standard. It includes software for examining, constructing and converting DICOM image files, handling offline media, sending and receiving images over a network connection, as well as demonstrative image storage and worklist servers. DCMTK is is written in a mixture of ANSI C and C++. It comes in complete source code and is made available as “open source” software.

 CMAKE_INSTALL_PREFIX:PATH=${DCMTK_INSTALL_DIR}

Vascular Modeling Toolkit (VMTK)

The Vascular Modeling Toolkit is a collection of libraries and tools for 3D reconstruction, geometric analysis, mesh generation and surface data analysis for image-based modeling of blood vessels.

Image Guided Surgery Software Toolkit (IGSTK)

The Image-Guided Surgery Toolkit (IGSTK) is a framework that integrates a set of high-level components with low-level open source software libraries and application programming interfaces (APIs) from hardware vendors. In addition to its interface to common tracking hardware (e.g., Aurora from Northern Digital Inc.), IGSTK has a GUI.

TubeTK

TubeTK is an open-source toolkit for the segmentation, registration, and analysis of tubes and surfaces in images.

Tubes and surfaces, as generalized 1D and 2D manifolds in N-dimensional images, are essential components in a variety of image analysis tasks. Instances of tubular structures in images include blood vessels in magnetic resonance angiograms and b-mode ultrasound images, wires in microscopy images of integrated circuits, roads in aerial photographs, and nerves in confocal microscopy.

References

• ITK + VTK + QT on Window 7 64bit and Visual Studio 2010 Pro 32bit project

Hello World

The following source code files (assumed to be put into src/ folder) demonstrate compilation of basic hello world program called hello written in C++.

// src/Hello_world.cc
#include <iostream>

int main()
{
    std::cout << "Hello, world!\n";
}

# src/CMakeLists.txt
cmake_minimum_required(VERSION 3.10)

# set the project name
project("Hello World")

# executable to compile
add_executable(hello "Hello_world.cc")

In order for CMake to work you have to run the following bash script (placed next to the src/ folder assuming that you are working under Linux-based OS and have all necessary dependencies installed):

#!/usr/bin/env bash
# Place this file next to src/ folder
cmake -S src/ -B build/ # Generates building files into build/ folder
cmake --build build/    # Actually builds executable
build/hello             # => Hello, world! - output from compiled program

For a detailed tutorial of CMakeLists.txt, refers to derekmolloy.ie: http://derekmolloy.ie/hello-world-introductions-to-cmake/.

CMake Basic Workflow

1. Edit CMakeLists.txt: CMake will configure the build system with user provided CMakeLists.txt.
2. Generate Build Dependencies: CMake will generate necessary build files according to different platforms and compilers (-G ). For example you may choose to output `Makefile` under Linux/Unix/MinGW , `*.sln` with MSVC in Windows, or `*.xcodeproj` with XCode in MacOS.

Different Interfaces of CMake Build

CMake comes with 3 different binaries for different interface build:

• cmake: Command line interface.
• cmake-gui: Graphical user interface of cmake.
• ccmake: Console equivalent of cmake-gui. Not available in Windows distribution.

The three software can cross use after configuration. i.e. You may use cmake method to generate the initial build configuration files, then edit the dependencies with cmake-gui or ccmake interface for convenience.

Command Line (cmake)

To configure and generate CMake build system under command line mode, type the following command in Terminal:

cmake <src_dir> --build <build_dir> -G <generator>

• <src_dir> refers to the folder containing root CMakeList.txt file.
• <build_dir> specifies the binary build directory.
• <generator> specifies the build system to be used, e.g. "Visual Studio 14 2015 Win64", "Unix Makefiles"

Another commonly used CLI method for Linux/Unix system:

cd <src_dir>    # move to source code directory
mkdir build     # create build directory
cd build        # move into build directory
cmake ..        # run cmake configuration and generation build files
make            # compile the code
install         # install the build files (optional)

Graphical User Interface (cmake-gui)

1. Double click on cmake-gui

   

   1. Similar to cmake, you need to provide source code location and desired build directory.
   2. Click Configure

2. Choose the generator that suitable for your compiler

   

3. After the initial configure step, the GUI will show you a list of cache variables, similar to the list you see when you run cmake -L -N from the command line.

   

   New cache variables are highlighted in red. (In this case, that’s all of them.) If you click Configure again, the red highlights will disappear, since the variables are no longer considered new.

   Change the variables when necessary. This step is usually essential for projects that depends on third party libraries.

   Once you’ve customized the cache variables, click Generate. This will generate the build pipeline in the binary folder. You can then use it to build your project.

Console GUI (ccmake)

ccmake is the console equivalent to cmake-gui. Like the GUI, it lets you set cache variables interactively. When CLI is handy to manage cmake configurations or running CMake in remote machine, ccmake will show it’s superiority over the two other methods

ccmake is run with terminal similar to cmake

cd <src_dir>    # move to source code directory
mkdir build     # create build directory
cd build        # move into build directory
ccmake ..       # run ccmake configuration and generation build files

• Press c to start configuration
• Press t to toggle advance mode
• Use keyboard arrow keys to navigation around, with Enter key to change the values.
• Path autocomplete is available with Tab key
• After configuration, press c to re-configure again and g to generate the build files. ccmake will close after generation

To build the binary:

cd ../build # navigate to build directory
make        # compile the binary
install     # install the build files (optional)

CMake on Different Platforms

Unix Makefiles (Unix)

CMake generates a Unix makefile by default when run from the command line in a Unix-like environment. Of course, you can generate makefiles explicitly using the -G option. When generating a makefile, you should also define the CMAKE_BUILD_TYPE variable. Assuming the source folder is the parent:

cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug ..

You should define the CMAKE_BUILD_TYPE variable because makefiles generated by CMake are single-configuration. Unlike a Visual Studio solution, you can’t use the same makefile to build multiple configurations such as Debug and Release. A single makefile is capable of building exactly one build type. By default, the available types are Debug, MinSizeRel, RelWithDebInfo and Release. Watch out – if you forget to define CMAKE_BUILD_TYPE, you’ll probably get an unoptimized build without debug information, which is useless. To change to a different build type, you must re-run CMake and generate a new makefile.

Once the makefile exists, you can actually build your project by running make. By default, make will build every target that was defined by CMakeLists.txt.

• Compile all targets by default:

    make
  

• Compile specific target:

    make <target>
  

• Parallel compile: You can also parallelize the build by passing -j 4(4 refers to 4 cores, you may use a higher number if the machine is available) to make.

    make -j <num_of_threads>
  

The makefile generated by CMake detects header file dependencies automatically, so editing a single header file won’t necessarily rebuild the entire project.

Microsoft Visual Studio (Windows)

We’ll generate a Visual Studio .sln file from the CMake command line. If you have several versions of Visual Studio installed, you’ll want to tell cmake which version to use. Again, assuming that the source folder is the parent:

cmake -G "Visual Studio 14 Win64" ..

The command will generate a Visual Studio .sln file for a 32-bit build. There are no multiplatform .sln files using CMake, so for a 64-bit build, you must specify the 64-bit generator:

cmake -G "Visual Studio 15 2017" ..
cmake -G "Visual Studio 15 2017 Win64" ..

cmake -G "Visual Studio 12" ..
cmake -G "Visual Studio 12 Win64" ..
cmake -G "Visual Studio 12 2013" ..
cmake -G "Visual Studio 12 2013 Win64" ..

cmake -G "Visual Studio 14" ..
cmake -G "Visual Studio 14 Win64" ..
cmake -G "Visual Studio 14 2015" ..
cmake -G "Visual Studio 14 2015 Win64" ..

Double click the resulting .sln file in Visual Studio, go to the Solution Explorer panel, right-click the target you want to run, then choose Set as Startup Project. Build and run as you normally would.

Note that CMake adds two additional targets to the solution: ALL_BUILD and ZERO_CHECK. ZERO_CHECK automatically re-runs CMake when it detects a change to CMakeLists.txt. ALL_BUILD usually builds all other targets, making it somewhat redundant in Visual Studio. If you’re used to setting up your solutions a certain way, it might seem annoying to have these extra targets in your .sln file, but you get used to it. CMake lets you organize targets and source files into folders, but I didn’t demonstrate that in the CMakeDemo sample.

Like any Visual Studio solution, you can change build type at any time from the Solution Configuration drop-down list. The CMakeDemo sample uses CMake’s default set of build types. Release configuration doesn’t produce any debug information yet a much faster runtime than Debug. If your program consist of large size file i/o or complex computation process, Release version will provide a much swift and fast executable than Debug one.

Ninja (Windows/Unix)

CMake also exposes a Ninja generator. Ninja is similar to make, but faster. It generates a build.ninjafile, which is similar to a Makefile. The Ninja generator is also single-configuration. Ninja’s -j option auto detects the number of available CPUs.

Other Compilers (Xcode Qt Creator）

Other CMake Features

• You can perform a build from the command line, regardless of the generator used: cmake –build . –target CMakeDemo –config Debug
• You can create build pipelines that cross-compile for other environments with the help of the CMAKE_TOOLCHAIN_FILE variable.
• You can generate a compile_commands.json file that can be fed to Clang’s LibTooling library.

Recommended IDE for CMake

• Microsoft Visual Studio
  • Platform: Windows
  • Complier: MVSC
• Qt Creator
  • Platform: Windows, Linux, MacOS
  • Complier: MSVC, GCC, MinGW
• CLion (Cross Platform)
  • Platform: Windows, Linux, MacOS
  • Complier: GCC, MinGW

References

• CMake Official Site
• CMake Wiki Page
• CMake Github Page
• Introduction to CMake by Example
• Quick CMake tutorial with CLion

You may get deeper look at Slurm through the official documentations and tutorials. Here we only provide a minimal tutorial on GPU cluster setup.

Computation jobs in HPC clusters are run in sequential orders with a specialized scheduling scheme. A scheduler receive user job submissions and arrange job executions in accordance to the priority level. When requested computational resources are available the submitted jobs will be processed in order to fully utilize computation hardwares.

Slurm Architecture

Slurm is run through Linux daemons for different services:

1. slurmctld (Slurm controller daemon)
   • To monitor resources and work
   • Can setup backup controller at multiple nodes for high availability cluster
   • Works at head node
2. slurmd (Slurm worker daemon)
   • Works at compute nodes
   • Waits and executes works assigned by slurmctld and return computation status
3. slurmdbd (Slurm database daemon, optional)
   • Record accounting information into database
   • Necessary when users need to set resources limits

Slurm commands will be explained after the installation.

Slurm Installation

Head Node Configuration

1. Login to the head node
2. To make the resolution of worker nodes in the cluster clearer, we may give local hostnames in respect to their IP addresses:

    sudo vim /etc/hosts
   

   Add the associate lines:

    <ip addr of node02>      node02
    <ip addr of node03>      node03
   

3. Install the Slurm controller package:

    sudo apt-get install slurm-wlm -y
   

4. Copy and edit the default Slurm configuration file:

    cd /etc/slurm-llnl
    cp /usr/share/doc/slurm-client/examples/slurm.conf.simple.gz .
    gzip -d slurm.conf.simple.gz
    sudo mv slurm.conf.simple slurm.conf
    sudo vim slurm.conf
   

5. Set the controller node info, edit the slurm.conf file:

    SlurmctldHost=node01(<ip addr of node01>)
    # e.g.: node01(192.168.1.14)
   

6. Customize the scheduler algorithm HPC cluster jobs can be allocated in different ways. Here we will use the basic “consumable resources” approach. This refers to that each node has a list of consumable resources, including CPU cores, memory and GPUs. The request will be allocated according to default settings unless user specifications. You may edit the SelectType field as following:

    SelectType=select/cons_res
    SelectTypeParameters=CR_Core_Memory,CR_CORE_DEFAULT_DIST_BLOCK,CR_ONE_TASK_PER_CORE
   

7. Set the cluster name You may give an arbitrary name to your new cluster at ClusterName under LOGGING AND ACCOUNTING section:

    ClusterName=mycluster
   

8. Set the worker nodes We need to tell Slurm which computers in the network is used as computational nodes. Near the end of the file, the default file has an example entry for a single worker node. Change it to the one satisfy our setup:

    # here the head node (node01) also act as a worker node
    NodeName=node01 NodeAddr=<ip addr node01> CPUs=40 Sockets=2 CoresPerSocket=20 ThreadsPerCore=1 RealMemory=515896 State=UNKNOWN 
    NodeName=node02 NodeAddr=<ip addr node02> CPUs=40 Sockets=2 CoresPerSocket=20 ThreadsPerCore=1 RealMemory=515896 State=UNKNOWN 
    NodeName=node03 NodeAddr=<ip addr node03> CPUs=40 Sockets=2 CoresPerSocket=20 ThreadsPerCore=1 RealMemory=515896 State=UNKNOWN 
   

   Here we have identical nodes with dual CPU sockets. Each CPU are running with 20 cores without hyper-threading. RAM size is 515896MB.

   Kindly reminder: You may reserve a portion of computation resources in head node to prevent worker tasks jamming Slurm controller services, i.e. set CPUs to 36 and reduce the RAM size in the ‘slurm.conf’ file

9. Create a partition

   

   Partitions in Slurm group worker nodes into logical sets. Jobs and resources can be assigned by user to specific partitions with each partition running with different priority rules. This encourages different hardware owners to participate in a single cluster by sharing peripheral devices including controller and storage services.

   At the last line of slurm.conf, define the partition:

    PartitionName=partition1 Nodes=node[01-03] Default=YES MaxTime=INFINITE State=UP
   

   If you want to set a maximum job running time under partition level, you may set MaxTime=<min, hr:min:00, days-hr:min:00, or days-hr>, e.g. MaxTime=60 for 60mins and MaxTime=2-12:00:00 for 2 days 12 hours run.

10. Configure cgroups: Slurm supports Linux cgroups kernel isolation, which will restrict the access to system resources. To tell Slurm which resources are allowed access:

    sudo vim /etc/slurm-llnl.cgroup.conf
    

    Paste the following:

    CgroupMountpoint="/sys/fs/cgroup"
    CgroupAutomount=yes
    CgroupReleaseAgentDir="/etc/slurm-llnl/cgroup"
    AllowedDevicesFile="/etc/slurm-llnl/cgroup_allowed_devices_file.conf"
    ConstrainCores=yes
    TaskAffinity=no
    ConstrainRAMSpace=yes
    ConstrainSwapSpace=no
    ConstrainDevices=yes
    AllowedRamSpace=100
    AllowedSwapSpace=0
    MaxRAMPercent=100
    MaxSwapPercent=100
    MinRAMSpace=30
    

    Then you need to whitelist the system devices by creating the file /etc/slurm-llnl/cgroup_allowed_devices_file.conf:

    /dev/null
    /dev/urandom
    /dev/zero
    /dev/sda*
    /dev/cpu/*/*
    /dev/pts/*
    /clusterfs*
    

    To enable memory cgroups for restricting memory allocation by jobs you need to modify the Linux kernel upon bootup:

    sudo vim /etc/default/grub
    

    Chnage the GRUB commandline to:

    GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
    

    Update GRUB and reboot:

    sudo update-grub
    sudo reboot
    

11. Copy the configuration files to NFS To apply settings to all nodes across the cluster, copy the slurm configuration files and Munge keys to the shared drive:

    sudo cp slurm.conf cgroup.conf cgroup_allowed_devices_file.conf /clusterfs
    sudo cp /etc/munge/munge.key /clusterfs
    

    Munge acts like key-based SSH for Slurm to communicate among nodes. It generates a private key to be used on all nodes while inter-node signals are encrypted with timestamps. Receiving signals will be decrypted with the identical key. Therefore both time synchronization and munge.key are important for Slurm to work properly.

12. Start Slurm services Restart Munge:

    sudo systemctl enable munge
    sudo systemctl start munge
    

    Restart Slurm worker daemon:

    sudo systemctl enable slurmd
    sudo systemctl start slurmd
    

    Restart Slurm controller daemon:

    sudo systemctl enable slurmctld
    sudo systemctl start slurmctld
    

Worker node configuration

Repeat this part for all worker nodes except for head node

1. Install Slurm client

    sudo apt-get install slurmd slurm-client -y
   

2. Update /etc/hosts to resolve other nodes on the worker node, for example on node02:

    <ip addr>    node01
    <ip addr>    node03
   

3. Copy the configuration files from shared drives

    sudo cp /clusterfs/munge.key /etc/munge/munge.key
    sudo cp /clusterfs/slurm.conf /etc/slurm-llnl/slurm.conf
    sudo cp /clusterfs/cgroup* /etc/slurm-llnl
   

4. Start Munge

    sudo systemctl enable munge
    sudo systemctl start munge
   

5. Test Munge

    ssh <username>@node01 munge -n | unmunge
   

   You will receive result similar to the following:

    STATUS:           Success (0)
    ENCODE_HOST:      node01
    ENCODE_TIME:      2018-11-15 15:48:56 -0600 (1542318536)
    DECODE_TIME:      2018-11-15 15:48:56 -0600 (1542318536)
    TTL:              300
    CIPHER:           aes128 (4)
    MAC:              sha1 (3)
    ZIP:              none (0)
    UID:              pi
    GID:              pi
    LENGTH:           0
   

   Check /etc/munge/munge.key are the same across nodes if you get error.

6. Start Slurm worker daemon

    sudo systemctl enable slurmd
    sudo systemctl start slurmd
   

Check Slurm Work properly

Login

References

Building a Raspberry Pi Cluster Slurm documentation Ubuntu Slurm

Step 0: Hardware Setup

Here we demonstrate the setup of a small cluster unit with 1 head node and 3 child nodes. For simplicity we will the CPU architecture is assume to be x64, though similar setup also works on ARM nodes like Raspberry Pi.

Parts list

• x64 architecture computers with Nvidia GPUs x 4 (1 head + 2 child nodes, recommended identical devices, GPUs should support CUDA 8.0 or above)
• Network router with minimum 4 ports x 1 (expandable via switches, 1000Gbps recommended)

This setup is scalable to as many nodes as you have, you may also have a separate network attached storage to the system for large data I/O. Here we will use the head node to act as the storage node.

Step 1: Install OS

It would be far easier to have all cluster nodes in same OS. To reduce graphical computation resources, I highly recommend Ubuntu Server for child nodes. If you are comfortable with SSH communications and CLI Linux environment, install Ubuntu Server for head node as well, or else you may choose any Ubuntu Desktops with same distribution number as the child nodes. This is to maintain the same dependency environment across whole cluster and software can be installed simultaneously across all nodes.

Choice of OS

• GUI head node
  • Ubuntu Desktop 18.04 LTS (install in head node only)
  • Ubuntu Server 18.04 LTS (install in all child nodes)
• CLI head node
  • Ubuntu Server 18.04 LTS (install in all nodes)

Both GUI and CLI works the same afterward…as long as all Slurm setups are accomplished under CLI environment…Linux newbies may feel more comfortable with GUI version as long as the file editing can be done without knowledge of CLI editors like Nano or Vim. Under GUI Linux you can call up the CLI terminal with Ctrl + Alt + T.

Step 2: Network Setup

It is essential to keep all nodes IPs constant over time to guarantee stable communication between nodes. In most modern day routers users may login to the admin interface to bind device IP according their MAC addresses under DHCP.

Step 3: Node Setup

Slurm expects hosts to be named with a specific pattern: <nodename><nodenumber>. When choosing the hostname for the nodes, it would be convenient to name them systemically in order. (e.g. node01,node02,node03,node04,…)

Hostname

Now we may setup the hostname:

sudo hostname node01       	# whatever name you chose
sudo vim /etc/hostname    	# change the hostname here too
sudo vim /etc/hosts       	# change the hostname to "node01"

System Time

Node communication requires accurate time synchronizations. The ntpdate package will periodically synchronize OS time in the background.

sudo apt-get install ntpdate -y

Reboot

sudo reboot

Repeat the procedure for all nodes but each of them with a different node number.

Shared Storage

Storage node is one the three key components of the HPC cluster. In order for the softwares/ data be able to run on any of the nodes in the cluster, each node should be able access to the same files. In a large scale cluster there is often an individual node for data storage purposes.

In this mini setup we will use the head node to act as the storage node. A specific folder will be exported as a network file system (NFS) and mounted among all nodes. If you have a separate network attached storage (NAS), you may mount that on all nodes as NFS.

Create and Export NFS directory

1. Create mount directory in head node

   sudo mkdir /clusterfs #create NFS directory at /clusterfs
   sudo chown nobody.nogroup -R /clusterfs #/clusterfs now owned by pseduo user
   sudo chmod 777 -R /clusterfs #R/W permission for all users to the NFS directory
   

2. Export the NFS directory You need to host a NFS server in the head node.
   1. Install NFS server

       sudo apt install nfs-kernel-server -y
      

   2. Export the NFS directory Add following lines to /etc/exports:

       /clusterfs    <ip-address>/24(rw,sync,no_root_squash,no_subtree_check)
      

      where <ip-address> is the IP of the head node. You may check with router interface or via ifconfig. This permission setting allows any clients to mount the shared directory. e.g. if the LAN address is 192.168.0.123, you will have

       /clusterfs    192.168.0.123/24(rw,sync,no_root_squash,no_subtree_check)
      

   • rw provides client R/W access
   • sync forces changes to be written on each transaction
   • no_root_squash enables the root users of the clients to write files as root permissions
   • no_subtree_check prevents errors caused by a file being changed while another system is using it.
3. Update the NFS kernel server

   sudo exportfs -a
   

Mount the NFS directory

Now we have exported the NFS directory from head node to the network. On child nodes you need mount in order to work like a single directory. Repeat the following procedures for all child nodes

1. Install NFS client

   sudo apt install nfs-common -y
   

2. Create mount directory in child nodes Guess what, this is exactly the same you have done for the head node

   sudo mkdir /clusterfs #create NFS directory at /clusterfs
   sudo chown nobody.nogroup -R /clusterfs #/clusterfs now owned by pseduo user
   sudo chmod 777 -R /clusterfs #R/W permission for all users to the NFS directory
   

3. Auto mounting We want the NFS directory automatically mounted on the child nodes when they boot.
   1. Edit /etc/fstab by adding:

    <head-node-ip>:/clusterfs    /clusterfs    nfs    defaults   0 0
   

   This line refers to mounting shared directory at head node to the “local” folder /clusterfs as NFS.

   1. Actually mount the drive: sudo mount -a Once you create a file in any node’s /clusterfs it will be RWable in all other nodes.

NIS System

You will need a NIS server in order to synchronize all user’s account among the cluster network.

Configuring NIS Server

1. Install NIS System on head node

    sudo apt-get install nis
   

2. Configure this node as master
   1. Edit the NIS configuration file

       sudo vim /etc/default/nis
      

      Change the line

       NISSERVER=master
      

   2. Select proper access IPs to the NIS

       sudo vim /etc/ypserv.securenets
      

      Change the line

       # This line gives access to everybody. PLEASE ADJUST!
       # comment out
       # 0.0.0.0 0.0.0.0
       # add to the end: IP range you allow to access
       255.255.255.0   10.0.0.0
      

   3. Modify the Makefile

       sudo vim /var/yp/Makefile
      

      Change the lines

       # line 52: change
       MERGE_PASSWD=true
       # line 56: change
       MERGE_GROUP=true
      

       sudo vim /etc/hosts
      

      Add the IP address for NIS

       127.0.0.1       localhost
       # add own IP address for NIS
       10.0.0.30       dlp.srv.world        dlp
      

   4. Update the NIS database

       /usr/lib/yp/ypinit -m
      

       At this point, we have to construct a list of the hosts which will run NIS
       servers.  dlp.srv.world is in the list of NIS server hosts.  Please continue to add
       the names for the other hosts, one per line.  When you are done with the
       list, type a <control D>.
               next host to add:  dlp.srv.world
               next host to add:  # Ctrl + D キー
       The current list of NIS servers looks like this:
       dlp.srv.world
       Is this correct?  [y/n: y]  y
       We need a few minutes to build the databases...
       Building /var/yp/srv.world/ypservers...
       Running /var/yp/Makefile...
       make[1]: Entering directory '/var/yp/srv.world'
       Updating passwd.byname...
       Updating passwd.byuid...
       Updating group.byname...
       Updating group.bygid...
       Updating hosts.byname...
       Updating hosts.byaddr...
       Updating rpc.byname...
       Updating rpc.bynumber...
       Updating services.byname...
       Updating services.byservicename...
       Updating netid.byname...
       Updating protocols.bynumber...
       Updating protocols.byname...
       Updating netgroup...
       Updating netgroup.byhost...
       Updating netgroup.byuser...
       Updating shadow.byname... Ignored -> merged with passwd
       make[1]: Leaving directory '/var/yp/srv.world'
       dlp.srv.world has been set up as a NIS master server.
       Now you can run ypinit -s dlp.srv.world on all slave server.
      

   5. Restart the NIS service

       sudo systemctl restart nis
      

3. If you have added users in local servers, apply them to NIS database as well

    cd /var/yp
    make
   

Configuring NIS Client

1. Install NIS System on head node

    sudo apt-get install nis
   

2. Configure this node as client
   1. Edit the NIS configuration file

       sudo vim /etc/yp.conf
      

      Change the line

       # ypserver ypserver.network.com
       # add to the end: [domain name] [server] [NIS server's hostname]
       domain srv.world server dlp.srv.world
      

   2. Edit NS Switch Config

       sudo vim /etc/nsswitch.conf
      

      Change the lines

       # line 7: add like follows
       passwd:         compat systemd nis
       group:          compat systemd nis
       shadow:         compat nis
       gshadow:        files
       hosts:          files dns nis
      

   3. Set the PAM rule for SSH if you wan to create /home/user/ directory automatically

       sudo vim /etc/pam.d/common-session
      

      Add the lines

       # add to the end
       session optional        pam_mkhomedir.so skel=/etc/skel umask=077
      

   4. Restart the NIS

       sudo systemctl restart rpcbind nis
      

   5. Try to logout and login again and see the NIS works

   6. Change the NIS password if you want to

       yppasswd
      

       Changing NIS account information for bionic on dlp.srv.world.
       Please enter old password:
       Changing NIS password for bionic on dlp.srv.world.
       Please enter new password:
       Please retype new password:
       The NIS password has been changed on dlp.srv.world.
      

The hardware part is done. Coming next we will start to install the job scheduler Slurm.

References

• Building a Raspberry Pi Cluster
• Slurm documentation
• Running a Job on HPC using Slurm

Content

• How Does HPC Cluster Work?
  • Detailed device list of HPC cluster
• How to Maximize the HPC Ability?
• When will I Need a HPC cluster for Computational Radiology?
• Selection of Distributed Resources Management Software

How Does HPC Cluster Work?

The HPC cluster is an assembly of one or more computational devices, which can be divided into three main components:

• Nodes
• Network
• Storage

The HPC architecture connects multiple computers via networks to form a cluster. In clustering we name the computers as “nodes”. Each node may carry specific functions including job scheduling and distribution, GPU computation, heterogeneous CPU architecture computations (ARM, FPGA nodes) and data storage. Even though individual devices may only carry very low computational ability, every node is playing an important role in terms of resource leveraging. The components operate seamless together to complete a diverse set of tasks.

Detailed device list of HPC cluster

• Headnode or login node, where users log in
• Specialized data transfer node
• Regular compute nodes (where majority of computations is run)
• “Fat” compute nodes that have at least 1TB of memory
• GPU nodes (on these nodes computations can be run both on CPU cores and on a Graphical Processing Unit)
• Switch and router to connect all nodes

How to Maximize the HPC Ability?

To maximize the power of HPC clusters, one may put every nodes in full loading whole time and keep each components keep pace with each others. The data storage nodes take responsibility of raw data ingestion and analyzed data output. To transfer data among storage nodes and computational nodes, a fast network and caching technique for data input/output is one of the keystones to boost up processing speed. To maintain such coordinated works, a bunch of software toolkits are developed to automate the process.

When will I Need a HPC cluster for Computational Radiology?

Take a look at this post. Docker container is an easy to use tool for AI development, all environments are ready with single docker pull command. This is only the case when computational resources are readily available, however this is never a case comes to GPU computation. Imagine 20 PhD students in same department share a 8 card PC, this will eventually result in computer resources monopolization. The scheduling technique in HPC clusters could bring in a fair usage environment to every user of the shared devices.

Selection of Distributed Resources Management Software

There are a number of cluster resources management systems available under Linux:

• Task scheduler:
  • Slurm
  • Torque PBS
  • HTCondor (minihtcondor for single node cluster)
• Container Solution:
  • Kubernetes
  • Singularity
• and more…

Each of the resource management system has it’s unique features. The combined usage of Kubernetes and Singularity with Docker provides flexible cluster orchestration as a container solution. What if I am only a small development team and wish to automate GPU scheduling? Slurm do support GPUs as the GRES (generic resource) and thus would be the preferable management tool for small cluster system. Slurm also has been supported by the most popular cloud services providers including AWS, Azure and GCP, thus provides high flexibility to mix private and public clusters.

In the coming posts there will be hand on steps to setup a Slurm cluster.

References

• Building a Raspberry Pi Cluster
• Deploying a Burstable and Event-driven HPC Cluster on AWS Using SLURM, Part 1
• Deploying a Burstable and Event-driven HPC Cluster on AWS Using SLURM, Part 2
• Run Swarm and Kubernetes Interchangeably
• Integrating Kubernetes with Docker Enterprise Edition 2.0 – Top 10 Questions from the Docker Virtual Event

So…let’s begin!!!

What is “Computational Radiology”?

Computation radiology is to apply computer techniques and algorithms for radiographic diagnostics and treatments. The term includes two parts:

Radiology

Radiology is a medical branch focusing on the generation and interpretation of in-vivo human scans, which can be categorized through different imaging modalities:

• X-ray (XR)
• Ultrasound (US)
• Computational Tomography (CT)
• Magnetic Resonance Imaging (MR)
• and more…

Computation

In the digital era, the above-mentioned images are mostly generated and stored in digital format. In traditional medical practices the scanned images are interpreted by professional clinicians. With the continual improvement of computation technology, Computer Assisted Diagnostics (CAD) has gained more and more attentions. Followings are brief list in this field:

• Image Reconstruction
  • From raw signals to 3D medical images
  • Signal processing
• Quantitative Analysis
  • Image segmentation
  • Landmark extraction
• Image Visualization
  • 2D orthogonal images
  • 3D rendering
  • Spatial orientations
  • Image registration
• Functional Imaging
  • Cine-imaging (perfusion, angiogram)
  • Functional MRI (BOLD, ASL)
  • Diffusion Tensor Imaging
• Computer Visions
  • Machine learning (supervised and unsupervised)
  • Denoising
  • Accelerated processing (multi-CPU/GPU)
• And More…

We will start by introducing basic tools and programming skills in coming posts.

Getting Started

Getting Started: getting started with installing Lagrange, whether you are completely new to using Jekyll, or simply just migrating to a new Jekyll theme.

Example Content

Text and Formatting

Questions?

This theme is completely free and open source software. You may use it however you want, as it is distributed under the MIT License. If you are having any problems, any questions or suggestions, feel free to tweet at me, or file a GitHub issue.

More Jekyll!

Millennial

Millennial is a minimalist Jekyll blog theme that I built from scratch. The purpose of this theme is to provide a simple, clean, content-focused publishing platform for a publication or blog.

Feel free to check out the demo, where you’ll also find instructions on how to use install and use the theme.

Portfolio Jekyll Theme

This is a Jekyll theme built using the DevTips Starter Kit as a foundation for starting, and following closely the amazing tutorial by Travis Neilson over at DevTips. The purpose of this theme is to provide a clean and simple website for your portfolio. Emphasis is placed on your projects, which are shown front and center on the home page.

Everything that you will ever need to know about this Jekyll theme is included in the repository, which you can also find in the demo site.

Jekyll Starter Kit

The Jekyll Starter Kit is a simple framework for starting your own Jekyll project using all of the best practices that I learned from building my other Jekyll themes.

Feel free to check out the GitHub repository, where you’ll also find instructions on how to use install and use the theme.

Lagrange is a minimalist Jekyll theme for running a personal blog or site for free through Github Pages, or on your own server. Everything that you will ever need to know about this Jekyll theme is included in the README below, which you can also find in the demo site.

Notable features

• Compatible with GitHub Pages.

• Support for Jekyll’s built-in Sass/SCSS preprocessor and data files for making customizing easier.

• Google Analytics support.

• Commenting support powered by Disqus.

• Optimized for search engines.

• LaTeX support through MathJax.

Table of Contents

1. Introduction
   1. What is Jekyll
   2. Never Used Jeykll Before?
2. Installation
   1. GitHub Pages Installation
   2. Local Installation
   3. Directory Structure
   4. Starting From Scratch
3. Configuration
   1. Sample Posts
   2. Site Variables
   3. Adding Menu Pages
   4. Posts
   5. Layouts
   6. YAML Front Block Matter
4. Features
   1. Design Considerations
   2. Disqus
   3. Google Analytics
   4. RSS Feeds
   5. Social Media Icons
   6. MathJax
   7. Syntax Highlighting
   8. Markdown
5. Everything Else
6. Contributing
7. Questions?
8. Credits
9. License

Introduction

Lagrange is a Jekyll theme that was built to be 100% compatible with GitHub Pages. If you are unfamiliar with GitHub Pages, you can check out their documentation for more information. Jonathan McGlone’s guide on creating and hosting a personal site on GitHub is also a good resource.

What is Jekyll?

Jekyll is a simple, blog-aware, static site generator for personal, project, or organization sites. Basically, Jekyll takes your page content along with template files and produces a complete website. For more information, visit the official Jekyll site for their documentation. Codecademy also offers a great course on how to deploy a Jekyll site for complete beginners.

Never Used Jekyll Before?

The beauty of hosting your website on GitHub is that you don’t have to actually have Jekyll installed on your computer. Everything can be done through the GitHub code editor, with minimal knowledge of how to use Jekyll or the command line. All you have to do is add your posts to the _posts directory and edit the _config.yml file to change the site settings. With some rudimentary knowledge of HTML and CSS, you can even modify the site to your liking. This can all be done through the GitHub code editor, which acts like a content management system (CMS).

Installation

GitHub Pages Installation

To start using Jekyll right away with GitHub Pages, fork the Lagrange repository on GitHub. From there, you can rename your repository to ‘USERNAME.github.io’, where ‘USERNAME’ is your GitHub username, and edit the settings.yml file in the _data folder to your liking. Ensure that you have a branch named gh-pages. Your website should be ready immediately at ‘http://USERNAME.github.io’. Note: if you are hosting several sites under the same GitHub username, then you will have to use Project Pages instead of User Pages - just change the repository name to something other than ‘http://USERNAME.github.io’.

Head over to the _posts directory to view all the posts that are currently on the website, and to see examples of what post files generally look like. You can simply just duplicate the template post and start adding your own content.

Local Installation

For a full local installation of Lagrange, download your own copy of Lagrange and unzip it into it’s own directory. From there, open up your favorite command line tool, enter bundle install, and then enter jekyll serve. Your site should be up and running locally at http://localhost:4000.

Directory Structure

If you are familiar with Jekyll, then the Lagrange directory structure shouldn’t be too difficult to navigate. The following some highlights of the differences you might notice between the default directory structure. More information on what these folders and files do can be found in the Jekyll documentation site.

Lagrange/
├── _data                      # Data files
|  └── settings.yml            # Theme settings and custom text
├── _includes                  # Theme includes
├── _layouts                   # Theme layouts (see below for details)
├── _posts                     # Where all your posts will go
├── assets                     # Style sheets and images are found here
|  ├── css                     # Style sheets go here
|  |  └── main.css             # Main CSS file
|  |  └── syntax.css           # Style sheet for code syntax highlighting
|  └── img                     # Images go here
├── menu                       # Menu pages
├── _config.yml                # Site build settings
├── Gemfile                    # Ruby Gemfile for managing Jekyll plugins
├── index.md                   # Home page
├── LICENSE.md                 # License for this theme
├── README.md                  # Includes all of the documentation for this theme
└── rss-feed.xml               # Generates RSS 2.0 file which Jekyll points to

Starting From Scratch

To completely start from scratch, simply delete all the files in the _posts, assets/img, and menu folder, and add your own content. You may also replace the README.md file with your own README. Everything in the _data folder and _config.yml file can be edited to suit your needs. You may also change the favicon.ico file to your own favicon.

Configuration

Sample Posts

Visit the the demo site to find sample posts that show what different types of text formatting look like. You can find these posts in the _posts folder, which show what the best practices for setting up your own site are.

Site Variables

To change site build settings, edit the _config.yml file found in the root of your repository, which you can tweak however you like. More information on configuration settings and plugins can be found on the Jekyll documentation site. This is also where you will be able to customize the title, description, and the author/owner of your site.

If you are hosting your site on GitHub Pages, then committing a change to the _config.yml file will force a rebuild of your site with Jekyll. Any changes made should be viewable soon after. If you are hosting your site locally, then you must run jekyll serve again for the changes to take place.

In the settings.yml file found in the _data folder, you will be able to customize your site settings, such as setting Disqus comments, Google Analytics, what shows up in your menu, and social media information.

Adding Menu Pages

The menu pages are found in the menu folder in the root directory, and can be added to your menu in the settings.yml file.

Posts

You will find example posts in your _posts directory. Go ahead and edit any post and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run jekyll serve, which launches a web server and auto-regenerates your site when a file is updated.

To add new posts, simply add a file in the _posts directory that follows the convention of YYYY-MM-DD-name-of-post.md and includes the necessary front matter. Take a look at any sample post to get an idea about how it works. If you already have a website built with Jekyll, simply copy over your posts to migrate to Lagrange.

Layouts

There are two main layout options that are included with Lagrange: post and page. Layouts are specified through the YAML front block matter. Any file that contains a YAML front block matter will be processed by Jekyll. For example:

---
layout: post
title: "Example Post"
---

Examples of what posts looks like can be found in the _posts directory, which includes this post you are reading right now. Posts are the basic blog post layout, which includes a header image, post content, author name, date published, social media sharing links, and related posts.

Pages are essentially the post layout without any of the extra features of the posts layout. An example of what pages look like can be found at the About and Contacts.

In addition to the two main layout options above, there are also custom layouts that have been created for the home page and the archives page. These are simply just page layouts with some Liquid template code. Check out the index.html file in the root directory for what the code looks like.

YAML Front Block Matter

The recommended YAML front block is:

---
layout:
title:
author:
categories:
tags: []
image:
---

layout specifies which layout to use, title is the page or post title, categories can be used to better organize your posts, tags are used when generating related posts based on the topic of the post, and image specifies which images to use. Have a look at some posts in the _posts directory to see how these variables are set.

Features

Design Considerations

Lagrange was designed to be a minimalist theme in order for the focus to remain on your content. For example, links are signified mainly through an underline text-decoration, in order to maximize the perceived affordance of clickability (I originally just wanted to make the links a darker shade of grey).

Disqus

Lagrange supports comments at the end of posts through Disqus. In order to activate Disqus commenting, set disqus.comments to true in the _data/settings.yml file. If you do not have a Disqus account already, you will have to set one up, and create a profile for your website. You will be given a disqus_shortname that will be used to generate the appropriate comments sections for your site. More information on how to set up Disqus.

Google Analytics

It is possible to track your site statistics through Google Analytics. Similar to Disqus, you will have to create an account for Google Analytics, and enter the correct Google ID for your site under google-ID in the settings.yml file. More information on how to set up Google Analytics.

RSS Feeds

Atom is supported by default through jekyll-feed. With jekyll-feed, you can set configuration variables such as ‘title’, ‘description’, and ‘author’, in the _config.yml file.

RSS 2.0 is also supported through RSS auto-discovery. The rss-feed.xml file (based on the template found at jekyll-rss-feeds) that the feed path points to when using RSS 2.0 is automatically generated based on the appropriate configuration variables found in _data/settings.yml.

To use RSS 2.0, ensure the following is done:

• Uncomment the last two lines in the _config.yml file.

• In _data/settings.yml, under ‘social’, comment out the rss-square that points to feed.xml, and uncomment the rss-square that points to rss-feed.xml.

• In _includes/head.html, comment out <link type="application/atom+xml" rel="alternate" href="https://jackyko1991.github.io/feed.xml" title="jackyko1991.github.io" /> and uncomment the line under the RSS 2.0 comment.

Social Media Icons

All social media icons are courtesy of Font Awesome. You can change which icons appear, as well as the account that they link to, in the settings.yml file in the _data folder.

MathJax

Lagrange comes out of the box with MathJax, which allows you to display mathematical equations in your posts through the use of LaTeX.

Syntax Highlighting

Lagrange provides syntax highlighting through fenced code blocks. Syntax highlighting allows you to display source code in different colors and fonts depending on what programming language is being displayed. You can find the full list of supported programming languages here. Another option is to embed your code through Gist.

Markdown

As always, Jekyll offers support for GitHub Flavored Markdown, which allows you to format your posts using the Markdown syntax. Examples of these text formatting features can be seen below. You can find this post in the _posts directory as well as the README.md file.

Everything Else

Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.

Contributing

If you would like to make a feature request, or report a bug or typo in the documentation, then please submit a GitHub issue. If you would like to make a contribution, then feel free to submit a pull request - as a bonus, I will credit all contributors below! If this is your first pull request, it may be helpful to read up on the GitHub Flow first.

Lagrange has been designed as a base for users to customize and fit to their own unique needs. Please keep this in mind when requesting features and/or submitting pull requests. Some examples of changes that I would love to see are things that would make the site easier to use, or better ways of doing things. Please avoid changes that do not benefit the majority of users.

Questions?

This theme is completely free and open source software. You may use it however you want, as it is distributed under the MIT License. If you are having any problems, any questions or suggestions, feel free to tweet at me, or file a GitHub issue.

Credits

Creator

Paul Le

• www.lenpaul.com

• Twitter

• GitHub

Contributors

• nikolalukovic

• gmemstr

• lynn9388

• robqiao

• Mauladen

• dhanus

• mlewand

• Hguimaraes

• ilhamadun

Icons + Demo Images

• Death to Stock

• Font Awesome

Other

• Jekyll

• Free Code Camp

• Khan Academy

License

Open sourced under the MIT license.

As always, Jekyll offers support for GitHub Flavored Markdown, which allows you to format your posts using the Markdown syntax. Examples of these text formatting features can be seen below. You can find this post in the _posts directory.

Basic Formatting

With Markdown, it is possible to emphasize words by making them italicized, using astericks or underscores, or making them bold, using double astericks or double underscores. Of course, you can combine those two formats, with both bold and italicized text, using any combination of the above syntax. You can also add a strikethrough to text using a double tilde.

Paragraphs

This is what a paragraph looks like. For the purpose of demonstration, the rest of this paragraph and the next paragraph after will mean absolutely nothing. Proin eget nibh a massa vestibulum pretium. Suspendisse eu nisl a ante aliquet bibendum quis a nunc. Praesent varius interdum vehicula. Aenean risus libero, placerat at vestibulum eget, ultricies eu enim. Praesent nulla tortor, malesuada adipiscing adipiscing sollicitudin, adipiscing eget est. Praesent nulla tortor, malesuada adipiscing adipiscing sollicitudin, adipiscing eget est.

Proin eget nibh a massa vestibulum pretium. Suspendisse eu nisl a ante aliquet bibendum quis a nunc. Mauris lobortis nulla et felis ullamcorper bibendum. Phasellus et hendrerit mauris. Proin eget nibh a massa vestibulum pretium. Suspendisse eu nisl a ante aliquet bibendum quis a nunc. Praesent varius interdum vehicula. Aenean risus libero, placerat at vestibulum eget, ultricies eu enim. Praesent nulla tortor, malesuada adipiscing adipiscing sollicitudin, adipiscing eget est.

Headings

Sometimes it is useful to have different levels of headings to structure your documents. Start lines with # to create headings. Multiple ## in a row denote smaller heading size. The following demonstrate the full range of heading sizes:

Heading One (h1)

Heading Two (h2)

Heading Three (h3)

Heading Four (h4)

Heading Five (h5)

Heading Six (h6)

Links

You can create an inline link by wrapping link text in square brackets [ ], and then wrapping the URL in parentheses ( ). For example, it is very easy to link to Google!.

Blockquotes

Blockquotes are useful for denoting quotes, or highlighting a large block of text. Single line blockquote:

This quote will change your life.

Multi line blockquote with a cite reference:

People think focus means saying yes to the thing you’ve got to focus on. But that’s not what it means at all. It means saying no to the hundred other good ideas that there are. You have to pick carefully. I’m actually as proud of the things we haven’t done as the things I have done. Innovation is saying no to 1,000 things.

Code and Syntax Highlighting

Code blocks are part of the Markdown spec, but syntax highlighting isn’t. However, many renderers - like GitHub or most Jekyll themes - support syntax highlighting. Which languages are supported and how those language names should be written will vary from renderer to renderer. You can find the full list of supported programming languages here. Also, it is possible to do inline code blocks, by wrapping the text in ` ` ` quotations.

No language indicated, so no syntax highlighting.

def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

// Example can be run directly in your JavaScript console

// Create a function that takes two arguments and returns the sum of those arguments
var adder = new Function("a", "b", "return a + b");

// Call the function
adder(2, 6);
// > 8

Another option is to embed your code through Gist.

Images

To add an image, use ![alt text](<Image url> "Image meta title"):

Unordered and Numbered Lists

You can make an unordered and nested list by preceding one or more lines of text with -, *, or +, and indenting sublists. The following lists show the full range of possible list formats.

• List item one
  • List item one
    • List item one
    • List item two
    • List item three
    • List item four
  • List item two
  • List item three
  • List item four
• List item two
• List item three
• List item four

Numbered lists are made by using numbers instead of bullet points.

1. List item one
   1. List item one
      1. List item one
      2. List item two
      3. List item three
      4. List item four
   2. List item two
   3. List item three
   4. List item four
2. List item two
3. List item three
4. List item four

MathJax Example

The Schrödinger equation is a partial differential equation that describes how the quantum state of a quantum system changes with time:

Joseph-Louis Millennial was an Italian mathematician and astronomer who was responsible for the formulation of Lagrangian mechanics, which is a reformulation of Newtonian mechanics.

Tables

Embedding

Plenty of social media sites offer the option of embedding certain parts of their site on your own site, such as YouTube and Twitter:

New Collection

Inline HTML elements

HTML defines a long list of available inline tags, which you can mix with Markdown if you like. A complete list of which can be found on the Mozilla Developer Network.

Horizontal Rule

Can be created by having three or more hyphens ---, asterisks ***, or underscores ___:

Useful Resources

More information on Markdown can be found at the following links:

• Markdown Here Cheatsheet
• Quick Markdown Example
• Markdown Basics
• GitHub Flavoured Markdown Spec
• Basic writing and formatting syntax