diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6ed59e1..5bf11c9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -22,6 +22,12 @@ repos: args: [--autofix] exclude: tests/.*.yml +- repo: https://github.com/executablebooks/mdformat + rev: 0.7.17 + hooks: + - id: mdformat + args: [--wrap=120] + - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.6 hooks: diff --git a/CHANGELOG.md b/CHANGELOG.md index c180ca0..ef0cff7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,67 +3,100 @@ ## `v0.4.1` - 2023-08-16 ### Features -- `PyscfCalculation`: Store serialized model as output [[a072ea6]](https://github.com/microsoft/aiida-pyscf/commit/a072ea6171b2204f94af8a6772a57fced0a0cef5) -- `PyscfCalculation`: Add support for computing the Hessian [[05cefef]](https://github.com/microsoft/aiida-pyscf/commit/05cefefe5bac8ce59b59747c47f6e99d8f6abd37) +- `PyscfCalculation`: Store serialized model as output + [(a072ea6)](https://github.com/microsoft/aiida-pyscf/commit/a072ea6171b2204f94af8a6772a57fced0a0cef5) +- `PyscfCalculation`: Add support for computing the Hessian + [(05cefef)](https://github.com/microsoft/aiida-pyscf/commit/05cefefe5bac8ce59b59747c47f6e99d8f6abd37) ## `v0.4.0` - 2023-06-13 ### Features -- `PyscfCalculation`: Add support to compute charge density and MEP [[98445f4]](https://github.com/microsoft/aiida-pyscf/commit/98445f411a2a129d5e498299832fe4344b712551) -- `PyscfCalculation`: Add the `trajectory` output [[78de8e0]](https://github.com/microsoft/aiida-pyscf/commit/78de8e033a5f11b7253b2208cec12a3edf23bf8f) -- `PyscfBaseWorkChain`: Handle failed electronic convergence [[f138e71]](https://github.com/microsoft/aiida-pyscf/commit/f138e718b538460ae81f98cb5e7a038a907ad5c5) -- `PyscfCalculation`: Add the `checkpoint` input [[d596f3d]](https://github.com/microsoft/aiida-pyscf/commit/d596f3dfae659c065e30c78673f4d24c2220cc1d) -- `PyscfCalculation`: Add `checkpoint` file as output if not converged [[df15f83]](https://github.com/microsoft/aiida-pyscf/commit/df15f83553704470243bcc1da440557d9cc6155c) -- `PyscfCalculation`: Add molecular orbital details to `parameters` output [[40eb22d]](https://github.com/microsoft/aiida-pyscf/commit/40eb22dba21eadf7dfe22ee0b02bb5c06082bc4a) -- `PyscfCalculation`: Configure logging of geometric optimizer [[4308fca]](https://github.com/microsoft/aiida-pyscf/commit/4308fca2a1b6cb1e11baf273824a303a398e9504) -- `PyscfCalculation`: Add `ERROR_IONIC_CONVERGENCE_NOT_REACHED` exit code [[711b7f8]](https://github.com/microsoft/aiida-pyscf/commit/711b7f8b5def5091519d66d4d3f79cba473096ac) -- `PyscfBaseWorkChain`: Handle `ERROR_IONIC_CONVERGENCE_NOT_REACHED` [[7bb09f8]](https://github.com/microsoft/aiida-pyscf/commit/7bb09f8428c5ee753078a1c7822357d715f8cd17) -- `PyscfBaseWorkChain`: Handle `ERROR_SCHEDULER_OUT_OF_WALLTIME` [[3075bfa]](https://github.com/microsoft/aiida-pyscf/commit/3075bfa0a3ee8cbecda380f9747bd6a7a90daff5) -- `PyscfBaseWorkChain`: Handle `ERROR_SCHEDULER_NODE_FAILURE` [[6f494e7]](https://github.com/microsoft/aiida-pyscf/commit/6f494e761c1651f3c5efffaf564762ed0ddc4d0a) + +- `PyscfCalculation`: Add support to compute charge density and MEP + [(98445f4)](https://github.com/microsoft/aiida-pyscf/commit/98445f411a2a129d5e498299832fe4344b712551) +- `PyscfCalculation`: Add the `trajectory` output + [(78de8e0)](https://github.com/microsoft/aiida-pyscf/commit/78de8e033a5f11b7253b2208cec12a3edf23bf8f) +- `PyscfBaseWorkChain`: Handle failed electronic convergence + [(f138e71)](https://github.com/microsoft/aiida-pyscf/commit/f138e718b538460ae81f98cb5e7a038a907ad5c5) +- `PyscfCalculation`: Add the `checkpoint` input + [(d596f3d)](https://github.com/microsoft/aiida-pyscf/commit/d596f3dfae659c065e30c78673f4d24c2220cc1d) +- `PyscfCalculation`: Add `checkpoint` file as output if not converged + [(df15f83)](https://github.com/microsoft/aiida-pyscf/commit/df15f83553704470243bcc1da440557d9cc6155c) +- `PyscfCalculation`: Add molecular orbital details to `parameters` output + [(40eb22d)](https://github.com/microsoft/aiida-pyscf/commit/40eb22dba21eadf7dfe22ee0b02bb5c06082bc4a) +- `PyscfCalculation`: Configure logging of geometric optimizer + [(4308fca)](https://github.com/microsoft/aiida-pyscf/commit/4308fca2a1b6cb1e11baf273824a303a398e9504) +- `PyscfCalculation`: Add `ERROR_IONIC_CONVERGENCE_NOT_REACHED` exit code + [(711b7f8)](https://github.com/microsoft/aiida-pyscf/commit/711b7f8b5def5091519d66d4d3f79cba473096ac) +- `PyscfBaseWorkChain`: Handle `ERROR_IONIC_CONVERGENCE_NOT_REACHED` + [(7bb09f8)](https://github.com/microsoft/aiida-pyscf/commit/7bb09f8428c5ee753078a1c7822357d715f8cd17) +- `PyscfBaseWorkChain`: Handle `ERROR_SCHEDULER_OUT_OF_WALLTIME` + [(3075bfa)](https://github.com/microsoft/aiida-pyscf/commit/3075bfa0a3ee8cbecda380f9747bd6a7a90daff5) +- `PyscfBaseWorkChain`: Handle `ERROR_SCHEDULER_NODE_FAILURE` + [(6f494e7)](https://github.com/microsoft/aiida-pyscf/commit/6f494e761c1651f3c5efffaf564762ed0ddc4d0a) ### Changes -- `PyscfCalculation`: Change filename format of FCIDUMP files [[5cd9094]](https://github.com/microsoft/aiida-pyscf/commit/5cd9094973edb63fe4fa6096ad224dcad6f5464f) -- `PyscfCalculation`: Nest molecular orbitals in `cubegen` inputs/outputs [[68b204a]](https://github.com/microsoft/aiida-pyscf/commit/68b204a6102f51fea0c0334b16167273d9c0da3e) -- `PyscfCalculation`: Improve the layout of the `parameters` output [[0145f2c]](https://github.com/microsoft/aiida-pyscf/commit/0145f2cd87b43f0fb4bdae330c633af5cb0586cd) -- `PyscfCalculation`: Remove redirection of stderr to separate file [[90a7d07]](https://github.com/microsoft/aiida-pyscf/commit/90a7d07274fa97d9f43ff901fb3e198387b0f391) -- `PyscfCalculation`: Remove the default `mean_field.method` [[6d223ad]](https://github.com/microsoft/aiida-pyscf/commit/6d223ada1e12a0027a717e93d5bc550605bade7d) + +- `PyscfCalculation`: Change filename format of FCIDUMP files + [(5cd9094)](https://github.com/microsoft/aiida-pyscf/commit/5cd9094973edb63fe4fa6096ad224dcad6f5464f) +- `PyscfCalculation`: Nest molecular orbitals in `cubegen` inputs/outputs + [(68b204a)](https://github.com/microsoft/aiida-pyscf/commit/68b204a6102f51fea0c0334b16167273d9c0da3e) +- `PyscfCalculation`: Improve the layout of the `parameters` output + [(0145f2c)](https://github.com/microsoft/aiida-pyscf/commit/0145f2cd87b43f0fb4bdae330c633af5cb0586cd) +- `PyscfCalculation`: Remove redirection of stderr to separate file + [(90a7d07)](https://github.com/microsoft/aiida-pyscf/commit/90a7d07274fa97d9f43ff901fb3e198387b0f391) +- `PyscfCalculation`: Remove the default `mean_field.method` + [(6d223ad)](https://github.com/microsoft/aiida-pyscf/commit/6d223ada1e12a0027a717e93d5bc550605bade7d) ### Fixes -- `PyscfCalculation`: Fix bug in script if SCF does not converge [[03f03a0]](https://github.com/microsoft/aiida-pyscf/commit/03f03a002303ead896efe731bbd36240d4cbf3a8) -- `PyscfParser`: Fix incorrect units of parsed optimized coordinates [[cfb5e5b]](https://github.com/microsoft/aiida-pyscf/commit/cfb5e5b7ff20d5685df9a214c682c88c2d7c79dc) -- `PyscfParser`: Do not override scheduler exit code if set [[47dd59b]](https://github.com/microsoft/aiida-pyscf/commit/47dd59bf4d69c31d8ab777d62eafe7388a467506) + +- `PyscfCalculation`: Fix bug in script if SCF does not converge + [(03f03a0)](https://github.com/microsoft/aiida-pyscf/commit/03f03a002303ead896efe731bbd36240d4cbf3a8) +- `PyscfParser`: Fix incorrect units of parsed optimized coordinates + [(cfb5e5b)](https://github.com/microsoft/aiida-pyscf/commit/cfb5e5b7ff20d5685df9a214c682c88c2d7c79dc) +- `PyscfParser`: Do not override scheduler exit code if set + [(47dd59b)](https://github.com/microsoft/aiida-pyscf/commit/47dd59bf4d69c31d8ab777d62eafe7388a467506) ### Dependencies -- Dependencies: Update requirement `mypy==1.3.0` [[631cf5f]](https://github.com/microsoft/aiida-pyscf/commit/631cf5f545a7d51b3a3afaa8e3c21cd9a561c5f1) + +- Dependencies: Update requirement `mypy==1.3.0` + [(631cf5f)](https://github.com/microsoft/aiida-pyscf/commit/631cf5f545a7d51b3a3afaa8e3c21cd9a561c5f1) ### Devops -- `PyscfParser`: Add unit tests for parsing of FCIDUMP and CUBE files [[017757c]](https://github.com/microsoft/aiida-pyscf/commit/017757ceae3e99ca77d3ed4503c464350c16de6d) +- `PyscfParser`: Add unit tests for parsing of FCIDUMP and CUBE files + [(017757c)](https://github.com/microsoft/aiida-pyscf/commit/017757ceae3e99ca77d3ed4503c464350c16de6d) ## `v0.3.0` - 2023-04-03 ### Features -- `PyscfCalculation`: Add support for writing FCIDUMP files [[#17]](https://github.com/microsoft/aiida-pyscf/pull/17) -- `PyscfCalculation`: Add support for computing orbital cube files [[#20]](https://github.com/microsoft/aiida-pyscf/pull/20) -- `PyscfCalculation`: Ensure strings are rendered with quotes in templates [[#19]](https://github.com/microsoft/aiida-pyscf/pull/19) -- `PyscfCalculation`: Add validation for `optimizer` parameters [[#16]](https://github.com/microsoft/aiida-pyscf/pull/16) -- `PyscfCalculation`: Refactor to simplify subclassing [[#22]](https://github.com/microsoft/aiida-pyscf/pull/22) + +- `PyscfCalculation`: Add support for writing FCIDUMP files [(#17)](https://github.com/microsoft/aiida-pyscf/pull/17) +- `PyscfCalculation`: Add support for computing orbital cube files + [(#20)](https://github.com/microsoft/aiida-pyscf/pull/20) +- `PyscfCalculation`: Ensure strings are rendered with quotes in templates + [(#19)](https://github.com/microsoft/aiida-pyscf/pull/19) +- `PyscfCalculation`: Add validation for `optimizer` parameters + [(#16)](https://github.com/microsoft/aiida-pyscf/pull/16) +- `PyscfCalculation`: Refactor to simplify subclassing [(#22)](https://github.com/microsoft/aiida-pyscf/pull/22) ### Documentation -- Docs: Add setup and run instructions to `README.md` [[#18]](https://github.com/microsoft/aiida-pyscf/pull/18) -- Docs: Add badges and table of contents to `README.md` [[#23]](https://github.com/microsoft/aiida-pyscf/pull/23) + +- Docs: Add setup and run instructions to `README.md` [(#18)](https://github.com/microsoft/aiida-pyscf/pull/18) +- Docs: Add badges and table of contents to `README.md` [(#23)](https://github.com/microsoft/aiida-pyscf/pull/23) ### Devops -- CI: Update `pip` and install `wheel` [[#21]](https://github.com/microsoft/aiida-pyscf/pull/21) +- CI: Update `pip` and install `wheel` [(#21)](https://github.com/microsoft/aiida-pyscf/pull/21) ## `v0.2.0` - 2023-03-28 ### Improvements -- `PyscfCalculation`: Use `PrefixLoader` for template environment loader [[#12]](https://github.com/microsoft/aiida-pyscf/pull/12) -- `PyscfCalculation`: Improve white-space in rendered script [[#13]](https://github.com/microsoft/aiida-pyscf/pull/13) +- `PyscfCalculation`: Use `PrefixLoader` for template environment loader + [(#12)](https://github.com/microsoft/aiida-pyscf/pull/12) +- `PyscfCalculation`: Improve white-space in rendered script [(#13)](https://github.com/microsoft/aiida-pyscf/pull/13) ## `v0.1.0` - 2023-03-27 diff --git a/README.md b/README.md index 5610be1..89a98da 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,48 @@ # `aiida-pyscf` + [![PyPI version](https://badge.fury.io/py/aiida-pyscf.svg)](https://badge.fury.io/py/aiida-pyscf) [![PyPI pyversions](https://img.shields.io/pypi/pyversions/aiida-pyscf.svg)](https://pypi.python.org/pypi/aiida-pyscf) [![CI](https://github.com/microsoft/aiida-pyscf/workflows/ci/badge.svg)](https://github.com/microsoft/aiida-pyscf/actions/workflows/ci.yml) -An [AiiDA](https://www.aiida.net) plugin for the [Python-based Simulations of Chemistry Framework (PySCF)](https://pyscf.org/index.html). +An [AiiDA](https://www.aiida.net) plugin for the +[Python-based Simulations of Chemistry Framework (PySCF)](https://pyscf.org/index.html). 1. [Installation](#installation) -2. [Requirements](#requirements) -3. [Setup](#setup) -4. [Examples](#examples) - * [Mean-field calculation](#mean-field-calculation) - * [Customizing the structure](#customizing-the-structure) - * [Optimizing geometry](#optimizing-geometry) - * [Writing Hamiltonian to FCIDUMP files](#writing-hamiltonian-to-fcidump-files) - * [Writing orbitals to CUBE files](#writing-orbitals-to-cube-files) - * [Restarting unconverged calculations](#restarting-unconverged-calculations) - * [Automatic error recovery](#automatic-error-recovery) - * [Pickled model](#pickled-model) +1. [Requirements](#requirements) +1. [Setup](#setup) +1. [Examples](#examples) + - [Mean-field calculation](#mean-field-calculation) + - [Customizing the structure](#customizing-the-structure) + - [Optimizing geometry](#optimizing-geometry) + - [Writing Hamiltonian to FCIDUMP files](#writing-hamiltonian-to-fcidump-files) + - [Writing orbitals to CUBE files](#writing-orbitals-to-cube-files) + - [Restarting unconverged calculations](#restarting-unconverged-calculations) + - [Automatic error recovery](#automatic-error-recovery) + - [Pickled model](#pickled-model) ## Installation The recommended method of installation is through [`pip`](https://pip.pypa.io/en/stable/): - pip install aiida-pyscf +``` +pip install aiida-pyscf +``` ## Requirements -To use `aiida-pyscf` a configured AiiDA profile is required. -Please refer to the [documentation of `aiida-core`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html) for detailed instructions. +To use `aiida-pyscf` a configured AiiDA profile is required. Please refer to the +[documentation of `aiida-core`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html) for +detailed instructions. ## Setup -To run a PySCF calculation through AiiDA using the `aiida-pyscf` plugin, the computer needs to be configured where PySCF should be run. -Please refer to the [documentation of `aiida-core`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#computer-setup) for detailed instructions. +To run a PySCF calculation through AiiDA using the `aiida-pyscf` plugin, the computer needs to be configured where PySCF +should be run. Please refer to the +[documentation of `aiida-core`](https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#computer-setup) +for detailed instructions. + +Then the PySCF code needs to be configured. The following YAML configuration file can be taken as a starting point: -Then the PySCF code needs to be configured. -The following YAML configuration file can be taken as a starting point: ```yaml label: pyscf description: PySCF @@ -48,19 +55,23 @@ prepend_text: '' append_text: '' ``` -Write the contents to a file named `pyscf.yml`, making sure to update the value of `computer` to the label of the computer configured in the previous step. -To configure the code, execute: + +Write the contents to a file named `pyscf.yml`, making sure to update the value of `computer` to the label of the +computer configured in the previous step. To configure the code, execute: + ```bash verdi code create core.code.installed --config pyscf.yml -n ``` + This should now have created the code with the label `pyscf` that will be used in the following examples. ## Examples ### Mean-field calculation -The default calculation is to perform a mean-field calculation. -At a very minimum, the structure and the mean-field method should be defined: +The default calculation is to perform a mean-field calculation. At a very minimum, the structure and the mean-field +method should be defined: + ```python from ase.build import molecule from aiida.engine import run @@ -71,9 +82,12 @@ builder.structure = StructureData(ase=molecule('H2O')) builder.parameters = Dict({'mean_field': {'method': 'RHF'}}) results, node = run.get_node(builder) ``` + This runs a Hartree-Fock calculation on the geometry of a water molecule. -The main results are stored in the `parameters` output, which by default contain the computed `total_energy` and `forces`, details on the molecular orbitals, as well as some timing information: +The main results are stored in the `parameters` output, which by default contain the computed `total_energy` and +`forces`, details on the molecular orbitals, as well as some timing information: + ```python print(results['parameters'].get_dict()) { @@ -116,8 +130,10 @@ print(results['parameters'].get_dict()) ### Customizing the structure -The geometry of the structure is fully defined through the `structure` input, which is provided by a `StructureData` node. -Any other properties, e.g., the charge and what basis set to use, can be specified through the `structure` dictionary in the `parameters` input: +The geometry of the structure is fully defined through the `structure` input, which is provided by a `StructureData` +node. Any other properties, e.g., the charge and what basis set to use, can be specified through the `structure` +dictionary in the `parameters` input: + ```python from ase.build import molecule from aiida.engine import run @@ -134,13 +150,18 @@ builder.parameters = Dict({ }) results, node = run.get_node(builder) ``` -Any attribute of the [`pyscf.gto.Mole` class](https://pyscf.org/user/gto.html) which is used to define the structure can be set through the `structure` dictionary, with the exception of the `atom` and `unit` attributes, which are set automatically by the plugin based on the `StructureData` input. + +Any attribute of the [`pyscf.gto.Mole` class](https://pyscf.org/user/gto.html) which is used to define the structure can +be set through the `structure` dictionary, with the exception of the `atom` and `unit` attributes, which are set +automatically by the plugin based on the `StructureData` input. ### Optimizing geometry -The geometry can be optimized by specifying the `optimizer` dictionary in the input `parameters`. -The `solver` has to be specified, and currently the solvers `geometric` and `berny` are supported. -The `convergence_parameters` accepts the parameters for the selected solver (see [PySCF documentation](https://pyscf.org/user/geomopt.html?highlight=geometry+optimization) for details): +The geometry can be optimized by specifying the `optimizer` dictionary in the input `parameters`. The `solver` has to be +specified, and currently the solvers `geometric` and `berny` are supported. The `convergence_parameters` accepts the +parameters for the selected solver (see +[PySCF documentation](https://pyscf.org/user/geomopt.html?highlight=geometry+optimization) for details): + ```python from ase.build import molecule from aiida.engine import run @@ -163,9 +184,11 @@ builder.parameters = Dict({ }) results, node = run.get_node(builder) ``` -The optimized structure is returned in the form of a `StructureData` under the `structure` output label. -The structure and energy of each frame in the geometry optimization trajectory, are stored in the form of a `TrajectoryData` under the `trajectory` output label. -The total energies can be retrieved as follows: + +The optimized structure is returned in the form of a `StructureData` under the `structure` output label. The structure +and energy of each frame in the geometry optimization trajectory, are stored in the form of a `TrajectoryData` under the +`trajectory` output label. The total energies can be retrieved as follows: + ```python results['trajectory'].get_array('energies') ``` @@ -173,6 +196,7 @@ results['trajectory'].get_array('energies') ### Computing the Hessian In order to compute the Hessian, specify an empty dictionary for the `hessian` key in the `parameters` input: + ```python from ase.build import molecule from aiida.engine import run @@ -186,12 +210,15 @@ builder.parameters = Dict({ }) results, node = run.get_node(builder) ``` -The computed Hessian will be attached as an `ArrayData` node with the link label `hessian`. -Use `node.outputs.hessian.get_array('hessian')` to retrieve the computed Hessian as a numpy array for further processing. + +The computed Hessian will be attached as an `ArrayData` node with the link label `hessian`. Use +`node.outputs.hessian.get_array('hessian')` to retrieve the computed Hessian as a numpy array for further processing. ### Writing Hamiltonian to FCIDUMP files -To instruct the calculation to dump a representation of the Hamiltonian to FCIDUMP files, add the `fcidump` dictionary to the `parameters` input: +To instruct the calculation to dump a representation of the Hamiltonian to FCIDUMP files, add the `fcidump` dictionary +to the `parameters` input: + ```python from ase.build import molecule from aiida.engine import run @@ -208,11 +235,14 @@ builder.parameters = Dict({ }) results, node = run.get_node(builder) ``` -The `active_spaces` and `occupations` keys are requires and each take a list of list of integers. -For each element in the list, a FCIDUMP file is generated for the corresponding active spaces and the occupations of the orbitals. -The shape of the `active_spaces` and `occupations` array has to be identical. -The generated FCIDUMP files are attached as `SinglefileData` output nodes in the `fcidump` namespace, where the label is determined by the index of the corresponding active space in the list: +The `active_spaces` and `occupations` keys are requires and each take a list of list of integers. For each element in +the list, a FCIDUMP file is generated for the corresponding active spaces and the occupations of the orbitals. The shape +of the `active_spaces` and `occupations` array has to be identical. + +The generated FCIDUMP files are attached as `SinglefileData` output nodes in the `fcidump` namespace, where the label is +determined by the index of the corresponding active space in the list: + ```python print(results['fcidump']['active_space_0'].get_content()) &FCI NORB= 4,NELEC= 4,MS2=0, @@ -229,14 +259,16 @@ print(results['fcidump']['active_space_0'].get_content()) ### Generating CUBE files -The `pyscf.tools.cubegen` module provides functions to compute various properties of the system and write them as CUBE files. -The `PyscfCalculation` plugin currently supports computing the following: +The `pyscf.tools.cubegen` module provides functions to compute various properties of the system and write them as CUBE +files. The `PyscfCalculation` plugin currently supports computing the following: + +- molecular orbitals +- charge density +- molecular electrostatic potential -* molecular orbitals -* charge density -* molecular electrostatic potential +To instruct the calculation to dump a representation of any of these quantities to CUBE files, add the `cubegen` +dictionary to the `parameters` input: -To instruct the calculation to dump a representation of any of these quantities to CUBE files, add the `cubegen` dictionary to the `parameters` input: ```python from ase.build import molecule from aiida.engine import run @@ -269,13 +301,19 @@ builder.parameters = Dict({ }) results, node = run.get_node(builder) ``` -The `indices` key has to be specified for the `orbitals` subdictionary and takes a list of integers, indicating the indices of the molecular orbitals that should be written to file. -Additional parameters can be provided in the `parameters` subdictionary (see the [PySCF documentation](https://pyscf.org/pyscf_api_docs/pyscf.tools.html?highlight=fcidump#module-pyscf.tools.cubegen) for details). -The `parameters` subdictionaries for the `density` and `mep` dictionaries are optional. -To compute the charge density and molecular electrostatic potential, the and empty dictionary for the `density` and `mep` keys, respectively, is sufficient. -The generated CUBE files are attached as `SinglefileData` output nodes in the `cubegen` namespace, with the `orbitals`, `density` and `mep` subnamespaces. -For the `orbitals` subnamespace, the label is determined by the corresponding molecular orbital index: +The `indices` key has to be specified for the `orbitals` subdictionary and takes a list of integers, indicating the +indices of the molecular orbitals that should be written to file. Additional parameters can be provided in the +`parameters` subdictionary (see the +[PySCF documentation](https://pyscf.org/pyscf_api_docs/pyscf.tools.html?highlight=fcidump#module-pyscf.tools.cubegen) +for details). The `parameters` subdictionaries for the `density` and `mep` dictionaries are optional. To compute the +charge density and molecular electrostatic potential, the and empty dictionary for the `density` and `mep` keys, +respectively, is sufficient. + +The generated CUBE files are attached as `SinglefileData` output nodes in the `cubegen` namespace, with the `orbitals`, +`density` and `mep` subnamespaces. For the `orbitals` subnamespace, the label is determined by the corresponding +molecular orbital index: + ```python print(results['cubegen']['orbitals']['mo_5'].get_content()) Orbital value in real space (1/Bohr^3) @@ -291,36 +329,46 @@ PySCF Version: 2.1.1 Date: Sun Apr 2 15:59:19 2023 ... ``` -> **Warning** -> PySCF is known to fail when computing the MEP with DHF, DKS, GHF and GKS references. +> **Warning** PySCF is known to fail when computing the MEP with DHF, DKS, GHF and GKS references. ### Restarting unconverged calculations -The plugin will automatically instruct PySCF to write a checkpoint file. -If the calculation did not converge, it will finish with exit status `410` and the checkpoint file is attached as a `SinglefileData` as the `checkpoint` output node. +The plugin will automatically instruct PySCF to write a checkpoint file. If the calculation did not converge, it will +finish with exit status `410` and the checkpoint file is attached as a `SinglefileData` as the `checkpoint` output node. This node can then be passed as input to a new calculation to restart from the checkpoint: + ```python failed_calculation = load_node(IDENTIFIER) builder = failed_calculation.get_builder_restart() builder.checkpoint = failed_calculation.outputs.checkpoint submit(builder) ``` -The plugin will write the checkpoint file of the failed calculation to the working directory such that PySCF can start of from there. + +The plugin will write the checkpoint file of the failed calculation to the working directory such that PySCF can start +of from there. ### Post-processing -The `PyscfCalculation` plugin does not support all PySCF functionality; it aims to support most functionality that is computationally intensive, as in this case it is important to be able to offload these calculations as a calcjob on a remote compute resource. -Most post-processing utilities are computationally inexpensive, and since the API is in Python, they can be called directly in AiiDA workflows as `calcfunction`s. -Many PySCF utilities require the _model_ of the system as an argument, where model is the main object used in PySCF, i.e. the object assigned to the `mean_field` variable in the following: +The `PyscfCalculation` plugin does not support all PySCF functionality; it aims to support most functionality that is +computationally intensive, as in this case it is important to be able to offload these calculations as a calcjob on a +remote compute resource. Most post-processing utilities are computationally inexpensive, and since the API is in Python, +they can be called directly in AiiDA workflows as `calcfunction`s. Many PySCF utilities require the _model_ of the +system as an argument, where model is the main object used in PySCF, i.e. the object assigned to the `mean_field` +variable in the following: + ```python from pyscf import scf mean_field = scf.RHF(..) mean_field.kernel() ``` -The `kernel` method is often computationally expensive, but its results (stored on the model object) are lost when the `PyscfCalculation` finishes as the Python interpreter of the calcjob shuts down and so the `mean_field` object no longer exists. -This would force post-processing code to reconstruct the model from scratch and rerun the expensive kernel. -Therefore, the `PyscfCalculation` serializes the PySCF model that was computed and stores it as a `PickledData` output node with the link label `model` in the provenance graph. -This allows recreating the model in another Python interpreter and have it ready to be used for post-processing: + +The `kernel` method is often computationally expensive, but its results (stored on the model object) are lost when the +`PyscfCalculation` finishes as the Python interpreter of the calcjob shuts down and so the `mean_field` object no longer +exists. This would force post-processing code to reconstruct the model from scratch and rerun the expensive kernel. +Therefore, the `PyscfCalculation` serializes the PySCF model that was computed and stores it as a `PickledData` output +node with the link label `model` in the provenance graph. This allows recreating the model in another Python interpreter +and have it ready to be used for post-processing: + ```python from pyscf.hessian import thermo node = load_node() # Load the completed `PyscfCalculation` @@ -329,14 +377,15 @@ hessian = mean_field.Hessian().kernel() freq_info = thermo.harmonic_analysis(mean_field.mol, hessian) ``` - ### Automatic error recovery -There are a variety of reasons why a PySCF calculation may not finish with the intended result. -Examples are the self-consistent field cycle not converging or the job getting killed by the scheduler because it ran out of the requested walltime. -The `PyscfBaseWorkChain` is designed to try and automatically recover from these kinds of errors whenever it can potentially be handled. -It is a simple wrapper around the `PyscfCalculation` plugin that automatically restarts a new `PyscfCalculation` if the previous iterations failed. -Launching a `PyscfBaseWorkChain` is almost identical to launching a `PyscfCalculation` directly; the inputs just have to be "nested" inside the `pyscf` namespace: +There are a variety of reasons why a PySCF calculation may not finish with the intended result. Examples are the +self-consistent field cycle not converging or the job getting killed by the scheduler because it ran out of the +requested walltime. The `PyscfBaseWorkChain` is designed to try and automatically recover from these kinds of errors +whenever it can potentially be handled. It is a simple wrapper around the `PyscfCalculation` plugin that automatically +restarts a new `PyscfCalculation` if the previous iterations failed. Launching a `PyscfBaseWorkChain` is almost +identical to launching a `PyscfCalculation` directly; the inputs just have to be "nested" inside the `pyscf` namespace: + ```python from aiida.engine import run from aiida.orm import Dict, StructureData, load_code, load_node @@ -354,9 +403,12 @@ builder.pyscf.parameters = Dict({ }) results, node = run.get_node(builder) ``` -In this example, we purposefully set the maximum number of iterations in the self-consistent field cycle to 3 (`'mean_field.max_cycle' = 3`), which will cause the first iteration to fail to reach convergence. -The `PyscfBaseWorkChain` detects the error, indicated by exit status `410` on the `PyscfCalculation`, and automatically restarts the calculation from the saved checkpoint. -After three iterations, the calculation converges: + +In this example, we purposefully set the maximum number of iterations in the self-consistent field cycle to 3 +(`'mean_field.max_cycle' = 3`), which will cause the first iteration to fail to reach convergence. The +`PyscfBaseWorkChain` detects the error, indicated by exit status `410` on the `PyscfCalculation`, and automatically +restarts the calculation from the saved checkpoint. After three iterations, the calculation converges: + ```console $ verdi process status IDENTIFIER PyscfBaseWorkChain<30126> Finished [0] [2:results] @@ -364,29 +416,35 @@ PyscfBaseWorkChain<30126> Finished [0] [2:results] ├── PyscfCalculation<30132> Finished [410] └── PyscfCalculation<30137> Finished [0] ``` -The following error modes are currently handled by the `PyscfBaseWorkChain`: -* `120`: Out of walltime: The calculation will be restarted from the last checkpoint if available, otherwise the work chain is aborted -* `140`: Node failure: The calculation will be restarted from the last checkpoint -* `410`: Electronic convergence not achieved: The calculation will be restarted from the last checkpoint -* `500`: Ionic convergence not achieved: The geometry optmizization did not converge, calculation will be restarted from the last checkpoint and structure +The following error modes are currently handled by the `PyscfBaseWorkChain`: +- `120`: Out of walltime: The calculation will be restarted from the last checkpoint if available, otherwise the work + chain is aborted +- `140`: Node failure: The calculation will be restarted from the last checkpoint +- `410`: Electronic convergence not achieved: The calculation will be restarted from the last checkpoint +- `500`: Ionic convergence not achieved: The geometry optmizization did not converge, calculation will be restarted from + the last checkpoint and structure ### Pickled model -The main objective of a `PyscfCalculation` is to solve the mean-field problem for a given structure. -The results of this, often computationally expensive, step are stored in the `mean_field_run` variable in the main script: +The main objective of a `PyscfCalculation` is to solve the mean-field problem for a given structure. The results of +this, often computationally expensive, step are stored in the `mean_field_run` variable in the main script: + ```python mean_field = scf.RHF(structure) density_matrix = mean_field.from_chk('restart.chk') mean_field_run = mean_field.run(density_matrix) ``` -The `mean_field_run` object can be used for a number of further post-processing operations implemented in PySCF. -To keep the `PyscfCalculation` interface simple, not all of this functionality is supported. -However, as soon as the calculation job finishes, the `mean_field_run` variable is lost and can no longer be accessed to be used for further processing. -As a workaround, the `PyscfCalculation` will ["pickle"](https://docs.python.org/3/library/pickle.html) the `mean_field_run` object and attach it as the `model` output to the calculation. -The `model` output node can be "unpickled" to restore the original `mean_field_run` object such that it can be used for further processing: +The `mean_field_run` object can be used for a number of further post-processing operations implemented in PySCF. To keep +the `PyscfCalculation` interface simple, not all of this functionality is supported. However, as soon as the calculation +job finishes, the `mean_field_run` variable is lost and can no longer be accessed to be used for further processing. + +As a workaround, the `PyscfCalculation` will ["pickle"](https://docs.python.org/3/library/pickle.html) the +`mean_field_run` object and attach it as the `model` output to the calculation. The `model` output node can be +"unpickled" to restore the original `mean_field_run` object such that it can be used for further processing: + ```python from aiida.engine import run inputs = {} @@ -395,29 +453,27 @@ mean_field = node.outputs.model.load() print(mean_field.e_tot) ``` -> **Warning** -> For certain cases, the calculation may fail to pickle the model and will except. -> In this case, one can set the `pickle_model` input to the `PyscfCalculation` to `False`. - +> **Warning** For certain cases, the calculation may fail to pickle the model and will except. In this case, one can set +> the `pickle_model` input to the `PyscfCalculation` to `False`. ## Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License +Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For +details, visit https://cla.opensource.microsoft.com. -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. +When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate +the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only +need to do this once across all repos using our CLA. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact +[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. ## Trademarks -This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft -trademarks or logos is subject to and must follow +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks +or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). -Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. -Any use of third-party trademarks or logos are subject to those third-party's policies. +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft +sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies. diff --git a/SECURITY.md b/SECURITY.md index 9dc6316..094a8a9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,33 +2,46 @@ ## Security -Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). +Microsoft takes the security of our software products and services seriously, which includes all source code +repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), +[Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), +[Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). -If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets +[Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to +us as described below. ## Reporting Security Issues **Please do not report security vulnerabilities through public GitHub issues.** -Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). +Instead, please report them to the Microsoft Security Response Center (MSRC) at +[https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). -If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If +possible, encrypt your message with our PGP key; please download it from the +[Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). -You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we +received your original message. Additional information can be found at +[microsoft.com/msrc](https://aka.ms/opensource/security/msrc). -Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: +Please include the requested information listed below (as much as you can provide) to help us better understand the +nature and scope of the possible issue: - * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +- Full paths of source file(s) related to the manifestation of the issue +- The location of the affected source code (tag/branch/commit or direct URL) +- Any special configuration required to reproduce the issue +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. -If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our +[Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active +programs. ## Preferred Languages