The Wire-Cell Workstation Cluster

Table of Contents

1. Introduction

This document describes a loosely federated cluster of workstations designed to achieve a few high level goals:

  • Enable easy sharing of workstation hardware.
  • Share common software stacks and simplify their build and distribution.
  • Provide easy means to use and develop software based on these stacks.

The name Wire-Cell Workstation Cluster (WCWC) is given to reflect the fact that its need was recognized in the context of development of Wire-Cell software. Despite that name, it is general to many pursuits. Indeed, and as will be shown, any software stacks that may be built with Spack can be incorporated into a WCWC. The WCWC was also conceieved for use on the internal campus network at BNL. However, it may be replicated in whole or in parts at other institutions or even on personal workstations and laptops.

1.1. Overview

The following topics are covered in this document:

  • End-user interaction with the WCWC software ecosystem is described in section 2. This gives simple guidance on how a user may find what software is available, configure the user’s account and use the software.
  • Software developer interaction with the WCWC software ecosystem is described in section 3. This shows how to develop software leveraging the WCWC ecosystem.
  • Administrative tasks such as initializing WCWC software ecosystem from a green field, installing software packages and other such things are in section 4.

1.2. Terms

WCWC is described in terms of different types of user accounts and computers across different networks. The document attempts to adhere to using these terms:

workstation
a physical computer, be it desktop or laptop, part of WCWC or not.
local workstation
a workstation at which a human user currently sits.
remote workstation
a workstation accessible by another workstation.
(ssh) client account
an account from which the ssh client may be run.
(ssh) server account
an account in which an ssh connection may produce a session.
local account
an account managed by the operating system of the workstation (eg via an entry in /etc/passwd)
distributed identity
an account managed outside of any one workstation operating system but applied to many.
internal (account or workstation)
that which is part of a WCWC
external (account or workstation)
that which is not part of a WCWC, possibly separated from a WCWC via a firewall or other access control.
home provider
a single WCWC workstation providing a user’s $HOME.

These terms are meant to provide generic applicability are informed by the particular BNL WCWC organization. See the companion document wcwc-bnl.html for details specific to BNL WCWC.

1.3. Enrollment

WCWC users and workstations must go through some enrollment process specific to the requirements and needs of each WCWC instance. Enrollment in the BNL WCWC is described in the companion document wcwc-bnl.html. Use of a WCWC software ecosystem via the wcwc command (described below) is relatively insensitive to details of this enrollment. Users of individual (non-clustered) workstations and laptops likely need no specific enrollment process.

1.4. Software Ecosystem

The remainder of this document focuses on the WCWC software ecosystem from the point of view of the (end) user, software developer and administrator. The ecosystem is build with Spack via automation and policy applied by the wcwc command available from where you got this document. It is assume the WCWC admin has arranged for wcwc to be provided in the user’s $PATH.

1.5. Project and problems

The WCWC project has all (meta) files in the brettviren/wcwc GitHub repo. Users of general WCWC features or the BNL WCWC instance are encouraged to report problems via that repository’s GitHub Issues. Any problems specific to non-BNL WCWC instances, should be reported elsewhere.

2. User

This section is intended to be read by all users with emphasis for those that will be “end” users that wish to merely run existing software.

2.1. OS packages

To simply run the wcwc command, the following packages are required:

  • lsb-release
  • git
  • python3
  • python3-click
  • python3-yaml
  • python-is-python3

Additional OS packages may be according to the policy for the particular WCWC instance. See wcwc-bnl.html#os-packages for the BNL WCWC OS package policy.

2.2. Introduction of Spack and wcwc

The large software stacks for various projects and experiments are installed by the WCWC admin via Spack and made available to each WCWC workstation under the /wcwc directory.

Spack is a system used throughout HEP and other scientific communities to build and manage software ecosystems that may evolve over time to grow very large, spanning multiple suites comprised of many packages distinguished by different versions, build variants, compilers and hardware architectures.

