2. Usage

2.1. Download

  • You can download MateriApps Installer by the following steps.

    • Download the release version

      Go to the MateriApps Installer release page to download the zip file and then extract it. The zip file you download from the release page includes a pdf version of this manual.

    • Download with git

      You can download the MateriApps Installer by typing the following command.

      git clone https://github.com/wistaria/MateriAppsInstaller.git
      

2.2. Directory Structure

  • The structure of the directory after extraction is as follows.

    | setup
    | apps
    | docs
    | tools
    | check_prefix.sh
    | macosx
    |   | install.sh
    |   | ports.sh
    |- README.md
    |- util.sh
    
  • The directory structure in setup, tools, and apps is given as follows.

    -- software_name
      |- README.md
      |- download.sh
      |- link.sh
      |- setup.sh
      |- version.sh
      |- install.sh
      |- patch
      |- config
    

Each file and directory is described below (see File Format for details). Files marked with * indicate files that always exist in the directory.

  • README.md (*)

    • It includes a brief introduction of the software and the URLs of the official website.

  • download.sh (*)

    • Download the source code archive

  • link.sh (*)

    • Create symbolic links to installed directories and configuration files

  • setup.sh (*)

    • Extract the prepared source code archive and apply the patch (if it exists)

  • version.sh (*)

    • Specify the version to download

  • install.sh (*)

    • Building and installing the program

  • patch

    • The directory where the patches are stored

  • config

    • Additional settings for installation other than the default settings, such as when using the Intel Compiler

  • In addition to the above, the following file directories are also available.

    • check_prefix.sh

      • Script to display variables that are commonly used in each script, such as the top installation directory

    • docs directory

      • A directory containing the manual and its source code

    • macosx directory

      • A directory containing scripts to install the necessary tools using Macports

    • scripts directory

      • A directory containing a set of administrative scripts

    • setup directory

      • A directory containing scripts to prepare for software installation (see Setup below for details)

2.3. Setup

  • Run setup/setup.sh before installing the software

    sh setup/setup.sh
    

    This script creates installation scripts, installation scripts and working scripts

  • Configuring the installation location for applications extracted by the MateriApps Installer

    • You can change the installation location by setting the following options in $HOME/.mainstaller.

      The installation location can be set in the $HOME/.mainstaller file as follows (you have to create it yourself):

      # Do not put spaces before or after = as it will be treated as a shell script
      
      MA_ROOT=$HOME/materiapps  # Software installation directory
      BUILD_DIR=$HOME/build     # Installation directory
      SOURCE_DIR=$HOME/source   # File download directory
      
      Table 2.1 Explanation of options

      option

      default

      description

      MA_ROOT

      $HOME/materiapps

      Software installation directory

      BUILD_DIR

      $HOME/build

      Installation directory

      SOURCE_DIR

      $HOME/source

      Source code archive file download directory

    • If this file does not exist, the software will be installed under $ HOME materiapps

    • (*) Note that the actual installation location uses the contents of the .mainstaller file at the time of the installation work described below.

2.4. Install

  • Move to each software directory and run install.sh.

    sh install.sh
    
    • When this script is executed, the build and installation will be performed automatically after downloading (download.sh) and extracting (setup.sh) the source code.

    • Depending on the software, settings for the compiler and libraries may have been defined, and they are stored as subdirectories under the config directory.

      • If you want to specify the compiler, you can add the compiler name after install.sh. The following is an example of compiling with intel.

        sh install.sh ``intel``
        
        • If you specify a settings directory that does not exist, a list of available settings is displayed.:

          $ sh install.sh help
          Error: unknown mode: help
          Available list:
          default
          intel
          
        • default

          • Basic settings used when the argument is omitted

        • intel

          • Settings for using Intel compiler, Intel MKL, Intel MPI

      • The compiler etc. can be directly specified using shell variables

      • ex.) A case of using the Intel compiler as the C compiler while using the default settings

        CC=`which icc` sh install.sh
        
      • Compiler options can be added by setting MA_EXTRA_FLAGS

        MA_EXTRA_FLAGS="-march=core-avx2" sh install.sh intel
        
      • The path of the cmake command can be specified using CMAKE

      • ISSP_UCOUNT is the path of the utilization rate measurement script in Supercomputer on Institute for Solid State Physics, and most users do not have to worry about it

      • For other variables available, see the beginning description of install.sh.

  • Run a simple test with sh runtest.sh

    • Check the existence of the installation directory

    • Check the validity of the configuration file

    • Check if the software actually works

  • The software is installed in the $ MA_ROOT/NAME/NAME-VERSION-MA_REVISION directory

    • NAME and VERSION are replaced with the software name and version respectively

      • MA_REVISION is an identifier that distinguishes when the MateriApps Installer is revised for the same version of software.

      • ex.) hphi/hphi-3.4.0-1

    • Along with the software, the configuration file NAMEvars-VERSION-MA_REVISION.sh that sets environment variables etc. is installed in $MA_ROOT/NAME/

      • ex.) hphivars-3.4.0-1.sh

      • Running sh link.sh creates a symbolic link NAMEvars.sh for NAMEvars-VERSION.sh

        • For apps, it is created under NAME

        • For tools, it is created under $MA_ROOT/env.d and loaded in $MA_ROOT/env.sh.

2.5. How to use the tools and apps

  • Tools (cmake, hdf5, python, etc.)

    • Run the following command (or write the same command in a shell initialization script)

      source $PREFIX_TOOL/env.sh
      
  • Applications (ALPS, OpenMX, MODYLAS, etc.)

    • Set environment variables (e.g. PATH) for each application using scripts.

      For example, in the case of ALPS:

      source $PREFIX_ALPS/alps/alpsvar.sh
      
    • If you want to fix the version, use the configuration file of that version.

      source $MA_ROOT/alps/alpsvar-20201106-r7860-1.sh