Note: The Autotools configuration and build system was DEPRECATED in Xyce 7.10

This guide describes the basic process for compiling and installing a Xyce binary using the CMake build system. It is easiest to view these instructions with full formatting on the Xyce GitHub website. For instructions on building Xyce with the deprecated Autotools system, see the Xyce Building Guide - DEPRECATED.

Xyce can be built for serial execution or with distributed-memory (MPI) parallelism. This is determined by the parallelism enabled in the build of Trilinos used when configuring Xyce. Different variants of Xyce and Trilinos can co-exist on a system, but the variants must be installed in different directories.

Binary installers for Windows, macOS and Red Hat Linux are made available for the latest release of Xyce on the Xyce website. Installers for previous versions of Xyce may be made available upon request at the Xyce contact-us page.

Building and installing Xyce from source involves the following steps:

1. Install the prerequisite libraries and tools
2. Build and install Trilinos from the source code
3. Build and install Xyce from the Xyce website or GitHub

Note: Some install/uninstall commands may require administrative privileges on Unix-like systems.

Xyce depends on external libraries to supply enhanced parsing, mathematical algorithms and parallel communication. Most Linux distributions will have the required components already installed, or they can be added via the package manager. For Mac and Windows, refer to the System-Specific Modifications section for guidance. If needed, the prerequisites can be built from source.

Be sure all the prerequisites are installed prior to building Trilinos.

cmake \
-D CMAKE_INSTALL_PREFIX=<path/to/where-you-will-install-Trilinos> \
-D SUITESPARSE_ENABLE_PROJECTS="suitesparse_config;amd" \
<path/to/SuiteSparse> 

cmake --build -t install

mpicc -o testBUG967 testBUG967.c
mpirun -np 2 ./testBUG967

Note: Trilinos is available in some package managers, but the particular installation may not have all the features required by Xyce. If Trilinos is available, you can try to use it to configure and build Xyce. If any issue is encountered, build Trilinos using these instructions.

Note: To build Trilinos on Windows, see the Windows section under System-Specific Modifications.

Trilinos is an extensive set of numerical packages for a wide range of computational problems. This section will provide a general overview of building Trilinos for Xyce. For detailed questions on Trilinos or its build system see the Trilinos getting started page.

The current minimum version of Trilinos usable in a CMake-configured Xyce is 14.4. Versions after 16.1 have not been rigorously tested with Xyce and may not work properly. A zip file of Trilinos version 14.4 can be downloaded here.

The following process will produce a serial Trilinos installation that will contain only the libraries needed by Xyce. For a distributed-memory parallel build, be sure to understand the serial build process prior to reading the Building Trilinos with MPI Parallelism section.

It is recommended to build the necessary packages outside the Trilinos source code directories.

1. Create a directory in a convenient location where you will build a serial version of Trilinos.
2. Identify a convenient location for the Trilinos installation. On Unix-like systems, the default Trilinos installation location is /usr/local. Multiple installations of Trilinos can exist on the same system, but they must be in different directories. We recommend specifying unique sub-directories in /usr/local, such as /usr/local/trilinos_serial. The installation directory can be changed by adding the following flag to the CMake invocation.

   -D CMAKE_INSTALL_PREFIX=<path/to/where-you-will-install-Trilinos> \

3. Verify the location of your compilers. If you have compilers or libraries in non-standard locations, see the Other Trilinos Options section, below.

A CMake "initial cache" file, called trilinos-base.cmake, is included in the Xyce repository in the cmake/trilinos directory. The file contains a typical set of options for a Xyce-oriented serial Trilinos build.

To configure Trilinos (using the default /usr/local install location), enter the build directory and run:

cmake -C <path/to/Xyce>/cmake/trilinos/trilinos-base.cmake <path/to/Trilinos>

Once the configuration step has completed, run the following in the build directory to build and install Trilinos:

cmake --build . -j 2 -t install