A WCWC user may interact with this software directly via the spack command. However, the wcwc command provides a simple interface to the most common tasks. To get started with wcwc the user is encouraged to become familiar with its command-line help. The main “page” of which can be viewed by running the command with no arguments:

$ wcwc
Usage: wcwc [OPTIONS] COMMAND [ARGS]...

  Operate on the WCWC software ecosystem.

Options:
  -L, --log-level TEXT     set logging level [default:info]
  -l, --log-output TEXT    log to a file [default:stdout]
  -I, --image TEXT         Name podman image in which to run,
                           no/off/disable/none to run directly or
                           yes/on/enable for "wcwc-builder", default=off
  -P, --image-prefix TEXT  Specify WCWC Spack installation prefix inside
                           container (def=/wcwc)
  -p, --prefix TEXT        Specify WCWC Spack installation prefix (def=/wcwc)
  -c, --config TEXT        Specify a config file
  -h, --help               Show this message and exit.

Commands:
  admin    Commands to modify the WCWC installation.
  env      Create a Spack Environment in a directory.
  envs     List the defined system/shared environments.
  find     Find matching installed package instances.
  list     List matching package names (not instances).
  scopes   List known scopes
  shell    Produce a configured shell environment.
  show     Show information about a stack.
  spack    A wrapper around spack for WCWC admins.
  spec     Wrapper around spack spec.
  stacks   Show status about existence of known stacks.
  version  Print WCWC version

If the above does not reflect what wcwc shows for you, then this document needs regenerating.

The top-level options related to “image” control running the wcwc command inside a podman container. This is primarily meant for expert users and WCWC admins. More information on this feature is in section 4.1. Similarly, the admin group of commands are intended for use by WCWC admins and may be ignored by users.

Each command has its own help “page” which an be viewed like:

$ wcwc <command> --help

The remainder of this section describes how to use wcwc for common tasks that “end users” may require. Subsequently in sections 3 and 4 we describe how to use wcwc for developers and cluster administrators, respectively.

2.3. Shell environment

To use software built by Spack, the user shell environment requires some settings. The wcwc shell command provides a number of ways to achieve this.

$ wcwc shell --help
Usage: wcwc shell [OPTIONS]

  Produce a configured shell environment.

  This is a user command.  WCWC admins should avoid using this to modify the
  WCWC installation.  Instead use command in the "wcwc admin" group.

  This command supports a "cross product" of behavior along these dimensions:

  - the shell flavor (fish, sh-like and csh-like)

  - the mode of supplying the target environment (settings, command or shell)

  - the make up of the target environment (base, load modules, activate
  environment)

Options:
  -S, --stacks TEXT               Comma-separated list of stack names, if
                                  needed to resolve environment
  -s, --shell [sh|bash|dash|zsh|fish|csh|tcsh|auto]
                                  Set the shell flavor, default:auto
  -o, --output TEXT               Emit shell settings to given output, "-" or
                                  "stdout" for emitting to standard output
  -c, --command TEXT              Execute the command in a configured shell
  -e, --environment TEXT          Use given Spack Environment to determine
                                  shell settings
  -l, --load TEXT                 Load the given package spec
  -k, --keep                      Retain settings file and emit its name
                                  (ignored for -o/--output)
  -h, --help                      Show this message and exit.

As introduced in the help page, there are three basic modes employed in use of wcwc shell:

subshell
Execute a configured sub-shell for interactive use (default).
command
Run a single command in a configured environment (give -c/--command option).
mutate
Modify the currently running shell with environment settings (get -o/--output option).

With subshell one gets a properly configured interactive shell to use. When done, simply exit to return to the calling shell, which has remained unchanged. With command, a single command is run and when complete the user is again returned to their previous and unchanged shell session. On the other hand, the mutate mode will emit shell environment settings intended to modify an existing shell. This should be used with caution as there is no “undo” (in general) and the user must exit the original shell to escape the mutations.

Regardless of mode the environment is modified according to specified loading of “environment modules” (-l/--load) and/or activating a Spack Environment (-e/--environment). In addition, the shell to assume is detected automatically but can be forced with -s/--shell. Furthermore, zero or more software “stacks” can be named to provide access to more or less of the ecosystem.

