docker provides you with a sort of virtual machine where everything needed ESTER is ready.

Under linux ubuntu: You may install docker with the guidelines: https://docs.docker.com/engine/install/ubuntu/

Download the image with:

sudo docker pull esterproject/2021:03

Then:

sudo docker run -it --user=1000:1000 --env="DISPLAY" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" esterproject/2021:03

you are logged on the virtual machine where ESTER can run. Just try:

mkdir runs
cd runs
ester 1d -M 3 -o M3.h5 # generate a 1D 3 solar mass ZAMS model
ester 2d -i M3.h5 -Omega_bk 0.3 -o M3O3.h5 # generate a 2D model rotating at 30% of the equatorial Keplerian angular velocity

You are ready to play with ESTER.

Installation on a Macintosh machine may be painful. If you are in a hurry then the use of 'docker' is recommended. So you first install the docker app (docker desktop); then download the image (see above), and then install or reinstall xquartz. Open xquartz goto preferences-> security check "Allow connections from network clients", then re-open a terminal

xhost +localhost
docker run -it -e DISPLAY=host.docker.internal:0 esterproject/2021:03
mkdir runs
cd runs
ester 1d -M 3 -o M3.h5 # generate a 1D 3 solar mass ZAMS model
ester 2d -i M3.h5 -Omega_bk 0.3 -o M3O3.h5 

Note that if you have problem with graphical display, try the -noplot option (ester 1d -noplot...).

ESTER uses BLAS, CBLAS and LAPACK libraries. The performance of the code highly depends and the performances of these libraries. Therefore you should be careful to use an optimized and parallel implementation. You will also need python in order to run ester. ESTER now uses cmake as a build system, you will need it to compile the code.

The most common implementations are:

• The original LAPACK implementation is on http://www.netlib.org/lapack/. It contains LAPACK and BLAS libraries, and CBLAS can be downloaded separately.

• ATLAS (Automatically Tuned Linear Algebra Software): An optimized (during installation) and parallel implementation of LAPACK, BLAS and CBLAS (be careful to use the --with-netlib-lapack-tarfile configure option to build the full implementation, otherwise some functions will be missing).

• Intel MKL: optimized and parallel version of LAPACK, BLAS and CBLAS.

• If you have root access to the machine where you want to install ESTER, you can install liblapack-dev and libblas-dev packages to install LAPACK, BLAS and CBLAS libraries.

