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 -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. 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

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.

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.

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_star]
[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

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

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 8.0.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 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.

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 your .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.7+.

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.