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¶
We provide two scripted options to quickly install Ascent and its dependencies.
uberenv.py¶
You can use uberenv, a python script that leverages spack to build Ascent and its dependencies:
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.
build_ascent.sh¶
You can use build_ascent.sh, a stand alone shell script to build Ascent and its dependencies:
# prerequisite: `cmake` must be in your path
git clone --recursive https://github.com/alpine-dav/ascent.git
cd ascent
env prefix=build ./scripts/build_ascent/build_ascent.sh
After this completes, build/install/ascent-develop will contain an Ascent install.
build_ascent.sh serves both to help with automatically building Ascent as well as documenting the steps necessary to configure and build Ascent and its dependencies using CMake:
We also provide also wrapper scripts for specific HPC platforms (e.g. build_ascent_hip_frontier.sh for ORNL’s Frontier, etc) script that you can leverage. Here is the Frontier HIP build script:
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