Setup

User setup

Obtaining multistar

To install on Unix-like systems (Linux, MacOS)

ssh-keygen -a 256 -t ed25519

send ~/.ssh/id_ed25519.pub to get git repository access.

ssh-agent $SHELL
ssh-add
[type passphrase]
cd
mkdir python
cd python
git clone git@star.sci.monash.edu:python/source

In .bashrc or .zshrc., add ${HOME}/python/source and ${HOME}/python/source/projects to PYTHONPATH and ${HOME}/python/source/bin to PATH environment variables.

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

Required Python modules

apng

numpy

numpy-quaternion

scipy

Cython

meson

ninja

libconf

matplotlib

psutil

pillow

tqdm

py-cpuinfo

PyYAML

tqdm

cairosvg

pip install -U ipython apng numpy numpy-quaternion scipy Cython meson ninja libconf matplotlib psutil pillow py-cpuinfo PyYAML tqdm cairosvg

Recommended Python modules

ipython

vtk

plotly

kepler (not public)

pip install -U ipython vtk plotly

Note

vtk tends to be a bit behind, wheels for pip are only made when a new version is released after a well-established Python release. Very annoying.

System packages

LaTeX

ffmpeg

Compiler and build options

You can use the native.ini file in the fortran sub-directory to set default build options for the package.

[built-in options]
buildtype = 'debugoptimized'

[binaries]
fortran = 'flang'

The compilation of the Fortran code is in the _build sub-directory; you can query current settings and available option; you probably have to consult the meson documentation (ask AI) what section in the native.ini file each has to go.

cd ~/python/source/multistar
meson configure _build

Note

The native.ini file is listed in .gitignore in the fortran directory and hence not saved with git. This is intentional. Example native.ini files may be provided after this note was written.

Warning

Some settings or settings changes, such as build type or compiler, in native.ini _may_ require to re-configure the _build directory; in this case, it is easiest to _explicitly_ “clean” the build directory and start over (won’t take too long).

from mulitstar import clean
clean()

Documentation

Required Python packages

sphinx

sphinx_rtd_theme

sphinx-design

pip install -U sphinx sphinx_rtd_theme sphinx-design

Building documentation

Building by hand

To compile the documentation, go to subdirectory multistar/doc and set up meson:

meson setup _build
meson compile -C _build

You can point your web browser to the local folder under multistar/doc/_build/html/index.html

Installing documentation

To put files on the server (c), I use

meson compile -C _build  web

Configuring build

You can custom-configure web install location by creating a native.init file. Possible meson options are listed in meson_options.txt as usual. A template with my defaults is in native.ini.default

[project options]
HOST = 'o'
DIR =  '/n/web/multistar/doc'
MOUNT = '/n'

Build using Python interface

There is a documentation build Python class that can be called directly from multistar:

import multistar
multistar.doc.build()

class multistar.doc.meson_build.BuildDoc(web=None, clean=False, dir=None, host=None, mount=None, native='native.ini')

Bases: object

Build documentation and sync to web

Parameters:

web (bool) – whether to rsync to web server
clean (bool) – set up from scratch
dir (str) – directory on server
host (str) – host name used by ssh
mount (str) – directory to mount, if applicable
native (str) – native file name to use. default is native.ini in doc directory. Any file path has to be relative to doc directory.

Build executable

You can call the build class as a stand-alone executable Python script in the doc sub-directory, meson_build.py.

mesons_build.py web=True

Valid options are those of Class BuildDoc above.