The following sub sections give examples of use of wcwc shell.

2.3.1. Minimal shell

Here perform minimal wcwc shell commands. The results are not terribly useful other than to illustrate basic features. First, we may start a subshell:

u$ wcwc shell
s$ exit

While in the subshell we have access to the spack command and not much else.

We have introduced a notation to mark the shell prompt to indicate something about a particular shell configuration. Here, u$ indicates the user’s nominal shell environment and s$ indicates a shell configured for Spack.

By default, wcwc shell executes an instance of the same shell currently run by the user. The user may explicitly specify the shell to execute:

tcsh-u$ wcwc shell --shell bash
bash-s$ 

Not all shells are supported for subshell or command modes. When this limitation is encountered, wcwc shell will cause an error and give the user a list of supported shells. These users will need to explicitly name a supported shell with the -s/--shell option.

2.3.2. Using individual Spack packages

Spack supports a method to configure shell environment for use of individual software packages that is called “Environment Modules”. This support is enabled when wcwc shell is called with one or more -l/--load options:

u$ wcwc shell --load root
bash-s$ root -l
root [0] .q
bash-s$ exit
u$

Or, avoid the explicit subshell:

u$ wcwc shell -l root/ra4vsyp -c "root -l"
root [0] .q
u$

2.3.3. Learning Spack package names

Spack package names may differ slightly from what may be expected. To list matching packages (not installed package instances):

$ wcwc list torch
py-botorch                      py-torch              py-torch-spline-conv  py-torchmeta
py-efficientnet-pytorch         py-torch-cluster      py-torchaudio         py-torchmetrics
py-gpytorch                     py-torch-geometric    py-torchbenchmark     py-torchsummary
py-pytorch-gradual-warmup-lr    py-torch-harmonics    py-torchdata          py-torchtext
py-pytorch-lightning            py-torch-nvidia-apex  py-torchdiffeq        py-torchvision
py-pytorch-sphinx-theme         py-torch-scatter      py-torchfile          py-vector-quantize-pytorch
py-segmentation-models-pytorch  py-torch-sparse       py-torchgeo
==> 27 packages

By default, the list command will only check for packages in the Spack stack and thus is blind to package provided by other stacks. Additional stacks may be given:

$ wcwc list wire-cell-toolkit
==> 0 packages

$ wcwc list -S wirecell wire-cell
wire-cell-data  wire-cell-dependencies  wire-cell-extra  wire-cell-prototype  wire-cell-toolkit
==> 5 packages

2.3.4. Specifying packages unambiguously

The example above when run in a full ecosystem will likely fail with some error like:

u$ wcwc shell -l root
==> Warning: Can't read package file /wcwc/spack/var/spack/repos/builtin/packages/bigdft-liborbs/package.py.

==> Error: root matches multiple packages.
  Matching packages:
    ra4vsyp root@6.32.02%gcc@12.2.0 arch=linux-debian12-x86_64
    kl5ziao root@6.32.02%gcc@12.2.0 arch=linux-debian12-x86_64
  Use a more specific spec (e.g., prepend '/' to the hash).

This is because the simple name root does not unambiguously identify a single installed instance of the package root. No problem as the -l/--load command actually accepts a “sentence” written in domain specific language called a Spack “spec” that can unambiguously describe installed package instances. See section 2.4.1 for a brief introduction. To discover how to write a spec, one may list available packages in more detail:

u$ wcwc find -lv root
-- linux-debian12-x86_64 / gcc@12.2.0 ---------------------------
ra4vsyp root@6.32.02~aqua~arrow~cuda~cudnn+davix~dcache~emacs+examples~fftw~fits~fortran+gdml+gminimal~graphviz+gsl~http~ipo+math+minuit~mlp~mysql~opengl~postgres~pythia8+python~r+roofit~root7+rpath~shadow~spectrum~sqlite~ssl+tbb+threads~tmva~tmva-cpu~tmva-gpu~tmva-pymva~tmva-sofie+unuran~vc+vdt~veccore+x+xml~xrootd build_system=cmake build_type=Release cxxstd=17 generator=make patches=22af347,9de4aa6
kl5ziao root@6.32.02~aqua~arrow~cuda~cudnn+davix~dcache~emacs+examples+fftw~fits~fortran+gdml+gminimal~graphviz+gsl~http~ipo+math+minuit+mlp~mysql+opengl~postgres~pythia8+python~r+roofit~root7+rpath~shadow+spectrum~sqlite~ssl+tbb+threads+tmva+tmva-cpu~tmva-gpu~tmva-pymva~tmva-sofie+unuran~vc+vdt~veccore+x+xml~xrootd build_system=cmake build_type=Release cxxstd=17 generator=make patches=22af347,9de4aa6
==> 2 installed packages

The find command can take a while as it must interrogate a large portion of the ecosystem. Your use of find may return different results depending on the state of the WCWC ecosystem.

This find command gives a lot of information but for our purpose we need only to examine the versions and/or the list of variants are enabled (with a +) or disabled (with a ~) and then use short hash to reference the instance we wish to “load”.

u$ wcwc shell -l root/ra4vsyp
s$ root -l
root [0] .q
s$ exit
u$

2.3.5. One-shot commands

Above we used wcwc spec to enter an interactive shell and from there run a command (root). The user must issue exit to finally return to the original shell. When the intermediate interactive shell is not needed it is simpler to execute the desired command directly. For example:

u$ wcwc shell --load root --command "root -l"
root [0] .q
u$ 

Exiting root brings the user back to the original shell.

2.3.6. Using Spack Environments

Spack Environments provide another shell environment configuration mechanism that is distinct from “Environment Modules” and conceptually similar to Python virtual environments. Like a Python venv, a user may “activate” a Spack Environment to configure the shell to make use of its contents. Because a Spack Environment collects software files via the file system (in a directory called a Spack view) fewer shell environment settings are required than when using Environment Modules. A Spack Environment is also defined by a directory and so is “durable” across different shell sessions.

Spack Environments can be of two types:

  • “system” aka “shared” environments are defined by the WCWC admin, users may “activate” them but not modify them.
  • “personal” aka “developer” are fully defined, modified and owned by the user.

Here, we show how to use system environments and in section 3.3 describe use of a “personal” environments.

Available environments can be listed:

u$ wcwc envs

u$ wcwc envs --stacks all
spack:
==> No environments

base:
==> No environments

wirecell:
==> 1 environments
    wct-master-gcc

As implied, in WCWC the environments are defined in the context of a WCWC “stack”. See section 2.4.2 for more information on stacks. To use an environment defined in a stack, one must name the stack:

u$ wcwc shell -S wirecell -e wct-master-gcc
e$ wire-cell --help
e$ exit
u$

2.3.7. Combining

Environment Modules and Spack Environments may be used together:

u$ wcwc shell --load root --environment wct-minimial
r+wc$ 

And one may use either in a one-shot command.

u$ wcwc shell --load root --environment wct-minimial --command "which root; which wire-cell"
u$

2.3.8. Shell mutation

If you must mutate an existing shell session:

u$ ssh shell -o sourceme
m$ source sourcme
m$ ...
m$ exit
(logout)

The calling shell environment is mutated and can not be undone. It is up to the user to remove the output script (sourceme) if/when desired.

2.4. A few Spack and WCWC concepts

This section describes some concepts introduced above.

2.4.1. Spack spec

In the example above, “root” is an abstract “spec” naming just the package. When multiple package instances are installed, this name is ambiguous. The command can not determine which installed instance to select and more “concrete” version of the spec must be used. For example, if there are multiple versions of root installed we must provide a more complete spec:

$ wcwc shell --load root@6.30.06

See the Spack documentation for details on spec. In WCWC one can discover installed package instances with:

