Setup

Some brief notes on getting KEPLER and auxiliary files.

Getting an Account

We will need the IP address of the machine from which you connect to the server and a ssh public key secured by passphrase.

To make that ssh key, if you do not yet have one already, use

ssh-keygen -a 256 -t ed25519

which, however, may overwrite any existing id_ed25519 keys, though it will ask you whether you do want to overwrite it or not. So, no worries here if you are careful and read the screen output.

Note

If and only if you already have a ed25519 key and would like to create a new one for access to this git server, you could name it, e.g., id_git_star and use instead

ssh-keygen -a 256 -t ed25519 -f ~/.ssh/id_git_star

to create a new key named id_git_star. At the time of this writing, you may, however, yet be unlikely to already have a ed25519 key. In the section below you would the use

ssh-add id_git_star

instead of the line

ssh-add

I also ask you to use a secure passphrase to secure your key. If I can crack it, it will be rejected or deleted at a later time.

When you have a key, send it (the file ~/.ssh/id_ed25519.pub or ~/.ssh/id_git_star.pub) along with the IP address of the machine from which you will access the repository.

Note

A static IP address is needed and easiest. If you do not have a static IP address, we can still try with a dynamic host name as you would get from DynDNS or NoIp. But either fixed IP or host name are needed. Please do send these along.

If you have ssh access to a computer with a static IP address, you can use that as a proxy to connect to the server. Please provide the IP address of that server then.

Changed In Version 17.

Getting, setting up, and compiling KEPLER

Assuming you use the bash shell, you need to do something like

ssh-agent bash
ssh-add
[type passphrase]
mkdir python
cd python
git clone git@star.sci.monash.edu:python/source
cd
mkdir kepler
cd kepler
git clone git@star.sci.monash.edu:kepler/source
git clone git@star.sci.monash.edu:kepler/mongo
mkdir gfortran
cd gfortran
[copy the Makefile below into this directory, kepler/gfortran]
make links
make

Note

If you use a proxy to connect to the server you can use command line flags you may look up in the ssh documentation, or set up the git host in your ~/.ssh/config file, e.g.,

Host kepler
Hostname star.sci.monash.edu
User git
ForwardX11 no
ProxyJump <gateway>

where <gateway is the name of the gateway, e.g., user@myhost.com or another alias definition from the ~/.ssh/config file.

You may then use that alias, e.g., for cloning the python repo just use the command

git clone kepler:python/source

Note

The current build process requires GNU make Version 4.3 or above as well as Python 3.9 or above.

The Makefile is

SOURCE = ${HOME}/source
SYSTEM = gfortran
VERSION = O64
include $(SOURCE)/Makefile.make

Note

For installation on MacOS one may need to switch (checkout) a different branch of the mongo libraries. Available branches can be seen using gitg (on Linux, Mac tool may differ) after switching to the kepler/mongo directory, then select “All branches” from the drop-down box. You can also use the git branch -r command to get a list of branches, but it will not tell you the connection history. Omit the leading “origin/” from the branch name you provide in the last step below:

cd $(HOME)/kepler/mongo
git branch -r
git checkout <branch>

You may also need to adjust the SYSTEM and VERSION variable in the Makefile accordingly. Refer to the kepler/source/Makefile.$SYSTEM.$VERSION files. If you use gfortran you may be able to keep SYSTEM the same. For VERSION you may want to try the value OSX.

At the time of this writing, the current mongo version of for MacOS on M1 seem to require a setting in .bashrc

ulimit -n 256

or mannual on the command line before running multiple instances of KEPLER with graphical output.

Note

When you check out the mongo master branch for gcc, it will be for the most recent version the maintainer has checked in. As of the time of writing this sentence, this is version 10.2.1. There exist binary versions of the library for older versions, tagged in the git repo. For example, you can swith to the version for gcc 7.x using

cd $(HOME)/kepler/mongo
git checkout tags/gcc-7.x

You can see all available tags using

git tag

In case there is no suitable or current version available, you may try to compile your own. After checking out the current version, go to the source and do a make:

cd $(HOME)/kepler/mongo/source
./make

