ANSYS Lumerical

Overview

Lumerical (now part of Ansys) is commercial, licensed software.

Due to system incompatibilities (circa March 2026), Lumerical will not run natively on Sherlock. The recommended approach to run Lumerical on Sherlock then, is to create an Apptainer (formerly Singularity) container. In addition to the ANSYS software, VNC (or a similar graphical friently protocol) can be bundled into the container to faciliate a better GUI interface and visualization experience.

Prerequisites

• Active Lumerical/Ansys license: Lumerical is licensed software. It is always a good idea to check Stanford licensing and/or the Stanford Software store, to see if licenses are available, but you will likely need to provide your own license.
• License Server Access: For a floating network type license (FNL), access to a license server is required (know the server hostname and port number)
• Sherlock account
• Lumerical installer file

Step 1: Obtain the Lumerical Installer

Download the appropriate Lumerical installer for Linux from the Ansys/Lumerical download portal. Transfer this file to your Sherlock home or group directory, eg.

# Example transfer from local machine
scp Lumerical_installer.tar.gz <SUNetID>@login.sherlock.stanford.edu:home/groups/{pi_sunet}/

Step 2: Obtain or Create an Apptainer Definition File

Lumerical provides DockerFile container definitions, for the Docker container system. While Docker is a very popular system, arguably pioneered the concept of modern containerization, and is nominally the industry standard in enterprise circles, it is effectively not compatible with HPC – at least not for users and non-admins, because it requires root access to build and run containers. Most HPC systems today use Apptainer or Podman – either of which will work on Sherlock, but Apptainer is the perfered and better supported option of the two.

Three basic approaches to building an Apptainer container for your ANSYS software include,

1. Build a Docker container on a different system, from one of the provided DockerFiles, then build (or “compose”) an Apptainer container using the Docker container as a base.
2. Create an Apptainer definition file, eg. lumerical.def from scratch, by following the regular Lumerical installation instructions
3. Convert a DockerFile to an Apptainer definition file.

The third option is really a variation on the second, principally in the sense that there is not currently a “proper” way to dependably convert a DockerFile to an Apptainer.def. That said, the syntax is not terribly difficlut to follow and modern LLM (“AI”) tools, eg CLAUDE, Gemini, ChatGPT, will do most of the heavy lifting if asked.

A Lumerical container will inevitably require numerous dependency libraries to be installed, so we recommend a combination of 2 and 3. A sample, and likely working, container file (e.g., lumerical.def) for building the container:

Bootstrap: docker
From: ubuntu:latest
#From: ubuntu:22.04

# build like:
# apptainer build --build-arg license_server=port@server lumerical.sif lumerical.def 
# apptainer build --force --build-arg license_server=1055@sedna.stanford.edu lumerical.sif lumerical-Apptainer-ubuntu-openmpi.def

%setup
    mkdir ${APPTAINER_ROOTFS}/LUMERICAL

%arguments
    license_server=

%files
    #rpm_install_files/Lumerical*.rpm /LUMERICAL
    Lumerical-2025-R2.4-4336-b98875243d9 /LUMERICAL/

%post
    # Copyright (c) 2003-2025, Ansys, Inc. All rights reserved.
    #
    # Unauthorized use, distribution, or duplication is prohibited.
    # This product is subject to U.S. laws governing export and re-export.
    #
    # For full Legal Notice, see license.txt
    #
    ##########################
    # General container parts:
    ###########################
    # Define options here (maybe tie with %environment)
    INSTALL_VNC=1
    #
    # Get latest
    apt-get update
    apt-get upgrade -y
    
    export DEBIAN_FRONTEND=noninteractive 
    export TZ=America/Pacific

    apt-get install -y vim nano
    apt-get install -y build-essential