• HDF5: used for standardized model input/output. It is also available [http://www.hdfgroup.org/downloads/ online], or in the libhdf5-dev package.

• SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. Using linux-ubuntu, SWIG is easily installed with ``sudo apt-get install swig''

• Boost a C++ library that can be obtained with sudo apt-get install libboost-all-dev

In order to install ester on your machine:

Clone the repository with:

$ git clone https://github.com/ester-project/ester.git

or

$ git clone [email protected]:ester-project/ester.git

This will create a directory named ester that contains the source code of ESTER. Go to this directory, and create a build directory:

$ cd ester
mkdir build

Ensure you are in the build directory and run:

cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/local

You pass several options to cmake in order to configure your build:

• -DCMAKE_CXX_COMPILER=icpc will tell cmake to use icpc as compiler for C++
• -DCMAKE_Fortran_COMPILER=ifort will configure cmake to use Intel compiler for Fortran
• -DCMAKE_INSTALL_PREFIX=$HOME/local will tell cmake to install ester into $HOME/local (by default, cmake will try to install to /usr/local

Here are two examples to configure ESTER to be installed in home directory using Intel compilers:

ester/build$ cmake .. -DCMAKE_INSTALL_PREFIX=$HOME -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
ester/build$ CC=/usr/bin/gcc-14 CXX=/usr/bin/g++-14 FC=gfortran-14 cmake .. -Wno-dev -DCMAKE_INSTALL_PREFIX=$HOME/ester/local -DPYTHON_NUMPY_INCLUDE_DIR=$HOME/miniforge3/envs/py312/lib/python3.12/site-packages/numpy/_core/include/

Once ESTER is correctly installed, you can run make and make install in order to install it on your system:

ester/build$ make -j
ester/build$ make install

You also need to tune your paths to have access to the appropriate python library. Note that in the latest Ubuntu version (20.04), python2.7 is deprecated, and only python3 (actually 3.8) runs completely. So, for instance, you may implement in your .cshrc (or any equivalent):

setenv ESTER $HOME/ester
setenv PYTHONPATH $HOME/local/lib/python3/dist-packages/:$HOME/local/lib/python3/dist-packages/ester/
setenv LD_LIBRARY_PATH $HOME/local/lib/

Note that specifying the environment variable ESTER is now crucial. It allows the code to know where the files of Solar_compositions are.

If you want to use monochromatic opacity tables, namely using the -opa mono option, you need to download the opacity data file:

wget https://zenodo.org/records/6858178/files/OP_mono_master_grid_MESA_emesh.txt.xz
xz -d OP_mono_master_grid_MESA_emesh.txt.xz
mv mono_master_grid_MESA_emesh.txt $HOME/ester/tables/op_mono
cd $HOME/ester/tables/op_mono
your_fortran_compiler convert_txt_to_binary_hybrid.F90 -o convert_mono
convert_mono

Note that the size of file OP_mono_master_grid_MESA_emesh.txt is 7.4Gb. To be useful this is processed to a binary file with the fortran script convert_txt_to_binary_hybrid.F90, which generates OP_mono_master_grid_MESA_emesh.bin . The use of this latter is much quicker than the original text file, which can now be removed.

If you installed ESTER from the github repository, getting the latest version of the code is as simple as running:

ester$ git pull

from any subdirectory of ester. And you can compile the new version directly with make install from the directory where you configured your installation. For instance from the BUILD directory:

ester$ cd build
ester/build $ make install

To check the functionality of the program we are going to calculate the structure of a star using the default parameter's values.

First create a directory where you want to save your models:

$ mkdir /tmp/ester-models
$ cd /tmp/ester-models

We can calculate the structure of a 1D non-rotating star:

/tmp/ester-models$ ester 1d

This will create a file called star.out that contains the model for this star:

/tmp/ester-models$ ls 
star.out

We can use this model as the starting point for the calculation of 2D rotating star:

/tmp/ester-models$ ester 2d -i star.out -Omega_bk 0.5

The -i option specify the input model, while -Omega_bk provides the rotation velocity as a fraction of the break-up velocity $\Omega_k = \sqrt{\frac{GM}{R_e^3}}$.

We give here as an example, the way we installed ESTER on a plain PC equipped with Ubuntu 14.04; it has also been tested with Ubuntu 16.04.

• First check that your computer has the gfortran, gcc, g++ compilers.
• under Ubuntu 14.04, you will easily install liblapack-dev and liblapack3 with the package manager. This also automatically install libblas-dev and libblas3 .
• We also recommend installing the pgplot5 package as it just needs an additional click! However, you need to check that libX11 is installed. Under Ubuntu 14.04, the package libx11-dev is needed.
• Next is the installation of cblas: this is not pre-compiled software of the distribution so you need to download it from the web, namely [http://www.netlib.org/blas/blast-forum/cblas.tgz cblas.tgz]. After unpacking the tarball and making the library, you should copy the file cblas.h to /usr/local/include and the file cblas_LINUX.a to /usr/local/lib/libcblas.a .
• If you wish to install HDF5 (recommended), look for the package 'libhdf5-dev' and install it. There are some other HDF5-related packages that may be downloaded, none are appropriate for ESTER installation.
• When all the foregoing softs are ready

$ cd your_ester_directory
ester$ mkdir local
ester$ mkdir BUILD
ester$ cd BUILD
ester/BUILD$ cmake .. -DCMAKE_INSTALL_PREFIX=/absolute_path/ester/local
ester/BUILD$ make
ester/BUILD$ make install
ester/BUILD$ cd ../local/bin
ester/BUILD$ ester-check-models

that's it!

• If you have intel compilers, ifort and icpc, then things should be simpler. Usually, mkl contains the full lapack, blas, cblas bundle. Just install pgplot5.

Installation on MacIntosh has raised many difficulties. Very recently (January 2025), we find an elegant solution based on the packaging software nix, which works for OS versions later than 11. Once, nix is installed then run the command:

nix-shell -p '(import (fetchGit { url="https://github.com/4D-STAR/ester"; ref="evolution_nix"; } ) {})'

and that's all.

For the sake of history and if it may help, here are the recommendations we use to give:

You can install Ester on Mac by following the same instructions as on a Linux machine. However you should set carefully the linker flags since Mac tends to install libraries in different location than Linux. As an example, here are the steps followed for the installation on a "naked" MacBook Pro. *First check that the compilers gfortran, gcc, g++ (for instance) are installed *Then you need the linear algebra libraries: [http://www.netlib.org/blas/#_cblas cblas.tgz], [http://www.netlib.org/lapack/lapack-3.5.0.tgz lapack-3.5.0.tgz], [http://www.netlib.org/blas/blas.tgz blas.tgz]. These sources need to be compiled. The compilation requires that you tune the make.inc file (lapack and blas) or the makefile.in (in cblas). In the compiler options, you should add the -m64 to insure 64-bit computations. Once these libraries are ready, move them to /usr/local/lib as libblas.a, libcblas.a and liblapack.a. Move also cblas.h to /usr/local/include

• At this stage the ESTER code can be compiled if no graphical output is needed during the runs. Just download the current version of [http://ester-project.github.io/ester/download/ester-1.1.0rc3.tar.gz ester.tgz] and let's go:

ester$ mkdir local
ester$ mkdir BUILD
ester$ cd BUILD
ester/BUILD$ ../configure --prefix=/absolute_path/ester/local LDFLAGS="-L/usr/local/gfortran/lib" CXXFLAGS="-I/usr/local/include/"
ester$ make
ester$ make install
ester$ cd ../local/bin
ester$ ./ester-check-models

At this stage the code should run!