Quick Start

Running Ascent via Docker

The easiest way to try out Ascent is via our Docker container. If you have Docker installed you can obtain a Docker image with a ready-to-use ascent install from Docker Hub. This image also includes a Jupyter install to support running Ascent’s tutorial notebooks.

To start the Jupyter server and run the tutorial notebooks, run:

docker run -p 8888:8888 -t -i alpinedav/ascent-jupyter

(The -p is used to forward ports between the container and your host machine, we use these ports to allow web servers on the container to serve data to the host.)

This container automatically launches a Jupyter Notebook server on port 8888. Assuming you forwarded port 8888 from the Docker container to your host machine, you should be able to connect to the notebook server using http://localhost:8888. The password for the notebook server is: learn

Installing Ascent and Third Party Dependencies

The quickest path to install Ascent and its dependencies is via uberenv:

git clone --recursive https://github.com/alpine-dav/ascent.git
cd ascent
python scripts/uberenv/uberenv.py --install --prefix="build"

After this completes, build/ascent-install will contain an Ascent install.

We also provide spack settings for several well known HPC clusters, here is an example of how to use our settings for OLCF’s Summit System:

python scripts/uberenv/uberenv.py --install --prefix="build" --spack-config-dir="scripts/uberenv_configs/spack_configs/configs/olcf/summit_gcc_9.3.0_cuda_11.0.3/"

For more details about building and installing Ascent see Building Ascent. This page provides detailed info about Ascent’s CMake options, uberenv and Spack support. We also provide info about building for known HPC clusters using uberenv and a Docker example that leverages Spack.

Public Installs of Ascent

We also provide public installs of Ascent for the default compilers at a few DOE HPC centers.

Summary table of public ascent installs:

Site	System	Compiler	Runtime	Modules	Install Path
OLCF	Summit	gcc 9.3.0	CUDA 11.0.3	gcc/9.3.0 cuda/11.0.3	/sw/summit/ums/ums010/ascent/current/summit/cuda/gnu/ascent-install/
OLCF	Summit	gcc 9.3.0	OpenMP	gcc/9.3.0	/sw/summit/ums/ums010/ascent/current/summit/openmp/gnu/ascent-install/
NERSC	Permutter	gcc 9.3.0	CUDA 11.4.0	PrgEnv-gnu cpe-cuda/21.12 cudatoolkit/21.9_11.4	/global/cfs/cdirs/alpine/software/ascent/current/perlmutter/cuda/gnu/ascent-install/
LLNL LC	CZ TOSS 3 (Pascal)	gcc 4.9.3	OpenMP	(none)	/usr/gapps/conduit/software/ascent/current/toss_3_x86_64_ib/openmp/gnu/ascent-install

Here is a link to the scripts we use to build public Ascent installs.

See Using Public Installs of Ascent for more details on using these installs.

Using Ascent in Your Project

The install includes examples that demonstrate how to use Ascent in a CMake-based build system and via a Makefile.

CMake-based build system example (see: examples/ascent/using-with-cmake):

###############################################################################
#
# Example that shows how to use an installed instance of Ascent in another
# CMake-based build system.
#
# To build:
#  mkdir build
#  cd build
#  cmake -DAscent_DIR={ascent install path} ../
#  make
#  ./ascent_render_example
#
# In order to run directly in a sub directory below using-with-cmake in an ascent install, 
# set Ascent_DIR to ../../..
# 
#  mkdir build
#  cd build
#  cmake .. -DAscent_DIR=../../..
#  make
#  ./ascent_render_example
#
###############################################################################

cmake_minimum_required(VERSION 3.9)

project(using_with_cmake)

#
# Use CMake's find_package to import ascent's targets
#
# PATHS is just a hint if someone runs this example from the Ascent install
# tree without setting up an environment hint to find Ascent
find_package(Ascent REQUIRED
             NO_DEFAULT_PATH
             PATHS ${CMAKE_SOURCE_DIR}/../../../)

# create our example
add_executable(ascent_render_example ascent_render_example.cpp)

# link to ascent
target_link_libraries(ascent_render_example ascent::ascent)

