Edit on GitHub

Installation guide

Here are the installation instructions for package Express. If you have trouble installing it, please refer to our Troubleshooting page for more information.

Install Julia

First, you should install Julia. We recommend downloading it from its official website. Please follow the detailed instructions on its website if you have to build Julia from source. Some computing centers provide preinstalled Julia. Please contact your administrator for more information in that case. Here's some additional information on how to set up Julia on HPC systems.

If you have Homebrew installed, open Terminal.app and type

brew install --cask julia

if you want to install it as a prebuilt binary app. Type

brew install julia

if you want to install it as a formula.

If you want to install multiple Julia versions in the same operating system, a suggested way is to use a version manager such as asdf. First, install asdf. Then, run

asdf install julia 1.6.6  # or other versions of Julia
asdf global julia 1.6.6

to install Julia and set v1.6.6 as a global version.

You can also try another cross-platform installer for the Julia programming language juliaup.

Which version should I pick?

You can install the "Current stable release" or the "Long-term support (LTS) release".

  • The "Current stable release" is the latest release of Julia. It has access to newer features, and is likely faster.
  • The "Long-term support release" is an older version of Julia that has continued to receive bug and security fixes. However, it may not have the latest features or performance improvements.

For most users, you should install the "Current stable release", and whenever Julia releases a new version of the current stable release, you should update your version of Julia. Note that any code you write on one version of the current stable release will continue to work on all subsequent releases.

For users in restricted software environments (e.g., your enterprise IT controls what software you can install), you may be better off installing the long-term support release because you will not have to update Julia as frequently.

Versions higher than v1.3, especially v1.6, are strongly recommended. This package may not work on v1.0 and below. Since the Julia team has set v1.6 as the LTS release, we will gradually drop support for versions below v1.6.

Julia and Julia packages support multiple operating systems and CPU architectures; check this table to see if it can be installed on your machine. For Mac computers with M-series processors, this package and its dependencies may not work. Please install the Intel-compatible version of Julia (for macOS x86).

Install Express

Now I am using macOS as a standard platform to explain the following steps:

  1. Open Terminal.app, and type julia to start an interactive session (known as the REPL).

  2. Run the following commands and wait for them to finish:

    julia> using Pkg

julia> Pkg.update()

julia> Pkg.add("Express")

  3. Run

    julia> using Express

    and have fun!

  4. While using, please keep this Julia session alive. Restarting might recompile the package and cost some time.

If you want to install the latest in-development (probably buggy) version of Express, type

julia> using Pkg
julia> Pkg.update()    Updating registry at `~/.julia/registries/General`
    Updating git-repo `https://github.com/JuliaRegistries/General.git`
  No Changes to `~/work/Express.jl/Express.jl/docs/Project.toml`
  No Changes to `~/work/Express.jl/Express.jl/docs/Manifest.toml`
julia> pkg"add Express#master"     Cloning git-repo `https://github.com/MineralsCloud/Express.jl.git`
    Updating git-repo `https://github.com/MineralsCloud/Express.jl.git`
   Resolving package versions...
    Updating `~/work/Express.jl/Express.jl/docs/Project.toml`
  [b12df14e] ~ Express v0.9.1 `~/.julia/dev/Express` ⇒ v0.9.1 `https://github.com/MineralsCloud/Express.jl.git#master`
    Updating `~/work/Express.jl/Express.jl/docs/Manifest.toml`
  [b12df14e] ~ Express v0.9.1 `~/.julia/dev/Express` ⇒ v0.9.1 `https://github.com/MineralsCloud/Express.jl.git#master`
Precompiling project...
  ✓ Express
  1 dependency successfully precompiled in 8 seconds. 97 already precompiled.
  1 dependency precompiled but a different version is currently loaded. Restart julia to access the new version

in the second step above.

Update Express

Please watch our GitHub repository for new releases. Once we release a new version, you can update Express by typing

julia> using Pkg
julia> Pkg.update("Express")    Updating registry at `~/.julia/registries/General`
    Updating git-repo `https://github.com/JuliaRegistries/General.git`
    Updating git-repo `https://github.com/MineralsCloud/Express.jl.git`
  No Changes to `~/work/Express.jl/Express.jl/docs/Project.toml`
  No Changes to `~/work/Express.jl/Express.jl/docs/Manifest.toml`