u$ wcwc find root
-- linux-debian12-x86_64_v3 / gcc@12.2.0 ------------------------
root@6.30.06
==> 1 installed package

In WCWC, packages are installed into the “namespace” of a stack and the above only searches the base Spack stack. See section 2.4.2 for more information.

2.4.2. WCWC stacks

A WCWC “stack” solidifies a nascent Spack pattern. A “stack” represents a subset of packages from a larger overall set. Specifically, the subset consists of packages that can be built by a particular Spack “repo”. A WCWC “stack” provides a Spack configuration “scope” that associates a repo, its corresponding Spack “namespace”, a package install tree and projection and a location to store definitions of system or shared Spack Environments. The stack may also have an associated git remote repository URL (and a git branch and/or tag) that provides the Spack “repo”.

A stack may coarsely depend on another stack with a stack corresponding to the Spack “builtin” repo forming the trunk of that dependency tree. If on stack’s install tree differs from a dependency then that dependency is considered a Spack “upstream”. Otherwise, stack install trees may coincide though it is recomended to define a stack’s “projection” to begin with {namespace}/ in order to keep distinct packages provided by each stack’s Spack repo. In particular, this distinction allows to resolve namespace collisions that arise when different Spack repos providing packages of identical name.

For users of wcwc, what is important to understand is that they may need to be named when using or making Spack Environments and/or packages. The wcwc subcommands generally take the -S/--stacks option to provide a comma-separated list of stacks:

$ wcwc <command> --stacks wirecell,base [....]

3. Developer

In this section we give guidance intended for those developing software in the WCWC ecosystem.

3.1. Personal environments

We saw the use of “system” or “shared” environments in section 2.3.6. Here we describe how to make a “personal” environment. It differs from a system environment largely in that its directory resides in a user-owned area and that we will refer to it by its directory path instead of a name. It also differs in that it is not shared and its life cycle is solely controlled by user.

To begin, we create a personal environment, based on a number of stacks and potentially with some number of initial specs:

u$ wcwc env --help

u$ wcwc env --stacks wirecell --environment ~/my-wct-env wire-cell-toolkit/q3zolqz
...
==> Updating view at /home/wcwc/my-wct-env/.spack-env/view

Additional specs may be added by repeating this command listing just the new specs.

We may then create a shell configured to use this environment similarly to how we did with system environments in section 2.3.6 except that we give our environment directory instead of a name:

u$ wcwc shell --environment ~/my-wct-env
e$ wire-cell --help
e$ exit
u$

3.2. Installing packages to environments

When adding a spec to an environment as shown in section 3.1 we must only provide specs that describe packages installed in a stack. It is also possible to install novel package instances directly to an environment. For now, this requires dropping down to spack.

u$ wcwc env --environment ~/test-env 
--> In WCWC, activate with: wcwc shell -e /home/bv/test-env
u$ wcwc shell -e /home/bv/test-env
e$ spack install --add zstd@1.5.0
...
[+] /home/bv/test-env/opt/builtin/linux-debian12-x86_64/gcc-12.2.0/zstd-1.5.0-gpj2gvmgyrdmwi2gfk3rkdk4gdfwm5es
==> Updating view at /home/bv/test-env/.spack-env/view

This example installs and adds an older version of zstd which is unlikely be an installed in order to observe that dependencies are taken from the central WCWC installation while zstd itself is built from scratch and installed into the environment area..

3.3. Developer environments

Personal environments may be easily used for developing software as all package files are collected into a single file system tree called the “view”. The view directory can be found at:

$ ls ~/test-env/.spack-env/view/
bin  include  lib  man

When the environment settings are activated (wcwc shell -e test-env) Spack defines a variable SPACK_ENV that points to the root directory. This may then be used to configure build systems of software to be developed. For example using waf or wcb from Wire-Cell Toolkit or Prototype we may execute:

e$ ./wcb configure --prefix=$SPACK_ENV/.spack-env/view [...]
e$ ./wcb install