# if cuda is in the mix:
# we need to make sure CUDA_RESOLVE_DEVICE_SYMBOLS is on for our target
# (it propgates some way magically in 3.14, but not in 3.21)
if(CMAKE_CUDA_COMPILER)
    set_property(TARGET ascent_render_example PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
endif()

CMake-based build system example with MPI (see: examples/ascent/using-with-cmake-mpi):

# Example that shows how to use an installed instance of Ascent in another
# CMake-based build system.
#
# To build:
#  cmake -DAscent_DIR={ascent install path}  -B build -S .
#  cd build
#  make
#  mpiexec -n 2 ./ascent_mpi_render_example
#
# In order to run directly in a sub directory below using-with-cmake-mpi in an ascent install,
# set Ascent_DIR to ../../..
# 
#  cmake -DAscent_DIR={ascent install path}  -B build -S .
#  cd build
#  make
#  mpiexec -n 2 ./ascent_mpi_render_example
#
###############################################################################

cmake_minimum_required(VERSION 3.9)

project(using_with_cmake)


#
# Make sure we have CMake's MPI targets.
#
find_package(MPI REQUIRED COMPONENTS CXX)


#
# Use CMake's find_package to import ascent's targets
#
# PATHS is just a hint if someone runs this example from the Ascent install
# tree without setting up an environment hint to find Ascent
find_package(Ascent REQUIRED
             NO_DEFAULT_PATH
             PATHS ${CMAKE_SOURCE_DIR}/../../../)


# create our example
add_executable(ascent_mpi_render_example ascent_mpi_render_example.cpp)

# link to ascent
target_link_libraries(ascent_mpi_render_example ascent::ascent_mpi)

# if cuda is in the mix:
# we need to make sure CUDA_RESOLVE_DEVICE_SYMBOLS is on for our target
# (it propgates some way magically in 3.14, but not in 3.21)
if(CMAKE_CUDA_COMPILER)
  set_property(TARGET ascent_mpi_render_example PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
endif()

Makefile-based build system example (see: examples/ascent/using-with-make):

###############################################################################
#
# Example that shows how to use an installed instance of Ascent in Makefile
# based build system.
#
# To build:
#  env ASCENT_DIR={ascent install path} make
#  ./ascent_render_example
#
# From within an ascent install:
#  make 
#  ./ascent_render_example
#
# Which corresponds to:
#
#  make ASCENT_DIR=../../../
#  ./ascent_render_example
#
###############################################################################

ASCENT_DIR ?= ../../..

# See $(ASCENT_DIR)/share/ascent/ascent_config.mk for detailed linking info 
include $(ASCENT_DIR)/share/ascent/ascent_config.mk

# make sure to enable c++11 support (conduit's interface now requires it)
CXX_FLAGS = -std=c++11
INC_FLAGS = $(ASCENT_INCLUDE_FLAGS)
LNK_FLAGS = $(ASCENT_LINK_RPATH) $(ASCENT_LIB_FLAGS)

main:
	$(CXX) $(CXX_FLAGS) $(INC_FLAGS) ascent_render_example.cpp $(LNK_FLAGS) -o ascent_render_example


clean:
	rm -f ascent_render_example

Makefile-based build system example with MPI (see: examples/ascent/using-with-make-mpi):

###############################################################################
#
# Example that shows how to use an installed instance of Ascent in Makefile
# based build system.
#
# To build:
#  env ASCENT_DIR={ascent install path} make
#  ./ascent_render_example
#
# From within an ascent install:
#  make 
#  mpiexec -n 2 ./ascent_mpi_render_example
#
# Which corresponds to:
#
#  make ASCENT_DIR=../../../ 
#  mpiexec -n 2 ./ascent_mpi_render_example
#
###############################################################################

ASCENT_DIR ?= ../../..

# See $(ASCENT_DIR)/share/ascent/ascent_config.mk for detailed linking info 
include $(ASCENT_DIR)/share/ascent/ascent_config.mk

# make sure to enable c++11 support (conduit's interface now requires it)
CXX_FLAGS = -std=c++11
INC_FLAGS = $(ASCENT_INCLUDE_FLAGS)
LNK_FLAGS = $(ASCENT_LINK_RPATH) $(ASCENT_MPI_LIB_FLAGS)

main:
	$(CXX) $(CXX_FLAGS) $(INC_FLAGS) ascent_mpi_render_example.cpp $(LNK_FLAGS) -o ascent_mpi_render_example


clean:
	rm -f ascent_mpi_render_example