Skip to content

Commit a900e9a

Browse files
vcanogilvcanogil
authored
Dev/atomsbase update (#35)
* update * update functions * update docs, add funcs and tests * fix doc typo * add commas * update typos
1 parent 88c2dc0 commit a900e9a

File tree

5 files changed

+289
-43
lines changed

5 files changed

+289
-43
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Extented Julia bindings to [cclib](https://github.com/cclib/cclib) library.
1515
- Further analysis of calculation outputs, such as population analysis.
1616

1717
- Integration with [AtomsBase.jl](https://github.com/JuliaMolSim/AtomsBase.jl) - an interface for atomic geometries.
18-
- By extension, provides interoperability with libraries that use AtomsBase.jl, such as [Molly.jl](https://github.com/JuliaMolSim/Molly.jl) and [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl).
18+
- By extension, provides interoperability with libraries that use AtomsBase.jl, such as [DFTK.jl](https://github.com/JuliaMolSim/DFTK.jl), [Molly.jl](https://github.com/JuliaMolSim/Molly.jl), and [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl).
1919
- Integration with [Fermi.jl](https://github.com/FermiQC/Fermi.jl) - quantum chemistry framework written in Julia.
2020

2121

‎docs/src/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
- Further analysis of calculation outputs, such as population analysis.
1010

1111
- Integration with [AtomsBase.jl](https://github.com/JuliaMolSim/AtomsBase.jl) - an interface for atomic geometries.
12-
- By extension, provides interoperability with libraries that use AtomsBase.jl, such as [Molly.jl](https://github.com/JuliaMolSim/Molly.jl) and [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl).
12+
- By extension, provides interoperability with libraries that use AtomsBase.jl, such as [DFTK.jl](https://github.com/JuliaMolSim/DFTK.jl), [Molly.jl](https://github.com/JuliaMolSim/Molly.jl), and [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl).
1313
- Integration with [Fermi.jl](https://github.com/FermiQC/Fermi.jl) - quantum chemistry framework written in Julia.
1414

1515
# How to install

‎docs/src/interop.md

Lines changed: 121 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,78 +2,158 @@
22

33
# AtomsBase.jl
44

5-
Cclib.jl allows loading atom information into [AtomsBase.jl](https://github.com/JuliaMolSim/AtomsBase.jl) objects using `get_atom_objects` function:
5+
Cclib.jl provides interoperability with [AtomsBase.jl](https://github.com/JuliaMolSim/AtomsBase.jl) by allowing to create AtomsBase systems.
6+
7+
The documentaiton below provides some essential functionality, such as creating and editing AtomsBase.jl systems.
8+
9+
For a detailed overview, or if you want to know how AtomsBase.jl operates behind the scenes, refer to its official documentation.
10+
11+
## Creating AtomsBase Systems
12+
We can load information contained in a Cclib.jl-supported file into a system by using the following functions:
13+
- `make_flexible_system` - for creating an AtomsBase `FlexibleSystem`
614

715
```Julia
816
# Input file can be found in the in the repo under "test" folder
917
julia> using Cclib
18+
julia> using Unitful
19+
julia> using AtomsBase
20+
julia> box = [[3.0, 0.0, 0.0], [0.0, 3.0, 0.0], [0.0, 0.0, 3.0]]u"Å"
21+
julia> boundary_conditions = [Periodic(), Periodic(), Periodic()]
22+
julia> system = make_flexible_system("./water_mp2.out", box, boundary_conditions)
23+
24+
FlexibleSystem(H₂O, periodic = TTT):
25+
bounding_box : [ 3 0 0;
26+
0 3 0;
27+
0 0 3]u"Å"
28+
29+
Atom(O, [ 0, 0, -0.0666785]u"Å")
30+
Atom(H, [ 0, -0.790649, 0.529118]u"Å")
31+
Atom(H, [ 0, 0.790649, 0.529118]u"Å")
32+
33+
.------.
34+
/| |
35+
O | |
36+
| | |
37+
|H.------.
38+
|H /
39+
*------*
40+
41+
```
42+
43+
- `make_isolated_system` - for creating an AtomsBase `isolated_system`
44+
45+
```Julia
46+
julia> using Cclib
47+
julia> system = make_isolated_system("./water_mp2.out")
48+
49+
FlexibleSystem(H₂O, infinite):
50+
Atom(O, [ 0, 0, -0.0666785]u"Å")
51+
Atom(H, [ 0, -0.790649, 0.529118]u"Å")
52+
Atom(H, [ 0, 0.790649, 0.529118]u"Å")
53+
```
54+
55+
- `get_atom_objects` - for getting an array of AtomsBase `Atom` objects in case you need more control.
56+
57+
```Julia
58+
julia> using Cclib
1059
julia> using AtomsBase
11-
julia> mol = ccread("./Trp_polar.fchk")
60+
julia> mol = ccread("./water_mp2.out")
1261
julia> atoms = get_atom_objects(mol)
1362
julia> atoms[1]
1463

15-
Atom(N, atomic_number = 7, atomic_mass = 14.007 u):
16-
position : [-0.069982688,0.33219872,0.28212832]u"Å"
64+
Atom(O, atomic_number = 8, atomic_mass = 15.999 u):
65+
position : [0,0,-0.066678532]u"Å"
1766
```
18-
19-
Like before, all the stored information for each atom is still accessible:
67+
## Accessing System Properties
68+
In case we need to look at what our system contains, we can use regular `keys` to see available system-level properties and `atomkeys` to see available atom-level properties
2069

2170
```Julia
22-
julia> keys(atoms[1])
71+
julia> using Cclib
72+
julia> using AtomsBase
73+
julia> system = make_isolated_system("./water_mp2.out")
74+
75+
julia> keys(system)
76+
(:bounding_box, :boundary_conditions)
77+
78+
julia> atomkeys(system)
2379
(:position, :velocity, :atomic_symbol, :atomic_number, :atomic_mass)
80+
81+
julia> bounding_box(system)
82+
[Inf a₀, 0.0 a₀, 0.0 a₀]
83+
[0.0 a₀, Inf a₀, 0.0 a₀]
84+
[0.0 a₀, 0.0 a₀, Inf a₀
85+
86+
julia> atomic_symbol(system)
87+
3-element Vector{Symbol}:
88+
:O
89+
:H
90+
:H
2491
```
92+
93+
## Updating and/or adding system properties
94+
We can also update and/or add system properties by using `update_system` function that accepts keywords arguments. Below is an example of adding data that was parsed using `ccread` to a system.
95+
```Julia
96+
julia> using Cclib
97+
julia> mol = ccread("./water_mp2.out")
98+
julia> system = make_isolated_system(mol);
99+
julia> system = update_system(system; nbasis=mol["nbasis"])
100+
julia> system[:nbasis]
101+
7
102+
```
103+
25104
# AtomsBase.jl-supported libraries
26105
27-
We can use data loaded with Cclib.jl to perform calculations using other libraries that use AtomsBase.jl, such as [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl)
106+
We can use data loaded with Cclib.jl to perform calculations using other libraries that use AtomsBase.jl, such as [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl) or [DFTK.jl](https://github.com/JuliaMolSim/DFTK.jl).
28107
29-
First, we load the data and define the system:
108+
Let's first load some dependencies and make a system
30109
```Julia
31110
julia> using Cclib
32111
julia> using AtomsBase
33112
julia> using Unitful
34113
julia> using UnitfulAtomic
35114
julia> using InteratomicPotentials
115+
julia> using DFTK
36116

37-
julia> atoms = get_atom_objects("./Trp_polar.fchk")
38-
julia> boundaryconditions = [Periodic(), Periodic(), Periodic()]
39-
julia> box = [[10.0, 0.0, 0.0], [0.0, 10.0, 0.0], [0.0, 0.0, 10.0]]u"Å"
40-
julia> system = FlexibleSystem(atoms, box, boundaryconditions)
41-
42-
FlexibleSystem(C₁₁H₁₂N₂O₂, periodic = TTT):
43-
bounding_box : [ 10 0 0;
44-
0 10 0;
45-
0 0 10]u"Å"
46-
47-
.------------------------.
48-
/| H |
49-
/ | |
50-
/ | |
51-
/ | H C C H |
52-
/ H |
53-
* C C C C H C H |
54-
| H | C HN H |
55-
| | |
56-
| | C C |
57-
| | C |
58-
| | O |
59-
| .----------------------H-.
60-
| / /
61-
| / /
62-
| H/O /
63-
| / H /
64-
|/ N/
65-
*------------------------*
117+
julia> box = [[3.0, 0.0, 0.0], [0.0, 3.0, 0.0], [0.0, 0.0, 3.0]]u"Å"
118+
julia> boundary_conditions = [Periodic(), Periodic(), Periodic()]
119+
julia> system = make_flexible_system("./water_mp2.out", box, boundary_conditions);
66120
```
121+
67122
We can now perform calculate various properties of the system:
123+
- using `InteratomicPotentials.jl`
68124
```Julia
69125
julia> ϵ = 1.0 * 1u"eV"
70126
julia> σ = 0.25 * 1u"Å"
71127
julia> rcutoff = 2.25 * 1u"Å"
72128
julia> lj = LennardJones(ϵ, σ, rcutoff, [:N, :C, :O, :H])
73-
julia> potential_energy(system, lj).
74-
-0.00039418327614247183 Eₕ
129+
julia> potential_energy(system, lj)
130+
-8.061904291397444e-5 Eₕ
75131
```
76-
Refer to InteratomicPotentials.jl documentation for more details.
132+
133+
- using `DFTK.jl`
134+
```Julia
135+
model = model_LDA(system; temperature=1e-3)
136+
basis = PlaneWaveBasis(model; Ecut=15, kgrid=(3, 3, 3))
137+
self_consistent_field(basis);
138+
n Energy log10(ΔE) log10(Δρ) Diag Δtime
139+
--- --------------- --------- --------- ---- ------
140+
1 -38.18166038243 0.81 5.2
141+
2 -45.38103756530 0.86 0.12 3.0 253ms
142+
3 -45.54220597356 -0.79 -0.74 3.0 273ms
143+
4 -45.55809718591 -1.80 -1.40 2.1 172ms
144+
5 -45.55889514812 -3.10 -2.14 1.0 159ms
145+
6 -45.55892123307 -4.58 -2.63 1.4 158ms
146+
7 -45.55892315420 -5.72 -3.26 1.8 211ms
147+
8 -45.55892314370 + -7.98 -3.57 1.2 113ms
148+
9 -45.55892319258 -7.31 -3.92 2.0 189ms
149+
10 -45.55892320440 -7.93 -4.94 1.1 142ms
150+
11 -45.55892320464 -9.63 -4.96 2.0 185ms
151+
12 -45.55892320468 -10.33 -5.44 1.0 134ms
152+
13 -45.55892320469 -11.36 -6.15 2.0 158ms
153+
```
154+
155+
For a full list of tools that support AtomsBase.jl, refer to its [official
156+
documentation](https://github.com/JuliaMolSim/AtomsBase.jl).
77157
78158
# Fermi.jl
79159

‎src/ab_integration.jl

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
# Functions for AtomsBase integration https://github.com/JuliaMolSim/AtomsBase.jl/tree/master
33
#
44
export get_atom_objects
5+
export make_flexible_system
6+
export make_isolated_system
7+
export update_system
58

69
"""
710
get_atom_objects(mol::Dict)
@@ -39,3 +42,150 @@ A list of AtomsBase atom objects
3942
function get_atom_objects(mol::String)
4043
return get_atom_objects(ccread(mol))
4144
end
45+
46+
"""
47+
make_flexible_system(mol::Dict)
48+
49+
Create an AtomsBase FlexibleSystem.
50+
51+
# Arguments
52+
- `mol::Dict`: Dictionary that was returned by `ccread` function
53+
- `args` will typically include `bounding_box` and `boundary_conditions`
54+
- `kwargs` passed will be stored as custom properties of the system
55+
56+
# Returns
57+
An AtomsBase FlexibleSystem
58+
59+
# Example
60+
```Julia
61+
julia> box = [[3.0, 0.0, 0.0], [0.0, 3.0, 0.0], [0.0, 0.0, 3.0]]u"Å"
62+
julia> boundary_conditions = [Periodic(), Periodic(), Periodic()]
63+
julia> myownproperty = "hello"
64+
julia> mol = make_flexible_system(
65+
ccread("water_mp2.out"),
66+
box,
67+
boundary_conditions
68+
myownproperty = myownproperty
69+
)
70+
FlexibleSystem(H₂O, periodic = TTT):
71+
bounding_box : [ 3 0 0;
72+
0 3 0;
73+
0 0 3]u"Å"
74+
myownproperty : hello
75+
76+
Atom(O, [ 0, 0, -0.0666785]u"Å")
77+
Atom(H, [ 0, -0.790649, 0.529118]u"Å")
78+
Atom(H, [ 0, 0.790649, 0.529118]u"Å")
79+
80+
.------.
81+
/| |
82+
O | |
83+
| | |
84+
|H.------.
85+
|H /
86+
*------*
87+
```
88+
"""
89+
function make_flexible_system(mol::Dict, args...; kwargs...)
90+
atoms = get_atom_objects(mol)
91+
return FlexibleSystem(atoms, args...; kwargs...)
92+
end
93+
94+
"""
95+
make_flexible_system(mol::String)
96+
97+
Create an AtomsBase FlexiblySystem.
98+
99+
# Arguments
100+
- `mol::String`: File supported by `ccread` function
101+
- `args` will typically include `bounding_box` and `boundary_conditions`
102+
- `kwargs` passed will be stored as custom properties of the system
103+
104+
# Returns
105+
An AtomsBase FlexibleSystem
106+
107+
# Example
108+
```Julia
109+
julia> box = [[3.0, 0.0, 0.0], [0.0, 3.0, 0.0], [0.0, 0.0, 3.0]]u"Å"
110+
julia> boundary_conditions = [Periodic(), Periodic(), Periodic()]
111+
julia> myownproperty = "hello"
112+
julia> mol = make_flexible_system(
113+
"water_mp2.out",
114+
box,
115+
boundary_conditions
116+
myownproperty = myownproperty
117+
)
118+
FlexibleSystem(H₂O, periodic = TTT):
119+
bounding_box : [ 3 0 0;
120+
0 3 0;
121+
0 0 3]u"Å"
122+
myownproperty : hello
123+
124+
Atom(O, [ 0, 0, -0.0666785]u"Å")
125+
Atom(H, [ 0, -0.790649, 0.529118]u"Å")
126+
Atom(H, [ 0, 0.790649, 0.529118]u"Å")
127+
128+
.------.
129+
/| |
130+
O | |
131+
| | |
132+
|H.------.
133+
|H /
134+
*------*
135+
```
136+
"""
137+
function make_flexible_system(mol::String, args...; kwargs...)
138+
return(make_flexible_system(ccread(mol), args...; kwargs...))
139+
end
140+
141+
"""
142+
make_isolated_system(mol::Dict)
143+
144+
Create an AtomsBase isolated_system.
145+
146+
# Arguments
147+
- `mol::Dict`: Dictionary that was returned by `ccread` function
148+
- `kwargs` passed will be stored as custom properties of the system
149+
150+
# Returns
151+
An AtomsBase isolated_system
152+
"""
153+
function make_isolated_system(mol::Dict; kwargs...)
154+
atoms = get_atom_objects(mol)
155+
return isolated_system(atoms; kwargs...)
156+
end
157+
158+
"""
159+
make_isolated_system(mol::String)
160+
161+
Create an AtomsBase isolated_system.
162+
163+
# Arguments
164+
- `mol::String`: File supported by `ccread` function
165+
- `kwargs` passed will be stored as custom properties of the system
166+
167+
# Returns
168+
An AtomsBase isolated_system
169+
"""
170+
function make_isolated_system(mol::String; kwargs...)
171+
return make_isolated_system(ccread(mol); kwargs...)
172+
end
173+
174+
"""
175+
update_system(system::AbstractSystem)
176+
177+
Update the system by changing and/or adding new properties,
178+
which are given as `kwargs`.
179+
Supported `kwargs` include `particles`, `atoms`, `bounding_box`,
180+
and `boundary_conditions`. User-specified `kwargs` are passed as
181+
custom properties.
182+
183+
# Arguments
184+
- `system::AbstractSystem`: An AtomsBase System
185+
186+
# Returns
187+
An updated AtomsBase system
188+
"""
189+
function update_system(system; kwargs...)
190+
return AbstractSystem(system; kwargs...)
191+
end

0 commit comments

Comments
 (0)