THOR (Tensors for High-dimensional Object Representation)

THOR is a multi-GPU implementation of tensors in tensor train format. It is designed for high-performance tensor calculations, manipulation, and research in scientific applications.

Key technical foundations:

• Thunder: A modern Fortran MPI/GPU communication library.
• DRay: A CUDA-enabled algebra of distributed arrays.

THOR provides utilities and applications across multiple languages, including Fortran, Matlab, and Python.

The Tensor_Network_Integrators directory contains examples for two primary application domains:

• WENO: A hydrodynamics code utilizing Weighted Essentially Non-Oscillatory flux reconstruction.
• HDI: High-Dimensional Integration applications.

The WENO library is organized into the following directories:

• src/ft: Contains the Full-tensor solver implementation.
• src/tt: Contains the Tensor-train solver implementation.
• src/misc: Contains various helper functions.

To use the Tensor Network Integrators, you must clone the repository recursively to ensure all submodules are included. If you have already cloned the repository without submodules, you can initialize them manually.

Initial Clone:

git clone --recursive https://github.com/lanl/thor.git

Updating existing clone:

git submodule update --init --recursive

Once the TTWENOLIB environment variable is set, you must run the appropriate setup script in your main MATLAB simulation script to initialize the solver components.

• For Tensor-Train (TT) solvers: Run tt_setup.m.
• For Full-tensor (FT) solvers: Run ft_setup.m.

Use the run command combined with getenv to ensure the correct path is used.

% For TT solver
run(getenv("TTWENOLIB") + "/tt_setup.m")

% For FT solver
run(getenv("TTWENOLIB") + "/ft_setup.m")

Specific installation procedures are provided for LANL HPC environments.

Darwin

salloc -p general
cd fortran
. load_env.sh intel
make -j
make test # optional

Chicoma

salloc --qos=debug --reservation=debug --partition=debug
cd fortran
. load_env.sh chicoma
make -j
make test # optional

To use the WENO library in MATLAB, you must define the TTWENOLIB environment variable to point to the root directory of the WENO library. This allows the setup scripts to be located dynamically.

In MATLAB

Run the following command in your startup.m file or at the beginning of your session:

setenv("TTWENOLIB", "/path/of/WENO")

In a Terminal

If running MATLAB from a terminal, export the variable before launching MATLAB:

export TTWENOLIB=/path/of/WENO

The Fortran applications require manual configuration of a make.inc file before building.

Build Steps:

1. Navigate to the fortran directory.
2. Locate a configuration file in the config subdirectory that matches your system architecture.
3. Copy that file to the fortran directory and name it make.inc.
4. Edit make.inc to specify your compiler and the paths to your BLAS/LAPACK libraries.
5. Run make to build and make test to verify the installation.

Example Build Workflow:

git clone git@github.com:lanl/thor.git
cd thor/TNI/fortran
cp config/gfortran.inc make.inc
# <edit make.inc to match your compiler and BLAS/LAPACK paths>
make -j
make test # optional

git clone git@github.com:lanl/thor.git
cd thor/TNI/fortran
cp config/gfortran.inc make.inc
# <edit make.inc>
make -j
make test # optional

To use the Tensor Train Configurational Integral (TTCI) method, ensure the following dependencies are installed and configured in your environment:

• LAMMPS: Must be installed with Python bindings available.
• ASE (Atomic Simulation Environment): Required for atomic structure handling.
• Potential files: You must provide the necessary potential files (e.g., .include, .eam).
• Structure files: You must provide structure files in LAMMPS format (e.g., .data). If you have .xyz files, they must be converted to .data format first.

The examples in the examples/ subdirectory are documented as Jupyter notebooks. To run interactive MATLAB code within Jupyter, follow these requirements:

1. MATLAB: Ensure a working MATLAB installation is available and the matlab command is in your system PATH.
2. Jupyter: Install Jupyter Notebook following the official instructions.
3. Proxy: Install the Jupyter-MATLAB proxy.

Alternative: If you cannot use Jupyter, you can open the notebook files in a browser, copy the MATLAB code, and save it as an *.m file to run directly in MATLAB.