Documentation

docs/make.jl

@@ -100,6 +100,8 @@ makedocs(
         ],
         "Usage" => Any[
             "guide/jobs.md",
+            "guide/inputs.md",
+            "guide/structure.md",
             "guide/pseudo.md",
         ],
         # "Examples" => EXAMPLES,

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

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

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("<job dir fuzzy>")` - 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"`.
+
+
+## 

docs/src/guide/structure.md

@@ -0,0 +1 @@
+# Structure

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

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