julia> Pkg.gc()      Active manifest files: 3 found
      Active artifact files: 3 found
      Active scratchspaces: 2 found
     Deleted no artifacts, repos, packages or scratchspaces

in Julia REPL.

Uninstall and reinstall Express

  1. To uninstall, in a Julia session, run

    julia> using Pkg

julia> Pkg.rm("Express")

julia> Pkg.gc()

  2. Press ctrl+d to quit the current session. Start a new Julia session and reinstall Express.

Install a plugin for express

Plugins are packages that handle ab initio software such as Quantum ESPRESSO in the express framework. The current plugin is QuantumESPRESSOExpress. To install QuantumESPRESSOExpress.jl, run

julia> using Pkg
julia> Pkg.update()    Updating registry at `~/.julia/registries/General`
    Updating git-repo `https://github.com/JuliaRegistries/General.git`
    Updating git-repo `https://github.com/MineralsCloud/Express.jl.git`
  No Changes to `~/work/Express.jl/Express.jl/docs/Project.toml`
  No Changes to `~/work/Express.jl/Express.jl/docs/Manifest.toml`
julia> Pkg.add("QuantumESPRESSOExpress")   Resolving package versions...
   Installed Crystallography ────────────── v0.5.1
   Installed RelocatableFolders ─────────── v1.0.0
   Installed spglib_jll ─────────────────── v1.16.5+0
   Installed Roots ──────────────────────── v1.2.0
   Installed QuantumESPRESSOBase ────────── v0.7.7
   Installed EzXML ──────────────────────── v1.1.0
   Installed QuantumESPRESSOParser ──────── v0.3.10
   Installed Functors ───────────────────── v0.2.8
   Installed Spglib ─────────────────────── v0.5.3
   Installed QuantumESPRESSO ────────────── v0.8.0
   Installed Comonicon ──────────────────── v0.12.18
   Installed TypeTransform ──────────────── v0.1.3
   Installed Counters ───────────────────── v0.3.3
   Installed CrystallographyBase ────────── v0.5.2
   Installed DataFrames ─────────────────── v1.3.6
   Installed PackageCompiler ────────────── v2.1.1
   Installed Compat ─────────────────────── v3.46.0
   Installed PeriodicTable ──────────────── v1.1.3
   Installed Scratch ────────────────────── v1.1.1
   Installed UnifiedPseudopotentialFormat ─ v0.4.1
   Installed PyFortran90Namelists ───────── v0.1.0
   Installed Setfield ───────────────────── v1.1.1
   Installed MLStyle ────────────────────── v0.4.16
   Installed CoordinateTransformations ──── v0.6.2
   Installed Combinatorics ──────────────── v1.0.2
   Installed XML2_jll ───────────────────── v2.9.14+0
   Installed ReadableRegex ──────────────── v0.3.2
   Installed QuantumESPRESSOFormatter ───── v0.3.4
   Installed IterTools ──────────────────── v1.4.0
   Installed QuantumESPRESSOExpress ─────── v0.5.7
   Installed PrettyTables ───────────────── v1.3.1
   Installed LLVMOpenMP_jll ─────────────── v15.0.4+0
   Installed QuantumESPRESSOCommands ────── v0.6.3
   Installed Parameters ─────────────────── v0.12.3
   Installed AcuteML ────────────────────── v0.11.3
    Updating `~/work/Express.jl/Express.jl/docs/Project.toml`
⌃ [524a00d3] + QuantumESPRESSOExpress v0.5.7
    Updating `~/work/Express.jl/Express.jl/docs/Manifest.toml`
  [6b84a0a3] + AcuteML v0.11.3
  [861a8166] + Combinatorics v1.0.2
⌅ [863f3e99] + Comonicon v0.12.18
⌅ [34da2185] ↓ Compat v4.5.0 ⇒ v3.46.0
  [150eb455] + CoordinateTransformations v0.6.2
  [5a653867] + Counters v0.3.3
  [a8cc5b0e] + Crayons v4.1.1
  [3bff3928] + Crystallography v0.5.1
⌅ [93b1d1cd] + CrystallographyBase v0.5.2
⌃ [a93c6f00] + DataFrames v1.3.6
  [e2d170a0] + DataValueInterfaces v1.0.0
  [8f5d6c58] + EzXML v1.1.0