In an ideal world, this will make a new binary library mongo.linux in that directory, and the links to it in the parent directory continue working as before, nothing else to do. Good luck! Please let us know about updates.

Note

If your bash shell is not located in /usr/bin you should specify the correct full path in variable SHELL in the Makefile, e.g.,

SHELL = /bin/bash

Note

If you’d like to adjust the standard values of BURN isotopes, nburn and or the maximum zone number, jmz, you can specify those values using the variable names NBURN and JMZ, respectively. These can be specified statically in the Makefile , e.g.,

SOURCE = $(HOME)/kepler/source
SYSTEM = gfortran
VERSION = O64
NBURN = 500
JMZ = 32767
include $(SOURCE)/Makefile.make

or, alternatively, add the definitions to the make command line, e.g.,

make JMZ=1983 NBURN=4096

Whereas any changes in this file should propagate to all paces where these definitions are needed, it is not clear, however, whether this is the case consistently. It is therefore recommended, for the time of this writing, to perform a

make clean

before recompiling the code using make.

Warning

JMZ needs to be an odd number and NBURN needs to be an even number. NBURN should be at least 500.

To switch the plot routine used, use the PLOT variable. Current plot interfaces are

value	result
mongo	traditional X11 mongo interface (default)
nil	no plot for cases where no plot interface can be linked or is desired
py	Python interface for Python module

PLOT = nil

Depending on whether to compile for a standalone executable or for the Python interface, one can select the set of interface utility subroutines to include using the UTILS variable.

value	result
f	utilities for standalone Fortran executable (default)
py	utilities for Python interface

UTILS = f

Warning

Usually, this should not be change manually, leave at default.

For compilation on older system where the FORTRAN 2003 intrinsic ieee_arithmetic is not defined, we may chose an alternate version to use, with its corresponding compile flags

IEEEVALS = ieeevals_gcc4.f90
IEEEFLAGS := -fno-range-check

For development to disable x flag, we may chose an alternate version to use

PROGDBG = progdbg_devel.f90

To disable compilation for native architecture use in

ARCH = none

in Makefile.

For gfortran there is now also the option to overwrite the compilers and linker using the variable FOR90, CCOMP, and linker. You may set extra compiler flags using FLAGSX to all three parts (Fortran, C, linker) or use FFLAGSX for options use for Fortran and C, CFLAGSX for additional compiler options for C, and LFLAGSX for extra linker options.

To add a note to the program that is printed on startup, use the NOTE option.

NOTE = Hello World!

When KEPLER is compiled while not on a clean git commit, the source files are included in the KEPLER executable. These are also saved to each dump file. These include all the make files, Python scripts, .c and .f90 files. By default, the Makefile in the build directory is always included as well. The Makefile variable SAVESOURCE controls what source files are included

One can set compiler executable using C and FORTRAN to set the executable name and COMPDIR to set a common executable directory, if needed.

Note

compdir needs to include the trailing path separator /.

For example, to overwrite the use of gnu C compiler on Apple, you may use

C = gcc-14

value	result
0	never save any source
1	save all source if not on git always save Makefile (default)
-1	save all source if not on git do not save Makefile when on git

SAVESOURCE = -1

Changed In Version 17.2.1: Added JMZ and NBURN variables to Makefile.

Changed In Version 17.3.2: Added FULDAT variable to Makefile.

Changed In Version 18.2.3: Added variables IEEEVALS and IEEEFLAGS to Makefile.

Changed In Version 18.3: Added variables PROGDBG and ARCH to Makefile.

Changed In Version 18.7.11: Variable FULDAT replaced by variable FULDEF.

Changed In Version 18.7.16: Variable FULDAT deprecated. Use proper link to desired fuldat version instead.

Changed In Version 18.15.3: Added Makefile capability to overwrite default compile flags for gfortran.

Changed In Version 18.39: Added variables NOTE and SAVESOURCE to Makefile.

Changed In Version 18.39.5: Added variables C and FORTRAN to Makefile.

For successful compilation, you need to have installed the UUID libraries including the header file, uuid/uuid.h. In Fedora, this requires the package libuuid-devel, on Debian (and maybe Ubuntu), the package name is uuid-dev. On Fedora we also need to install the static gfortran libraries for compilation with gfortran, libgfortran-static. On Ubuntu, the X11 devel package may need to be installed, called xorg-dev.

