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 key, if you do not yet have one, use

ssh-keygen -b 4096 -t rsa

which, however, will overwrite any existing id_rsa keys. If you want to be on the safe side, use

ssh-keygen -b 4096 -t rsa -f ~/.ssh/id_git

to create a new key named id_git.

When you have a key, send it (the file ~/.ssh/id_rsa.pub or ~/.ssh/id_git.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.

Getting, setting up, and compiling KEPLER

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

ssh-agent bash
ssh-add id_git
[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

The Makefile is

SOURCE = $(HOME)/kepler/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.

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.

It is also possible to specify the version of fuldat.f to be used in the Makefile. The default is equivalent to

FULDAT = fuldat1.f

New In Version 17.2.1.

Changed In Version 17.3.2: Added FULDAT variable 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.

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 you .bashrc file:

export PYTHONPATH=${HOME}/python/source:${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.6.

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 checkins!

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 :code”git checkin 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.

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 ~/kepler/soucre/doc and then run

make html

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

To copy the result to the web page, use

make web

Note

Likely works for Alex only.

Installing the Python Module

This has only been tested for Fedora Linux 22+ so far. First, you need to get a current version of Python, most easy to install locally. As of the time of this writing, this is Version 3.6.0. Earlier versions may have bugs and not work.

# using bash
export py=3.6.0
wget https://www.python.org/ftp/python/${py}/Python-${py}.tar.xz
cd
tar -xvJf Python-${py}.tar.xz
cd Python-${py}
./configure --prefix=$HOME/Python
make -j
make test
make install

Note

the make -j command may giv you some message of components in python it did not build because of missing dependencies. You should try to find them all to build a complete python install, otherwise some key components may not be build. Specifically, pip3 has happened to be missing in some of the installations I attempted.

Then, I change my ~/.bashrc to file to include

# PYTHON 3.6
export PYTHON=${HOME}/Python
export PATH=$PYTHON/bin:$PATH
export MANPATH=$PYTHON/man:$MANPATH
export PYTHONPATH=${PYTHONPATH}:${PYTHON}

and open a new bash shell. Now, you want to install a phledora of python packages,

pip3 install -U  --force-reinstall numpy scipy ipython[notebook] psutil pyyaml six matplotlib

You will need to install numpy 1.11 or higher (1.11b2 as of this writing), which you may have to check out from github and compile/install your self. (I contriuted bug fix to f2py to make KEPLER work.)

By default, it appears current numpy does not create a link for f2py3 by defaul, so we need to make this by hand:

cd
cd Python/bin
ln -s f2py3.6 f2py3

Next, you need to get the Makefile specifically for the KEPLER library to be linked

cd
cd kepler
git clone git@star.sci.monash.edu:kepler/python

if you now load the kepler module, in an ideal world, this should compile the necessary binary libraries all from scratch.

Note

Please let me know of any problems, their solutions, and possible updates for this documentation

A useful scrtip that I run every now and then to update python is

#!/usr/bin/bash
pip3 install --upgrade pip
pip3 freeze --local | grep -v '^\-e' | cut -d = -f 1  | xargs -n1 pip3 install -U

You should coupy this into a file, e.g., update_python and make executable.