# NOTE: Lumerical uses QT, but it packages its own version, so we do *not* want to install it here.
#    apt-get install -y qtcreator qtbase5-dev qt5-qmake cmake
#    apt-get install -y libqt5gui5

    
    # Install extra packages. Some of these are probably ANSYS/Lumerical specific, so our division of container
    #  parts is not very complete.
    #########
    # if we use their extract-rpm.sh, do we need alien? We do. Or at least some parts. Intall alien, then remove it during cleanup.
    apt-get install -y alien
    #apt-get install -y rpm2cpio cpip  # eventually, we will figure out which alien libraries we actually need...
    #
    apt-get install -y freeglut3-dev libxslt-dev libxcursor1 wget sudo
    #apt-get install -y --allow-downgrades cpio=2.13+dfsg-7
    #
    # from lito (we will trim the redundant package)
    apt-get -y install libxcb-xinerama0 libxcb-cursor0 libxcursor-dev
    apt-get -y install libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev libxcb-shape0-dev libxcb-xkb-dev

    #apt-get -y install libxcb-xinerama0 libxcb-cursor0 libxcursor-dev
    #apt-get -y  install freeglut3-dev
    #
    # then, hold to see if we really need to do this (we do...):
    #cd /usr/lib/x86_64-linux-gnu
    ln -s /usr/lib/x86_64-linux-gnu/libglut.so.3.12.0 /usr/lib/x86_64-linux-gnu/libglut.so.3 

    
    # Add lumerical user
    useradd --shell /bin/bash --create-home lumerical

    # Installation of Open MPI
    apt-get install -y openmpi-bin

    # Installation of Lumerical RPM
    # cd /tmp
    # yoder: move this to a more specialized location.
    #cd /LUMERICAL
    cd /LUMERICAL/Lumerical-2025-R2.4-4336-b98875243d9
    #
    # yoder: instead of alien, use their extract-rpm.sh method/script. Both should work.
    # But we still need to install alien -- or at least parts of that package?
    export LUMERICAL_DIR=/opt/lumerical/v252
    printf "LUMERICAL_DIR: ${LUMERICAL_DIR}\n"
    echo "export LUMERICAL_DIR=${LUMERICAL_DIR}" >> /envfile
    ./extract-rpm.sh
    mv opt/* /opt/
    
    #export LUMERICAL_DIR=$(eval rpm -qlp ./Lumerical*.rpm | grep VERSION$ | cut -f1-4 -d"/")
    #echo "export LUMERICAL_DIR=${LUMERICAL_DIR}" >> /envfile
    #
    #alien -i Lumerical*.rpm --scripts
    # yoder: for now, keep this...
    # looks like extract-rpm.sh cleans up (deletes the .rpm files)
    #rm -rf Lumerical*.rpm
    
    # Update PATH
    echo "export PATH=${LUMERICAL_DIR}/bin:${LUMERICAL_DIR}/python/bin:\$PATH" >> /home/lumerical/.bashrc
    
    # Set OpenMPI as default resource on startup scripts
    mkdir -p ${LUMERICAL_DIR}/Lumerical
    echo "setresource('FDTD',1,'job launching preset','Remote: OpenMPI');" >> ${LUMERICAL_DIR}/Lumerical/global_fd_ide_startup_script.lsf
    echo "setresource('EME',1,'job launching preset','Remote: OpenMPI');" >> ${LUMERICAL_DIR}/Lumerical/global_mfd_ide_startup_script.lsf
    echo "setresource('varFDTD',1,'job launching preset','Remote: OpenMPI');" >> ${LUMERICAL_DIR}/Lumerical/global_mfd_ide_startup_script.lsf
    #
######
#    # Add VNC to container:
    if [ ${INSTALL_VNC} -eq 1 ]; then
      apt-get install -y --no-install-recommends \
          xfce4 \
          xfce4-goodies \
          dbus-x11 \
          xterm
      apt-get install -y libcurl4-openssl-dev --fix-broken
      #
      # Set xfce4-terminal as default terminal emulator:
      update-alternatives --set x-terminal-emulator /usr/bin/xfce4-terminal.wrapper
      #
      # TurboVNC:
      apt-get -y install wget gpg
      apt-get -y install lsb-release
      #
      #
      #echo "deb bit done..."
      wget -q -O- "https://packagecloud.io/dcommander/turbovnc/gpgkey" | gpg --dearmor > "/etc/apt/trusted.gpg.d/TurboVNC.gpg"
      wget -q -O "/etc/apt/sources.list.d/TurboVNC.list" "https://raw.githubusercontent.com/TurboVNC/repo/main/TurboVNC.list"
      #
      wget -q -O- https://packagecloud.io/dcommander/libjpeg-turbo/gpgkey | gpg --dearmor >/etc/apt/trusted.gpg.d/libjpeg-turbo.gpg
      wget -q -O "/etc/apt/sources.list.d/libjpeg-turbo.list" "https://raw.githubusercontent.com/libjpeg-turbo/repo/main/libjpeg-turbo.list"
      #
      wget -q -O- https://packagecloud.io/dcommander/virtualgl/gpgkey | gpg --dearmor >/etc/apt/trusted.gpg.d/VirtualGL.gpg
      wget -q -O "/etc/apt/sources.list.d/VirtualGL.list" "https://raw.githubusercontent.com/VirtualGL/repo/main/VirtualGL.list"
      #
      apt-get update
      apt-get -y install turbovnc
      apt-get -y install virtualgl libjpeg-turbo-official
      #
      # Set VNC password (replace 'your_vnc_password' with a strong password)
      export PATH=/opt/TurboVNC/bin:${PATH}
      #######

      # There are ways to configure startup scripts, manage the desktop from the container, etc.,
      #  but I do not use them.
      #mkdir -p /root/.vnc
      #echo "monkey018" | vncpasswd -f > /root/.vnc/passwd
      #chmod 600 /root/.vnc/passwd

      ## Configure xstartup script for XFCE
      #echo "#!/bin/bash" > /root/.vnc/xstartup
      #echo "unset SESSION_MANAGER" >> /root/.vnc/xstartup
      #echo "unset DBUS_SESSION_BUS_ADDRESS" >> /root/.vnc/xstartup
      #echo "[ -x /etc/vnc/xstx:artup ] && exec /etc/vnc/xstartup" >> /root/.vnc/xstartup
      #echo "[ -r \$HOME/.Xresources ] && xrdb \$HOME/.Xresources" >> /root/.vnc/xstartup
      #echo "startxfce4 &" >> /root/.vnc/xstartup
      #chmod +x /root/.vnc/xstartup
  
      ## END VNC
    fi
   

    # Cleanup
    apt-get -y remove alien
    apt-get clean
    rm -rf /var/lib/apt/lists/*

%environment
    # Set offscreen for running in headless mode
    export QT_QPA_PLATFORM=offscreen
    
    # Set the licensing variable
    export ANSYSLMD_LICENSE_FILE=
    #
    # this is not a smart way to set the Lumerical PATH, but it is what we are going to do for now...
    export PATH=/opt/lumerical/v252/bin:${PATH}
    export LD_LIBRARY_PATH=/opt/lumerical/v252/lib:${LD_LIBRARY_PATH}
    export LIBRARY_PATH=/opt/lumerical/v252/lib:${LIBRARY_PATH}
    #
    # VNC:
    export PATH=/opt/TurboVNC/bin:${PATH}

    # Source the environment file if it exists
    if [ -f /envfile ]; then
        . /envfile
    fi

%runscript
    # Source bashrc for lumerical user
    if [ -f /home/lumerical/.bashrc ]; then
        . /home/lumerical/.bashrc
    fi
    exec "$@"

%labels
    Author Ansys, Inc.
    Version 1.0

%help
    This container includes Lumerical software from Ansys.
    
    To build this container:
        apptainer build lumerical.sif lumerical.def --build-arg license_server=<your_license_server>
    
    To run:
        apptainer run lumerical.sif <command>

Step 3: Build the Container

Build the container on Sherlock, eg.

Copy code

# Build the container
apptainer build lumerical.sif lumerical.def

Step 4: Configure License Settings

See ANSYS documentaiton on how to set up a license. Typically, the license file will be configured in your $HOME directory, then your container will be directed to look for and/or validate that license via environment variables. Specifically, Lumerical uses the ANSYSLMD_LICENSE_FILE variable to define various licensing elements.

Under most circumstances, you can automatically pass environmetn variables from the host to a container, so the license server can be defined by setting the local (on your host machine) variable ANSYSLMD_LICENSE_FILE to point to the license server:

Copy code
# Option 1: Environment variable
export ANSYSLMD_LICENSE_FILE=<port>@<license_server_hostname>

Lumerical however, may conflict with some of Sherlock’s standard environment variable settings, and so it may be necessary to either build the container with that Licensing variable defined, (TODO: make this correct)

# Build the container so that ANSYSLMD_LICENSE_FILE is set in the container
apptainer build --build-env lumerical_lic= lumerical.sif lumerical.def

or the ANSYSLMD_LICENSE_FILE can be set at runtime – see below.

Option 2: Create a license file

echo “SERVER ANY " > /home/groups//lumerical/license.lic echo "USE_SERVER" >> /home/groups//lumerical/license.lic Step 5: Test the Container Run a simple test to verify the installation:

bash Copy code

Interactive test

apptainer shell lumerical.sif Apptainer> fdtd-solutions –version Apptainer> exit

Set license and test

export ANSYSLMD_LICENSE_FILE=@ apptainer exec lumerical.sif fdtd-solutions --test-license