Artenv

artenv は Artemis の version と解析環境を管理するためのツールです. pyenv や rbenv のように, コマンド一つで Artemis 環境と解析ディレクトリを切り替えられます.

v2 では native installation に加えて Apptainer container image も Artemis version として扱えるようになりました. Apptainer image を使うと, ROOT, yaml-cpp, Artemis を利用先の計算機ごとに用意する手間を減らせます. 解析環境をほかの計算機や共同研究者とそろえやすくなる点も利点です.

Concepts

artenv では, Artemis の実行環境と解析ディレクトリを分けて管理します.

• version: Artemis の実行環境. native installation または Apptainer image.
• environment: 実験・解析ごとの作業環境. 使用する version, working directory, git repository, artlogin の設定などを持つ.
• template: 新しい解析ディレクトリを作るためのひな形. 外部 git repository から取得して使う.

まず artenv version install や artenv version register で Artemis version を登録し, 次に artenv register で解析 environment を登録します. 登録後は次のように切り替えられます.

artenv shell h424
artenv default h424

artenv shell <env> は現在の shell だけを切り替えます. artenv default <env> は新しく開く shell で使うデフォルト environment を設定します.

Requirements

• bash
• GNU coreutils (readlink -f, realpath)
• git
• mikefarah/yq v4 以降 (TOML の読み込みに使用. artenv bootstrap で導入可能)
• curl または wget (yq の取得や version の install に使用)
• Apptainer version を使う場合は apptainer

shell integration は bash と zsh で使えます.

Installation

git clone で artenv 本体を配置します.

git clone https://github.com/yano404/artenv.git ~/.artenv

.bashrc や .zshrc に次を追加します.

export ARTENV_ROOT="$HOME/.artenv"
export PATH="$ARTENV_ROOT/bin:$PATH"
eval "$(artenv init -)"

shell を再起動します.

exec $SHELL

yq の導入

設定ファイルの読み込みに使う yq は, 次のコマンドで管理者権限なしで導入できます.

artenv bootstrap

省略した場合は, 既存の mikefarah/yq v4 以降を使い, 見つからなければ必要時に自動取得します.

Shell Completion

artenv は bash と zsh の補完を提供しています.

bash の場合は .bashrc などで補完スクリプトを読み込みます.

source "${ARTENV_ROOT}/completions/artenv.bash"

zsh の場合は fpath に補完ディレクトリを追加し, compinit を初期化します.

fpath=("${ARTENV_ROOT}/completions" $fpath)
autoload -Uz compinit
compinit

Quick Start

1. Artemis version を用意する

Apptainer を使える環境では, container image を pull して version として登録するのが簡単です.

artenv version install latest

tag を指定すると, URI, version name, SIF 保存先の入力は省略されます. この例では artemis_apptainer-latest という version が登録され, image は $ARTENV_ROOT/images/artemis_apptainer-latest.sif に保存されます.

利用可能な tag は次で確認できます.

artenv version install --list

対話的に Apptainer image を登録することもできます.

$ artenv version install --apptainer
Enter the pull URI [oras://ghcr.io/yano404/artemis_apptainer:latest]>
Enter the version name> artemis-latest
Enter the path to save SIF [/home/yano/.artenv/images/artemis-latest.sif]>
Configuration:
  URI                    oras://ghcr.io/yano404/artemis_apptainer:latest
  VERSION                artemis-latest
  SIF                    /home/yano/.artenv/images/artemis-latest.sif
OK? (y/N)> y

すでに .sif image を持っている場合は, それを version として登録できます.

$ artenv version register artemis-apptainer
Select version type
1) native
2) apptainer
#? 2
Enter the path to Apptainer image (.sif)> /path/to/artemis.sif
artemis-apptainer was registered

native installation を使う場合は, Artemis, ROOT, yaml-cpp の path を登録します.

$ artenv version register artemis-native
Select version type
1) native
2) apptainer
#? 1
Enter the path to artemis> /path/to/artemis
Enter the path to root> /path/to/root
Enter the path to yaml-cpp> /path/to/yaml-cpp
artemis-native was registered

source から Artemis を build して登録したい場合は --native を使います.