In the case of WCT, this does two things. It tells the build system to check in the “prefix” when auto-locating required dependencies and it uses the “prefix” as the installation target. In the case where the environment and its view are filled with files from WCT itself, this installation merely overwrites the symlinks.

3.4. Spack View for development

The kernel of a Spack Environment is a Spack View. It may be used to create a simpler developer environment. The user may supply the environment settings or optionally a direnv .envrc file can be initialized to supply basic shell environment settings. To create the view:

The view command help page:

$ wcwc view --help
Usage: wcwc view [OPTIONS] VIEW

  Create a view directory given one or more seed specs.

Options:
  -S, --stacks TEXT   Set stacks to use as comma separated list
  -e, --exclude TEXT  Exclude a spec from the view. Special 'seeds' excludes
                      the seeds
  -d, --direnv TEXT   Initialize a direnv .envrc in the given directory
  -s, --seed TEXT     Supply a seed spec.
  -f, --force         Force (re)making the view
  -h, --help          Show this message and exit.

The use of -d/--direnv=/path means that with a direnv-enabled shell, cd’ing to that /path will cause your shell to be configured to use the view. This includes a Python virtual so that any pip install or python setup.py install commands install into the view directory. For a worked example, see wcwc-howto.html#spack-view-wct.

4. Administrator

The WCWC administrator is responsible to assemble the original WCWC, assist with enrollment and populate /wcwc with packages, stacks, and environments. Users wishing to make use of wcwc to supply software to their individual (non-clustered) laptops or workstations will also be an WCWC administrator. This section describes ways that the wcwc command can assist in some of these tasks.

The basic “user” commands are relevant for admin tasks and in addition some tasks not relevant to users are placed in the admin command group:

$ wcwc admin

4.1. Use of podman images

The wcwc command can execute itself in a podman container (using an image it creates) in order to enable these important features:

  • Tightly control the build host environment.
  • Decouple “apparent” and “real” path for WCWC_PREFIX.

By default, a fixed image is used. That is, running the container does not produce a new image. Instead, a “real” directory is mounted into the container to provide WCWC_PREFIX. The WCWC admin should always use a podman image for wcwc admin install even when WCWC_PREFIX redirection is unnecessary.

Any named image that does not exist will be created on the fly if they do not exist and wcwc will not change an existing image. The default image name is wcwc-image. If a custom image is created it should have an ENTRYPOINT that runs wcwc.

The external (native host) WCWC_PREFIX and the location it is mounted in the container can be controlled. Both default to /wcwc.

Given “true’ish” prefix path or image names (true yes on enable enabled) the defaults are used and given “false’ish” (false no off disable disabled none) they are disabled. Otherwise the paths/names are take as literal.

A simple, if pointless exercising of the podman support is:

$ wcwc -I yes -p /tmp/my-wcwc -P /weird/path/wcwc version
...builds image if first time...
0.0.2

Some reasons as to why these options might be specified are discussed in section 4.3.

4.2. Compilers

t.b.d. defining OS-packaged and Spack-built compilers.

4.3. Green field installation

Starting from a “vanilla” computer, we describe how to construct the /wcwc area.

It is recommended to create a special user (eg “wcwc”) that has sole write permission to /wcwc. In principle, multiple users may contribute to modifying /wcwc but that can lead to confusion and “cruft”. Future WCWC development may explore ways to allow multiple users and workstations to contribute to building out the /wcwc contents.

4.3.1. Preamble

We start by selecting a location to store all the software. Potentially 100s of GB or more may be required depending on how much software is installed. By default, the /wcwc directory is used but a non-standard location may be set in one of two ways:

$ export WCWC_PREFIX=/path/to/wcwc
$ export WCWC_IMAGE=yes  # can also give some name to use non-standard image

### or

$ wcwc --image=yes --prefix=/path/to/wcwc [...]

The command line overrides environment variable. If a non-standard WCWC prefix is used, then it must be subsequently used by all users of the wcwc command. We may use an external WCWC_PREFIX which is different than the prefix used in the container (eg, default /wcwc) if we wish to utilize some build host that can not write to /wcwc. After doing new installations to /wcwc in the container we may rsync from the changes that were fed into the non-standard WCWC_PREFIX to an account that can write to the “real” /wcwc.