The "-j 2" designates the number of processors to be used for compiling Trilinos. Choose an appropriate number for your system.

-D CMAKE_C_COMPILER=<C-compiler> \
-D CMAKE_CXX_COMPILER=<C++-compiler> \
-D CMAKE_Fortran_COMPILER=<Fortran-compiler> \

-DTrilinos_ENABLE_Fortran=OFF \

-DCMAKE_C_FLAGS="-Wno-error=implicit-function-declaration" \

-D AMD_LIBRARY_DIRS=/path/to/AMD/lib \
-D AMD_INCLUDE_DIRS=/path/to/AMD/include \
-D BLAS_LIBRARY_DIRS=/path/to/BLAS/lib \
-D LAPACK_LIBRARY_DIRS=/path/to/LAPACK/lib \

cmake \
-C <path/to/Xyce>/cmake/trilinos/trilinos-MPI-base.cmake \
-D CMAKE_C_COMPILER=mpicc \
-D CMAKE_CXX_COMPILER=mpicxx \
-D CMAKE_Fortran_COMPILER=mpifort \
<path/to/Trilinos>

cmake --build . -j 2 -t install

Note: If you plan to have multiple builds of Xyce on your system, they must be in different directories. We recommend specifying unique sub-directories in /usr/local, such as /usr/local/xyce_serial and /usr/local/xyce_mpi.

The generalized process for a serial configuration of Xyce, assuming Trilinos is already installed, can be summarized as:

cd <your-build-directory>
mkdir xyce-build
cd xyce-build

cmake \
-D CMAKE_INSTALL_PREFIX=<path/to/where-you-will-install-Xyce> \
-D Trilinos_ROOT=</path/to/Trilinos-install-location> \
<path/to/Xyce>

The simple CMake invocation above assumes that:

• All the required prerequisites are found in your default paths
• Trilinos is installed in the Trilinos_ROOT directory
• Xyce will be installed in the CMAKE_INSTALL_PREFIX directory
• The first compiler found in your default paths is the same one used to build Trilinos.

If a different C/C++ compiler was used to build Trilinos, specify that compiler using these commands:

-D CMAKE_C_COMPILER=<C-compiler> \
-D CMAKE_CXX_COMPILER=<C++-compiler> \

You may need to use a full path if the compilers cannot be located in your default paths. If additional compiler flags need to be passed to the C/C++ compiler, use these commands:

-D CMAKE_C_FLAGS=<flags> \
-D CMAKE_CXX_FLAGS=<flags> \

If a required prerequiste is not found in your default path, then you must specify the location of those headers, libraries, or executables. Xyce provides special CMake options for some of these prerequisites, like flex and bison:

-D FLEX_EXECUTABLE=<path/to/flex-install-location>/bin/flex \
-D FLEX_INCLUDE_DIR=<path/to/flex-install-location>/include \
-D BISON_EXECUTABLE=<path/to/bison-install-location>/bin/bison \

Once the configuration step is done, run the following in the xyce-build directory to compile and install Xyce in the CMAKE_INSTALL_PREFIX directory:

cmake --build . -j 2 -t install

The -j 2 indicates that two processors should be used for compiling Xyce. Choose an appropriate number for your system.

The generalized process for a parallel configuration of Xyce, given that MPI-enabled Trilinos libraries are already installed, can be summarized as:

cd <your-build-directory>
mkdir xyce-mpi-build
cd xyce-mpi-build

cmake \
-D CMAKE_INSTALL_PREFIX=<path/to/where-you-will-install-mpi-Xyce> \
-D Trilinos_ROOT=</path/to/Trilinos-mpi-install-location> \
-D CMAKE_C_COMPILER=<mpi-C-compiler> \
-D CMAKE_CXX_COMPILER=<mpi-C++-compiler> \
<path/to/Xyce>

The simple CMake invocation above assumes that:

• All the required prerequisites are found in your default paths
• Trilinos is installed in the Trilinos_ROOT directory
• Xyce will be installed in the CMAKE_INSTALL_PREFIX directory
• The MPI compilers provided to CMAKE_C_COMPILER and CMAKE_CXX_COMPILER are the same ones used to build Trilinos.

If a required prerequisite is not found in your default path, like flex or bison, then you must specify the location of those executables (see the serial Building Xyce section, above).

As with the serial build, once the configuration step is done, run the following in the xyce-build directory to compile and install Xyce in the CMAKE_INSTALL_PREFIX directory:

cmake --build . -j 2 -t install

Xyce has a Verilog-A model compiler capability, which uses the "Xyce/ADMS" compiler tool. See the Xyce/ADMS Users Guide for more information on the capability and for instructions on using Xyce/ADMS.

To enable the feature with CMake, install ADMS prior to building Xyce. Then, to enable the capability in the Xyce build, add the following flag to the Xyce CMake invocation:

-D Xyce_PLUGIN_SUPPORT=ON \

The CMake support for the plugin capability is still being developed. As such, there are some differences from the website:

• The "toys" example is installed in /path/to/install/share/examples/toys.
• The buildxyceplugin.sh script requires the absolute path to the .va files.
• The name of the plugin file can vary by system (e.g., on a Mac, the "toys" library will be called, "libtoys.dylib", not "toys.so").

The Xyce CMake does not create an uninstall script. However, on installation it does produce an "install manifest" file, which lists every installed file with their full path. To remove a Xyce installation from a Unix-like system, simply run:

xargs rm < install_manifest.txt

Note that the above method is immediate and permanent. You may also want to uninstall Trilinos. As with Xyce, an install_manifest.txt file is produced when Trilinos is installed.

If you do not want to keep the build directories, simply copy the install_manifest.txt file(s) to a safe location (the file name can be changed). Then Xyce and/or Trilinos can be uninstalled at any time using the xarg command, above (be sure to specify the correct filename).

If you wish to test the Xyce installation, run the Xyce Regression Suite. See the Running the Xyce Regression Suite documentation on the Xyce home page. Note that the test suite is controlled with Perl and Bash scripts, and some tests require Python with Scipy and Numpy.

If many flags are being applied as part of a CMake invocation, you might want to create a configuration script. This is essentially a shell script with the CMake invocation. The following commands are for Unix-like systems. Analogous scripts can be created for Windows systems.

As an example, to configure an MPI-enabled Trilinos build, one might create a file containing:

#!/bin/sh

cmake \
-C path/to/Xyce/cmake/trilinos/trilinos-MPI-base.cmake \
-D CMAKE_C_COMPILER=mpicc \
-D CMAKE_CXX_COMPILER=mpicxx \
-D CMAKE_Fortran_COMPILER=mpifort \
-D CMAKE_INSTALL_PREFIX=$HOME/install/Trilinos/mpi/ \
path/to/Trilinos

More options can be added as needed. The file can be made executable by running the following on the command line:

chmod a+x <filename>

Running the configuration script in the build directory is the same as running the CMake configure line directly.

The instructions above are applicable to Linux and similar systems. However, additional instructions are provided here for Windows and macOS. Click on the following for more information.

cmake ^
    -C path\to\Xyce\cmake\trilinos\trilinos-base.cmake ^
    -D HAVE_TEUCHOS_LAPACKLARND=OFF ^
    -D Trilinos_ENABLE_Stokhos=OFF ^
    -D Trilinos_ENABLE_Sacado=OFF ^
    -D Trilinos_ENABLE_Amesos2=OFF ^
    ...
    path\to\Trilinos

-D Xyce_USE_FFT=TRUE
-D Xyce_USE_INTEL_FFT=TRUE

cmake --build <path to build folder> -t package

cpack <path to build folder>

-D Trilinos_ENABLE_Fortran=OFF \