Installation

This repository holds the pixi environment for developing aiflow and aiflow_nodes together. Both are cloned into the root of this repository as independent git repositories (not submodules), so you can branch, commit and push in each of them as usual. They are listed in .gitignore.

aiflow_env/
├── README.md
├── pixi.toml
├── pixi.lock
├── aiflow/          # git clone, installed editable into the environment
└── aiflow_nodes/    # git clone, installed editable into the environment

The environment supports linux-64 and osx-arm64 (Apple Silicon). Intel Macs (osx-64) are not supported, since conda-forge has no recent TensorFlow build for them. On macOS, GPAW is not installed, because the only osx-arm64 build needs a newer numpy than pyiron_atomistics allows. All other packages are the same, and only the GPAW calculator nodes in aiflow_nodes are unavailable.

1. Install pixi

curl -fsSL https://pixi.sh/install.sh | sh

Restart your shell (or source ~/.bashrc) so pixi is on your PATH, then check it works:

pixi --version

See the pixi installation docs for other options.

2. Clone aiflow_env

git clone git@github.com:pyiron/aiflow_env.git
cd aiflow_env

All following commands run from this directory. git pull here later picks up changes to pixi.toml and pixi.lock; rerun pixi install afterwards.

3. Clone aiflow_nodes

git clone git@github.com:pyiron/aiflow_nodes.git

You can also work with your own fork instead.

git clone git@github.com:<your-user>/aiflow_nodes.git aiflow_nodes

4. Clone aiflow

git clone git@github.com:pyiron/aiflow.git

Or, from your own fork:

git clone git@github.com:<your-user>/aiflow.git aiflow

Either way the clones must be named aiflow and aiflow_nodes (the explicit target directory above takes care of renamed forks), since pixi.toml refers to them by these paths.

pixi.toml installs aiflow from ./aiflow (editable, with the all extra) and aiflow_nodes from ./aiflow_nodes (editable), so the clones must exist before the next step. aiflow's development tools (its dev dependency group: pytest, ruff, pylint, deptry, mkdocs, …) are listed in pixi.toml itself, because pixi cannot install a dependency group of a path dependency. aiflow_nodes' conda-forge dependencies are declared once, in its own pyproject.toml ([tool.pixi.package.run-dependencies]), and pixi.toml pulls them in through its [dev] table.

5. Install the pixi environment

pixi install

This resolves the environment from pixi.lock and installs it into .pixi/. The first run downloads several GB (LAMMPS, GPAW, TensorFlow, ...) and takes a while.

6. Build the aiflow GUI

The aiflow.gui widget is written in TypeScript (aiflow/frontend) and is compiled with npm. Node.js is part of the pixi environment, so build it with:

pixi run gui-build

This runs npm install and npm run build in aiflow/frontend and writes widget.js, widget.css and ngl.js to aiflow/src/aiflow/gui/static. Without this step the GUI shows an empty widget.

When working on the frontend, pixi run gui-dev rebuilds on every change (restart the Jupyter kernel to pick it up) and pixi run gui-test runs the jest tests.

7. Activate the pixi environment

pixi shell

This starts a subshell with the environment active; leave it with exit. Activation also sets GLIBC_TUNABLES=glibc.rtld.execstack=2, needed for the conda-forge TensorFlow build on glibc >= 2.41 (has no effect on macOS).

To run a single command without a subshell use pixi run <command>, e.g. pixi run lab to start JupyterLab.

Check the installation:

python -c "import aiflow_nodes, aiflow; print('ok')"

8. Install the pre-commit hooks

pre-commit is part of the pixi environment. With the environment active, install the hooks in each repository:

cd aiflow && pre-commit install && cd ..
cd aiflow_nodes && pre-commit install && cd ..

• aiflow installs a pre-commit hook (ruff lint and format) and a pre-push hook that runs the fast unit tests with python -m pytest. The push hook uses the active Python, so push from inside pixi shell.
• aiflow_nodes installs a pre-commit hook (ruff lint and format).

To run all hooks over the whole repository once, e.g. after installing:

pre-commit run --all-files

Skip the hooks for a single commit or push with --no-verify.

Updating

All commands run from the root of this repository.

Update the environment definition

git pull
pixi install

This picks up changes to pixi.toml and pixi.lock. pixi shell and pixi run also bring the environment in sync with the lock file automatically, so pixi install mainly saves you the wait later.

Update aiflow and aiflow_nodes

Pull in each clone as usual:

git -C aiflow pull
git -C aiflow_nodes pull

Both are installed editable, so Python code changes take effect immediately. These cases need an extra step:

• aiflow's dependencies changed (its pyproject.toml): run pixi install, which re-resolves the environment and updates pixi.lock.
• aiflow_nodes' dependencies changed (its pyproject.toml): run pixi install as well. A new conda dependency goes into its [tool.pixi.package.run-dependencies], not into pixi.toml.
• aiflow/frontend changed: rebuild the GUI with pixi run gui-build and restart the Jupyter kernel.

Update dependency versions

To move the packages in pixi.lock to the newest versions allowed by pixi.toml:

pixi update

Run the tests, then commit the new pixi.lock (and pixi.toml, if you changed version pins) to this repository.

Update the pre-commit hooks

The hook versions are pinned in each repository's .pre-commit-config.yaml, so a git pull there updates them and pre-commit installs the new versions on its next run. Nothing needs to be reinstalled.

If using vscode

Set python interpreter to .pixi/envs/default/bin/python