⌅ [d9f16b24] + Functors v0.2.8
  [41ab1584] + InvertedIndices v1.2.0
  [c8e1da08] + IterTools v1.4.0
  [82899510] + IteratorInterfaceExtensions v1.0.0
  [d8e11817] + MLStyle v0.4.16
  [9b87118b] + PackageCompiler v2.1.1
  [d96e819e] + Parameters v0.12.3
  [7b2266bf] + PeriodicTable v1.1.3
  [2dfb63ee] + PooledArrays v1.4.2
⌅ [08abe8d2] + PrettyTables v1.3.1
  [e44308e6] + PyFortran90Namelists v0.1.0
  [95228164] + QuantumESPRESSO v0.8.0
  [51b62caa] + QuantumESPRESSOBase v0.7.7
⌅ [f713baf6] + QuantumESPRESSOCommands v0.6.3
⌃ [524a00d3] + QuantumESPRESSOExpress v0.5.7
  [a4e7ca57] + QuantumESPRESSOFormatter v0.3.4
  [a780ab42] + QuantumESPRESSOParser v0.3.10
  [cbbcb084] + ReadableRegex v0.3.2
  [05181044] + RelocatableFolders v1.0.0
⌅ [f2b01f46] ↓ Roots v1.4.1 ⇒ v1.2.0
  [6c6a2e73] + Scratch v1.1.1
  [efcf1570] ↑ Setfield v0.8.2 ⇒ v1.1.1
⌅ [f761d5c5] + Spglib v0.5.3
  [3783bdb8] + TableTraits v1.0.1
  [bd369af6] + Tables v1.10.0
  [0fb2cfb0] + TypeTransform v0.1.3
  [8030dd95] + UnifiedPseudopotentialFormat v0.4.1
  [1d63c593] + LLVMOpenMP_jll v15.0.4+0
  [02c8fc9c] + XML2_jll v2.9.14+0
  [ac4a9f1e] + spglib_jll v1.16.5+0
  [8bb1440f] + DelimitedFiles
  [4af54fe1] + LazyArtifacts
        Info Packages marked with ⌃ and ⌅ have new versions available, but those with ⌅ are restricted by compatibility constraints from upgrading. To see why use `status --outdated -m`
    Building QuantumESPRESSOCommands → `~/.julia/scratchspaces/44cfe95a-1eb2-52ea-b672-e2afdf69b78f/eee07f6fe79b79c43121f5058c27ad4d079e7c51/build.log`
Precompiling project...
  ✓ TypeTransform
  ✓ IterTools
  ✓ Counters
  ✓ ReadableRegex
  ✓ Combinatorics
  ✓ Parameters
  ✓ Functors
  ✓ Roots
  ✓ Setfield
  ✓ LLVMOpenMP_jll
  ✓ PeriodicTable
  ✓ PyFortran90Namelists
  ✓ CoordinateTransformations
  ✓ PrettyTables
  ✓ XML2_jll
  ✓ spglib_jll
  ✓ FiniteDiff
  ✓ EzXML
  ✓ Spglib
  ✓ MLStyle
  ✓ AcuteML
  ✓ CrystallographyBase
  ✓ Crystallography
  ✓ NLSolversBase
  ✓ QuantumESPRESSOBase
  ✓ OptimBase
  ✓ DataFrames
  ✓ UnifiedPseudopotentialFormat
  ✓ LsqFit
  ✓ EquationsOfStateOfSolids
  ✓ QuantumESPRESSOParser
  ✓ QuantumESPRESSOFormatter
  ✓ QuantumESPRESSO
  ✓ Express
  ✗ QuantumESPRESSOExpress
  34 dependencies successfully precompiled in 79 seconds. 102 already precompiled.
  10 dependencies precompiled but different versions are currently loaded. Restart julia to access the new versions
  1 dependency errored. To see a full report either run `import Pkg; Pkg.precompile()` or load the package

in Julia REPL.

Install command-line tools

We provide a command-line interface of express for non-developers: ExpressCommands.jl. It installs an executable 'xps' that can execute code from configuration files provided by users. To install ExpressCommands, run

julia> using Pkg
julia> Pkg.update()    Updating registry at `~/.julia/registries/General`
    Updating git-repo `https://github.com/JuliaRegistries/General.git`
    Updating git-repo `https://github.com/MineralsCloud/Express.jl.git`
  No Changes to `~/work/Express.jl/Express.jl/docs/Project.toml`
  No Changes to `~/work/Express.jl/Express.jl/docs/Manifest.toml`
