Merge pull request #219 from openmopac/release23

Final preparations for new major version

CITATION.cff

@@ -2,7 +2,7 @@ cff-version: 1.2.0
 message: "If you use this software for a scientific publication, please cite it as below."
 title: MOPAC
 type: software
-version: 22.1.1
+version: 23.0.0
 doi: 10.5281/zenodo.6511958
 date-released: 2024-01-29
 authors:

README.md

@@ -92,6 +92,30 @@ The main source for MOPAC documentation is presently its old [online user manual
 
 There is a [new documentation website](https://openmopac.github.io) under development, but it is not yet ready for general use.
 
+## Interfaces
+
+While MOPAC is primarily a self-contained command-line program whose behavior is specified by an input file, it also has other modes of
+operation, some of which only require the MOPAC shared library and not the executable.
+
+### MDI Engine
+
+MOPAC can be compiled to run as an MDI Engine through the [MolSSI Driver Interface Library](https://github.com/MolSSI-MDI/MDI_Library)
+by setting `-DMDI=ON` when running CMake. See [MDI documentation](https://molssi-mdi.github.io/MDI_Library) for more information.
+
+### Run from library
+
+MOPAC calculations can be run as a C-like library call to `run_mopac_from_input(path_to_file)` where `path_to_file` is a C string
+containing the system path to a MOPAC input file. Alternatively, a Fortran wrapper in the `include` directory allows this to be run as
+the subroutine `run_mopac_from_input_f(path_to_file)` in the `mopac_api_f` module where `path_to_file` is a Fortran string.
+
+### Diskless/stateless API
+
+A subset of MOPAC calculations can be run through a C-like Application Programming Interface (API) defined by the `mopac_api.h` C header file
+in the `include` directory, which also has a Fortran wrapper for convenience to Fortran software developers. Calculations run through this API
+do not use any input or output files or any other form of disk access, and the data structures of the API contain all relevant information
+regarding the input and output of the MOPAC calculation. The functionality and data exposed by this API is limited, and has been designed to
+align with the most common observed uses of MOPAC. Future expansion of this functionality and data will be considered upon request.
+
 ## Citation
 
 To cite the use of open-source MOPAC in scientific publications, see the `CITATION.cff` file in this repository.

include/README.md

@@ -0,0 +1,6 @@
+# MOPAC include files
+
+For OS-level ABI-compatibility, the MOPAC API is bound to C. The data structures and function prototypes of this C-like API
+are provided in the `mopac_api.h` header file. It is possible but inconvenient to use the C-like API in other Fortran software,
+so a Fortran convenience wrapper is also provided here. Because this wrapper needs to be compiled with the software using the
+MOPAC API, it is being provided with a permissive MIT license to allow broad use.

include/mopac_api.h

@@ -6,6 +6,38 @@
 #ifndef MOPAC_API_H
 #define MOPAC_API_H
 
+/*
+This C-like MOPAC API consists of 4 data structures - mopac_system, mopac_properties, mopac_state,
+and mozyme_state - and 6 main functions - mopac_scf, mopac_relax, mopac_vibe, mozyme_scf, mozyme_relax,
+and mozyme_vibe - that are organized by the solver they use - conventional MOPAC or reduced-scaling
+MOZYME - and the calculation they perform - a single self-consistent field (SCF) cycle, a geometric
+relaxation, or a vibrational calculation. For each function, mopac_system defines the atomistic
+system and various solver and model options and mopac_properties contains physical properties
+produced by the calculation. All data in mopac_system must be specified on input, while
+mopac_properties does not need to be initialized. Memory in mopac_properties is allocated by MOPAC,
+and it should be deallocated by using the destroy_mopac_properties function provided by the API.
+
+The mopac_state and mozyme_state structures contain information that specifies the electronic ground
+state. They must either be given a trivial initialization (mpack = 0 or numat = 0) to start a
+calculation from an atomic guess (MOPAC) or a Lewis-structure guess (MOZYME), or the output state of a
+previous calculation can be used to initialize the new calculation with the final state of the previous
+calculation, which is useful for running molecular dynamics simulations. The output states should be
+deallocated using functions provided by the API - destroy_mopac_state or destroy_mozyme_state. It is
+also possible to construct custom initial states, and the memory for these states must be allocated by
+using the create_mopac_state or create_mozyme_state API functions with the sizes of all arrays
+specified on input (mpack for MOPAC; numat, noccupied, nvirtual, icocc_dim, icvir_dim, cocc_dim, and
+cvir_dim for MOZYME).
+
+The API can also be used to run MOPAC calculations from an input file using the run_mopac_from_input
+function. This is equivalent to running MOPAC from the command line, except that MOPAC and all of its
+dependent math libraries can stay resident in memory between calculations when using API calls, which
+may improve performance in high-throughput settings for which disk access is not a bottleneck. In
+contrast, the other API functions run MOPAC without any disk access, which may be beneficial for
+high-throughput settings with file systems that perform poorly when large numbers of small files are
+being read and written simultaneously. If MOPAC encounters an error, then run_mopac_from_input returns
+1, otherwise it returns 0 for calculations that have completed successfully.
+*/
+
 /* data that defines the atomistic system and MOPAC job options */
 struct mopac_system {
   /* number of atoms */

src/molkst_C.F90

@@ -262,7 +262,7 @@ module molkst_C
                      !  Units         Text
   & git_hash*40 = 'unknown', & !  Git commit hash string
   & os*12 = 'unknown', &       !  Operating system name
-  & verson*20 = '22.*.*'       !  Version number for this copy of MOPAC
+  & verson*20 = '23.*.*'       !  Version number for this copy of MOPAC
                      !  Pattern      "xx.yy.zz(-pre)"
                      !  Description  major version, minor version, patch version, & pre-release tag
   character ::     &