Add ITensors.compile function (#436)

Project.toml

@@ -8,18 +8,20 @@ HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NDTensors = "23ae76d9-e61a-49c4-8f12-3f1a16adf9cf"
+PackageCompiler = "9b87118b-4619-50d2-8e1e-99f35a4d4d9d"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 
 [compat]
-julia = "1.4"
 HDF5 = "0.13.1"
 KrylovKit = "0.4.2"
 NDTensors = "0.1.11"
+PackageCompiler = "1.0.0"
 StaticArrays = "0.12.3"
 TimerOutputs = "0.5.5"
+julia = "1.4"
 
 [extras]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"

docs/src/AdvancedUsageGuide.md

@@ -502,8 +502,7 @@ If you plan to use ITensors.jl directly from the command line
 (i.e. not from the REPL), and the startup time is an issue,
 you can try compiling ITensors.jl using [PackageCompiler](https://julialang.github.io/PackageCompiler.jl/dev/).
 
-Before using PackageCompiler, when we first start using ITensors.jl
-we might see:
+Before using PackageCompiler to compile ITensors, when we first start using ITensors.jl we might see:
 ```julia
 julia> @time using ITensors
   3.845253 seconds (10.96 M allocations: 618.071 MiB, 3.95% gc time)
@@ -520,27 +519,21 @@ julia> @time svd(A, i');
 julia> @time svd(A, i');
   0.000177 seconds (450 allocations: 36.609 KiB)
 ```
-We would start by making a file `precompile_itensors.jl`:
-```julia
-using ITensors
-i = Index(2)
-A = randomITensor(i', i)
-svd(A, i')
+ITensors provides the command `ITensors.compile()` to create what is
+called a "custom system image", a custom version of Julia that
+includes a compiled version of ITensors (see the [PackageCompiler documentation](https://julialang.github.io/PackageCompiler.jl/dev/) for more details).
+Just run the command:
 ```
-We make the "custom system image", a custom version of Julia that
-includes a compiled version of ITensors.jl, with the commands:
-```
-julia> using PackageCompiler
-
-julia> create_sysimage(:ITensors, sysimage_path="sys_itensors.so", precompile_execution_file="precompile_itensors.jl")
-[ Info: PackageCompiler: creating system image object file, this might take a while...
+julia> ITensors.compile()
+[...]
 ```
-Then, in the same directory that contains the file `sys_itensors.so`,
-if we start julia with:
+By default, this will create the file `sys_itensors.so` in the directory
+`~/.julia/sysimages`.
+Then if we start julia with:
 ```
-$ julia --sysimage sys_itensors.so
+$ julia --sysimage ~/.julia/sysimages/sys_itensors.so
 ```
-then we see:
+then you should see something like:
 ```julia
 julia> @time using ITensors
   0.330587 seconds (977.61 k allocations: 45.807 MiB, 1.89% gc time)
@@ -559,10 +552,10 @@ julia> @time svd(A, i');
 ```
 which is much better. 
 
-There is a script to partially automate this process in the
-`packagecompiler/` directory of the ITensors.jl library.
-Additionally, we will investigate pre-packaging a compiled 
-version of ITensors.jl.
+Note that you will have to recompile ITensors with the command 
+`ITensors.compile()` any time that you update the version of ITensors
+in order to keep the system image updated. We hope to make this
+process more automated in the future.
 
 ## Multithreading Support
 

src/ITensors.jl

@@ -14,6 +14,7 @@ using HDF5
 using KrylovKit
 using LinearAlgebra
 using NDTensors
+using PackageCompiler
 using Printf
 using Random
 using StaticArrays
@@ -85,6 +86,12 @@ include("physics/site_types/tj.jl")
 include("physics/fermions.jl")
 include("physics/autompo.jl")
 
+#####################################
+# Package compilation
+#
+#
+include("packagecompile/compile.jl")
+
 #####################################
 # Developer tools, for internal
 # use only

src/packagecompile/compile.jl

@@ -0,0 +1,58 @@
+
+"""
+    ITensors.compile(; path = "~/.julia/sysimages",
+                       filename = "sys_itensors.so")
+
+Compile ITensors.jl with [PackageCompiler](https://julialang.github.io/PackageCompiler.jl/dev/).
+
+This will take some time, perhaps a few minutes. This will create the file `sys_itensors.so`, by default in the directory `~/.julia/sysimages/`. This is a version of Julia that is compiled with ITensors. After running this command, if you start Julia with:
+```
+~ julia --sysimage ~/.julia/sysimages/sys_itensors.so
+```
+and you should see the startup time and JIT compilation time are substantially improved when you are using ITensors.
+
+You can create an alias like:
+```
+~ alias julia_itensors="julia --sysimage ~/.julia/sysimages/sys_itensors.so"
+```
+(which you can put in your `~/.bashrc`, `~/.zshrc`, etc.). Then you can start Julia with a version of ITensors installed with the command:
+```
+~ julia_itensors
+```
+
+Note that if you update ITensors to a new version, for example with `Pkg.update("ITensors")`, you will need to run this command again to recompile the new version of ITensors.
+"""
+function compile(; path::AbstractString = joinpath(ENV["HOME"],
+                                                   ".julia",
+                                                   "sysimages"),
+                   filename::AbstractString = "sys_itensors.so")
+  if !isdir(path)
+    println("""The directory "$path" doesn't exist yet, creating it now.""")
+    println()
+    mkdir(path)
+  end
+  path_filename = joinpath(path, filename)
+  println("""Creating the system image containing the compiled version of ITensors at "$path_filename". This may take a few minutes.""")
+  create_sysimage(:ITensors;
+                  sysimage_path = path_filename,
+                  precompile_execution_file = "precompile_itensors.jl")
+  println("""
+
+          The system image containing the compiled version of ITensors is located at "$path_filename". This is a version of Julia that is compiled with ITensors.
+
+          You can now start Julia with:
+          ```
+          ~ julia --sysimage $path_filename
+          ```
+          and you should see that the startup times and JIT compilation times are substantially improved when you are using ITensors.
+
+          You can create an alias like:
+          ```
+          ~ alias julia_itensors="julia --sysimage $path_filename"
+          ```
+          (which you can put in your `~/.bashrc`, `~/.zshrc`, etc.). Then you can start Julia with a version of ITensors installed with the command:
+          ```
+          ~ julia_itensors
+          ```
+          """)
+end