$ artenv version install --native
Enter the path to root> /home/yano/local/root/v6.32.04
Enter the path to yaml-cpp> /home/yano/local/yaml-cpp/v0.8.0
Enter the path to the source of artemis> /home/yano/src/artemis/develop
Enter the path to build directory> /home/yano/build/artemis/artdev
Enter the install prefix> /home/yano/local/artemis/artdev
Configuration:
  ROOTSYS                /home/yano/local/root/v6.32.04
  YAML_CPP_LIB           /home/yano/local/yaml-cpp/v0.8.0/lib
  YAML_CPP_CMAKE         /home/yano/local/yaml-cpp/v0.8.0/lib/cmake
  ARTEMIS_SOURCE         /home/yano/src/artemis/develop
  BUILD_DIR              /home/yano/build/artemis/artdev
  INSTALL_PREFIX         /home/yano/local/artemis/artdev
OK? (y/N)> y
Will you register this version to artenv? (y/N)> y
Enter the version name> artemis-native
artemis-native was registered

2. 解析ディレクトリを登録する・作成する

version を用意したら, 解析ディレクトリを artenv で扱えるようにします. 既存の解析ディレクトリを使う場合は artenv register で登録します. 新しく解析ディレクトリを作る場合は, artenv new で template から working directory を作ってから登録します.

既存の解析ディレクトリを登録する

すでに解析ディレクトリがある場合は, それを environment として登録します.

$ artenv register h424
Select the artemis version
1) artemis-native
2) artemis_apptainer-latest
#? 2
artemis_apptainer-latest was selected
Enter the path to working directory> /path/to/analysis_directory
Use artlogin? (y/n)> n
Enter the path to git repos (optional)> /path/to/git_repos or URL of git repos
h424 was registered

artlogin を使う場合は git repository の指定が必須です.

Use artlogin? (y/n)> y
Enter the path to git repos (required)> /path/to/git_repos or URL of git repos

登録した environment は次で有効化できます.

artenv shell h424

batch job や HPC のセットアップスクリプトでは, 対話せずに登録することもできます.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/analysis_directory \
  --singleuser

複数人で共有する artlogin environment の場合は --multiuser と --repos を使います.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/shared_directory \
  --repos /path/to/upstream.git \
  --multiuser

Template から解析ディレクトリを作る

新しい解析ディレクトリを作る場合は artenv new を使います. artenv new は template をもとに基本的なディレクトリ構造を作るためのコマンドです. 作成されるのは解析のひな形なので, detector 構成, steering file, parameter file などを実験に合わせて編集する必要があります.

artenv new で解析ディレクトリを作る場合は, 最初に template repository を取得します.

artenv templates update

標準では artemis-templates が default repository として使われます. 取得済みの template は次で確認できます.

artenv templates ls

template を指定して working directory を作ります.

artenv new /path/to/work -t default/standard

template 名が一意に決まる場合は repository 名を省略できます.

artenv new /path/to/work -t standard

-t を省略して対話的に選ぶこともできます.

$ artenv new art
Select the template
1) default/standard
#? 1
created /path/to/art from template default/standard

Next: register an environment for this directory:
  artenv register <env> --version <version> --work /path/to/art

作成した directory は, 必要な設定を編集したあとで environment として登録します.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/art \
  --singleuser

Configuration Files

設定は $ARTENV_ROOT 以下の TOML ファイルとして保存されます.

Version Configuration

native version の例です.

$ARTENV_ROOT/versions/artemis-native.toml

[version]
type = "native"
artsys = "/path/to/artemis"
rootsys = "/path/to/root"
yamllib = "/path/to/yaml-cpp/lib"
yamlcmake = "/path/to/yaml-cpp/cmake"

Apptainer version の例です.

$ARTENV_ROOT/versions/artemis-latest.toml

[version]
type = "apptainer"
uri = "oras://ghcr.io/yano404/artemis_apptainer:latest"
image = "/path/to/artemis.sif"
digest = "sha256:..."

uri と digest は artenv version install で登録した場合に保存されます. 既存の .sif を artenv version register で登録した場合は image のみです.

Environment Configuration

$ARTENV_ROOT/envs/h424.toml

[env]
version = "artemis-latest"
work = "/path/to/work"
git_repos = "/path/to/git_repos"
use_artlogin = false
binds = ["/extra/path"]

use_artlogin = true の environment は multi-user environment として扱われます. binds は Apptainer version を使う environment で利用されます.

Apptainer Support

Apptainer version を使う environment が有効なとき, 次のコマンドは自動的に container 内で実行されます.

• artemis
• root

それ以外のコマンドは host 側で実行されます. 任意のコマンドを container 内で実行するには artexec を使います.

