Cyclops Tensor Framework (CTF)

CTF provides a domain-specific language optimized for computational chemistry and physics involving higher-order tensors (order 3+). It is designed for workloads such as coupled-cluster computations, lattice QCD, and quantum informatics.

Key application examples include:

• CCSD: Coupled-cluster computations (examples/ccsd.cxx).
• Sparse MP3: Sparse tensor operations (examples/sparse_mp3.cxx).
• Aquarius: A specialized application built on CTF.

CTF uses operator overloading and string-based indexing to build expression trees for parallel execution.

Indexing Semantics

• Contraction (Summation): If an index appears in the operands but NOT in the output, it is contracted (summed over). Example: y["i"] = R["ij"] * b["j"] (index j is contracted).
• Hadamard Product: If an index appears in both operands and the output, it is an element-wise operation. Example: x["i"] = d["i"] * y["i"].
• General Form: CTF can execute any operation of the form C["..."] += A["..."] * B["..."] provided the string lengths match the tensor orders.

// Matrix-vector multiplication with contraction on 'j'
y["i"] = R["ij"] * b["j"];

// Hadamard product
x["i"] = d["i"] * y["i"];

CTF's high-level abstractions for vectors, matrices, and higher-order tensors make it suitable for prototyping various numerical algorithms:

• Algebraic Multigrid: Requires sparse matrix multiplication (examples/algebraic_multigrid.cxx).
• Recursive Algorithms: Higher-order tensors can express algorithms like parallel scans (examples/scan.cxx) and FFT (examples/fft.cxx).
• Distributed-Memory Coordination: CTF provides interface hook-ups for ScaLAPACK, making it easy to coordinate with distributed-memory solvers.

CTF provides sparse matrix primitives that allow for the development of parallel graph algorithms. A key feature is that matrices and vectors can be defined on user-defined semirings or monoids. Multiplication of sparse matrices with sparse vectors or other sparse matrices is automatically parallelized.

Example implementations in the repository:

• Bellman-Ford (Single Source Shortest Path): examples/sssp.cxx
• Betweenness Centrality: examples/btwn_central.cxx

To build the documentation for the CTF Python library, ensure the library is installed system-wide or that its paths are correctly configured in your environment. You must install the necessary dependencies first, then use sphinx-apidoc to generate the API documentation from the source, and finally use make to compile the HTML files.

Follow these steps in the documentation directory:

1. Install requirements using pip.
2. Generate API documentation using sphinx-apidoc pointing to the ../ctf source directory.
3. Build the HTML output using make html.

pip install -r requirements.txt
sphinx-apidoc -f -o . ../ctf && make html

Use the following commands to run test suites for C++ and Python:

C++ Testing

• Sequential tests: make test
• 2-processor tests: make test2
• N-processor tests: make testN (replace N with the desired number of processors).

Python Testing

• Sequential tests: make python_test
• N-processor tests: make python_testN (replace N with the desired number of processors).

# Example: Run Python tests with 4 processors
make python_test4

The ./configure script is responsible for obtaining dependencies and setting the build type. It generates config.mk (C++), setup.py (Python), and a how-did-i-configure file.

To see all available configuration options, run ./configure --help.

After configuring, use make to build the libraries. Parallel make is supported.

C++ Libraries

• Build static library: make libctf
• Build shared library: make shared
• Install C++ libraries: make install (requires sudo if installing to system directories like /usr/local/).

Python Library

• Build Python library: make python
• Install Python library via pip: make python_install (requires sudo if not in a virtual environment).

Uninstallation

• Uninstall C++: make uninstall
• Uninstall Python: make python_uninstall

# Example: Build and install Python library
make python
make python_install

CTF follows the standard installation convention. You must first run the configure script to check dependencies and generate build files (config.mk for C++ and setup.py for Python), then build and install.

Note on MPICH Bug: If you encounter segmentation faults when running with 2 or more processors using MPICH, set the following environment variable: export MPIR_CVAR_DEVICE_COLLECTIVES=none

./configure
make
make install

The Term class and its derivatives, Sum_Term and Contract_Term, are the primary abstractions for building and manipulating tensor expressions in CTF. You can compose complex expressions using standard arithmetic operators (+, -, *) which return new Term objects.

• Term: The base abstract class for all expressions.
• Sum_Term: Represents the addition or subtraction of terms.
• Contract_Term: Represents the multiplication (contraction) of terms.

Expressions can be evaluated using .execute() or have their computational cost estimated using .estimate_time().

// Example of composing a tensor expression
// Result = (A * B) + (C * 0.5)
CTF_int::Term* expression = (A * B) + (C * 0.5);

// Execute the expression into an output tensor
expression->execute(output_tensor);

CTF has strict dependencies on MPI and BLAS. You can automate the building of supplemental packages during the ./configure step:

• ScaLAPACK: Use --build-scalapack (requires cmake). Alternatively, provide a manual library path.
• HPTT (for faster transposition): Use --build-hptt.