We will assume henceforth that the default prefix is used.

In section 4.1 the use of a podman container image to install packages is introduced. In the container the /wcwc path is always used. Outside the container the WCWC_PREFIX or --prefix value is that of a host directory. It will be mounted onto /wcwc in the container.

4.3.2. Initialize

The base Spack and any other stacks can be initialized simply with:

$ wcwc admin init spack
$ wcwc admin init wirecell

The spack stack is treated special in that its scope is the usual “system” scope found here under /wcwc/spack/etc/spack/. Files for the other stacks are placed under stacks/<stack>/ subdirectory under the WCWC prefix to hold the scope and environments and potentially a unique install tree.

4.3.3. Options

Prior to initialization, the file wcwc.yaml is read from the prefix directory in order to describe known stacks. You may explicitly create this file in order to customize before initializing.

$ wcwc admin defaults

Most likely configuration change is to a tag. Alternatively, wcwc.yaml parameters for the stack being initialized can be specified on the init command line: For example, to use the current main branch for Spack:

$ wcwc admin init --tag develop spack

4.4. Installing packages

Installing packages with wcwc requires naming their spec. Eg:

$ wcwc admin install root

This will install the “preferred” version of the root package into the default stack (Spack itself with default WCWC configuration). The preferred version is typically the newest release known to Spack with the default variants considered.

Some packages that are not provided by the Spack repo may be provided by another stack and it is possible for a stack to provide a package of the same name as Spack or another stack. To have wcwc consider a stack it must be named. For example, at the time of writing Spack does not provide a go-jsonnet package but the wirecell stack does.

$ wcwc admin install --stacks wirecell go-jsonnet

When multiple stacks must are considered and they provide the same package, Spack will determine from which stack to take the package based on last-one-wins order. Or the package name can be qualified by the stack’s namespace. For example, two stacks provide go-jsonnet:

$ wcwc admin install --stacks wirecell,art wirecell.go-jsonnet

This is a contrived, unrealistic example as the two stacks are mutually incompatible at the time of writing. It does not actually make sense to consider both together.

As described in section 2.4.1, multiple instances of the same package may be installed. It is at installation time that one may specify in detail what spec to install. For example to install a minimal and a maximal WCT of a specific version:

$ wcwc admin install -S wirecell wire-cell-toolkit@0.28.0
$ wcwc admin install -S wirecell wire-cell-toolkit@0.28.0+glpk+root+hdf+cuda+torch+emacs

The spec to install can be left ambiguous. Spack will remove ambiguity through its “concretization” process. You may preview the concrete spec with wcwc spec -S wirecell wire-cell-toolkit.

4.5. Defining system environments

Almost identically to defining user environments, the admin may define “system” environments. These are defined under WCWC_PREFIX and so can be used by all users. The only difference is:

  • Must run in a podman container if the general WCWC_PREFIX was built side one.
  • Must give -t/--target option to provide the stack that will hold the definition.
$ wcwc env --target wirecell --environment wct-master-gcc wire-cell-toolkit/q3zolqz

$ wcwc envs --stacks all
spack:
==> No environments

base:
==> No environments

wirecell:
==> 1 environments
    wct-master-gcc

4.6. Updating packaging

Existing or new package.py may be edited in-place. Some git gymnasitics may be warranted:

$ cd /wcwc/stacks/wirecell/repo
$ emacs newpackage/package.py oldpackage/package.py

$ git config user.name "My Name"
$ git config user.email "myname@example.com"

$ git commit -am "Added new, fixed old"
$ git push --set-upstream origin wcwc-master:master

5. Other documents

WCWC howtos
Examples for specific tasks to accomplish with WCWC.
BNL WCWC
Information specific to the BNL instance of WCWC.
Package notes
Notes on specific packages, mostly relevant for admins.

Author: Brett Viren

Created: 2026-01-20 Tue 10:21

Validate