1 /* Ergo, version 3.8, a program for linear scaling electronic structure
2  * calculations.
3  * Copyright (C) 2019 Elias Rudberg, Emanuel H. Rubensson, Pawel Salek,
4  * and Anastasia Kruchinina.
5  *
6  * This program is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
18  *
19  * Primary academic reference:
20  * Ergo: An open-source program for linear-scaling electronic structure
21  * calculations,
22  * Elias Rudberg, Emanuel H. Rubensson, Pawel Salek, and Anastasia
23  * Kruchinina,
24  * SoftwareX 7, 107 (2018),
25  * <http://dx.doi.org/10.1016/j.softx.2018.03.005>
26  *
27  * For further information about Ergo, see <http://www.ergoscf.org>.
28  */
29 
30 /** @file scf.h
31 
32     @brief Code for classes containing various options related to
33     self-consistent field (SCF) calculations.
34 
35     @author: Elias Rudberg <em>responsible</em>.
36 */
37 
38 #ifndef SCF_HEADER
39 #define SCF_HEADER
40 
41 #include <string.h>
42 
43 #include "molecule.h"
44 #include "basisinfo.h"
45 #include "integrals_2el.h"
46 #include "matrix_typedefs.h"
47 
48 
49 namespace SCF {
50 
51 static const int DISTURB_ELEMENT_MAX_COUNT = 60;
52 
53 struct Options {
54   std::string calculation_identifier;
55   std::string method_and_basis_set;
56   Vector3D electric_field;
57   ergo_real electronic_temperature;
58   ergo_real sparse_threshold_for_S;
59   ergo_real sparse_threshold_for_Z;
60   ergo_real convergence_threshold;
61   ergo_real step_length_giveup;
62   ergo_real step_length_start;
63   ergo_real puri_eig_acc_factor_for_guess;
64   ergo_real purification_conv_limit;
65   int create_checkpoints;
66   std::string checkpoint_IDstr;
67   ergo_real purification_eigvalue_err_limit;
68   ergo_real purification_subspace_err_limit;
69   int purification_with_acceleration;
70   int use_new_stopping_criterion;
71   ergo_real gap_expected_lower_bound;
72   mat::normType purification_truncation_norm;
73   mat::normType purification_stop_crit_norm;
74   int cht_leavesSizeMax;
75   int cht_blocksize;
76   ergo_real subspace_factor_fock;
77   ergo_real subspace_factor_dens;
78   int use_artificial_subspace_disturbances;
79   int no_of_threads_for_V;
80   ergo_real box_size_for_V_and_T;
81   int purification_maxmul;
82   int purification_create_m_files;
83   int purification_ignore_failure;
84   int purification_use_rand_perturbation_for_alleigsint;
85   int use_dft;
86   int use_simple_starting_guess;
87   int use_diag_guess_from_file;
88   int write_diag_dens_to_file;
89   ergo_real starting_guess_disturbance;
90   int sg_disturb_specific_elements;
91   int disturbedElementIndexVector[DISTURB_ELEMENT_MAX_COUNT];
92   ergo_real shift_using_prev_density_matrix;
93   int skip_H_core;
94   int use_simple_dense_H_core;
95   int break_on_energy_increase;
96   int force_restricted;  /**< use a restricted determinant for open shell. */
97   int force_unrestricted; /**< use an unrestricted det. for closed shell. */
98   int spin_flip_atom_count;
99   int starting_guess_spin_diff;
100   int max_no_of_diis_matrices;
101   int max_restart_count;
102   int no_of_impr_req_for_diis;
103   int use_diis_always;
104   int do_f_thresh_verification;
105   int output_statistics_mfiles;
106   int no_of_careful_first_scf_steps;
107   int do_report_density_diff;
108   ergo_real error_maxabs_for_diis;
109   int min_number_of_iterations;
110   int max_number_of_iterations;
111   int output_density_at_every_step;
112   int output_expected_values_pos_operator;
113   int output_density_images;
114   int output_density_images_only;
115   int write_guess_density_only;
116   int compute_core_density;
117   int no_of_core_electrons;
118   ergo_real output_density_images_boxwidth;
119   int image_view_axis;
120   int save_final_potential;
121   int use_diagonalization;
122   int use_diag_on_error;
123   int use_diag_on_error_guess;
124   int store_all_eigenvalues_to_file;
125   int try_eigv_on_next_iteration_if_fail;
126   int puri_compute_eigv_in_each_iteration;
127   int run_shift_and_square_method_on_F;
128   int save_permuted_F_matrix_in_bin;
129   int write_overlap_matrix;
130   int save_full_matrices_for_matlab;
131   int analyze_result_after_scf;
132   int do_acc_scan_J;
133   int do_acc_scan_K;
134   int do_acc_scan_Vxc;
135   int scan_do_invcholfactor_transf;
136   int scan_no_of_steps;
137   ergo_real scan_start_thresh;
138   ergo_real scan_step_factor;
139   int create_mtx_file_S;
140   int create_mtx_file_H_core;
141   int create_mtx_files_F;
142   int create_mtx_files_D;
143   int create_mtx_files_dipole;
144   int create_mtx_files_S_and_quit;
145   int create_2el_integral_m_file;
146   int create_basis_func_coord_file;
147   int use_prev_vector_as_initial_guess;
148   int output_homo_and_lumo_eigenvectors;
149   int number_of_occupied_eigenvectors;
150   int number_of_unoccupied_eigenvectors;
151   int jump_over_X_iter_proj_method;
152   int go_back_X_iter_proj_method;
153   std::string eigenvectors_method;
154   std::string eigenvectors_iterative_method;
155   ergo_real eigensolver_accuracy;
156   int eigensolver_maxiter;
157   int output_mulliken_pop;
158   int compute_gradient_fixeddens;
159   int verify_gradient_fixeddens;
160 
161   /** Initializes all the fields to sane values. */
OptionsOptions162 Options() : calculation_identifier("N/A"),
163     method_and_basis_set("N/A"),
164     electric_field(0,0,0),
165     electronic_temperature(0),
166     sparse_threshold_for_S(1e-9),
167     sparse_threshold_for_Z(1e-8),
168     convergence_threshold(2e-7),
169     step_length_giveup(0.00005),
170     step_length_start(0.4),
171     puri_eig_acc_factor_for_guess(1e-2),
172     purification_conv_limit(0.1),
173     create_checkpoints(0),
174     checkpoint_IDstr(""),
175     purification_eigvalue_err_limit(1e-8),
176     purification_subspace_err_limit(1e-6),
177     purification_with_acceleration(0),
178     use_new_stopping_criterion(1),
179     gap_expected_lower_bound(0.05),
180     purification_truncation_norm(mat::mixedNorm),
181     purification_stop_crit_norm(mat::mixedNorm),
182     cht_leavesSizeMax(1024),
183     cht_blocksize(64),
184     subspace_factor_fock(0.1),
185     subspace_factor_dens(0.1),
186     use_artificial_subspace_disturbances(0),
187     no_of_threads_for_V(1),
188     box_size_for_V_and_T(6.5),
189     purification_maxmul(100),
190     purification_create_m_files(0),
191     purification_ignore_failure(0),
192     purification_use_rand_perturbation_for_alleigsint(0),
193     use_dft(0),
194     use_simple_starting_guess(0),
195     use_diag_guess_from_file(0),
196     write_diag_dens_to_file(0),
197     starting_guess_disturbance(0.0),
198     sg_disturb_specific_elements(0),
199     shift_using_prev_density_matrix(0.0),
200     skip_H_core(0),
201     use_simple_dense_H_core(0),
202     break_on_energy_increase(0),
203     force_restricted(0),
204     force_unrestricted(0),
205     spin_flip_atom_count(0),
206     starting_guess_spin_diff(0),
207     max_no_of_diis_matrices(10),
208     max_restart_count(2),
209     no_of_impr_req_for_diis(4),
210     use_diis_always(0),
211     do_f_thresh_verification(0),
212     output_statistics_mfiles(0),
213     no_of_careful_first_scf_steps(0),
214     do_report_density_diff(1),
215     error_maxabs_for_diis(0.5),
216     min_number_of_iterations(),
217     max_number_of_iterations(),
218     output_density_at_every_step(1),
219     output_expected_values_pos_operator(0),
220     output_density_images(0),
221     output_density_images_only(0),
222     write_guess_density_only(0),
223     compute_core_density(0),
224     no_of_core_electrons(0),
225     output_density_images_boxwidth(0.5),
226     image_view_axis(),
227     save_final_potential(0),
228     use_diagonalization(0),
229     use_diag_on_error(1),
230     use_diag_on_error_guess(1),
231     store_all_eigenvalues_to_file(0),
232     try_eigv_on_next_iteration_if_fail(0),
233     puri_compute_eigv_in_each_iteration(0),
234     run_shift_and_square_method_on_F(0),
235     save_permuted_F_matrix_in_bin(0),
236     write_overlap_matrix(0),
237     save_full_matrices_for_matlab(0),
238     analyze_result_after_scf(0),
239     do_acc_scan_J(0),
240     do_acc_scan_K(0),
241     do_acc_scan_Vxc(0),
242     scan_do_invcholfactor_transf(1),
243     scan_no_of_steps(16),
244     scan_start_thresh(1e-9),
245     scan_step_factor(template_blas_sqrt((ergo_real)10)),
246     create_mtx_file_S(0),
247     create_mtx_file_H_core(0),
248     create_mtx_files_F(0),
249     create_mtx_files_D(0),
250     create_mtx_files_dipole(0),
251     create_mtx_files_S_and_quit(0),
252     create_2el_integral_m_file(0),
253     create_basis_func_coord_file(0),
254     use_prev_vector_as_initial_guess(0),
255     output_homo_and_lumo_eigenvectors(0),
256     number_of_occupied_eigenvectors(1),
257     number_of_unoccupied_eigenvectors(1),
258     jump_over_X_iter_proj_method(3),
259     go_back_X_iter_proj_method(10),
260     eigenvectors_method("square"),
261     eigenvectors_iterative_method("lanczos"),
262     eigensolver_accuracy(1e-4*template_blas_sqrt(mat::getMachineEpsilon<ergo_real>())),
263     eigensolver_maxiter(200),
264     output_mulliken_pop(0),
265     compute_gradient_fixeddens(0),
266     verify_gradient_fixeddens(0)
267   {
268     memset(disturbedElementIndexVector, 0,
269            sizeof(disturbedElementIndexVector));
270   }
271 };
272 
273 /** An object respresenting the configuration of the matrix
274     library. All the thresholds and relevant parameters are collected
275     in one object for the purposes of the input processing. */
276 struct MatOptions {
277   mat::SizesAndBlocks size_block_info;
278   std::vector<int> permutationHML;
279   std::vector<int> inversePermutationHML;
280   ergo_real sparse_threshold; /**< threshold value for sparse matrix
281 				 truncation. */
282   ergo_real threshold_inch; /**< Truncation threshold in INCH function. */
283   int sparse_matrix_block_size;
284   int sparse_matrix_block_factor_3;
285   int sparse_matrix_block_factor_2;
286   int sparse_matrix_block_factor_1;
287   int threads;
288   int parallelLevel;
289   int no_of_buffers_per_allocator;
290   int use_allocator_manager;
291 
MatOptionsMatOptions292   MatOptions() :
293     sparse_threshold(1e-8),
294     threshold_inch(1e-10),
295     sparse_matrix_block_size(32),
296     sparse_matrix_block_factor_3(8),
297     sparse_matrix_block_factor_2(8),
298     sparse_matrix_block_factor_1(32),
299     threads(1),
300     parallelLevel(1),
301     /* FIXME: there should be a param to set no_of_buffers_per_allocator, for large calculations it needs to be larger, e.g. 10 x larger seems to give much better performance of matrix operations for large cases.
302        This is also connected to blocksize, maybe the best solution would be to have a param determining the number of MegaBytes per allocator or something like that.  */
303     no_of_buffers_per_allocator(20000),
304     use_allocator_manager(1)
305   {};
~MatOptionsMatOptions306   ~MatOptions() {
307   }
308   /** after the parameters are called, this routine is to be called
309       to figure out the basis set permutation. */
310   void prepare(const BasisInfoStruct& basisInfo);
311 };
312 
313 struct OutputOptions {
OutputOptionsOutputOptions314   OutputOptions()
315   {}
316 
317 };
318 
319 } /* end of SCF name space */
320 
321 
322 
323 #endif
324