julia> Pkg.add("ExpressCommands")   Resolving package versions...
   Installed ExpressBase ──────────── v0.3.0
   Installed PrettyPrint ──────────── v0.2.0
   Installed EquationOfStateRecipes ─ v0.1.3
   Installed ExpressCommands ──────── v0.6.0
   Installed EasyJobsBase ─────────── v0.3.1
   Installed SimpleWorkflows ──────── v0.22.0
    Updating `~/work/Express.jl/Express.jl/docs/Project.toml`
  [0fa58581] + ExpressCommands v0.6.0
    Updating `~/work/Express.jl/Express.jl/docs/Manifest.toml`
⌅ [db8ca866] ↓ EasyJobsBase v0.4.0 ⇒ v0.3.1
  [8d49d7c9] + EquationOfStateRecipes v0.1.3
⌃ [6bf22d12] ↓ ExpressBase v0.4.0 ⇒ v0.3.0
  [0fa58581] + ExpressCommands v0.6.0
  [8162dcfd] + PrettyPrint v0.2.0
⌅ [6a97d125] ↓ SimpleWorkflows v0.23.0 ⇒ v0.22.0
        Info Packages marked with ⌃ and ⌅ have new versions available, but those with ⌅ are restricted by compatibility constraints from upgrading. To see why use `status --outdated -m`
    Building ExpressCommands → `~/.julia/scratchspaces/44cfe95a-1eb2-52ea-b672-e2afdf69b78f/eb40bc516b985a9c32377ce6f998247f435959e4/build.log`
ERROR: Error building `ExpressCommands`:
ERROR: LoadError: UndefVarError: VcOptim not defined
Stacktrace:
 [1] include(mod::Module, _path::String)
   @ Base ./Base.jl:419
 [2] include(x::String)
   @ ExpressCommands ~/.julia/packages/ExpressCommands/JFR1y/src/ExpressCommands.jl:1
 [3] top-level scope
   @ ~/.julia/packages/ExpressCommands/JFR1y/src/ExpressCommands.jl:92
 [4] include
   @ ./Base.jl:419 [inlined]
 [5] include_package_for_output(pkg::Base.PkgId, input::String, depot_path::Vector{String}, dl_load_path::Vector{String}, load_path::Vector{String}, concrete_deps::Vector{Pair{Base.PkgId, UInt64}}, source::String)
   @ Base ./loading.jl:1554
 [6] top-level scope
   @ stdin:1
in expression starting at /home/runner/.julia/packages/ExpressCommands/JFR1y/src/EOS.jl:1
in expression starting at /home/runner/.julia/packages/ExpressCommands/JFR1y/src/ExpressCommands.jl:1
in expression starting at stdin:1
ERROR: LoadError: Failed to precompile ExpressCommands [0fa58581-61d8-4f50-b6a2-2e2dd41ab979] to /home/runner/.julia/compiled/v1.8/ExpressCommands/jl_bjOGUs.
Stacktrace:
  [1] error(s::String)
    @ Base ./error.jl:35
  [2] compilecache(pkg::Base.PkgId, path::String, internal_stderr::IO, internal_stdout::IO, keep_loaded_modules::Bool)
    @ Base ./loading.jl:1707
  [3] compilecache
    @ ./loading.jl:1651 [inlined]
  [4] _require(pkg::Base.PkgId)
    @ Base ./loading.jl:1337
  [5] _require_prelocked(uuidkey::Base.PkgId)
    @ Base ./loading.jl:1200
  [6] macro expansion
    @ ./loading.jl:1180 [inlined]
  [7] macro expansion
    @ ./lock.jl:223 [inlined]
  [8] require(into::Module, mod::Symbol)
    @ Base ./loading.jl:1144
  [9] include(fname::String)
    @ Base.MainInclude ./client.jl:476
 [10] top-level scope
    @ none:5
in expression starting at /home/runner/.julia/packages/ExpressCommands/JFR1y/deps/build.jl:1

in Julia REPL.

After installation, the path to xps is $HOME/.julia/bin/xps by default. So please add $HOME/.julia/bin to your PATH environment variable.