artexec ./make.sh
artexec bash
artexec which root

解析コードを container 内の ROOT や Artemis を使って build する場合も, cmake や make に artexec を付けて実行します.

artexec cmake -S . -B build
artexec make -C build

ART_WORK_DIR は自動的に container へ bind mount されます. 追加で bind したい path がある場合は environment config に binds を記載します.

$ARTENV_ROOT/envs/h424.toml

[env]
version = "artemis-latest"
work = "/path/to/work"
binds = ["/extra/path1", "/extra/path2"]

Apptainer environment でも artlogin を使えます. use_artlogin = true の environment では USE_ARTLOGIN=YES が設定され, host 側で artlogin function が定義されます. artlogin が作る user ごとの checkout は shared working directory の下に作られるため, container wrapper からも同じ directory が見えます.

Templates

artenv new で使う template は, $ARTENV_ROOT/templates/<repo>/ 以下に cache されます. template repository は $ARTENV_ROOT/template-repos/<name>.toml で設定します.

Template Repository Configuration

template repository の設定は次のような TOML で保存されます. 追加や編集には Template Commands の command を使えます. TOML を直接編集することもできます.

$ARTENV_ROOT/template-repos/default.toml

[repo]
url = "https://github.com/yano404/artemis-templates.git"
enabled = true
ref = "main"
description = "Artemis analysis templates"

template-repos/default.toml は初回実行時に share/template-repos/default.toml から作られます. runtime data として扱われるため, 自分の環境に合わせて編集しても git pull 時の衝突を避けやすくなっています.

private repository の認証は git の SSH key や credential helper に任されます. artenv は credential を保存しません.

Local Templates

$ARTENV_ROOT/templates/local/ に置いた template は local/<template> として使えます. local namespace は artenv templates update の対象にはなりません.

Command Structure

v2.1 以降では, command は対象ごとに整理されています.

• environment command: artenv register, artenv ls, artenv info, artenv shell のように直下で実行する.
• version command: artenv version ls, artenv version register, artenv version install のように version group の下で実行する.
• template command: artenv templates ls, artenv templates update のように templates group の下で実行する.
• utility command: artenv bootstrap, artenv doctor, artenv upgrade, artenv commands など.

以前の flat command も deprecated alias として残っています. たとえば artenv register-env は artenv register, artenv register-version は artenv version register, artenv install は artenv version install と同じ処理を行います. ただし新しく書く手順では grouped command を使うのがおすすめです.

deprecation notice を消したい場合は, ARTENV_NO_DEPRECATION=1 を設定します.

Utility Commands

artenv bootstrap

artenv 用の yq を取得し, $ARTENV_ROOT/vendor/bin/yq に導入します. すでに導入済みの場合は再取得しません. --force を指定すると再取得して置き換えます.

artenv bootstrap
artenv bootstrap --force

artenv doctor

登録済み environment や artenv store の状態を診断します.

artenv doctor
artenv doctor h424
artenv doctor --all
artenv doctor --orphans

--orphans は store 全体を確認し, 参照されていない .sif image, 存在しない version を参照する environment, 対応する environment がない *.artlogin.sh などを報告します. 問題が見つかった場合は non-zero で終了します. --orphans では使用中の yq の version, path, 導入元 (artenv 管理または system) も確認できます.

artenv migrate

v1 の symlink-based な設定を v2 の TOML-based な設定へ移行します.

artenv migrate

link を解決できない項目は削除せずに残し, non-zero で終了します. link を修正してから再実行します.

artenv upgrade

artenv 本体を最新の release tag に更新します.

artenv upgrade

remote から tag を取得し, 最新の vX.Y.Z tag を checkout します. release tag 上の detached HEAD になるのは意図された挙動です.

artenv upgrade が更新するのは tracked な core files だけです. versions/, envs/, templates/, template-repos/, images/, vendor/ などの runtime data は gitignore されており, 変更されません.

tracked file に local change がある場合, artenv upgrade は stash せずに停止します. 必要なら自分で退避してから再実行します.

git -C "$ARTENV_ROOT" stash
artenv upgrade
git -C "$ARTENV_ROOT" stash pop

Apptainer image は artenv upgrade では更新されません. image を更新する場合は別途 artenv version install --update <version> を実行します.

artenv commands

利用可能な command を表示します.

artenv commands

artenv --version

artenv のバージョンを表示します.

$ artenv --version
artenv v2.6.1 (bf20389)

