From 881a1712d61d8bf1e2a6c1ebb5fc07182b8c2685 Mon Sep 17 00:00:00 2001 From: Unknown Date: Wed, 16 Jun 2021 20:10:49 +0200 Subject: [PATCH] Documentation --- docs/make.jl | 2 ++ docs/src/guide/advanced_tutorial.jl | 4 ++-- docs/src/guide/basic_tutorial.jl | 3 +-- docs/src/guide/jobs.md | 19 +++++++++++++++++++ docs/src/guide/structure.md | 1 + docs/src/index.md | 14 ++++++++------ src/jobAPI.jl | 8 ++++---- 7 files changed, 37 insertions(+), 14 deletions(-) create mode 100644 docs/src/guide/structure.md diff --git a/docs/make.jl b/docs/make.jl index 84dc9527..e7fd27d2 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -100,6 +100,8 @@ makedocs( ], "Usage" => Any[ "guide/jobs.md", + "guide/inputs.md", + "guide/structure.md", "guide/pseudo.md", ], # "Examples" => EXAMPLES, diff --git a/docs/src/guide/advanced_tutorial.jl b/docs/src/guide/advanced_tutorial.jl index 7fce55ed..a6ef2e30 100644 --- a/docs/src/guide/advanced_tutorial.jl +++ b/docs/src/guide/advanced_tutorial.jl @@ -6,8 +6,8 @@ # in it. using DFControl -tjob = DFJob(joinpath(@__DIR__, "../../src/assets/job/"))#hide -tjob2 = DFJob(joinpath(@__DIR__, "../../src/assets/job/Job2"))#hide +tjob = DFJob(joinpath(pathof(DFControl), "..","..","docs", "src", "assets", "job"))#hide +tjob2 = DFJob(joinpath(pathof(DFControl), "..","..", "docs", "src", "assets", "job", "Job2"))#hide try#hide job = DFJob(pwd()) catch#hide diff --git a/docs/src/guide/basic_tutorial.jl b/docs/src/guide/basic_tutorial.jl index 183689c9..014c5408 100644 --- a/docs/src/guide/basic_tutorial.jl +++ b/docs/src/guide/basic_tutorial.jl @@ -93,7 +93,7 @@ set_localdir!(job, pwd()); #hide try #hide submit(job) catch #hide -global job = DFJob(joinpath(@__DIR__, "../assets/job/"));#hide +global job = DFJob(joinpath(pathof(DFControl), "..","..", "docs", "src", "assets", "job"));#hide end #hide # We can access the bands through @@ -109,7 +109,6 @@ plot(bands, fermi=fermi) # Since more info (such as the structure) is available in the job, # plotting the job leads to a richer plot plot(job, -10, 1) -# where -10, 1 designates the energy window for the plot. # As can be seen in the [Advanced Usage](@ref), additional information # generated by additional calculations will be picked up by DFControl diff --git a/docs/src/guide/jobs.md b/docs/src/guide/jobs.md index 7b933982..2edc8d26 100644 --- a/docs/src/guide/jobs.md +++ b/docs/src/guide/jobs.md @@ -1 +1,20 @@ # Jobs + +## Basics +A `DFJob` is a collection of `DFInputs` that can be scheduled to run or not in a linear fashion in the job's `local_dir`, using the `Structure` associated with the job. + +There are three ways of constructing a job: +- `DFJob(name::String, structure::Structure, inputs::Vector{DFInput}, input_flags::Pair{Symbol, Any}...; local_dir::String = "")` - creates a new job +- `DFJob("/abs/path/to/job/dir")` - loads a job from the specified path +- `DFJob("")` - looks through the jobs known to `DFControl` (i.e. that were saved previously) and shows a menu allowing to select the desired one + +A job can be saved through `save(job)`, this will generate and save all the input files associated with each `DFInput` in the job, and subsequently save a `job.tt` submission script. `job.local_dir` can be inspected to get an idea of what these are. + +`submit` will first `save` the job and then attempt to run the job script, first using `sbatch job.tt` followed by `bash job.tt`. + +The job script preamble is defined by a `Vector{String}` in `job.header`, which will be pasted as lines before the execution lines. This can be useful for specifying `#SBATCH` options, `module load` directives, `export OMP_NUM_THREADS=1` environment variables, and similar. + +To change a string inside one of the `header` lines, `set_headerword!(job, "string123" => "string124")` can be used, where any string that matches `"string123"` will be replaced by `"string124"`. + + +## diff --git a/docs/src/guide/structure.md b/docs/src/guide/structure.md new file mode 100644 index 00000000..6ff2abe2 --- /dev/null +++ b/docs/src/guide/structure.md @@ -0,0 +1 @@ +# Structure diff --git a/docs/src/index.md b/docs/src/index.md index a420ad6e..55b3a058 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -5,15 +5,17 @@ codes encounter. It aids in the creation, execution, monitoring, management, and The core framework is code-agnostic, however, many features are so far only implemented for [Quantum-Espresso](https://quantum-espresso.org) and [Wannier90](http://www.wannier.org/). Rudimentary support for [ABINIT](https://www.abinit.org) and [ELK](https://elk.sourceforge.io) is also present. ## Philosophy -DFControl is structured to mimic the often adopted strategy of a linear submission script that specifies which input files -are ran with which codes producing which outputs. Everything revolves around the [`DFJob`](@ref Jobs) struct that holds a collection of [`DFInput`](@ref Inputs) which will be ran sequentially in the job's directory. A `DFJob` is therefore linked to a given directory. -Using the structure of the script that is created upon saving or submitting a job, a `DFJob` can be easily reloaded at a later stage to continue the investigation where left off. - DFControl is aimed to be user friendly first and foremost, with features being added as time progresses without changing this core value. On the other hand, a core requirement has always been that power users that know all the ins and outs of the codes that they run should be able to have all the control they want without incurring friction from the library. -DFControl therefore should never be a barrier to code functionality, just a tool to increase efficiency of its users. +DFControl therefore should never be a barrier to DFT code functionality, just a tool to increase efficiency of its users. + +In light of this DFControl is structured to mimic the often adopted strategy of a linear submission script that specifies which input files +are ran with which DFT codes producing which outputs. Everything revolves around the [`DFJob`](@ref Jobs) that holds a collection of [`DFInputs`](@ref Inputs) which will be ran sequentially in the job's directory, on the job's crystal [`Structure`](@ref). A `DFJob` is therefore identified with a specific directory. +Using the script that is created upon saving or submitting a job, a `DFJob` can be easily reloaded at a later stage to continue the investigation where left off. + ## Highlighted features -- Creation and submission of a simple self-consistent-field calculation starting from a structure Cif file in less than 10 lines of code (see the [Basic Tutorial](@ref)]). +- Creation and submission of a simple self-consistent-field calculation starting from a structure Cif file in less than 10 lines of code (see the [Basic Tutorial](@ref)]) +- Separation of `Structure` and `DFInput` so that the same `DFInputs` can be copied and used with a different `Structure` in a new job - Automatic validation and conversion of input flags - Tracking of jobs for ease of continuation at later times - Ease of input generation diff --git a/src/jobAPI.jl b/src/jobAPI.jl index 438d7bf2..663e2669 100644 --- a/src/jobAPI.jl +++ b/src/jobAPI.jl @@ -139,11 +139,11 @@ function set_localdir!(job::DFJob, dir::String; copy=false) if !isabspath(dir) dir = abspath(dir) end - if !ispath(dir) - mkpath(dir) - @info "$dir did not exist, it was created." - end if copy + if !ispath(dir) + mkpath(dir) + @info "$dir did not exist, it was created." + end cp(job, dir; temp=true) end job.local_dir = dir