To make compilation faster by compiling in parallel, you could use the -j option to make:

make -j

But this will not be good if you need to debug the compilation.

To set up the environment for KEPLER, add the following to your .bashrc file:

source ${HOME}/kepler/source/init.sh

To add the KEPLER Python directory to your path, add the following to your .bashrc file:

export PYTHONPATH=${HOME}/python/source:${HOME}/python/source/projects:${PYTHONPATH}

(drop the part after the “:” in case there was no python path defined)

To add the KEPLER Python scripts to your execution path, add the following to you .bashrc file:

export PATH=${HOME}/python/source/bin:${PATH}

Note

The python scripts now use Python 3.9+.

To see current branch when in git-controlled directories, add the following to your .bashrc file:

function parse_git_status {
  stat=$(git status -s 2> /dev/null) || return
  if  [ ${#stat} -ne 0 ]
  then
      echo "*"
  fi
}

function parse_git_branch {
  ref=$(git symbolic-ref HEAD 2> /dev/null) || return
  echo "["${ref#refs/heads/}$(parse_git_status)"] "
}

# prompt
if [ "${TERM}" == "xterm" ];
then
  export PS1="\[\e]1;\h\007\e]2;\u@\h\007\e[34;1m\]\$(parse_git_branch)\w>\[\e[0m\]"
else
  export PS1="\[\e[34;1m\]\$(parse_git_branch)\w>\[\e[0m\]"
fi

Editing KEPLER

Before starting your edits, make your one branch! Go to the kepler/source directory and type

git checkout -b <my_branch>

Whenever you are finished with some piece of changes do a git commit:

git commit -am "<my change>"

Also, set your user name and email address as git directs you. The important thing is to do atomic check-ins!

We can try to set up so your branch can also be hosted on the main server. Maybe to start, send me a patch of your changes, using code:git format-patch of similar. It would be a good idea to do a git rebase first to synchronize your changes with the current version on the server. You own branch(es) on the main server would make merging them with the main repository later possibly easier.

There is also an ep.py script that you can modify to add adjust to your needs. My version does a git pull at the beginning of the session and a git commit and git push at the end (you would not have access to push to the main repository, but if we set up a branch for you, that may work).

Make sure not to add any unneeded huge files to the repository. Maintain the .gitignore file accordingly.

To clean the current compile files, in the compile directory use

make clean

To also clean documentation use

make cleanall

You may also want to build code new from scratch (deleting all old files before compilation). Use

make -j new

To also build documentation (in parallel) use

make -j allnew

Updating your KEPLER version

Go to source directory and use

git pull

for the python source you would this accordingly in its source directory.

For the KEPLER source you may also use

make pull

in the compile directory.

Compiling and updating documentation

To be able to compile the documentation, add the following to your .bashrc file:

export PYTHONPATH=${HOME}/kepler/source/doc:${PYTHONPATH}

To compile the documentation, go to your build directory, e.g., ~/kepler/gfortran, and then run

make html

you can then find the documentation in ~/kepler/doc/html and can point your browser to ~/kepler/doc/html/index.html, e.g., file:///home/alex/kepler/doc/html/index.html

To copy the result to the web page, use

make web

You can clean the documentation using

make cleandoc

You can clean and build new using

make docnew

or clean, build fresh, and upload to web using

make webnew

By default, the documentation will be built in ~/kepler/doc, but you can set Makefile (or environment)

DOC=mydoc

to build in ~/kepler/mydoc instead, or even overwrite the base directory and specify full path

DOCDIR=my_absolute_doc_path

to build in directory my_absolute_doc_path.

You may need a bunch of Sphinx Python packages. As of the time of this writing, these compreise

Sphinx
sphinx-bootstrap-theme
sphinx-rtd-theme
sphinxcontrib-applehelp
sphinxcontrib-devhelp
sphinxcontrib-htmlhelp
sphinxcontrib-jquery
sphinxcontrib-jsmath
sphinxcontrib-lunrsearch
sphinxcontrib-qthelp
sphinxcontrib-serializinghtml
sphinxcontrib-websupport