Environment Commands

artenv ls

登録済みの environment を表示します. * が付いているものは現在有効な environment です.

$ artenv ls
  artdev
  e545
* e559
  h424

archived environment も含めて表示する場合は --all を使います.

artenv ls --all

artenv register

解析 environment を登録します.

artenv register <env-name> [options]

実行すると, 登録済みの Artemis version から使用するものを選択し, working directory や artlogin の設定を入力します.

$ artenv register h424
Select the artemis version
1) artemis-native
2) artemis_apptainer-latest
#? 2
artemis_apptainer-latest was selected
Enter the path to working directory> /path/to/analysis_directory
Use artlogin? (y/n)> n
Enter the path to git repos (optional)> /path/to/git_repos or URL of git repos
h424 was registered

各項目は option で指定できます. すべて指定すれば非対話で environment を登録できるため, HPC の setup script や batch job でも使いやすくなります.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/analysis_directory \
  --singleuser

利用できる option は次の通りです.

option	meaning
--version <version>	使用する Artemis version. 登録済みかつ archived でないもの.
--work <dir>	working directory. 既存の directory を指定する.
--repos <url-or-path>	git repository の path または URL. --multiuser では必須.
--multiuser	artlogin を有効にする. use_artlogin = true として保存される.
--singleuser	artlogin を無効にする. use_artlogin = false として保存される.

TTY 上では, option を省略した項目だけ従来通り対話的に入力できます. TTY でない場合は入力できないため, --version と --work が必須です. --multiuser を指定しなければ single-user として登録されます.

複数人で使う artlogin environment は次のように登録します.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/shared_directory \
  --repos /path/to/upstream.git \
  --multiuser

artenv info

environment の詳細を表示します. 引数を省略した場合は現在有効な environment を表示します.

artenv info
artenv info h424

native environment の例です.

$ artenv info e559
- env: e559
- artemis version: artemis-e559
  - artemis: /home/quser/local/artemis/artemis-e559 [OK]
  - root: /home/quser/local/root/v6.26.10 [OK]
  - yaml-cpp lib: /home/quser/local/yaml-cpp/yaml-cpp-0.6.3/lib [OK]
  - yaml-cpp cmake: /home/quser/local/yaml-cpp/yaml-cpp-0.6.3/lib/cmake [OK]
- analysis directory: /home/yano/work/e559/art [OK]
- working directory: /home/yano/work/e559/art [OK]
- git repository:
- use artlogin: NO

Apptainer environment の例です.

$ artenv info e559-apptainer
- env: e559-apptainer
- artemis version: artemis-apptainer
  - type: apptainer
  - image: /path/to/artemis.sif [OK]
  - binds: <none>
- analysis directory: /home/yano/work/e559/art [OK]
- working directory: /home/yano/work/e559/art [OK]
- git repository:
- use artlogin: NO

artenv shell

現在の shell で使う environment を切り替えます. 引数を省略すると現在有効な environment を表示します.

artenv shell h424
artenv shell

切り替えに失敗した場合は non-zero で終了します. 有効化した environment の working directory には acd で移動できます.

artenv default

新しく開く shell で使うデフォルト environment を設定します. 引数を省略すると現在のデフォルト environment を表示します.

artenv default h424
artenv default

artenv new

template から working directory を作成します.

artenv new <dir> -t <template>

<template> は <repo>/<template> の形で指定します. template 名が一意に決まる場合は repository 名を省略できます.

artenv new /path/to/work -t default/standard
artenv new /path/to/work -t standard

複数人で共有する project の雛形を作る場合は --multiuser を使います. この mode では shared directory と upstream bare repository だけを作り, environment 登録は行いません.

artenv new --multiuser /shared/myproject -t default/standard

artenv edit

environment の TOML config を $VISUAL または $EDITOR で開きます. 保存時に TOML として読めるか検証されます.

artenv edit h424
artenv edit

artenv remove

environment を削除します.

$ artenv remove e559
Remove environment 'e559'? (y/N)> y
e559 was removed

artenv archive / unarchive

使わなくなった environment を削除せずに一覧から隠せます. archived environment は通常の artenv ls には表示されませんが, 参照や有効化はできます.

$ artenv archive e545
e545 was archived

$ artenv ls
* e559
  h424

$ artenv ls --all
  e545 (archived)
* e559
  h424

$ artenv unarchive e545
e545 was unarchived

Version Commands

artenv version

現在有効な Artemis version を表示します. artenv version current も同じ用途で使えます.

$ artenv version
artemis-e559

artenv version ls

登録済みの Artemis version を表示します. * が付いているものは現在有効な version です.

$ artenv version ls
* artemis-e559
  artemis-root-6.26.10
  develop

archived version も含めて表示する場合は --all を使います.

artenv version ls --all

artenv version register

既存の native installation や .sif image を Artemis version として登録します.

artenv version register <version-name>

まず version type を選択します.

Select version type
1) native
2) apptainer
#?

native を選んだ場合は, ホスト側にインストール済みの Artemis, ROOT, yaml-cpp の path を入力します. Apptainer を選んだ場合は, 既存の .sif image の path を入力します.

artenv version install

Artemis version を用意して登録します. Apptainer image の pull, native build, 既存 Apptainer image の update に対応しています.

artenv version install latest
artenv version install --list
artenv version install --apptainer
artenv version install --native
artenv version install --update artemis-latest

--update は artenv version install で登録した Apptainer version を re-pull します. registry 側の digest を確認し, 更新がある場合は確認後に SIF を上書きします. archived などの既存の version 設定は保持されます.

$ artenv version install --update artemis-latest
Checking registry...
Update:
  VERSION                artemis-latest
  URI                    oras://ghcr.io/yano404/artemis_apptainer:latest
  SIF                    /home/yano/.artenv/images/artemis-latest.sif
  DIGEST                 sha256:121ea823...
OK? (y/N)> y

artenv version info

version の設定を表示します. 引数を省略した場合は現在有効な version を表示します.

artenv version info
artenv version info artemis-latest

artenv version edit

version の TOML config を $VISUAL または $EDITOR で開きます. 保存時に TOML として読めるか検証されます.

artenv version edit artemis-latest
artenv version edit

artenv version remove

登録済みの version を削除します. その version を使っている environment がある場合は削除が止まります.

$ artenv version remove artemis-e559
artenv: version 'artemis-e559' is used by the following environments:
  - e545
remove these environments first, or use --force

Apptainer version と一緒に $ARTENV_ROOT/images 以下の SIF も削除したい場合は --purge を使います. ただし, 別の version も同じ SIF を参照している場合は image を残し, 指定した version の登録だけを削除します.

$ artenv version remove --purge artemis-latest
Remove version 'artemis-latest'? (y/N)> y
removed image: /home/yano/.artenv/images/artemis-latest.sif
artemis-latest was removed

artenv version archive / unarchive

version も environment と同じように archive できます. archive した version は artenv version ls から隠れますが, 削除はされません.

artenv version archive artemis-old
artenv version ls --all
artenv version unarchive artemis-old

Template Commands

Templates で説明した repository を管理する command です.

artenv templates update

設定済みの template repository を clone または update します. 引数を省略すると enabled な repository をすべて処理します.

artenv templates update
artenv templates update default

artenv templates ls

取得済み template を <repo>/<template> の形で表示します.

artenv templates ls

artenv templates repos

設定済み template repository を表示します.

artenv templates repos

artenv templates add-repo

実験や研究グループで用意した template repository を登録し, 取得します. 以下の URL は例なので, 使用する repository の URL に置き換えてください.

artenv templates add-repo experiment https://example.org/group/artemis-templates.git
artenv new /path/to/work -t experiment/standard

--ref <ref> で branch, tag, commit を, --description <text> で説明を指定できます. --no-fetch を付けると登録だけを行い, あとから artenv templates update experiment で取得できます. 通常の登録で取得に失敗した場合は, 登録が取り消されます.

artenv templates edit-repo

repository の TOML config を $VISUAL または $EDITOR で開き, 保存後に TOML の構文を検証します. URL や ref の変更は, update で cache に反映します.

artenv templates edit-repo experiment
artenv templates update experiment

artenv templates disable-repo / enable-repo

repository を削除せず, 一覧や対話選択から隠せます. 無効化した repository は templates ls, new の選択肢, templates update の対象から外れます. cache は残るため, -t experiment/standard のように repository 名を含めて指定すれば使用できます.

artenv templates disable-repo experiment
artenv templates enable-repo experiment

artenv templates remove-repo

repository の設定と取得済み cache を確認なしで削除します. その template から作成済みの解析ディレクトリには影響しません.

artenv templates remove-repo experiment

default も削除できますが, 自動では復元されません. 必要になった場合は add-repo で再登録します.