diff --git a/search/search_index.json b/search/search_index.json index 5034be0..8268fe3 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"CASTEP Documentation This is the CASTEP community documentation and tutorial site. For an overview of CASTEP, and to obtain a licence please see the castep website For the Dassault Syst\u00e8mes BIOVIA (Materials Studio) documentation for CASTEP see HTML documentation and a downloadable pdf user guide Contributors: Albert Bart\u00f3k-P\u00e1rtay, Stewart Clark, Phil Hasnip, Chris Pickard, Matt Probert, Keith Refson, Kane Shenton, Benjamin Shi, Jonathan Yates","title":"Home"},{"location":"#castep-documentation","text":"This is the CASTEP community documentation and tutorial site. For an overview of CASTEP, and to obtain a licence please see the castep website For the Dassault Syst\u00e8mes BIOVIA (Materials Studio) documentation for CASTEP see HTML documentation and a downloadable pdf user guide","title":"CASTEP Documentation"},{"location":"#contributors","text":"Albert Bart\u00f3k-P\u00e1rtay, Stewart Clark, Phil Hasnip, Chris Pickard, Matt Probert, Keith Refson, Kane Shenton, Benjamin Shi, Jonathan Yates","title":"Contributors:"},{"location":"developer/CI/","text":"CI Testing System Overview Notice The following document assumes you have access to both the CASTEP source and the ANVIL CI system. The CASTEP CI system is divided into 3 phases: Rapid Response (BitBucket) A short set of tests run whenever a PR is created or pushed to. CASTEP PR Tests (Jenkins) A more substantial set of tests run whenever a PR is created or pushed to. CASTEP Default Tests (Jenkins) A set of tests run whenever default or a release branch is merged to. The main CASTEP continuous integration (CI) system is a Jenkins instance run on the ANVIL service. The main CASTEP Jenkins instance is available at: https://anvil.softeng-support.ac.uk/jenkins/job/CASTEP/view/all/ Going through the Jenkins Dashboard will take you to the waterfall diagram landing page. Note The ANVIL service is an STFC-cloud managed system and requests to register will be considered by them on a case-by-case basis and are out of control of the CASTEP team. Personal Pipeline For the purposes of development testing you can request a personal pipeline in order to be able to rapidly test in the variety of environments under which the main CASTEP testing is performed. This is required for e.g. modifying the Jenkinsfile Access to this pipeline will require an ANVIL account and a reasonable cause for the request. Navigating Jenkins Waterfall diagram The landing page from the Jenkins dashboard is the Waterfall diagram which shows a quick display of the most recent results for the default , Release and PR_builds pipelines. Tip To enable accessibility options including text-scale and colourblind mode, select the gear in the top-right. The colours represent the status of the pipeline: Colour Colourblind Meaning Green Plain Previous run succeeded. Orange Diamonds Previous run failed tests, but built successfully. Red Diagonal stripe Previous run failed to build one or more pipelines successfully. Note The text below the pipeline describes how long the pipeline has been failing as well as the extent of the failure. Clicking on any of the pipeline names will take you to the pipeline menu for that pipeline. Pipeline Menu The pipeline menu is the display of the status for any single pipeline. It has a number of important displays and buttons. The figure below highlights these. Note The side-bar is dynamic and the options available to you may not match those in the figure above for any particular pipeline. For example, this pipeline has not generated a coverage report. Navigation Bar The navigation bar allows you to look at other pipelines, each name is a link to that section/level of the Jenkins. Warning The \"CASTEP\" level button will take you to the Waterfall landing page. In order to get to the top-level CASTEP dashboard, select \"All\" instead. When viewing linter and warning reports the navigation bar will also display the currently applied filters in the order they were applied and serves as the way to remove those filters. Pipeline Status The pipeline status shows the previous run statuses. It is possible to click on any stage, and then logs to get a step-by-step breakdown of the issue. Any step that failed will be coloured pink rather than the usual grey. It is then possible to click on the tab to expand the console output for that particular step. Generally in the case of: builds this will be the Compile step above the failure. tests this will be the Diff step below the failure. Note Clicking the step name will take you to a different page with a full-page display of the output of that step. Tip Tabs collapse when another is selected. Reports During a Jenkins run, several \"reports\" may be created and made available in the side-bar of a pipeline that generates them. Linting and Compiler Warnings Following a build, Jenkins will collect the compiler warnings issued during a build along with, if a linting phase is run, the resulting linter issues into a report accessible through the side-bar. Warning The warning collection will take the set of warnings from the first build using any of the following compilers: gfortran ifort nag This means that if the first item for each compiler in builds_to_run (see manual parametrised runs ) is not an opt=debug build, you may miss most warnings. The reports allow the types of issues to be selected and filtered: They can be grouped and sorted by clicking the appropriate buttons above the main table and table entries. The doughnut of severity is actually a clickable filter to filter to warnings of that level! The + icon to the left of the issue in \"Issues\" \"group by\" mode allows you to expand the issue to get more detail. Selecting the file from the \"File\" column displays annotated source, however, see the issue below. Known issue Due to the relatively large sizes of CASTEP source files, while selecting the file:line link will take you to an annotated copy of the source at the point of the issue in question, the rendering engine tends to bog down machines causing browsers to struggle or fail to load the annotated file. Test Coverage Report Whenever a coverage build is run (i.e. with either the ifort or gfortran compiler and opt=coverage ), Jenkins will accumulate the coverage reports and make them accessible in the side-bar. Known issue Due to current security settings on ANVIL the ifort reports are not viewable through this view and must be downloaded to be viewed. FORD API Documentation As part of the full build of the default branch following a merge, Jenkins will trigger a FORD API documentation build. The results of this build are accessible from the side-bar of the CASTEP > All > Default_branch > docs-trigger pipeline. Build Artefacts During a Jenkins run, various files will be preserved, making them available to download. Currently the artefacts that are preserved are: Linting reports Failed test data Coverage reports FORD Documentation Some artefacts are available for download at the top of the pipeline menu above the previous runs. For interactive reports (coverage and FORD), when opened the download button is available in the top-right. Jenkins Pipelines The tests run in the course of CI are controlled through the Jenkinsfile in the root CASTEP folder. Default builds run In general, the default set of configurations are run on rocky8 using: Intel 23 Ifx 24 GCC 13 GCC 9 NAG 7.1 NVFortran 23.7 with different combinations of arch , comms and external libraries attempting to cover a broad scope of possible use-cases. Note All default or manual builds will also run a test of the correctness and completeness of the source distribution GNU make and CMake dist targets. Default build keys At time of writing, the default build keys are: rocky8;linux_x86_64_ifort;debug;mpi#intel23 rocky8;linux_x86_64_gfortran;debug;mpi#gcc9 rocky8;linux_x86_64_nag;debug;serial rocky8;linux_x86_64_gfortran10;coverage;mpi#gcc13-libxc rocky8;linux_x86_64_ifort;coverage;serial#intel23-nocmake rocky8;linux_x86_64_ifort;fast;serial#intel23-nocmake rocky8;linux_x86_64_gfortran;fast;mpi#gcc9-nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-nocmake rocky8;linux_x86_64_gfortran10;fast;serial#gcc13-nocmake rocky8;linux_x86_64_nvfortran;fast;mpi#nogrimmed4 rocky8;linux_x86_64_ifx;fast;mpi#ifx24-nocmake However, these are subject to change. PR Builds run When a PR is opened, BitBucket triggers a small subset of the Jenkins tests. These builds only run the quick subset of the tests. Note If a PR only affects parts of CASTEP which are not tested, such as documentation or separate tools, it should have [skiptest] or [skipanvil] in the PR title. If a PR is not yet ready for testing, it should have [wip] or [draft] in the PR title. These will prevent the PR from triggering the Jenkins build saving resources. Default PR builds These builds are (at the time of writing): rocky8;linux_x86_64_nag;intermediate;serial#nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-fftw-nocmake rocky8;linux_x86_64_ifort;intermediate;serial#intel23-nocmake rocky8;linux_x86_64_nvfortran;fast;serial#nogrimmed4-nognumake However, these are subject to change. Manual Parametrised Runs If you wish to start a run with a particular subset of configurations or tests, it is possible to start a parametrised run manually. From the Jenkins interface select the pipeline to run the build on (see Personal Pipelines ) and select Build with Parameters . This allows one to manually specify the components to use. Parameters The parameters are as follows: Parameter Meaning Default repo_method Define method to retrieve repo. Should not need to be changed. https repo_host URL to repository if externally hosted. Should not need to be changed. bitbucket.org repo_path URL Path to workspace and repository. 1 castep/castep branch Branch to build and test. 2 default builds_to_run Builds to run as list of build keys . see: Default builds list tests_to_run List of tests to run. all except quick baseURL Slack URL to post mesasge to. N.B. Set to empty string to not send message. https://corecastepdevelopers.slack.com/services/hooks/ lint Run or skip linting stage. true 1 The command run as part of the checkout will be roughly equivalent to: git clone ${ repo_method } :// ${ repo_host } / ${ repo_path } --single-branch --branch ${ branch } 2 Jenkins will automatically push the run's status to the HEAD commit of the branch being tested at the time of the run. Warning Pushes to the branch while a test is running may result in Jenkins picking up the latest changes and running partial tests on the new HEAD Build keys The Jenkins tests are able to be run on a variety of different system configurations. In order to select a particular configuration, it is necessary to specify the key which identifies the configuration. The format of these keys is: agent;arch;opt;comms#comment Where agent is one of: rocky8 -- Rocky Linux 8 rocky8-gpu -- Rocky Linux 8 with GPU support rocky9 -- Rocky Linux 9 icdpacewin -- Windows and arch , opt and comms correspond to the CASTEP build system variables ARCH , OPT and COMMS . comment is used to distinguish otherwise similar variants and uniquely identify a particular configuration as well as apply modifications to the build (see comment tags ). It should be noted, however, that only certain combinations of variables are available on certain agents. For a full set of available combinations it is necessary to look into the Jenkinsfile itself as this list is frequently updated and changed. Comment Tags The comment section of the build key allows changes to the configuration outside of the usual build flags. These are added in the following way (adding nocmake ): If the base build does not have a comment rocky8;linux_x86_64_nag;debug;serial#nocmake If it does rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake Multiple comment tags are joined with - rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake-nognumake Comment tags Currently the available tags are: Tag Effect targetHost Compiles optimised CASTEP targetting the VM architecture targetPortable Compiles portable CASTEP libxc Links CASTEP against LibXC nogrimmed3 Does not compile (or test) D3 SEDC nogrimmed4 Does not compile (or test) D4 SEDC nodlmg Does not compile (or test) DLMG libraries debug Enable verbose build stages nocmake Disable the CMake build phase and test nognumake Disable the GNU Make build phase and test, run specified test suite on CMake build (if not disabled) BitBucket pipelines In addition to the main Jenkins tests, there is also a subset of short, fast tests which are run on BitBucket every commit to ascertain functionality quickly. The BitBucket pipelines are managed through the bitbucket-pipelines.yml in the root CASTEP folder. They currently run: lint -- Run the castep-linter on the source. build-castep -- A debug build of CASTEP with included LibXC build-castep-python -- debug build of CASTEP's Python bindings test-castep -- Run of CASTEP's quick test suite. test-python -- Run of CASTEP's python test suite. All of these are performed on a single image of a Linux system compiled with gfortran and static LAPACK and BLAS libraries. They are not to be considered comprehensive. Modifying the Jenkinsfile Adding new configurations To add a new combination (c.f. Modifications ), it is necessary to define it in the matrix variable in the Jenkinsfile . This matrix is a Groovy Map object which translates a particular configuration to a Map of extra parameters needed to perform the build. i.e. matrix = [ \"agent;arch#comment\" : [ \"modules\" : \"\" , \"fft\" : \"\" , ...], ... ] Note All parameters are optional. To specify an empty Map (no parameters) use: [:] The list build parameters is outlined in the get_buildconfig_from_map function. Build Parameters Currently the build parameters are: Parameter Description Default modules Modules to load on Linux agents 1 \"\" fft Passed as the CASTEP build system variable FFT \"generic\" math_libs Passed as the CASTEP build system variable MATHLIBS \"generic\" fft_lib_dir Passed as the CASTEP build system variable FFTLIBDIR \"\" math_lib_dir Passed as the CASTEP build system variable MATHLIBDIR \"\" extra_args Extra command-line arguments passed literally to the GNU make build system. \"\" cmake_extra_args Extra command-line arguments passed literally to the CMake build system. \"\" 1 The list of available modules can be found on the ANVIL system under Examples -> List of available software . Adding new comment tags Comment tags are managed in the get_buildconfig_from_map routine. They are processed out of the matrix key, so they can be applied to any particular build configuration. A closure within the routine ( process_buildconfig_arg ) handles this process, its signature is: process_buildconfig_arg ( String comment_key , String make_arg , String cmake_arg ) Where: comment_key Comment tag to process make_arg Extra CLI args to pass to GNU Make build cmake_arg Extra CLI args to pass to CMake build This routine checks for the presence of the comment tag, removes it from the build lookup key and adds make_arg and cmake_arg to their respective argument lists. Note In cases where you do not need to add or modify the compilation arguments, it is reasonable to put them as empty strings ( \"\" ). The comment tags are still passed through to config[0] which can be checked for the presence of the key. Submitting modifications to the Jenkinsfile For any PR with a modification to the Jenkinsfile to be accepted it must be provided with the following: Detailed description of the reasons for the change as well as the changes themselves A custom pipeline run demonstrating the use of the modified pipeline with all expected use-cases, which may include: Each agent in common usage (Currently rocky8 , icdpacewin , rocky8-gpu ) A significant selection of the build configurations in common usage Including at least one WITH a comment, and one without Combinations of common tags All tests (including quick which is not default) Note In order to develop and test a custom Jenkinsfile , it is necessary to make a request to one of the Jenkins admins to reconfigure your pipeline to point to the relevant repository prior to being able to run the custom Jenkinsfile .","title":"CI System"},{"location":"developer/CI/#ci-testing-system","text":"","title":"CI Testing System"},{"location":"developer/CI/#overview","text":"Notice The following document assumes you have access to both the CASTEP source and the ANVIL CI system. The CASTEP CI system is divided into 3 phases: Rapid Response (BitBucket) A short set of tests run whenever a PR is created or pushed to. CASTEP PR Tests (Jenkins) A more substantial set of tests run whenever a PR is created or pushed to. CASTEP Default Tests (Jenkins) A set of tests run whenever default or a release branch is merged to. The main CASTEP continuous integration (CI) system is a Jenkins instance run on the ANVIL service. The main CASTEP Jenkins instance is available at: https://anvil.softeng-support.ac.uk/jenkins/job/CASTEP/view/all/ Going through the Jenkins Dashboard will take you to the waterfall diagram landing page. Note The ANVIL service is an STFC-cloud managed system and requests to register will be considered by them on a case-by-case basis and are out of control of the CASTEP team.","title":"Overview"},{"location":"developer/CI/#personal-pipeline","text":"For the purposes of development testing you can request a personal pipeline in order to be able to rapidly test in the variety of environments under which the main CASTEP testing is performed. This is required for e.g. modifying the Jenkinsfile Access to this pipeline will require an ANVIL account and a reasonable cause for the request.","title":"Personal Pipeline"},{"location":"developer/CI/#navigating-jenkins","text":"","title":"Navigating Jenkins"},{"location":"developer/CI/#waterfall-diagram","text":"The landing page from the Jenkins dashboard is the Waterfall diagram which shows a quick display of the most recent results for the default , Release and PR_builds pipelines. Tip To enable accessibility options including text-scale and colourblind mode, select the gear in the top-right. The colours represent the status of the pipeline: Colour Colourblind Meaning Green Plain Previous run succeeded. Orange Diamonds Previous run failed tests, but built successfully. Red Diagonal stripe Previous run failed to build one or more pipelines successfully. Note The text below the pipeline describes how long the pipeline has been failing as well as the extent of the failure. Clicking on any of the pipeline names will take you to the pipeline menu for that pipeline.","title":"Waterfall diagram"},{"location":"developer/CI/#pipeline-menu","text":"The pipeline menu is the display of the status for any single pipeline. It has a number of important displays and buttons. The figure below highlights these. Note The side-bar is dynamic and the options available to you may not match those in the figure above for any particular pipeline. For example, this pipeline has not generated a coverage report.","title":"Pipeline Menu"},{"location":"developer/CI/#navigation-bar","text":"The navigation bar allows you to look at other pipelines, each name is a link to that section/level of the Jenkins. Warning The \"CASTEP\" level button will take you to the Waterfall landing page. In order to get to the top-level CASTEP dashboard, select \"All\" instead. When viewing linter and warning reports the navigation bar will also display the currently applied filters in the order they were applied and serves as the way to remove those filters.","title":"Navigation Bar"},{"location":"developer/CI/#pipeline-status","text":"The pipeline status shows the previous run statuses. It is possible to click on any stage, and then logs to get a step-by-step breakdown of the issue. Any step that failed will be coloured pink rather than the usual grey. It is then possible to click on the tab to expand the console output for that particular step. Generally in the case of: builds this will be the Compile step above the failure. tests this will be the Diff step below the failure. Note Clicking the step name will take you to a different page with a full-page display of the output of that step. Tip Tabs collapse when another is selected.","title":"Pipeline Status"},{"location":"developer/CI/#reports","text":"During a Jenkins run, several \"reports\" may be created and made available in the side-bar of a pipeline that generates them.","title":"Reports"},{"location":"developer/CI/#linting-and-compiler-warnings","text":"Following a build, Jenkins will collect the compiler warnings issued during a build along with, if a linting phase is run, the resulting linter issues into a report accessible through the side-bar. Warning The warning collection will take the set of warnings from the first build using any of the following compilers: gfortran ifort nag This means that if the first item for each compiler in builds_to_run (see manual parametrised runs ) is not an opt=debug build, you may miss most warnings. The reports allow the types of issues to be selected and filtered: They can be grouped and sorted by clicking the appropriate buttons above the main table and table entries. The doughnut of severity is actually a clickable filter to filter to warnings of that level! The + icon to the left of the issue in \"Issues\" \"group by\" mode allows you to expand the issue to get more detail. Selecting the file from the \"File\" column displays annotated source, however, see the issue below. Known issue Due to the relatively large sizes of CASTEP source files, while selecting the file:line link will take you to an annotated copy of the source at the point of the issue in question, the rendering engine tends to bog down machines causing browsers to struggle or fail to load the annotated file.","title":"Linting and Compiler Warnings"},{"location":"developer/CI/#test-coverage-report","text":"Whenever a coverage build is run (i.e. with either the ifort or gfortran compiler and opt=coverage ), Jenkins will accumulate the coverage reports and make them accessible in the side-bar. Known issue Due to current security settings on ANVIL the ifort reports are not viewable through this view and must be downloaded to be viewed.","title":"Test Coverage Report"},{"location":"developer/CI/#ford-api-documentation","text":"As part of the full build of the default branch following a merge, Jenkins will trigger a FORD API documentation build. The results of this build are accessible from the side-bar of the CASTEP > All > Default_branch > docs-trigger pipeline.","title":"FORD API Documentation"},{"location":"developer/CI/#build-artefacts","text":"During a Jenkins run, various files will be preserved, making them available to download. Currently the artefacts that are preserved are: Linting reports Failed test data Coverage reports FORD Documentation Some artefacts are available for download at the top of the pipeline menu above the previous runs. For interactive reports (coverage and FORD), when opened the download button is available in the top-right.","title":"Build Artefacts"},{"location":"developer/CI/#jenkins-pipelines","text":"The tests run in the course of CI are controlled through the Jenkinsfile in the root CASTEP folder.","title":"Jenkins Pipelines"},{"location":"developer/CI/#default-builds-run","text":"In general, the default set of configurations are run on rocky8 using: Intel 23 Ifx 24 GCC 13 GCC 9 NAG 7.1 NVFortran 23.7 with different combinations of arch , comms and external libraries attempting to cover a broad scope of possible use-cases. Note All default or manual builds will also run a test of the correctness and completeness of the source distribution GNU make and CMake dist targets. Default build keys At time of writing, the default build keys are: rocky8;linux_x86_64_ifort;debug;mpi#intel23 rocky8;linux_x86_64_gfortran;debug;mpi#gcc9 rocky8;linux_x86_64_nag;debug;serial rocky8;linux_x86_64_gfortran10;coverage;mpi#gcc13-libxc rocky8;linux_x86_64_ifort;coverage;serial#intel23-nocmake rocky8;linux_x86_64_ifort;fast;serial#intel23-nocmake rocky8;linux_x86_64_gfortran;fast;mpi#gcc9-nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-nocmake rocky8;linux_x86_64_gfortran10;fast;serial#gcc13-nocmake rocky8;linux_x86_64_nvfortran;fast;mpi#nogrimmed4 rocky8;linux_x86_64_ifx;fast;mpi#ifx24-nocmake However, these are subject to change.","title":"Default builds run"},{"location":"developer/CI/#pr-builds-run","text":"When a PR is opened, BitBucket triggers a small subset of the Jenkins tests. These builds only run the quick subset of the tests. Note If a PR only affects parts of CASTEP which are not tested, such as documentation or separate tools, it should have [skiptest] or [skipanvil] in the PR title. If a PR is not yet ready for testing, it should have [wip] or [draft] in the PR title. These will prevent the PR from triggering the Jenkins build saving resources. Default PR builds These builds are (at the time of writing): rocky8;linux_x86_64_nag;intermediate;serial#nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-fftw-nocmake rocky8;linux_x86_64_ifort;intermediate;serial#intel23-nocmake rocky8;linux_x86_64_nvfortran;fast;serial#nogrimmed4-nognumake However, these are subject to change.","title":"PR Builds run"},{"location":"developer/CI/#manual-parametrised-runs","text":"If you wish to start a run with a particular subset of configurations or tests, it is possible to start a parametrised run manually. From the Jenkins interface select the pipeline to run the build on (see Personal Pipelines ) and select Build with Parameters . This allows one to manually specify the components to use. Parameters The parameters are as follows: Parameter Meaning Default repo_method Define method to retrieve repo. Should not need to be changed. https repo_host URL to repository if externally hosted. Should not need to be changed. bitbucket.org repo_path URL Path to workspace and repository. 1 castep/castep branch Branch to build and test. 2 default builds_to_run Builds to run as list of build keys . see: Default builds list tests_to_run List of tests to run. all except quick baseURL Slack URL to post mesasge to. N.B. Set to empty string to not send message. https://corecastepdevelopers.slack.com/services/hooks/ lint Run or skip linting stage. true 1 The command run as part of the checkout will be roughly equivalent to: git clone ${ repo_method } :// ${ repo_host } / ${ repo_path } --single-branch --branch ${ branch } 2 Jenkins will automatically push the run's status to the HEAD commit of the branch being tested at the time of the run. Warning Pushes to the branch while a test is running may result in Jenkins picking up the latest changes and running partial tests on the new HEAD","title":"Manual Parametrised Runs"},{"location":"developer/CI/#build-keys","text":"The Jenkins tests are able to be run on a variety of different system configurations. In order to select a particular configuration, it is necessary to specify the key which identifies the configuration. The format of these keys is: agent;arch;opt;comms#comment Where agent is one of: rocky8 -- Rocky Linux 8 rocky8-gpu -- Rocky Linux 8 with GPU support rocky9 -- Rocky Linux 9 icdpacewin -- Windows and arch , opt and comms correspond to the CASTEP build system variables ARCH , OPT and COMMS . comment is used to distinguish otherwise similar variants and uniquely identify a particular configuration as well as apply modifications to the build (see comment tags ). It should be noted, however, that only certain combinations of variables are available on certain agents. For a full set of available combinations it is necessary to look into the Jenkinsfile itself as this list is frequently updated and changed.","title":"Build keys"},{"location":"developer/CI/#comment-tags","text":"The comment section of the build key allows changes to the configuration outside of the usual build flags. These are added in the following way (adding nocmake ): If the base build does not have a comment rocky8;linux_x86_64_nag;debug;serial#nocmake If it does rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake Multiple comment tags are joined with - rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake-nognumake Comment tags Currently the available tags are: Tag Effect targetHost Compiles optimised CASTEP targetting the VM architecture targetPortable Compiles portable CASTEP libxc Links CASTEP against LibXC nogrimmed3 Does not compile (or test) D3 SEDC nogrimmed4 Does not compile (or test) D4 SEDC nodlmg Does not compile (or test) DLMG libraries debug Enable verbose build stages nocmake Disable the CMake build phase and test nognumake Disable the GNU Make build phase and test, run specified test suite on CMake build (if not disabled)","title":"Comment Tags"},{"location":"developer/CI/#bitbucket-pipelines","text":"In addition to the main Jenkins tests, there is also a subset of short, fast tests which are run on BitBucket every commit to ascertain functionality quickly. The BitBucket pipelines are managed through the bitbucket-pipelines.yml in the root CASTEP folder. They currently run: lint -- Run the castep-linter on the source. build-castep -- A debug build of CASTEP with included LibXC build-castep-python -- debug build of CASTEP's Python bindings test-castep -- Run of CASTEP's quick test suite. test-python -- Run of CASTEP's python test suite. All of these are performed on a single image of a Linux system compiled with gfortran and static LAPACK and BLAS libraries. They are not to be considered comprehensive.","title":"BitBucket pipelines"},{"location":"developer/CI/#modifying-the-jenkinsfile","text":"","title":"Modifying the Jenkinsfile"},{"location":"developer/CI/#adding-new-configurations","text":"To add a new combination (c.f. Modifications ), it is necessary to define it in the matrix variable in the Jenkinsfile . This matrix is a Groovy Map object which translates a particular configuration to a Map of extra parameters needed to perform the build. i.e. matrix = [ \"agent;arch#comment\" : [ \"modules\" : \"\" , \"fft\" : \"\" , ...], ... ] Note All parameters are optional. To specify an empty Map (no parameters) use: [:] The list build parameters is outlined in the get_buildconfig_from_map function. Build Parameters Currently the build parameters are: Parameter Description Default modules Modules to load on Linux agents 1 \"\" fft Passed as the CASTEP build system variable FFT \"generic\" math_libs Passed as the CASTEP build system variable MATHLIBS \"generic\" fft_lib_dir Passed as the CASTEP build system variable FFTLIBDIR \"\" math_lib_dir Passed as the CASTEP build system variable MATHLIBDIR \"\" extra_args Extra command-line arguments passed literally to the GNU make build system. \"\" cmake_extra_args Extra command-line arguments passed literally to the CMake build system. \"\" 1 The list of available modules can be found on the ANVIL system under Examples -> List of available software .","title":"Adding new configurations"},{"location":"developer/CI/#adding-new-comment-tags","text":"Comment tags are managed in the get_buildconfig_from_map routine. They are processed out of the matrix key, so they can be applied to any particular build configuration. A closure within the routine ( process_buildconfig_arg ) handles this process, its signature is: process_buildconfig_arg ( String comment_key , String make_arg , String cmake_arg ) Where: comment_key Comment tag to process make_arg Extra CLI args to pass to GNU Make build cmake_arg Extra CLI args to pass to CMake build This routine checks for the presence of the comment tag, removes it from the build lookup key and adds make_arg and cmake_arg to their respective argument lists. Note In cases where you do not need to add or modify the compilation arguments, it is reasonable to put them as empty strings ( \"\" ). The comment tags are still passed through to config[0] which can be checked for the presence of the key.","title":"Adding new comment tags"},{"location":"developer/CI/#submitting-modifications-to-the-jenkinsfile","text":"For any PR with a modification to the Jenkinsfile to be accepted it must be provided with the following: Detailed description of the reasons for the change as well as the changes themselves A custom pipeline run demonstrating the use of the modified pipeline with all expected use-cases, which may include: Each agent in common usage (Currently rocky8 , icdpacewin , rocky8-gpu ) A significant selection of the build configurations in common usage Including at least one WITH a comment, and one without Combinations of common tags All tests (including quick which is not default) Note In order to develop and test a custom Jenkinsfile , it is necessary to make a request to one of the Jenkins admins to reconfigure your pipeline to point to the relevant repository prior to being able to run the custom Jenkinsfile .","title":"Submitting modifications to the Jenkinsfile"},{"location":"developer/adding_pair_pots/","text":"Adding Empirical potentials If you have access to the source, it is possible to add a new formulation for an empirical potential easily. The idea of the module is that this should be trivial even to a beginner programmer with no expert knowledge of Fortran. A summary of how to do this is in the header of the pair_pot.f90 source, a more in-depth description is below. Setting up parameters First we need to make the pair_pot_type aware of your potential. There are several key things we need to update in order to use our potential. First, we need to update the number of potentials our code is looking for: BEFORE : integer , parameter :: num_pot = 9 AFTER : integer , parameter :: num_pot = 10 Next we need to tell the code what our potential's keyword is and its internal ID. This will be the highest number which isn't occupied. (NOTE: Keywords have to have a length of 4 characters and must be padded with spaces to this length): BEFORE : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' ] AFTER : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 , new = 10 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' , 'NEW ' ] We then need to add the parameters that our potential will use to the pair_pot_type . The style of these parameters should be: The variable name should be the keyword of your potential followed by an underscore, followed by the name or symbol for the parameter. They should be of type real(kind=dp) . They should be allocatable, and of dimensions equivalent to the number of particles involved in the interaction (i.e. 2-body \\Rightarrow{} \\Rightarrow{} dimension(:,:) ; 3-body \\Rightarrow{} \\Rightarrow{} dimension(:,:,:) ). They should have a comment describing the full name and form of your potential. It is also important to note that Fortran is case-insensitive, meaning it does not distinguish between upper and lower cases in variable names. !New example potential of the form b*exp(rij^-qi)*exp(rik^-qi) + (cos(rijk) - cos(s)) real ( kind = dp ), dimension (:), allocatable :: new_q real ( kind = dp ), dimension (:,:), allocatable :: new_b real ( kind = dp ), dimension (:,:,:), allocatable :: new_s We should now go into pair_pot_print and add our potential to the 1- and 2- (and possibly 3-)body sections of the potential printing. This is of the form: 1-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 103 ) pre_str , 'r' , pair_pot % cut_off ( pair_pot % new , 1 , 1 ), 'NEW' write ( unit_out , 103 ) pre_str , 'q' , pair_pot % new_q ( 1 , 1 ), 'NEW' end if 2-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 202 ) pre_str , 'r' , pair_pot_print_combinations ( pair_pot % cut_off ( pair_pot % new , :, :), ispec , jspec ), 'NEW' write ( unit_out , 202 ) pre_str , 'b' , pair_pot_print_combinations ( pair_pot % new_b , ispec , jspec ), 'NEW' end if 3-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 301 ) pre_str , ispec_name , jspec_name , kspec_name write ( unit_out , 103 ) pre_str , 'S' , pair_pot % new_s ( ispec , jspec , kspec ), 'NEW' end if And with that we should be done with setting up our potential in pair_pot_type , things like cut-off and the activation of the potential are handled automatically based on the potential keyword, although for some specialised potentials advanced rules can be necessary. Allocation and deallocation It is important in Fortran to ensure that our parameter arrays are allocated. We need to go into the routine pair_pot_allocate and add our new parameters to it. For our example potential, the syntax is as follows: if ( pair_pot % pot_present ( pair_pot % new ) allocate ( pair_pot % new_q ( 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_q' , 'pair_pot_allocate' ) allocate ( pair_pot % new_b ( 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_b' , 'pair_pot_allocate' ) allocate ( pair_pot % new_s ( 1 : nspec , 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_s' , 'pair_pot_allocate' ) end if We also need to do the same for cleaning up our potential at the end, in the routine pair_pot_deallocate : if ( allocated ( pair_pot % new_q )) then deallocate ( pair_pot % new_q , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_q in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_b )) then deallocate ( pair_pot % new_b , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_b in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_s )) then deallocate ( pair_pot % new_s , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_s in pair_pot_deallocate' ) end if Initialising variables We need to be able to set the values for our parameters. For this we need to add an initialisation subroutine. The details can be found in the sample file, available on request. For three-body routines it is necessary to set the pair_pot%three_body flag on initialisation, and also to add a species triplet loop. Writing the calculation routine This is the only bit which is down to the the creator to consider how it should be set up. The subroutine should obey the follow: The name of the routine should be pair_pot_ The potential should have a header referencing the origin of the potential and the form of the potential. Two-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , rij , mod_rij_2 , ispec , jspec [, spins ], dfij , de ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. rij is of type real(kind=dp) of dimension(3) and is the vector between the two particles. mod_rij_2 is of type real(kind=dp) and is the distance between the two particles. ispec is of type integer and is the species of atom i. jspec is of type integer and is the species of atom j. spins [optional] is of type real(kind=dp) of dimension(4,2) and is the pair of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3) and is the vector force between the two particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the two particles. To reference two-body terms you should use the following syntax: pair_pot % new_b ( ispec , jspec ) Three-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , dr , mod_dr_2 , rcjk , include_cjk , spec [, spins ], dfij , de , stress ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. dr is of type real(kind=dp) of dimension(3,3) and is the vectors of the triplet of pairs of particles. mod_dr_2 is of type real(kind=dp) of dimension(3) and is the distance between the triplet of particles. rcjk is of type real(kind=dp) of dimension(3,3) and is the absolute positions of the particles in the cell. include_cjk is of type logical of dimension(3) and is whether the magnitude of distances between particles is less than that of the cut-off. spec is of type integer of dimension(3) and is the species of the particles. spins [optional] is of type real(kind=dp) of dimension(4,3) and is the triplet of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3,3) and is the vector force between the triplet of particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the interactions. stress is of type real(kind=dp) of dimension(6) and is the upper triangle of stress contributions of the particles. To reference three-body terms you should use the following syntax: pair_pot % new_s ( spec ( i_atom ), spec ( j_atom ), spec ( k_atom )) Spins If your potential uses spin as part of the force-field these are passed into the calculation routines as a set of 4-vectors (2 for 2-body, 3 for 3-body) where the 4 parameters are the 3 directions and the magnitude. Adding the contribution To actually tell the code to calculate the contribution of your potential to the system, we need to add it to the pair_pot_contribution routine, this has the following syntax for two-body potentials: if ( pot_include ( pair_pot % new )) then call pair_pot_new ( pair_pot , rij , mod_rij_2 , species ( 1 ), species ( 2 ), dfij , de ) e_cont = e_cont + de fij (:) = fij (:) + dfij (:) end if Three-body potentials are currently trickier and must currently be manually inserted into the loop in pair_pot_calc , there are aims to simplify this in future releases. Testing We should now be able to activate your potential by adding NEW=T into the devel code block and can set all the parameters just as for other potentials. To verify that you potential is working as expected, there are several built-in methods to check for developers. The first is the FD_CHECK devel code which enables finite difference evaluation alongside the potential evaluation and dumps the output to a file .fd . It aso prints warnings if the analytic and finite difference derivatives do not match. You should verify that the finite difference evaluated forces are the same as the analytic derivative. The second is the PRINT_POT devel code which evaluates your potential over 1000 evenly spaced points between 0 and your cut-off and dumps the computed forces and energies to a series of files of the form ____.pot these are just 3-column tabular data of the form Distance Energy Force ready to be plotted. Tests should be added to the test suite to compute the value of your new potential at known points.","title":"Adding empirical potentials"},{"location":"developer/adding_pair_pots/#adding-empirical-potentials","text":"If you have access to the source, it is possible to add a new formulation for an empirical potential easily. The idea of the module is that this should be trivial even to a beginner programmer with no expert knowledge of Fortran. A summary of how to do this is in the header of the pair_pot.f90 source, a more in-depth description is below.","title":"Adding Empirical potentials"},{"location":"developer/adding_pair_pots/#setting-up-parameters","text":"First we need to make the pair_pot_type aware of your potential. There are several key things we need to update in order to use our potential. First, we need to update the number of potentials our code is looking for: BEFORE : integer , parameter :: num_pot = 9 AFTER : integer , parameter :: num_pot = 10 Next we need to tell the code what our potential's keyword is and its internal ID. This will be the highest number which isn't occupied. (NOTE: Keywords have to have a length of 4 characters and must be padded with spaces to this length): BEFORE : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' ] AFTER : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 , new = 10 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' , 'NEW ' ] We then need to add the parameters that our potential will use to the pair_pot_type . The style of these parameters should be: The variable name should be the keyword of your potential followed by an underscore, followed by the name or symbol for the parameter. They should be of type real(kind=dp) . They should be allocatable, and of dimensions equivalent to the number of particles involved in the interaction (i.e. 2-body \\Rightarrow{} \\Rightarrow{} dimension(:,:) ; 3-body \\Rightarrow{} \\Rightarrow{} dimension(:,:,:) ). They should have a comment describing the full name and form of your potential. It is also important to note that Fortran is case-insensitive, meaning it does not distinguish between upper and lower cases in variable names. !New example potential of the form b*exp(rij^-qi)*exp(rik^-qi) + (cos(rijk) - cos(s)) real ( kind = dp ), dimension (:), allocatable :: new_q real ( kind = dp ), dimension (:,:), allocatable :: new_b real ( kind = dp ), dimension (:,:,:), allocatable :: new_s We should now go into pair_pot_print and add our potential to the 1- and 2- (and possibly 3-)body sections of the potential printing. This is of the form: 1-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 103 ) pre_str , 'r' , pair_pot % cut_off ( pair_pot % new , 1 , 1 ), 'NEW' write ( unit_out , 103 ) pre_str , 'q' , pair_pot % new_q ( 1 , 1 ), 'NEW' end if 2-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 202 ) pre_str , 'r' , pair_pot_print_combinations ( pair_pot % cut_off ( pair_pot % new , :, :), ispec , jspec ), 'NEW' write ( unit_out , 202 ) pre_str , 'b' , pair_pot_print_combinations ( pair_pot % new_b , ispec , jspec ), 'NEW' end if 3-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 301 ) pre_str , ispec_name , jspec_name , kspec_name write ( unit_out , 103 ) pre_str , 'S' , pair_pot % new_s ( ispec , jspec , kspec ), 'NEW' end if And with that we should be done with setting up our potential in pair_pot_type , things like cut-off and the activation of the potential are handled automatically based on the potential keyword, although for some specialised potentials advanced rules can be necessary.","title":"Setting up parameters"},{"location":"developer/adding_pair_pots/#allocation-and-deallocation","text":"It is important in Fortran to ensure that our parameter arrays are allocated. We need to go into the routine pair_pot_allocate and add our new parameters to it. For our example potential, the syntax is as follows: if ( pair_pot % pot_present ( pair_pot % new ) allocate ( pair_pot % new_q ( 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_q' , 'pair_pot_allocate' ) allocate ( pair_pot % new_b ( 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_b' , 'pair_pot_allocate' ) allocate ( pair_pot % new_s ( 1 : nspec , 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_s' , 'pair_pot_allocate' ) end if We also need to do the same for cleaning up our potential at the end, in the routine pair_pot_deallocate : if ( allocated ( pair_pot % new_q )) then deallocate ( pair_pot % new_q , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_q in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_b )) then deallocate ( pair_pot % new_b , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_b in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_s )) then deallocate ( pair_pot % new_s , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_s in pair_pot_deallocate' ) end if","title":"Allocation and deallocation"},{"location":"developer/adding_pair_pots/#initialising-variables","text":"We need to be able to set the values for our parameters. For this we need to add an initialisation subroutine. The details can be found in the sample file, available on request. For three-body routines it is necessary to set the pair_pot%three_body flag on initialisation, and also to add a species triplet loop.","title":"Initialising variables"},{"location":"developer/adding_pair_pots/#writing-the-calculation-routine","text":"This is the only bit which is down to the the creator to consider how it should be set up. The subroutine should obey the follow: The name of the routine should be pair_pot_ The potential should have a header referencing the origin of the potential and the form of the potential. Two-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , rij , mod_rij_2 , ispec , jspec [, spins ], dfij , de ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. rij is of type real(kind=dp) of dimension(3) and is the vector between the two particles. mod_rij_2 is of type real(kind=dp) and is the distance between the two particles. ispec is of type integer and is the species of atom i. jspec is of type integer and is the species of atom j. spins [optional] is of type real(kind=dp) of dimension(4,2) and is the pair of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3) and is the vector force between the two particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the two particles. To reference two-body terms you should use the following syntax: pair_pot % new_b ( ispec , jspec ) Three-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , dr , mod_dr_2 , rcjk , include_cjk , spec [, spins ], dfij , de , stress ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. dr is of type real(kind=dp) of dimension(3,3) and is the vectors of the triplet of pairs of particles. mod_dr_2 is of type real(kind=dp) of dimension(3) and is the distance between the triplet of particles. rcjk is of type real(kind=dp) of dimension(3,3) and is the absolute positions of the particles in the cell. include_cjk is of type logical of dimension(3) and is whether the magnitude of distances between particles is less than that of the cut-off. spec is of type integer of dimension(3) and is the species of the particles. spins [optional] is of type real(kind=dp) of dimension(4,3) and is the triplet of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3,3) and is the vector force between the triplet of particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the interactions. stress is of type real(kind=dp) of dimension(6) and is the upper triangle of stress contributions of the particles. To reference three-body terms you should use the following syntax: pair_pot % new_s ( spec ( i_atom ), spec ( j_atom ), spec ( k_atom ))","title":"Writing the calculation routine"},{"location":"developer/adding_pair_pots/#spins","text":"If your potential uses spin as part of the force-field these are passed into the calculation routines as a set of 4-vectors (2 for 2-body, 3 for 3-body) where the 4 parameters are the 3 directions and the magnitude.","title":"Spins"},{"location":"developer/adding_pair_pots/#adding-the-contribution","text":"To actually tell the code to calculate the contribution of your potential to the system, we need to add it to the pair_pot_contribution routine, this has the following syntax for two-body potentials: if ( pot_include ( pair_pot % new )) then call pair_pot_new ( pair_pot , rij , mod_rij_2 , species ( 1 ), species ( 2 ), dfij , de ) e_cont = e_cont + de fij (:) = fij (:) + dfij (:) end if Three-body potentials are currently trickier and must currently be manually inserted into the loop in pair_pot_calc , there are aims to simplify this in future releases.","title":"Adding the contribution"},{"location":"developer/adding_pair_pots/#testing","text":"We should now be able to activate your potential by adding NEW=T into the devel code block and can set all the parameters just as for other potentials. To verify that you potential is working as expected, there are several built-in methods to check for developers. The first is the FD_CHECK devel code which enables finite difference evaluation alongside the potential evaluation and dumps the output to a file .fd . It aso prints warnings if the analytic and finite difference derivatives do not match. You should verify that the finite difference evaluated forces are the same as the analytic derivative. The second is the PRINT_POT devel code which evaluates your potential over 1000 evenly spaced points between 0 and your cut-off and dumps the computed forces and energies to a series of files of the form ____.pot these are just 3-column tabular data of the form Distance Energy Force ready to be plotted. Tests should be added to the test suite to compute the value of your new potential at known points.","title":"Testing"},{"location":"developer/adding_testing/","text":"Adding Tests Following the addition of a new feature or bugfix it is essential to add system and unit tests that demonstrate the functionality of said addition. This document describes the process of adding new tests to the system as well as implementing your own testing groups. Warning Before any code is accepted into CASTEP it must have tests to prove its functionality and robustness. testcode CASTEP's test suite is built using the testcode testing platform. This handles all of the generation of benchmarks and comparisons in the test suite. Valid Properties CASTEP's extract_results.pl can extract the following properties from the .castep files: Note Those in code-style are the names for the properties, those without are just divisions used here Energy PS_Energy FreeEnergy SolvationEnergy dEtot/dlogE Spin AbsSpin Force Stress Phonons Phonon-q Phonon Grad_q(f) Freq g(f) ir Raman Born Species Ion Born Permittivity Polarisability Permittivity epsilon(f) NLO_Chi2 Raman Raman_Tr Raman_II depolarisation Electric_constants Compliance_mat Mulliken Populations Species Ion s p d f Total Charge Hirshfeld populations Species Ion Hirshfeld Spin ELF Data elf_fmt gx gy gz ELF(chi) den_fmt gx gy gz density chdiff_fmt gx gy gz diff-den pot_fmt gx gy gz potential Band Structure kx ky kz weight Eigenvalue MD Data MD Labels from the block magres cs_iso cs_aniso cs_eta Cq eta_q hf_iso FC SD PARA DIA TOT TDDFT_Eigenvalues Hugoniostat H-Compression H-Temperature H-Pressure H-Energy EFermi xrd_sf h k l Re(...) , Im(...) from output file The Test folder structure The CASTEP test folder is structured as follows: Test |- CMakeLists.txt |- jobconfig |- userconfig |- README |- List |- Electronic |- Cr-AFM |- Cr_00PBE.uspcc |- Cr_AFM.cell |- Cr_AFM.param |- benchmark.out.castep-23.1.castep-python-1.0.python-3.6.9.inp=Cr_AFM.param |- ELF |- Electrostatics ... |- XC ... The key files in the Test directory are: CMakeLists.txt CMake source file to build test suite in the CMake build system (see: Adding tests to be run ) jobconfig Essential file for testcode which defines the jobs, tolerances and categories of tests. userconfig Essential file for testcode which defines the commands to run tests and where to look for benchmarks. README Brief documentation detailing the purpose of the test suite and how to construct tests. The tests themselves are generally structured in the folder tree by a folder representing the general category of the tests and then a sub-folder for the specific test case. It is, however, possible to have multiple test cases within these sub-folders. The structure is used by testcode to determine which properties to check with which tolerances. Adding Tests Defining new tests What do tests look like? Tests in CASTEP are generally defined via a short CASTEP run (complete with .cell and .param files) which is: Sufficient to demonstrate the functionality in question Short enough that it does not take significant time to run Stable enough that the results do not change significantly from run to run. Note These calculations do not necessarily need to be physcially meaningful and in general should not, due to the time requirements. Adding tests to be run testcode runs tests according to two files contained in the Test directory . userconfig To add tests you should not need to touch userconfig , so we can ignore that here. jobconfig If we are adding a new test folder we need to modify jobconfig to include the new test folder, as well as define tolerances on the various properties we might measure within the tests. The structure of the jobconfig is as follows: # Run all tests on this folder and all subfolders with the given settings. [Electronic/*] run_concurrent = true # (1) tolerance = (0.015, None, 'Spin') # (2) # Override the settings of the general folder for a specific case. [Electronic/Si2-fine-grid] tolerance = (0.0003, None, 'Energy'), (0.0003, None, 'PS_Energy') Enable running tests within this folder in parallel. Set the tolerance for a given property . How to ensure stability CASTEP tests generally want to have a fixed seed using: rand_seed: 1234567890 Note The actual value of the rand_seed doesn't matter, only that it is fixed. The test should also generally be a short run of a small crystal structure to avoid any potential noise accumulating in the answer. The run does not need tight tolerances on E_{\\text{cut}} E_{\\text{cut}} or \\mathbf{k} \\mathbf{k} -point meshes, only sufficient to ensure that the answer produced is not noise itself. Adding Test Groups Adding to jobconfig At the end of the jobconfig file, there is a section called categories which contains the list of categories testcode knows about. The structure is: < category_name > := < path_to_tests > | < other categories > Note The can contain wildcards, or absolute paths Note All paths are relative to the location of jobconfig in CASTEP's case that is the /Test Example format of the categories [categories] spe-simple = Electronic/* bs-simple = Excitations/* phonon-simple = Phonon/* ... simple = spe-simple bs-simple phonon-simple [...] ... Adding to CMake To add the tests to be compatible with the CMake build system you need to modify the CMakeLists.txt at Test/CMakeLists.txt and add the category to the list on line 157, which looks like: foreach ( CASTEP_TEST_CATEGORY \"spe\" \"bs\" \"phonon\" ... ) ADD_CATEGORY_TARGETS ( ${ CASTEP_TEST_CATEGORY } TRUE ) endforeach () Adding to Make To add the tests properly to the GNU make build system ) you need to modify the Makefile at Test/Makefile and add the category in several places. Add it to the list of .PHONY : .PHONY : check check - simple check - spe - simple ... and create an entry in the appropriate lists for each of the five classes of test jobs: check recheck benchmark compare diff to call your tests when the target is called e.g.: check-solvation : exe - exists prepare - clean $( TESTCODE ) $( QUIET_FLAG ) $( PARALLEL ) -e $( CASTEPEXE ) -c solvation-simple Note exe-exists and prepare-clean are to ensure that CASTEP is compiled and that any old test runs are cleared out before starting the tests.","title":"Testing"},{"location":"developer/adding_testing/#adding-tests","text":"Following the addition of a new feature or bugfix it is essential to add system and unit tests that demonstrate the functionality of said addition. This document describes the process of adding new tests to the system as well as implementing your own testing groups. Warning Before any code is accepted into CASTEP it must have tests to prove its functionality and robustness.","title":"Adding Tests"},{"location":"developer/adding_testing/#testcode","text":"CASTEP's test suite is built using the testcode testing platform. This handles all of the generation of benchmarks and comparisons in the test suite.","title":"testcode"},{"location":"developer/adding_testing/#valid-properties","text":"CASTEP's extract_results.pl can extract the following properties from the .castep files: Note Those in code-style are the names for the properties, those without are just divisions used here Energy PS_Energy FreeEnergy SolvationEnergy dEtot/dlogE Spin AbsSpin Force Stress Phonons Phonon-q Phonon Grad_q(f) Freq g(f) ir Raman Born Species Ion Born Permittivity Polarisability Permittivity epsilon(f) NLO_Chi2 Raman Raman_Tr Raman_II depolarisation Electric_constants Compliance_mat Mulliken Populations Species Ion s p d f Total Charge Hirshfeld populations Species Ion Hirshfeld Spin ELF Data elf_fmt gx gy gz ELF(chi) den_fmt gx gy gz density chdiff_fmt gx gy gz diff-den pot_fmt gx gy gz potential Band Structure kx ky kz weight Eigenvalue MD Data MD Labels from the block magres cs_iso cs_aniso cs_eta Cq eta_q hf_iso FC SD PARA DIA TOT TDDFT_Eigenvalues Hugoniostat H-Compression H-Temperature H-Pressure H-Energy EFermi xrd_sf h k l Re(...) , Im(...) from output file","title":"Valid Properties"},{"location":"developer/adding_testing/#the-test-folder-structure","text":"The CASTEP test folder is structured as follows: Test |- CMakeLists.txt |- jobconfig |- userconfig |- README |- List |- Electronic |- Cr-AFM |- Cr_00PBE.uspcc |- Cr_AFM.cell |- Cr_AFM.param |- benchmark.out.castep-23.1.castep-python-1.0.python-3.6.9.inp=Cr_AFM.param |- ELF |- Electrostatics ... |- XC ... The key files in the Test directory are: CMakeLists.txt CMake source file to build test suite in the CMake build system (see: Adding tests to be run ) jobconfig Essential file for testcode which defines the jobs, tolerances and categories of tests. userconfig Essential file for testcode which defines the commands to run tests and where to look for benchmarks. README Brief documentation detailing the purpose of the test suite and how to construct tests. The tests themselves are generally structured in the folder tree by a folder representing the general category of the tests and then a sub-folder for the specific test case. It is, however, possible to have multiple test cases within these sub-folders. The structure is used by testcode to determine which properties to check with which tolerances.","title":"The Test folder structure"},{"location":"developer/adding_testing/#adding-tests_1","text":"","title":"Adding Tests"},{"location":"developer/adding_testing/#defining-new-tests","text":"","title":"Defining new tests"},{"location":"developer/adding_testing/#what-do-tests-look-like","text":"Tests in CASTEP are generally defined via a short CASTEP run (complete with .cell and .param files) which is: Sufficient to demonstrate the functionality in question Short enough that it does not take significant time to run Stable enough that the results do not change significantly from run to run. Note These calculations do not necessarily need to be physcially meaningful and in general should not, due to the time requirements.","title":"What do tests look like?"},{"location":"developer/adding_testing/#adding-tests-to-be-run","text":"testcode runs tests according to two files contained in the Test directory .","title":"Adding tests to be run"},{"location":"developer/adding_testing/#userconfig","text":"To add tests you should not need to touch userconfig , so we can ignore that here.","title":"userconfig"},{"location":"developer/adding_testing/#jobconfig","text":"If we are adding a new test folder we need to modify jobconfig to include the new test folder, as well as define tolerances on the various properties we might measure within the tests. The structure of the jobconfig is as follows: # Run all tests on this folder and all subfolders with the given settings. [Electronic/*] run_concurrent = true # (1) tolerance = (0.015, None, 'Spin') # (2) # Override the settings of the general folder for a specific case. [Electronic/Si2-fine-grid] tolerance = (0.0003, None, 'Energy'), (0.0003, None, 'PS_Energy') Enable running tests within this folder in parallel. Set the tolerance for a given property .","title":"jobconfig"},{"location":"developer/adding_testing/#how-to-ensure-stability","text":"CASTEP tests generally want to have a fixed seed using: rand_seed: 1234567890 Note The actual value of the rand_seed doesn't matter, only that it is fixed. The test should also generally be a short run of a small crystal structure to avoid any potential noise accumulating in the answer. The run does not need tight tolerances on E_{\\text{cut}} E_{\\text{cut}} or \\mathbf{k} \\mathbf{k} -point meshes, only sufficient to ensure that the answer produced is not noise itself.","title":"How to ensure stability"},{"location":"developer/adding_testing/#adding-test-groups","text":"","title":"Adding Test Groups"},{"location":"developer/adding_testing/#adding-to-jobconfig","text":"At the end of the jobconfig file, there is a section called categories which contains the list of categories testcode knows about. The structure is: < category_name > := < path_to_tests > | < other categories > Note The can contain wildcards, or absolute paths Note All paths are relative to the location of jobconfig in CASTEP's case that is the /Test Example format of the categories [categories] spe-simple = Electronic/* bs-simple = Excitations/* phonon-simple = Phonon/* ... simple = spe-simple bs-simple phonon-simple [...] ...","title":"Adding to jobconfig"},{"location":"developer/adding_testing/#adding-to-cmake","text":"To add the tests to be compatible with the CMake build system you need to modify the CMakeLists.txt at Test/CMakeLists.txt and add the category to the list on line 157, which looks like: foreach ( CASTEP_TEST_CATEGORY \"spe\" \"bs\" \"phonon\" ... ) ADD_CATEGORY_TARGETS ( ${ CASTEP_TEST_CATEGORY } TRUE ) endforeach ()","title":"Adding to CMake"},{"location":"developer/adding_testing/#adding-to-make","text":"To add the tests properly to the GNU make build system ) you need to modify the Makefile at Test/Makefile and add the category in several places. Add it to the list of .PHONY : .PHONY : check check - simple check - spe - simple ... and create an entry in the appropriate lists for each of the five classes of test jobs: check recheck benchmark compare diff to call your tests when the target is called e.g.: check-solvation : exe - exists prepare - clean $( TESTCODE ) $( QUIET_FLAG ) $( PARALLEL ) -e $( CASTEPEXE ) -c solvation-simple Note exe-exists and prepare-clean are to ensure that CASTEP is compiled and that any old test runs are cleared out before starting the tests.","title":"Adding to Make"},{"location":"developer/build-system/","text":"The CASTEP Build Sytem Introduction This documentation is intended for developers who intend to add new features/sources to the CASTEP system. A quick-start guide on how to build CASTEP can be found in the CASTEP_ROOT in README.INSTALL for the GNU Make build-system or README.cmake for the new CMake build system. The CASTEP build system is designed to be efficient, but also intuitive. There are two existing build systems, one relying on GNU Make, which is faster to build and intended for rapid development, and one based on CMake which is designed to be more intuitive to those who are used to CMake build systems and for automatically detecting the best options for the average user. CASTEP directory structure When adding new sources to CASTEP it is important to consider the hierarchical directory/module structure of CASTEP. CASTEP sources are currently organised into sub-libraries which each depend on the library above them in the hierarchy. These libraries, in order of hierarchy are: Utility Fundamental OTFG Dispersion Functional There are also Tools which are separately built programs which depend on the CASTEP sub-libraries. GNU Make The GNU make build system is broken down into a hierarchical tree which build up the required rules for compiling CASTEP on as many varied systems as possible while still being isolated and maintable. The hierarchy of these make files is as follows: \u251c `/` \u2514\u2500\u252c\u2500 `Makefile` - Root Makefile \u251c\u2500 `obj/` \u2514\u2500\u2500\u252c\u2500 `include_rules.mk` \u251c\u2500 `include_utility.mk` \u251c\u2500 `include_fundamental.mk` \u251c\u2500 `include_otfg.mk` \u251c\u2500 `include_dispersion.mk` \u251c\u2500 `include_functional.mk` \u251c\u2500 `include_test.mk` \u251c\u2500 `include_tools.mk` \u251c\u2500 `platforms/` \u2514\u2500\u2500\u2500\u2500 Various make rules for different platforms CMake The CMake system is designed to be intuitive for those who are used to CMake build systems while still being familiar to those who are used to the CASTEP GNU Make style syntax. This means that many of the CASTEP CMake variables have names which are chosen to match, or are aliased to, the CASTEP GNU Make variables. This is intended to minimise confusion for people who transition from GNU Make to CMake. The CMake system is also intended to expand the capabilities of CASTEP to be able to compile and run efficiently on Windows systems. Adding New Source Files In order to add new sources to CASTEP, first it is necessary to work out the relevant dependencies and where they fit into the directory structure (i.e. the CASTEP sub-libraries). Adding to GNU Make build-system Following this the source should be added to the relevant obj/include_.mk SRCS_$(D) . This will automatically include your new source in the CASTEP sub-library. Adding to the CMake build-system The next step is to navigate into the sub-library folder which contains your new source and add the source file into the CMakeLists.txt therein. Conditional inclusion If your source file provides functions which should only conditionally be included in CASTEP (e.g. interfaces to external libraries), then it must provide stub functions (generally no-op s returning relevant arguments) in order that the conditional inclusions can be compiled. These are generally saved as source_name.stub.f90 and these must be conditionally included into the compilation. Adding to GNU Make build-system First off, it is important to add a conditional into the relevant obj/include_.mk to include either your stub or your main source into the compilation. obj/include_.mk ifeq (${MY_LIBRARY_VAR},none) SRCS_$(d) := $(SRCS_$(d)) source_name.stub.f90 else SRCS_$(d) := $(SRCS_$(d)) source_name.f90 endif If extra libraries are needed to be conditionally linked these should be added as follows: obj/include_rules.mk ifneq (${MY_LIBRARY_VAR},none) ifneq ($(strip $(MY_LIB_REL_LIB_DIR)), ) CASTEP_LIB_SEARCH_PATH += -L\"../$(MY_LIB_REL_LIB_DIR)\" ifdef SUN CASTEP_LIB_SEARCH_PATH += -R \"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef NAG CASTEP_LIB_SEARCH_PATH += -Wl,-Wl,,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef LINUX CASTEP_LIB_SEARCH_PATH += -Wl,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" endif LIBS += -lmy_extra_lib endif Adding to CMake build-system The process with the CMake is similar, create a variable which selects either your source or stub based on an option. e.g. CASTEP_ROOT/CMakeLists.txt option(WITH_MY_LIB \"my lib's features\") cmake/extralibs.cmake if(WITH_MY_LIB) set(MY_LIB_MOD source_name.f90) else() set(MY_LIB_MOD source_name.stub.f90) endif() SOURCE_DIR/CMakeLists.txt add_castep_lib(NAME sub_lib SRCS ... ${MY_LIB_MOD} ... ) If extra libraries are needed to be conditionally linked these should be added as follows: cmake/extralibs.cmake if(WITH_MY_LIB) find_library(my_extra_lib NAMES my_extra_lib HINTS ${EXTERNAL_MY_LIB} DOC \"Doc\") if (NOT my_extra_lib) message(FATAL_ERROR \"MY_EXTRA_LIB requested, but not found. Set EXTERNAL_MY_LIB to manually specify location of libraries (currently: '${EXTERNAL_MY_LIB}')\") endif() set(MY_EXTRA_LIB ${my_extra_lib}) set(MY_LIB_MOD source_name.f90) else() set(MY_EXTRA_LIB \"\") set(MY_LIB_MOD source_name.stub.f90) endif() ... mark_as_advanced(... my_extra_lib) SOURCE_DIR/CMakeLists.txt target_link_libraries(sub-lib ... ${MY_EXTRA_LIB}) Special Compilation Options If you need to add special per-file compilation options, first you should check that your code is properly standards conforming. Failing that, it is possible to override options by setting them up in each platform, however, this is discouraged unless absolutely necessary. Adding to GNU Make build-system In the GNU make system it is necessary to add the special compilation flags to each relevant platform under the obj/platforms directory. e.g. obj/platforms/.mk .o: private OPT = -O2 Adding to CMake build-system In the CMake build system, flags are set up in the cmake/buildflags_.cmake files. To override flags, the set_special_flags function has been defined, which override flags for a particular build optimisation. set_special_flags(OPT FAST FILES .f90 FLAGS -O2)","title":"Build System"},{"location":"developer/build-system/#the-castep-build-sytem","text":"","title":"The CASTEP Build Sytem"},{"location":"developer/build-system/#introduction","text":"This documentation is intended for developers who intend to add new features/sources to the CASTEP system. A quick-start guide on how to build CASTEP can be found in the CASTEP_ROOT in README.INSTALL for the GNU Make build-system or README.cmake for the new CMake build system. The CASTEP build system is designed to be efficient, but also intuitive. There are two existing build systems, one relying on GNU Make, which is faster to build and intended for rapid development, and one based on CMake which is designed to be more intuitive to those who are used to CMake build systems and for automatically detecting the best options for the average user.","title":"Introduction"},{"location":"developer/build-system/#castep-directory-structure","text":"When adding new sources to CASTEP it is important to consider the hierarchical directory/module structure of CASTEP. CASTEP sources are currently organised into sub-libraries which each depend on the library above them in the hierarchy. These libraries, in order of hierarchy are: Utility Fundamental OTFG Dispersion Functional There are also Tools which are separately built programs which depend on the CASTEP sub-libraries.","title":"CASTEP directory structure"},{"location":"developer/build-system/#gnu-make","text":"The GNU make build system is broken down into a hierarchical tree which build up the required rules for compiling CASTEP on as many varied systems as possible while still being isolated and maintable. The hierarchy of these make files is as follows: \u251c `/` \u2514\u2500\u252c\u2500 `Makefile` - Root Makefile \u251c\u2500 `obj/` \u2514\u2500\u2500\u252c\u2500 `include_rules.mk` \u251c\u2500 `include_utility.mk` \u251c\u2500 `include_fundamental.mk` \u251c\u2500 `include_otfg.mk` \u251c\u2500 `include_dispersion.mk` \u251c\u2500 `include_functional.mk` \u251c\u2500 `include_test.mk` \u251c\u2500 `include_tools.mk` \u251c\u2500 `platforms/` \u2514\u2500\u2500\u2500\u2500 Various make rules for different platforms","title":"GNU Make"},{"location":"developer/build-system/#cmake","text":"The CMake system is designed to be intuitive for those who are used to CMake build systems while still being familiar to those who are used to the CASTEP GNU Make style syntax. This means that many of the CASTEP CMake variables have names which are chosen to match, or are aliased to, the CASTEP GNU Make variables. This is intended to minimise confusion for people who transition from GNU Make to CMake. The CMake system is also intended to expand the capabilities of CASTEP to be able to compile and run efficiently on Windows systems.","title":"CMake"},{"location":"developer/build-system/#adding-new-source-files","text":"In order to add new sources to CASTEP, first it is necessary to work out the relevant dependencies and where they fit into the directory structure (i.e. the CASTEP sub-libraries).","title":"Adding New Source Files"},{"location":"developer/build-system/#adding-to-gnu-make-build-system","text":"Following this the source should be added to the relevant obj/include_.mk SRCS_$(D) . This will automatically include your new source in the CASTEP sub-library.","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-the-cmake-build-system","text":"The next step is to navigate into the sub-library folder which contains your new source and add the source file into the CMakeLists.txt therein.","title":"Adding to the CMake build-system"},{"location":"developer/build-system/#conditional-inclusion","text":"If your source file provides functions which should only conditionally be included in CASTEP (e.g. interfaces to external libraries), then it must provide stub functions (generally no-op s returning relevant arguments) in order that the conditional inclusions can be compiled. These are generally saved as source_name.stub.f90 and these must be conditionally included into the compilation.","title":"Conditional inclusion"},{"location":"developer/build-system/#adding-to-gnu-make-build-system_1","text":"First off, it is important to add a conditional into the relevant obj/include_.mk to include either your stub or your main source into the compilation. obj/include_.mk ifeq (${MY_LIBRARY_VAR},none) SRCS_$(d) := $(SRCS_$(d)) source_name.stub.f90 else SRCS_$(d) := $(SRCS_$(d)) source_name.f90 endif If extra libraries are needed to be conditionally linked these should be added as follows: obj/include_rules.mk ifneq (${MY_LIBRARY_VAR},none) ifneq ($(strip $(MY_LIB_REL_LIB_DIR)), ) CASTEP_LIB_SEARCH_PATH += -L\"../$(MY_LIB_REL_LIB_DIR)\" ifdef SUN CASTEP_LIB_SEARCH_PATH += -R \"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef NAG CASTEP_LIB_SEARCH_PATH += -Wl,-Wl,,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef LINUX CASTEP_LIB_SEARCH_PATH += -Wl,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" endif LIBS += -lmy_extra_lib endif","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-cmake-build-system","text":"The process with the CMake is similar, create a variable which selects either your source or stub based on an option. e.g. CASTEP_ROOT/CMakeLists.txt option(WITH_MY_LIB \"my lib's features\") cmake/extralibs.cmake if(WITH_MY_LIB) set(MY_LIB_MOD source_name.f90) else() set(MY_LIB_MOD source_name.stub.f90) endif() SOURCE_DIR/CMakeLists.txt add_castep_lib(NAME sub_lib SRCS ... ${MY_LIB_MOD} ... ) If extra libraries are needed to be conditionally linked these should be added as follows: cmake/extralibs.cmake if(WITH_MY_LIB) find_library(my_extra_lib NAMES my_extra_lib HINTS ${EXTERNAL_MY_LIB} DOC \"Doc\") if (NOT my_extra_lib) message(FATAL_ERROR \"MY_EXTRA_LIB requested, but not found. Set EXTERNAL_MY_LIB to manually specify location of libraries (currently: '${EXTERNAL_MY_LIB}')\") endif() set(MY_EXTRA_LIB ${my_extra_lib}) set(MY_LIB_MOD source_name.f90) else() set(MY_EXTRA_LIB \"\") set(MY_LIB_MOD source_name.stub.f90) endif() ... mark_as_advanced(... my_extra_lib) SOURCE_DIR/CMakeLists.txt target_link_libraries(sub-lib ... ${MY_EXTRA_LIB})","title":"Adding to CMake build-system"},{"location":"developer/build-system/#special-compilation-options","text":"If you need to add special per-file compilation options, first you should check that your code is properly standards conforming. Failing that, it is possible to override options by setting them up in each platform, however, this is discouraged unless absolutely necessary.","title":"Special Compilation Options"},{"location":"developer/build-system/#adding-to-gnu-make-build-system_2","text":"In the GNU make system it is necessary to add the special compilation flags to each relevant platform under the obj/platforms directory. e.g. obj/platforms/.mk .o: private OPT = -O2","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-cmake-build-system_1","text":"In the CMake build system, flags are set up in the cmake/buildflags_.cmake files. To override flags, the set_special_flags function has been defined, which override flags for a particular build optimisation. set_special_flags(OPT FAST FILES .f90 FLAGS -O2)","title":"Adding to CMake build-system"},{"location":"developer/git_workflow/","text":"Draft bitbucket/git workflow for CASTEP developers: NB: Not a git tutorial! Bitbucket web - create fork (\u201cmyfork\u201d for this example) Make fork visible to CDG (bitbucket group, very least to dominik.jochym@stfc.ac.uk so that the CI works) Clone to local machine git clone git@bitbucket.org:mybitbucket/castep-myfork.git castep-myfork Setup local githook (see readme in .githooks) Configure remote \u201cmyfork\u201d and \u201cupstream\u201d: git remote add upstream git@bitbucket.org:castep/castep.git git remote add myfork git@bitbucket.org:mybitbucket/castep-myfork.git Can verify remotes with git remote -v (useful to have more remote aliases if you want to check out a branch on someone else\u2019s fork) Name branch git branch foo Switch to branch git switch foo (Stage and) Commit changes git commit -m \u201cCool stuff\u201d If planned destination branch (usually default) has changed: Fetch from official git fetch upstream default:default [NB: reference to \u201cupstream\u201d might be different if your remote aliases are configured differently]. This not only performs the fetch but also updates the local \"default\" branch to sync with the upstream. Rebase using destination (default) branch git rebase default . This makes it so that your changes are sitting on top of the latest \u201cofficial\u201d default. If your branch contains many PRs it may be better to \"squash\", using the bitbucket merge option \"squash merge\", or git rebase -i default and then in your editor, leave the first line as 'pick ....' and then change all subsequent lines from 'pick ...' to 'squash ...'. Save the file and then you will get a squashed history for this PR. Fix conflicts if needed git mergetool tool=kdiff3 [kdiff3 is just my personal preference] and then: git rebase --continue (and commit) Push branch to fork ( git push myfork foo ) This is a very good habit to get used to: always specify the remote and branch so you know exactly what you\u2019re trying to push and where! Synchronise your fork\u2019s default branch with upstream: git push myfork default Create pull request (bitbucket web, from fork) \"Delete this branch after merge\" should be checked in most cases. The exception is with long-term development branches and release branches. If another PR is merged first, you have two choices: Do NOT click \u201cSync now\u201d on the PR page as this does a merge and commit, which breaks our --ffonly policy At your local clone, go back to step 9 Similar to step 10, except this is a \u201cforce\u201d push as the rebase has changed the commit history: git push --force myfork foo git push myfork default On the website interface, click \"merge\". Then change the merge strategy to \"Squash\". You will then get an opportunity to edit the commit message. Switch back to the default branch git switch default. Do not do any further work on your foo branch and attempt any merging, or you risk creating a \"spaghetti\" of loops in the commit graph. You may re-use the name of your branch if you delete the old one with git branch -D .","title":"Git workflow"},{"location":"developer/release_procedure/","text":"CASTEP new release procedure Initial setup Open an issue containing this checklist Open bug fix/release branch Cherry pick appropriate bug-fixes from default Update version number in license.F90 Ensure BIOVIA release is tagged Functionality Check OTFG features exposed in cell Check CI Create dedicated pipeline for release branch on ANVIL Run full build tests on Make and CMake Check make dist works -- Including unpacking and building from dist only! Check that cmake -t dist also compiles and includes everything Ensure checkpoints forward & backward compatible Ensure compatibility between Academic and BIOVIA releases Check CASTEP builds and runs on ARCHER2 -- Both GNU and CMake Check GPU build on Tier-1 machines -- Both GNU and CMake Check supported compilers for oldest and latest and update README.install appropriately External Libraries Check linked/included library versions for updates Current libraries: dl_mg simple-dftd3 d4 spglib libxc FoxXML External Tools Checked shipped versions of third-party tools and utilities for updates Current tools: c2x cif2cell optados BoltzTrap SHengBTE emc atat elastic_constants Update emacs_mode keys for most recent keywords Check that version requirement of Python components and utilities are still up to date Documentation Check and update README.install docs Update release notes Update version in Ford Docs Check new parameters (cell and param keywords) New parameters have correct help text New parameters are documented in the manual Licences Update checksums file Upload appropriately to licences.stfc.ac.uk Finalisation Tag final release commit Pre-notify HPC providers of release Notify mailing list of release Update castep.org with latest info Check release branch for build system and documentation updates and back-port to default branch if needed","title":"Release Procedure"},{"location":"developer/release_procedure/#castep-new-release-procedure","text":"","title":"CASTEP new release procedure"},{"location":"developer/release_procedure/#initial-setup","text":"Open an issue containing this checklist Open bug fix/release branch Cherry pick appropriate bug-fixes from default Update version number in license.F90 Ensure BIOVIA release is tagged","title":"Initial setup"},{"location":"developer/release_procedure/#functionality","text":"Check OTFG features exposed in cell Check CI Create dedicated pipeline for release branch on ANVIL Run full build tests on Make and CMake Check make dist works -- Including unpacking and building from dist only! Check that cmake -t dist also compiles and includes everything Ensure checkpoints forward & backward compatible Ensure compatibility between Academic and BIOVIA releases Check CASTEP builds and runs on ARCHER2 -- Both GNU and CMake Check GPU build on Tier-1 machines -- Both GNU and CMake Check supported compilers for oldest and latest and update README.install appropriately","title":"Functionality"},{"location":"developer/release_procedure/#external-libraries","text":"Check linked/included library versions for updates Current libraries: dl_mg simple-dftd3 d4 spglib libxc FoxXML","title":"External Libraries"},{"location":"developer/release_procedure/#external-tools","text":"Checked shipped versions of third-party tools and utilities for updates Current tools: c2x cif2cell optados BoltzTrap SHengBTE emc atat elastic_constants Update emacs_mode keys for most recent keywords Check that version requirement of Python components and utilities are still up to date","title":"External Tools"},{"location":"developer/release_procedure/#documentation","text":"Check and update README.install docs Update release notes Update version in Ford Docs Check new parameters (cell and param keywords) New parameters have correct help text New parameters are documented in the manual","title":"Documentation"},{"location":"developer/release_procedure/#licences","text":"Update checksums file Upload appropriately to licences.stfc.ac.uk","title":"Licences"},{"location":"developer/release_procedure/#finalisation","text":"Tag final release commit Pre-notify HPC providers of release Notify mailing list of release Update castep.org with latest info Check release branch for build system and documentation updates and back-port to default branch if needed","title":"Finalisation"},{"location":"developer/style_guide/","text":"Introduction The CASTEP code has been designed from conception to achieve various goals - including efficiency and maintainability. The following are some simple guidelines on writing code for inclusion within CASTEP. These are intended to enable the writing of correct, efficient code, and to ensure a consistent style for multiple authors throughout the code that is straightforward for others to maintain in the future. Fortran 2003 has been chosen as the language that all the code will be written in, as it has many modern features which enable the writing of clean, modular code without compromising efficiency and portability. In this document, there is a template for writing modules , and for writing subprograms within a module. These templates are designed to enforce good programming practice and documentation of routine function and side-effects. It is important that all routines be written with these templates. The general guidelines about style addressed here, the use of module templates, the completeness of the documentation, etc. all help to make writing new code and maintaining the existing code a simple task. It is also the programmer's responsibility to ensure that each routine is coded as efficiently as possible. Whilst it is tempting to use some of the new built-in features of Fortran 2003, experience has shown that discretion is required in their usage so as not to compromise efficiency. Therefore, guidelines on the use of such features has also been included. CASTEP linter The CASTEP linter is a Python tool which checks your CASTEP build for any issues related to the CASTEP style. It should be used after making any major modifications. Note The linter is also run on the CASTEP CI system and will warn you if any new issues arise from your modifications. Should any new issues be in your PR, it may not be accepted. Using the CASTEP linter The linter is available on PyPI and can be installed on your system using pip : python -m pip install castep-linter Following the install, it should be possible to run the linter by running: castep-lint e.g. castep-lint Source/Functional/pair_pot.f90 For further information, type castep-lint -h It is also possible to use the CASTEP linter in emacs through a flycheck extension . To use this you must install the flycheck package which can be done through the MELPA emacs package repository. Writing to the Specification Document \"It does exactly what it says on the tin\" Obviously, it is of paramount importance to make sure that any routine that you are responsible for does exactly what the specification says that it should do, particularly with regard to exit conditions, side-effects, etc. Routines and variables that are covered by the specification are public whilst other routines and variables are private . The specification says nothing about the r\u00f4le or meaning of private routines. Private routines and variables are only accessible within the module in which they occur. Do not assume anything that is not written in the specification document If the specification does not say that a particular routine will preserve the input values on exit, then you cannot presume that whoever coded it will do likewise! Even if that routine was written by you... Similarly, it may seem obvious that a particular variable has a particular meaning, but if it is not defined in the specification, then it cannot be presumed. Future revisions of the code may change non-specified routines freely. If all code sticks to the specification at all times, then maintaining the code is much simpler. Note that the specification does not say anything about private routines or variables in any module. For this reason, great care must be taken when using such routines. The subprogram template is there to remind you to document all side-effects of each routine! Code robustly for errors That is, the user should never see a Fortran run-time error message - your code should check for possible error conditions, and either correct the error or print a nice, meaningful error message and do a graceful exit via io_abort . Conditions on execution Conditions given in the specification must be true for correct execution of each routine. Obviously, these should be tested for to ensure correctness, but this may introduce a considerable performance penalty, particularly for Utility or Fundamental routines. For this reason, it is recommended to use a single #ifdef debug block at the start of each routine to test these conditions where appropriate and call io_abort as necessary. The code can then be compiled either with or without full error checking as appropriate. Errors and Warnings Use stderr from any node Unlike normal messages, any node can write an error or warning message. Any such message is to be written to stderr from the relevant node. The routine shall then call io_abort to terminate the program neatly. Use iprint consistently Normal output, including warning messages and debugging information, should only by written to stdout by the root node. The level of detail is controlled by the iprint variable: 0 - Minimal output - just the basic parameters controlling the run and the answers! 1 - Default output - breakdown of energies and forces into components, etc. but no debugging output. 2 - Minimal debugging - values of all significant parameters, etc. Not printing all the arrays. 3 - Maximal debugging - the works! Efficiency Issues Libraries The use of BLAS and LAPACK libraries are recommended, as these are freely available libraries and often come in vendor-optimised versions for each platform. For efficiency, it is also recommended that you do not use BLAS \"level 0 routines\" as there are little efficiency gains to be made, and the equivalent fortran is often much neater and easier to read. Fortran array intrinsics Beware the use of fortran array intrinsics - they can be inefficient and may cause memory problems, e.g. result=matmul(a,matmul(b,c)) requires an implicit dynamic memory allocation. Wherever practical use BLAS instead. Some intrinsics may also impede compiler optimisation, particularly on a vector machine. Similarly, do not use functions such as transfer or mold - these can be very inefficient. Passing arrays to subprograms This is a tricky subject, which can easily lead to confusion and inefficient code. The main problem is that there are multiple ways of passing arrays, and these are not in general equivalent! The best practice is to always pass the whole array together with its size, such as: call foo ( int_array , N1 , N2 ) ... subroutine foo ( int_array , N1 , N2 ) implicit none integer , intent ( in ) :: N1 , N2 integer , dimension ( 1 : N1 , 1 : N2 ) :: int_array ... as this does not cause any copying of the array and allows the compiler to do bound-checking etc. The use of assumed-shape arrays , such as int_array(:, :) is less efficient as this has an explicit rank, but an implicit shape. This requires the use of functions such as size(int_array,1) and may prevent certain compiler optimisations. However, it does allow the compiler to do bound-checking. Care must be taken in passing the array though. If an array section is to be passed then it is much better to use assumed-size arrays (i.e. the old fashioned way), that is call foo2 ( int_array ( 1 , N )) ... subroutine foo2 ( int_array ) implicit none integer , dimension ( * ) :: int_array ... than to pass int_array(:, N) and receive int_array(:) as this will create a copy of the array on the stack which will rapidly lead to \"out of memory\" errors. The use of assumed-size arrays, such as int_array(*) is useful if you want to write a general purpose routine that will work with any size and/or rank array. Note however, that it will not in general work with scalars, nor does it allow bounds-checking. However, it does not cause the creation of any copies of the array. Machine-Specific Code Avoid! Write in standard fortran without vendor extensions and without using any system routines wherever possible, for maximum portability. The one exception that is allowed to this is in the Utility modules, where all the low-level input/output and communications are handled. Test thoroughly to prevent Always test your routines on several different platforms and with several different compilers to be sure that you have not inadvertently relied upon some default behaviour of one specific compiler. The CI system will handle compilation for all supported compilers once submitted as a merge request into the Bitbucket repository, but these should be performed beforehand to minimise the effort in bugfixing. File handling One obvious area of machine dependency is that of file handling. For this reason, the io module should be used to handle the opening of all files. The programmer is responsible for reading / writing the data and closing the file. Files are not to be kept open for any longer than strictly necessary. Compiler/preprocessor directives These should be avoided wherever possible as they hinder portability. They should only be used in the Utility modules for machine specific code. All module filenames should be given the extension .f90 , with the exception of Utility modules, where .F90 is permitted, but generally only if preproccesing is used. Fortran90 Features Use of dynamic arrays Each routine is responsible for allocating/using/deallocating its own workspace. We recommend that such allocate / deallocate s only occur once in a routine - never inside a loop as this will produce a significant performance penalty. You must ensure that you always deallocate local work arrays on termination of the routine. Obviously, care needs to be taken if there are multiple exit points from a routine. Pointers Always accept passed arrays in subprograms as arrays and not as pointers. This will force automatic dereferencing of the array and enable better optimisations by the compiler. Flow of control Use of constructs such as select case and do ... end do , with labelling of \"do loops\", etc. is recommended for clarity. Use of cycle and exit is OK - but only use to move a maximum of one level of nesting where possible. Do NOT use goto . Functions A function subprogram should be \"pure\", i.e. generate no side-effects through modification of variables in argument list or module variables through \"use association\". Avoid recursion. Use of use Use modules with an only clause if only a small number of variables required. Put appropriate use statements into each subroutine required, NOT into the module header, in order to keep track of module variable modification. Line numbers Avoid where possible. Line numbers are only to be used for format statements, and end= or err= in file handling. Do not use continue . General features Avoid multiple statement lines unless trivially simple. Modules General All code is to be contained within modules. Usage Each module described in the specification is to be one source file. All routines given in the specification for this module are to be in this file. Auxiliary modules CASTEP also encourages the use of the more recent (Fortran 2008) submodule s. Submodules allow the programmatic subdivision of a module enabling the compiler to precompile interfaces, reduce required compilation if only the submodule has changed and allowing the developer to more effectively control scope of module internals. For clarity, and to keep the module from being excessively long, the module may also use auxiliary modules, which can be in separate files (again with one file per module). Any auxiliary modules must be used in only one specified module, i.e. no auxiliary code reuse in other specified modules as the auxiliary routines are not specified! The naming convention of any auxiliary modules is to be inherited from the specified module to make it clear where the auxiliary routines are to be used, e.g. if the specified module is called me.F90 with routines called me_sub , etc. then an auxiliary module would be me_extra.F90 with routines called me_extra_sub , etc. Note Rather than using full auxilliary modules in modern CASTEP, submodule s are encouraged. Style and Layout Use the module template The module template gives the recommended layout for a module and for a subprogram. This is available in the CASTEP source at Source/template.f90 . In particular, note the layout and contents of the comment header, and the order of declarations. Everything is to be private unless explicitly specified as public! This also makes it simple to check the code against the specification. Layout All code is to use indentation as generated by GNU-Emacs f90-mode. Use any editor you like to create the code, but please ensure that whatever goes into the Bitbucket repository has been passed through Emacs f90-mode indentation at the finished stage. To assist in Emacs usage, the module template contains Emacs directives to set f90-mode, etc. Case Use lower case for keywords and use capitalisation as given in the specification for all routines and variables mentioned therein. For private routines and variables use lower case in general. However, you may use upper case to differentiate words within a name, e.g. userInputData - as long as you are consistent throughout the module. Use upper case, with stripped spaces, for the value of string variables that are passed between routines, e.g. run_type='MOLECULARDYNAMICS' not 'MolecularDynamics ' or 'molecular dynamics' etc. to simplify string comparisons. Names For clarity, don't change variable name on passing to a different routine wherever possible. Avoid short (1 or 2 letter) variable names except for simple loop counters. Use new form end subroutine name etc. not older form end subroutine . Types Do NOT use implicit typing. Similarly, you do not have to stick to the old rules for implicit typing - you can have integer names beginning with \" c \" etc! Do not give type as double precision - use real(kind=dp) instead, as dp is a constant in the Constants module and this will make porting to other architectures (e.g. Cray) much simpler. Remember that all machine-specific code stays in the Utility routines. Similarly, when declaring a constant, use 1.234_dp NOT 1.234d0 . Free format Use free-format f90, with a maximum line length of 132 characters. Spaces Use spaces between keywords e.g. end if not endif . Code cleanly Obviously, to ensure correctness and make it easier for others to maintain the code. If the obvious way to code a routine is inefficient, whilst the efficient way is obscure, then this is allowed as long as the routine is well documented internally, with a discussion as to the design decisions made. Be aware of vectorisation When coding, be aware that the code is almost always executed upon vector architectures. Therefore code with a style that enables good vectorisation - e.g. don't put if statements inside nested loops wherever possible. Documentation Internal Each module, based upon the module template , is to have a header block describing its overall purpose and function. Each routine, written to the template, is to have a header block describing its function, the variables required and how modified, the necessary conditions for correct operation, etc. These comments should be clear and easy to understand. Each routine is also to contain lots of comments within the code. Comments are to be either on the same line(s) as the feature being comment upon, or in a block of lines above the feature. Comment density should be comparable to code density. All comments are to be in English and obey standard rules of English grammar. External A module (or any modifications) is only considered complete when additional documentation has been supplied for inclusion. Documentation must be provided in the appropriate module and function header blocks, explaining the function of the module and each routine, the physics behind the code, the algorithms used, the key variables and data structures, and appropriate references to the literature. Testing Test Program Each module shall be tested for correctness before being added to the Bitbucket repository. To this end a set of tests shall be provided, which must compile and execute correctly in the CI system. The purpose of these tests is to verify the correct operation of every specified routine in the module. CASTEP uses the testcode testing platform which allows automated generation of benchmark data from a set of valid CASTEP input files. Please see Testing for more information on how to do this. Reference data The module test program shall come with both appropriate input datafiles and reference output results. Correct operation of the test shall be verified by comparing the actual output against the reference output results. Module Template General Note particularly the order of declaration, use of implicit none and private , and the standard comment header, for internal documentation. All lines in comment headers are to be 80 characters wide. Not all sections of the header will be relevant to all subprograms and so can be deleted. It is very important that the header is kept up-to-date and as complete as possible. Use of public and private Each module uses an initial private statement to force all entities in the module to be private by default. Then have explicit public statements to expose those datatypes, variables and (overloaded) routine names, as listed in the specification document. This makes it easy to compare the code to the specification document. Template ! -*- mode: F90 ; mode: font-lock ; column-number-mode: true ; vc-back-end: git -*- !=============================================================================! ! D U M M Y ! !=============================================================================! ! Overall explanation of purpose and function of module. ! ! ! !-----------------------------------------------------------------------------! ! Written from \"Module Specification for New Plane Wave Code\", M. Segall, ! ! P. Lindan, M. Probert, C. Pickard, P. Hasnip, S. Clark and M. Payne ! ! Copyright 1999/2000 ! !-----------------------------------------------------------------------------! ! Written by author, version, date ! !-----------------------------------------------------------------------------! ! ! ! ! !=============================================================================! module dummy use constants , only : dp !Minimal useage where practical implicit none !Impose strong typing private !Everything is private ... !---------------------------------------------------------------------------! ! P u b l i c R o u t i n e s ! !---------------------------------------------------------------------------! public :: routine_name ... !... unless exposed here. interface routine_name !Overloaded routines, etc. ... !(specific names are private) end interface !---------------------------------------------------------------------------! ! P u b l i c V a r i a b l e s ! !---------------------------------------------------------------------------! public datatypes ... public variables ... !---------------------------------------------------------------------------! ! P r i v a t e R o u t i n e s ! !---------------------------------------------------------------------------! !---------------------------------------------------------------------------! ! P r i v a t e V a r i a b l e s ! !---------------------------------------------------------------------------! datatypes ... !Private data for all routines variables .. !in this module ... ... contains subroutine public1 ( var1 , var2 ,...) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! !-------------------------------------------------------------------------! ! Arguments: ! ! var1, intent, meaning ! ! ... (in order of call list) ! !-------------------------------------------------------------------------! ! Parent module variables used: ! ! globalvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Modules used: ! ! other_module used, ! ! other_vars, meanings, changes ! ! ... ! !-------------------------------------------------------------------------! ! Key Internal Variables: ! ! intvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Necessary conditions: ! ! ... ! !-------------------------------------------------------------------------! ! Written by author, version, date ! !=========================================================================! use my_module , only : some_other_function use other_module , only : other_var1 implicit none integer , intent ( in ), dimension (:,:) :: var1 !Variables in call order real ( kind = dp ), intent ( in ), parameter :: var2 ... ( other variables in call list ) real ( kind = dp ) :: my_var1 = 2.7182818_dp !base of natural logs complex ( kind = dp ), allocatable , dimension (:) :: my_work1 ... ( other internal variables ) ... ( condition checks ) ... ( actual code ) return end subroutine public1 ... ( other public subroutines ) subroutine private1 (....) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! ! (etc, as for public routines) ! !=========================================================================! .... end subroutine private1 end module dummy","title":"Style Guide"},{"location":"developer/style_guide/#introduction","text":"The CASTEP code has been designed from conception to achieve various goals - including efficiency and maintainability. The following are some simple guidelines on writing code for inclusion within CASTEP. These are intended to enable the writing of correct, efficient code, and to ensure a consistent style for multiple authors throughout the code that is straightforward for others to maintain in the future. Fortran 2003 has been chosen as the language that all the code will be written in, as it has many modern features which enable the writing of clean, modular code without compromising efficiency and portability. In this document, there is a template for writing modules , and for writing subprograms within a module. These templates are designed to enforce good programming practice and documentation of routine function and side-effects. It is important that all routines be written with these templates. The general guidelines about style addressed here, the use of module templates, the completeness of the documentation, etc. all help to make writing new code and maintaining the existing code a simple task. It is also the programmer's responsibility to ensure that each routine is coded as efficiently as possible. Whilst it is tempting to use some of the new built-in features of Fortran 2003, experience has shown that discretion is required in their usage so as not to compromise efficiency. Therefore, guidelines on the use of such features has also been included.","title":"Introduction"},{"location":"developer/style_guide/#castep-linter","text":"The CASTEP linter is a Python tool which checks your CASTEP build for any issues related to the CASTEP style. It should be used after making any major modifications. Note The linter is also run on the CASTEP CI system and will warn you if any new issues arise from your modifications. Should any new issues be in your PR, it may not be accepted.","title":"CASTEP linter"},{"location":"developer/style_guide/#using-the-castep-linter","text":"The linter is available on PyPI and can be installed on your system using pip : python -m pip install castep-linter Following the install, it should be possible to run the linter by running: castep-lint e.g. castep-lint Source/Functional/pair_pot.f90 For further information, type castep-lint -h It is also possible to use the CASTEP linter in emacs through a flycheck extension . To use this you must install the flycheck package which can be done through the MELPA emacs package repository.","title":"Using the CASTEP linter"},{"location":"developer/style_guide/#writing-to-the-specification-document","text":"","title":"Writing to the Specification Document"},{"location":"developer/style_guide/#it-does-exactly-what-it-says-on-the-tin","text":"Obviously, it is of paramount importance to make sure that any routine that you are responsible for does exactly what the specification says that it should do, particularly with regard to exit conditions, side-effects, etc. Routines and variables that are covered by the specification are public whilst other routines and variables are private . The specification says nothing about the r\u00f4le or meaning of private routines. Private routines and variables are only accessible within the module in which they occur.","title":"\"It does exactly what it says on the tin\""},{"location":"developer/style_guide/#do-not-assume-anything-that-is-not-written-in-the-specification-document","text":"If the specification does not say that a particular routine will preserve the input values on exit, then you cannot presume that whoever coded it will do likewise! Even if that routine was written by you... Similarly, it may seem obvious that a particular variable has a particular meaning, but if it is not defined in the specification, then it cannot be presumed. Future revisions of the code may change non-specified routines freely. If all code sticks to the specification at all times, then maintaining the code is much simpler. Note that the specification does not say anything about private routines or variables in any module. For this reason, great care must be taken when using such routines. The subprogram template is there to remind you to document all side-effects of each routine!","title":"Do not assume anything that is not written in the specification document"},{"location":"developer/style_guide/#code-robustly-for-errors","text":"That is, the user should never see a Fortran run-time error message - your code should check for possible error conditions, and either correct the error or print a nice, meaningful error message and do a graceful exit via io_abort .","title":"Code robustly for errors"},{"location":"developer/style_guide/#conditions-on-execution","text":"Conditions given in the specification must be true for correct execution of each routine. Obviously, these should be tested for to ensure correctness, but this may introduce a considerable performance penalty, particularly for Utility or Fundamental routines. For this reason, it is recommended to use a single #ifdef debug block at the start of each routine to test these conditions where appropriate and call io_abort as necessary. The code can then be compiled either with or without full error checking as appropriate.","title":"Conditions on execution"},{"location":"developer/style_guide/#errors-and-warnings","text":"","title":"Errors and Warnings"},{"location":"developer/style_guide/#use-stderr-from-any-node","text":"Unlike normal messages, any node can write an error or warning message. Any such message is to be written to stderr from the relevant node. The routine shall then call io_abort to terminate the program neatly.","title":"Use stderr from any node"},{"location":"developer/style_guide/#use-iprint-consistently","text":"Normal output, including warning messages and debugging information, should only by written to stdout by the root node. The level of detail is controlled by the iprint variable: 0 - Minimal output - just the basic parameters controlling the run and the answers! 1 - Default output - breakdown of energies and forces into components, etc. but no debugging output. 2 - Minimal debugging - values of all significant parameters, etc. Not printing all the arrays. 3 - Maximal debugging - the works!","title":"Use iprint consistently"},{"location":"developer/style_guide/#efficiency-issues","text":"","title":"Efficiency Issues"},{"location":"developer/style_guide/#libraries","text":"The use of BLAS and LAPACK libraries are recommended, as these are freely available libraries and often come in vendor-optimised versions for each platform. For efficiency, it is also recommended that you do not use BLAS \"level 0 routines\" as there are little efficiency gains to be made, and the equivalent fortran is often much neater and easier to read.","title":"Libraries"},{"location":"developer/style_guide/#fortran-array-intrinsics","text":"Beware the use of fortran array intrinsics - they can be inefficient and may cause memory problems, e.g. result=matmul(a,matmul(b,c)) requires an implicit dynamic memory allocation. Wherever practical use BLAS instead. Some intrinsics may also impede compiler optimisation, particularly on a vector machine. Similarly, do not use functions such as transfer or mold - these can be very inefficient.","title":"Fortran array intrinsics"},{"location":"developer/style_guide/#passing-arrays-to-subprograms","text":"This is a tricky subject, which can easily lead to confusion and inefficient code. The main problem is that there are multiple ways of passing arrays, and these are not in general equivalent! The best practice is to always pass the whole array together with its size, such as: call foo ( int_array , N1 , N2 ) ... subroutine foo ( int_array , N1 , N2 ) implicit none integer , intent ( in ) :: N1 , N2 integer , dimension ( 1 : N1 , 1 : N2 ) :: int_array ... as this does not cause any copying of the array and allows the compiler to do bound-checking etc. The use of assumed-shape arrays , such as int_array(:, :) is less efficient as this has an explicit rank, but an implicit shape. This requires the use of functions such as size(int_array,1) and may prevent certain compiler optimisations. However, it does allow the compiler to do bound-checking. Care must be taken in passing the array though. If an array section is to be passed then it is much better to use assumed-size arrays (i.e. the old fashioned way), that is call foo2 ( int_array ( 1 , N )) ... subroutine foo2 ( int_array ) implicit none integer , dimension ( * ) :: int_array ... than to pass int_array(:, N) and receive int_array(:) as this will create a copy of the array on the stack which will rapidly lead to \"out of memory\" errors. The use of assumed-size arrays, such as int_array(*) is useful if you want to write a general purpose routine that will work with any size and/or rank array. Note however, that it will not in general work with scalars, nor does it allow bounds-checking. However, it does not cause the creation of any copies of the array.","title":"Passing arrays to subprograms"},{"location":"developer/style_guide/#machine-specific-code","text":"","title":"Machine-Specific Code"},{"location":"developer/style_guide/#avoid","text":"Write in standard fortran without vendor extensions and without using any system routines wherever possible, for maximum portability. The one exception that is allowed to this is in the Utility modules, where all the low-level input/output and communications are handled.","title":"Avoid!"},{"location":"developer/style_guide/#test-thoroughly-to-prevent","text":"Always test your routines on several different platforms and with several different compilers to be sure that you have not inadvertently relied upon some default behaviour of one specific compiler. The CI system will handle compilation for all supported compilers once submitted as a merge request into the Bitbucket repository, but these should be performed beforehand to minimise the effort in bugfixing.","title":"Test thoroughly to prevent"},{"location":"developer/style_guide/#file-handling","text":"One obvious area of machine dependency is that of file handling. For this reason, the io module should be used to handle the opening of all files. The programmer is responsible for reading / writing the data and closing the file. Files are not to be kept open for any longer than strictly necessary.","title":"File handling"},{"location":"developer/style_guide/#compilerpreprocessor-directives","text":"These should be avoided wherever possible as they hinder portability. They should only be used in the Utility modules for machine specific code. All module filenames should be given the extension .f90 , with the exception of Utility modules, where .F90 is permitted, but generally only if preproccesing is used.","title":"Compiler/preprocessor directives"},{"location":"developer/style_guide/#fortran90-features","text":"","title":"Fortran90 Features"},{"location":"developer/style_guide/#use-of-dynamic-arrays","text":"Each routine is responsible for allocating/using/deallocating its own workspace. We recommend that such allocate / deallocate s only occur once in a routine - never inside a loop as this will produce a significant performance penalty. You must ensure that you always deallocate local work arrays on termination of the routine. Obviously, care needs to be taken if there are multiple exit points from a routine.","title":"Use of dynamic arrays"},{"location":"developer/style_guide/#pointers","text":"Always accept passed arrays in subprograms as arrays and not as pointers. This will force automatic dereferencing of the array and enable better optimisations by the compiler.","title":"Pointers"},{"location":"developer/style_guide/#flow-of-control","text":"Use of constructs such as select case and do ... end do , with labelling of \"do loops\", etc. is recommended for clarity. Use of cycle and exit is OK - but only use to move a maximum of one level of nesting where possible. Do NOT use goto .","title":"Flow of control"},{"location":"developer/style_guide/#functions","text":"A function subprogram should be \"pure\", i.e. generate no side-effects through modification of variables in argument list or module variables through \"use association\". Avoid recursion.","title":"Functions"},{"location":"developer/style_guide/#use-of-use","text":"Use modules with an only clause if only a small number of variables required. Put appropriate use statements into each subroutine required, NOT into the module header, in order to keep track of module variable modification.","title":"Use of use"},{"location":"developer/style_guide/#line-numbers","text":"Avoid where possible. Line numbers are only to be used for format statements, and end= or err= in file handling. Do not use continue .","title":"Line numbers"},{"location":"developer/style_guide/#general-features","text":"Avoid multiple statement lines unless trivially simple.","title":"General features"},{"location":"developer/style_guide/#modules","text":"","title":"Modules"},{"location":"developer/style_guide/#general","text":"All code is to be contained within modules.","title":"General"},{"location":"developer/style_guide/#usage","text":"Each module described in the specification is to be one source file. All routines given in the specification for this module are to be in this file.","title":"Usage"},{"location":"developer/style_guide/#auxiliary-modules","text":"CASTEP also encourages the use of the more recent (Fortran 2008) submodule s. Submodules allow the programmatic subdivision of a module enabling the compiler to precompile interfaces, reduce required compilation if only the submodule has changed and allowing the developer to more effectively control scope of module internals. For clarity, and to keep the module from being excessively long, the module may also use auxiliary modules, which can be in separate files (again with one file per module). Any auxiliary modules must be used in only one specified module, i.e. no auxiliary code reuse in other specified modules as the auxiliary routines are not specified! The naming convention of any auxiliary modules is to be inherited from the specified module to make it clear where the auxiliary routines are to be used, e.g. if the specified module is called me.F90 with routines called me_sub , etc. then an auxiliary module would be me_extra.F90 with routines called me_extra_sub , etc. Note Rather than using full auxilliary modules in modern CASTEP, submodule s are encouraged.","title":"Auxiliary modules"},{"location":"developer/style_guide/#style-and-layout","text":"","title":"Style and Layout"},{"location":"developer/style_guide/#use-the-module-template","text":"The module template gives the recommended layout for a module and for a subprogram. This is available in the CASTEP source at Source/template.f90 . In particular, note the layout and contents of the comment header, and the order of declarations. Everything is to be private unless explicitly specified as public! This also makes it simple to check the code against the specification.","title":"Use the module template"},{"location":"developer/style_guide/#layout","text":"All code is to use indentation as generated by GNU-Emacs f90-mode. Use any editor you like to create the code, but please ensure that whatever goes into the Bitbucket repository has been passed through Emacs f90-mode indentation at the finished stage. To assist in Emacs usage, the module template contains Emacs directives to set f90-mode, etc.","title":"Layout"},{"location":"developer/style_guide/#case","text":"Use lower case for keywords and use capitalisation as given in the specification for all routines and variables mentioned therein. For private routines and variables use lower case in general. However, you may use upper case to differentiate words within a name, e.g. userInputData - as long as you are consistent throughout the module. Use upper case, with stripped spaces, for the value of string variables that are passed between routines, e.g. run_type='MOLECULARDYNAMICS' not 'MolecularDynamics ' or 'molecular dynamics' etc. to simplify string comparisons.","title":"Case"},{"location":"developer/style_guide/#names","text":"For clarity, don't change variable name on passing to a different routine wherever possible. Avoid short (1 or 2 letter) variable names except for simple loop counters. Use new form end subroutine name etc. not older form end subroutine .","title":"Names"},{"location":"developer/style_guide/#types","text":"Do NOT use implicit typing. Similarly, you do not have to stick to the old rules for implicit typing - you can have integer names beginning with \" c \" etc! Do not give type as double precision - use real(kind=dp) instead, as dp is a constant in the Constants module and this will make porting to other architectures (e.g. Cray) much simpler. Remember that all machine-specific code stays in the Utility routines. Similarly, when declaring a constant, use 1.234_dp NOT 1.234d0 .","title":"Types"},{"location":"developer/style_guide/#free-format","text":"Use free-format f90, with a maximum line length of 132 characters.","title":"Free format"},{"location":"developer/style_guide/#spaces","text":"Use spaces between keywords e.g. end if not endif .","title":"Spaces"},{"location":"developer/style_guide/#code-cleanly","text":"Obviously, to ensure correctness and make it easier for others to maintain the code. If the obvious way to code a routine is inefficient, whilst the efficient way is obscure, then this is allowed as long as the routine is well documented internally, with a discussion as to the design decisions made.","title":"Code cleanly"},{"location":"developer/style_guide/#be-aware-of-vectorisation","text":"When coding, be aware that the code is almost always executed upon vector architectures. Therefore code with a style that enables good vectorisation - e.g. don't put if statements inside nested loops wherever possible.","title":"Be aware of vectorisation"},{"location":"developer/style_guide/#documentation","text":"","title":"Documentation"},{"location":"developer/style_guide/#internal","text":"Each module, based upon the module template , is to have a header block describing its overall purpose and function. Each routine, written to the template, is to have a header block describing its function, the variables required and how modified, the necessary conditions for correct operation, etc. These comments should be clear and easy to understand. Each routine is also to contain lots of comments within the code. Comments are to be either on the same line(s) as the feature being comment upon, or in a block of lines above the feature. Comment density should be comparable to code density. All comments are to be in English and obey standard rules of English grammar.","title":"Internal"},{"location":"developer/style_guide/#external","text":"A module (or any modifications) is only considered complete when additional documentation has been supplied for inclusion. Documentation must be provided in the appropriate module and function header blocks, explaining the function of the module and each routine, the physics behind the code, the algorithms used, the key variables and data structures, and appropriate references to the literature.","title":"External"},{"location":"developer/style_guide/#testing","text":"","title":"Testing"},{"location":"developer/style_guide/#test-program","text":"Each module shall be tested for correctness before being added to the Bitbucket repository. To this end a set of tests shall be provided, which must compile and execute correctly in the CI system. The purpose of these tests is to verify the correct operation of every specified routine in the module. CASTEP uses the testcode testing platform which allows automated generation of benchmark data from a set of valid CASTEP input files. Please see Testing for more information on how to do this.","title":"Test Program"},{"location":"developer/style_guide/#reference-data","text":"The module test program shall come with both appropriate input datafiles and reference output results. Correct operation of the test shall be verified by comparing the actual output against the reference output results.","title":"Reference data"},{"location":"developer/style_guide/#module-template","text":"","title":"Module Template"},{"location":"developer/style_guide/#general_1","text":"Note particularly the order of declaration, use of implicit none and private , and the standard comment header, for internal documentation. All lines in comment headers are to be 80 characters wide. Not all sections of the header will be relevant to all subprograms and so can be deleted. It is very important that the header is kept up-to-date and as complete as possible.","title":"General"},{"location":"developer/style_guide/#use-of-public-and-private","text":"Each module uses an initial private statement to force all entities in the module to be private by default. Then have explicit public statements to expose those datatypes, variables and (overloaded) routine names, as listed in the specification document. This makes it easy to compare the code to the specification document.","title":"Use of public and private"},{"location":"developer/style_guide/#template","text":"! -*- mode: F90 ; mode: font-lock ; column-number-mode: true ; vc-back-end: git -*- !=============================================================================! ! D U M M Y ! !=============================================================================! ! Overall explanation of purpose and function of module. ! ! ! !-----------------------------------------------------------------------------! ! Written from \"Module Specification for New Plane Wave Code\", M. Segall, ! ! P. Lindan, M. Probert, C. Pickard, P. Hasnip, S. Clark and M. Payne ! ! Copyright 1999/2000 ! !-----------------------------------------------------------------------------! ! Written by author, version, date ! !-----------------------------------------------------------------------------! ! ! ! ! !=============================================================================! module dummy use constants , only : dp !Minimal useage where practical implicit none !Impose strong typing private !Everything is private ... !---------------------------------------------------------------------------! ! P u b l i c R o u t i n e s ! !---------------------------------------------------------------------------! public :: routine_name ... !... unless exposed here. interface routine_name !Overloaded routines, etc. ... !(specific names are private) end interface !---------------------------------------------------------------------------! ! P u b l i c V a r i a b l e s ! !---------------------------------------------------------------------------! public datatypes ... public variables ... !---------------------------------------------------------------------------! ! P r i v a t e R o u t i n e s ! !---------------------------------------------------------------------------! !---------------------------------------------------------------------------! ! P r i v a t e V a r i a b l e s ! !---------------------------------------------------------------------------! datatypes ... !Private data for all routines variables .. !in this module ... ... contains subroutine public1 ( var1 , var2 ,...) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! !-------------------------------------------------------------------------! ! Arguments: ! ! var1, intent, meaning ! ! ... (in order of call list) ! !-------------------------------------------------------------------------! ! Parent module variables used: ! ! globalvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Modules used: ! ! other_module used, ! ! other_vars, meanings, changes ! ! ... ! !-------------------------------------------------------------------------! ! Key Internal Variables: ! ! intvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Necessary conditions: ! ! ... ! !-------------------------------------------------------------------------! ! Written by author, version, date ! !=========================================================================! use my_module , only : some_other_function use other_module , only : other_var1 implicit none integer , intent ( in ), dimension (:,:) :: var1 !Variables in call order real ( kind = dp ), intent ( in ), parameter :: var2 ... ( other variables in call list ) real ( kind = dp ) :: my_var1 = 2.7182818_dp !base of natural logs complex ( kind = dp ), allocatable , dimension (:) :: my_work1 ... ( other internal variables ) ... ( condition checks ) ... ( actual code ) return end subroutine public1 ... ( other public subroutines ) subroutine private1 (....) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! ! (etc, as for public routines) ! !=========================================================================! .... end subroutine private1 end module dummy","title":"Template"},{"location":"developer/using_devel_codes/","text":"Using Devel Codes This document is intended to describe the use of devel codes for developers to speed up implementation of experimental parameters. What are devel codes Devel codes are handy tools for developers to control features while they are not ready for public release. Devel codes are read from the devel_code block of the .param file. Devel codes are much simpler to use than keywords, however they do not have the rigorous type/value checking or unit conversion that keywords do. Nor are they searchable and do not provide any help. In order to use devel codes you have to explicitly know how to call them, the values they should take and what they do. The devel code block is an arbitrary string which can be used to provide parameters to a function, however, the devel code block also has several useful standard structural elements to make it more useful than just a string one has to parse themselves. Using devel codes Devel code sub-blocks Devel codes are divided into sub-blocks which are usually named related to the module or functions they support. Examples include: MD - Relating to molecular dynamics options FIRE - Relating to the FIRE geometry optimisation method ELECTRONIC - Relating to electronic minimisation However they can be anything the developer wants. Note While in principle block names are general and arbitrary, keeping them related to the module where they are used or their functionality is useful for remembering how to call them. Another use of blocks is to have a block dedicated to a particular algorithm or as a structured block in the style of .cell style blocks (i.e. %block ... %endblock ) ready for integration into the main parameters when the feature is complete. The structure of a sub-block in the .param file (here XYZ ) is as follows: %block devel_code XYZ: param=3 :ENDXYZ %endblock devel_code Extracting devel codes The devel code block is converted upon reading the param file into parameters :: current_params%devel_code . This block can then be parsed using the following functions: io :: io_code_present(code, key, block) Check whether a particular parameter key is present in block block . If block is not given check the top-level devel-code. io :: io_code_block(code, block) Return the entire block block as a character array allowing you to manually process the data. Most useful for situations where the final parameter will be a block of data. io :: io_code_logical(code, key, block) Parse given parameter key in block block as a logical according to list-directed Fortran logical rules. io :: io_code_integer(code, key, block) Parse given parameter key in block block as an integer according to list-directed Fortran integer rules. io :: io_code_real(code, key, block) Parse given parameter key in block block as an real according to list-directed Fortran real rules. io :: io_code_complex(code, key, block) Parse given parameter key in block block as an complex according to list-directed Fortran complex rules. io :: io_code_string(code, key, block) Parse given parameter key in block block as a character string. Example For a devel_code block that looks like: %block devel_code mod_param=17 XYZ: param=3 :ENDXYZ %endblock devel_code The usual procedure for processing a devel code argument is as follows: module my_module ... ! Can read into module parameters if necessary integer :: module_param ... function use_devel_code () ! Ensure the devel_codes are available use parameters , only : current_params ! Ensure we can parse the devel-codes use io , only : io_code_present , io_code_integer ! Have the param available integer :: param ! Check that we're the master process for reading the strings if ( on_root_node ) then ! Check if the devel code has been set if ( io_code_present ( current_params % devel_code , 'param' , 'XYZ' )) & ! Read and parse the parameter for use & param = io_code_integer ( current_params % devel_code , 'param' , 'XYZ' ) !Since it's top-level we parse it without passing the block. if ( io_code_present ( current_params % devel_code , 'mod_param' )) & & module_param = io_code_integer ( current_params % devel_code , 'mod_param' ) endif ! Distribute the parameters to all nodes call comms_gcopy ( param , 1 ) ...","title":"Using Devel Codes"},{"location":"developer/using_devel_codes/#using-devel-codes","text":"This document is intended to describe the use of devel codes for developers to speed up implementation of experimental parameters.","title":"Using Devel Codes"},{"location":"developer/using_devel_codes/#what-are-devel-codes","text":"Devel codes are handy tools for developers to control features while they are not ready for public release. Devel codes are read from the devel_code block of the .param file. Devel codes are much simpler to use than keywords, however they do not have the rigorous type/value checking or unit conversion that keywords do. Nor are they searchable and do not provide any help. In order to use devel codes you have to explicitly know how to call them, the values they should take and what they do. The devel code block is an arbitrary string which can be used to provide parameters to a function, however, the devel code block also has several useful standard structural elements to make it more useful than just a string one has to parse themselves.","title":"What are devel codes"},{"location":"developer/using_devel_codes/#using-devel-codes_1","text":"","title":"Using devel codes"},{"location":"developer/using_devel_codes/#devel-code-sub-blocks","text":"Devel codes are divided into sub-blocks which are usually named related to the module or functions they support. Examples include: MD - Relating to molecular dynamics options FIRE - Relating to the FIRE geometry optimisation method ELECTRONIC - Relating to electronic minimisation However they can be anything the developer wants. Note While in principle block names are general and arbitrary, keeping them related to the module where they are used or their functionality is useful for remembering how to call them. Another use of blocks is to have a block dedicated to a particular algorithm or as a structured block in the style of .cell style blocks (i.e. %block ... %endblock ) ready for integration into the main parameters when the feature is complete. The structure of a sub-block in the .param file (here XYZ ) is as follows: %block devel_code XYZ: param=3 :ENDXYZ %endblock devel_code","title":"Devel code sub-blocks"},{"location":"developer/using_devel_codes/#extracting-devel-codes","text":"The devel code block is converted upon reading the param file into parameters :: current_params%devel_code . This block can then be parsed using the following functions: io :: io_code_present(code, key, block) Check whether a particular parameter key is present in block block . If block is not given check the top-level devel-code. io :: io_code_block(code, block) Return the entire block block as a character array allowing you to manually process the data. Most useful for situations where the final parameter will be a block of data. io :: io_code_logical(code, key, block) Parse given parameter key in block block as a logical according to list-directed Fortran logical rules. io :: io_code_integer(code, key, block) Parse given parameter key in block block as an integer according to list-directed Fortran integer rules. io :: io_code_real(code, key, block) Parse given parameter key in block block as an real according to list-directed Fortran real rules. io :: io_code_complex(code, key, block) Parse given parameter key in block block as an complex according to list-directed Fortran complex rules. io :: io_code_string(code, key, block) Parse given parameter key in block block as a character string.","title":"Extracting devel codes"},{"location":"developer/using_devel_codes/#example","text":"For a devel_code block that looks like: %block devel_code mod_param=17 XYZ: param=3 :ENDXYZ %endblock devel_code The usual procedure for processing a devel code argument is as follows: module my_module ... ! Can read into module parameters if necessary integer :: module_param ... function use_devel_code () ! Ensure the devel_codes are available use parameters , only : current_params ! Ensure we can parse the devel-codes use io , only : io_code_present , io_code_integer ! Have the param available integer :: param ! Check that we're the master process for reading the strings if ( on_root_node ) then ! Check if the devel code has been set if ( io_code_present ( current_params % devel_code , 'param' , 'XYZ' )) & ! Read and parse the parameter for use & param = io_code_integer ( current_params % devel_code , 'param' , 'XYZ' ) !Since it's top-level we parse it without passing the block. if ( io_code_present ( current_params % devel_code , 'mod_param' )) & & module_param = io_code_integer ( current_params % devel_code , 'mod_param' ) endif ! Distribute the parameters to all nodes call comms_gcopy ( param , 1 ) ...","title":"Example"},{"location":"developer/using_trace/","text":"Using the trace module The trace module provides functionality useful to developers for debugging and profiling particular sections of castep. It is common practice to put calls to trace_entry and trace_exit at the beginning and end of function calls in castep, but the reasoning why may be unclear. The primary reason for most users is that when castep performs an io_abort , it first calls into trace on each process to dump the current trace stack to the ..err files. This is the main error message people see when castep fails. This document sets out to explain in more detail, the usage of the trace module and how and why it benefits developers. The trace module Tracing code Trace Blocks The trace module provides a number of functions which are helpful in debugging and profiling code. The key functions in trace for general usage are trace_entry and trace_exit which should be used in all major functions. This makes it so the subprogram is logged in tracing. Note The trace_entry and trace_exit routines do have an associated cost, and therefore for short routines called very frequently (e.g. functions in loops) it can be a bad idea for performance to trace these routines. The syntax for trace_entry is: call trace_entry ( block_name , success [, profile ][, class ]) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. profile - logical, intent(in) - whether to profile this block class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Note trace_entry and trace_exit subroutines can be called around any arbitrary blocks of code. This makes it possible to narrow down failing points, but not only that, they can be used to profile sections of code where performance is falling below expectations. Trace Sections It is possible to mark a section of a code as a sub-element of a trace-block rather than a block in its own right. These can also have extra arguments passed through to log parameters at certain stages. The syntax for trace_section is: call trace_section_entry ( section_name [, variable_name , value ], success [, class ]) Where: section_name - character, intent(in) - is the name of the entry in the trace. variable_name - character, intent(in) - is the logging name to be attached to the section in the trace output value - integer|character, intent(in) - is the current value of the variable to be logged. value can either be an integer or character(len=63) success - integer, intent(out) - is the return status of the function, 0 if successful. class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_section_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Debugging The trace stack is built up from the trace_entry and trace_exit routines which keep track of where the code is currently executing. This is why it is recommended that all major routines (where possible, see note above) begin and end with a trace_entry , trace_exit . Tracing can also be used to dump information to a logging file whenever a trace_entry / trace_exit call is hit. This is done using: call trace_set_debug (. true .) It is then possible to check within a module whether trace debugging is on using: if ( trace_debug_is_on ()) then ... end if Profiling Trace also provides profiling functionality timing the duration between any entry & exit . Timing can be enabled through setting the relevant prof or profclass devel codes to true ( see: below ). It is also possible to enable profiling globally using: class trace_set_profile (. true .) And subsequently disable it in a similar way: class trace_set_profile (. false .) The trace module tracks a number of useful profiling factors including time spent in function, call counts, and time per call. Devel Codes The trace module has several functions which can be enabled by devel codes. Global FULL_TRACE - logical - Enable full profiling for all modules including the trace module itself. TRACE - logical - Enable automated dumping of function calls to the profiling filed PROF block Enables timing for the castep. # Prints profiling information for the whole run # i.e. how long is spent in each subroutine. %block devel_code PROF: * :ENDPROF %endblock devel_code PROFCLASS Block List of \"classes\" to be matched against trace classes (see: trace_entry ), to enable profiling for certain groups of operations. %block devel_code PROFCLASS:FFT ORTHOGONALISATION:ENDPROFCLASS %endblock devel_code will print a table of the total time spent in routines labelled with a particular class. This will produce an output like: Class of operation Time spent FFT 1.41s ORTHOGONALISATION 0.05s Note For PROF::ENDPROF and PROFCLASS::ENDPROFCLASS there must be no whitespace in the devel_code before or after the colon (:) character, i.e PROF:wave:ENDPROF and not PROF: wave :ENDPROF Dumping info It is possible to dump the info in the tracing at any time. In order to get all information including timings, calls, etc. you can call trace_output as follows: call trace_output ( out_unit , success , order ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. order - character, intent(in) - Order in which to dump trace, must be one of: L - Order they were (first) added to trace. T - Descending order of total time spent in function. C - Descending order of number of calls. P - Descenging order of time per call. It is also possible to quickly dump the current trace call stack. This is done as follows: call trace_log_output ( out_unit , success ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. Output format If any of the TRACE , FULL_TRACE or PROF devel_codes are present, or a call is made to trace_output , CASTEP writes a table of calls to each subroutine in (something similar to) the following format: +------------------------------------------------------------ | o-- list of parent routines | / | O->name of subroutine | / | --o-> list of child routines +------------------------------------------------------------ The list of parent routines has information on the number of calls this parent routine calls this current routine. The subroutine of interest has information on how many times in total it was called. The list of child routines has a list of how many times a particular child routine was called from the subroutine of interest. If profiling is on, for all or some of the routines, there is an additional column for number of times the routine was profiled and a total time spent in each routine. Logging Files By default, CASTEP creates ..profile files to log trace information.","title":"Using trace"},{"location":"developer/using_trace/#using-the-trace-module","text":"The trace module provides functionality useful to developers for debugging and profiling particular sections of castep. It is common practice to put calls to trace_entry and trace_exit at the beginning and end of function calls in castep, but the reasoning why may be unclear. The primary reason for most users is that when castep performs an io_abort , it first calls into trace on each process to dump the current trace stack to the ..err files. This is the main error message people see when castep fails. This document sets out to explain in more detail, the usage of the trace module and how and why it benefits developers.","title":"Using the trace module"},{"location":"developer/using_trace/#the-trace-module","text":"","title":"The trace module"},{"location":"developer/using_trace/#tracing-code","text":"","title":"Tracing code"},{"location":"developer/using_trace/#trace-blocks","text":"The trace module provides a number of functions which are helpful in debugging and profiling code. The key functions in trace for general usage are trace_entry and trace_exit which should be used in all major functions. This makes it so the subprogram is logged in tracing. Note The trace_entry and trace_exit routines do have an associated cost, and therefore for short routines called very frequently (e.g. functions in loops) it can be a bad idea for performance to trace these routines. The syntax for trace_entry is: call trace_entry ( block_name , success [, profile ][, class ]) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. profile - logical, intent(in) - whether to profile this block class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Note trace_entry and trace_exit subroutines can be called around any arbitrary blocks of code. This makes it possible to narrow down failing points, but not only that, they can be used to profile sections of code where performance is falling below expectations.","title":"Trace Blocks"},{"location":"developer/using_trace/#trace-sections","text":"It is possible to mark a section of a code as a sub-element of a trace-block rather than a block in its own right. These can also have extra arguments passed through to log parameters at certain stages. The syntax for trace_section is: call trace_section_entry ( section_name [, variable_name , value ], success [, class ]) Where: section_name - character, intent(in) - is the name of the entry in the trace. variable_name - character, intent(in) - is the logging name to be attached to the section in the trace output value - integer|character, intent(in) - is the current value of the variable to be logged. value can either be an integer or character(len=63) success - integer, intent(out) - is the return status of the function, 0 if successful. class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_section_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful.","title":"Trace Sections"},{"location":"developer/using_trace/#debugging","text":"The trace stack is built up from the trace_entry and trace_exit routines which keep track of where the code is currently executing. This is why it is recommended that all major routines (where possible, see note above) begin and end with a trace_entry , trace_exit . Tracing can also be used to dump information to a logging file whenever a trace_entry / trace_exit call is hit. This is done using: call trace_set_debug (. true .) It is then possible to check within a module whether trace debugging is on using: if ( trace_debug_is_on ()) then ... end if","title":"Debugging"},{"location":"developer/using_trace/#profiling","text":"Trace also provides profiling functionality timing the duration between any entry & exit . Timing can be enabled through setting the relevant prof or profclass devel codes to true ( see: below ). It is also possible to enable profiling globally using: class trace_set_profile (. true .) And subsequently disable it in a similar way: class trace_set_profile (. false .) The trace module tracks a number of useful profiling factors including time spent in function, call counts, and time per call.","title":"Profiling"},{"location":"developer/using_trace/#devel-codes","text":"The trace module has several functions which can be enabled by devel codes.","title":"Devel Codes"},{"location":"developer/using_trace/#global","text":"FULL_TRACE - logical - Enable full profiling for all modules including the trace module itself. TRACE - logical - Enable automated dumping of function calls to the profiling filed","title":"Global"},{"location":"developer/using_trace/#prof-block","text":"Enables timing for the castep. # Prints profiling information for the whole run # i.e. how long is spent in each subroutine. %block devel_code PROF: * :ENDPROF %endblock devel_code","title":"PROF block"},{"location":"developer/using_trace/#profclass-block","text":"List of \"classes\" to be matched against trace classes (see: trace_entry ), to enable profiling for certain groups of operations. %block devel_code PROFCLASS:FFT ORTHOGONALISATION:ENDPROFCLASS %endblock devel_code will print a table of the total time spent in routines labelled with a particular class. This will produce an output like: Class of operation Time spent FFT 1.41s ORTHOGONALISATION 0.05s Note For PROF::ENDPROF and PROFCLASS::ENDPROFCLASS there must be no whitespace in the devel_code before or after the colon (:) character, i.e PROF:wave:ENDPROF and not PROF: wave :ENDPROF","title":"PROFCLASS Block"},{"location":"developer/using_trace/#dumping-info","text":"It is possible to dump the info in the tracing at any time. In order to get all information including timings, calls, etc. you can call trace_output as follows: call trace_output ( out_unit , success , order ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. order - character, intent(in) - Order in which to dump trace, must be one of: L - Order they were (first) added to trace. T - Descending order of total time spent in function. C - Descending order of number of calls. P - Descenging order of time per call. It is also possible to quickly dump the current trace call stack. This is done as follows: call trace_log_output ( out_unit , success ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful.","title":"Dumping info"},{"location":"developer/using_trace/#output-format","text":"If any of the TRACE , FULL_TRACE or PROF devel_codes are present, or a call is made to trace_output , CASTEP writes a table of calls to each subroutine in (something similar to) the following format: +------------------------------------------------------------ | o-- list of parent routines | / | O->name of subroutine | / | --o-> list of child routines +------------------------------------------------------------ The list of parent routines has information on the number of calls this parent routine calls this current routine. The subroutine of interest has information on how many times in total it was called. The list of child routines has a list of how many times a particular child routine was called from the subroutine of interest. If profiling is on, for all or some of the routines, there is an additional column for number of times the routine was profiled and a total time spent in each routine.","title":"Output format"},{"location":"developer/using_trace/#logging-files","text":"By default, CASTEP creates ..profile files to log trace information.","title":"Logging Files"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/","text":"Linear expansion DeltaSCF DFT calculations - Constraining projected reference orbitals Basics For molecules adsorbed at surfaces, \\Delta \\Delta SCF calculations become challenging, simply because of the large number of states. Not only is it difficult to identify the correct state, often hybridization spreads adsorbate molecular orbitals across a large number of substrate bands. A more realistic excitation constraint would be to project on a gasphase molecular orbital and subsequently enforce occupation of this state. This idea is referred to as linear expansion \\Delta \\Delta SCF and has first been proposed by Gavnholt et al 1 . The CASTEP implementation is described in Maurer and Reuer (2013) 2 . Herein, we constrain the occupation of a so-called resonance state built from a linear combination of Kohn-Sham states instead of a single KS state. We expand an abitrary reference state |\\phi_c\\rangle |\\phi_c\\rangle in the space of Kohn-Sham states as follows: |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle At the same time we orthogonalize the remaining KS states |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle After an additional orthonormalization of all states we have constructed a resonance state \\tilde{\\psi_c^{\\mathbf{k}}} \\tilde{\\psi_c^{\\mathbf{k}}} and removed all its contributions from all other states. We can now constrain the occupation of this state with the effect of describing an excitation of a specific molecular orbital. This is done in every SCF step until the calculation is converged. For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_overlap_cutoff Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : linear expansion deltascf_overlap_cutoff : 0.01 #band occ spin %block deltascf_constraints 35 1.0000 1 %endblock deltascf_constraints In this example, we take state 35 from wavefunction file .check and enforce an occupation of 1.00 electrons. In this runmode we do not have to pick constraints that yield a net change in charge equal to 0. Charge neutrality will be satisfied by modifying the Fermi level accordingly. However, this is only strictly sensible for metallic systems. Jeppe Gavnholt, Thomas Olsen, Mads Engelund, and Jakob Schi\u00f8tz. \u0394 self-consistent field method to obtain potential energy surfaces of excited molecules on surfaces. Phys. Rev. B , 78:075441, Aug 2008. doi:10.1103/PhysRevB.78.075441 . \u21a9 Reinhard J. Maurer and Karsten Reuter. Excited-state potential-energy surfaces of metal-adsorbed organic molecules from linear expansion \u0394-self-consistent field density-functional theory (\u0394SCF-DFT). The Journal of Chemical Physics , 139(1):014708, 07 2013. doi:10.1063/1.4812398 . \u21a9","title":"Linear expansion DeltaSCF"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/#linear-expansion-deltascf-dft-calculations-constraining-projected-reference-orbitals","text":"","title":"Linear expansion DeltaSCF DFT calculations - Constraining projected reference orbitals"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/#basics","text":"For molecules adsorbed at surfaces, \\Delta \\Delta SCF calculations become challenging, simply because of the large number of states. Not only is it difficult to identify the correct state, often hybridization spreads adsorbate molecular orbitals across a large number of substrate bands. A more realistic excitation constraint would be to project on a gasphase molecular orbital and subsequently enforce occupation of this state. This idea is referred to as linear expansion \\Delta \\Delta SCF and has first been proposed by Gavnholt et al 1 . The CASTEP implementation is described in Maurer and Reuer (2013) 2 . Herein, we constrain the occupation of a so-called resonance state built from a linear combination of Kohn-Sham states instead of a single KS state. We expand an abitrary reference state |\\phi_c\\rangle |\\phi_c\\rangle in the space of Kohn-Sham states as follows: |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle At the same time we orthogonalize the remaining KS states |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle After an additional orthonormalization of all states we have constructed a resonance state \\tilde{\\psi_c^{\\mathbf{k}}} \\tilde{\\psi_c^{\\mathbf{k}}} and removed all its contributions from all other states. We can now constrain the occupation of this state with the effect of describing an excitation of a specific molecular orbital. This is done in every SCF step until the calculation is converged. For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_overlap_cutoff Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : linear expansion deltascf_overlap_cutoff : 0.01 #band occ spin %block deltascf_constraints 35 1.0000 1 %endblock deltascf_constraints In this example, we take state 35 from wavefunction file .check and enforce an occupation of 1.00 electrons. In this runmode we do not have to pick constraints that yield a net change in charge equal to 0. Charge neutrality will be satisfied by modifying the Fermi level accordingly. However, this is only strictly sensible for metallic systems. Jeppe Gavnholt, Thomas Olsen, Mads Engelund, and Jakob Schi\u00f8tz. \u0394 self-consistent field method to obtain potential energy surfaces of excited molecules on surfaces. Phys. Rev. B , 78:075441, Aug 2008. doi:10.1103/PhysRevB.78.075441 . \u21a9 Reinhard J. Maurer and Karsten Reuter. Excited-state potential-energy surfaces of metal-adsorbed organic molecules from linear expansion \u0394-self-consistent field density-functional theory (\u0394SCF-DFT). The Journal of Chemical Physics , 139(1):014708, 07 2013. doi:10.1063/1.4812398 . \u21a9","title":"Basics"},{"location":"documentation/Delta_SCF/mo_delta_scf/","text":"DFT+U(MO) - Applying potentials to arbitrary orbitals Basics We can employ the molecular orbital projections we have introduced in the le \\Delta \\Delta SCF section to also introduce penalty potentials that shift specific orbitals up or down. This can be used to specify the HOMO-LUMO of an adsorbed molecule or to modify the level alignment with the metal substrate. This constraint potential can be combined with population constraints. For more details and an example application on Porphine molecules adsorbed at coinage metal surfaces, see M\u00fcller et al . (2016) 1 . For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_dftu_checkpoint Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_dftu_checkpoint : .check deltascf_method : DFT+U(MO) #band occ spin +U in eV excite? %block deltascf_constraints 34 0.0000 1 -1.40 Y 35 1.0000 2 0.70 Y %endblock deltascf_constraints In this mode we add a potential to the Hamiltonian for each defined constraint, which has the following form: V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| You can find a detailed description of these potentials in Appendix D of First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches 2 In this example, two +U constraint potentials act on orbital no. 34 of the majority spin channel and orbital no. 35 of the minority spin channel, taken from the deltascf_dftu_checkpoint=.check file. In addition, the occupation of orbital no. 35 taken from file deltascf_checkpoint=.check file is constrained to the occupation 1.000. Excitation constraints on each state can be activated (or not) by adding the final 'Y' or 'N' to the relevant line. Moritz M\u00fcller, Katharina Diller, Reinhard J. Maurer, and Karsten Reuter. Interfacial charge rearrangement and intermolecular interactions: Density-functional theory study of free-base porphine adsorbed on Ag(111) and Cu(111). The Journal of Chemical Physics , 144(2):024701, 01 2016. doi:10.1063/1.4938259 . \u21a9 Reinhard Johann Maurer. First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches . PhD thesis, Technische Universit\u00e4t M\u00fcnchen, 2014. URL: https://mediatum.ub.tum.de/1190934 . \u21a9","title":"MO Delta SCF"},{"location":"documentation/Delta_SCF/mo_delta_scf/#dftumo-applying-potentials-to-arbitrary-orbitals","text":"","title":"DFT+U(MO) - Applying potentials to arbitrary orbitals"},{"location":"documentation/Delta_SCF/mo_delta_scf/#basics","text":"We can employ the molecular orbital projections we have introduced in the le \\Delta \\Delta SCF section to also introduce penalty potentials that shift specific orbitals up or down. This can be used to specify the HOMO-LUMO of an adsorbed molecule or to modify the level alignment with the metal substrate. This constraint potential can be combined with population constraints. For more details and an example application on Porphine molecules adsorbed at coinage metal surfaces, see M\u00fcller et al . (2016) 1 . For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_dftu_checkpoint Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_dftu_checkpoint : .check deltascf_method : DFT+U(MO) #band occ spin +U in eV excite? %block deltascf_constraints 34 0.0000 1 -1.40 Y 35 1.0000 2 0.70 Y %endblock deltascf_constraints In this mode we add a potential to the Hamiltonian for each defined constraint, which has the following form: V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| You can find a detailed description of these potentials in Appendix D of First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches 2 In this example, two +U constraint potentials act on orbital no. 34 of the majority spin channel and orbital no. 35 of the minority spin channel, taken from the deltascf_dftu_checkpoint=.check file. In addition, the occupation of orbital no. 35 taken from file deltascf_checkpoint=.check file is constrained to the occupation 1.000. Excitation constraints on each state can be activated (or not) by adding the final 'Y' or 'N' to the relevant line. Moritz M\u00fcller, Katharina Diller, Reinhard J. Maurer, and Karsten Reuter. Interfacial charge rearrangement and intermolecular interactions: Density-functional theory study of free-base porphine adsorbed on Ag(111) and Cu(111). The Journal of Chemical Physics , 144(2):024701, 01 2016. doi:10.1063/1.4938259 . \u21a9 Reinhard Johann Maurer. First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches . PhD thesis, Technische Universit\u00e4t M\u00fcnchen, 2014. URL: https://mediatum.ub.tum.de/1190934 . \u21a9","title":"Basics"},{"location":"documentation/Delta_SCF/molpdos/","text":"Molecular Orbital (MO) projected Density-of-States - MolPDOS Basics This mode allows to generate projections and pDOS plots with respect to any molecular orbital (MO). To run it one just has to add calculate_modos=true keyword to .param file. The projection data is produced by CASTEP after the SCF task and is written to files called .modos_state_<#>_<#> , where the two numbers correspond to the number and the spin of the specified reference orbital from the reference checkfile. At the end of the .castep file the projection is commented in the following way: Calculating MODOS weights +-------------------INPUT PARAMETERS-------------------+ Taking band from model N2-base.check MODOS state 1 MODOS band nr. 5 MODOS band has spin 1 MODOS state 2 MODOS band nr. 6 MODOS band has spin 1 |DeltaSCF| Population of state: 5 1 1.000000 |DeltaSCF| Population of state: 6 1 0.000000 Writing file N2-modos.modos_state_5_1 Writing file N2-modos.modos_state_6_1 These files, together with the .bands file can be post-processed with the MolPDOS program with the following command MolPDOS This will write output in the .castep with following header. ############################################# # # # # # MolPDOS -CASTEP Post-processor # # # # by R. J. Maurer # # # # # ############################################# In addition it will write files for the total DOS (Total-DOS.dat), for the two spin channels if the calculation was spin polarized (Total-DOS_spin1.dat, Total-DOS_spin2.dat), and for the MolPDOS ( <#>_spin<#>_1X molpdos_bin_with No real number, default=0.01 molpdos_smearing No real number, default=0.05 molpdos_scaling No real number, default=1.0, scales MolPDOSes no_fermi_shift No no argument, logical, removes fermishift ax is_energy_margin No real in eV default=0.0eV output_filename No Example .molpdos file: molpdos_state : 34 1 molpdos_state : 35 1 molpdos_state : 36 1 molpdos_state : 33 1 molpdos_bin_width : 0.02 molpdos_smearing : 0.05 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat","title":"Molecular Projected DOS"},{"location":"documentation/Delta_SCF/molpdos/#molecular-orbital-mo-projected-density-of-states-molpdos","text":"","title":"Molecular Orbital (MO) projected Density-of-States - MolPDOS"},{"location":"documentation/Delta_SCF/molpdos/#basics","text":"This mode allows to generate projections and pDOS plots with respect to any molecular orbital (MO). To run it one just has to add calculate_modos=true keyword to .param file. The projection data is produced by CASTEP after the SCF task and is written to files called .modos_state_<#>_<#> , where the two numbers correspond to the number and the spin of the specified reference orbital from the reference checkfile. At the end of the .castep file the projection is commented in the following way: Calculating MODOS weights +-------------------INPUT PARAMETERS-------------------+ Taking band from model N2-base.check MODOS state 1 MODOS band nr. 5 MODOS band has spin 1 MODOS state 2 MODOS band nr. 6 MODOS band has spin 1 |DeltaSCF| Population of state: 5 1 1.000000 |DeltaSCF| Population of state: 6 1 0.000000 Writing file N2-modos.modos_state_5_1 Writing file N2-modos.modos_state_6_1 These files, together with the .bands file can be post-processed with the MolPDOS program with the following command MolPDOS This will write output in the .castep with following header. ############################################# # # # # # MolPDOS -CASTEP Post-processor # # # # by R. J. Maurer # # # # # ############################################# In addition it will write files for the total DOS (Total-DOS.dat), for the two spin channels if the calculation was spin polarized (Total-DOS_spin1.dat, Total-DOS_spin2.dat), and for the MolPDOS ( <#>_spin<#>_1X molpdos_bin_with No real number, default=0.01 molpdos_smearing No real number, default=0.05 molpdos_scaling No real number, default=1.0, scales MolPDOSes no_fermi_shift No no argument, logical, removes fermishift ax is_energy_margin No real in eV default=0.0eV output_filename No Example .molpdos file: molpdos_state : 34 1 molpdos_state : 35 1 molpdos_state : 36 1 molpdos_state : 33 1 molpdos_bin_width : 0.02 molpdos_smearing : 0.05 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat","title":"Keywords allowed in .molpdos"},{"location":"documentation/Delta_SCF/overview/","text":"Overview Functionality Calculate \\Delta \\Delta SCF-DFT excitation energies by changing band occupation - the \"simple\" method. Constrain and occupy an orbital of a subsystem or reference system to resemble an electronic excitation via 'linear expansion mode' = le \\Delta \\Delta SCF-DFT Put penalties onto orbitals of a subsystem in a DFT+U fashion (DFT+U(MO)). This can be done by enforcing idempotency (integer occupation) or by constrained DFT Generate a projection of the orbital of a subsystem on the Density-of-States (DOS) There is also a separate post-processing tool (MolPDOS) to generate the corresponding DOS from the projection information Prerequisites The following applies to all modes, except the \\Delta \\Delta SCF-DFT mode. Nonetheless, this runmode requires a good understanding of its limitations. The two systems should not be strongly geometrically or electronically mixed and a separation into general system and subsystem has to still be chemically reasonable. Otherwise this Ansatz breaks down. Ideally the difference can be seen as a weak perturbation. This applies for example for A molecule adsorbed at a metal surface with weak to medium hybridization, e.g. C 6 H 6 \\@Au(111). A particle or molecule inserted into a porous nanostructure. The exact same system in another electronic state, e.g. groundstate vs. first excited state. The wavefunction of the subsystem has to be calculated with exactly the same settings (K-points, spin-polarisation, cutoff, cell size) as the actual system. This introduces some artificial dispersion for gas-phase molecules, but if the cell is sufficiently large the effects should be small. In addition, this might be something desirable, for example when high coverage situations are investigated. At the moment, the excitation constraints only work for metals_method=DM and spin_treatment=scalar or none . Currently, hybrid XC functionals are unsupported. General Use The general use of \\Delta \\Delta SCF always involves the following steps: Define the base system and calculate the self consistent density and wave functions using a task=single point energy . The checkfile generated is then used as the base for the next steps. Define the system you want to study and add something similar to the following to the .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_mode : 1 where is the seedname of the base calculation in step 1. Decide on the type of \\Delta \\Delta SCF calculation. The allowed methods are: deltascf_method : SIMPLE or deltascf_mode : 1 deltascf_method : DFT+U(MO) or deltascf_mode : 2 deltascf_method : LINEAR EXPANSTION or deltascf_mode : 3 For each method, the constraints need to be specified as follows: SIMPLE #band occ spin from_band to_band %block deltascf_constraints 5 0.5000 1 5 5 6 0.5000 1 6 6 %endblock deltascf_constraints DFT+U(MO) #band occ spin U(eV) excite_band %block deltascf_constraints 5 0.5000 1 +0.0 .true. 6 0.5000 1 +0.0 .true. %endblock deltascf_constraints LINEAR EXPANSION #band occ spin %block deltascf_constraints 5 0.5000 1 6 0.5000 1 %endblock deltascf_constraints The \"occ\" column is the constrained occupation required. In this instance, 1 electron is being raised from band 5 to band 6. The occupation is defined such that 0<=occ<=1 so if non-spin polarized calculation then occ=0.5 means 1 electron. You can now run the \\Delta \\Delta SCF calculation as any other CASTEP task. If you wish to, you can analyse the results using the MolPDOS post-processing tool which needs an additional .molpdos input file. Hence use MolPDOS ","title":"Delta SCF Overview"},{"location":"documentation/Delta_SCF/overview/#overview","text":"","title":"Overview"},{"location":"documentation/Delta_SCF/overview/#functionality","text":"Calculate \\Delta \\Delta SCF-DFT excitation energies by changing band occupation - the \"simple\" method. Constrain and occupy an orbital of a subsystem or reference system to resemble an electronic excitation via 'linear expansion mode' = le \\Delta \\Delta SCF-DFT Put penalties onto orbitals of a subsystem in a DFT+U fashion (DFT+U(MO)). This can be done by enforcing idempotency (integer occupation) or by constrained DFT Generate a projection of the orbital of a subsystem on the Density-of-States (DOS) There is also a separate post-processing tool (MolPDOS) to generate the corresponding DOS from the projection information","title":"Functionality"},{"location":"documentation/Delta_SCF/overview/#prerequisites","text":"The following applies to all modes, except the \\Delta \\Delta SCF-DFT mode. Nonetheless, this runmode requires a good understanding of its limitations. The two systems should not be strongly geometrically or electronically mixed and a separation into general system and subsystem has to still be chemically reasonable. Otherwise this Ansatz breaks down. Ideally the difference can be seen as a weak perturbation. This applies for example for A molecule adsorbed at a metal surface with weak to medium hybridization, e.g. C 6 H 6 \\@Au(111). A particle or molecule inserted into a porous nanostructure. The exact same system in another electronic state, e.g. groundstate vs. first excited state. The wavefunction of the subsystem has to be calculated with exactly the same settings (K-points, spin-polarisation, cutoff, cell size) as the actual system. This introduces some artificial dispersion for gas-phase molecules, but if the cell is sufficiently large the effects should be small. In addition, this might be something desirable, for example when high coverage situations are investigated. At the moment, the excitation constraints only work for metals_method=DM and spin_treatment=scalar or none . Currently, hybrid XC functionals are unsupported.","title":"Prerequisites"},{"location":"documentation/Delta_SCF/overview/#general-use","text":"The general use of \\Delta \\Delta SCF always involves the following steps: Define the base system and calculate the self consistent density and wave functions using a task=single point energy . The checkfile generated is then used as the base for the next steps. Define the system you want to study and add something similar to the following to the .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_mode : 1 where is the seedname of the base calculation in step 1. Decide on the type of \\Delta \\Delta SCF calculation. The allowed methods are: deltascf_method : SIMPLE or deltascf_mode : 1 deltascf_method : DFT+U(MO) or deltascf_mode : 2 deltascf_method : LINEAR EXPANSTION or deltascf_mode : 3 For each method, the constraints need to be specified as follows: SIMPLE #band occ spin from_band to_band %block deltascf_constraints 5 0.5000 1 5 5 6 0.5000 1 6 6 %endblock deltascf_constraints DFT+U(MO) #band occ spin U(eV) excite_band %block deltascf_constraints 5 0.5000 1 +0.0 .true. 6 0.5000 1 +0.0 .true. %endblock deltascf_constraints LINEAR EXPANSION #band occ spin %block deltascf_constraints 5 0.5000 1 6 0.5000 1 %endblock deltascf_constraints The \"occ\" column is the constrained occupation required. In this instance, 1 electron is being raised from band 5 to band 6. The occupation is defined such that 0<=occ<=1 so if non-spin polarized calculation then occ=0.5 means 1 electron. You can now run the \\Delta \\Delta SCF calculation as any other CASTEP task. If you wish to, you can analyse the results using the MolPDOS post-processing tool which needs an additional .molpdos input file. Hence use MolPDOS ","title":"General Use"},{"location":"documentation/Delta_SCF/simple_delta_scf/","text":"Conventional Delta-Self-Consistent-Field-DFT Calculations Basics In \\Delta \\Delta SCF-DFT we calculate electronic excited states by assuming a certain non-equilibrium orbital occupation and by self-consistently solving the Kohn-Sham equations with this excited state population. The excitation energy is then simply the energy difference between the ground state KS-DFT calculation and the \\Delta \\Delta SCF-DFT calculation: \\Delta E = E(\\Delta SCF)-E(DFT) \\Delta E = E(\\Delta SCF)-E(DFT) We therefore need to perform two calculations, the ground state DFT calculation and the DeltaSCF calculation. For a more detailed explanation, see Maurer and Reuter (2011) 1 . For this simple \\Delta \\Delta SCF calculation, we have to set deltascf_method = simple in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_smearing Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.0000 1 34 34 35 1.0000 1 35 35 %endblock deltascf_constraints In this example, we enforce an occupation of 0.00 electrons in the electronic state 34, spin channel 1 and an occupation of 1.00 electrons in the electronic state 35, spin channel 1. The last two numbers in each line specify a window of states in which the corresponding state is searched if it changes its position between SCF cycles. In that way we can ensure that we constrain the correct state. deltascf_smearing is a mechanism which relaxes the constraints minimally to facilitate convergence. Sometimes, especially in the case of degenerate states, deltascf_smearing is necessary. Reinhard J. Maurer and Karsten Reuter. Assessing computationally efficient isomerization dynamics: \u0394SCF density-functional theory study of azobenzene molecular switching. The Journal of Chemical Physics , 135(22):224303, 12 2011. doi:10.1063/1.3664305 . \u21a9","title":"Simple Delta SCF"},{"location":"documentation/Delta_SCF/simple_delta_scf/#conventional-delta-self-consistent-field-dft-calculations","text":"","title":"Conventional Delta-Self-Consistent-Field-DFT Calculations"},{"location":"documentation/Delta_SCF/simple_delta_scf/#basics","text":"In \\Delta \\Delta SCF-DFT we calculate electronic excited states by assuming a certain non-equilibrium orbital occupation and by self-consistently solving the Kohn-Sham equations with this excited state population. The excitation energy is then simply the energy difference between the ground state KS-DFT calculation and the \\Delta \\Delta SCF-DFT calculation: \\Delta E = E(\\Delta SCF)-E(DFT) \\Delta E = E(\\Delta SCF)-E(DFT) We therefore need to perform two calculations, the ground state DFT calculation and the DeltaSCF calculation. For a more detailed explanation, see Maurer and Reuter (2011) 1 . For this simple \\Delta \\Delta SCF calculation, we have to set deltascf_method = simple in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_smearing Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.0000 1 34 34 35 1.0000 1 35 35 %endblock deltascf_constraints In this example, we enforce an occupation of 0.00 electrons in the electronic state 34, spin channel 1 and an occupation of 1.00 electrons in the electronic state 35, spin channel 1. The last two numbers in each line specify a window of states in which the corresponding state is searched if it changes its position between SCF cycles. In that way we can ensure that we constrain the correct state. deltascf_smearing is a mechanism which relaxes the constraints minimally to facilitate convergence. Sometimes, especially in the case of degenerate states, deltascf_smearing is necessary. Reinhard J. Maurer and Karsten Reuter. Assessing computationally efficient isomerization dynamics: \u0394SCF density-functional theory study of azobenzene molecular switching. The Journal of Chemical Physics , 135(22):224303, 12 2011. doi:10.1063/1.3664305 . \u21a9","title":"Basics"},{"location":"documentation/EPR/overview/","text":"In crystalline materials, electron paramagnetic resonance (EPR) can be used to study paramagnetic defects. EPR spectra of spin \u00bd centers have two contributions: the hyperfine tensor {\\bf A} {\\bf A} and the g-tensor {\\bf g} {\\bf g} , which are defined through the following effective Hamiltonian \\begin{equation} H_{eff}=\\frac{\\alpha}{2}{\\bf S}\\cdot{\\bf g}\\cdot{\\bf B} + \\sum_I {\\bf S}\\cdot{\\bf A}_{I}\\cdot{\\bf I}_I \\end{equation} where \\alpha \\alpha is the fine structure constant and the summation I I runs over nuclei. The hyperfine tensor arises from the interaction of the nuclei with the ground-state spin density. This term has been calculated within the planewave-pseudopotential approach; indeed it was for this property that the PAW scheme was first introduced.\\cite{walle93} The g-tensor arises from the interaction of the electronic spin with the external magnetic field. This term plays an somewhat similar role to the shielding in NMR; induced electronic currents in the sample modify the g-tensor from its vacuum value. The GIPAW approach has been used to compute g-tensors in several crystalline materials including defects in \\alpha \\alpha -quartz and zirconia.","title":"EPR Overview"},{"location":"documentation/Geometry_Optimisation/constraints/","text":"Atomic constraints CASTEP can impose various forms of linear or non-linear constraints upon the positions of the atoms. This can be used with all forms of geometry optimization and molecular dynamics. Some simple short cuts exist, such as to keep all the atoms fixed: FIX_ALL_IONS : T or to fix the Centre of Mass: FIX_COM : T It is also possible to specify constraints on individual atoms, using the IONIC_CONSTRAINTS block. The simplest case is to control which atoms remain fixed during a geometry optimisation. e.g. %BLOCK IONIC_CONSTRAINTS fix: C 1 !fix position of atom C 1 %ENDBLOCK IONIC_CONSTRAINTS Some further examples include fix: all !fix all atoms\u2028 fix: C N !fix species C and N\u2028 fix: C 1 !fix position of atom C 1\u2028 fix: C{1,3,5-10} !fix positions of atoms C1, C3, C5,C6,C7,C8,C9,C10\u2028 fix: all unfix: H !fix positions of all atoms except H The last example in particularly useful in the case of molecular crystals, when you might want to allow the H atoms to move but keep all of the heavy atoms in the positions determined by diffraction. To fix the individual Cartesian components of an atom's position use the full syntax of the ionic_constraints block, where each constraint removes one degree of freedom. For example %BLOCK IONIC_CONSTRAINTS 1 W 1 1.0000000000 0.0000000000 0.0000000000 2 W 1 0.0000000000 1.0000000000 0.0000000000 3 W 1 0.0000000000 0.0000000000 1.0000000000 4 W 2 1.0000000000 0.0000000000 0.0000000000 %ENDBLOCK IONIC_CONSTRAINTS The 1 st line says that constraint number 1 is to fix the x coordinate of Tungsten atom 1. The 2 nd line says that constraint number 2 is to fix the y coordinate of Tungsten atom 1. etc. To fix an atom in 3D requires 3 constraints to remove all 3 degrees of freedom. The ionic_constraints block can also be used to impose any arbitary linear constraint, such as to restrict an atom to move in a plane or along a line, or to fix the centre of mass. A constraint may involve more than 1 atom, and hence can span mulitple lines, but each constraint operates on 1 degree of freedom. It cannot be used to fix a bond length - that is a non-linear constraint - see below for more details. The general syntax for constraint i i operating on atom j j of element X at position r^j r^j is %BLOCK IONIC_CONSTRAINTS ... i X j a1 a2 a3 ... %ENDBLOCK IONIC_CONSTRAINTS and the constraint is specfied as \\begin{equation} C^i={\\bf a^i}\\cdot{\\bf r^j} \\end{equation} where C^i C^i is given by the initial conditions. For example to fix the second S atom to move in the plane parallel to y=x y=x use this: %BLOCK IONIC_CONSTRAINTS 1 S 2 -1 1 0 %ENDBLOCK IONIC_CONSTRAINTS Cell Constraints Cell constraints can be used with all forms of geometry optimization and molecular dynamics that allow the cell size/shape to vary. Some simple short cuts exist, such as to keep the unit cell fixed during the optimisation FIX_CELL : T or to fix the volume (but not the shape) of the unit cell FIX_VOL : T It is also possible to apply an arbitary set of constraints to the cell angles and cell lengths using the CELL_CONSTRAINTS block. %BLOCK CELL_CONSTRAINTS a b c alpha beta gamma %ENDBLOCK CELL_CONSTRAINTS Setting an element to zero means to keep it fixed. Two or more elements set to the same positive integer, means that these elements should be kept equal during the geometry optimisation. For example %BLOCK CELL_CONSTRAINTS 0 0 0 4 5 6 %ENDBLOCK CELL_CONSTRAINTS would keep all cell lengths fixed, and allow the three cell angles to vary independently, and %BLOCK CELL_CONSTRAINTS 0 0 0 4 4 6 %ENDBLOCK CELL_CONSTRAINTS would enforce \\alpha=\\beta\\neq\\gamma \\alpha=\\beta\\neq\\gamma and keep the cell lengths fixed. Symmetry The application of symmetry with constraints (for ionic positions and/or cell vectors) needs to be considered carefully. In general, if symmetry is on, then there is no need to add a constraint to explicitly impose a restriction that is implied by the symmetry. If there is a need for an additional restriction, then that can be added on top of the symmetry, but the user needs to be careful that the additional constraint does not conflict with symmetry. If in doubt, turn symmetry off and impose all the desired constraints explicitly. Non-linear Constraints CASTEP can also support non-linear constraints, such as fixed bond length, in both molecular dynamics, and also in geometry optimization if using GEOM_METHOD=DELOCALISED : %BLOCK NONLINEAR_CONSTRAINTS constraint_type atom1 atom2 (atom3 (atom 4)) ... %ENDBLOCK NONLINEAR_CONSTRAINTS where the first element specifies a constraint type (distance, bend angle or torsion angle). Then depending on the type of constraint, either 2, 3 or 4 atoms need to be specified, and the corresponding quantity (distance, bend angle or torsion angle) is held constant at the initial value. As for (linear) ionic constraints, atoms are specified by species and number within that species. In addition, it is necessary to specify which periodic image of the cell the atom is located in (so constraints can straddle a cell boundary). For instance %BLOCK NONLINEAR_CONSTRAINTS distance H 4 0 0 0 O 2 0 1 0 bend H 5 0 0 0 C 1 1 0 1 H 2 0 0 0 torsion H 6 0 0 0 H 3 1 0 0 H 1 0 0 1 H 9 1 1 1 0 %ENDBLOCK NONLINEAR_CONSTRAINTS specifies: the distance between the 4 th hydrogen atom and the 2 nd oxygen atom in the adjacent ( 0 1 0 ) cell the bend angle defined by the 5 th hydrogen atom, the 1 st carbon atom in the ( 1 0 1 ) cell and the 2 nd hydrogen atom the torsion angle defined by 4 hydrogen atoms, etc.","title":"Constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#atomic-constraints","text":"CASTEP can impose various forms of linear or non-linear constraints upon the positions of the atoms. This can be used with all forms of geometry optimization and molecular dynamics. Some simple short cuts exist, such as to keep all the atoms fixed: FIX_ALL_IONS : T or to fix the Centre of Mass: FIX_COM : T It is also possible to specify constraints on individual atoms, using the IONIC_CONSTRAINTS block. The simplest case is to control which atoms remain fixed during a geometry optimisation. e.g. %BLOCK IONIC_CONSTRAINTS fix: C 1 !fix position of atom C 1 %ENDBLOCK IONIC_CONSTRAINTS Some further examples include fix: all !fix all atoms\u2028 fix: C N !fix species C and N\u2028 fix: C 1 !fix position of atom C 1\u2028 fix: C{1,3,5-10} !fix positions of atoms C1, C3, C5,C6,C7,C8,C9,C10\u2028 fix: all unfix: H !fix positions of all atoms except H The last example in particularly useful in the case of molecular crystals, when you might want to allow the H atoms to move but keep all of the heavy atoms in the positions determined by diffraction. To fix the individual Cartesian components of an atom's position use the full syntax of the ionic_constraints block, where each constraint removes one degree of freedom. For example %BLOCK IONIC_CONSTRAINTS 1 W 1 1.0000000000 0.0000000000 0.0000000000 2 W 1 0.0000000000 1.0000000000 0.0000000000 3 W 1 0.0000000000 0.0000000000 1.0000000000 4 W 2 1.0000000000 0.0000000000 0.0000000000 %ENDBLOCK IONIC_CONSTRAINTS The 1 st line says that constraint number 1 is to fix the x coordinate of Tungsten atom 1. The 2 nd line says that constraint number 2 is to fix the y coordinate of Tungsten atom 1. etc. To fix an atom in 3D requires 3 constraints to remove all 3 degrees of freedom. The ionic_constraints block can also be used to impose any arbitary linear constraint, such as to restrict an atom to move in a plane or along a line, or to fix the centre of mass. A constraint may involve more than 1 atom, and hence can span mulitple lines, but each constraint operates on 1 degree of freedom. It cannot be used to fix a bond length - that is a non-linear constraint - see below for more details. The general syntax for constraint i i operating on atom j j of element X at position r^j r^j is %BLOCK IONIC_CONSTRAINTS ... i X j a1 a2 a3 ... %ENDBLOCK IONIC_CONSTRAINTS and the constraint is specfied as \\begin{equation} C^i={\\bf a^i}\\cdot{\\bf r^j} \\end{equation} where C^i C^i is given by the initial conditions. For example to fix the second S atom to move in the plane parallel to y=x y=x use this: %BLOCK IONIC_CONSTRAINTS 1 S 2 -1 1 0 %ENDBLOCK IONIC_CONSTRAINTS","title":"Atomic constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#cell-constraints","text":"Cell constraints can be used with all forms of geometry optimization and molecular dynamics that allow the cell size/shape to vary. Some simple short cuts exist, such as to keep the unit cell fixed during the optimisation FIX_CELL : T or to fix the volume (but not the shape) of the unit cell FIX_VOL : T It is also possible to apply an arbitary set of constraints to the cell angles and cell lengths using the CELL_CONSTRAINTS block. %BLOCK CELL_CONSTRAINTS a b c alpha beta gamma %ENDBLOCK CELL_CONSTRAINTS Setting an element to zero means to keep it fixed. Two or more elements set to the same positive integer, means that these elements should be kept equal during the geometry optimisation. For example %BLOCK CELL_CONSTRAINTS 0 0 0 4 5 6 %ENDBLOCK CELL_CONSTRAINTS would keep all cell lengths fixed, and allow the three cell angles to vary independently, and %BLOCK CELL_CONSTRAINTS 0 0 0 4 4 6 %ENDBLOCK CELL_CONSTRAINTS would enforce \\alpha=\\beta\\neq\\gamma \\alpha=\\beta\\neq\\gamma and keep the cell lengths fixed.","title":"Cell Constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#symmetry","text":"The application of symmetry with constraints (for ionic positions and/or cell vectors) needs to be considered carefully. In general, if symmetry is on, then there is no need to add a constraint to explicitly impose a restriction that is implied by the symmetry. If there is a need for an additional restriction, then that can be added on top of the symmetry, but the user needs to be careful that the additional constraint does not conflict with symmetry. If in doubt, turn symmetry off and impose all the desired constraints explicitly.","title":"Symmetry"},{"location":"documentation/Geometry_Optimisation/constraints/#non-linear-constraints","text":"CASTEP can also support non-linear constraints, such as fixed bond length, in both molecular dynamics, and also in geometry optimization if using GEOM_METHOD=DELOCALISED : %BLOCK NONLINEAR_CONSTRAINTS constraint_type atom1 atom2 (atom3 (atom 4)) ... %ENDBLOCK NONLINEAR_CONSTRAINTS where the first element specifies a constraint type (distance, bend angle or torsion angle). Then depending on the type of constraint, either 2, 3 or 4 atoms need to be specified, and the corresponding quantity (distance, bend angle or torsion angle) is held constant at the initial value. As for (linear) ionic constraints, atoms are specified by species and number within that species. In addition, it is necessary to specify which periodic image of the cell the atom is located in (so constraints can straddle a cell boundary). For instance %BLOCK NONLINEAR_CONSTRAINTS distance H 4 0 0 0 O 2 0 1 0 bend H 5 0 0 0 C 1 1 0 1 H 2 0 0 0 torsion H 6 0 0 0 H 3 1 0 0 H 1 0 0 1 H 9 1 1 1 0 %ENDBLOCK NONLINEAR_CONSTRAINTS specifies: the distance between the 4 th hydrogen atom and the 2 nd oxygen atom in the adjacent ( 0 1 0 ) cell the bend angle defined by the 5 th hydrogen atom, the 1 st carbon atom in the ( 1 0 1 ) cell and the 2 nd hydrogen atom the torsion angle defined by 4 hydrogen atoms, etc.","title":"Non-linear Constraints"},{"location":"documentation/Geometry_Optimisation/files/","text":".geom The .geom file is the primary output file, and contains the unit cell, positions of the atoms and the forces on the atoms for each step of the geometry optimisation. The format of this file is very similar to the .md file. BEGIN header END header 0 F F F F <-- c -1.1089287934762380E+000 -1.1089287934762380E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 0.0000000000000000E+000 0.0000000000000000E+000 0.0000000000000000E+000 <-- R H 2 0.0000000000000000E+000 0.0000000000000000E+000 1.8897261258369291E+000 <-- R H 1 5.2328399876121735E-008 -1.0421543664521416E-007 7.0009877481903737E-002 <-- F H 2 -5.2328399876121735E-008 1.0421543664521414E-007 -7.0009877481903737E-002 <-- F 1 F F F T <-- c -1.1238786617585625E+000 -1.1238786617585625E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 9.4833861449528325E-008 -1.8886784811136898E-007 1.2687770000486739E-001 <-- R H 2 -9.4833861449528339E-008 1.8886784811136895E-007 1.7628484258320618E+000 <-- R H 1 -3.5821658412345467E-009 7.1341230429117867E-009 4.3459352502549203E-002 <-- F H 2 3.5821658412345467E-009 -7.1341230429117867E-009 -4.3459352502549203E-002 <-- F 5 T T T T <-- c -1.1282766172341445E+000 -1.1282766172341445E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 -3.9595146097124387E-007 7.8856409239690845E-007 2.1772199021621047E-001 <-- R H 2 3.9595146097124376E-007 -7.8856409239690845E-007 1.6720041356207189E+000 <-- R H 1 -8.2747158669639466E-009 1.6479675454026804E-008 1.5340573808683700E-006 <-- F H 2 8.2747158669639466E-009 -1.6479675454026804E-008 -1.5340573808683700E-006 <-- F All quantities are reported in atomic units (this cannot be changed by any parameter) <-- c Reports the iteration number and whether the convergence criteria are satisfied. <-- E Energy (total energy, enthalpy) <-- h Unit cell vectors <-- S Stress on unit cell (only reported if the cell is allowed to change) <-- R Cartesian positions of atoms <-- F Force on atoms The '\u2190 c' line also reports the status of 4 convergence flags (either F=false or T=true). These are (in order): dE - has the energy change/atom been below geom_energy_tol for the last geom_convergence_win steps? Fmax - is the largest component of any force below geom_force_tol? dRmax - is the largest change in position for any atom below geom_disp_tol? Smax - is the largest component of the stress tensor below geom_stress_tol?","title":"Files"},{"location":"documentation/Geometry_Optimisation/files/#geom","text":"The .geom file is the primary output file, and contains the unit cell, positions of the atoms and the forces on the atoms for each step of the geometry optimisation. The format of this file is very similar to the .md file. BEGIN header END header 0 F F F F <-- c -1.1089287934762380E+000 -1.1089287934762380E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 0.0000000000000000E+000 0.0000000000000000E+000 0.0000000000000000E+000 <-- R H 2 0.0000000000000000E+000 0.0000000000000000E+000 1.8897261258369291E+000 <-- R H 1 5.2328399876121735E-008 -1.0421543664521416E-007 7.0009877481903737E-002 <-- F H 2 -5.2328399876121735E-008 1.0421543664521414E-007 -7.0009877481903737E-002 <-- F 1 F F F T <-- c -1.1238786617585625E+000 -1.1238786617585625E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 9.4833861449528325E-008 -1.8886784811136898E-007 1.2687770000486739E-001 <-- R H 2 -9.4833861449528339E-008 1.8886784811136895E-007 1.7628484258320618E+000 <-- R H 1 -3.5821658412345467E-009 7.1341230429117867E-009 4.3459352502549203E-002 <-- F H 2 3.5821658412345467E-009 -7.1341230429117867E-009 -4.3459352502549203E-002 <-- F 5 T T T T <-- c -1.1282766172341445E+000 -1.1282766172341445E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 -3.9595146097124387E-007 7.8856409239690845E-007 2.1772199021621047E-001 <-- R H 2 3.9595146097124376E-007 -7.8856409239690845E-007 1.6720041356207189E+000 <-- R H 1 -8.2747158669639466E-009 1.6479675454026804E-008 1.5340573808683700E-006 <-- F H 2 8.2747158669639466E-009 -1.6479675454026804E-008 -1.5340573808683700E-006 <-- F All quantities are reported in atomic units (this cannot be changed by any parameter) <-- c Reports the iteration number and whether the convergence criteria are satisfied. <-- E Energy (total energy, enthalpy) <-- h Unit cell vectors <-- S Stress on unit cell (only reported if the cell is allowed to change) <-- R Cartesian positions of atoms <-- F Force on atoms The '\u2190 c' line also reports the status of 4 convergence flags (either F=false or T=true). These are (in order): dE - has the energy change/atom been below geom_energy_tol for the last geom_convergence_win steps? Fmax - is the largest component of any force below geom_force_tol? dRmax - is the largest change in position for any atom below geom_disp_tol? Smax - is the largest component of the stress tensor below geom_stress_tol?","title":".geom"},{"location":"documentation/Geometry_Optimisation/keywords/","text":"To perform a geometry optimisation set the task parameter task : geomopt The convergence criteria have the following default values, each of which can be set independently. geom_energy_tol : Tolerance on energy change between iterations (default: 2.0e-5 eV) geom_force_tol : Tolerance on maximum force on each atom (default: 0.05 eV/ANG) geom_stress_tol : Tolerance on maximum stress on cell (default: 0.1 GPa) geom_disp_tol : Tolerance on change in atom positions between iterations (default: 0.001: Ang) geom_max_iter : Maximum number of iterations (default: 30) It is possible to change the optimisation method, and to choose a preconditioner. geom_method : LBFGS (default), BFGS, TPSD, DAMPEDMD, FIRE geom_preconditioner : EXP / FF / ID # EXPonential, Force Field, Identity (default) It is useful to set the following two parameters in a geometry optimisation. These will cause CASTEP to write a new cell/cif file with the final optimised coordinates write_cell_structure : T write_cif_structure : T","title":"Keywords"},{"location":"documentation/Geometry_Optimisation/overview/","text":"The essence of the calculation is for the ions and electrons in the supercell to be moved around stepwise until the forces on the atoms and the change in total energy between steps fall below some predefined convergence tolerance. The ionic positions are optimised using quasi-Newton methods. For each configuration of the ionic positions the electronic configuration is optimised using the method of conjugate gradients. The flow of the calculation is thus; Move ions into new positions using geometry optimisation algorithm Find electronic energy and forces for this ionic configuration Compare total energy with previous configurations and check if forces within tolerance limits If structure not optimised start at (1) and generate new set of ionic positions This cycle is performed until the forces fall within the tolerance limit and the energy should then be a local minimum. With periodic boundary conditions (as used by CASTEP) it is also possible to change the size and shape of the cell, in addition to (or instead of) moving the ions. In this case, the stress is calculated in addition to the forces, and this is used to change the cell, until the stress falls within a given tolerance. Finally, when considering the change in the cell, it is also possible to apply an external pressure. Hence it is the enthalpy, which is the appropriate free energy in this scenario, which is minimised instead of the energy. Finite-basis set corrections It should be noted, that with a plane-wave basis set (as used by CASTEP) there is an important side-effect of changing the size and/or shape of the cell - it changes the basis set used for the electronic states. Many DFT programs ignore this effect, which means that if the cell vectors change by more than a few %, the final structure is evaluated with a non-self-consistent basis, with a different cut-off energy to that intended. In CASTEP, there are two choices here: to either keep the cut-off energy constant (which results in the number and meaning of the plane-waves used in the basis changing from step-to-step) or to keep the number of plane-waves constant (which results in a change in the cut-off energy and in the meaning of the plane-waves used from step-to-step). The constant-cutoff/variable-number of plane-waves approach is the CASTEP default as it is the most physically reasonable. The constant number of plane-waves approach means that the quality of the calculation is changing from step-to-step. The effect of changing lattice vectors on the basis set can also be corrected to first-order using the 'finite basis set correction'. This can be calculated by the change in total energy for a small change in the cut-off energy at the start of a calculation, and then used as a correction to the energy and the stress. This is especially important in variable-cell calculations, for which it is activated by default. Advanced settings For geometry optimisation, there are a variety of different algorithms available which can be selected by the geom_method parameter in the param file. The choices are: LBFGS - the low-memory version of BFGS - the default option BFGS - widely-used quasi-Newton minimization TPSD - two-point steepest descent DELOCALIZED - a BFGS-based minimizer using delocalized internal coordinates DMD - optimally damped MD FIRE - fast inertial relaxation engine - a modified MD approach NB These are all 'local optimisations', i.e. the final structure depends upon the initial configuration and is not the global minimum. For those interested in finding the global minimum, then there are associated projects using Genetic Algorithms and AIRSS. The first 3 methods can do variable-cell or fixed-cell optimization, whereas the last 3 are only fixed-cell (for now). LBFGS/BFGS is generally the fastest method, and since v19, LBFGS has supported new preconditioners which should make it generally faster still. TPSD (unlike LBFGS/BFGS) has no built-in history, so should be much slower - however, the CASTEP implementation has a very efficient preconditioner which makes up for this, and the lack of history means that variable-cell optimisation with additional cell constraints is much more efficient than the equivalent calculation in LBFGS/BFGS. The DELOCALIZED minimizer is the only supported method to use delocalized internal coordinates, as opposed to absolute or fractional coordinates, and as such, should be best for optimizing large structures such as molecule-in-a-box with many low-energy soft modes. The two MD-based methods are generally less efficient, but can handle arbitrary constraints well, and have sometimes out-performed other methods for very anisotropic systems, such as molecule-on-a-surface etc.","title":"Overview"},{"location":"documentation/Geometry_Optimisation/overview/#finite-basis-set-corrections","text":"It should be noted, that with a plane-wave basis set (as used by CASTEP) there is an important side-effect of changing the size and/or shape of the cell - it changes the basis set used for the electronic states. Many DFT programs ignore this effect, which means that if the cell vectors change by more than a few %, the final structure is evaluated with a non-self-consistent basis, with a different cut-off energy to that intended. In CASTEP, there are two choices here: to either keep the cut-off energy constant (which results in the number and meaning of the plane-waves used in the basis changing from step-to-step) or to keep the number of plane-waves constant (which results in a change in the cut-off energy and in the meaning of the plane-waves used from step-to-step). The constant-cutoff/variable-number of plane-waves approach is the CASTEP default as it is the most physically reasonable. The constant number of plane-waves approach means that the quality of the calculation is changing from step-to-step. The effect of changing lattice vectors on the basis set can also be corrected to first-order using the 'finite basis set correction'. This can be calculated by the change in total energy for a small change in the cut-off energy at the start of a calculation, and then used as a correction to the energy and the stress. This is especially important in variable-cell calculations, for which it is activated by default.","title":"Finite-basis set corrections"},{"location":"documentation/Geometry_Optimisation/overview/#advanced-settings","text":"For geometry optimisation, there are a variety of different algorithms available which can be selected by the geom_method parameter in the param file. The choices are: LBFGS - the low-memory version of BFGS - the default option BFGS - widely-used quasi-Newton minimization TPSD - two-point steepest descent DELOCALIZED - a BFGS-based minimizer using delocalized internal coordinates DMD - optimally damped MD FIRE - fast inertial relaxation engine - a modified MD approach NB These are all 'local optimisations', i.e. the final structure depends upon the initial configuration and is not the global minimum. For those interested in finding the global minimum, then there are associated projects using Genetic Algorithms and AIRSS. The first 3 methods can do variable-cell or fixed-cell optimization, whereas the last 3 are only fixed-cell (for now). LBFGS/BFGS is generally the fastest method, and since v19, LBFGS has supported new preconditioners which should make it generally faster still. TPSD (unlike LBFGS/BFGS) has no built-in history, so should be much slower - however, the CASTEP implementation has a very efficient preconditioner which makes up for this, and the lack of history means that variable-cell optimisation with additional cell constraints is much more efficient than the equivalent calculation in LBFGS/BFGS. The DELOCALIZED minimizer is the only supported method to use delocalized internal coordinates, as opposed to absolute or fractional coordinates, and as such, should be best for optimizing large structures such as molecule-in-a-box with many low-energy soft modes. The two MD-based methods are generally less efficient, but can handle arbitrary constraints well, and have sometimes out-performed other methods for very anisotropic systems, such as molecule-on-a-surface etc.","title":"Advanced settings"},{"location":"documentation/Geometry_Optimisation/tools/","text":"JMol can read a .geom file and animate the movement of atoms during the optimisation. See tutorials for more examples.","title":"Tools"},{"location":"documentation/Getting_Started/basic_cell_file/","text":"This is a basic overview of the cell file. See the full cell file page for more details. The cell file is one of CASTEP's two main input files. It contains all of the information about the crystal lattice and the atomic positions, as well as additional information such as Brillouin zone sampling ('k-points'), pseudopotentials, and atomic properties. The file itself is a free-format keyword-driven text file, consisting of keywords and blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. Most of the keywords and blocks are optional, but CASTEP requires two block entries: a block to specify the lattice, and another to specify the atomic elements and positions within the cell. Lattice There are two main ways to set the crystal lattice in the cell file. The lattice_abc block specifies the lattice constants in terms of the lengths of the lattice vectors ( \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} ) and angles (alpha, beta and gamma): %block lattice_abc a b c alpha beta gamma %endblock lattice_abc This doesn't specify how the cell is to be oriented in the Cartesian coordinate system, so CASTEP uses the convention that \\mathbf{a} \\mathbf{a} is along the x-axis, and \\mathbf{b} \\mathbf{b} is in the x-y plane. Alternatively, you can specify the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} directly in terms of their Cartesian components, using the lattice_cart block. Note that these are specified as row vectors: %block lattice_cart [unit] a_x a_y a_z b_x b_y b_z c_x c_y c_z %endblock lattice_cart The first line is optional, and specifies a length unit; the default is ang , meaning Angstroms. Atomic positions The positions of the atoms within a cell may be specified in either fractional coordinates (i.e. the coordinates in the basis of the lattice vectors) or Cartesian coordinates: %block positions_frac symbol u v w %endblock positions_frac where symbol is the chemical symbol for the atomic element, and u , v and w are the fractional components of the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} , respectively, such that the Cartesian positions vector of the atom, \\mathbf{r} \\mathbf{r} , is \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} To add a second atom, simply add a second line with the new information, and similarly for additional atoms. An alternative is to specify the atomic coordinates with reference to their absolute Cartesian coordinates: %block positions_abs [unit] symbol x y z %endblock positions_abs where [unit] is an optional length unit (default: ang , meaning Angstroms), symbol is the chemical symbol for the atomic element, and x , y and z are the Cartesian coordinates of the atom, such that the position vector, \\mathbf{r}=(x,y,z) \\mathbf{r}=(x,y,z) . Comments It can be convenient to add comments to a cell file, not only to explain why certain choices were made, but also as a way of disabling input lines without removing them from the file. Both ! and # are accepted as comment characters, and anything to the right of these will be ignored by CASTEP. For example, the cell section # Place a single atom at the origin %block positions_abs bohr C 0.00000000 0.00000000 0.00000000 !Si 0.00000000 0.00000000 0.00000000 %endblock positions_abs has a comment explaining the atomic coordinates, and a single carbon atom at the origin. The second atomic position is commented out, so CASTEP will ignore it.","title":"cell File"},{"location":"documentation/Getting_Started/basic_cell_file/#lattice","text":"There are two main ways to set the crystal lattice in the cell file. The lattice_abc block specifies the lattice constants in terms of the lengths of the lattice vectors ( \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} ) and angles (alpha, beta and gamma): %block lattice_abc a b c alpha beta gamma %endblock lattice_abc This doesn't specify how the cell is to be oriented in the Cartesian coordinate system, so CASTEP uses the convention that \\mathbf{a} \\mathbf{a} is along the x-axis, and \\mathbf{b} \\mathbf{b} is in the x-y plane. Alternatively, you can specify the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} directly in terms of their Cartesian components, using the lattice_cart block. Note that these are specified as row vectors: %block lattice_cart [unit] a_x a_y a_z b_x b_y b_z c_x c_y c_z %endblock lattice_cart The first line is optional, and specifies a length unit; the default is ang , meaning Angstroms.","title":"Lattice"},{"location":"documentation/Getting_Started/basic_cell_file/#atomic-positions","text":"The positions of the atoms within a cell may be specified in either fractional coordinates (i.e. the coordinates in the basis of the lattice vectors) or Cartesian coordinates: %block positions_frac symbol u v w %endblock positions_frac where symbol is the chemical symbol for the atomic element, and u , v and w are the fractional components of the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} , respectively, such that the Cartesian positions vector of the atom, \\mathbf{r} \\mathbf{r} , is \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} To add a second atom, simply add a second line with the new information, and similarly for additional atoms. An alternative is to specify the atomic coordinates with reference to their absolute Cartesian coordinates: %block positions_abs [unit] symbol x y z %endblock positions_abs where [unit] is an optional length unit (default: ang , meaning Angstroms), symbol is the chemical symbol for the atomic element, and x , y and z are the Cartesian coordinates of the atom, such that the position vector, \\mathbf{r}=(x,y,z) \\mathbf{r}=(x,y,z) .","title":"Atomic positions"},{"location":"documentation/Getting_Started/basic_cell_file/#comments","text":"It can be convenient to add comments to a cell file, not only to explain why certain choices were made, but also as a way of disabling input lines without removing them from the file. Both ! and # are accepted as comment characters, and anything to the right of these will be ignored by CASTEP. For example, the cell section # Place a single atom at the origin %block positions_abs bohr C 0.00000000 0.00000000 0.00000000 !Si 0.00000000 0.00000000 0.00000000 %endblock positions_abs has a comment explaining the atomic coordinates, and a single carbon atom at the origin. The second atomic position is commented out, so CASTEP will ignore it.","title":"Comments"},{"location":"documentation/Getting_Started/basic_param_file/","text":"This is a basic overview of the param file. See the full param file page for more details. The param file is one of CASTEP's two main input files. It contains all of the information about the kind of simulation your wish CASTEP to perform, as well as details of how CASTEP should perform them and additional simulations and analyses. The file itself is a free-format keyword-driven text file, consisting largely of single-line keywords, although there are a small number of blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. All of the keywords and blocks are optional, but you will almost always want to change at least some. Task This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file . Cut-off energy The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV. XC functional Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"param File"},{"location":"documentation/Getting_Started/basic_param_file/#task","text":"This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file .","title":"Task"},{"location":"documentation/Getting_Started/basic_param_file/#cut-off-energy","text":"The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV.","title":"Cut-off energy"},{"location":"documentation/Getting_Started/basic_param_file/#xc-functional","text":"Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"XC functional"},{"location":"documentation/Getting_Started/built_in_help/","text":"CASTEP has an in-built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: castep -h To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: castep -h kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. castep -s symmetry Finally, to list all keywords, use: castep -h all To find out which version of CASTEP you have, use: castep -v","title":"Command line help"},{"location":"documentation/Getting_Started/intro/","text":"CASTEP is a software package to calculate the properties of materials. It is based on quantum mechanics, in a form known as density functional theory, and can simulate a wide range of materials proprieties including energetics, structure at the atomic level, vibrational properties, and many experimental characterisation methods, such as infra-red and Raman spectra, NMR, and core-level spectra. This documentation This documentation focuses on using CASTEP at the command-line, as a stand-alone program. You can build two versions of CASTEP: a \"serial\" version called castep.serial , which is primarily designed to run on a single CPU core; or a parallel version called castep.mpi , which uses the message passing interface (MPI) to run on more than one core. Most of this documentation applies equally to both versions, but for simplicity we will focus on the serial version in most of the examples. We will refer to the CASTEP command itself as castep , which you will need to change to castep.serial or castep.mpi , as appropriate. In this documentation, anything in a fixed width font like this is text to type, either on the command-line or in a CASTEP input file. For CASTEP's input files, there is sometimes a choice between different settings, and this will be indicated using the | symbol, meaning \"or\". For example, setting : choice_1|choice_2|choice_3 If some of the entries are optional, they will have square brackets around them [like this] , for example: setting : choice_1|choice_2|choice_3 [unit of choice]","title":"Introduction"},{"location":"documentation/Getting_Started/intro/#this-documentation","text":"This documentation focuses on using CASTEP at the command-line, as a stand-alone program. You can build two versions of CASTEP: a \"serial\" version called castep.serial , which is primarily designed to run on a single CPU core; or a parallel version called castep.mpi , which uses the message passing interface (MPI) to run on more than one core. Most of this documentation applies equally to both versions, but for simplicity we will focus on the serial version in most of the examples. We will refer to the CASTEP command itself as castep , which you will need to change to castep.serial or castep.mpi , as appropriate. In this documentation, anything in a fixed width font like this is text to type, either on the command-line or in a CASTEP input file. For CASTEP's input files, there is sometimes a choice between different settings, and this will be indicated using the | symbol, meaning \"or\". For example, setting : choice_1|choice_2|choice_3 If some of the entries are optional, they will have square brackets around them [like this] , for example: setting : choice_1|choice_2|choice_3 [unit of choice]","title":"This documentation"},{"location":"documentation/Getting_Started/restarting/","text":"Checkpointing and Restarting CASTEP provides a mechanism for saving intermediate and final states of the calculation and for restarting or continuing from a saved state. At the end of every calculation which completes normally, CASTEP writes two files .check and .castep_bin which are binary-format files containing a complete state of the calculation including input parameters, cell variables, electron densities and any results or intermediate quantities whose calculation has completed. All inputs and results reported in the .castep file are saved to the checkpoint: indeed a lost .castep file from a completed calculation may be (mostly) regenerated using a minimal continuation run. .check vs .castep_bin The only difference between .check and .castep_bin is that the .check file contains the converged ground-state wavefunctions but .castep_bin does not, and therefore requires much less disk space to store. This makes it useful for purposes of archiving a calculation. When continuing from a .castep_bin CASTEP will regenerate the ground state wavefunctions non-selfconsistently using the ground-state density from the file. Checkpointing during a calculation An incomplete calculation can be completed in a new run by adding the parameters keyword continuation : default in the .param file and rerunning CASTEP as before with the same command-line argument. This is the usual way of continuing a run interrupted, for example, by the job time limit on a batch scheduling system. To benefit from continuation, a checkpoint file must have been written in the original run. There are three parameters keywords which may be used to do this: num_backup_iter write a checkpoint every (default 5) geometry MD or phonon steps backup_interval write a checkpoint every seconds run_time write a checkpoint and exit at the first opportunity after seconds have elapsed. These may be used to periodically checkpoint many lengthy post-SCF tasks including geometry optimization, MD, phonon calculations, but checkpointing of spectral and magres tasks is not supported via this mechanism. Neither is checkpointing possible within an extremely lengthy SCF calculation, but see the next section for an alternative. Checkpoint files are portable, and independent of data-distribution, so the continuation run may use a different number of parallel nodes, data distribution, OpenMP etc. They are also portable across computers, so a run may be started on one computer and finished on another, which may be helpful to balance use of computer resources. Advanced keywords One additional related parameters keyword which finds occasional use is a simple one-liner stop which can be added to the .param file while a run is in progress. CASTEP rereads the .param file at every checkpoint opportunity and if this is present will perform a graceful exit after writing the checkpoint files. Which periodic and end-of-run checkpoint files are written may be controlled by the parameters keyword write_checkpoint which takes values none : to suppress checkpoints completely minimal writes only .castep_bin all : writes both .check and .castep_bin Continuing from completed calculations The checkpoint/restart mechanism may also be used to \"chain\" runs or initialise a modified run with the results of a previous one. The .param file of the new run should contain continuation : .check Parameters values stored in and read from .check will be used, unless overridden by the new .param file, which therefore needs only a minimal number of entries. The .cell file is usually just copy of the original, but may also be modified if needed. Modifying task is a good way to \"chain\" calculations, for example performing a geometry optimisation followed by a spectral calculation. Info Not all parameter or cell keywords can be overridden upon continuation. castep --help will report whether a variable is modifiable on continuation","title":"Checkpoint and Restart"},{"location":"documentation/Getting_Started/restarting/#checkpointing-and-restarting","text":"CASTEP provides a mechanism for saving intermediate and final states of the calculation and for restarting or continuing from a saved state. At the end of every calculation which completes normally, CASTEP writes two files .check and .castep_bin which are binary-format files containing a complete state of the calculation including input parameters, cell variables, electron densities and any results or intermediate quantities whose calculation has completed. All inputs and results reported in the .castep file are saved to the checkpoint: indeed a lost .castep file from a completed calculation may be (mostly) regenerated using a minimal continuation run. .check vs .castep_bin The only difference between .check and .castep_bin is that the .check file contains the converged ground-state wavefunctions but .castep_bin does not, and therefore requires much less disk space to store. This makes it useful for purposes of archiving a calculation. When continuing from a .castep_bin CASTEP will regenerate the ground state wavefunctions non-selfconsistently using the ground-state density from the file.","title":"Checkpointing and Restarting"},{"location":"documentation/Getting_Started/restarting/#checkpointing-during-a-calculation","text":"An incomplete calculation can be completed in a new run by adding the parameters keyword continuation : default in the .param file and rerunning CASTEP as before with the same command-line argument. This is the usual way of continuing a run interrupted, for example, by the job time limit on a batch scheduling system. To benefit from continuation, a checkpoint file must have been written in the original run. There are three parameters keywords which may be used to do this: num_backup_iter write a checkpoint every (default 5) geometry MD or phonon steps backup_interval write a checkpoint every seconds run_time write a checkpoint and exit at the first opportunity after seconds have elapsed. These may be used to periodically checkpoint many lengthy post-SCF tasks including geometry optimization, MD, phonon calculations, but checkpointing of spectral and magres tasks is not supported via this mechanism. Neither is checkpointing possible within an extremely lengthy SCF calculation, but see the next section for an alternative. Checkpoint files are portable, and independent of data-distribution, so the continuation run may use a different number of parallel nodes, data distribution, OpenMP etc. They are also portable across computers, so a run may be started on one computer and finished on another, which may be helpful to balance use of computer resources. Advanced keywords One additional related parameters keyword which finds occasional use is a simple one-liner stop which can be added to the .param file while a run is in progress. CASTEP rereads the .param file at every checkpoint opportunity and if this is present will perform a graceful exit after writing the checkpoint files. Which periodic and end-of-run checkpoint files are written may be controlled by the parameters keyword write_checkpoint which takes values none : to suppress checkpoints completely minimal writes only .castep_bin all : writes both .check and .castep_bin","title":"Checkpointing during a calculation"},{"location":"documentation/Getting_Started/restarting/#continuing-from-completed-calculations","text":"The checkpoint/restart mechanism may also be used to \"chain\" runs or initialise a modified run with the results of a previous one. The .param file of the new run should contain continuation : .check Parameters values stored in and read from .check will be used, unless overridden by the new .param file, which therefore needs only a minimal number of entries. The .cell file is usually just copy of the original, but may also be modified if needed. Modifying task is a good way to \"chain\" calculations, for example performing a geometry optimisation followed by a spectral calculation. Info Not all parameter or cell keywords can be overridden upon continuation. castep --help will report whether a variable is modifiable on continuation","title":"Continuing from completed calculations"},{"location":"documentation/Getting_Started/running_castep/","text":"CASTEP has two main input files, called the cell file and the param file . The cell file defines the structure of the material (or molecule) you wish to study, and the param file defines the kind of simulation CASTEP should perform. The cell and param files should be named using the same prefix, which CASTEP calls the \"seedname\", with the extensions .cell and .param , respectively. For example, for a calculation called mytest , you need the input files mytest.cell mytest.param and the calculation is run with the command castep mytest The main CASTEP output file will be names using the same seedname and the .castep extension, i.e. in the above example it would be called mytest.castep . If this file already exists, CASTEP will append its output to it. When CASTEP completes successfully, it writes additional files such as the .bib file, which contains references to key papers for the theory and methods CASTEP used. If CASTEP encounters a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error files from each of these cores. They are named using the same seedname, but with the numeric process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them. See the Troubleshooting Guide for details of how to find and fix common problems.","title":"Running CASTEP"},{"location":"documentation/Groundstate/ELF/","text":"ELF - Electron Localization Function The ground state electron density, e.g. from a single point calculation or an MD run, etc. contains much useful information. It can be analysed in different ways, and the Electron Localization Function (ELF) is one such. This idea was originally created by Becke and Edgecombe 1 for the analysis of molecules. The idea was later extended to spin and then to solid state systems by Silvi and Savin 2 . It was later discovered that the theoretical expressions were not strictly positive definite, and so a correlation correction was added by Jarvis and Carter 3 , and it is this final form that has been implemented in CASTEP. ELF theory The ELF is given by \\begin{equation} ELF = \\frac{1}{1+\\left( D/D0 \\right)^2} \\end{equation} \\begin{equation} ELF = \\frac{1}{1+\\left( D/D0 \\right)^2} \\end{equation} and for Hartree-Fock approaches we have \\begin{equation} D = \\frac{\\sum{\\left| \\nabla \\psi \\right|^2}}{2} -\\frac{\\left(\\nabla n\\right)^2}{8*n} \\end{equation} with \\psi \\psi being the wavefunction and n n the electron number density, and \\begin{equation} D0 = 0.3*\\left(3*\\pi^2\\right)^{2/3}*n^{5/3} \\end{equation} \\begin{equation} D0 = 0.3*\\left(3*\\pi^2\\right)^{2/3}*n^{5/3} \\end{equation} with D0 D0 is the probability. Hence ELF measures the excess kinetic energy due to Pauli repulsion, and this definition is bounded 0 1 to get more information on what has been included in the D3 correction. In the current implementation, users cannot supply custom parameters for this correction scheme. SEDC_SCHEME : D3 SEDC_SCHEME : D3-BJ This is the Grimme D3 scheme with Becke-Johnson damping. Note When running a D3-BJ calculation with IPRINT > 1 , you might see Dispersion version: D4 in the .castep output file. Confusingly, this does not mean the Grimme D4 method has been used, it's just an interal CASTEP version label for this correction scheme. Compilation flags: for the D3 correction, CASTEP must be compiled with GRIMMED3 := compile Note that for the D3 correction to work, CASTEP must be compiled with the following flag: # Grimme D3 library support. Options are none or compile GRIMMED3 := compile in the Makefile For CASTEP 20, the D3 library is included in the distribution and the setting the flag above should be sufficient. D4 Generally applicable atomic-charge dependent London dispersion correction, termed DFT+D4. It is available from CASTEP 24.1 onwards via setting SEDC_SCHEME : D4 Note that D4 is made available via using the external dftd4 library. This library is included in the CASTEP 24.1 distribution and should be compiled by default when you build CASTEP. Restrictions: Default D4 parameters are available for the PBE, RPBE, PBESOL, BLYP, PW91 and RSCAN functionals. Exchange-dipole moment (XDM) method A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. Restrictions: Default XDM parameters are available for the following XC functionals: B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN SEDC_SCHEME : XDM For functionals that are not in this list, you need to specify the following additional parameters: Customisation keywords .param file SEDC_A1_XDM Type: Real (float) Level: Expert Description: Customisable A1 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default: 1.0. SEDC_A2_XDM Type: Physical (float) Level: Expert Description: Customisable A2 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SC_XDM Type: Real (float) Level: Expert Description: Customisable SC value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_C9_XDM Type: Logical Level: Basic Description: Specifies whether three-body dispersion coefficients are to be computed in the XDM semi-empirical dispersion/ van der Waals correction scheme. Modifiable: restart and on the fly Allowed values: TRUE or FALSE Default is FALSE Note that if you wish to experiment with these values, for example to test a new functional, then careful further testing is necessary. Other Schemes SEDC_SCHEME : OBS Ortmann, Bechstedt and Schmidt Semiempirical van der Waals correction to the density functional description of solids and molecular structures Customisation keywords .param file \" SEDC_LAMBDA_OBS \" Type: Real (float) Level: Expert Description: Customisable lambda value for damping function in the the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . \" SEDC_N_OBS \" Type: Real (float) Level: Expert Description: Customisable n value for the damping function in the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SCHEME : JCHS Jure\u010dka, \u010cern\u00fd, Hobza and Salahub Customisation keywords .param file SEDC_SR_JCHS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_S6_JCHS Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_JCHS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . Stefan Grimme, Andreas Hansen, Jan Gerit Brandenburg, and Christoph Bannwarth. Dispersion-corrected mean-field electronic structure methods. Chemical Reviews , 116(9):5105\u20135154, 2016. PMID: 27077966. doi:10.1021/acs.chemrev.5b00533 . \u21a9 Kyuho Lee, \u00c9amonn D. Murray, Lingzhu Kong, Bengt I. Lundqvist, and David C. Langreth. Higher-accuracy van der Waals density functional. Phys. Rev. B , 82:081101, Aug 2010. doi:10.1103/PhysRevB.82.081101 . \u21a9 Kristian Berland and Per Hyldgaard. Exchange functional that tests the robustness of the plasmon description of the van der Waals density functional. Phys. Rev. B , 89:035412, Jan 2014. doi:10.1103/PhysRevB.89.035412 . \u21a9 Oleg A. Vydrov and Troy Van Voorhis. Nonlocal van der Waals density functional: The simpler the better. The Journal of Chemical Physics , 133(24):244103, 12 2010. doi:10.1063/1.3521275 . \u21a9 Yan Zhao and Donald G. Truhlar. The M06 suite of density functionals for main group thermochemistry, thermochemical kinetics, noncovalent interactions, excited states, and transition elements: two new functionals and systematic testing of four M06-class functionals and 12 other functionals. Theoretical Chemistry Accounts , 120(1):215\u2013241, May 2008. doi:10.1007/s00214-007-0310-x . \u21a9 Jeffrey A. van Santen and Gino A. DiLabio. Dispersion corrections improve the accuracy of both noncovalent and covalent interactions energies predicted by a density-functional theory approximation. The Journal of Physical Chemistry A , 119(25):6703\u20136713, 2015. PMID: 26030132. doi:10.1021/acs.jpca.5b02809 . \u21a9 Grygoriy A. Dolgonos, Johannes Hoja, and A. Daniel Boese. Revised values for the x23 benchmark set of molecular crystals. Phys. Chem. Chem. Phys. , 21:24333\u201324344, 2019. doi:10.1039/C9CP04488D . \u21a9 Ji\u0159\u00ed Klime\u0161, David R. Bowler, and Angelos Michaelides. Van der Waals density functionals applied to solids. Phys. Rev. B , 83:195131, May 2011. doi:10.1103/PhysRevB.83.195131 . \u21a9 Alexandre Tkatchenko and Matthias Scheffler. Accurate molecular van der Waals interactions from ground-state electron density and free-atom reference data. Phys. Rev. Lett. , 102:073005, Feb 2009. doi:10.1103/PhysRevLett.102.073005 . \u21a9 Victor G. Ruiz, Wei Liu, Egbert Zojer, Matthias Scheffler, and Alexandre Tkatchenko. Density-functional theory with screened van der Waals interactions for the modeling of hybrid inorganic-organic systems. Phys. Rev. Lett. , 108:146103, Apr 2012. doi:10.1103/PhysRevLett.108.146103 . \u21a9 Alexandre Tkatchenko, Robert A. DiStasio, Roberto Car, and Matthias Scheffler. Accurate and efficient method for many-body van der Waals interactions. Phys. Rev. Lett. , 108:236402, Jun 2012. doi:10.1103/PhysRevLett.108.236402 . \u21a9 \u21a9 Alberto Ambrosetti, Anthony M. Reilly, Robert A. DiStasio, Jr., and Alexandre Tkatchenko. Long-range correlation energy calculated from coupled atomic response functions. The Journal of Chemical Physics , 140(18):18A508, 02 2014. doi:10.1063/1.4865104 . \u21a9 Stefan Grimme. Semiempirical GGA-type density functional constructed with a long-range dispersion correction. Journal of Computational Chemistry , 27(15):1787\u20131799, 2006. doi:https://doi.org/10.1002/jcc.20495 . \u21a9 Stefan Grimme, Jens Antony, Stephan Ehrlich, and Helge Krieg. A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu. The Journal of Chemical Physics , 132(15):154104, 04 2010. doi:10.1063/1.3382344 . \u21a9 Stefan Grimme, Stephan Ehrlich, and Lars Goerigk. Effect of the damping function in dispersion corrected density functional theory. Journal of Computational Chemistry , 32(7):1456\u20131465, 2011. arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/jcc.21759 , doi:https://doi.org/10.1002/jcc.21759 . \u21a9 Eike Caldeweyher, Christoph Bannwarth, and Stefan Grimme. Extension of the d3 dispersion coefficient model. The Journal of Chemical Physics , July 2017. URL: http://dx.doi.org/10.1063/1.4993215 , doi:10.1063/1.4993215 . \u21a9 Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph Bannwarth, and Stefan Grimme. A generally applicable atomic-charge dependent london dispersion correction. The Journal of Chemical Physics , April 2019. URL: http://dx.doi.org/10.1063/1.5090222 , doi:10.1063/1.5090222 . \u21a9 Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. Extension and evaluation of the d4 london-dispersion model for periodic systems. Physical Chemistry Chemical Physics , 22(16):8499\u20138512, 2020. URL: http://dx.doi.org/10.1039/D0CP00502A , doi:10.1039/d0cp00502a . \u21a9 F. Ortmann, F. Bechstedt, and W. G. Schmidt. Semiempirical van der Waals correction to the density functional description of solids and molecular structures. Phys. Rev. B , 73:205101, May 2006. doi:10.1103/PhysRevB.73.205101 . \u21a9 Petr Jure\u010dka, Ji\u0159\u00ed \u010cern\u00fd, Pavel Hobza, and Dennis R. Salahub. Density functional theory augmented with an empirical dispersion term. Interaction energies and geometries of 80 noncovalent complexes compared with ab initio quantum mechanics calculations. Journal of Computational Chemistry , 28(2):555\u2013569, 2007. doi:10.1002/jcc.20570 . \u21a9 Axel D. Becke and Erin R. Johnson. A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. The Journal of Chemical Physics , 127(12):124108, 09 2007. doi:10.1063/1.2768530 . \u21a9 Daniel G. A. Smith, Lori A. Burns, Konrad Patkowski, and C. David Sherrill. Revised damping parameters for the d3 dispersion correction to density functional theory. The Journal of Physical Chemistry Letters , 7(12):2197\u20132203, 2016. PMID: 27203625. doi:10.1021/acs.jpclett.6b00780 . \u21a9","title":"Dispersion Corrections"},{"location":"documentation/Groundstate/dftd/#long-range-dispersion-corrections","text":"","title":"Long-range dispersion corrections"},{"location":"documentation/Groundstate/dftd/#background","text":"","title":"Background"},{"location":"documentation/Groundstate/dftd/#why-and-when-are-long-range-dispersion-methods-needed","text":"Van der Waals (vdW) interactions are ubiquitous in nature but aren't accounted for by standard local and semilocal density functional approximations (i.e. LDA or GGAs). In particular, the long-range attractive part of the vdW interaction between system components (London dispersion interaction) is not captured. Including such dispersion effects is essential for accurately describing certain systems, especially for systems that are not bound ionically or covalently, e.g. gas molecules. The use of a dispersion method is strongly recommended when intermolecular interactions are expected to play a key role such as in molecular crystals, stacked 2D materials, and generally any weakly-bound system.","title":"Why and when are long range-dispersion methods needed?"},{"location":"documentation/Groundstate/dftd/#types-of-correction-schemes","text":"There are several families of dispersion methods. A good summary of these can be found in the 2016 review by Grimme et al . 1 We will summarise these categories here and, for those implemented in CASTEP, link to the relevant keywords. Semiempirical/semiclassical treatments Here the dispersion energy is calculated atom-wise (typically pair-wise) and is added to the DFT energy of the underlying functional. Note that a specific damping parameter (and function) is usually used to combine a given underlying functional (e.g. PBE) with a dispersion correction (e.g. D3). This means, for example, that the D3 correction to the PBE functional may be different to the D3 correction to HSE. Methods include: The Tkatchenko\u2212Scheffler scheme ( TS ) The TS-based many-body dispersion scheme ( MBD ) Grimme's D2 and D3 methods The exchange-dipole moment model ( XDM ) Nonlocal density-based treatments (not implemented in CASTEP) Here non-local functionals of the electronic density are constructed. Methods include the van der Waals functionals (e.g. vdW-DF2 2 and vdW-DF-cx 3 ) and Vydrov and Van Voorhis functionals 4 . Effective one-electron potentials (not implemented in CASTEP) Finally, the many-body correlated motion of electrons can be, to some extent, captured empiricially by using effective one-electron potentials. Examples of these include: semi-local functionals such as the Minnesota functionals (e.g. M06 5 ) and external potentials such as the dispersion-corrected atom-centered potentials (e.g. van Santen and DiLabio, 2015 6 ).","title":"Types of correction schemes"},{"location":"documentation/Groundstate/dftd/#general-recommendations","text":"Every application will have its own set of important features and it is not possible to say with certainty which density functional approximation will be the most appropriate. With that said, here are some suggestions for different types of materials: Molecular crystals: D3-BJ/XDM/MBD in combination with GGA or hybrid functionals (Dolgonos et al ., 2019 7 ). Metals: vdW-DFs developed with solid state materials in mind (Klime\u0161 et al ., 2011 8 ). Interactions between molecules and surfaces of metals: vdW-DFs or dispersion methods that include screening, e.g. TSSCS MOFs: dispersion corrected (e.g. TS, D3, etc.) GGAs Layered vdW materials: Beyond pairwise approaches, e.g. D3-BJ* or MBD. ^* ^* See note below for how to include the three-body terms in the CASTEP D3 correction. Again, please do your own testing and consult relevant reviews and benchmarking papers. For the TS, MBD and XDM methods you may get a warning if your unit cell is small (where the lattice constants are comparable to the vdW radii). This has been fixed in academic CASTEP v24.1 for TS and MBD, and in v25 for XDM. If you are using an older version of CASTEP, then you should try to use larger unit cells until your dispersion correction converges. Not all XC_FUNCTIONAL values are supported for all schemes - if in doubt use PBE. The primary 'XC_FUNCTIONAL' for XDM is B86PBE. Each scheme has default parameters defined for a subset of elements (see table below). For other elements you need to define custom parameters using the SEDC_CUSTOM_PARAMS keyword in the .cell file.","title":"General recommendations"},{"location":"documentation/Groundstate/dftd/#using-dispersion-corrections-in-castep","text":"","title":"Using dispersion corrections in CASTEP"},{"location":"documentation/Groundstate/dftd/#param-file-keywords","text":"In the .param file, set: SEDC_APPLY : true turns on dispersion correction. SEDC_SCHEME : The semi-empirical dispersion/van der Waals correction scheme to use. Default is NONE , other possible values listed in the table below. SEDC_SCHEME Available from CASTEP version Compatible XC functionals Elements supported Stresses Phonons ^* ^* TS 9 Predates 2012 PBE, PBE0, PBE1PBE, BLYP, B3LYP, AM0, RPB, PBESOL, PW91 Up to Z=54 with first row Lanthanides Analytic DFPT & FD TSSURF 10 Not sure if working TSSCS 11 Not sure if working Up to Z=54 with first row Lanthanides Analytic MBD (Alias: MBD*) 11 12 2015? Rewritten (and fixed) for CASTEP 18 PBE, PBE0, PBE1PBE, HSE03, HSE06, RSCAN Up to Z=54 with first row Lanthanides Numeric FD G06 (= D2) 13 Predates 2012 PBE, BLYP, BP86, B3LYP, TPSS Up to Z= 54 Analytic DFPT & FD D3 14 CASTEP 20 ( Compilation instructions ) PBE, PBE0, HF Analytic FD D3-BJ 15 CASTEP 20 ( Compilation instructions ) PBE, PBE0, HF Analytic FD D4 16 17 18 CASTEP 24.1 PBE, RPBE, PBESOL, BLYP, PW91, RSCAN Analytic FD OBS 19 Predates 2012 LDA, PW91 Up to Z=57 Analytic DFPT & FD JCHS 20 Predates 2012 PBE, BLYP, B3LYP, TPSS H, C, N, O, F, Cl, Br Analytic DFPT & FD XDM 21 CASTEP 20 B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN Up to Z=102 Analytic FD ^* ^* DFPT: Density functional perturbation theory; FD: finite displacement. All of the above methods support analytic forces.","title":".param file keywords"},{"location":"documentation/Groundstate/dftd/#cell-file-keywords","text":"In the .cell file you can optionally set custom parameters for each species: C6 (eV \u00c5 ^6 ^6 ): Available for TS, MBD*, and Grimme schemes. R0 (\u00c5): Available for TS, MBD*, and Grimme schemes. alpha (\u00c5 ^3 ^3 ): Available for TS, MBD*, and OBS schemes. I (eV): Available for the OBS scheme. Rvdw (\u00c5): Available for the OBS scheme. You set them like this: %BLOCK SEDC_CUSTOM_PARAMS ! example values for test purposes only - don't use these... ! He C6:1.00 R0:2.00 Ne C6:10.00 R0:4.00 %ENDBLOCK SEDC_CUSTOM_PARAMS","title":".cell file keywords"},{"location":"documentation/Groundstate/dftd/#method-details-and-customisation","text":"","title":"Method details and customisation"},{"location":"documentation/Groundstate/dftd/#tkatchenkoscheffler-schemes","text":"A density-dependent, atom pairwise dispersion-correction scheme. SEDC_SCHEME : TS Restrictions: Can only be used with the following XC functionals: PBE, PBE0, PBE1PBE, BLYP, B3LYP, AM0, RPB, PBESOL, PW91 Elements up to Z=54 (Xe) together with first row Lanthanides are supported. SEDC_SCHEME : TSSCS TS with self-consistent screening SEDC_SCHEME : TSSURF Customisation keywords for all TS schemes .param file SEDC_SR_TS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the TS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_TS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the TS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For the TS methods, C6 (eV \u00c5 ^6 ^6 ), R0 (\u00c5) and alpha (\u00c5 ^3 ^3 ) can be customised.","title":"Tkatchenko\u2212Scheffler schemes"},{"location":"documentation/Groundstate/dftd/#many-body-dispersion","text":"Beyond what can be included in simple pairwise dispersion approaches, MBD introduces: (1) many-body energy (Axilrod-Teller and higher-order) and (2) long-range Coulomb response (screening) that serves to modify the polarizabilities of interacting species. SEDC_SCHEME : MBD (Alias: MBD* ) Note that the two aliases MBD and MBD* both refer to the revised version of MBD which employs range-separation (rs) of the self-consistent screening (SCS) of polarizabilities and the calculation of the long-range correlation energy, i.e. the MBD@rs-scs method. Restrictions: Can only be used with the following XC functionals: PBE, PBE0, PBE1PBE, HSE03, HSE06, RSCAN Elements up to Z=54 (Xe) together with first row Lanthanides are supported. Note that in the current implementation, only numeric stresses are available. Customisation keywords for MBD scheme .param file SEDC_SR_TS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the TS and MBD correction schemes. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_TS Type: Real (float) Level: Expert Description: Customisable d value for the damping functionin the TS and MBD correction schemes. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For the MBD method, C6 (eV \u00c5 ^6 ^6 ), R0 (\u00c5) and alpha (\u00c5 ^3 ^3 ) can be customised.","title":"Many-body dispersion"},{"location":"documentation/Groundstate/dftd/#grimme-d-corrections","text":"D2 Note that default D2 parameters are available only for the PBE, BLYP, BP86, B3LYP, TPSS functionals. You can also customise the correction parameters using the following keywords: SEDC_SCHEME : G06 Note This is CASTEP's name for the Grimme D2 correction Customisation keywords G06 .param file SEDC_S6_G06 Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the G06 semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_G06 Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the G06 semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For Grimme's D2 method, C6 (eV \u00c5 ^6 ^6 ) and R0 (\u00c5) can be customised. D3 Grimme's DFT-D3 method. The D3 scheme with Becke-Johnson damping (D3-BJ) is generally more accurate 22 than the 'zero-damping' method (D3). Note that most published results for \"D3\" are actually \"D3-BJ\", and that the original version of D3 is rarely used any more. Restrictions: Default D3 parameters are available for the PBE, PBE0 and HF functionals. By default the three-body term is not included . To include it, set d3_threebody: True within a devel_code block in the .param file. Turn on IPRINT > 1 to get more information on what has been included in the D3 correction. In the current implementation, users cannot supply custom parameters for this correction scheme. SEDC_SCHEME : D3 SEDC_SCHEME : D3-BJ This is the Grimme D3 scheme with Becke-Johnson damping. Note When running a D3-BJ calculation with IPRINT > 1 , you might see Dispersion version: D4 in the .castep output file. Confusingly, this does not mean the Grimme D4 method has been used, it's just an interal CASTEP version label for this correction scheme. Compilation flags: for the D3 correction, CASTEP must be compiled with GRIMMED3 := compile Note that for the D3 correction to work, CASTEP must be compiled with the following flag: # Grimme D3 library support. Options are none or compile GRIMMED3 := compile in the Makefile For CASTEP 20, the D3 library is included in the distribution and the setting the flag above should be sufficient. D4 Generally applicable atomic-charge dependent London dispersion correction, termed DFT+D4. It is available from CASTEP 24.1 onwards via setting SEDC_SCHEME : D4 Note that D4 is made available via using the external dftd4 library. This library is included in the CASTEP 24.1 distribution and should be compiled by default when you build CASTEP. Restrictions: Default D4 parameters are available for the PBE, RPBE, PBESOL, BLYP, PW91 and RSCAN functionals.","title":"Grimme D corrections"},{"location":"documentation/Groundstate/dftd/#exchange-dipole-moment-xdm-method","text":"A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. Restrictions: Default XDM parameters are available for the following XC functionals: B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN SEDC_SCHEME : XDM For functionals that are not in this list, you need to specify the following additional parameters: Customisation keywords .param file SEDC_A1_XDM Type: Real (float) Level: Expert Description: Customisable A1 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default: 1.0. SEDC_A2_XDM Type: Physical (float) Level: Expert Description: Customisable A2 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SC_XDM Type: Real (float) Level: Expert Description: Customisable SC value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_C9_XDM Type: Logical Level: Basic Description: Specifies whether three-body dispersion coefficients are to be computed in the XDM semi-empirical dispersion/ van der Waals correction scheme. Modifiable: restart and on the fly Allowed values: TRUE or FALSE Default is FALSE Note that if you wish to experiment with these values, for example to test a new functional, then careful further testing is necessary.","title":"Exchange-dipole moment (XDM) method"},{"location":"documentation/Groundstate/dftd/#other-schemes","text":"SEDC_SCHEME : OBS Ortmann, Bechstedt and Schmidt Semiempirical van der Waals correction to the density functional description of solids and molecular structures Customisation keywords .param file \" SEDC_LAMBDA_OBS \" Type: Real (float) Level: Expert Description: Customisable lambda value for damping function in the the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . \" SEDC_N_OBS \" Type: Real (float) Level: Expert Description: Customisable n value for the damping function in the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SCHEME : JCHS Jure\u010dka, \u010cern\u00fd, Hobza and Salahub Customisation keywords .param file SEDC_SR_JCHS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_S6_JCHS Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_JCHS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . Stefan Grimme, Andreas Hansen, Jan Gerit Brandenburg, and Christoph Bannwarth. Dispersion-corrected mean-field electronic structure methods. Chemical Reviews , 116(9):5105\u20135154, 2016. PMID: 27077966. doi:10.1021/acs.chemrev.5b00533 . \u21a9 Kyuho Lee, \u00c9amonn D. Murray, Lingzhu Kong, Bengt I. Lundqvist, and David C. Langreth. Higher-accuracy van der Waals density functional. Phys. Rev. B , 82:081101, Aug 2010. doi:10.1103/PhysRevB.82.081101 . \u21a9 Kristian Berland and Per Hyldgaard. Exchange functional that tests the robustness of the plasmon description of the van der Waals density functional. Phys. Rev. B , 89:035412, Jan 2014. doi:10.1103/PhysRevB.89.035412 . \u21a9 Oleg A. Vydrov and Troy Van Voorhis. Nonlocal van der Waals density functional: The simpler the better. The Journal of Chemical Physics , 133(24):244103, 12 2010. doi:10.1063/1.3521275 . \u21a9 Yan Zhao and Donald G. Truhlar. The M06 suite of density functionals for main group thermochemistry, thermochemical kinetics, noncovalent interactions, excited states, and transition elements: two new functionals and systematic testing of four M06-class functionals and 12 other functionals. Theoretical Chemistry Accounts , 120(1):215\u2013241, May 2008. doi:10.1007/s00214-007-0310-x . \u21a9 Jeffrey A. van Santen and Gino A. DiLabio. Dispersion corrections improve the accuracy of both noncovalent and covalent interactions energies predicted by a density-functional theory approximation. The Journal of Physical Chemistry A , 119(25):6703\u20136713, 2015. PMID: 26030132. doi:10.1021/acs.jpca.5b02809 . \u21a9 Grygoriy A. Dolgonos, Johannes Hoja, and A. Daniel Boese. Revised values for the x23 benchmark set of molecular crystals. Phys. Chem. Chem. Phys. , 21:24333\u201324344, 2019. doi:10.1039/C9CP04488D . \u21a9 Ji\u0159\u00ed Klime\u0161, David R. Bowler, and Angelos Michaelides. Van der Waals density functionals applied to solids. Phys. Rev. B , 83:195131, May 2011. doi:10.1103/PhysRevB.83.195131 . \u21a9 Alexandre Tkatchenko and Matthias Scheffler. Accurate molecular van der Waals interactions from ground-state electron density and free-atom reference data. Phys. Rev. Lett. , 102:073005, Feb 2009. doi:10.1103/PhysRevLett.102.073005 . \u21a9 Victor G. Ruiz, Wei Liu, Egbert Zojer, Matthias Scheffler, and Alexandre Tkatchenko. Density-functional theory with screened van der Waals interactions for the modeling of hybrid inorganic-organic systems. Phys. Rev. Lett. , 108:146103, Apr 2012. doi:10.1103/PhysRevLett.108.146103 . \u21a9 Alexandre Tkatchenko, Robert A. DiStasio, Roberto Car, and Matthias Scheffler. Accurate and efficient method for many-body van der Waals interactions. Phys. Rev. Lett. , 108:236402, Jun 2012. doi:10.1103/PhysRevLett.108.236402 . \u21a9 \u21a9 Alberto Ambrosetti, Anthony M. Reilly, Robert A. DiStasio, Jr., and Alexandre Tkatchenko. Long-range correlation energy calculated from coupled atomic response functions. The Journal of Chemical Physics , 140(18):18A508, 02 2014. doi:10.1063/1.4865104 . \u21a9 Stefan Grimme. Semiempirical GGA-type density functional constructed with a long-range dispersion correction. Journal of Computational Chemistry , 27(15):1787\u20131799, 2006. doi:https://doi.org/10.1002/jcc.20495 . \u21a9 Stefan Grimme, Jens Antony, Stephan Ehrlich, and Helge Krieg. A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu. The Journal of Chemical Physics , 132(15):154104, 04 2010. doi:10.1063/1.3382344 . \u21a9 Stefan Grimme, Stephan Ehrlich, and Lars Goerigk. Effect of the damping function in dispersion corrected density functional theory. Journal of Computational Chemistry , 32(7):1456\u20131465, 2011. arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/jcc.21759 , doi:https://doi.org/10.1002/jcc.21759 . \u21a9 Eike Caldeweyher, Christoph Bannwarth, and Stefan Grimme. Extension of the d3 dispersion coefficient model. The Journal of Chemical Physics , July 2017. URL: http://dx.doi.org/10.1063/1.4993215 , doi:10.1063/1.4993215 . \u21a9 Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph Bannwarth, and Stefan Grimme. A generally applicable atomic-charge dependent london dispersion correction. The Journal of Chemical Physics , April 2019. URL: http://dx.doi.org/10.1063/1.5090222 , doi:10.1063/1.5090222 . \u21a9 Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. Extension and evaluation of the d4 london-dispersion model for periodic systems. Physical Chemistry Chemical Physics , 22(16):8499\u20138512, 2020. URL: http://dx.doi.org/10.1039/D0CP00502A , doi:10.1039/d0cp00502a . \u21a9 F. Ortmann, F. Bechstedt, and W. G. Schmidt. Semiempirical van der Waals correction to the density functional description of solids and molecular structures. Phys. Rev. B , 73:205101, May 2006. doi:10.1103/PhysRevB.73.205101 . \u21a9 Petr Jure\u010dka, Ji\u0159\u00ed \u010cern\u00fd, Pavel Hobza, and Dennis R. Salahub. Density functional theory augmented with an empirical dispersion term. Interaction energies and geometries of 80 noncovalent complexes compared with ab initio quantum mechanics calculations. Journal of Computational Chemistry , 28(2):555\u2013569, 2007. doi:10.1002/jcc.20570 . \u21a9 Axel D. Becke and Erin R. Johnson. A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. The Journal of Chemical Physics , 127(12):124108, 09 2007. doi:10.1063/1.2768530 . \u21a9 Daniel G. A. Smith, Lori A. Burns, Konrad Patkowski, and C. David Sherrill. Revised damping parameters for the d3 dispersion correction to density functional theory. The Journal of Physical Chemistry Letters , 7(12):2197\u20132203, 2016. PMID: 27203625. doi:10.1021/acs.jpclett.6b00780 . \u21a9","title":"Other Schemes"},{"location":"documentation/Groundstate/intro/","text":"One of the most fundamental tasks for CASTEP is to take a crystal lattice and set of atomic positions, and compute the electronic density and total energy. Once the lattice and atomic positions have been specified, you can tell CASTEP to compute the energy by setting the task keyword in the param file : task : energy Your cell and param files should be named using the same prefix, which CASTEP calls the \"seedname\", and the extensions .cell and .param , respectively. For example, for a calculation called mytest , you need the input files mytest.cell mytest.param and the calculation is run with the command castep mytest CASTEP computes the energy by solving the Kohn-Sham equations iteratively, using the 'self-consistent field' (SCF) method.","title":"Overview"},{"location":"documentation/Groundstate/nlxc/","text":"","title":"Nlxc"},{"location":"documentation/Groundstate/population_analysis/","text":"Population analysis At the end of a single point calculation, the ground state electron density is obtained. The electrons are distributed such that the total energy functional is minimised, meaning that they do not belong to individual atoms anymore. However, it is often useful as well as insightful to partition the total electron density to atomic or bond contributions. While such population analyses have no direct connection to experimental observables, they provide a chemical interpretation of possible charge transfer within the system. There are many flavours of charge partitioning, of which CASTEP can perform the Mulliken population analysis 1 (see also part II 2 , part III 3 and part IV 4 ) and the Hirshfeld definition 5 . Mulliken population analysis The total number of electrons N N of a quantum mechanical system can be found by evaluating the sum \\begin{equation} N = \\sum _ \\mu (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\end{equation} where \\mathbf{P} \\mathbf{P} and \\mathbf{S} \\mathbf{S} are the density and overlap matrices expressed in a suitable basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} , respectively. The overlap matrix elements are obtained as \\begin{equation} S _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} The density matrix results from evaluating the density operator using the basis set \\begin{equation} P _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\hat{P} | \\chi _ \\nu \\rangle \\end{equation} where the single-particle density operator is expressed in terms of the single-particle wavefunctions \\psi _ i \\psi _ i and the corresponding occupancies f _ i f _ i as \\begin{equation} \\hat{P} = \\sum _ i f _ i \\; |\\psi _ i \\rangle \\langle \\psi _ i | \\textrm{,} \\end{equation} therefore \\begin{equation} P _ {\\mu\\nu} = \\sum _ i f _ i \\; \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\psi _ i | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} If the basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} is local (i.e. functions with compact support), individual terms (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} in the total charge expression may be associated with the spatial region corresponding to the individual basis function \\chi _ \\mu \\chi _ \\mu . If these basis functions are centred on atoms, the contributions belonging to a particular atom A A are defined as the charge of A A : \\begin{equation} N _ A = \\sum _ {\\mu \\in A} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\textrm{.} \\end{equation} Conveniently, the off-diagonal elements of \\mathbf{P} \\mathbf{S} \\mathbf{P} \\mathbf{S} are partitioned into bond contributions between atoms A A and B B as \\begin{equation} N _ {AB} = \\sum _ {\\mu \\in A} \\sum _ {\\nu \\in B} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\nu} \\textrm{.} \\end{equation} To assign a charge to an atom, \\begin{equation} q _ A = Z' _ A - N _ A \\end{equation} is calculated, where Z' Z' is the pseudoatom nuclear charge. The CASTEP implementation In CASTEP, the solution of the electronic problem results in a set of Kohn-Sham orbitals \\psi _ i \\psi _ i , which are expressed in terms of plane-wave functions. Plane-waves are non-local, therefore not directly suitable for Mulliken population analysis. In order to obtain a suitable local basis, CASTEP solves the electronic problem of the isolated atom for each atomic specie present in the system, resulting in a set of atomic orbitals \\chi _ \\mu \\chi _ \\mu . Note that for this set of calculations, the same calculation settings (e.g. electronic cutoff and pseudopotentials) are used. With the atomic orbitals determined, the Mulliken population analysis can be performed by calculating the projections \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\chi _ \\mu | \\psi _ i \\rangle . CASTEP keywords The default behaviour is to compute the population analysis on completion of most tasks that determine the ground state electron density. Mulliken population analysis can be turned off by adding POPN_CALCULATE : FALSE to the .param file. The bond population analysis is computed between all atoms which are closer than a spatial cutoff (3 \u212b by default), which may be controlled using the .param keyword POPN_BOND_CUTOFF , for example POPN_BOND_CUTOFF : 4.0 to set the cutoff to 4 \u212b. To control the verbosity of the population analysis output, POPN_WRITE : ENHANCED which is the default setting, writes individual orbital as well as atomic and bond populations; POPN_WRITE : MINIMAL only writes atomic and bond populations; POPN_WRITE : NONE only writes bond populations. The .cell block SPECIES_LCAO_STATES controls the number of atomic orbitals, as specified by their main and angular quantum numbers, used for each atomic specie. By default, all valence states up to the next noble gas configuration are obtained and used in the population analysis, but these can be overridden, for example: %BLOCK SPECIES_LCAO_STATES H 3 %ENDBLOCK SPECIES_LCAO_STATES will use the 1s, 2s and 2p orbitals. Shallow core states, if explicitly treated as valance states, are included. For example, for atoms such as Na, where most pseudopotential definitions include shallow core states, 2s, 2p, 3s and 3p are all used in the population analysis. The Hirshfeld partitioning scheme The Hirshfeld population analysis partitions the total ground state electronic density \\rho(\\mathbf{r}) \\rho(\\mathbf{r}) into atomic densities using \\begin{equation} \\rho _ A(\\mathbf{r}) = w _ A(\\mathbf{r}) \\rho(\\mathbf{r}) \\end{equation} where w _ A(\\mathbf{r}) w _ A(\\mathbf{r}) is the sharing function belonging to atom A A . The sharing function is calculated from the spherically averaged isolated atom densities \\rho^\\textrm{isolated} \\rho^\\textrm{isolated} as \\begin{equation} w _ A(\\mathbf{r}) = \\frac{\\rho^\\textrm{isolated} _ A (\\mathbf{r})}{\\sum _ A \\rho^\\textrm{isolated} _ A (\\mathbf{r})} \\textrm{,} \\end{equation} where each \\rho^\\textrm{isolated} _ A \\rho^\\textrm{isolated} _ A is centred at the position \\mathbf{R} _ A \\mathbf{R} _ A of the nucleus of A A . The electronic charge attributed to atom A A is the integral \\begin{equation} N _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) \\textrm{,} \\end{equation} from which the total charge is obtained as \\begin{equation} q _ A = Z' _ A - N _ A \\textrm{.} \\end{equation} Other quantities, such as the volume of the bonded atom is calculated from the integral \\begin{equation} V _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) |\\mathbf{r} - \\mathbf{R} _ A|^3 \\textrm{,} \\end{equation} which are useful in other methods, such as the many-body and XDM ispersion schemes . The CASTEP implementation Similarly to the Mulliken population analysis, the ground state electron density of isolated atoms of every specie are determined in the post-processing step, using the same pseudopotential and calculation parameters as the main calculation. CASTEP keywords To switch on the Hirshfeld partitioning scheme, add CALCULATE_HIRSHFELD : TRUE to the .param file. This provides a basic analysis of the Hirshfeld charges. More information, such as atomic volumes, can be gained when using IPRINT : 2 or higher. R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. I. The Journal of Chemical Physics , 23(10):1833\u20131840, 10 1955. doi:10.1063/1.1740588 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. II. Overlap Populations, Bond Orders, and Covalent Bond Energies. The Journal of Chemical Physics , 23(10):1841\u20131846, 10 1955. doi:10.1063/1.1740589 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. III. Effects of Hybridization on Overlap and Gross AO Populations. The Journal of Chemical Physics , 23(12):2338\u20132342, 12 1955. doi:10.1063/1.1741876 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. IV. Bonding and Antibonding in LCAO and Valence\u2010Bond Theories. The Journal of Chemical Physics , 23(12):2343\u20132346, 12 1955. doi:10.1063/1.1741877 . \u21a9 F. L. Hirshfeld. Bonded-atom fragments for describing molecular charge densities. Theoretica chimica acta , 44(2):129\u2013138, Jun 1977. doi:10.1007/BF00549096 . \u21a9","title":"Population analysis"},{"location":"documentation/Groundstate/population_analysis/#population-analysis","text":"At the end of a single point calculation, the ground state electron density is obtained. The electrons are distributed such that the total energy functional is minimised, meaning that they do not belong to individual atoms anymore. However, it is often useful as well as insightful to partition the total electron density to atomic or bond contributions. While such population analyses have no direct connection to experimental observables, they provide a chemical interpretation of possible charge transfer within the system. There are many flavours of charge partitioning, of which CASTEP can perform the Mulliken population analysis 1 (see also part II 2 , part III 3 and part IV 4 ) and the Hirshfeld definition 5 .","title":"Population analysis"},{"location":"documentation/Groundstate/population_analysis/#mulliken-population-analysis","text":"The total number of electrons N N of a quantum mechanical system can be found by evaluating the sum \\begin{equation} N = \\sum _ \\mu (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\end{equation} where \\mathbf{P} \\mathbf{P} and \\mathbf{S} \\mathbf{S} are the density and overlap matrices expressed in a suitable basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} , respectively. The overlap matrix elements are obtained as \\begin{equation} S _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} The density matrix results from evaluating the density operator using the basis set \\begin{equation} P _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\hat{P} | \\chi _ \\nu \\rangle \\end{equation} where the single-particle density operator is expressed in terms of the single-particle wavefunctions \\psi _ i \\psi _ i and the corresponding occupancies f _ i f _ i as \\begin{equation} \\hat{P} = \\sum _ i f _ i \\; |\\psi _ i \\rangle \\langle \\psi _ i | \\textrm{,} \\end{equation} therefore \\begin{equation} P _ {\\mu\\nu} = \\sum _ i f _ i \\; \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\psi _ i | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} If the basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} is local (i.e. functions with compact support), individual terms (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} in the total charge expression may be associated with the spatial region corresponding to the individual basis function \\chi _ \\mu \\chi _ \\mu . If these basis functions are centred on atoms, the contributions belonging to a particular atom A A are defined as the charge of A A : \\begin{equation} N _ A = \\sum _ {\\mu \\in A} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\textrm{.} \\end{equation} Conveniently, the off-diagonal elements of \\mathbf{P} \\mathbf{S} \\mathbf{P} \\mathbf{S} are partitioned into bond contributions between atoms A A and B B as \\begin{equation} N _ {AB} = \\sum _ {\\mu \\in A} \\sum _ {\\nu \\in B} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\nu} \\textrm{.} \\end{equation} To assign a charge to an atom, \\begin{equation} q _ A = Z' _ A - N _ A \\end{equation} is calculated, where Z' Z' is the pseudoatom nuclear charge.","title":"Mulliken population analysis"},{"location":"documentation/Groundstate/population_analysis/#the-castep-implementation","text":"In CASTEP, the solution of the electronic problem results in a set of Kohn-Sham orbitals \\psi _ i \\psi _ i , which are expressed in terms of plane-wave functions. Plane-waves are non-local, therefore not directly suitable for Mulliken population analysis. In order to obtain a suitable local basis, CASTEP solves the electronic problem of the isolated atom for each atomic specie present in the system, resulting in a set of atomic orbitals \\chi _ \\mu \\chi _ \\mu . Note that for this set of calculations, the same calculation settings (e.g. electronic cutoff and pseudopotentials) are used. With the atomic orbitals determined, the Mulliken population analysis can be performed by calculating the projections \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\chi _ \\mu | \\psi _ i \\rangle .","title":"The CASTEP implementation"},{"location":"documentation/Groundstate/population_analysis/#castep-keywords","text":"The default behaviour is to compute the population analysis on completion of most tasks that determine the ground state electron density. Mulliken population analysis can be turned off by adding POPN_CALCULATE : FALSE to the .param file. The bond population analysis is computed between all atoms which are closer than a spatial cutoff (3 \u212b by default), which may be controlled using the .param keyword POPN_BOND_CUTOFF , for example POPN_BOND_CUTOFF : 4.0 to set the cutoff to 4 \u212b. To control the verbosity of the population analysis output, POPN_WRITE : ENHANCED which is the default setting, writes individual orbital as well as atomic and bond populations; POPN_WRITE : MINIMAL only writes atomic and bond populations; POPN_WRITE : NONE only writes bond populations. The .cell block SPECIES_LCAO_STATES controls the number of atomic orbitals, as specified by their main and angular quantum numbers, used for each atomic specie. By default, all valence states up to the next noble gas configuration are obtained and used in the population analysis, but these can be overridden, for example: %BLOCK SPECIES_LCAO_STATES H 3 %ENDBLOCK SPECIES_LCAO_STATES will use the 1s, 2s and 2p orbitals. Shallow core states, if explicitly treated as valance states, are included. For example, for atoms such as Na, where most pseudopotential definitions include shallow core states, 2s, 2p, 3s and 3p are all used in the population analysis.","title":"CASTEP keywords"},{"location":"documentation/Groundstate/population_analysis/#the-hirshfeld-partitioning-scheme","text":"The Hirshfeld population analysis partitions the total ground state electronic density \\rho(\\mathbf{r}) \\rho(\\mathbf{r}) into atomic densities using \\begin{equation} \\rho _ A(\\mathbf{r}) = w _ A(\\mathbf{r}) \\rho(\\mathbf{r}) \\end{equation} where w _ A(\\mathbf{r}) w _ A(\\mathbf{r}) is the sharing function belonging to atom A A . The sharing function is calculated from the spherically averaged isolated atom densities \\rho^\\textrm{isolated} \\rho^\\textrm{isolated} as \\begin{equation} w _ A(\\mathbf{r}) = \\frac{\\rho^\\textrm{isolated} _ A (\\mathbf{r})}{\\sum _ A \\rho^\\textrm{isolated} _ A (\\mathbf{r})} \\textrm{,} \\end{equation} where each \\rho^\\textrm{isolated} _ A \\rho^\\textrm{isolated} _ A is centred at the position \\mathbf{R} _ A \\mathbf{R} _ A of the nucleus of A A . The electronic charge attributed to atom A A is the integral \\begin{equation} N _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) \\textrm{,} \\end{equation} from which the total charge is obtained as \\begin{equation} q _ A = Z' _ A - N _ A \\textrm{.} \\end{equation} Other quantities, such as the volume of the bonded atom is calculated from the integral \\begin{equation} V _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) |\\mathbf{r} - \\mathbf{R} _ A|^3 \\textrm{,} \\end{equation} which are useful in other methods, such as the many-body and XDM ispersion schemes .","title":"The Hirshfeld partitioning scheme"},{"location":"documentation/Groundstate/population_analysis/#the-castep-implementation_1","text":"Similarly to the Mulliken population analysis, the ground state electron density of isolated atoms of every specie are determined in the post-processing step, using the same pseudopotential and calculation parameters as the main calculation.","title":"The CASTEP implementation"},{"location":"documentation/Groundstate/population_analysis/#castep-keywords_1","text":"To switch on the Hirshfeld partitioning scheme, add CALCULATE_HIRSHFELD : TRUE to the .param file. This provides a basic analysis of the Hirshfeld charges. More information, such as atomic volumes, can be gained when using IPRINT : 2 or higher. R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. I. The Journal of Chemical Physics , 23(10):1833\u20131840, 10 1955. doi:10.1063/1.1740588 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. II. Overlap Populations, Bond Orders, and Covalent Bond Energies. The Journal of Chemical Physics , 23(10):1841\u20131846, 10 1955. doi:10.1063/1.1740589 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. III. Effects of Hybridization on Overlap and Gross AO Populations. The Journal of Chemical Physics , 23(12):2338\u20132342, 12 1955. doi:10.1063/1.1741876 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. IV. Bonding and Antibonding in LCAO and Valence\u2010Bond Theories. The Journal of Chemical Physics , 23(12):2343\u20132346, 12 1955. doi:10.1063/1.1741877 . \u21a9 F. L. Hirshfeld. Bonded-atom fragments for describing molecular charge densities. Theoretica chimica acta , 44(2):129\u2013138, Jun 1977. doi:10.1007/BF00549096 . \u21a9","title":"CASTEP keywords"},{"location":"documentation/Groundstate/soc/","text":"keywords For a calculation of a non-spin polarised system with spin orbit coupling (e.g. GaAs) the following keywords should be set in the param file spin_treatment : vector spin_orbit_coupling : true spin_polarised : false relativistic_treatment : dirac If the system has a spin density (e.g. a ferromagnet or antiferromagnet) then the following keywords should be set in the para file spin_treatment : vector spin_orbit_coupling : true spin_polarised : true relativistic_treatment : dirac As the spin-orbit coupling is transmitted via the pseudopotential is is necessary to use j-dependent pseudopotentials. These can be read from file (UPF or uspso) or generated on the fly. At the moment the SOC19 set of OTFG norm-conserving potentials are suitable. These can be specified with the following block in the cell file ``` %block species_pot SOC19 %endblock species_pot Limitations","title":"Spin Orbit Coupling"},{"location":"documentation/Groundstate/soc/#keywords","text":"For a calculation of a non-spin polarised system with spin orbit coupling (e.g. GaAs) the following keywords should be set in the param file spin_treatment : vector spin_orbit_coupling : true spin_polarised : false relativistic_treatment : dirac If the system has a spin density (e.g. a ferromagnet or antiferromagnet) then the following keywords should be set in the para file spin_treatment : vector spin_orbit_coupling : true spin_polarised : true relativistic_treatment : dirac As the spin-orbit coupling is transmitted via the pseudopotential is is necessary to use j-dependent pseudopotentials. These can be read from file (UPF or uspso) or generated on the fly. At the moment the SOC19 set of OTFG norm-conserving potentials are suitable. These can be specified with the following block in the cell file ``` %block species_pot SOC19 %endblock species_pot","title":"keywords"},{"location":"documentation/Groundstate/soc/#limitations","text":"","title":"Limitations"},{"location":"documentation/Groundstate/spin_constraints/","text":"Introduction Spin constraints allow you to \u2018fix\u2019 the spins within DFT by adding an energy penalty to states which do not obey the constraint. These change the minimum energy state from being the normal ground state to only those which have the target spin. Theory Energy Penalty Function The easiest constraint is to fix the vector direction of the spin on a target atom. The energy penalty has the form: E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 (eq1), where is the penalty constant, \\mathbf{M}_I \\mathbf{M}_I is the magnetic moment of atom I I , defined by \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r where m(r) m(r) is the magnetization of the electrons at r r , and F_I(r) F_I(r) is a function approximating the electronic density of the atom I I . This integral sums up the total magnetic moments in a region around the atom. Eq (1) goes to zero as \\mathbf{M}_I \\mathbf{M}_I goes to \\mathbf{e}_I \\mathbf{e}_I and it is positive otherwise, so this leaves the target state unchanged and increases the energy of other states. The potential that arises from this can be found by taking the derivative of (1) with respect to the density: V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] This is a local potential that pushes the density towards the constrained state. The strength of this \u201cpush\u201d is changed by the penalty constant . Due to the factor (the spin operator), the potential only has components in the spin space and tries to rotate the direction of spin, but not change the magnitude. Energy Penalty Constant The energy penalty constant ( \\lambda \\lambda ) must be large enough to overcome any natural features of the energy landscape. That is, it must be big enough to make the target minimum be the actual minimum of the system. On the other hand, making this value too big causes the numerics to become difficult to solve. CASTEP is built to solve things that act like physical systems and various parameters have been tuned to make it fast at this. Values that are too big, push the system away from being like a physical system and make it take a very long time to converge. There are a few tricks that we can play to speed this up. The first is to start with a low value of the \\lambda \\lambda and then increase it gradually. We do this by starting with a very low value, waiting until the system is converged, and then checking if the constraints are actually fulfilled (ie \\mathbf{M}_I = \\mathbf{e}_I \\mathbf{M}_I = \\mathbf{e}_I . If not, we double \\lambda \\lambda and converge again. We repeat this until the constraint is obeyed. Using Magnetic Constraints To apply a constraint to an atom, you must specify the spin in the cell file and add the extra tag FIX_SPIN for each atom on which you want to apply a constraint to block positions_frac or positions_abs in cell: %block positions_frac Fe 0.0 0.0 0.0 spin 2 0 0 FIX_SPIN Ni 0.5 0.5 0.5 spin 1 1 0 Mn 0.3 0.4 0.0 %endblock positions_frac This will set the system up with two Fe atoms as follows: Element Initial Spin Spin Constraint Fe 2 0 0 Along 1 0 0 Ni 1 1 0 None Mn None None It will then do the procedure mentioned in the previous section, doubling \\lambda \\lambda to achieve the target constraints. You can only add FIX_SPIN to any atom that you have specified the spin for. Convergence Some of the magnetic states can be difficult to converge, as the penalty potential still does not end up looking like a physical system. This causes the calculation to take a huge number of steps to reach convergence (if it even gets there!) You almost certainly need to decrease the value of spin_mix_amp which has a default of 0.8 but should be much lower (eg 0.5 or even less) for many of these systems. Alternatively, you can use metals_method: EDFT which uses EDFT instead of density mixing and this can improve the convergence.","title":"Spin Constraints"},{"location":"documentation/Groundstate/spin_constraints/#introduction","text":"Spin constraints allow you to \u2018fix\u2019 the spins within DFT by adding an energy penalty to states which do not obey the constraint. These change the minimum energy state from being the normal ground state to only those which have the target spin.","title":"Introduction"},{"location":"documentation/Groundstate/spin_constraints/#theory","text":"","title":"Theory"},{"location":"documentation/Groundstate/spin_constraints/#energy-penalty-function","text":"The easiest constraint is to fix the vector direction of the spin on a target atom. The energy penalty has the form: E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 (eq1), where is the penalty constant, \\mathbf{M}_I \\mathbf{M}_I is the magnetic moment of atom I I , defined by \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r where m(r) m(r) is the magnetization of the electrons at r r , and F_I(r) F_I(r) is a function approximating the electronic density of the atom I I . This integral sums up the total magnetic moments in a region around the atom. Eq (1) goes to zero as \\mathbf{M}_I \\mathbf{M}_I goes to \\mathbf{e}_I \\mathbf{e}_I and it is positive otherwise, so this leaves the target state unchanged and increases the energy of other states. The potential that arises from this can be found by taking the derivative of (1) with respect to the density: V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] This is a local potential that pushes the density towards the constrained state. The strength of this \u201cpush\u201d is changed by the penalty constant . Due to the factor (the spin operator), the potential only has components in the spin space and tries to rotate the direction of spin, but not change the magnitude.","title":"Energy Penalty Function"},{"location":"documentation/Groundstate/spin_constraints/#energy-penalty-constant","text":"The energy penalty constant ( \\lambda \\lambda ) must be large enough to overcome any natural features of the energy landscape. That is, it must be big enough to make the target minimum be the actual minimum of the system. On the other hand, making this value too big causes the numerics to become difficult to solve. CASTEP is built to solve things that act like physical systems and various parameters have been tuned to make it fast at this. Values that are too big, push the system away from being like a physical system and make it take a very long time to converge. There are a few tricks that we can play to speed this up. The first is to start with a low value of the \\lambda \\lambda and then increase it gradually. We do this by starting with a very low value, waiting until the system is converged, and then checking if the constraints are actually fulfilled (ie \\mathbf{M}_I = \\mathbf{e}_I \\mathbf{M}_I = \\mathbf{e}_I . If not, we double \\lambda \\lambda and converge again. We repeat this until the constraint is obeyed.","title":"Energy Penalty Constant"},{"location":"documentation/Groundstate/spin_constraints/#using-magnetic-constraints","text":"To apply a constraint to an atom, you must specify the spin in the cell file and add the extra tag FIX_SPIN for each atom on which you want to apply a constraint to block positions_frac or positions_abs in cell: %block positions_frac Fe 0.0 0.0 0.0 spin 2 0 0 FIX_SPIN Ni 0.5 0.5 0.5 spin 1 1 0 Mn 0.3 0.4 0.0 %endblock positions_frac This will set the system up with two Fe atoms as follows: Element Initial Spin Spin Constraint Fe 2 0 0 Along 1 0 0 Ni 1 1 0 None Mn None None It will then do the procedure mentioned in the previous section, doubling \\lambda \\lambda to achieve the target constraints. You can only add FIX_SPIN to any atom that you have specified the spin for.","title":"Using Magnetic Constraints"},{"location":"documentation/Groundstate/spin_constraints/#convergence","text":"Some of the magnetic states can be difficult to converge, as the penalty potential still does not end up looking like a physical system. This causes the calculation to take a huge number of steps to reach convergence (if it even gets there!) You almost certainly need to decrease the value of spin_mix_amp which has a default of 0.8 but should be much lower (eg 0.5 or even less) for many of these systems. Alternatively, you can use metals_method: EDFT which uses EDFT instead of density mixing and this can improve the convergence.","title":"Convergence"},{"location":"documentation/Groundstate/xc/","text":"","title":"Xc"},{"location":"documentation/Input_Files/cell_file/","text":"This is a detailed description of options for CASTEP's cell file. See the basic cell file page for an overview. This page has the most frequently-used cell file options, but for a full set use CASTEP's built-in help . There is also a concise table of cell keywords . The cell file is one of CASTEP's two main input files. It contains all of the information about the crystal lattice and the atomic positions, as well as additional information such as Brillouin zone sampling ('k-points'), pseudopotentials, cell symmetry, external pressure, constraints on motion of the atoms or cell, and atomic properties such as the mass of each species. The file itself is a free-format keyword-driven text file, consisting of keywords and blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. Most of the keywords and blocks are optional, but CASTEP requires two block entries: a block to specify the lattice, and another to specify the atomic elements and positions within the cell. At the very least, the cell lattice vectors and ionic positions must be specified. Reasonable defaults are chosen for anything else not specified. For the purposes of the following definitions, all variables represented by R R are defined to be real numbers, those represented by I I are defined to be integers and those represented by C C are characters. Cell Lattice Vectors The cell lattice vectors may be specified in Cartesian coordinates or in terms of the lattice vector magnitudes and the angles between them ( a, b, c, \\alpha, \\beta, \\gamma a, b, c, \\alpha, \\beta, \\gamma ). Only one of LATTICE_CART and LATTICE_ABC may occur in a cell definition file. The definitions of these keywords are as follows: %BLOCK LATTICE_CART [units] a_x a_y a_z b_x b_y b_z c_x c_y c_z %ENDBLOCK LATTICE_CART Here a_x is the x-component of the first lattice vector, \\mathbf{a} \\mathbf{a} , b_y b_y is the y-component of the second lattice vector, \\mathbf{b} \\mathbf{b} , etc. [units] specifies the units in which the lattice vectors are defined. If not present, the default is \u00c5. %BLOCK LATTICE_ABC [units] a b c alpha beta gamma %ENDBLOCK LATTICE_ABC Here a is the value of the lattice constant \\vert\\mathbf{a}\\vert \\vert\\mathbf{a}\\vert , gamma is the value of the cell angle \\gamma \\gamma (in degrees) etc. If the lattice is specified in this manner, the absolute orientation is arbitrary. In this case the orientation is defined by applying the following constraints: \\mathbf{a} \\mathbf{a} lies along the x-axis \\mathbf{b} \\mathbf{b} lies in the xy plane \\mathbf{c} \\mathbf{c} forms a right-handed set with \\mathbf{a} \\mathbf{a} and \\mathbf{b} \\mathbf{b} [units] specifies the units in which the lattice vector magnitudes are defined. If not present, the default is \u00c5. Angles should be specified in degrees. Ionic Positions The ionic positions may be specified in fractional coordinates relative to the lattice vectors of the unit cell, or in absolute coordinates. Only one of POSITIONS_FRAC and POSITIONS_ABS may occur in a cell definition file. %BLOCK POSITIONS_FRAC CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK END POSITIONS_FRAC The first entry on a line is the symbol of the species (chemical element). Alternatively, the atomic number may be given instead, in which case CASTEP will be look up for chemical symbol. A symbol can have a maximum of three characters. The first alphabetical characters identify the element, from which default values for atomic mass etc. The next three entries on a line in POSITIONS_FRAC are real numbers representing the position of the ion in fractions of the unit cell lattice vectors. If the optional flag SPIN is present on a line, this sets the spin polarisation ( N^\\uparrow-N^\\downarrow N^\\uparrow-N^\\downarrow ) of the atom for initialisation of the spin density; for non-collinear spin calculations, the vector spin is specified as three numbers. If this flag is not present a non-spin polarised state will be assumed. %BLOCK POSITIONS_ABS [units] CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK POSITIONS_ABS The first entry on a line is the symbol or atomic number of the ionic species, as for POSITIONS_FRAC . The next three entries are real numbers representing the position of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5. The optional flag SPIN is defined above under POSITIONS_FRAC . Brillouin Zone Sampling (k-points) (N.B. in the following section the keywords with the prefixes KPOINT_ and KPOINTS_ are synonymous. KPOINT_ is the preferred usage.) The k-points at which the Brillouin zone is to be sampled during a self consistent calculation to find the electronic ground state may be defined either by specifying a list of k-points or a Monkhorst-Pack grid in terms of the dimensions of the k-point mesh or a minimum k-point density. The origin of the Monkhorst-Pack grid may be offset by a vector from the origin of the Brillouin zone. If no k-points are specified, the default will be a Monkhorst-Pack grid with a maximum spacing of 0.1\u00c5 ^{-1} ^{-1} and no offset of the origin. The KPOINT_LIST , KPOINT_MP_GRID and KPOINT_MP_SPACING keywords are mutually exclusive. KPOINT_MP_OFFSET may be specified in combination with either KPOINT_MP_GRID or KPOINT_MP_SPACING . %BLOCK KPOINT_LIST \\begin{array}{cccc} R_{1i} R_{1j} R_{1k} R_{1w} R_{2i} R_{2j} R_{2k} R_{2w} ... %ENDBLOCK KPOINT_LIST The first three entries on a line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The final entry on a line is the weight of the k-point relative to the others specified. The sum of the weights must be equal to 1. KPOINT_MP_GRID I_i I_j I_k This specifies the dimensions of the Monkhorst-Pack grid requested in the directions of the reciprocal space lattice vectors. The generated grid will be I_i\\times I_j\\times I_k I_i\\times I_j\\times I_k ; any symmetries generated (or supplied) will be used to reduce this number, when computing the irreducible wedge. KPOINT_MP_SPACING R [units] The single entry is the maximum distance between k-points on the Monkhorst-Pack grid. The dimensions of the grid will be chosen such that the maximum separation of k-points is less than this. [units] specifies the units in which the k-point spacing is defined, although note that the actual units used are 2\\pi 2\\pi units . If not present, the default is ang-1 , such that the spacing is in 2\\pi \u00c5^{-1} 2\\pi \u00c5^{-1} . KPOINT_MP_OFFSET R_i R_j R_k This specifies the offset of the Monkhorst-Pack grid with respect to the origin of the Brillouin zone. The three entries are the offset in fractional coordinates relative to the reciprocal lattice vectors. The k-point set for performing spectral calculations can be specified in the same manner, using version of the keywords above with SPECTRAL_ prepended. The same restrictions regarding mutually exclusive keywords apply. For a non-self-consistent spectral calculation, the k-points may be defined along a path through reciprocal space or a list of k-points. %BLOCK SPECTRAL_KPOINT_PATH R_{1i} R_{1j} R_{1k} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK SPECTRAL_KPOINT_PATH The three numbers on each line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The k-points define a continuous sequence of straight line segments, unless the keyword BREAK appears on a separate line within the sequence of k-points. In this case the continuous path will end at the k-point immediately preceding the BREAK keyword and resume at the k-point immediately following. The path will be open unless the first and last point in the list are identical . The maximum spacing of the points sampled along each line segment is defined by the keyword SPECTRAL_KPOINT_PATH_SPACING (default value 0.1 \\times 2\\pi 0.1 \\times 2\\pi \u00c5 ^{-1} ^{-1} ). If necessary, the actual spacing used may be smaller than this in order to ensure that the length of the line segment is an integer multiple of the spacing between points on that segment. Alternatively, the k-point set for performing a band structure calculation can be specified in the same manner as the main k-point set, using version of the keywords above with BS_ prepended. The same restrictions regarding mutually exclusive keywords apply. In this case, the k-point weight in SPECTRAL_KPOINT_LIST is optional. If omitted, the weights for each k-point are assumed to be equal. For a phonon spectrum calculation, the k-points may be defined along a path through reciprocal space or a list of k-points, in the same manner as for a spectral calculation. The corresponding keywords are identical to those for the band structure specification with the initial SPECTRAL_ replaced by PHONON_ , e.g. PHONON_KPOINT_PATH , PHONON_KPOINT_PATH_SPACING and PHONON_KPOINT_LIST . The same restrictions regarding mutually exclusive keywords apply. The block keyword PHONON_GAMMA_DIRECTIONS specifies the directions in which the gamma point will be approached when calculating the non-analytic terms of the LO/TO splitting. Each line in this block will consist of a 3-vector specifying a direction in the basis of reciprocal lattice vectors. If this keyword is not present, the default will be a single vector determined as follows: If the gamma point is q_i = 0 q_i = 0 and there is a successor kpoint q_{i+1} q_{i+1} in the list, then it is q_{i+1} q_{i+1} . Otherwise if the gamma point is q_i =0 q_i =0 and there is a predecessor kpoint q_{i-1} q_{i-1} in the list then it is q_{i-1} q_{i-1} . Otherwise (i.e. a Gamma point only calculation) the a-axis of the reciprocal cell. For backwards compatibility the keywords beginning BS_ and OPTICS_ are synonyms for SPECTRAL_KPOINT_ and similarly those beginning. Cell Symmetry If no symmetry is specified in the cell definition file, the default is for no symmetry to be applied. SYMMETRY_GENERATE If this keyword is present in the cell, the highest symmetry group that applies to the structure of the cell will be found and the corresponding symmetry operations generated. SYMMETRY_TOL R [units] This parameter is the tolerance within which symmetry will be considered to be satisfied. If an ion is found within this distance of its symmetric position, the symmetry will be considered to be satisfied. [units] specifies the units in which the tolerance is defined. If not present, the default is \u00c5. Alternatively, the symmetry operations may be provided directly in a SYMMETRY_OPS block. The symmetry of the cell is represented as a series of symmetry operations under which the unit cell is invariant. Each operation is represented as a 3\\times 3 3\\times 3 array. %BLOCK SYMMETRY_OPS R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 ... %ENDBLOCK SYMMETRY_OPS Each of the first three lines contains 3 entries representing a row of a 3\\times3 3\\times3 array. These represent one symmetry rotation. The three entries on the following line contain the translation associated with this rotation. Constraints The movement of ions or the unit cell during a relaxation or molecular dynamics run may be constrained. The constraints on the ionic motion may by specified as a set of linear constraints. Each constraint is specified as a series of coefficients a_{ijk} a_{ijk} such that: $$ \\sum_{k=1}^{\\tt N_\\mathrm{species}} \\quad \\sum_{j=1}^{\\mathrm{N_\\mathrm{ions}}(k)} \\quad \\sum_{i=1}^{3} a_{ijk} \\verb#ionic_positions(i,j,k)# = constant $$ where \\mathrm{N_\\mathrm{ions}}(k) \\mathrm{N_\\mathrm{ions}}(k) is the number of ions in species k k . The change in the shape of the unit cell may also be constrained using the keyword CELL_CONSTRAINTS . The special case of constraining the centre of mass of the ions to remain fixed is supported by a logical keyword FIX_COM . Also all ionic positions or cell parameters may be fixed by specifying the keywords FIX_ALL_IONS or FIX_ALL_CELL to be TRUE respectively. If no ionic or cell constraints are specified in the cell definition file, the default is to fix the centre of mass. %BLOCK IONIC_CONSTRAINTS I_1 CCC_{1s} I_{1s} I_{n1} R_{1i} R_{1j} R_{1k} I_2 CCC_{2s} I_{2s} I_{n2} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK IONIC_CONSTRAINTS The first element on each line is an integer specifying the number of the constraint being specified. The second entry is either the symbol or atomic number of the species of the ion to which this constraint applies. The third element is the number of the ion within the species. The ordering of the ions in a species is the order in which they appear in the POSITIONS_FRAC or POSITIONS_ABS block in the cell definition file. The final three numbers are real numbers representing the coefficients of the Cartesian coordinates of the ionic position in the constraint sum. All coefficients in the sum not explicitly specified will be zero. On reading this data, the matrix of ionic constraints will be orthogonalised. %BLOCK CELL_CONSTRAINTS I_a I_b I_c I_alpha I_beta I_gamma %ENDBLOCK CELL_CONSTRAINTS The first three entries relate to the magnitude of the three lattice vectors a,b,c a,b,c and the second set of three entries to the angles \\alpha, \\beta, \\gamma \\alpha, \\beta, \\gamma . If the value of the entry corresponding to a magnitude or angle is zero, this quantity will remain fixed. If two or three entries contain the same integer, the corresponding quantities will be constrained to have the same value. If a positive integer greater than 0 occurs in entries 1 through 3 the same integer cannot occur in entries 4 through 6 as this would imply that a vector length and angle must have the same value. Species Characteristics The mass of a species, the pseudopotential which represents the ion and the size of the LCAO basis set used for population anslsyis may be specified in the cell definition file. %BLOCK SPECIES_MASS [units] CCC_1 I_1 R_1 CCC_2 I_2 R_2 ... %ENDBLOCK SPECIES_MASS [units] specifies the units in which the masses are defined. If not present, the default is atomic mass units. The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the mass of that species. Not all species need appear in the SPECIES_MASS block, any not present will assume the default mass for that species. If the initial alphabetical symbol specified for a species is not a standard element symbol in the periodic table, the mass of the species must be specified. %BLOCK SPECIES_POT CCC_1 I_1 CCC_2 I_2 ... %ENDBLOCK SPECIES_POT The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the filename of the file containing the definition of the pseudopotential representing the ionic species. The file to which this refers may be a definition of the parameters of the pseudopotential which is to be generated at runtime, or an old-style pseudopotential definition containing the data for the pseudopotential. Not all species need appear in the SPECIES_POT block. If a pseudopotential is not specified, the default pseudopotential parameters will be used to generate a pseudopotential for the element specified. If the initial alphabetical characters of a species label is not a standard element symbol in the periodic table, the potential for the species must be specified. The charge on the ion for each species will be derived from the pseudopotential corresponding to that ion. %BLOCK SPECIES_LCAO_STATES CCC_1 I_1 I_{B1} CCC_2 I_2 I_{B2} ... %ENDBLOCK SPECIES_LCAO_STATES The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second number is the number of angular momentum channels to use in the LCAO basis set for the species when performing population analysis. For example, to use the 2s and 2p states for C (The 1s state is a core state) this should be 2. By default, the number of states will be the appropriate number to complete the valence shell to the next noble gas. If shallow core states are excluded from a pseudopotential, the value of SPECIES_LCAO_STATES for that species should be included in the cell file to ensure a meaningful basis set is used. External Pressure An external pressure may be applied to the unit cell by specifying a pressure tensor. %BLOCK EXTERNAL_PRESSURE [units] R_{xx} R_{xy} R_{xz} R_{yy} R_{yz} R_{zz} %ENDBLOCK EXTERNAL_PRESSURE [units] specifies the units in which the pressure is defined. If not present, the default is GPa. Entry R_{xx} R_{xx} is the xx xx -component of the pressure, R_{xy} R_{xy} the xy xy -component etc. The default is to apply no external pressure. Ionic Velocities The initial ionic velocities may be specified in Cartesian coordinates in a cell definition file. %BLOCK IONIC_VELOCITIES [units] CCC_1 V_{1x} V_{1y} V_{1z} CCC_2 V_{2x} V_{2y} V_{2z} ... %ENDBLOCK IONIC_VELOCITIES The first entry on a line is the chemical symbol (or atomic number) of the ionic species. The correct symbol will be looked up for the atomic species if the atomic number is specified. A symbol can have a maximum of three characters. The next three entries are real numbers representing the velocity of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5/ps. If this keyword is not present and a molecular dynamics calculation is performed, the ionic velocities will be randomly initialised with the appropriate temperature.","title":"cell File"},{"location":"documentation/Input_Files/cell_file/#cell-lattice-vectors","text":"The cell lattice vectors may be specified in Cartesian coordinates or in terms of the lattice vector magnitudes and the angles between them ( a, b, c, \\alpha, \\beta, \\gamma a, b, c, \\alpha, \\beta, \\gamma ). Only one of LATTICE_CART and LATTICE_ABC may occur in a cell definition file. The definitions of these keywords are as follows: %BLOCK LATTICE_CART [units] a_x a_y a_z b_x b_y b_z c_x c_y c_z %ENDBLOCK LATTICE_CART Here a_x is the x-component of the first lattice vector, \\mathbf{a} \\mathbf{a} , b_y b_y is the y-component of the second lattice vector, \\mathbf{b} \\mathbf{b} , etc. [units] specifies the units in which the lattice vectors are defined. If not present, the default is \u00c5. %BLOCK LATTICE_ABC [units] a b c alpha beta gamma %ENDBLOCK LATTICE_ABC Here a is the value of the lattice constant \\vert\\mathbf{a}\\vert \\vert\\mathbf{a}\\vert , gamma is the value of the cell angle \\gamma \\gamma (in degrees) etc. If the lattice is specified in this manner, the absolute orientation is arbitrary. In this case the orientation is defined by applying the following constraints: \\mathbf{a} \\mathbf{a} lies along the x-axis \\mathbf{b} \\mathbf{b} lies in the xy plane \\mathbf{c} \\mathbf{c} forms a right-handed set with \\mathbf{a} \\mathbf{a} and \\mathbf{b} \\mathbf{b} [units] specifies the units in which the lattice vector magnitudes are defined. If not present, the default is \u00c5. Angles should be specified in degrees.","title":"Cell Lattice Vectors"},{"location":"documentation/Input_Files/cell_file/#ionic-positions","text":"The ionic positions may be specified in fractional coordinates relative to the lattice vectors of the unit cell, or in absolute coordinates. Only one of POSITIONS_FRAC and POSITIONS_ABS may occur in a cell definition file. %BLOCK POSITIONS_FRAC CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK END POSITIONS_FRAC The first entry on a line is the symbol of the species (chemical element). Alternatively, the atomic number may be given instead, in which case CASTEP will be look up for chemical symbol. A symbol can have a maximum of three characters. The first alphabetical characters identify the element, from which default values for atomic mass etc. The next three entries on a line in POSITIONS_FRAC are real numbers representing the position of the ion in fractions of the unit cell lattice vectors. If the optional flag SPIN is present on a line, this sets the spin polarisation ( N^\\uparrow-N^\\downarrow N^\\uparrow-N^\\downarrow ) of the atom for initialisation of the spin density; for non-collinear spin calculations, the vector spin is specified as three numbers. If this flag is not present a non-spin polarised state will be assumed. %BLOCK POSITIONS_ABS [units] CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK POSITIONS_ABS The first entry on a line is the symbol or atomic number of the ionic species, as for POSITIONS_FRAC . The next three entries are real numbers representing the position of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5. The optional flag SPIN is defined above under POSITIONS_FRAC .","title":"Ionic Positions"},{"location":"documentation/Input_Files/cell_file/#brillouin-zone-sampling-k-points","text":"(N.B. in the following section the keywords with the prefixes KPOINT_ and KPOINTS_ are synonymous. KPOINT_ is the preferred usage.) The k-points at which the Brillouin zone is to be sampled during a self consistent calculation to find the electronic ground state may be defined either by specifying a list of k-points or a Monkhorst-Pack grid in terms of the dimensions of the k-point mesh or a minimum k-point density. The origin of the Monkhorst-Pack grid may be offset by a vector from the origin of the Brillouin zone. If no k-points are specified, the default will be a Monkhorst-Pack grid with a maximum spacing of 0.1\u00c5 ^{-1} ^{-1} and no offset of the origin. The KPOINT_LIST , KPOINT_MP_GRID and KPOINT_MP_SPACING keywords are mutually exclusive. KPOINT_MP_OFFSET may be specified in combination with either KPOINT_MP_GRID or KPOINT_MP_SPACING . %BLOCK KPOINT_LIST \\begin{array}{cccc} R_{1i} R_{1j} R_{1k} R_{1w} R_{2i} R_{2j} R_{2k} R_{2w} ... %ENDBLOCK KPOINT_LIST The first three entries on a line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The final entry on a line is the weight of the k-point relative to the others specified. The sum of the weights must be equal to 1. KPOINT_MP_GRID I_i I_j I_k This specifies the dimensions of the Monkhorst-Pack grid requested in the directions of the reciprocal space lattice vectors. The generated grid will be I_i\\times I_j\\times I_k I_i\\times I_j\\times I_k ; any symmetries generated (or supplied) will be used to reduce this number, when computing the irreducible wedge. KPOINT_MP_SPACING R [units] The single entry is the maximum distance between k-points on the Monkhorst-Pack grid. The dimensions of the grid will be chosen such that the maximum separation of k-points is less than this. [units] specifies the units in which the k-point spacing is defined, although note that the actual units used are 2\\pi 2\\pi units . If not present, the default is ang-1 , such that the spacing is in 2\\pi \u00c5^{-1} 2\\pi \u00c5^{-1} . KPOINT_MP_OFFSET R_i R_j R_k This specifies the offset of the Monkhorst-Pack grid with respect to the origin of the Brillouin zone. The three entries are the offset in fractional coordinates relative to the reciprocal lattice vectors. The k-point set for performing spectral calculations can be specified in the same manner, using version of the keywords above with SPECTRAL_ prepended. The same restrictions regarding mutually exclusive keywords apply. For a non-self-consistent spectral calculation, the k-points may be defined along a path through reciprocal space or a list of k-points. %BLOCK SPECTRAL_KPOINT_PATH R_{1i} R_{1j} R_{1k} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK SPECTRAL_KPOINT_PATH The three numbers on each line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The k-points define a continuous sequence of straight line segments, unless the keyword BREAK appears on a separate line within the sequence of k-points. In this case the continuous path will end at the k-point immediately preceding the BREAK keyword and resume at the k-point immediately following. The path will be open unless the first and last point in the list are identical . The maximum spacing of the points sampled along each line segment is defined by the keyword SPECTRAL_KPOINT_PATH_SPACING (default value 0.1 \\times 2\\pi 0.1 \\times 2\\pi \u00c5 ^{-1} ^{-1} ). If necessary, the actual spacing used may be smaller than this in order to ensure that the length of the line segment is an integer multiple of the spacing between points on that segment. Alternatively, the k-point set for performing a band structure calculation can be specified in the same manner as the main k-point set, using version of the keywords above with BS_ prepended. The same restrictions regarding mutually exclusive keywords apply. In this case, the k-point weight in SPECTRAL_KPOINT_LIST is optional. If omitted, the weights for each k-point are assumed to be equal. For a phonon spectrum calculation, the k-points may be defined along a path through reciprocal space or a list of k-points, in the same manner as for a spectral calculation. The corresponding keywords are identical to those for the band structure specification with the initial SPECTRAL_ replaced by PHONON_ , e.g. PHONON_KPOINT_PATH , PHONON_KPOINT_PATH_SPACING and PHONON_KPOINT_LIST . The same restrictions regarding mutually exclusive keywords apply. The block keyword PHONON_GAMMA_DIRECTIONS specifies the directions in which the gamma point will be approached when calculating the non-analytic terms of the LO/TO splitting. Each line in this block will consist of a 3-vector specifying a direction in the basis of reciprocal lattice vectors. If this keyword is not present, the default will be a single vector determined as follows: If the gamma point is q_i = 0 q_i = 0 and there is a successor kpoint q_{i+1} q_{i+1} in the list, then it is q_{i+1} q_{i+1} . Otherwise if the gamma point is q_i =0 q_i =0 and there is a predecessor kpoint q_{i-1} q_{i-1} in the list then it is q_{i-1} q_{i-1} . Otherwise (i.e. a Gamma point only calculation) the a-axis of the reciprocal cell. For backwards compatibility the keywords beginning BS_ and OPTICS_ are synonyms for SPECTRAL_KPOINT_ and similarly those beginning.","title":"Brillouin Zone Sampling (k-points)"},{"location":"documentation/Input_Files/cell_file/#cell-symmetry","text":"If no symmetry is specified in the cell definition file, the default is for no symmetry to be applied. SYMMETRY_GENERATE If this keyword is present in the cell, the highest symmetry group that applies to the structure of the cell will be found and the corresponding symmetry operations generated. SYMMETRY_TOL R [units] This parameter is the tolerance within which symmetry will be considered to be satisfied. If an ion is found within this distance of its symmetric position, the symmetry will be considered to be satisfied. [units] specifies the units in which the tolerance is defined. If not present, the default is \u00c5. Alternatively, the symmetry operations may be provided directly in a SYMMETRY_OPS block. The symmetry of the cell is represented as a series of symmetry operations under which the unit cell is invariant. Each operation is represented as a 3\\times 3 3\\times 3 array. %BLOCK SYMMETRY_OPS R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 ... %ENDBLOCK SYMMETRY_OPS Each of the first three lines contains 3 entries representing a row of a 3\\times3 3\\times3 array. These represent one symmetry rotation. The three entries on the following line contain the translation associated with this rotation.","title":"Cell Symmetry"},{"location":"documentation/Input_Files/cell_file/#constraints","text":"The movement of ions or the unit cell during a relaxation or molecular dynamics run may be constrained. The constraints on the ionic motion may by specified as a set of linear constraints. Each constraint is specified as a series of coefficients a_{ijk} a_{ijk} such that: $$ \\sum_{k=1}^{\\tt N_\\mathrm{species}} \\quad \\sum_{j=1}^{\\mathrm{N_\\mathrm{ions}}(k)} \\quad \\sum_{i=1}^{3} a_{ijk} \\verb#ionic_positions(i,j,k)# = constant $$ where \\mathrm{N_\\mathrm{ions}}(k) \\mathrm{N_\\mathrm{ions}}(k) is the number of ions in species k k . The change in the shape of the unit cell may also be constrained using the keyword CELL_CONSTRAINTS . The special case of constraining the centre of mass of the ions to remain fixed is supported by a logical keyword FIX_COM . Also all ionic positions or cell parameters may be fixed by specifying the keywords FIX_ALL_IONS or FIX_ALL_CELL to be TRUE respectively. If no ionic or cell constraints are specified in the cell definition file, the default is to fix the centre of mass. %BLOCK IONIC_CONSTRAINTS I_1 CCC_{1s} I_{1s} I_{n1} R_{1i} R_{1j} R_{1k} I_2 CCC_{2s} I_{2s} I_{n2} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK IONIC_CONSTRAINTS The first element on each line is an integer specifying the number of the constraint being specified. The second entry is either the symbol or atomic number of the species of the ion to which this constraint applies. The third element is the number of the ion within the species. The ordering of the ions in a species is the order in which they appear in the POSITIONS_FRAC or POSITIONS_ABS block in the cell definition file. The final three numbers are real numbers representing the coefficients of the Cartesian coordinates of the ionic position in the constraint sum. All coefficients in the sum not explicitly specified will be zero. On reading this data, the matrix of ionic constraints will be orthogonalised. %BLOCK CELL_CONSTRAINTS I_a I_b I_c I_alpha I_beta I_gamma %ENDBLOCK CELL_CONSTRAINTS The first three entries relate to the magnitude of the three lattice vectors a,b,c a,b,c and the second set of three entries to the angles \\alpha, \\beta, \\gamma \\alpha, \\beta, \\gamma . If the value of the entry corresponding to a magnitude or angle is zero, this quantity will remain fixed. If two or three entries contain the same integer, the corresponding quantities will be constrained to have the same value. If a positive integer greater than 0 occurs in entries 1 through 3 the same integer cannot occur in entries 4 through 6 as this would imply that a vector length and angle must have the same value.","title":"Constraints"},{"location":"documentation/Input_Files/cell_file/#species-characteristics","text":"The mass of a species, the pseudopotential which represents the ion and the size of the LCAO basis set used for population anslsyis may be specified in the cell definition file. %BLOCK SPECIES_MASS [units] CCC_1 I_1 R_1 CCC_2 I_2 R_2 ... %ENDBLOCK SPECIES_MASS [units] specifies the units in which the masses are defined. If not present, the default is atomic mass units. The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the mass of that species. Not all species need appear in the SPECIES_MASS block, any not present will assume the default mass for that species. If the initial alphabetical symbol specified for a species is not a standard element symbol in the periodic table, the mass of the species must be specified. %BLOCK SPECIES_POT CCC_1 I_1 CCC_2 I_2 ... %ENDBLOCK SPECIES_POT The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the filename of the file containing the definition of the pseudopotential representing the ionic species. The file to which this refers may be a definition of the parameters of the pseudopotential which is to be generated at runtime, or an old-style pseudopotential definition containing the data for the pseudopotential. Not all species need appear in the SPECIES_POT block. If a pseudopotential is not specified, the default pseudopotential parameters will be used to generate a pseudopotential for the element specified. If the initial alphabetical characters of a species label is not a standard element symbol in the periodic table, the potential for the species must be specified. The charge on the ion for each species will be derived from the pseudopotential corresponding to that ion. %BLOCK SPECIES_LCAO_STATES CCC_1 I_1 I_{B1} CCC_2 I_2 I_{B2} ... %ENDBLOCK SPECIES_LCAO_STATES The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second number is the number of angular momentum channels to use in the LCAO basis set for the species when performing population analysis. For example, to use the 2s and 2p states for C (The 1s state is a core state) this should be 2. By default, the number of states will be the appropriate number to complete the valence shell to the next noble gas. If shallow core states are excluded from a pseudopotential, the value of SPECIES_LCAO_STATES for that species should be included in the cell file to ensure a meaningful basis set is used.","title":"Species Characteristics"},{"location":"documentation/Input_Files/cell_file/#external-pressure","text":"An external pressure may be applied to the unit cell by specifying a pressure tensor. %BLOCK EXTERNAL_PRESSURE [units] R_{xx} R_{xy} R_{xz} R_{yy} R_{yz} R_{zz} %ENDBLOCK EXTERNAL_PRESSURE [units] specifies the units in which the pressure is defined. If not present, the default is GPa. Entry R_{xx} R_{xx} is the xx xx -component of the pressure, R_{xy} R_{xy} the xy xy -component etc. The default is to apply no external pressure.","title":"External Pressure"},{"location":"documentation/Input_Files/cell_file/#ionic-velocities","text":"The initial ionic velocities may be specified in Cartesian coordinates in a cell definition file. %BLOCK IONIC_VELOCITIES [units] CCC_1 V_{1x} V_{1y} V_{1z} CCC_2 V_{2x} V_{2y} V_{2z} ... %ENDBLOCK IONIC_VELOCITIES The first entry on a line is the chemical symbol (or atomic number) of the ionic species. The correct symbol will be looked up for the atomic species if the atomic number is specified. A symbol can have a maximum of three characters. The next three entries are real numbers representing the velocity of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5/ps. If this keyword is not present and a molecular dynamics calculation is performed, the ionic velocities will be randomly initialised with the appropriate temperature.","title":"Ionic Velocities"},{"location":"documentation/Input_Files/cell_keywords/","text":"This is a concise list of the common keywords for CASTEP's cell input file. The definitions of the keywords are given in more detail in the section on the cell file . Keyword in the cell file Type Default Description LATTICE_CART ^1 ^1 B -- The cell lattice vectors in Cartesian coordinates. LATTICE_ABC ^1 ^1 B -- The cell lattice vectors specified in $ a, b, c, \\alpha, \\beta, \\gamma $ format. POSITIONS_FRAC ^2 ^2 B -- The positions of the ions in fraction coordinates with respect to the lattice vectors. POSITIONS_ABS ^2 ^2 B -- The positions of the ions in absolute coordinates. KPOINT_LIST ^3 ^3 B -- A list of k-points in the Brillouin zone with associated weights. KPOINT_MP_GRID ^3 ^3 W -- The k-points defined as a Monkhorst-Pack grid by specifying the grid dimensions in each direction. KPOINT_MP_SPACING ^3 ^3 P 0.1 \u00c5^{-1} \u00c5^{-1} The k-points as a Monkhorst-Pack grid by specifying the maximum distance between k-points. KPOINT_MP_OFFSET V 0,0,0 The offset of the origin of the Monkhorst-Pack grid in fractional coordinates relative to the reciprocal lattice vectors. SPECTRAL_KPOINT_PATH ^4 ^4 B -- A list of k-points in the Brillouin zone which defines the path along which a band-structure calculation will be performed. SPECTRAL_KPOINT_PATH_SPACING P 0.1 \u00c5^{-1} \u00c5^{-1} Specifies the maximum spacing between k-points along the path for which a band structure calculation will be performed. SPECTRAL_KPOINT_LIST ^4 ^4 B SCF k-points A list of k-points at which a band-structure calculation will be performed. SPECTRAL_KPOINT_MP_GRID ^4 ^4 W -- The k-points for optical matrix element calculations defined as a Monkhorst-Pack grid by specifying the grid dimensions in each direction. SPECTRAL_KPOINT_MP_SPACING ^4 ^4 P 0.1 \u00c5 ^{-1} ^{-1} The k-points for optical matrix element calculations as a Monkhorst-Pack grid by specifying the maximum distance between k-points. SPECTRAL_KPOINT_MP_OFFSET V 0,0,0 The offset of the origin of the Monkhorst-Pack grid for optical matrix element calculations in fractional coordinates relative to the reciprocal lattice vectors. PHONON_KPOINT_PATH ^5 ^5 B -- A list of k-points in the Brillouin zone which defines the path along which a phonon calculation will be performed. PHONON_KPOINT_PATH_SPACING P 0.1 \u00c5 ^{-1} ^{-1} Specifies the maximum spacing between k-points along the path for which a phonon calculation will be performed. PHONON_KPOINT_LIST ^5 ^5 B SCF k-points A list of k-points at which a phonon calculation will be performed. PHONON_GAMMA_DIRECTIONS B See text The directions in which the gamma point will be approached for calculation of the LO/TO splitting. SYMMETRY_GENERATE ^6 ^6 D no symmetry If this is present, the highest symmtery group of the cell will found and the corresponding symmetry operations generated. SYMMETRY_OPS ^6 ^6 B no symmetry The symmetry operations that apply to the cell. SYMMETRY_TOL P 0.01 \u00c5 The tolerance within which symmetry will be enforced. IONIC_CONSTRAINTS B no constraints The constraints on the motion of ions during relaxation or MD. FIX_ALL_IONS L FALSE Constrain all ionic positions to remain fixed. FIX_ALL_CELL L FALSE Constrain all cell parameters to remain fixed. FIX_COM L TRUE Constrain the centre of mass of the ions to remain fixed. CELL_CONSTRAINTS B no constraints The constraints on changes in the cell shape during relaxation or MD. SPECIES_MASS B atomic mass The masses of the ionic species. SPECIES_POT B see text The names of the pseudopotentials associated with each species. SPECIES_LCAO_STATES B see text The number of angular momentum states to use in the LCAO basis set for this species when performing population analysis. EXTERNAL_PRESSURE B no pressure The external pressure tensor. IONIC_VELOCITIES B random The velocities of the ions in Cartesian coordinates. For the argument types, B indicates block data, P means a physical value, L is a logical value, D is a keyword that may simply be defined (present) or not, V is a real vector and W is an integer vector. ^1 ^1 Only one of LATTICE_CART and LATTICE_ABC maybe present in a cell file. ^2 ^2 Only one of POSITIONS_FRAC and POSITIONS_ABS may be present in a cell file. ^3 ^3 Only one of KPOINTS_LIST , KPOINTS_MP_GRID and KPOINTS_MP_SPACING may be present in a cell file. ^4 ^4 Only one of SPECTRAL_KPOINT_PATH , SPECTRAL_KPOINTS_MP_GRID , SPECTRAL_KPOINTS_MP_SPACING and SPECTRAL_KPOINT_LIST may be present in a cell file. ^5 ^5 Only one of PHONON_KPOINT_PATH and PHONON_KPOINT_LIST may be present in a cell file. ^6 ^6 Only one of SYMMETRY_GENERATE and SYMMETRY_OPS may be present in a cell file.","title":"Cell Keywords"},{"location":"documentation/Input_Files/param_file/","text":"This is a detailed description of options for CASTEP's param file. See the basic param file page for an overview. This page has the most frequently-used param file options, but for a full set use CASTEP's built-in help . The param file is one of CASTEP's two main input files. It contains all of the information about the kind of simulation your wish CASTEP to perform, as well as details of how CASTEP should perform them and additional simulations and analyses. The file itself is a free-format keyword-driven text file, consisting largely of single-line keywords, although there are a small number of blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. All of the keywords and blocks are optional, but you will almost always want to change at least some. Task This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file . Cut-off energy The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV. XC functional Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"param File"},{"location":"documentation/Input_Files/param_file/#task","text":"This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file .","title":"Task"},{"location":"documentation/Input_Files/param_file/#cut-off-energy","text":"The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV.","title":"Cut-off energy"},{"location":"documentation/Input_Files/param_file/#xc-functional","text":"Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"XC functional"},{"location":"documentation/Molecular_Dynamics/basics/","text":"Fundamental to MD calculations is the calculation time-step. An appropriate value for the simulation should be specified in the parameters file in the following way. md_delta_t = 2 fs Any valid unit of time can be used when specifying the time-step. The number of time-steps to perform is specified with e.g. md_num_iter = 500 NB This is the number of steps to be calculated in this run. It is NOT the accumulated total number of steps in a series of continuation runs. The \"MD time\" value in the .castep file records the cumulative time. Ensembles The following statistical ensembles can be simulated using CASTEP. NVE In this ensemble the number of atoms (N), the shape and volume (V) of the simulation cell and the energy (E) remain constant. The conserved energy is the Born-Oppenheimer Hamiltonian E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} in atomic units. This ensemble is selected using the command md_ensemble = NVE in the parameters file. The actual value of the conserved energy will be the result of the initial self-consistent DFT calculation plus the kinetic energy of the initial ionic velocities. These ionic velocities are defined in one of three ways. By explicit user definition of ionic velocities in the cell file, e.g. %BLOCK IONIC_VELOCITIES auv H xxxxx yyyyy zzzzz H xxxxx yyyyy zzzzz O xxxxx yyyyy zzzzz %ENDBLOCK IONIC_VELOCITIES using any valid unit of velocity (auv is atomic unit of velocity), etc. By definition of an initial temperature in the parameters file, e.g. md_temperature = 293 K Note that this can be specified using any valid unit of temperature. In this case initial velocities are assigned randomly such that the total linear momentum is zero and the instantaneous temperature matches that specified. The system will reach equilibrium with a somewhat different temperature due to equipartition of kinetic and potential energy. By continuation from an equilibrated run at the desired temperature. This could be a run in any of the other available ensembles. This will also use the cell and ionic positions from the continuation file. See the section on continuation for details. Velocities read from a continuation file will always take precedence. If no continuation file is used, and both md_temperature and an IONIC_VELOCITIES block are specified, the md_temperature keyword will be ignored. By default, pressure is not calculated during an NVE run. To override this use the command calculate_stress = true in the parameters file. NVT This ensemble is selected with md_ensemble = NVT The system will be evolved to a specific temperature defined using the md_temperature keyword as used above. Initial velocities are assigned based on this temperature, read from an IONIC_VELOCITIES block in the cell file, or read from a continuation file in the same way as above. Temperature control can be implemented by one of several methods, all of which have been shown to correctly sample the canonical ensemble. The first of these is the deterministic Nose-Hoover chain method of Tuckerman et al 1 and is selected with md_thermostat = nose-hoover in the parameters file. In the NVT case, a single Nose-Hoover chain is coupled to all particle degrees of freedom. The length of the chain can also be specified, e.g. md_nhc_length = 5 for a chain of five thermostats. In the Nose-Hoover case with a chain of M M thermostats acting of N_{f} N_{f} ionic degrees of freedom, the conserved quantity is the pseudo-Hamiltonian \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} where the Q_{i} Q_{i} are the thermostat fictitious masses assigned automatically from the specified ion relaxation time and \\xi_{i} \\xi_{i} are the thermostat degrees of freedom. This is printed with the label Hamilt Energy: at each time-step. A Nose-Hoover thermostat with no chain (i.e. with M M =1 ) is known to not be ergodic and hence should be avoided. The second method of controlling temperature is through the stochastic Langevin thermostat. md_thermostat = langevin In this case the printed Hamiltonian energy is the value of equation above. This is not conserved by the dynamics, but should exhibit no long term drift from the equilibrium value. Finally, the temperature may be controled via the Hoover-Langevin thermostat. md_thermostat = hoover-langevin which is the fusion of a deterministic Nose-Hoover thermostat acting directly on the physical system, with a Langevin thermostat operating on the Nose-Hoover variables, in order to guarantee ergodicity. With each method, a suitable relaxation time for the thermostatic process should be specified. This can use any supported unit of time, e.g md_ion_t = 2.4 ps for a thermostat relaxation time of 2.4 picoseconds. The Hoover-Langevin thermostat is the LEAST sensitive to the choice of this value. As with the NVE ensemble, pressure is not calculated by default. This is overridden in the same way as the NVE case. NPH In this ensemble the size and (if desired) shape of the simulation cell varies to regulate pressure. No thermostat is applied and hence the enthalpy (H) is conserved. This ensemble is specified with the following: md_ensemble = NPH The external pressure is set in the cell definition file using any valid unit of pressure. The required symmetry of the external pressure tensor implies that only the upper triangular components need be specified, e.g. %block external_pressure GPa 0.5 0.0 0.0 0.5 0.0 0.5 %endblock external_pressure to specify an isotropic external pressure of 0.5 Giga-Pascals. MD can also support non-isotropic pressure if using a variable-shape barostat. Velocities are assigned such that the initial temperature is equal to md_temperature , or are read from the cell definition file/continuation file as in the NVE/NVT cases. Two barostat schemes are available. The first restricts the dynamics of the cell to isotropic expansions and contractions. This follows the method of Andersen 2 and Hoover 3 4 as corrected by Martyna et al. 5 . This is selected using: md_barostat = andersen-hoover In this case the printed Hamiltonian energy is the enthalpy, plus the kinetic energy associated with the cell motion. \\begin{equation} \\label{eq:AndersenNPH} H = \\left<\\Psi|\\hat{H} {e}|\\Psi\\right> + \\frac{1}{2} \\sum {N}\\sum_{j=1} {|\\mathbf{R}}\\frac{Z_{i}Z_{j} {i}-\\mathbf{R} +\\sum_{i=1}}| {N}\\frac{P_{i} /2W \\end{equation } The alternative scheme implements the method of Parrinello and Rahman}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2 6 7 . Both the size and shape of the simulation cell are allowed to vary. The issue of cell rotations is eliminated by the use of a symmetrised pressure tensor. Note that as liquids cannot sustain shear, this method should only be used with solids. It should also be noted that this scheme is based on the modified Parrinello-Rahman method of Martyna, Tobias and Klien 5 . The following line in the parameters file selects this barostat. md_barostat = parrinello-rahman The cell dynamics contain nine degrees of freedom (of which six are independent) leading to a Hamiltonian energy of \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} For both barostats, a relaxation time for the cell motions should be specified with an appropriate unit of time, for example: md_cell_t = 20 ps This time is used to calculate a fictitious mass W W for the cell dynamics and should be large compared to the characteristic time for the ionic dynamics. The NPH equations of motion require that pressure (stress) is calculated at each MD time-step. The value of calculate_stress is therefore irrelevant in this case. A variable cell implies variable reciprocal lattice vectors which has consequences for the plane-wave basis set. As the cell changes, the number of plane waves required to produce the specified cut-off energy changes. The user therefore has two options. The first is to fix the size of the basis set. fixed_npw = true The cut-off energy is now variable as is the quality of the basis set. This option should therefore only be used for calculations in which the volume changes are small and which are over-converged with respect to the number of plane waves. The second option is to allow the basis set to change at each time-step. fixed_npw = false which is the default value. This keeps the cut-off energy approximately constant by adding or subtracting plane waves from the basis set at each time-step. In either case, the effect of Pulay stress is reduced by applying a finite basis set correction to the pressure at each time-step. In the case of a fixed number of plane waves, the constant correction to energy is ignored. With variable number of plane waves the energy correction is no longer constant and is recalculated at each step. NPT The NPT ensemble is specified with the command: md_ensemble = NPT This can use either the Nose-Hoover or Langevin thermostat, and either Andersen-Hoover or Parrinello-Rahman barostat. In all cases, the dynamics can be shown to correctly sample the isothermal-isobaric ensemble 5 All options pertaining to the NPH and NVT ensembles apply. In the case of Langevin dynamics at NPT, the printed Hamiltonian energy is the same as in the NPH ensemble, i.e. that given by the equations above. In the case of Nose-Hoover NPT molecular dynamics, the Hamiltonian energy is given by \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} in the case of isotropic cell dynamics, or \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} in the Parrinello-Rahman case. Note that in each case the motion of the cell degree(s) of freedom couple to a second Nose-Hoover chain. Glenn J. Martyna, Michael L. Klein, and Mark Tuckerman. Nos\u00e9\u2013Hoover chains: The canonical ensemble via continuous dynamics. The Journal of Chemical Physics , 97(4):2635\u20132643, 08 1992. doi:10.1063/1.463940 . \u21a9 Hans C. Andersen. Molecular dynamics simulations at constant pressure and/or temperature. The Journal of Chemical Physics , 72(4):2384\u20132393, 02 1980. doi:10.1063/1.439486 . \u21a9 William G. Hoover. Canonical dynamics: equilibrium phase-space distributions. Phys. Rev. A , 31:1695\u20131697, Mar 1985. doi:10.1103/PhysRevA.31.1695 . \u21a9 William G. Hoover. Constant-pressure equations of motion. Phys. Rev. A , 34:2499\u20132500, Sep 1986. doi:10.1103/PhysRevA.34.2499 . \u21a9 Glenn J. Martyna, Douglas J. Tobias, and Michael L. Klein. Constant pressure molecular dynamics algorithms. The Journal of Chemical Physics , 101(5):4177\u20134189, 09 1994. doi:10.1063/1.467468 . \u21a9 \u21a9 \u21a9 M. Parrinello and A. Rahman. Crystal structure and pair potentials: a molecular-dynamics study. Phys. Rev. Lett. , 45:1196\u20131199, Oct 1980. doi:10.1103/PhysRevLett.45.1196 . \u21a9 M. Parrinello and A. Rahman. Polymorphic transitions in single crystals: A new molecular dynamics method. Journal of Applied Physics , 52(12):7182\u20137190, 12 1981. doi:10.1063/1.328693 . \u21a9","title":"MD Basics"},{"location":"documentation/Molecular_Dynamics/basics/#ensembles","text":"The following statistical ensembles can be simulated using CASTEP.","title":"Ensembles"},{"location":"documentation/Molecular_Dynamics/basics/#nve","text":"In this ensemble the number of atoms (N), the shape and volume (V) of the simulation cell and the energy (E) remain constant. The conserved energy is the Born-Oppenheimer Hamiltonian E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} in atomic units. This ensemble is selected using the command md_ensemble = NVE in the parameters file. The actual value of the conserved energy will be the result of the initial self-consistent DFT calculation plus the kinetic energy of the initial ionic velocities. These ionic velocities are defined in one of three ways. By explicit user definition of ionic velocities in the cell file, e.g. %BLOCK IONIC_VELOCITIES auv H xxxxx yyyyy zzzzz H xxxxx yyyyy zzzzz O xxxxx yyyyy zzzzz %ENDBLOCK IONIC_VELOCITIES using any valid unit of velocity (auv is atomic unit of velocity), etc. By definition of an initial temperature in the parameters file, e.g. md_temperature = 293 K Note that this can be specified using any valid unit of temperature. In this case initial velocities are assigned randomly such that the total linear momentum is zero and the instantaneous temperature matches that specified. The system will reach equilibrium with a somewhat different temperature due to equipartition of kinetic and potential energy. By continuation from an equilibrated run at the desired temperature. This could be a run in any of the other available ensembles. This will also use the cell and ionic positions from the continuation file. See the section on continuation for details. Velocities read from a continuation file will always take precedence. If no continuation file is used, and both md_temperature and an IONIC_VELOCITIES block are specified, the md_temperature keyword will be ignored. By default, pressure is not calculated during an NVE run. To override this use the command calculate_stress = true in the parameters file.","title":"NVE"},{"location":"documentation/Molecular_Dynamics/basics/#nvt","text":"This ensemble is selected with md_ensemble = NVT The system will be evolved to a specific temperature defined using the md_temperature keyword as used above. Initial velocities are assigned based on this temperature, read from an IONIC_VELOCITIES block in the cell file, or read from a continuation file in the same way as above. Temperature control can be implemented by one of several methods, all of which have been shown to correctly sample the canonical ensemble. The first of these is the deterministic Nose-Hoover chain method of Tuckerman et al 1 and is selected with md_thermostat = nose-hoover in the parameters file. In the NVT case, a single Nose-Hoover chain is coupled to all particle degrees of freedom. The length of the chain can also be specified, e.g. md_nhc_length = 5 for a chain of five thermostats. In the Nose-Hoover case with a chain of M M thermostats acting of N_{f} N_{f} ionic degrees of freedom, the conserved quantity is the pseudo-Hamiltonian \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} where the Q_{i} Q_{i} are the thermostat fictitious masses assigned automatically from the specified ion relaxation time and \\xi_{i} \\xi_{i} are the thermostat degrees of freedom. This is printed with the label Hamilt Energy: at each time-step. A Nose-Hoover thermostat with no chain (i.e. with M M =1 ) is known to not be ergodic and hence should be avoided. The second method of controlling temperature is through the stochastic Langevin thermostat. md_thermostat = langevin In this case the printed Hamiltonian energy is the value of equation above. This is not conserved by the dynamics, but should exhibit no long term drift from the equilibrium value. Finally, the temperature may be controled via the Hoover-Langevin thermostat. md_thermostat = hoover-langevin which is the fusion of a deterministic Nose-Hoover thermostat acting directly on the physical system, with a Langevin thermostat operating on the Nose-Hoover variables, in order to guarantee ergodicity. With each method, a suitable relaxation time for the thermostatic process should be specified. This can use any supported unit of time, e.g md_ion_t = 2.4 ps for a thermostat relaxation time of 2.4 picoseconds. The Hoover-Langevin thermostat is the LEAST sensitive to the choice of this value. As with the NVE ensemble, pressure is not calculated by default. This is overridden in the same way as the NVE case.","title":"NVT"},{"location":"documentation/Molecular_Dynamics/basics/#nph","text":"In this ensemble the size and (if desired) shape of the simulation cell varies to regulate pressure. No thermostat is applied and hence the enthalpy (H) is conserved. This ensemble is specified with the following: md_ensemble = NPH The external pressure is set in the cell definition file using any valid unit of pressure. The required symmetry of the external pressure tensor implies that only the upper triangular components need be specified, e.g. %block external_pressure GPa 0.5 0.0 0.0 0.5 0.0 0.5 %endblock external_pressure to specify an isotropic external pressure of 0.5 Giga-Pascals. MD can also support non-isotropic pressure if using a variable-shape barostat. Velocities are assigned such that the initial temperature is equal to md_temperature , or are read from the cell definition file/continuation file as in the NVE/NVT cases. Two barostat schemes are available. The first restricts the dynamics of the cell to isotropic expansions and contractions. This follows the method of Andersen 2 and Hoover 3 4 as corrected by Martyna et al. 5 . This is selected using: md_barostat = andersen-hoover In this case the printed Hamiltonian energy is the enthalpy, plus the kinetic energy associated with the cell motion. \\begin{equation} \\label{eq:AndersenNPH} H = \\left<\\Psi|\\hat{H} {e}|\\Psi\\right> + \\frac{1}{2} \\sum {N}\\sum_{j=1} {|\\mathbf{R}}\\frac{Z_{i}Z_{j} {i}-\\mathbf{R} +\\sum_{i=1}}| {N}\\frac{P_{i} /2W \\end{equation } The alternative scheme implements the method of Parrinello and Rahman}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2 6 7 . Both the size and shape of the simulation cell are allowed to vary. The issue of cell rotations is eliminated by the use of a symmetrised pressure tensor. Note that as liquids cannot sustain shear, this method should only be used with solids. It should also be noted that this scheme is based on the modified Parrinello-Rahman method of Martyna, Tobias and Klien 5 . The following line in the parameters file selects this barostat. md_barostat = parrinello-rahman The cell dynamics contain nine degrees of freedom (of which six are independent) leading to a Hamiltonian energy of \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} For both barostats, a relaxation time for the cell motions should be specified with an appropriate unit of time, for example: md_cell_t = 20 ps This time is used to calculate a fictitious mass W W for the cell dynamics and should be large compared to the characteristic time for the ionic dynamics. The NPH equations of motion require that pressure (stress) is calculated at each MD time-step. The value of calculate_stress is therefore irrelevant in this case. A variable cell implies variable reciprocal lattice vectors which has consequences for the plane-wave basis set. As the cell changes, the number of plane waves required to produce the specified cut-off energy changes. The user therefore has two options. The first is to fix the size of the basis set. fixed_npw = true The cut-off energy is now variable as is the quality of the basis set. This option should therefore only be used for calculations in which the volume changes are small and which are over-converged with respect to the number of plane waves. The second option is to allow the basis set to change at each time-step. fixed_npw = false which is the default value. This keeps the cut-off energy approximately constant by adding or subtracting plane waves from the basis set at each time-step. In either case, the effect of Pulay stress is reduced by applying a finite basis set correction to the pressure at each time-step. In the case of a fixed number of plane waves, the constant correction to energy is ignored. With variable number of plane waves the energy correction is no longer constant and is recalculated at each step.","title":"NPH"},{"location":"documentation/Molecular_Dynamics/basics/#npt","text":"The NPT ensemble is specified with the command: md_ensemble = NPT This can use either the Nose-Hoover or Langevin thermostat, and either Andersen-Hoover or Parrinello-Rahman barostat. In all cases, the dynamics can be shown to correctly sample the isothermal-isobaric ensemble 5 All options pertaining to the NPH and NVT ensembles apply. In the case of Langevin dynamics at NPT, the printed Hamiltonian energy is the same as in the NPH ensemble, i.e. that given by the equations above. In the case of Nose-Hoover NPT molecular dynamics, the Hamiltonian energy is given by \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} in the case of isotropic cell dynamics, or \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} in the Parrinello-Rahman case. Note that in each case the motion of the cell degree(s) of freedom couple to a second Nose-Hoover chain. Glenn J. Martyna, Michael L. Klein, and Mark Tuckerman. Nos\u00e9\u2013Hoover chains: The canonical ensemble via continuous dynamics. The Journal of Chemical Physics , 97(4):2635\u20132643, 08 1992. doi:10.1063/1.463940 . \u21a9 Hans C. Andersen. Molecular dynamics simulations at constant pressure and/or temperature. The Journal of Chemical Physics , 72(4):2384\u20132393, 02 1980. doi:10.1063/1.439486 . \u21a9 William G. Hoover. Canonical dynamics: equilibrium phase-space distributions. Phys. Rev. A , 31:1695\u20131697, Mar 1985. doi:10.1103/PhysRevA.31.1695 . \u21a9 William G. Hoover. Constant-pressure equations of motion. Phys. Rev. A , 34:2499\u20132500, Sep 1986. doi:10.1103/PhysRevA.34.2499 . \u21a9 Glenn J. Martyna, Douglas J. Tobias, and Michael L. Klein. Constant pressure molecular dynamics algorithms. The Journal of Chemical Physics , 101(5):4177\u20134189, 09 1994. doi:10.1063/1.467468 . \u21a9 \u21a9 \u21a9 M. Parrinello and A. Rahman. Crystal structure and pair potentials: a molecular-dynamics study. Phys. Rev. Lett. , 45:1196\u20131199, Oct 1980. doi:10.1103/PhysRevLett.45.1196 . \u21a9 M. Parrinello and A. Rahman. Polymorphic transitions in single crystals: A new molecular dynamics method. Journal of Applied Physics , 52(12):7182\u20137190, 12 1981. doi:10.1063/1.328693 . \u21a9","title":"NPT"},{"location":"documentation/Molecular_Dynamics/files/","text":"Understanding the Output In this chapter we shall briefly describe the output produced during a CASTEP calculation. Only the level of detail printed at iprint = 1 will be discussed. The .castep file Header As well as the usual information printed at the top of the output file, the molecular dynamics data specified in the parameters file is presented. ************************ Molecular Dynamics Parameters ************************ ensemble : NPT variable cell method : fixed basis quality pressure : see below temperature : 293.0 K using : Parrinello-Rahman barostat with characteristic cell time : 26.00 ps using : Langevin thermostat with characteristic ionic time : 16.95 ps time step : 0.2000E-02 ps number of MD steps : 500000 using best-fit first order extrapolation for wavefunctions backup results every : 5 steps MD SCF energy / atom convergence tol. : 0.1000E-04 eV MD SCF convergence tolerance window : 3 cycles ******************************************************************************* This amount of information presented in this section will obviously vary depending on the type of calculation being performed, but should be self-explanatory. Initial cell The information specified in the .cell file is then output. This will include the ionic positions, any user specified velocities if present, the usual pseudo-potential, k-point information, and details of any constraints. The total energy of the initial cell is then minimised, performing a finite basis set correction along the way if appropriate. The message Starting MD is then printed, and the MD calculation proper commences. As the first time-step will require data on forces, stress (for variable cell calculations) and energies, these are evaluated and printed at this point. Forces are output in the following format, using the force unit specified by the user, or the default of eV / Ang. ******************************** Forces ********************************* * * * Cartesian components (eV/A) * * --------------------------------------------------------------------- * * x y z * * * * Si 1 -0.02632 -0.02632 -0.02632 * * Si 2 -0.02653 -0.02617 -0.02617 * * Si 3 -0.02617 -0.02617 -0.02653 * * Si 4 -0.02617 -0.02653 -0.02617 * * Si 5 0.00075 0.05164 0.00075 * * Si 6 0.05204 0.05204 0.05204 * * Si 7 0.05164 0.00075 0.00075 * * Si 8 0.00075 0.00075 0.05164 * * * ************************************************************************* The stress tensor (if calculated) is output in the specified units of pressure, along with the corresponding scalar T=0 T=0 pressure, i.e. one third of the trace of the stress tensor. ***************** Stress Tensor ***************** * * * Cartesian components (GPa) * * --------------------------------------------- * * x y z * * * * x 0.009981 1.140649 1.140649 * * y 1.140649 0.009981 1.140649 * * z 1.140649 1.140649 0.009981 * * * * Pressure: -0.0100 * * * ************************************************* The current time and MD energies are then printed in the user specified energy units. Here potential energy refers to the total configurational energy of electrons plus ions obtained from the DFT calculation. Kinetic energy is the classical kinetic energy of the ions. Total energy refers to the sum of these two energies. The enthalpy and the relevant Hamiltonian energy for the ensemble as quoted in section ensembles is then printed. The temperature is also output at this point. Note that this is the ionic temperature only. If performing a calculation with finite temperature electrons (i.e. EDFT) the electron temperature may not be the same. Finally total pressure, i.e. the trace of the stress tensor plus the kinetic (ideal gas) pressure is printed in the user specified pressure units. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx x MD Data: x x x x time : 0.000000 ps x x x x Potential Energy: -865.882944 eV x x Kinetic Energy: 0.265113 eV x x Total Energy: -865.617832 eV x x Enthalpy: -865.617735 eV x x Hamilt Energy: -865.617735 eV x x x x Temperature: 293.000000 K x x T/=0 Pressure: 0.172231 GPa x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Iteration The MD simulation proper now begins. ================================================================= Starting MD iteration 1 ... ================================================================= Following this message the current cell information on the new configuration is printed and the energy is re-minimised to determine the new forces. The MD step is then performed and the updated forces, stress and energy information is printed in the same manner as above. ----------------------------------------------------------------- ... finished MD iteration 1 ----------------------------------------------------------------- The process repeats until the calculation is killed, or the specified number of MD iterations is completed. The .md file The .md file is provided as a single source for all the dynamical data produced by a CASTEP calculation. In all cases, data is printed in Hartree atomic units. Fortran formating data will be given here for all entries in this file for those who wish to import it into their own analysis codes. The CASTEP default behaviour is to record every single configuration in the .md file. This can therefore grow to quite a large size if doing a long MD run! The only exception to this, is if doing a non-DFT calculation, whereupon a sample of the configurations are written if md_sample_iter >0, otherwise no configurations are written. Note that unlike the .castep file, the .md file from a previous calculation with the same seedname will be overwritten, unless the new calculation is a continuation of the original. Header At the top of every .md file a header is written as below. The total length is four lines including blanks. The comments written are taken from the cell/parameter files. BEGIN header This is 8 atom cubic Si cell END header This is followed by a blank line. There is a single space at the start of each non-blank line. This header is written once only. Time and Energy Data The next entry will be the data for the first MD step. This begins with the current time on the first line, followed by the Total, Hamiltonian, and Kinetic energy on the second line with the label <-- E . 0.00000000E+000 -3.18206146E+001 -3.18108683E+001 9.74270683E-003 <-- E Formatting: format(12x,es18.8e3) format(9x,3(3x,es18.8e3),' <-- E') Thermodynamic Data The current temperature is then printed with the label <-- T . If the output is from a variable cell calculation, or calculate_stress has been explicitly set to true, the pressure is also printed with the label <-- P . 9.27876841E-04 <-- T 5.85402338E-06 <-- P Formatting: format(12x,es18.8,T73, ' <-- T') format(12x,es18.8,T73, ' <-- P') Cell Data For all calculations, the current matrix of cell vectors is printed with the label <-- h Each row gives the three Cartesian components of one of the cell vectors. 1.01599045E+001 0.00000000E+000 0.00000000E+000 <-- h 1.29430839E-017 1.01599045E+001 0.00000000E+000 <-- h 1.29430839E-017 1.29430839E-017 1.01599045E+001 <-- h Formatting: format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') The remaining cell data is only printed for variable cell calculations, regardless of the value of calculate_stress . First the velocity of each cell vector is printed with the label <-- hv . 2.80052926E-008 -1.42751448E-007 -1.35787248E-007 <-- hv -1.42751448E-007 2.76907508E-008 -1.44694219E-007 <-- hv -1.35787248E-007 -1.44694219E-007 2.71532850E-008 <-- hv Formatting: format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') The full pressure tensor (including kinetic contributions) is then printed with the label <-- S in a similar fashion. -6.21684372E-006 3.03062374E-005 3.23291890E-005 <-- S 3.03062374E-005 -6.06171719E-006 3.31426773E-005 <-- S 3.23291890E-005 3.31426773E-005 -5.79666096E-006 <-- S Formatting: format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') Ionic Data Data on the current ionic configuration is then printed. Atoms are identified by their chemical symbol in the first column, and number of the atom within the species in the second. First the position vectors of all ions are printed with the label <-- R . Si 1 1.04834750E-002 1.15560090E-002 7.82230990E-003 <-- R Si 2 -3.20400394E-003 5.07172565E+000 5.10986361E+000 <-- R Si 3 5.07271954E+000 5.11656710E+000 -2.45225140E-003 <-- R Si 4 5.10789066E+000 -2.63240242E-002 5.09753015E+000 <-- R Si 5 7.57309188E+000 2.52845762E+000 7.57612741E+000 <-- R Si 6 2.55271297E+000 2.54057876E+000 2.53924276E+000 <-- R Si 7 2.53422324E+000 7.64091983E+000 7.62428191E+000 <-- R Si 8 7.63167143E+000 7.59610368E+000 2.52717191E+000 <-- R Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- R') Velocities are then printed in a similar fashion. Si 1 5.77278549E-005 7.23673746E-005 4.30349159E-005 <-- V Si 2 -1.72415752E-005 -5.23270551E-005 1.75385181E-004 <-- V Si 3 -4.17085102E-005 2.14539848E-004 -1.78769096E-005 <-- V Si 4 1.58756714E-004 -1.60916056E-004 9.49147966E-005 <-- V Si 5 -2.70431102E-004 -7.18757382E-005 -2.43440176E-004 <-- V Si 6 7.51663795E-005 8.70332331E-008 -8.82271461E-006 <-- V Si 7 -4.19898677E-005 1.31687892E-004 3.60873179E-005 <-- V Si 8 7.97201068E-005 -1.33563298E-004 -7.92824105E-005 <-- V Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- V') Finally forces are printed. Si 1 -4.23569381E-003 2.52214252E-003 -2.46018145E-003 <-- F Si 2 3.06338418E-003 -2.16206923E-003 -5.29928454E-003 <-- F Si 3 7.37259995E-004 -4.73479365E-003 -2.20030945E-003 <-- F Si 4 -6.89050954E-003 -2.25153379E-003 -8.37626756E-003 <-- F Si 5 4.53551291E-003 3.34757083E-003 1.02791157E-002 <-- F Si 6 2.06737343E-003 2.05175887E-003 2.70990363E-003 <-- F Si 7 -1.41457164E-003 -9.15433604E-004 1.54850432E-003 <-- F Si 8 2.13724448E-003 2.14235805E-003 3.79851935E-003 <-- F Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- F') A blank line is then printed, and the process repeats with the data from the next time-step. The .hug file If you are using the Hugoniostat predictor-corrector method to generate a Hugoniot curve, each different state point generated has a different compression etc. This is summarized in the .hug file as follows: 0.990000000000 36.31531287 0.41888602 0.15771481 <-- cTPE 0.943272613764 40.07750465 0.63662992 1.62298398 <-- cTPE 0.865294155381 58.07130958 1.30346964 6.92736406 <-- cTPE The 4 data fields are: c - the ratio of the compressed to original cell vectors T - the temperature (in user units) - calculated as a time average of the instantaneous temperature of the configurations at this compression P - the pressure (in user units) - calculated as a time average E - the energy (in user units) - calculated as a time average","title":"MD Files"},{"location":"documentation/Molecular_Dynamics/files/#understanding-the-output","text":"In this chapter we shall briefly describe the output produced during a CASTEP calculation. Only the level of detail printed at iprint = 1 will be discussed.","title":"Understanding the Output"},{"location":"documentation/Molecular_Dynamics/files/#the-castep-file","text":"","title":"The .castep file"},{"location":"documentation/Molecular_Dynamics/files/#header","text":"As well as the usual information printed at the top of the output file, the molecular dynamics data specified in the parameters file is presented. ************************ Molecular Dynamics Parameters ************************ ensemble : NPT variable cell method : fixed basis quality pressure : see below temperature : 293.0 K using : Parrinello-Rahman barostat with characteristic cell time : 26.00 ps using : Langevin thermostat with characteristic ionic time : 16.95 ps time step : 0.2000E-02 ps number of MD steps : 500000 using best-fit first order extrapolation for wavefunctions backup results every : 5 steps MD SCF energy / atom convergence tol. : 0.1000E-04 eV MD SCF convergence tolerance window : 3 cycles ******************************************************************************* This amount of information presented in this section will obviously vary depending on the type of calculation being performed, but should be self-explanatory.","title":"Header"},{"location":"documentation/Molecular_Dynamics/files/#initial-cell","text":"The information specified in the .cell file is then output. This will include the ionic positions, any user specified velocities if present, the usual pseudo-potential, k-point information, and details of any constraints. The total energy of the initial cell is then minimised, performing a finite basis set correction along the way if appropriate. The message Starting MD is then printed, and the MD calculation proper commences. As the first time-step will require data on forces, stress (for variable cell calculations) and energies, these are evaluated and printed at this point. Forces are output in the following format, using the force unit specified by the user, or the default of eV / Ang. ******************************** Forces ********************************* * * * Cartesian components (eV/A) * * --------------------------------------------------------------------- * * x y z * * * * Si 1 -0.02632 -0.02632 -0.02632 * * Si 2 -0.02653 -0.02617 -0.02617 * * Si 3 -0.02617 -0.02617 -0.02653 * * Si 4 -0.02617 -0.02653 -0.02617 * * Si 5 0.00075 0.05164 0.00075 * * Si 6 0.05204 0.05204 0.05204 * * Si 7 0.05164 0.00075 0.00075 * * Si 8 0.00075 0.00075 0.05164 * * * ************************************************************************* The stress tensor (if calculated) is output in the specified units of pressure, along with the corresponding scalar T=0 T=0 pressure, i.e. one third of the trace of the stress tensor. ***************** Stress Tensor ***************** * * * Cartesian components (GPa) * * --------------------------------------------- * * x y z * * * * x 0.009981 1.140649 1.140649 * * y 1.140649 0.009981 1.140649 * * z 1.140649 1.140649 0.009981 * * * * Pressure: -0.0100 * * * ************************************************* The current time and MD energies are then printed in the user specified energy units. Here potential energy refers to the total configurational energy of electrons plus ions obtained from the DFT calculation. Kinetic energy is the classical kinetic energy of the ions. Total energy refers to the sum of these two energies. The enthalpy and the relevant Hamiltonian energy for the ensemble as quoted in section ensembles is then printed. The temperature is also output at this point. Note that this is the ionic temperature only. If performing a calculation with finite temperature electrons (i.e. EDFT) the electron temperature may not be the same. Finally total pressure, i.e. the trace of the stress tensor plus the kinetic (ideal gas) pressure is printed in the user specified pressure units. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx x MD Data: x x x x time : 0.000000 ps x x x x Potential Energy: -865.882944 eV x x Kinetic Energy: 0.265113 eV x x Total Energy: -865.617832 eV x x Enthalpy: -865.617735 eV x x Hamilt Energy: -865.617735 eV x x x x Temperature: 293.000000 K x x T/=0 Pressure: 0.172231 GPa x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","title":"Initial cell"},{"location":"documentation/Molecular_Dynamics/files/#iteration","text":"The MD simulation proper now begins. ================================================================= Starting MD iteration 1 ... ================================================================= Following this message the current cell information on the new configuration is printed and the energy is re-minimised to determine the new forces. The MD step is then performed and the updated forces, stress and energy information is printed in the same manner as above. ----------------------------------------------------------------- ... finished MD iteration 1 ----------------------------------------------------------------- The process repeats until the calculation is killed, or the specified number of MD iterations is completed.","title":"Iteration"},{"location":"documentation/Molecular_Dynamics/files/#the-md-file","text":"The .md file is provided as a single source for all the dynamical data produced by a CASTEP calculation. In all cases, data is printed in Hartree atomic units. Fortran formating data will be given here for all entries in this file for those who wish to import it into their own analysis codes. The CASTEP default behaviour is to record every single configuration in the .md file. This can therefore grow to quite a large size if doing a long MD run! The only exception to this, is if doing a non-DFT calculation, whereupon a sample of the configurations are written if md_sample_iter >0, otherwise no configurations are written. Note that unlike the .castep file, the .md file from a previous calculation with the same seedname will be overwritten, unless the new calculation is a continuation of the original.","title":"The .md file"},{"location":"documentation/Molecular_Dynamics/files/#header_1","text":"At the top of every .md file a header is written as below. The total length is four lines including blanks. The comments written are taken from the cell/parameter files. BEGIN header This is 8 atom cubic Si cell END header This is followed by a blank line. There is a single space at the start of each non-blank line. This header is written once only.","title":"Header"},{"location":"documentation/Molecular_Dynamics/files/#time-and-energy-data","text":"The next entry will be the data for the first MD step. This begins with the current time on the first line, followed by the Total, Hamiltonian, and Kinetic energy on the second line with the label <-- E . 0.00000000E+000 -3.18206146E+001 -3.18108683E+001 9.74270683E-003 <-- E Formatting: format(12x,es18.8e3) format(9x,3(3x,es18.8e3),' <-- E')","title":"Time and Energy Data"},{"location":"documentation/Molecular_Dynamics/files/#thermodynamic-data","text":"The current temperature is then printed with the label <-- T . If the output is from a variable cell calculation, or calculate_stress has been explicitly set to true, the pressure is also printed with the label <-- P . 9.27876841E-04 <-- T 5.85402338E-06 <-- P Formatting: format(12x,es18.8,T73, ' <-- T') format(12x,es18.8,T73, ' <-- P')","title":"Thermodynamic Data"},{"location":"documentation/Molecular_Dynamics/files/#cell-data","text":"For all calculations, the current matrix of cell vectors is printed with the label <-- h Each row gives the three Cartesian components of one of the cell vectors. 1.01599045E+001 0.00000000E+000 0.00000000E+000 <-- h 1.29430839E-017 1.01599045E+001 0.00000000E+000 <-- h 1.29430839E-017 1.29430839E-017 1.01599045E+001 <-- h Formatting: format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') The remaining cell data is only printed for variable cell calculations, regardless of the value of calculate_stress . First the velocity of each cell vector is printed with the label <-- hv . 2.80052926E-008 -1.42751448E-007 -1.35787248E-007 <-- hv -1.42751448E-007 2.76907508E-008 -1.44694219E-007 <-- hv -1.35787248E-007 -1.44694219E-007 2.71532850E-008 <-- hv Formatting: format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') The full pressure tensor (including kinetic contributions) is then printed with the label <-- S in a similar fashion. -6.21684372E-006 3.03062374E-005 3.23291890E-005 <-- S 3.03062374E-005 -6.06171719E-006 3.31426773E-005 <-- S 3.23291890E-005 3.31426773E-005 -5.79666096E-006 <-- S Formatting: format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S')","title":"Cell Data"},{"location":"documentation/Molecular_Dynamics/files/#ionic-data","text":"Data on the current ionic configuration is then printed. Atoms are identified by their chemical symbol in the first column, and number of the atom within the species in the second. First the position vectors of all ions are printed with the label <-- R . Si 1 1.04834750E-002 1.15560090E-002 7.82230990E-003 <-- R Si 2 -3.20400394E-003 5.07172565E+000 5.10986361E+000 <-- R Si 3 5.07271954E+000 5.11656710E+000 -2.45225140E-003 <-- R Si 4 5.10789066E+000 -2.63240242E-002 5.09753015E+000 <-- R Si 5 7.57309188E+000 2.52845762E+000 7.57612741E+000 <-- R Si 6 2.55271297E+000 2.54057876E+000 2.53924276E+000 <-- R Si 7 2.53422324E+000 7.64091983E+000 7.62428191E+000 <-- R Si 8 7.63167143E+000 7.59610368E+000 2.52717191E+000 <-- R Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- R') Velocities are then printed in a similar fashion. Si 1 5.77278549E-005 7.23673746E-005 4.30349159E-005 <-- V Si 2 -1.72415752E-005 -5.23270551E-005 1.75385181E-004 <-- V Si 3 -4.17085102E-005 2.14539848E-004 -1.78769096E-005 <-- V Si 4 1.58756714E-004 -1.60916056E-004 9.49147966E-005 <-- V Si 5 -2.70431102E-004 -7.18757382E-005 -2.43440176E-004 <-- V Si 6 7.51663795E-005 8.70332331E-008 -8.82271461E-006 <-- V Si 7 -4.19898677E-005 1.31687892E-004 3.60873179E-005 <-- V Si 8 7.97201068E-005 -1.33563298E-004 -7.92824105E-005 <-- V Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- V') Finally forces are printed. Si 1 -4.23569381E-003 2.52214252E-003 -2.46018145E-003 <-- F Si 2 3.06338418E-003 -2.16206923E-003 -5.29928454E-003 <-- F Si 3 7.37259995E-004 -4.73479365E-003 -2.20030945E-003 <-- F Si 4 -6.89050954E-003 -2.25153379E-003 -8.37626756E-003 <-- F Si 5 4.53551291E-003 3.34757083E-003 1.02791157E-002 <-- F Si 6 2.06737343E-003 2.05175887E-003 2.70990363E-003 <-- F Si 7 -1.41457164E-003 -9.15433604E-004 1.54850432E-003 <-- F Si 8 2.13724448E-003 2.14235805E-003 3.79851935E-003 <-- F Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- F') A blank line is then printed, and the process repeats with the data from the next time-step.","title":"Ionic Data"},{"location":"documentation/Molecular_Dynamics/files/#the-hug-file","text":"If you are using the Hugoniostat predictor-corrector method to generate a Hugoniot curve, each different state point generated has a different compression etc. This is summarized in the .hug file as follows: 0.990000000000 36.31531287 0.41888602 0.15771481 <-- cTPE 0.943272613764 40.07750465 0.63662992 1.62298398 <-- cTPE 0.865294155381 58.07130958 1.30346964 6.92736406 <-- cTPE The 4 data fields are: c - the ratio of the compressed to original cell vectors T - the temperature (in user units) - calculated as a time average of the instantaneous temperature of the configurations at this compression P - the pressure (in user units) - calculated as a time average E - the energy (in user units) - calculated as a time average","title":"The .hug file"},{"location":"documentation/Molecular_Dynamics/hugoniostat/","text":"Hugoniostat The Hugoniostat is an approach to simulate shock-waves in DFT through a pseudo-ensemble which drives the temperature and pressure to the point on the Hugoniot line. Two Hugoniotstat methods are implemented. The constant volume Hugoniostat (NVHug) of Maillet et al. 1 and the constant pressure/stress Hugoniostat of Ravelo et al. 2 . The NVHug and NPHug algorithms are a form of pseudo-ensemble which means that the do not strictly conserve a formal quantity, but drive the system into a desired state. The algorithms are implemented as other CASTEP ensembles and use many of the common MD keywords and can function with with any of the standard CASTEP thermostat methods (see basics ). Details of extended Hugoniostat methods can be found in the PhD thesis 3 where the methods were initially implemented in CASTEP. Hugoniot Equation of State The Hugoniot describes the shocked state of the system \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} where subscript 1 1 and 2 2 refer to the states ahead and behind the shock-front, \\rho{} \\rho{} is the mass density of the fluid, u u is the fluid velocity, P P is the pressure and h h is the specific enthalpy (per unit mass). It can also be formulated in terms of the shock speed: \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) where u_{s} u_{s} is the shock speed and e e is the specific internal energy. Using substitutions of the mass conservation & momentum conservation into the energy conservation it is possible to derive the Hugoniot equation: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), which in the per-unit-mass basis gives us: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), NVHug The NVHug method performs a static cell calculation at a compression ratio of md_hug_compression in the direction specified by md_hug_dir (by default ISO tropic). The equations of motion that govern NVHug are (in the Nose-Hoover formulation): \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), where \\chi{} \\chi{} is the heat-flow of the thermostat into the system, \\nu{} \\nu{} is the coupling between the thermostat and the system, C C is a scaling constant in units of energy to conserve system size independence and E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) where t_{0} t_{0} is the time before the system has been compressed (i.e. the equilibrium state), we deem the deviation of our current state from the Hugoniot state the Hugoniot estimator: E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). Example .param task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NVHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 md_hug_compression : 0.7 NPHug The equations of motion that govern the NPHug Hugoniostat (in the Nose-Hoover formulation) are: \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), where \\alpha{} \\alpha{} refers to an element in the direction of a cell-vector \\vec{h} \\vec{h} , \\nu{}_{H} \\nu{}_{H} is the coupling of the thermostat to the system, \\nu{}_{P}{} \\nu{}_{P}{} is the coupling of the barostat piston to the system, \\sigma{} \\sigma{} is the target pressure tensor and P P is the instantaneous total pressure tensor, D D is a scaling constant in units of pressure to conserve system size independence, Ravelo et al . 2 suggest the equilibrium bulk modulus ( B_{0} B_{0} ) . Example .param task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NPHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 .cell ... %block external_pressure GPa 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 10.0 %endblock external_pressure Accelerated Equilibration Due to the nature of plane-wave density functional theory (DFT) calculations and the way in which the forces are calculated, DFT can be very susceptible to rapid changes in structure and can become unstable at extremely high temperatures, and if atoms become close enough the fundamental assumptions of non-polarisability of core electrons becomes invalid in DFT. DFT is also expensive to calculate compared to the empirical force-fields, and so wasting as little calculation as possible is essential. The accelerated equilibration methods exist to make the process of computing shockwaves faster and more robust. Damping Ravelo et al . 2 suggested applying damping to the \"velocity\" of the thermo-/barostats preventing the over-shoot of the ideal Hugeoniot values. This makes the thermostat NVHug formulation: \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, and similarly for the update equation of motion of the NPHug formulation: \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, where \\beta{}_{H} \\beta{}_{H} and \\beta{}_{p} \\beta{}_{p} are user-defined damping coefficients for the heat-flow and barostat piston respectively, chosen to bring about critical damping to the Hugoniot state. Related Keywords beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs Examples %block devel_code md: BETA_T=0.1 BETA_H=0.1 :endmd # Lightly Damped md: BETA_T=0.3 BETA_H=0.3 :endmd # Damped %enblock devel_code Effects of the damping on the Langevin scheme (Eq. 4.2) on a 500- atom Lennard-Jones cell at 60% volume with an overly strong Hugoniostat coupling ( \\nu{}_{H} \\nu{}_{H} ) of 0.1fs^{\u22121} 0.1fs^{\u22121} and a damping factor ( \\beta{}_{H} \\beta{}_{H} ) of (Undamped) 0.0, (Lightly Damped) 0.1, (Damped) 0.3. Quenching Quenching is a more extreme version of damping where upon the \"acceleration\" of the thermo-/barostat changing sign, the \"velocity\" is reset to 0. Because this is not directly coupled to the system this does not damage the internal dynamics of the system and can lead to faster convergence and more stable temperatures. Particularly in the initial phases of NVHug where upon initial compression temperatures and pressures can spike. Quenching only takes place during the equilibration phase as determined by md_eqm_t Related Keywords quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat velocity upon changing direction for rapid equilibration Examples %block devel_code md: QUENCH_T=T :endmd # Quench Thermostat md: QUENCH_P=T :endmd # Quench Barostat %enblock devel_code The effects of quenching on the temperature of a 70% volume 500-atom Lennard-Jones system, unquenched line (black) shows a large tran- sient initially, the quenched lines (blue and green) show the elimination of this transient at the expense of \u201cunphysical\u201d temperature dynamics, which are eliminated when the quenching is turned off (blue) after equilibration. It should be noted that all three converge to the same temperature. Steady compression Steady compression spreads the system compression in NVHug compression over a period of time rather than compressing instantaneously to allow the system to equilibrate more steadily and avoid transient temperature and pressure spikes. This was also proposed in Ravelo et al . 2 as a means of smoothing equilibration. k-points and wavefunction samples are determined from the compressed cell so that the NVHug can be more efficient for the majority of the run. compression_t and compression_rate are two different ways of specifying the same thing either as %/fs or fs/% . When the compression has reached the target compression the compression will stop. For steady compression, it is generally best to compress the system for slightly less time than the equilibration period to ensure that the system is in a valid steady state before measuring data. compression_block gives the system time to equilibrate between compressions by compressing every compression_block steps rather than every step (though the compression at each compression step will be larger s.t. compression_rate and compression_t are preserved). Relevant Keywords compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure. Examples md_eqm_t: 600fs %block devel_code md: compression_t=400 :endmd %enblock devel_code Effect of steady compression on reducing initial transients during equilibration. Predictor-corrector (Experimental) Due to the nature of DFT, where a lot of important properties (e.g. wavefunctions) are tied to the simulation cell, it is generally more efficient to use a fixed-cell calculation in order to reduce the computational expense of recalculating all the properties which are related to the cell. This means that using NVHug is generally more efficient in CASTEP, however, we are usually more interested in sampling particular pressures on the Hugoniot rather than the effect of a given compression. The predictor-corrector attempts to mitigate these issues by using past measures on the Hugoniot curve to automatically trace out the Hugoniot curve up to a given pressure with a series of NVHug simulations. It uses the previous hist_len points to fit a curve and predict what compression would give the target pressure and run it. Tracing out the Hugoniot to target_p in either steps steps or steps of size pstep . E.g. pc: target_p=10 steps=2 :endpc Will target 5 and 10GPa pc: target_p=10 pstep=2 :endpc will target 2, 4, 6, 8 and 10GPa err determines how close the actual pressure must be to the target to be accepted, relative to the actual target. E.g. pc: target_p=10 err=0.1 :endpc Will accept any calculation whose final Hugoniot P P is between 9-11GPa as complete and move to the next target. The reuse keyword causes the P-C to use the final state of the previous step as the initial state of the current. Including temperature/pressure and atomic positions to speed up the equilibration process. max_delta limits the compression step the P-C can take between stages to ensure that initial steps, where estimates are limited by lack of datapoints, in very stiff materials do not result in extreme temperature or pressure jumps where fundamental assumptions of DFT may break down and cause the system to fail. Related Keywords pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's final state as the next steps initial state. max_delta : (Physical) Maximum attempted compression step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep Examples PC: PC=T TARGET_P=1.0 STEPS=2 METHOD='LIN' AV_METHOD='RUNAV' :ENDPC Keywords Summary Param Keywords md_ensemble : Should be set to HUG to use Hugoniostat methods. md_hug_method : (NONE, NVHUG, NPHUG) Hugoniostat method. (default: NONE) md_hug_dir : (XDIR, YDIR, ZDIR, ISO) Hugoniostat compression direction. (default: ISO) md_hug_t : (Physical) Hugoniostat coupling constant. md_hug_compression : (Physical) Hugoniostat compression ratio \\frac{V}{V_{0}} \\frac{V}{V_{0}} . Values from 0.0 to 1.0 (default) Devel Code Parameters MD Block chem_pot : (Physical) Manually specify total chemical potential (scaling factor) in eV Equilibration Acceleration quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat upon changing direction for rapid equilibration eqm_hug_t : (Physical) Hugoniostat coupling during equilibration phase in 1/fs beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure. Running Averages ra_len : (Integer) Number of running average steps to use in calculating final Hugoniot av_method : (CUMAV, RUNAV, DIRCT, FINAL) Method for computing Hugoniot to dump to .hug file. Initial States ma_init_t : (Logical) Use Maillet hugoniostat temperature estimator as initial temperature. init_eta : (Physical) Initial \\eta{} \\eta{} (cell compression velocity) for NPHug in \\tfrac{A}{fs} \\tfrac{A}{fs} . temp_init : (Physical) Initial temperature to be used for each hug stage (overriding md_temperature each stage in P-C) in K K . PC Block pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's temperature as initial temperature rather than md_temperature max_delta : (Physical) Maximum attempted pressure step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep J.-B. Maillet, M. Mareschal, L. Soulard, R. Ravelo, P. S. Lomdahl, T. C. Germann, and B. L. Holian. Uniaxial hugoniostat: a method for atomistic simulations of shocked materials. Phys. Rev. E , 63:016121, Dec 2000. doi:10.1103/PhysRevE.63.016121 . \u21a9 R. Ravelo, B. L. Holian, T. C. Germann, and P. S. Lomdahl. Constant-stress hugoniostat method for following the dynamical evolution of shocked matter. Phys. Rev. B , 70:014103, Jul 2004. doi:10.1103/PhysRevB.70.014103 . \u21a9 \u21a9 \u21a9 \u21a9 Jacob Wilkins. Exploration of approaches to shock-wave simulations . PhD thesis, University of York, July 2019. URL: https://etheses.whiterose.ac.uk/24444/ . \u21a9","title":"Hugoniostat"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#hugoniostat","text":"The Hugoniostat is an approach to simulate shock-waves in DFT through a pseudo-ensemble which drives the temperature and pressure to the point on the Hugoniot line. Two Hugoniotstat methods are implemented. The constant volume Hugoniostat (NVHug) of Maillet et al. 1 and the constant pressure/stress Hugoniostat of Ravelo et al. 2 . The NVHug and NPHug algorithms are a form of pseudo-ensemble which means that the do not strictly conserve a formal quantity, but drive the system into a desired state. The algorithms are implemented as other CASTEP ensembles and use many of the common MD keywords and can function with with any of the standard CASTEP thermostat methods (see basics ). Details of extended Hugoniostat methods can be found in the PhD thesis 3 where the methods were initially implemented in CASTEP.","title":"Hugoniostat"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#hugoniot-equation-of-state","text":"The Hugoniot describes the shocked state of the system \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} where subscript 1 1 and 2 2 refer to the states ahead and behind the shock-front, \\rho{} \\rho{} is the mass density of the fluid, u u is the fluid velocity, P P is the pressure and h h is the specific enthalpy (per unit mass). It can also be formulated in terms of the shock speed: \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) where u_{s} u_{s} is the shock speed and e e is the specific internal energy. Using substitutions of the mass conservation & momentum conservation into the energy conservation it is possible to derive the Hugoniot equation: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), which in the per-unit-mass basis gives us: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}),","title":"Hugoniot Equation of State"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#nvhug","text":"The NVHug method performs a static cell calculation at a compression ratio of md_hug_compression in the direction specified by md_hug_dir (by default ISO tropic). The equations of motion that govern NVHug are (in the Nose-Hoover formulation): \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), where \\chi{} \\chi{} is the heat-flow of the thermostat into the system, \\nu{} \\nu{} is the coupling between the thermostat and the system, C C is a scaling constant in units of energy to conserve system size independence and E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) where t_{0} t_{0} is the time before the system has been compressed (i.e. the equilibrium state), we deem the deviation of our current state from the Hugoniot state the Hugoniot estimator: E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)).","title":"NVHug"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#example","text":"","title":"Example"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param","text":"task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NVHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 md_hug_compression : 0.7","title":".param"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#nphug","text":"The equations of motion that govern the NPHug Hugoniostat (in the Nose-Hoover formulation) are: \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), where \\alpha{} \\alpha{} refers to an element in the direction of a cell-vector \\vec{h} \\vec{h} , \\nu{}_{H} \\nu{}_{H} is the coupling of the thermostat to the system, \\nu{}_{P}{} \\nu{}_{P}{} is the coupling of the barostat piston to the system, \\sigma{} \\sigma{} is the target pressure tensor and P P is the instantaneous total pressure tensor, D D is a scaling constant in units of pressure to conserve system size independence, Ravelo et al . 2 suggest the equilibrium bulk modulus ( B_{0} B_{0} ) .","title":"NPHug"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#example_1","text":"","title":"Example"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param_1","text":"task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NPHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000","title":".param"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#cell","text":"... %block external_pressure GPa 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 10.0 %endblock external_pressure","title":".cell"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#accelerated-equilibration","text":"Due to the nature of plane-wave density functional theory (DFT) calculations and the way in which the forces are calculated, DFT can be very susceptible to rapid changes in structure and can become unstable at extremely high temperatures, and if atoms become close enough the fundamental assumptions of non-polarisability of core electrons becomes invalid in DFT. DFT is also expensive to calculate compared to the empirical force-fields, and so wasting as little calculation as possible is essential. The accelerated equilibration methods exist to make the process of computing shockwaves faster and more robust.","title":"Accelerated Equilibration"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#damping","text":"Ravelo et al . 2 suggested applying damping to the \"velocity\" of the thermo-/barostats preventing the over-shoot of the ideal Hugeoniot values. This makes the thermostat NVHug formulation: \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, and similarly for the update equation of motion of the NPHug formulation: \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, where \\beta{}_{H} \\beta{}_{H} and \\beta{}_{p} \\beta{}_{p} are user-defined damping coefficients for the heat-flow and barostat piston respectively, chosen to bring about critical damping to the Hugoniot state.","title":"Damping"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords","text":"beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples","text":"%block devel_code md: BETA_T=0.1 BETA_H=0.1 :endmd # Lightly Damped md: BETA_T=0.3 BETA_H=0.3 :endmd # Damped %enblock devel_code Effects of the damping on the Langevin scheme (Eq. 4.2) on a 500- atom Lennard-Jones cell at 60% volume with an overly strong Hugoniostat coupling ( \\nu{}_{H} \\nu{}_{H} ) of 0.1fs^{\u22121} 0.1fs^{\u22121} and a damping factor ( \\beta{}_{H} \\beta{}_{H} ) of (Undamped) 0.0, (Lightly Damped) 0.1, (Damped) 0.3.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#quenching","text":"Quenching is a more extreme version of damping where upon the \"acceleration\" of the thermo-/barostat changing sign, the \"velocity\" is reset to 0. Because this is not directly coupled to the system this does not damage the internal dynamics of the system and can lead to faster convergence and more stable temperatures. Particularly in the initial phases of NVHug where upon initial compression temperatures and pressures can spike. Quenching only takes place during the equilibration phase as determined by md_eqm_t","title":"Quenching"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords_1","text":"quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat velocity upon changing direction for rapid equilibration","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_1","text":"%block devel_code md: QUENCH_T=T :endmd # Quench Thermostat md: QUENCH_P=T :endmd # Quench Barostat %enblock devel_code The effects of quenching on the temperature of a 70% volume 500-atom Lennard-Jones system, unquenched line (black) shows a large tran- sient initially, the quenched lines (blue and green) show the elimination of this transient at the expense of \u201cunphysical\u201d temperature dynamics, which are eliminated when the quenching is turned off (blue) after equilibration. It should be noted that all three converge to the same temperature.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#steady-compression","text":"Steady compression spreads the system compression in NVHug compression over a period of time rather than compressing instantaneously to allow the system to equilibrate more steadily and avoid transient temperature and pressure spikes. This was also proposed in Ravelo et al . 2 as a means of smoothing equilibration. k-points and wavefunction samples are determined from the compressed cell so that the NVHug can be more efficient for the majority of the run. compression_t and compression_rate are two different ways of specifying the same thing either as %/fs or fs/% . When the compression has reached the target compression the compression will stop. For steady compression, it is generally best to compress the system for slightly less time than the equilibration period to ensure that the system is in a valid steady state before measuring data. compression_block gives the system time to equilibrate between compressions by compressing every compression_block steps rather than every step (though the compression at each compression step will be larger s.t. compression_rate and compression_t are preserved).","title":"Steady compression"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#relevant-keywords","text":"compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure.","title":"Relevant Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_2","text":"md_eqm_t: 600fs %block devel_code md: compression_t=400 :endmd %enblock devel_code Effect of steady compression on reducing initial transients during equilibration.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#predictor-corrector-experimental","text":"Due to the nature of DFT, where a lot of important properties (e.g. wavefunctions) are tied to the simulation cell, it is generally more efficient to use a fixed-cell calculation in order to reduce the computational expense of recalculating all the properties which are related to the cell. This means that using NVHug is generally more efficient in CASTEP, however, we are usually more interested in sampling particular pressures on the Hugoniot rather than the effect of a given compression. The predictor-corrector attempts to mitigate these issues by using past measures on the Hugoniot curve to automatically trace out the Hugoniot curve up to a given pressure with a series of NVHug simulations. It uses the previous hist_len points to fit a curve and predict what compression would give the target pressure and run it. Tracing out the Hugoniot to target_p in either steps steps or steps of size pstep . E.g. pc: target_p=10 steps=2 :endpc Will target 5 and 10GPa pc: target_p=10 pstep=2 :endpc will target 2, 4, 6, 8 and 10GPa err determines how close the actual pressure must be to the target to be accepted, relative to the actual target. E.g. pc: target_p=10 err=0.1 :endpc Will accept any calculation whose final Hugoniot P P is between 9-11GPa as complete and move to the next target. The reuse keyword causes the P-C to use the final state of the previous step as the initial state of the current. Including temperature/pressure and atomic positions to speed up the equilibration process. max_delta limits the compression step the P-C can take between stages to ensure that initial steps, where estimates are limited by lack of datapoints, in very stiff materials do not result in extreme temperature or pressure jumps where fundamental assumptions of DFT may break down and cause the system to fail.","title":"Predictor-corrector (Experimental)"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords_2","text":"pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's final state as the next steps initial state. max_delta : (Physical) Maximum attempted compression step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_3","text":"PC: PC=T TARGET_P=1.0 STEPS=2 METHOD='LIN' AV_METHOD='RUNAV' :ENDPC","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#keywords-summary","text":"","title":"Keywords Summary"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param-keywords","text":"md_ensemble : Should be set to HUG to use Hugoniostat methods. md_hug_method : (NONE, NVHUG, NPHUG) Hugoniostat method. (default: NONE) md_hug_dir : (XDIR, YDIR, ZDIR, ISO) Hugoniostat compression direction. (default: ISO) md_hug_t : (Physical) Hugoniostat coupling constant. md_hug_compression : (Physical) Hugoniostat compression ratio \\frac{V}{V_{0}} \\frac{V}{V_{0}} . Values from 0.0 to 1.0 (default)","title":"Param Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#devel-code-parameters","text":"","title":"Devel Code Parameters"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#md-block","text":"chem_pot : (Physical) Manually specify total chemical potential (scaling factor) in eV","title":"MD Block"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#equilibration-acceleration","text":"quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat upon changing direction for rapid equilibration eqm_hug_t : (Physical) Hugoniostat coupling during equilibration phase in 1/fs beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure.","title":"Equilibration Acceleration"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#running-averages","text":"ra_len : (Integer) Number of running average steps to use in calculating final Hugoniot av_method : (CUMAV, RUNAV, DIRCT, FINAL) Method for computing Hugoniot to dump to .hug file.","title":"Running Averages"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#initial-states","text":"ma_init_t : (Logical) Use Maillet hugoniostat temperature estimator as initial temperature. init_eta : (Physical) Initial \\eta{} \\eta{} (cell compression velocity) for NPHug in \\tfrac{A}{fs} \\tfrac{A}{fs} . temp_init : (Physical) Initial temperature to be used for each hug stage (overriding md_temperature each stage in P-C) in K K .","title":"Initial States"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#pc-block","text":"pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's temperature as initial temperature rather than md_temperature max_delta : (Physical) Maximum attempted pressure step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep J.-B. Maillet, M. Mareschal, L. Soulard, R. Ravelo, P. S. Lomdahl, T. C. Germann, and B. L. Holian. Uniaxial hugoniostat: a method for atomistic simulations of shocked materials. Phys. Rev. E , 63:016121, Dec 2000. doi:10.1103/PhysRevE.63.016121 . \u21a9 R. Ravelo, B. L. Holian, T. C. Germann, and P. S. Lomdahl. Constant-stress hugoniostat method for following the dynamical evolution of shocked matter. Phys. Rev. B , 70:014103, Jul 2004. doi:10.1103/PhysRevB.70.014103 . \u21a9 \u21a9 \u21a9 \u21a9 Jacob Wilkins. Exploration of approaches to shock-wave simulations . PhD thesis, University of York, July 2019. URL: https://etheses.whiterose.ac.uk/24444/ . \u21a9","title":"PC Block"},{"location":"documentation/Molecular_Dynamics/keywords/","text":"To perform a molecular dynamics calculation set the task parameter task : md To control the length of the dynamics simulation md_num_iter : number of MD steps (default 100) md_delta_t : MD timestep (default 1fs) To control the conditions for the dynamics md_ensemble : Ensemble (NVE, NVT, NPH, NPT, HUG) md_thermostat : Thermostat to use if not a constant energy ensemble. values: NOSE-HOOVER (default), LANGEVIN, HOOVER-LANGEVIN md_barostat : Barostat to use if not a constant volume ensemble. Values: ANDERSEN-HOOVER (default), PARRINELLO-RAHMAN md_temperature : Temperature to use if not a constant energy ensemble For the Hugoniot Thermostat md_hug_method : Hugoniostat method. Values: NONE (default), NVHUG, NPHUG md_hug_dir : Hugoniostat compression direction. Values: XDIR, YDIR, ZDIR, ISO (default) md_hug_t : Hugoniostat coupling constant. md_hug_compression : Hugoniostat compression ratio. Values from 0.0 to 1.0 (default) Path Integral MD (PIMD) MD_USE_PATHINT PIMD on/off MD_NUM_BEADS PIMD number of beads MD_PATHINT_INIT PIMD initialisation method MD_PATHINT_STAGING PIMD staging modes on/off MD_PATHINT_NUM_STAGES PIMD number of stages Advanced settings It is possible to change the tolerances for accepting the SCF groundstate during the molecular dynamics run. The default value are those for a single point energy e.g. the default for md_elec_energy_tol is the value of elec_energy_tol md_elec_energy_tol : MD total energy per atom convergence tolerance md_elec_eigenvalue_tol : MD eigenvalue convergence tolerance md_elec_force_tol : max force per atom convergence tolerance md_elec_convergence_win : MD convergence tolerance window MD_EQM_METHOD MD enhanced equilibration method MD_EQM_ION_T MD equilibration time for ions MD_EQM_CELL_T MD equilibration time for cell MD_EQM_T MD equilibration time MD_ION_T MD characteristic ionic time MD_CELL_T MD characteristic cell time MD_CELL_DAMP_RINGING Damp cell ringing mode MD_USE_PLUMED Use PLUMED metadynamics","title":"MD Keywords"},{"location":"documentation/Molecular_Dynamics/keywords/#path-integral-md-pimd","text":"MD_USE_PATHINT PIMD on/off MD_NUM_BEADS PIMD number of beads MD_PATHINT_INIT PIMD initialisation method MD_PATHINT_STAGING PIMD staging modes on/off MD_PATHINT_NUM_STAGES PIMD number of stages","title":"Path Integral MD (PIMD)"},{"location":"documentation/Molecular_Dynamics/keywords/#advanced-settings","text":"It is possible to change the tolerances for accepting the SCF groundstate during the molecular dynamics run. The default value are those for a single point energy e.g. the default for md_elec_energy_tol is the value of elec_energy_tol md_elec_energy_tol : MD total energy per atom convergence tolerance md_elec_eigenvalue_tol : MD eigenvalue convergence tolerance md_elec_force_tol : max force per atom convergence tolerance md_elec_convergence_win : MD convergence tolerance window MD_EQM_METHOD MD enhanced equilibration method MD_EQM_ION_T MD equilibration time for ions MD_EQM_CELL_T MD equilibration time for cell MD_EQM_T MD equilibration time MD_ION_T MD characteristic ionic time MD_CELL_T MD characteristic cell time MD_CELL_DAMP_RINGING Damp cell ringing mode MD_USE_PLUMED Use PLUMED metadynamics","title":"Advanced settings"},{"location":"documentation/Molecular_Dynamics/overview/","text":"Instead of using the forces to optimise the structure of the system, CASTEP can instead use the forces to accelerate the atoms (and cell-shape) in order to simulate dynamical properties - a method known as \"Molecular Dynamics\" or simply \"MD\". To perform this kind of calculation, set task : MD in your param file. CASTEP has a wide range of Molecular Dynamics (MD) capabilities, and can do equilibrium MD using a variety of ensembles: NVE - the microcanonical ensemble - with fixed number of atoms, volume of cell, and total energy conserved NVT - the canonical ensemble - with constant temperature not constant energy - due to the application of a thermostat NPH - constant external pressure and enthalpy - due to the application of a barostat NPT - constant external pressure and temperature - due to the application of a barostat and a thermostat HUG - the Hugoniostat - a special thermo-barostat algorithm to find states on the Hugoniot curve Of these, NPT is the closest to most real-life experiments. Of the different thermostats, CASTEP supports Nose-Hoover, Nose-Hoover chains, Langevin and Hoover-Langevin. Of the different barostats, CASTEP supports the isotropic Andersen-Hoover barostat, and the anisotropic Parrinello-Rahman barostat. CASTEP also supports the Berendsen thermostat and barostat, as a route to faster equilibration before switching to one of the above thermostats/barostats for production data. As well as generating different classical ensembles, CASTEP can also generate a state on the Hugoniot using the Hugoniostat algorithm. In fact, CASTEP can generate multiple sets of points on the Hugoniot curve in a single calculation. CASTEP can also go beyond the Born-Oppenheimer approximation to do quantum dynamics, using Path Integral Molecular Dynamics (PIMD), in either NVT or NPT ensembles, using the Langevin thermostat. In all MD schemes, CASTEP can support both linear and non-linear constraints on the ionic positions and/or on the cell vectors. The detailed trajectory information is written to a .md file, which is a structured text file (similar to the .geom file), for ease of manipulation and post-calculation analysis.","title":"MD Overview"},{"location":"documentation/Molecular_Dynamics/pimd/","text":"For some systems, with light atoms and/or at low temperatures, the zero-point motion of the atom (rather than the electrons) can become significant. This requires a level of theory beyond the Born-Oppenheimer approximation, which assuming that the nuclei can be treated as classical point charges. One way of doing this, is the Feynman Path Integral approach to quantum mechanics, and using the isomorphism of a ring of classical \"beads and springs\" to represent a quantum particle. This approach is combined with MD to generate an ensemble of configurations, and so the approach is known as Path Integral Molecular Dynamics (PIMD). With this approach, quantum expectation values can be calculated by trajectory averages. Hence classical MD analysis techniques can be used to generate quantum values. Keywords PIMD is a form of MD, and so all the usual MD keywords apply. NB the only supported md_thermostat is Langevin but this works with all values of md_barostat . To activate PIMD, the key variables are: md_use_pathint : true md_num_beads : 2 which turns on PIMD and 2 beads. It is important to note that the number of beads is an extra convergence parameter - the discretized ring becomes a continuous path integral in the limit that the number of beads tends to infinity. In practice, this is usually 2 -- 128 for light atoms (e.g. hydrogen) at temperatures > 10K. For lower temperatures, the number of beads goes up significantly. num_farms : 2 This is an important way to parallelize a PIMD calculation. With task farming, each bead can be assigned to a farm, so the number of farms should be either 1 (no farming) or md_num_beads . Then the PIMD calculation can be run in parallel on num_farms blocks of processors, where the number of processors in each block is determined by the usual CASTEP+DFT parallelization strategies (k-points, g-vectors, bands etc). More advanced keywords are: md_pathint_init : point / Gaussian md_pathint_staging : true This determines how the initial beads positions for a given atom are assigned. 'point' puts all the beads at the same point, whilst 'Gaussian' uses a Gaussian spreading function, which is analyticaly correct for a free particle to estimate the delocalization at the given temperature. The staging mode transformation is a key way to eliminate the natural harmonics in the dynamics of the ring of beads, which would otherwise significantly reduce the time step required, particularly at low temperatures. Output files When doing a PIMD calculation, there is md_num_beads times more information generated! Hence if using farming, then only the centroid position of and velocity etc of each ring of beads (corresponding to the classical position of each atom) is output to the .castep file. The coordinate data for each value of imaginary time (the cyclic index labelling the beads for each atom) is written to individual farmXXX.castep where XXX is the farm number. If not farming, then all this data is written to the single .castep file. The size of each ring for each atom at each real timestep is analysed in terms of the 'radius of gyration' tensor, and the 3 RGY eigenvalues and corresponding eigenvectors are also output to the master .castep file. In addition, there are beadXXX.md files produced, one per imaginary time value (number of beads). These can be used for different MD analysis techniques, and can also be merged using scripts such as pimerge.pl to put all the bead data for each value of real time into the same file, which can be useful for visualization of the bead dynamics. Working with i-pi i-pi is a 3 rd -party python package for doing PIMD. This needs other codes, such as CASTEP, to generate the forces for a given configuration, and can then do different forms of PIMD, including centroid PIMD, which is not natively supported by CASTEP. i-pi communicates to CASTEP via internet sockets. The support for this is built into CASTEP from v22 or later. There is an example of running i-pi with CASTEP in the examples/castep directory, along with a 'run_me' script that launches the i-pi server, creates a set of sub-directories (one per bead), and then launches the separate CASTEP clients. If doing PIMD in this mode, then you do not set PIMD variables in the .param file but rather in an i-pi input.xml file. The CASTEP .param file keywords needed are: task : socketdriver socket_port: 31415 socket_host: localhost where the task tells CASTEP to communicate with i-pi on socket_port (in this case, it is sent the bead coordinates and returns the energy and forces). The socket_host can be localhost, or an internet host, if running on a remote server. For more information, see the i-pi website .","title":"PIMD"},{"location":"documentation/Molecular_Dynamics/pimd/#keywords","text":"PIMD is a form of MD, and so all the usual MD keywords apply. NB the only supported md_thermostat is Langevin but this works with all values of md_barostat . To activate PIMD, the key variables are: md_use_pathint : true md_num_beads : 2 which turns on PIMD and 2 beads. It is important to note that the number of beads is an extra convergence parameter - the discretized ring becomes a continuous path integral in the limit that the number of beads tends to infinity. In practice, this is usually 2 -- 128 for light atoms (e.g. hydrogen) at temperatures > 10K. For lower temperatures, the number of beads goes up significantly. num_farms : 2 This is an important way to parallelize a PIMD calculation. With task farming, each bead can be assigned to a farm, so the number of farms should be either 1 (no farming) or md_num_beads . Then the PIMD calculation can be run in parallel on num_farms blocks of processors, where the number of processors in each block is determined by the usual CASTEP+DFT parallelization strategies (k-points, g-vectors, bands etc). More advanced keywords are: md_pathint_init : point / Gaussian md_pathint_staging : true This determines how the initial beads positions for a given atom are assigned. 'point' puts all the beads at the same point, whilst 'Gaussian' uses a Gaussian spreading function, which is analyticaly correct for a free particle to estimate the delocalization at the given temperature. The staging mode transformation is a key way to eliminate the natural harmonics in the dynamics of the ring of beads, which would otherwise significantly reduce the time step required, particularly at low temperatures.","title":"Keywords"},{"location":"documentation/Molecular_Dynamics/pimd/#output-files","text":"When doing a PIMD calculation, there is md_num_beads times more information generated! Hence if using farming, then only the centroid position of and velocity etc of each ring of beads (corresponding to the classical position of each atom) is output to the .castep file. The coordinate data for each value of imaginary time (the cyclic index labelling the beads for each atom) is written to individual farmXXX.castep where XXX is the farm number. If not farming, then all this data is written to the single .castep file. The size of each ring for each atom at each real timestep is analysed in terms of the 'radius of gyration' tensor, and the 3 RGY eigenvalues and corresponding eigenvectors are also output to the master .castep file. In addition, there are beadXXX.md files produced, one per imaginary time value (number of beads). These can be used for different MD analysis techniques, and can also be merged using scripts such as pimerge.pl to put all the bead data for each value of real time into the same file, which can be useful for visualization of the bead dynamics.","title":"Output files"},{"location":"documentation/Molecular_Dynamics/pimd/#working-with-i-pi","text":"i-pi is a 3 rd -party python package for doing PIMD. This needs other codes, such as CASTEP, to generate the forces for a given configuration, and can then do different forms of PIMD, including centroid PIMD, which is not natively supported by CASTEP. i-pi communicates to CASTEP via internet sockets. The support for this is built into CASTEP from v22 or later. There is an example of running i-pi with CASTEP in the examples/castep directory, along with a 'run_me' script that launches the i-pi server, creates a set of sub-directories (one per bead), and then launches the separate CASTEP clients. If doing PIMD in this mode, then you do not set PIMD variables in the .param file but rather in an i-pi input.xml file. The CASTEP .param file keywords needed are: task : socketdriver socket_port: 31415 socket_host: localhost where the task tells CASTEP to communicate with i-pi on socket_port (in this case, it is sent the bead coordinates and returns the energy and forces). The socket_host can be localhost, or an internet host, if running on a remote server. For more information, see the i-pi website .","title":"Working with i-pi"},{"location":"documentation/Molecular_Dynamics/restarts/","text":"Check-pointing, Continuation and Parameter Changes As with any other calculation in CASTEP, checkpoint files are written at regular intervals. Should the calculation be interrupted for whatever reason, it is possible to continue from the point at which the checkpoint file was last written. Check-pointing is performed by dumping all pertinent data to a .check file. The interval at which this check-pointing occurs can be controlled in two ways. The first option is to specify the number of md steps between checkpoints. num_backup_iter = 5 Alternatively, the wall-clock time (in seconds) between backups can be specified with: backup_interval = 60 Both can be specified but backup_interval will be preferred over num_backup_iter if both are set. To disable either option, set the corresponding parameter to zero. The name of the checkpoint file will be the calculation seed-name followed by \".check\". This can be overridden with: checkpoint = my_md_run.check To continue an MD calculation from a checkpoint file, ensure that the .check file, the .castep file and the .md file from the previous run are present in the current directory. If the seed-name of the new run is the same as for the old, the command continuation = default will suffice. To continue the run from a checkpoint file my_md_run.check use: continuation = my_md_run.check Note the standard CASTEP behaviour is to append new data to the end of existing files (such as .castep and .md) to avoid loosing data from earlier runs. This is not the case for the .check file, which is overwritten with new data. For this reason, the default CASTEP behaviour is to make a backup of the .check file, before over-writing it, so as to minimize the risk of data loss. Changing Parameters on Continuation Check-pointing is particularly useful for MD calculations where we often require many thousands of time-steps to extract useful information. Another important benefit is the ability to halt a calculation, and continue from a checkpoint with a revised set of MD parameters. For example one may wish to alter the target thermostat temperature, or the cell relaxation time without having to restart the run from the unequilibrated configuration. All options described in the above sections can be changed on a restart, i.e. it is possible to change ensemble, thermostat and barostat schemes, relaxation times, time-step, constraints, etc. by specifying new values in the input files for the new run. It is not possible to change the number of atoms/electrons in the cell upon a restart. Care must be taken when changing parameters on a restart. For example a large discontinuous change in the specified temperature or pressure will perturb a system away from equilibrium. In such cases the system should not be sampled until re-equilibrated. Although it is possible to change electronic minimisation schemes/parameters on a restart, this is somewhat unwise for obvious reasons. On-The-Fly Parameter Changes In fact, molecular dynamics parameters can be changed without having to halt the calculation at all! At the end of each MD step, the parameters file is re-read. Any parameters in this file which differ from those currently in use will be updated before the next MD step commences. It is therefore possible to alter the state of a running calculation by simply making changes to the parameters file while the calculation is running. The same considerations/restrictions which apply to changing parameters on a restart apply to these on the fly changes.","title":"MD Restarts"},{"location":"documentation/Molecular_Dynamics/restarts/#check-pointing-continuation-and-parameter-changes","text":"As with any other calculation in CASTEP, checkpoint files are written at regular intervals. Should the calculation be interrupted for whatever reason, it is possible to continue from the point at which the checkpoint file was last written. Check-pointing is performed by dumping all pertinent data to a .check file. The interval at which this check-pointing occurs can be controlled in two ways. The first option is to specify the number of md steps between checkpoints. num_backup_iter = 5 Alternatively, the wall-clock time (in seconds) between backups can be specified with: backup_interval = 60 Both can be specified but backup_interval will be preferred over num_backup_iter if both are set. To disable either option, set the corresponding parameter to zero. The name of the checkpoint file will be the calculation seed-name followed by \".check\". This can be overridden with: checkpoint = my_md_run.check To continue an MD calculation from a checkpoint file, ensure that the .check file, the .castep file and the .md file from the previous run are present in the current directory. If the seed-name of the new run is the same as for the old, the command continuation = default will suffice. To continue the run from a checkpoint file my_md_run.check use: continuation = my_md_run.check Note the standard CASTEP behaviour is to append new data to the end of existing files (such as .castep and .md) to avoid loosing data from earlier runs. This is not the case for the .check file, which is overwritten with new data. For this reason, the default CASTEP behaviour is to make a backup of the .check file, before over-writing it, so as to minimize the risk of data loss.","title":"Check-pointing, Continuation and Parameter Changes"},{"location":"documentation/Molecular_Dynamics/restarts/#changing-parameters-on-continuation","text":"Check-pointing is particularly useful for MD calculations where we often require many thousands of time-steps to extract useful information. Another important benefit is the ability to halt a calculation, and continue from a checkpoint with a revised set of MD parameters. For example one may wish to alter the target thermostat temperature, or the cell relaxation time without having to restart the run from the unequilibrated configuration. All options described in the above sections can be changed on a restart, i.e. it is possible to change ensemble, thermostat and barostat schemes, relaxation times, time-step, constraints, etc. by specifying new values in the input files for the new run. It is not possible to change the number of atoms/electrons in the cell upon a restart. Care must be taken when changing parameters on a restart. For example a large discontinuous change in the specified temperature or pressure will perturb a system away from equilibrium. In such cases the system should not be sampled until re-equilibrated. Although it is possible to change electronic minimisation schemes/parameters on a restart, this is somewhat unwise for obvious reasons.","title":"Changing Parameters on Continuation"},{"location":"documentation/Molecular_Dynamics/restarts/#on-the-fly-parameter-changes","text":"In fact, molecular dynamics parameters can be changed without having to halt the calculation at all! At the end of each MD step, the parameters file is re-read. Any parameters in this file which differ from those currently in use will be updated before the next MD step commences. It is therefore possible to alter the state of a running calculation by simply making changes to the parameters file while the calculation is running. The same considerations/restrictions which apply to changing parameters on a restart apply to these on the fly changes.","title":"On-The-Fly Parameter Changes"},{"location":"documentation/Molecular_Dynamics/tools/","text":"JMol can read a .md file and animate the motion of the atoms. See the tutorials for examples of more tools for MD.","title":"MD Tools"},{"location":"documentation/NMR/NMR_overview/","text":"Diamagnetic Insulators By a diamagnetic insulator we mean a system with an electronic gap between its highest occupied state and lowest unoccupied state, and all of the electronic spins are paired, simple examples are diamond, quartz, glycine\u2026 This class of materials is the most suitable for calculations as the main NMR interactions, magnetic sielding, J-coupling and electric field gradients can all be computed. Magnetic Shielding In a diamagnetic insulator this arises from orbital currents induced by an external magnetic field. This current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , produces a non-uniform induced magnetic field in the material, which is given by the Biot-Savart law as {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. The shielding tensor is defined as the ratio between this induced field, and the external applied field {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. It can thus be seen that the question of computing the shielding tensor is that of computing the induced electronic current. J-coupling The J-coupling is a small perturbation to the electronic ground-state of the system and we can identify it as a derivative of the total energy E, of the system {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} An equivalent expression arises from considering one nuclear spin (L) as perturbation which creates a magnetic field at a second (receiving) nucleus (K) {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. Eqn.~\\ref{eq:J} tells us that the question of computing J is essentially that of computing the magnetic field induced indirectly by a nuclear magnetic moment. When spin-orbit coupling is neglected we can consider the field as arising from two, essentially independent, mechanisms. Firstly, the magnetic moment can interact with electronic charge inducing an orbital current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , which in turn creates a magnetic field at the other nuclei in the system. This mechanism is similar to the case of magnetic shielding in insulators. The second mechanism arises from the interaction of the magnetic moment with the electronic spin, causing an electronic spin polarisation. By working to first order in these quantities we can write the magnetic field at atom {\\rm K} {\\rm K} induced by the magnetic moment of atom {\\rm L} {\\rm L} as {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. Several quantum chemistry packages provide the ability to compute J coupling tensors in molecular systems (see Helgaker et al . 1 } for a review of methods). An approach to compute J tensors within the planewave-pseudopotential approach has recently been developed 2 . EFG For a nucleus with spin > > \u00bd the NMR response will include an interaction between the quadrupole moment of the nucleus, Q, and the electric field gradient (EFG) generated by the surrounding electronic structure. The EFG is a second rank, symmetric, traceless tensor G({\\bf r}) G({\\bf r}) given by G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} where \\alpha,\\beta,\\gamma \\alpha,\\beta,\\gamma denote the Cartesian coordinates x,y,z and E_{\\alpha}({\\bf r}) E_{\\alpha}({\\bf r}) is the local electric field at the position {\\bf r} {\\bf r} , which can be calculated from the charge density n({\\bf r}) n({\\bf r}) : \\begin{equation} E_{\\alpha}({\\bf r})=\\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3} (r_{\\alpha}-r_{\\alpha}'). \\end{equation} The EFG tensor is then equal to \\begin{equation}\\label{eq:efg_rs} G_{\\alpha\\beta}({\\bf r}) = \\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3}\\left[ \\delta_{\\alpha\\beta} -3 \\frac{(r_{\\alpha}-r_{\\alpha}')(r_{\\beta}-r_{\\beta}')}{|{\\bf r}-{\\bf r}'|^2}\\right]. \\end{equation} The computation of electric field gradient tensors is less demanding than either shielding or J-coupling tensors as it requires only knowledge of the electronic ground state. The LAPW approach in its implementation within the Wien series of codes 3 has been widely used and shown to reliably predict Electric Field Gradient (EFG) tensors 4 . The equivalent formalism for the planewave/PAW approach is reported in Profeta et al . 5 . The quadrupolar coupling constant, C _Q _Q and the asymmetry parameter, \\eta_Q \\eta_Q can be obtained from the the diagonalized electric field gradient tensor whose eigenvalues are labelled V _{xx} _{xx} , V _{yy} _{yy} , V _{zz} _{zz} , such that |V_{zz}|>|V_{yy}|>|V_{xx}| |V_{zz}|>|V_{yy}|>|V_{xx}| : \\begin{equation} C_{Q}=\\frac{eV_{zz}Q}{h}, \\end{equation} where h is Planck's constant and \\begin{equation} \\eta_Q=\\frac{V_{xx}-V_{yy}}{V_{zz}}. \\end{equation} Trygve Helgaker, Micha\u0142 Jaszu\u0144ski, and Magdalena Pecul. The quantum-chemical calculation of nmr indirect spin\u2013spin coupling constants. Progress in Nuclear Magnetic Resonance Spectroscopy , 53(4):249\u2013268, 2008. doi:10.1016/j.pnmrs.2008.02.002 . \u21a9 Si\u00e2n A. Joyce, Jonathan R. Yates, Chris J. Pickard, and Francesco Mauri. A first principles theory of nuclear magnetic resonance J-coupling in solid-state systems. The Journal of Chemical Physics , 127(20):204107, 11 2007. doi:10.1063/1.2801984 . \u21a9 P. Blaha, K. Schwarz, P. Sorantin, and S.B. Trickey. Full-potential, linearized augmented plane wave programs for crystalline systems. Computer Physics Communications , 59(2):399\u2013415, 1990. doi:10.1016/0010-4655(90)90187-6 . \u21a9 P. Blaha, P. Sorantin, C. Ambrosch, and K. Schwarz. Calculation of the electric field gradient tensor from energy band structures. Hyperfine Interactions , 51(1):917\u2013923, Jun 1989. doi:10.1007/BF02407802 . \u21a9 Mickael Profeta, Francesco Mauri, and Chris J. Pickard. Accurate first principles prediction of 17O NMR parameters in SiO2: assignment of the zeolite ferrierite spectrum. Journal of the American Chemical Society , 125(2):541\u2013548, 2003. PMID: 12517169. doi:10.1021/ja027124r . \u21a9","title":"NMR Overview"},{"location":"documentation/NMR/NMR_overview/#diamagnetic-insulators","text":"By a diamagnetic insulator we mean a system with an electronic gap between its highest occupied state and lowest unoccupied state, and all of the electronic spins are paired, simple examples are diamond, quartz, glycine\u2026 This class of materials is the most suitable for calculations as the main NMR interactions, magnetic sielding, J-coupling and electric field gradients can all be computed.","title":"Diamagnetic Insulators"},{"location":"documentation/NMR/NMR_overview/#magnetic-shielding","text":"In a diamagnetic insulator this arises from orbital currents induced by an external magnetic field. This current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , produces a non-uniform induced magnetic field in the material, which is given by the Biot-Savart law as {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. The shielding tensor is defined as the ratio between this induced field, and the external applied field {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. It can thus be seen that the question of computing the shielding tensor is that of computing the induced electronic current.","title":"Magnetic Shielding"},{"location":"documentation/NMR/NMR_overview/#j-coupling","text":"The J-coupling is a small perturbation to the electronic ground-state of the system and we can identify it as a derivative of the total energy E, of the system {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} An equivalent expression arises from considering one nuclear spin (L) as perturbation which creates a magnetic field at a second (receiving) nucleus (K) {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. Eqn.~\\ref{eq:J} tells us that the question of computing J is essentially that of computing the magnetic field induced indirectly by a nuclear magnetic moment. When spin-orbit coupling is neglected we can consider the field as arising from two, essentially independent, mechanisms. Firstly, the magnetic moment can interact with electronic charge inducing an orbital current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , which in turn creates a magnetic field at the other nuclei in the system. This mechanism is similar to the case of magnetic shielding in insulators. The second mechanism arises from the interaction of the magnetic moment with the electronic spin, causing an electronic spin polarisation. By working to first order in these quantities we can write the magnetic field at atom {\\rm K} {\\rm K} induced by the magnetic moment of atom {\\rm L} {\\rm L} as {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. Several quantum chemistry packages provide the ability to compute J coupling tensors in molecular systems (see Helgaker et al . 1 } for a review of methods). An approach to compute J tensors within the planewave-pseudopotential approach has recently been developed 2 .","title":"J-coupling"},{"location":"documentation/NMR/NMR_overview/#efg","text":"For a nucleus with spin > > \u00bd the NMR response will include an interaction between the quadrupole moment of the nucleus, Q, and the electric field gradient (EFG) generated by the surrounding electronic structure. The EFG is a second rank, symmetric, traceless tensor G({\\bf r}) G({\\bf r}) given by G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} where \\alpha,\\beta,\\gamma \\alpha,\\beta,\\gamma denote the Cartesian coordinates x,y,z and E_{\\alpha}({\\bf r}) E_{\\alpha}({\\bf r}) is the local electric field at the position {\\bf r} {\\bf r} , which can be calculated from the charge density n({\\bf r}) n({\\bf r}) : \\begin{equation} E_{\\alpha}({\\bf r})=\\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3} (r_{\\alpha}-r_{\\alpha}'). \\end{equation} The EFG tensor is then equal to \\begin{equation}\\label{eq:efg_rs} G_{\\alpha\\beta}({\\bf r}) = \\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3}\\left[ \\delta_{\\alpha\\beta} -3 \\frac{(r_{\\alpha}-r_{\\alpha}')(r_{\\beta}-r_{\\beta}')}{|{\\bf r}-{\\bf r}'|^2}\\right]. \\end{equation} The computation of electric field gradient tensors is less demanding than either shielding or J-coupling tensors as it requires only knowledge of the electronic ground state. The LAPW approach in its implementation within the Wien series of codes 3 has been widely used and shown to reliably predict Electric Field Gradient (EFG) tensors 4 . The equivalent formalism for the planewave/PAW approach is reported in Profeta et al . 5 . The quadrupolar coupling constant, C _Q _Q and the asymmetry parameter, \\eta_Q \\eta_Q can be obtained from the the diagonalized electric field gradient tensor whose eigenvalues are labelled V _{xx} _{xx} , V _{yy} _{yy} , V _{zz} _{zz} , such that |V_{zz}|>|V_{yy}|>|V_{xx}| |V_{zz}|>|V_{yy}|>|V_{xx}| : \\begin{equation} C_{Q}=\\frac{eV_{zz}Q}{h}, \\end{equation} where h is Planck's constant and \\begin{equation} \\eta_Q=\\frac{V_{xx}-V_{yy}}{V_{zz}}. \\end{equation} Trygve Helgaker, Micha\u0142 Jaszu\u0144ski, and Magdalena Pecul. The quantum-chemical calculation of nmr indirect spin\u2013spin coupling constants. Progress in Nuclear Magnetic Resonance Spectroscopy , 53(4):249\u2013268, 2008. doi:10.1016/j.pnmrs.2008.02.002 . \u21a9 Si\u00e2n A. Joyce, Jonathan R. Yates, Chris J. Pickard, and Francesco Mauri. A first principles theory of nuclear magnetic resonance J-coupling in solid-state systems. The Journal of Chemical Physics , 127(20):204107, 11 2007. doi:10.1063/1.2801984 . \u21a9 P. Blaha, K. Schwarz, P. Sorantin, and S.B. Trickey. Full-potential, linearized augmented plane wave programs for crystalline systems. Computer Physics Communications , 59(2):399\u2013415, 1990. doi:10.1016/0010-4655(90)90187-6 . \u21a9 P. Blaha, P. Sorantin, C. Ambrosch, and K. Schwarz. Calculation of the electric field gradient tensor from energy band structures. Hyperfine Interactions , 51(1):917\u2013923, Jun 1989. doi:10.1007/BF02407802 . \u21a9 Mickael Profeta, Francesco Mauri, and Chris J. Pickard. Accurate first principles prediction of 17O NMR parameters in SiO2: assignment of the zeolite ferrierite spectrum. Journal of the American Chemical Society , 125(2):541\u2013548, 2003. PMID: 12517169. doi:10.1021/ja027124r . \u21a9","title":"EFG"},{"location":"documentation/Output_Files/output_files/","text":"CASTEP writes output data in a variety of files. Some of these will be in human readable ASCII format (i.e. plaintext) and can be read with commands such as less or more on linux, or with a simple text editor (textedit, notepad etc). Other files will be in binary format and are designed to be read or processed with an external program. See Tools for software and libraries to read and analyse them. Groundstate .castep ASCII. CASTEP's main outputfile. .bib ASCII. Bibtex file containing citations to the methods CASTEP has used in the calculation. .check Binary. This checkpoint file contains the results of the calculation including the groundstate charge density and wavefunctions. It is typically a very large file. Will be read by CASTEP when performing a continuation calculation. Also read by postprocessing software such as c2x or euphonic. .check_bak Binary. backup of the checkpoint file. .castep_bin Binary. This file is identical to .check except that does not contain the wavefunctions. Therefore it is usually much smaller than the .check file, making it suitable for archiving a calculation. It may also be processed by euphonic, c2x or other software which can read checkpoint file. .cst_esp Binary. The local part of the Kohn-Sham potential (Vloc + Hartree + XC). .usp ASCII. Pseudoptential data, written for each species. See the page on reading usp headers . .uspso ASCII. Pseudoptential data, written for each species. This is the J-dependant version of the .usp . See the page on reading usp headers . .beta Xmgrace (.agr) format. Beta projectors for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .pwave Xmgrace (.agr) format. Pseudo-wavefunctions for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .econv Xmgrace (.agr) format. Isolated atom energy cutoff convergence for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .bands ASCII. Kohn-Sham eigenvalues at the requested k-points. Can be used to plot band structures or density of states. Note that the eigenvalues are given in atomic units (Hartree). .den_fmt ASCII. Charge density. Only written if write_formatted_density : T . .pot_fmt ASCII. Groundstate local potential (Vloc + Hartree + XC) (See .cst_esp ). Only written if write_formatted_potential : T . .chdiff Binary. Difference between the groundstate charge density and a superposition of atomic densities. Only written if calculate_densdiff : T .chdiff_fmt ASCII. same data as .chdiff in human readable format. Only written if calculate_densdiff : T and write_formatted_density : T . .xrd_sf ASCII. X-ray structure factors. See the documentation page . .elf Binary. Result of ELF calculation. .elf_fmt ASCII. Result of ELF calculation.Only written if write_formatted_elf : T . Geometry Optimisation *.geom ASCII. State of the system (coordinates, unit cell etc) at each step of the geometry optimisation. See for specification. Can be used to animate the geometry optimisation and can be read directly by Jmol. Molecular Dynamics *.md ASCII. State of the system (coordinates, unit cell etc) at each step of the molecular dynamics simulation. Same format as the .geom file. See for specification. Can be used to animate the trajectory, and can be read directly by Jmol. *.hug ASCII. Hugoniot data for hugoniostat MD. Spectral .pdos_bin Binary. Matrix elements used for plotting a projected density of states. Used by Optados. .ome_bin Binary. Matrix elements used for calculating optical properties. Used by Optados. .dome_bin Binary. Diagonal elements of the optical matrix elements. Used by Optados to plot densities of states / spectral properties using adaptive smearing. .elnes_bin Binary. Matrix elements used for plotting the core-loss spectrum. Used by Optados. .orbitals Binary. Kohn-Sham states at each kpoints. Used by orbital2bands to make a reorganised .bands file for a cleaner looking bandstructure. Phonon and Efield .phonon ASCII. Phonon eigenvalues and eigenvectors. .phonon_dos ASCII. Phonon branch gradients and density-of-states when param keyword phonon_calculate_dos is true. .efield ASCII. Mode oscillator strengths and frequency-dependent permittivity tensor in the ir band. Electron-Phonon coupling .epme ASCII. Electron-phonon matrix elements. .epme_bin Binary. Electron-phonon matrix elements. Elastic Constants .elastic ASCII. Elastic constants, compliance matrix, Frozen ion constants, Internal Strain and Piezoelectric tensors TDDFT .tddft ASCII. TDDFT state band projection analysis and TDDFT excitation energies. Magres .magres ASCII. Contain the NMR tensors (depending on magres_task shielding, EFG or J). Read by MagresView or the Soprano python libraries. _current.dat ASCII. Written if MAGRES_WRITE_RESPONSE=True . Used to compute NICS (nucleus independent chemical shifts) see https://www.ccpnc.ac.uk/docs/nics . Transition state search .ts ASCII. See the specification in the documentation pages .","title":"Output Files"},{"location":"documentation/Output_Files/output_files/#groundstate","text":".castep ASCII. CASTEP's main outputfile. .bib ASCII. Bibtex file containing citations to the methods CASTEP has used in the calculation. .check Binary. This checkpoint file contains the results of the calculation including the groundstate charge density and wavefunctions. It is typically a very large file. Will be read by CASTEP when performing a continuation calculation. Also read by postprocessing software such as c2x or euphonic. .check_bak Binary. backup of the checkpoint file. .castep_bin Binary. This file is identical to .check except that does not contain the wavefunctions. Therefore it is usually much smaller than the .check file, making it suitable for archiving a calculation. It may also be processed by euphonic, c2x or other software which can read checkpoint file. .cst_esp Binary. The local part of the Kohn-Sham potential (Vloc + Hartree + XC). .usp ASCII. Pseudoptential data, written for each species. See the page on reading usp headers . .uspso ASCII. Pseudoptential data, written for each species. This is the J-dependant version of the .usp . See the page on reading usp headers . .beta Xmgrace (.agr) format. Beta projectors for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .pwave Xmgrace (.agr) format. Pseudo-wavefunctions for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .econv Xmgrace (.agr) format. Isolated atom energy cutoff convergence for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .bands ASCII. Kohn-Sham eigenvalues at the requested k-points. Can be used to plot band structures or density of states. Note that the eigenvalues are given in atomic units (Hartree). .den_fmt ASCII. Charge density. Only written if write_formatted_density : T . .pot_fmt ASCII. Groundstate local potential (Vloc + Hartree + XC) (See .cst_esp ). Only written if write_formatted_potential : T . .chdiff Binary. Difference between the groundstate charge density and a superposition of atomic densities. Only written if calculate_densdiff : T .chdiff_fmt ASCII. same data as .chdiff in human readable format. Only written if calculate_densdiff : T and write_formatted_density : T . .xrd_sf ASCII. X-ray structure factors. See the documentation page . .elf Binary. Result of ELF calculation. .elf_fmt ASCII. Result of ELF calculation.Only written if write_formatted_elf : T .","title":"Groundstate"},{"location":"documentation/Output_Files/output_files/#geometry-optimisation","text":"*.geom ASCII. State of the system (coordinates, unit cell etc) at each step of the geometry optimisation. See for specification. Can be used to animate the geometry optimisation and can be read directly by Jmol.","title":"Geometry Optimisation"},{"location":"documentation/Output_Files/output_files/#molecular-dynamics","text":"*.md ASCII. State of the system (coordinates, unit cell etc) at each step of the molecular dynamics simulation. Same format as the .geom file. See for specification. Can be used to animate the trajectory, and can be read directly by Jmol. *.hug ASCII. Hugoniot data for hugoniostat MD.","title":"Molecular Dynamics"},{"location":"documentation/Output_Files/output_files/#spectral","text":".pdos_bin Binary. Matrix elements used for plotting a projected density of states. Used by Optados. .ome_bin Binary. Matrix elements used for calculating optical properties. Used by Optados. .dome_bin Binary. Diagonal elements of the optical matrix elements. Used by Optados to plot densities of states / spectral properties using adaptive smearing. .elnes_bin Binary. Matrix elements used for plotting the core-loss spectrum. Used by Optados. .orbitals Binary. Kohn-Sham states at each kpoints. Used by orbital2bands to make a reorganised .bands file for a cleaner looking bandstructure.","title":"Spectral"},{"location":"documentation/Output_Files/output_files/#phonon-and-efield","text":".phonon ASCII. Phonon eigenvalues and eigenvectors. .phonon_dos ASCII. Phonon branch gradients and density-of-states when param keyword phonon_calculate_dos is true. .efield ASCII. Mode oscillator strengths and frequency-dependent permittivity tensor in the ir band.","title":"Phonon and Efield"},{"location":"documentation/Output_Files/output_files/#electron-phonon-coupling","text":".epme ASCII. Electron-phonon matrix elements. .epme_bin Binary. Electron-phonon matrix elements.","title":"Electron-Phonon coupling"},{"location":"documentation/Output_Files/output_files/#elastic-constants","text":".elastic ASCII. Elastic constants, compliance matrix, Frozen ion constants, Internal Strain and Piezoelectric tensors","title":"Elastic Constants"},{"location":"documentation/Output_Files/output_files/#tddft","text":".tddft ASCII. TDDFT state band projection analysis and TDDFT excitation energies.","title":"TDDFT"},{"location":"documentation/Output_Files/output_files/#magres","text":".magres ASCII. Contain the NMR tensors (depending on magres_task shielding, EFG or J). Read by MagresView or the Soprano python libraries. _current.dat ASCII. Written if MAGRES_WRITE_RESPONSE=True . Used to compute NICS (nucleus independent chemical shifts) see https://www.ccpnc.ac.uk/docs/nics .","title":"Magres"},{"location":"documentation/Output_Files/output_files/#transition-state-search","text":".ts ASCII. See the specification in the documentation pages .","title":"Transition state search"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/","text":"Molecular vibrational calculations CASTEP is primarily a solid state code with periodic boundary conditions, and is not necessarily the first choice for performing vibrational spectroscopy calculations on molecules. Nevertheless it can sometimes be convenient to use it in this mode (for example, if it is desired to compare a molecular crystal with an isolated molecule at exactly the same level of theory). With certain limitations this can be done in CASTEP using the \u201cmolecule in large box\u201d method. The idea is to place the molecule in a vacuum by constructing a large supercell. If the supercell is sufficiently large that the periodic images of the molecule do not interact then the frequencies and eigenvectors in the molecular limit can be recovered. Because the zero charge density in a large volume must still be represented using a plane-wave basis sat, such calculations can become expensive, but it is nevertheless essential to perform careful cell size convergence tests. A molecule in free space possesses rotational as well as translational symmetry, which results in three (or two for a linear molecule) free librational modes of zero frequency. A periodic CASTEP calculation does not possess this symmetry and the librational mode frequencies will have nonzero values, either real and positive or imaginary. If a molecular electric field calculation is desired the parameter efield_ignore_molec_modes may be specified with the keyword value of MOLECULE or LINEAR_MOLECULE . This omits the 6 (or 5) lowest modes from the infra-red polarizability calculation, assuming them to be the librations. As with crystalline systems it is desirable to maximise the use of symmetry by optimally orienting the molecule. In this case an additional criterion applies - the simulation cell vectors should be organised for maximal compatibility with the molecular symmetry. Any incompatible symmetry operations will not be found if using the SYMMETRY_GENERATE keyword. For example a tetrahedral molecule is best modelled in a cubic cell with the 3-fold axes oriented along the cube diagonals. By contrast a hexagonal molecule such as benzene is better modelled using a hexagonal simulation cell with the molecule commensurately oriented. A limitation of this method is that CASTEP implements only the crystallographic point group symmetry operations, and does not include all of the molecular point groups. It is not always possible to take full advantage of molecular symmetry, and 5-fold rotation axes and icosahedral groups can not be represented. In such cases some degeneracies will be lifted and only approximately satisfied, and the group theoretical analysis of the eigenvectors will not be correct for the molecular point group. Finally, it is sometimes desirable to compute the vibrational spectrum of an ion rather than a neutral molecule. This adds a number of complications of different degrees of severity. First is the well-known result that semi-local DFT (LDA and GGA) severely underbinds anions, and the description of the molecular states in some systems may be substantially incorrect. Second, the introduction of a non-zero molecular charge in a periodic cell necessitates the addition of a compensating charge to avoid a divergent Coulomb energy. CASTEP implicitly adds a uniform charge distribution which integrates over the cell to the negative of the sum of ionic and electronic charge in the system. This model while effective, gives rise to additional electrostatic terms which decrease only as 1/L^{3} 1/L^{3} . Consequently it is impossible to completely converge such a calculation with respect to cell size. It is beyond the scope of this document to describe the techniques which may be used to recover the \u201cinfinite\u201d volume limit. The reader is referred to ref ( Leslie and Gillan 1985 ) and the extensive literature which cites this paper for further reading. An example of a successful approach involving an extrapolation of frequencies of a molecular anion to the infinite cell limit is given in Parker et al. ( Parker et al. 2006 ). Isotopic substitution calculations A powerful technique in experimental spectroscopy is isotopic substitution where the sample is modified by the substitution of a common isotope of some element by a heavier or lighter one. This can provide valuable site-specific spectroscopic information, particularly if the substitution can be performed in a site-specific manner. Force constants and dynamical matrices do not depend on nuclear mass, and are therefore one set of computations will suffice irrespective of isotopic substitution. The phonons tool (section [phonons-tool] ) allows recomputation of the frequencies for different isotopic substitutions without recomputing dynamical matrices. The simplest case is complete substitution. The new .cell file should contain a block specifying the new mass, e.g. %block SPECIES_MASS H 2.014101778 %endblock SPECIES_MASS Running the phonon code will compute the vibrational frequencies and eigenvectors for a completely deuterated sample. Slightly more complicated is the case where only one or a few of a number of sites is to be substituted. In that case the above prescription is inadequate as it would change all of the sites containing the species in question. It is therefore necessary to use CASTEP\u2019s sub-species labelling capabilities. For example the original cell containing a methane molecule might contain %block SPECIES_POT C C_00.recpot H H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS The continuation cell for input to phonons should contain %block SPECIES_POT C C_00.recpot H H_04.recpot H:D H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H:D 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS %block SPECIES_MASS H:D 2.014101778 H 1.007825032 C 12.0107 %endblock SPECIES_MASS The new atom label may contain any alphanumeric extension following the colon up to a maximum of 8 characters. This defines a new system with one hydrogen atom of a methane molecule replaced by deuterium. Notice that this has broken the initial symmetry of the cell. The phonons program generates a new system of reduced symmetry with three distinct atom types, and copies the dynamical matrix data from the original methane system from the .check file over to the corresponding atoms in the new system. It then diagonalises the dynamical matrix, applies whatever post-processing is specified and writes the frequencies and eigenvectors as usual. This straightforward approach fails to take into account isotopic shifts in bond lengths and geometry, and is therefore an approximate one. Since isotopic shifts in bond lengths depend in turn on the vibrational frequency, within the quasiharmionic approximation a self-consistent approach under which bond lengths and frequencies are simultaneously adjusted to self-consistency would be required. This would also require new DFPT electronic calculations at each stage and is beyond the scope of this utility. Constrained lattice dynamics It is sometimes desirable to compute the vibrational frequencies of a restricted region of an ab initio model. Consider the case of a molecule adsorbed on a surface. If only the frequencies of the molecular vibrations are needed it would be desirable to compute a subset of the modes were this possible. While it is not practical (as it would require prior knowledge of the eigenvectors of the full calculation), an alternative approach is to apply constraints to certain atoms. CASTEP implements a technique known as constrained lattice dynamics , also known as the partial hessian method. Nominated atoms are assumed to be \u201cfrozen\u201d, and the corresponding entries of the dynamical matrix are set to zero. The model is effectively one whereby the atoms in the region of the system deemed \u201cirrelevant\u201d are assigned a mass of infinity. It is not necessary to perform any computations for perturbation of these atoms, and a considerable saving of computational effort may be achieved. Frozen atoms are specified a CASTEP .cell file using the same syntax as applies to geometry operations. The block %block IONIC_CONSTRAINTS 1 Si 1 1 1 1 2 Si 2 1 1 1 3 C 4 1 1 1 %endblock IONIC_CONSTRAINTS constrains silicon atoms numbered 1-2 and C atom number 4 to be fixed. These do not move during geometry optimisation, and their perturbations are not considered during a lattice dynamics calculation. In fact the constrained lattice dynamics method does not make full use of the generality of CASTEP\u2019s linear constraints block (see for example the tutorial on MD at http://www.castep.org ) but only identifies atoms which are fully constrained not to move. As in the example above, there should be a single line for each atom which creates a uniquely numbered constraint. This should contain a \u201c1\u201d in all of the x, y, z positions. Except in rather specialised geometries the presence of fixed atom constraints is incompatible with most symmetry operations, and therefore symmetry should usually be turned off during a constrained lattice dynamics calculation. There is also an incompatibility with the acoustic sum rule (section [asr] ) as constraining the atoms breaks the translational invariance of the Hamiltonian. Acoustic sum rule correction is therefore disabled automatically if constraints are present.","title":"Advanced-Topics"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#sec:molecules","text":"CASTEP is primarily a solid state code with periodic boundary conditions, and is not necessarily the first choice for performing vibrational spectroscopy calculations on molecules. Nevertheless it can sometimes be convenient to use it in this mode (for example, if it is desired to compare a molecular crystal with an isolated molecule at exactly the same level of theory). With certain limitations this can be done in CASTEP using the \u201cmolecule in large box\u201d method. The idea is to place the molecule in a vacuum by constructing a large supercell. If the supercell is sufficiently large that the periodic images of the molecule do not interact then the frequencies and eigenvectors in the molecular limit can be recovered. Because the zero charge density in a large volume must still be represented using a plane-wave basis sat, such calculations can become expensive, but it is nevertheless essential to perform careful cell size convergence tests. A molecule in free space possesses rotational as well as translational symmetry, which results in three (or two for a linear molecule) free librational modes of zero frequency. A periodic CASTEP calculation does not possess this symmetry and the librational mode frequencies will have nonzero values, either real and positive or imaginary. If a molecular electric field calculation is desired the parameter efield_ignore_molec_modes may be specified with the keyword value of MOLECULE or LINEAR_MOLECULE . This omits the 6 (or 5) lowest modes from the infra-red polarizability calculation, assuming them to be the librations. As with crystalline systems it is desirable to maximise the use of symmetry by optimally orienting the molecule. In this case an additional criterion applies - the simulation cell vectors should be organised for maximal compatibility with the molecular symmetry. Any incompatible symmetry operations will not be found if using the SYMMETRY_GENERATE keyword. For example a tetrahedral molecule is best modelled in a cubic cell with the 3-fold axes oriented along the cube diagonals. By contrast a hexagonal molecule such as benzene is better modelled using a hexagonal simulation cell with the molecule commensurately oriented. A limitation of this method is that CASTEP implements only the crystallographic point group symmetry operations, and does not include all of the molecular point groups. It is not always possible to take full advantage of molecular symmetry, and 5-fold rotation axes and icosahedral groups can not be represented. In such cases some degeneracies will be lifted and only approximately satisfied, and the group theoretical analysis of the eigenvectors will not be correct for the molecular point group. Finally, it is sometimes desirable to compute the vibrational spectrum of an ion rather than a neutral molecule. This adds a number of complications of different degrees of severity. First is the well-known result that semi-local DFT (LDA and GGA) severely underbinds anions, and the description of the molecular states in some systems may be substantially incorrect. Second, the introduction of a non-zero molecular charge in a periodic cell necessitates the addition of a compensating charge to avoid a divergent Coulomb energy. CASTEP implicitly adds a uniform charge distribution which integrates over the cell to the negative of the sum of ionic and electronic charge in the system. This model while effective, gives rise to additional electrostatic terms which decrease only as 1/L^{3} 1/L^{3} . Consequently it is impossible to completely converge such a calculation with respect to cell size. It is beyond the scope of this document to describe the techniques which may be used to recover the \u201cinfinite\u201d volume limit. The reader is referred to ref ( Leslie and Gillan 1985 ) and the extensive literature which cites this paper for further reading. An example of a successful approach involving an extrapolation of frequencies of a molecular anion to the infinite cell limit is given in Parker et al. ( Parker et al. 2006 ).","title":"Molecular vibrational calculations"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#sec:isotopes","text":"A powerful technique in experimental spectroscopy is isotopic substitution where the sample is modified by the substitution of a common isotope of some element by a heavier or lighter one. This can provide valuable site-specific spectroscopic information, particularly if the substitution can be performed in a site-specific manner. Force constants and dynamical matrices do not depend on nuclear mass, and are therefore one set of computations will suffice irrespective of isotopic substitution. The phonons tool (section [phonons-tool] ) allows recomputation of the frequencies for different isotopic substitutions without recomputing dynamical matrices. The simplest case is complete substitution. The new .cell file should contain a block specifying the new mass, e.g. %block SPECIES_MASS H 2.014101778 %endblock SPECIES_MASS Running the phonon code will compute the vibrational frequencies and eigenvectors for a completely deuterated sample. Slightly more complicated is the case where only one or a few of a number of sites is to be substituted. In that case the above prescription is inadequate as it would change all of the sites containing the species in question. It is therefore necessary to use CASTEP\u2019s sub-species labelling capabilities. For example the original cell containing a methane molecule might contain %block SPECIES_POT C C_00.recpot H H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS The continuation cell for input to phonons should contain %block SPECIES_POT C C_00.recpot H H_04.recpot H:D H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H:D 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS %block SPECIES_MASS H:D 2.014101778 H 1.007825032 C 12.0107 %endblock SPECIES_MASS The new atom label may contain any alphanumeric extension following the colon up to a maximum of 8 characters. This defines a new system with one hydrogen atom of a methane molecule replaced by deuterium. Notice that this has broken the initial symmetry of the cell. The phonons program generates a new system of reduced symmetry with three distinct atom types, and copies the dynamical matrix data from the original methane system from the .check file over to the corresponding atoms in the new system. It then diagonalises the dynamical matrix, applies whatever post-processing is specified and writes the frequencies and eigenvectors as usual. This straightforward approach fails to take into account isotopic shifts in bond lengths and geometry, and is therefore an approximate one. Since isotopic shifts in bond lengths depend in turn on the vibrational frequency, within the quasiharmionic approximation a self-consistent approach under which bond lengths and frequencies are simultaneously adjusted to self-consistency would be required. This would also require new DFPT electronic calculations at each stage and is beyond the scope of this utility.","title":"Isotopic substitution calculations"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#constrained-lattice-dynamics","text":"It is sometimes desirable to compute the vibrational frequencies of a restricted region of an ab initio model. Consider the case of a molecule adsorbed on a surface. If only the frequencies of the molecular vibrations are needed it would be desirable to compute a subset of the modes were this possible. While it is not practical (as it would require prior knowledge of the eigenvectors of the full calculation), an alternative approach is to apply constraints to certain atoms. CASTEP implements a technique known as constrained lattice dynamics , also known as the partial hessian method. Nominated atoms are assumed to be \u201cfrozen\u201d, and the corresponding entries of the dynamical matrix are set to zero. The model is effectively one whereby the atoms in the region of the system deemed \u201cirrelevant\u201d are assigned a mass of infinity. It is not necessary to perform any computations for perturbation of these atoms, and a considerable saving of computational effort may be achieved. Frozen atoms are specified a CASTEP .cell file using the same syntax as applies to geometry operations. The block %block IONIC_CONSTRAINTS 1 Si 1 1 1 1 2 Si 2 1 1 1 3 C 4 1 1 1 %endblock IONIC_CONSTRAINTS constrains silicon atoms numbered 1-2 and C atom number 4 to be fixed. These do not move during geometry optimisation, and their perturbations are not considered during a lattice dynamics calculation. In fact the constrained lattice dynamics method does not make full use of the generality of CASTEP\u2019s linear constraints block (see for example the tutorial on MD at http://www.castep.org ) but only identifies atoms which are fully constrained not to move. As in the example above, there should be a single line for each atom which creates a uniquely numbered constraint. This should contain a \u201c1\u201d in all of the x, y, z positions. Except in rather specialised geometries the presence of fixed atom constraints is incompatible with most symmetry operations, and therefore symmetry should usually be turned off during a constrained lattice dynamics calculation. There is also an incompatibility with the acoustic sum rule (section [asr] ) as constraining the atoms breaks the translational invariance of the Hamiltonian. Acoustic sum rule correction is therefore disabled automatically if constraints are present.","title":"Constrained lattice dynamics"},{"location":"documentation/Phonons/Castep_Phonons/Bibliography/","text":"Ackland, G J, M C Warren, and S J Clark. 1997. \u201cPractical Methods in Ab Initio Lattice Dynamics.\u201d Journal of Physics: Condensed Matter 9 (37): 7861\u201372. http://stacks.iop.org/0953-8984/9/7861 . Balan, E., A. M. Saitta, F. Mauri, and G. Calas. 2001. \u201cFirst-Principles Modeling of the Infra-Red Spectrum of Kaolinite.\u201d American Mineralogist 86: 1321\u201330. https://doi.org/10.2138/am-2001-11-1201 . Baroni, Stefano, Stefano de Gironcoli, Andrea Dal Corso, and Paolo Giannozzi. 2001. \u201cPhonons and Related Crystal Properties from Density-Functional Perturbation Theory.\u201d Reviews of Modern Physics 73 (2): 515\u201362. https://doi.org/10.1103/RevModPhys.73.515 . Boyd, Robert W. 2003. Nonlinear Optics . San Diego, Calif.: Academic Press. http://www.myilibrary.com?id=105034 . Cheng, Y. Q., and A. J. Ramirez-Cuesta. 2020. \u201cCalculation of the Thermal Neutron Scattering Cross-Section of Solids Using OCLIMAX.\u201d J. Chem. Theory Comput. 16 (8): 5212\u201317. https://doi.org/10.1021/acs.jctc.0c00569 . Dove, Martin T. 1993. Introduction to Lattice Dynamics . Cambridge Topics in Mineral Physics and Chemistry. Cambridge University Press. https://doi.org/10.1017/CBO9780511619885 . Fair, R., A. Jackson, D. Voneshen, D. Jochym, D. Le, K. Refson, and T. Perring. 2022. \u201cEuphonic: Inelastic Neutron Scattering Simulations from Force Constants and Visualization Tools for Phonon Properties.\u201d J Appl Cryst 55 (6): 1689\u20131703. https://doi.org/10.1107/S1600576722009256 . Giannozzi, Paolo, Stefano de Gironcoli, Pasquale Pavone, and Stefano Baroni. 1991. \u201cAb Initio Calculation of Phonon Dispersions in Semiconductors.\u201d Phys. Rev. B 43 (9): 7231\u201342. https://doi.org/10.1103/PhysRevB.43.7231 . Gonze, Xavier. 1997. \u201cFirst-Principles Responses of Solids to Atomic Displacements and Homogeneous Electric Fields: Implementation of a Conjugate-Gradient Algorithm.\u201d Physical Review B 55 (16): 10377\u201354. https://doi.org/10.1103/PhysRevB.55.10337 . Gonze, Xavier, and Changyol Lee. 1997. \u201cDynamical Matrices, Born Effective Charges, Dielectric Permittivity Tensors, and Interatomic Force Constants from Density-Functional Perturbation Theory.\u201d Physical Review B 55 (16): 10355\u201368. https://doi.org/10.1103/PhysRevB.55.10355 . Kendrick, John, and Andrew D. Burnett. 2016. \u201cPDielec: The Calculation of Infrared and Terahertz Absorption for Powdered Crystals.\u201d Journal of Computational Chemistry 37 (16): 1491\u20131504. https://doi.org/10.1002/jcc.24344 . Kunc, K., and Richard M. Martin. 1982. \u201cAb Initio Force Constants of GaAs: A New Approach to Calculation of Phonons and Dielectric Properties.\u201d Phys. Rev. Lett. 48 (6): 406\u20139. https://doi.org/10.1103/PhysRevLett.48.406 . Leslie, M., and M. J. Gillan. 1985. \u201cThe Energy and Elastic Dipole Tensor of Defects in Ionic Crystals Calculated by the Supercell Method.\u201d Journal of Physics: Condensed Matter 18: 973\u201382. https://doi.org/10.1088/0022-3719/18/5/005 . Levine, Zachary H., and Douglas C. Allan. 1989. \u201cLinear Optical Response in Silicon and Germanium Including Self-Energy Effects.\u201d Phys. Rev. Lett. 63 (16): 1719\u201322. https://doi.org/10.1103/PhysRevLett.63.1719 . Lloyd-Williams, Jonathan H., and Bartomeu Monserrat. 2015. \u201cLattice Dynamics and Electron-Phonon Coupling Calculations Using Nondiagonal Supercells.\u201d Physical Review B 92 (18): 184301. https://doi.org/10.1103/PhysRevB.92.184301 . Maradudin, A. A., and G. K. Horton, eds. 1980. Dynamical Properties of Solids . Vol. 1\u20137. Elsevier. https://www.sciencedirect.com/bookseries/dynamical- properties-of-solids . Miwa, Kazutoshi. 2011. \u201cPrediction of Raman Spectra with Ultrasoft Pseudopotentials.\u201d Physical Review B 84 (9): 094304. https://doi.org/10.1103/PhysRevB.84.094304 . Pallikara, Ioanna, Prakriti Kayastha, Jonathan M Skelton, and Lucy D Whalley. 2022. \u201cThe Physical Significance of Imaginary Phonon Modes in Crystals.\u201d Electronic Structure 4 (3): 033002. https://doi.org/10.1088/2516-1075/ac78b3 . Parker, S. F., K. Refson, K. P. J. Williams, D. A. Braden, B. S. Hudson, and K. Yvon. 2006. \u201cSpectroscopic and Ab Initio Characterization of the ReH9(2-) Ion.\u201d Inorg. Chem. 45 (26): 10951\u201357. https://doi.org/10.1021/ic0611894 . Parlinski, K., Z. Q. Li, and Y. Kawazoe. 1997. \u201cFirst-Principles Determination of the Soft Mode in Cubic ZrO2 ZrO2 .\u201d Phys. Rev. Lett. 78 (21): 4063\u201366. https://doi.org/10.1103/PhysRevLett.78.4063 . Pick, R. M. Robert M. R. M. Robert M., Morrel H. Cohen, and Richard M. Martin. 1970. \u201cMicroscopic Theory of Force Constants in the Adiabatic Approximation.\u201d Physical Review B 1 (2): 910\u201320. https://doi.org/10.1103/PhysRevB.1.910 . Pickard, Chris J. 1997. \u201cAb Initio Electron Energy Loss Spectroscopy.\u201d PhD Thesis, University of Cambridge. https://www.tcm.phy.cam.ac.uk/~cjp20/old/thesis.ps.gz . Porezag, Dirk, and Mark R. Pederson. 1996. \u201cInfrared Intensities and Raman-Scattering Activities Within Density-Functional Theory.\u201d Phys. Rev. B 54 (11): 7830\u201336. https://doi.org/10.1103/PhysRevB.54.7830 . Probert, M. I. J., and M. C. Payne. 2003. \u201cImproving the Convergence of Defect Calculations in Supercells: An Ab Initio Study of the Neutral Silicon Vacancy.\u201d Phys. Rev. B 67 (7): 075204. https://doi.org/10.1103/PhysRevB.67.075204 . Ramirez-Cuesta, A. J. 2004. \u201caCLIMAX 4.0.1, the New Version of the Software for Analyzing and Interpreting INS Spectra.\u201d Computer Physics Communications 157 (3): 226\u201338. https://doi.org/10.1016/S0010-4655(03)00520-4 . Refson, Keith, P. R. Tulip, and Stewart J. Clark. 2006. \u201cVariational Density-Functional Perturbation Theory for Dielectrics and Lattice Dynamics.\u201d Physical Review B 73 (15): 155114. https://doi.org/10.1103/PhysRevB.73.155114 . Srivastava, G. P. 2023. The Physics of Phonons (2 nd Edition) . Taylor; Francis. https://doi.org/10.1201/9781003141273 . Yates, Jonathan R, Xinjie Wang, David Vanderbilt, and Ivo Souza. 2007. \u201cSpectral and Fermi Surface Properties from Wannier Interpolation.\u201d Physical Review B 75 (19): 195121. https://doi.org/10.1103/PhysRevB.75.195121 . Ye, Lin-Hui, Bang-Gui Liu, Ding-Sheng Wang, and Rushan Han. 2004. \u201cAb Initio Phonon Dispersions of Single-Wall Carbon Nanotubes.\u201d Phys. Rev. B 69 (23): 235409. https://doi.org/10.1103/PhysRevB.69.235409 .","title":"Bibliography"},{"location":"documentation/Phonons/Castep_Phonons/Dielectric-properties/","text":"Density functional perturbation theory is not limited to atomic displacement perturbations, and may also be used to calculate other response properties with respect to an electric field perturbation of an insulating system 1 . These are the dielectric permittivity \\epsilon_{\\alpha,\\beta}^{\\infty} = \\delta_{\\alpha,\\beta} - \\frac{4 \\pi}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, \\epsilon_{\\alpha,\\beta}^{\\infty} = \\delta_{\\alpha,\\beta} - \\frac{4 \\pi}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, the \u201cmolecular\u201d polarizability \\alpha_{\\alpha,\\beta}^{\\infty} = - \\frac{1}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, \\alpha_{\\alpha,\\beta}^{\\infty} = - \\frac{1}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, and the Born effective charges Z^{*}_{\\alpha,\\beta} = \\Omega \\frac{\\partial P_{\\beta}}{\\partial u_{\\kappa,\\alpha}} = \\frac{\\partial F_{\\kappa,\\alpha}}{\\partial \\varepsilon_{\\beta}} = \\frac{\\partial^2 E}{\\partial u_{\\kappa,\\alpha}\\partial \\varepsilon_{\\beta}} Z^{*}_{\\alpha,\\beta} = \\Omega \\frac{\\partial P_{\\beta}}{\\partial u_{\\kappa,\\alpha}} = \\frac{\\partial F_{\\kappa,\\alpha}}{\\partial \\varepsilon_{\\beta}} = \\frac{\\partial^2 E}{\\partial u_{\\kappa,\\alpha}\\partial \\varepsilon_{\\beta}} which play a strong role in lattice dynamics of crystals, and in particular governs the frequency-dependent dielectric response in the infra-red region ( Gonze and Lee 1997 ). An electric field response calculation is selected using the task keyword in the .param file. task : EFIELD which computes the optical frequency dielectric permittivity tensor and the low frequency (ionic lattice) response to a time-varying field in the regime of the phonon modes and the Born charges. Alternatively task : PHONON+EFIELD performs both dielectric and phonon tasks. The low and near-infrared frequency contributions to the permittivity and polarizability and the Born effective charges are printed to the .castep output file. An extract for the same Wurtzite BN calculation as earlier is shown in figure [efield-out] . An additional output file seedname .efield is also written and contains the frequency-dependent permittivity over the entire range, with a spacing determined by parameter efield_freq_spacing , and a Lorentzian broadening governed by a fixed Q Q , efield_oscillator_q . The low-frequency contribution of the phonons to the dielectric polarizability and permittivity is only well-defined when all mode frequencies are real and positive. In the presence of any imaginary mode or one of zero frequency the low-frequency dielectric and polarizability tensors are not calculated and are reported as \u201cinfinity\u201d. By default the three lowest frequency modes are assumed to be acoustic modes and not included in the calculation. To support molecule-in-supercell calculations, the parameter efield_ignore_molec_modes may be set to molecule , which excludes the 6 lowest frequency modes from the dielectric calculation. Allowed values are CRYSTAL , MOLECULE and LINEAR_MOLECULE which ignore 3, 6 and 5 modes respectively. In fact CASTEP usually performs an electric field response calculation even for a task : PHONON calculation because the permittivity tensor and Born charges are required to calculate the LO/TO splitting terms. Conversely a pure task : EFIELD calculation also performs a \\Gamma \\Gamma -point phonon calculation which is needed to compute the ionic contribution to the permittivity and polarizability. Consequently the only real difference between any of the tasks PHONON , EFIELD and PHONON+EFIELD lies in what is printed to the output file as the same computations are performed in each case. Only if one or other of those properties is specifically turned off with one of the parameters phonon_calc_lo_to_splitting : FALSE efield_calc_ion_permittivity : FALSE is a \u201cpure\u201d phonon or E-field calculation ever performed. It is well documented that the LDA tends to overestimate dielectric permittivities - by over 10% in the case of Si or Ge ( Levine and Allan 1989 ). It is possible to include an ad-hoc correction term to model the missing self-energy, by applying the so-called \u201cscissors operator\u201d, which consists of a rigid upshift of all conduction band states. This was incorporated into DFPT electric field response calculations by Gonze and Lee ( Gonze and Lee 1997 ). The parameters keyword excited_state_scissors 1.0 eV is used to model the effect of a 1 eV (in this example) upshift of conduction band states and will include the effects on dielectric permittivity and Born charges (but not phonons). The value to use must be determined from high-level calculations or empirically. =============================================================================== Optical Permittivity (f->infinity) DC Permittivity (f=0) ---------------------------------- --------------------- 4.50788 0.00000 0.00000 6.64363 0.00000 0.00000 0.00000 4.50788 0.00000 0.00000 6.64363 0.00000 0.00000 0.00000 4.63846 0.00000 0.00000 7.15660 =============================================================================== =============================================================================== Polarisabilities (A**3) Optical (f->infinity) Static (f=0) --------------------- ------------- 6.52844 0.00000 0.00000 10.50324 0.00000 0.00000 0.00000 6.52844 0.00000 0.00000 10.50324 0.00000 0.00000 0.00000 6.77146 0.00000 0.00000 11.45793 =============================================================================== =================================================== Born Effective Charges ---------------------- B 1 1.84636 0.00000 0.00000 0.00000 1.84636 0.00000 0.00000 0.00000 1.94523 B 2 1.84636 0.00000 0.00000 0.00000 1.84636 0.00000 0.00000 0.00000 1.94523 N 1 -1.85371 0.00000 0.00000 0.00000 -1.85371 0.00000 0.00000 0.00000 -1.94009 N 2 -1.85371 0.00000 0.00000 0.00000 -1.85371 0.00000 0.00000 0.00000 -1.94009 =================================================== Figure 6 Extract from the .castep output file generated from the hexagonal BN run of figure [example-gamma] , with task : EFIELD . The Born effective charges are laid out with the columns representing the X,Y,Z electric field directions and the rows the X,Y,Z displacement directions. Non-linear optical susceptibility In addition to the linear response properties calculated with task EFIELD or phonon+efield the non-linear dielectric susceptibility may be computed if the parameter efield_calculate_nonlinear : CHI2 is set. The calculation uses the \u201c2n+1 theorem\u201d extension of DFPT ( Baroni et al. 2001 ; Miwa 2011 ) to compute the static response, \\chi^{(2)} \\chi^{(2)} . The results are reported in the .castep file in reduced tensor form as the \u201cd-matrix\u201d ( Boyd 2003 ). See figure [nlo] . This is not activated by default, because it is substantially more expensive than a baseline E-field linear response calculation. (It requires the calculation of three sets of response functions with a full k-point set in P1 symmetry, even for crystals with higher, even cubic symmetry.) =========================================================================== Nonlinear Optical Susceptibility (pm/V) --------------------------------------- 1.13621 -1.13625 0.00001 0.00002 -7.73417 0.00002 0.00002 -0.00003 -0.00008 -7.73421 0.00002 -1.13625 -7.73417 -7.73421 -30.12197 -0.00008 0.00001 0.00002 =========================================================================== Figure 7 Nonlinear optical susceptibility \\chi^{(2)} \\chi^{(2)} expressed as a d-matrix for LiNbO3. Because the response of a metallic system to an applied field is the generation of a current flow, the dielectric permittivity diverges and the Born charges become zero. CASTEP will check that the system has a band gap before proceeding with an E-field response calculation and abort if there is none. \u21a9","title":"Dielectric-properties"},{"location":"documentation/Phonons/Castep_Phonons/Dielectric-properties/#sec:nlo","text":"In addition to the linear response properties calculated with task EFIELD or phonon+efield the non-linear dielectric susceptibility may be computed if the parameter efield_calculate_nonlinear : CHI2 is set. The calculation uses the \u201c2n+1 theorem\u201d extension of DFPT ( Baroni et al. 2001 ; Miwa 2011 ) to compute the static response, \\chi^{(2)} \\chi^{(2)} . The results are reported in the .castep file in reduced tensor form as the \u201cd-matrix\u201d ( Boyd 2003 ). See figure [nlo] . This is not activated by default, because it is substantially more expensive than a baseline E-field linear response calculation. (It requires the calculation of three sets of response functions with a full k-point set in P1 symmetry, even for crystals with higher, even cubic symmetry.) =========================================================================== Nonlinear Optical Susceptibility (pm/V) --------------------------------------- 1.13621 -1.13625 0.00001 0.00002 -7.73417 0.00002 0.00002 -0.00003 -0.00008 -7.73421 0.00002 -1.13625 -7.73417 -7.73421 -30.12197 -0.00008 0.00001 0.00002 =========================================================================== Figure 7 Nonlinear optical susceptibility \\chi^{(2)} \\chi^{(2)} expressed as a d-matrix for LiNbO3. Because the response of a metallic system to an applied field is the generation of a current flow, the dielectric permittivity diverges and the Born charges become zero. CASTEP will check that the system has a band gap before proceeding with an E-field response calculation and abort if there is none. \u21a9","title":"Non-linear optical susceptibility"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/","text":"This guide introduces the concepts, keywords and techniques needed to set up and run CASTEP calculations of lattice dynamics and vibrational spectroscopy. The material covers the various lattice-dynamical and related methods implemented in CASTEP, how to set up a calculation, and presents simple examples of the major types of calculation. It is assumed that the reader is familiar with the general CASTEP input and output files and keywords to the level which may be found at https://castep-docs.github.io/castep-docs/ . It describes how to analyse the results and generate graphical output using the CASTEP tools, but does not cover the modelling of IR, Raman or inelastic neutron or X-ray spectra, which are large subjects and beyond the scope of this document. It does not describe the compilation and installation of CASTEP and its tools, nor does it describe the operational details of invoking and running CASTEP. Computational clusters, HPC computing environments and batch systems vary to a considerable degree, and the reader is referred to their cluster or computer centre documentation. It does discuss general aspects of managing and running large phonon calculations including restarts and parallelism in section [large-calculations] . There are many useful textbooks on the theory of vibrations in crystals, or lattice dynamics as the subject is usually known. A good beginner\u2019s guide is \u201cIntroduction to Lattice Dynamics\u201d by Martin Dove ( Dove 1993 ). More advanced texts are available by Srivistava ( Srivastava 2023 ), Maradudin ( Maradudin and Horton 1980 ) and many others. The following section presents only a brief summary to introduce the notation. Theory of Lattice Dynamics Consider a crystal with a unit cell containing N N atoms, labelled \\kappa \\kappa , and a a labels the primitive cells in the lattice. The crystal is initially in mechanical equilibrium, with Cartesian co-ordinates R_{{\\kappa,\\alpha}} R_{{\\kappa,\\alpha}} , ( \\alpha=1..3 \\alpha=1..3 denotes the Cartesian x x , y y or z z direction). {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} denotes the displacement of an atom from its equilibrium position. Harmonic lattice dynamics is based on a Taylor expansion of total energy about structural equilibrium co-ordinates. E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... where {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} is the vector of atomic displacements from equilibrium and {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} is the matrix of force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. At equilibrium the forces F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} are all zero so the first-order term vanishes. In the Harmonic Approximation the 3 ^{\\text{rd}} ^{\\text{rd}} and higher order terms are neglected 1 . Assume Born von Karman periodic boundary conditions and substitute a plane-wave trial solution {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) with a phonon wavevector {\\mathbf{q}} {\\mathbf{q}} and a polarization vector {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} . This yields an eigenvalue equation {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . The dynamical matrix is defined as {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} where the index a a runs over all lattice images of the primitive cell. That is, the dynamical matrix is the mass-reduced Fourier transform of the force constant matrix. The eigenvalue equation [dmat-eigen] can be solved by standard numerical methods. The eigenvalues, \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 , must be real numbers because {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} is a Hermitian matrix. The vibrational frequencies at each mode \\omega_{m,{\\mathbf{q}}} \\omega_{m,{\\mathbf{q}}} are obtained as the square roots, and consequently are either real and positive (if \\omega_{m,{\\mathbf{q}}}^2 > 0 \\omega_{m,{\\mathbf{q}}}^2 > 0 ) or pure imaginary (if \\omega_{m,{\\mathbf{q}}}^2 < 0 \\omega_{m,{\\mathbf{q}}}^2 < 0 ) The corresponding eigenvectors are the polarization vectors, and describe the pattern of atomic displacements belonging to each mode. The central question of ab-initio lattice dynamics is therefore how to determine the force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} which are the second derivatives of the total energy with respect to two atomic displacements. The first derivatives are the forces, and may be determined straightforwardly using the Hellman\u2013Feynmann Theorem as the derivative of the quantum mechanical energy with respect to an atomic displacement, \\lambda \\lambda \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} If {\\left < \\psi \\right |} {\\left < \\psi \\right |} represents the ground state of {\\hat{H}} {\\hat{H}} then the first two terms vanish because {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 . Differentiating again yields \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. Unlike equation [hellman] the terms involving the derivatives of the wavefunctions do not vanish. This means that it is necessary to somehow compute the electronic response of the system to the displacement of an atom to perform ab-initio lattice dynamics calculations. This may be accomplished either by a finite-displacement method, i.e. performing two calculations which differ by a small displacement of an atomic co-ordinate and evaluating a numerical derivative, or by using perturbation theory to evaluate the response wavefunction {\\frac{d \\psi}{d \\lambda}} {\\frac{d \\psi}{d \\lambda}} . (In Kohn-Sham DFT, as implemented in CASTEP we actually evaluate the first-order response orbitals.) Some general references on ab-initio lattice dynamics methods are chapter 3 of ref ( Srivastava 2023 ) and the review paper by Baroni et al. ( Baroni et al. 2001 ). Prerequisites Geometry Optimisation A successful phonon calculation almost always requires a preceding geometry optimisation (except for small, high symmetry system where all atoms lie on crystallographic high-symmetry positions and the forces are zero by symmetry). It is not necessary to perform a variable-cell optimisation - the lattice dynamics is well defined at any stress or pressure, and phonons in high-pressure or strained systems are frequently of scientific interest. The two most convenient ways of achieving this are to Set up the phonon run as a continuation of the geometry optimisation by setting the parameters keyword continuation : . Add the keyword write_cell_structure : TRUE to the geometry optimization run and modify the resulting -out.cell to use as the input for a new run. The importance of a high-quality structure optimisation can not be overemphasized - the energy expansion in equation [taylor] makes the explicit assumption that the system is in mechanical equilibrium and that all atomic forces are zero. This is sufficiently important that before performing a phonon calculation CASTEP will compute the residual forces to determine if the geometry is converged. If any component of the force exceeds geom_force_tol it will print an error message and abort the run. Should a run fail with this message, it may be because the geometry optimisation run did not in fact succeed, or because some parameter governing the convergence ( e.g. the cutoff energy) differs in the phonon run compared to the geometry optimisation. In that case the correct procedure would be to re-optimise the geometry using the same parameters as needed for the phonon run. Alternatively if the geometry error and size of the force residual are tolerable, then the value of geom_force_tol may be increased in the .param file of the phonon calculation which will allow the run to proceed. How accurate a geometry optimization is needed? Accumulated practical experience suggests that substantially tighter tolerances are needed to generate reasonable quality phonons than are needed for structural or energetics calculations. For many crystalline systems a geometry force convergence tolerance set using parameter geom_force_tol of 0.01 eV/\u00c5 is typically needed. For \u201csoft\u201d materials containing weak bonds such as molecular crystals or in the presence of hydrogen bonds, an even smaller value is frequently necessary. Only careful convergence testing of the geometry and resulting frequencies can determine the value to use. To achieve a high level of force convergence, it is obviously essential that the forces be evaluated to at least the same precision. This will in turn govern the choice of electronic k-point sampling, and probably require a smaller than default SCF convergence tolerance, elec_energy_tol . See section [convergence] for further discussion of geometry optimisation and convergence for phonon calculations. If a lattice dynamics calculation is performed at the configuration which minimises the energy the force constant matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is positive definite, and all of its eigenvalues are positive. Consequently the vibrational frequencies which are the square roots of the eigenvalues are real numbers. 2 If on the other hand the system is not at a minimum energy equilibrium configuration {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is not necessarily positive definite, the eigenvalues \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 may be negative. In that case the frequencies are imaginary and do not correspond to a physical vibrational mode. For convenience CASTEP prints such values using a a minus sign \u201c - - \u201d. These are sometimes loosely referred to as \u201cnegative\u201d frequencies, but bear in mind that this convention really indicates negative eigenvalues and imaginary frequencies. 3 Use of Symmetry CASTEP lattice dynamics uses symmetry to reduce the number of perturbation calculations to the irreducible set, and applies the symmetry transformations to generate the full dynamical matrix. Combined with the usual reduction in k-points in the IBZ, savings in CPU time by use of crystallographic symmetry can easily be a factor of 10 or more. It is therefore important to maximise the symmetry available to the calculation, and to either specify the symmetry operations in the .cell file using the %block SYMMETRY_OPS keyword or generate them using keyword symmetry_generate . CASTEP generates the dynamical matrix using perturbations along Cartesian X, Y and Z directions. To maximise the use of symmetry and minimise the number of perturbations required, the symmetry axes of the crystal or molecule should be aligned along Cartesian X, Y, and Z. If the cell axes are specified using %block LATTICE_ABC , CASTEP attempts to optimally orient the cell in many cases, but if using %block LATTICE_CART it is the responsibility of the user. This is one of the few cases where the absolute orientation makes any difference in a CASTEP calculation. An optimal orientation will use the fewest perturbations and lowest CPU time and will also exhibit best convergence with respect to, for example electronic k-point set. Phonon calculations should normally be set up using the primitive unit cell. As an example the conventional cell of a face-centred-cubic crystal contains four primitive unit cells, and thus four times the number of electrons and four times the volume. It will therefore cost 16 times as much memory and 16 times the compute time to run even the SCF calculation. CASTEP\u2019s symmetry analysis will print a warning to the .castep file if this is detected. A further reason to work with the primitive cell is that CASTEP defines its phonon {\\mathbf{q}} {\\mathbf{q}} -point parameters with respect to the actual simulation cell, and so a naive attempt to specify {\\mathbf{q}} {\\mathbf{q}} -point paths would result in output for a folded Brillouin-Zone, which is unlikely to be what is desired. Most input structure-preparation tools like c2x or cif2cell are capable of conversion between conventional and primitive cells. There is a further consideration related to symmetry; structure, cell and atomic co-ordinates must be specified to a reasonably high accuracy in the input files. CASTEP uses stochastic methods to analyse the effect of symmetry operations on the dynamical matrix, and this analysis can fail to detect symmetries or otherwise misbehave unless symmetry operations, lattice vectors and atomic co-ordinates are consistent to a reasonable degree of precision. It is recommended that symmetry-related lattice vectors and internal co-ordinates are consistent to at least 10 ^{-6} ^{-6} \u00c5\u2006 which can only be achieved if the values in the .cell file are expressed to this number of decimal places. This is particularly significant in the case of trigonal or hexagonal systems specified with %block LATTICE_CART where equality of the a a and b b cell vector lengths is only as precise as the number of significant figures used to represent the components. Two features of CASTEP\u2019s .cell file input may be helpful. First is the ability to input cell vectors and atomic positions using (a limited set of) mathematical syntax. See figure [example-gamma] for an example. Second, if the cell file keyword snap_to_symmetry is present, CASTEP will adjust co-ordinates and vectors to satisfy symmetry to high precision. Alternatively there is a utility program in the academic distribution named symmetry_snap which implements the same functionality. This is invoked simply as symmetry_snap seedname which reads seedname .cell and outputs the symmetrised version to seedname -symm.cell Thus the harmonic approximation is noticeably in error for very asymmetric potentials, which for examplein the worst cases can lead to disagreement with experimental frequencies of up to 5% for the librational modes of small molecular crystals, or OH bonds. It also neglects phonon-phonon interactions and therefore does not predict any intrinsic line broadening. \u21a9 Beware of the tempting but incorrect assumption that a CASTEP geometry optimisation is sufficient to find the true minimum-energy configuration of the atoms. Any such geometry optimization can only yield the minimum subject to the constraints imposed; in most cases by crystallographic symmetry and in all cases by the lattice repeat symmetry of the unit cell. The true system may be able to lower its energy further, but only by breaking the symmetry or lattice constraint. In such cases there will be an imaginary frequencies corresponding to any such possibility. \u21a9 This apparent problem may be turned to a positive advantage. A lattice dynamics calculation can be used as a test whether a purported equilibrium crystal structure really is dynamically stable. The presence of imaginary frequencies anywhere in the Brillouin Zone would indicate that the structure is unstable to a distortion along the corresponding eigenvector. Another occasion would be to investigate a transition state. By definition a transition state geometry is at a stationary saddle point of the energy hypersurface and must therefore exhibit precisely one imaginary frequency. A final example is the case of a system exhibiting a \u201csoft-mode\u201d phase transition where the frequency at the Brillouin-zone boundary decreases to zero, indicating that the crystal could lower its energy by doubling of the corresponding unit cell parameter. It is often useful to explore how the frequency approaches zero as some external variable such as pressure or lattice constant is varied, in order to precisely locate the phase transition. Reference ( Pallikara et al. 2022 ) discusses the physical significance of imaginary phonon modes in some details and with examples. \u21a9","title":"Introduction"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:theory","text":"Consider a crystal with a unit cell containing N N atoms, labelled \\kappa \\kappa , and a a labels the primitive cells in the lattice. The crystal is initially in mechanical equilibrium, with Cartesian co-ordinates R_{{\\kappa,\\alpha}} R_{{\\kappa,\\alpha}} , ( \\alpha=1..3 \\alpha=1..3 denotes the Cartesian x x , y y or z z direction). {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} denotes the displacement of an atom from its equilibrium position. Harmonic lattice dynamics is based on a Taylor expansion of total energy about structural equilibrium co-ordinates. E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... where {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} is the vector of atomic displacements from equilibrium and {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} is the matrix of force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. At equilibrium the forces F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} are all zero so the first-order term vanishes. In the Harmonic Approximation the 3 ^{\\text{rd}} ^{\\text{rd}} and higher order terms are neglected 1 . Assume Born von Karman periodic boundary conditions and substitute a plane-wave trial solution {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) with a phonon wavevector {\\mathbf{q}} {\\mathbf{q}} and a polarization vector {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} . This yields an eigenvalue equation {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . The dynamical matrix is defined as {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} where the index a a runs over all lattice images of the primitive cell. That is, the dynamical matrix is the mass-reduced Fourier transform of the force constant matrix. The eigenvalue equation [dmat-eigen] can be solved by standard numerical methods. The eigenvalues, \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 , must be real numbers because {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} is a Hermitian matrix. The vibrational frequencies at each mode \\omega_{m,{\\mathbf{q}}} \\omega_{m,{\\mathbf{q}}} are obtained as the square roots, and consequently are either real and positive (if \\omega_{m,{\\mathbf{q}}}^2 > 0 \\omega_{m,{\\mathbf{q}}}^2 > 0 ) or pure imaginary (if \\omega_{m,{\\mathbf{q}}}^2 < 0 \\omega_{m,{\\mathbf{q}}}^2 < 0 ) The corresponding eigenvectors are the polarization vectors, and describe the pattern of atomic displacements belonging to each mode. The central question of ab-initio lattice dynamics is therefore how to determine the force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} which are the second derivatives of the total energy with respect to two atomic displacements. The first derivatives are the forces, and may be determined straightforwardly using the Hellman\u2013Feynmann Theorem as the derivative of the quantum mechanical energy with respect to an atomic displacement, \\lambda \\lambda \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} If {\\left < \\psi \\right |} {\\left < \\psi \\right |} represents the ground state of {\\hat{H}} {\\hat{H}} then the first two terms vanish because {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 . Differentiating again yields \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. Unlike equation [hellman] the terms involving the derivatives of the wavefunctions do not vanish. This means that it is necessary to somehow compute the electronic response of the system to the displacement of an atom to perform ab-initio lattice dynamics calculations. This may be accomplished either by a finite-displacement method, i.e. performing two calculations which differ by a small displacement of an atomic co-ordinate and evaluating a numerical derivative, or by using perturbation theory to evaluate the response wavefunction {\\frac{d \\psi}{d \\lambda}} {\\frac{d \\psi}{d \\lambda}} . (In Kohn-Sham DFT, as implemented in CASTEP we actually evaluate the first-order response orbitals.) Some general references on ab-initio lattice dynamics methods are chapter 3 of ref ( Srivastava 2023 ) and the review paper by Baroni et al. ( Baroni et al. 2001 ).","title":"Theory of Lattice Dynamics"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:prerequisites","text":"","title":"Prerequisites"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:geometry","text":"A successful phonon calculation almost always requires a preceding geometry optimisation (except for small, high symmetry system where all atoms lie on crystallographic high-symmetry positions and the forces are zero by symmetry). It is not necessary to perform a variable-cell optimisation - the lattice dynamics is well defined at any stress or pressure, and phonons in high-pressure or strained systems are frequently of scientific interest. The two most convenient ways of achieving this are to Set up the phonon run as a continuation of the geometry optimisation by setting the parameters keyword continuation : . Add the keyword write_cell_structure : TRUE to the geometry optimization run and modify the resulting -out.cell to use as the input for a new run. The importance of a high-quality structure optimisation can not be overemphasized - the energy expansion in equation [taylor] makes the explicit assumption that the system is in mechanical equilibrium and that all atomic forces are zero. This is sufficiently important that before performing a phonon calculation CASTEP will compute the residual forces to determine if the geometry is converged. If any component of the force exceeds geom_force_tol it will print an error message and abort the run. Should a run fail with this message, it may be because the geometry optimisation run did not in fact succeed, or because some parameter governing the convergence ( e.g. the cutoff energy) differs in the phonon run compared to the geometry optimisation. In that case the correct procedure would be to re-optimise the geometry using the same parameters as needed for the phonon run. Alternatively if the geometry error and size of the force residual are tolerable, then the value of geom_force_tol may be increased in the .param file of the phonon calculation which will allow the run to proceed. How accurate a geometry optimization is needed? Accumulated practical experience suggests that substantially tighter tolerances are needed to generate reasonable quality phonons than are needed for structural or energetics calculations. For many crystalline systems a geometry force convergence tolerance set using parameter geom_force_tol of 0.01 eV/\u00c5 is typically needed. For \u201csoft\u201d materials containing weak bonds such as molecular crystals or in the presence of hydrogen bonds, an even smaller value is frequently necessary. Only careful convergence testing of the geometry and resulting frequencies can determine the value to use. To achieve a high level of force convergence, it is obviously essential that the forces be evaluated to at least the same precision. This will in turn govern the choice of electronic k-point sampling, and probably require a smaller than default SCF convergence tolerance, elec_energy_tol . See section [convergence] for further discussion of geometry optimisation and convergence for phonon calculations. If a lattice dynamics calculation is performed at the configuration which minimises the energy the force constant matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is positive definite, and all of its eigenvalues are positive. Consequently the vibrational frequencies which are the square roots of the eigenvalues are real numbers. 2 If on the other hand the system is not at a minimum energy equilibrium configuration {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is not necessarily positive definite, the eigenvalues \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 may be negative. In that case the frequencies are imaginary and do not correspond to a physical vibrational mode. For convenience CASTEP prints such values using a a minus sign \u201c - - \u201d. These are sometimes loosely referred to as \u201cnegative\u201d frequencies, but bear in mind that this convention really indicates negative eigenvalues and imaginary frequencies. 3","title":"Geometry Optimisation"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:symmetry","text":"CASTEP lattice dynamics uses symmetry to reduce the number of perturbation calculations to the irreducible set, and applies the symmetry transformations to generate the full dynamical matrix. Combined with the usual reduction in k-points in the IBZ, savings in CPU time by use of crystallographic symmetry can easily be a factor of 10 or more. It is therefore important to maximise the symmetry available to the calculation, and to either specify the symmetry operations in the .cell file using the %block SYMMETRY_OPS keyword or generate them using keyword symmetry_generate . CASTEP generates the dynamical matrix using perturbations along Cartesian X, Y and Z directions. To maximise the use of symmetry and minimise the number of perturbations required, the symmetry axes of the crystal or molecule should be aligned along Cartesian X, Y, and Z. If the cell axes are specified using %block LATTICE_ABC , CASTEP attempts to optimally orient the cell in many cases, but if using %block LATTICE_CART it is the responsibility of the user. This is one of the few cases where the absolute orientation makes any difference in a CASTEP calculation. An optimal orientation will use the fewest perturbations and lowest CPU time and will also exhibit best convergence with respect to, for example electronic k-point set. Phonon calculations should normally be set up using the primitive unit cell. As an example the conventional cell of a face-centred-cubic crystal contains four primitive unit cells, and thus four times the number of electrons and four times the volume. It will therefore cost 16 times as much memory and 16 times the compute time to run even the SCF calculation. CASTEP\u2019s symmetry analysis will print a warning to the .castep file if this is detected. A further reason to work with the primitive cell is that CASTEP defines its phonon {\\mathbf{q}} {\\mathbf{q}} -point parameters with respect to the actual simulation cell, and so a naive attempt to specify {\\mathbf{q}} {\\mathbf{q}} -point paths would result in output for a folded Brillouin-Zone, which is unlikely to be what is desired. Most input structure-preparation tools like c2x or cif2cell are capable of conversion between conventional and primitive cells. There is a further consideration related to symmetry; structure, cell and atomic co-ordinates must be specified to a reasonably high accuracy in the input files. CASTEP uses stochastic methods to analyse the effect of symmetry operations on the dynamical matrix, and this analysis can fail to detect symmetries or otherwise misbehave unless symmetry operations, lattice vectors and atomic co-ordinates are consistent to a reasonable degree of precision. It is recommended that symmetry-related lattice vectors and internal co-ordinates are consistent to at least 10 ^{-6} ^{-6} \u00c5\u2006 which can only be achieved if the values in the .cell file are expressed to this number of decimal places. This is particularly significant in the case of trigonal or hexagonal systems specified with %block LATTICE_CART where equality of the a a and b b cell vector lengths is only as precise as the number of significant figures used to represent the components. Two features of CASTEP\u2019s .cell file input may be helpful. First is the ability to input cell vectors and atomic positions using (a limited set of) mathematical syntax. See figure [example-gamma] for an example. Second, if the cell file keyword snap_to_symmetry is present, CASTEP will adjust co-ordinates and vectors to satisfy symmetry to high precision. Alternatively there is a utility program in the academic distribution named symmetry_snap which implements the same functionality. This is invoked simply as symmetry_snap seedname which reads seedname .cell and outputs the symmetrised version to seedname -symm.cell Thus the harmonic approximation is noticeably in error for very asymmetric potentials, which for examplein the worst cases can lead to disagreement with experimental frequencies of up to 5% for the librational modes of small molecular crystals, or OH bonds. It also neglects phonon-phonon interactions and therefore does not predict any intrinsic line broadening. \u21a9 Beware of the tempting but incorrect assumption that a CASTEP geometry optimisation is sufficient to find the true minimum-energy configuration of the atoms. Any such geometry optimization can only yield the minimum subject to the constraints imposed; in most cases by crystallographic symmetry and in all cases by the lattice repeat symmetry of the unit cell. The true system may be able to lower its energy further, but only by breaking the symmetry or lattice constraint. In such cases there will be an imaginary frequencies corresponding to any such possibility. \u21a9 This apparent problem may be turned to a positive advantage. A lattice dynamics calculation can be used as a test whether a purported equilibrium crystal structure really is dynamically stable. The presence of imaginary frequencies anywhere in the Brillouin Zone would indicate that the structure is unstable to a distortion along the corresponding eigenvector. Another occasion would be to investigate a transition state. By definition a transition state geometry is at a stationary saddle point of the energy hypersurface and must therefore exhibit precisely one imaginary frequency. A final example is the case of a system exhibiting a \u201csoft-mode\u201d phase transition where the frequency at the Brillouin-zone boundary decreases to zero, indicating that the crystal could lower its energy by doubling of the corresponding unit cell parameter. It is often useful to explore how the frequency approaches zero as some external variable such as pressure or lattice constant is varied, in order to precisely locate the phase transition. Reference ( Pallikara et al. 2022 ) discusses the physical significance of imaginary phonon modes in some details and with examples. \u21a9","title":"Use of Symmetry"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/","text":"The cell and param file keywords used specifically for phonon and related calculations are listed here alphabetically with brief descriptions. CELL file keywords PHONON_FINE_KPOINT_LIST List of phonon wavevectors on the fine grid (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer list of points. PHONON_FINE_KPOINT_MP_GRID Fine MP-grid of phonon wavevectors (Integer Vector) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer grid of wavevectors. PHONON_FINE_KPOINT_MP_OFFSET Origin offset of the fine phonon MP grid (Real Vector) The offset of the fine MP grid at which the phonons calculated using DFPT are interpolated. PHONON_FINE_KPOINT_MP_SPACING The spacing of points on the fine MP set for phonons (Physical) This specifies the minimum spacing between points on a Monkhorst-Pack grid that phonons will be interpolated onto from the coarser phonon grid. PHONON_FINE_KPOINT_PATH Path of phonon wavevectors on a fine scale (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer path. PHONON_FINE_KPOINT_PATH_SPACING The fine spacing of points on a path at which phonons are calculated (Physical) The spacing of k-points along a path (specified by PHONON_FINE_KPOINT_PATH ) at which phonons will be interpolated from a coarser grid PHONON_GAMMA_DIRECTIONS Phonon gamma-point LO/TO splitting (Block) This is a list of directions along which {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 will be calculated for the non-analytic LO/TO term in a phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 . Fractional coordinates must be used. Default value: The k-point before gamma in the k-point list, or the one after or (0.1, 0, 0) PHONON_KPOINTS_LIST Alias for PHONON_KPOINT_LIST (Block) Default value: Determined from PHONON_KPOINT_LIST PHONON_KPOINTS_PATH Alias for PHONON_KPOINT_PATH (Block) Default value: Determined from PHONON_KPOINT_PATH PHONON_KPOINTS_PATH_SPACING Alias for PHONON_KPOINT_PATH_SPACING (Physical) Default value: Determined from PHONON_KPOINT_PATH_SPACING PHONON_KPOINT_LIST List of phonon k-points (Block) A list of discrete k-points at which phonon frequencies and eigenvectors will be calculated. Default value: SCF k-points are used if an alternative PHONON_KPOINT_* specifier is not given. PHONON_KPOINT_MP_GRID Phonon wavevector Monkhorst-Pack grid (Integer Vector) The phonon wavevectors defined by a Monkhorst-Pack grid. Symmetry (if specified) will be used to generate the wavevector list and weights. PHONON_KPOINT_MP_OFFSET Phonon wavevector Monkhorst Pack grid offset (Real Vector) The offset of the origin of the Monkhorst-Pack set for phonons in fractional coordinates, or the keyword INCLUDE_GAMMA . Default value: INCLUDE_GAMMA PHONON_KPOINT_MP_SPACING Phonon wavevector Monkhorst-Pack grid density (Physical) The density of wavevectors on a a Monkhorst-Pack grid for phonon calculations. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_KPOINT_PATH Phonon dispersion k-point path (Block) The path continuous through the BZ on which phonon dispersion is calculated. This is specified in fractional coordinates. Default value: None. PHONON_KPOINT_PATH_SPACING Phonon dispersion path spacing (Physical) The maximum spacing between kpoints along the path specified by PHONON_KPOINT_PATH . Units of inverse length must be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_SUPERCELL_MATRIX Supercell matrix for finite difference phonon calculations (Block) The supercelling matrix for force constant matrix calculations. The supercell matrix is specified by a 3x3 integer matrix which gives the supercell used in finite-difference phonon calculations. SUPERCELL_KPOINTS_LIST SCF k-points for FD phonon supercell (Block) A list of k-points in the Brillouin zone (with associated weights) used for BZ integration during a supercell FD phonon calculation. The k-point weights must sum to 1. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING and the crystal symmetry. SUPERCELL_KPOINTS_MP_GRID SCF Monkhorst-Pack grid for FD phonon supercell calculation (Integer Vector) The k-points defined by a Monkhorst-Pack grid when doing a finite displacement phonon calculation. Symmetry (if specified) will be used to generate the k-point list and weights. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING . SUPERCELL_KPOINTS_MP_OFFSET SCF Monkhorst Pack grid offset for a FD phonon supercell calculation (Real Vector) The offset of the origin of the Monkhorst-Pack set in fractional coordinates when performing a finite displacement phonon calculation. Default value: (0, 0, 0). SUPERCELL_KPOINTS_MP_SPACING SCF Monkhorst-Pack grid density for FD phonon supercell calculation (Physical) The k-point density of a Monkhorst-Pack grid for a supercell FD phonon calculation. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PARAM file keywords NUM_BACKUP_ITER md/geom iterations between backups (Integer) Specifies the number of iterations between backups of all data for restarts, for a geometry optimization or molecular dynamics run. Allowed values: (any integer) > > 0 Default value : 5 BACKUP_INTERVAL seconds between backups (Integer) Specifies the interval, in seconds, between backups of all data for restarts, for a geometry optimization/molecular dynamics/phonon run - if less than or equal to zero then no timed backups. Allowed values: (any) Default value : 0 BORN_CHARGE_SUM_RULE enforce Born charge sum rule (Logical) Selects whether to explicitly correct the Born effective charge tensor to enforce the sum rule that effective charges sum to zero. CALCULATE_BORN_CHARGES calculate Born effective charges (Logical) Selects whether to compute Born effective charge tensors as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : TRUE CALCULATE_RAMAN calculate Raman intensities (Logical) Selects whether to compute Raman intensities as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : FALSE EFIELD_CALC_ION_PERMITTIVITY calculate zero-frequency permittivity (Logical) Specifies whether or not to compute the zero-frequency dielectric permittivity based on the ionic response to electric fields. This requires a gamma-point phonon calculation in addition to the EFIELD linear response one. Allowed values: TRUE or FALSE Default value : TRUE EFIELD_CALCULATE_NONLINEAR calculate non-linear optical susceptibility (String) Select which non-linear optical property to calculate during TASK=EFIELD calculation. Allowed values: NONE, CHI2 Default value : NONE EFIELD_CONVERGENCE_WIN convergence tolerance window in EFIELD (Integer) The LR convergence criteria must be met for EFIELD_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 EFIELD_DFPT_METHOD E-field DFPT solver method (String) Selects the solver for E-field density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : ALLBANDS EFIELD_ENERGY_TOL E(2) convergence tolerance in EFIELD (Physical) Tolerance for accepting convergence of the field constants during PHONON calculation. The difference between max and min E(2) values over EFIELD_CONVERGENCE_WIN iterations must be less than this. NB This is an INTENSIVE parameter and has units of volume. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} A ^3 ^3 EFIELD_FREQ_SPACING Spacing of frequencies in permittivity calculation (Physical) Spacing of frequencies in calculation of frequency-dependent permittivity. Allowed values: (any) > > 0.0 Default value : 1.0 cm ^{-1} ^{-1} EFIELD_IGNORE_MOLEC_MODES Ignore lowest modes in permittivity calculation (String) Ignore the lowest lying (3,5,6) modes when computing the ionic contribution to the permittivity and polarizability. Allowed values: CRYSTAL , MOLECULE , LINEAR_MOLECULE Default value : CRYSTAL EFIELD_MAX_CG_STEPS max. number of cg steps in EFIELD (Integer) The maximum number of conjugate gradient steps in EFIELD calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 EFIELD_MAX_CYCLES maximum cycles in EFIELD (Integer) The maximum number of SCF cycles in EFIELD calculation regardless of convergence. Allowed values: (any integer) > > 0 Default value : 50 EFIELD_OSCILLATOR_Q Q-factor for line-shape broadening (Real) Oscillator Q-factor for line-shape broadening in calculation of frequency- dependent permittivity. Allowed values: (any) > > 0.0 Default value : 50.0 EFIELD_UNIT unit of electric field in output (String) Controls the units used for all electric field in output - many different units are supported. Default value : eV/A/E ELEC_METHOD treatment of metals or finite temperature insulator (String) The treatment of metals or finite temperature insulator to be used. An alias for METALS_METHOD . Allowed values: NONE (=ALLBANDS), DM, EDFT Default value : DM EXCITED_STATE_SCISSORS \u201cscissors\u201d operator band-gap correction (Physical) Effectively adds an offset to conduction-band eigenvalues as empirical correction for LDA/GGA underestimation of band-gaps. Allowed values: (any) Default value : 0.0 FIX_OCCUPANCY treat system as an insulator (Logical) Determines if the system is treated as an insulator or a metal. Allowed values: TRUE or FALSE Default value : FALSE GEOM_FORCE_TOL geometry optimization force convergence tolerance (Physical) Tolerance for accepting convergence of the maximum |ionic force| during geometry optimization. Allowed values: (any) > > 0.0 Default value : 0.05 eV/A PHONON_CALCULATE_DOS density of states calculation (Logical) Determines whether or not the phonon density of states will be calculated. Allowed values: TRUE or FALSE Default value : FALSE PHONON_DOS_SPACING density of states calculation (Physical) The resolution at which a phonon density-of-states will be calculated. Allowed values: (any) > 0.0 > 0.0 Default value : 10.0 cm ^{-1} ^{-1} . PHONON_DOS_LIMIT density of states calculation (Logical) The largest phonon to be included in a phonon density-of-states calculation. Allowed values: (any) > > PHONON_DOS_SPACING Default value : 5000.0 cm ^{-1} ^{-1} . PHONON_CALC_LO_TO_SPLITTING gamma-point phonon LO/TO correction (Logical) Selects whether to compute non-analytic contribution to dynamical matrix from long-ranged electric field effects responsible for LO/TO splitting. This requires calculation of the dielectric permittivity by E-field linear-response and the Born effective charges. Allowed values: TRUE or FALSE Default value : TRUE PHONON_CONVERGENCE_WIN convergence tolerance window in LR (Integer) The LR convergence criteria must be met for PHONON_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 PHONON_ENERGY_TOL E(2) convergence tolerance in LR (Physical) Tolerance for accepting convergence of the force constants during PHONON calculation. The difference between max and min E(2) values over PHONON_CONVERGENCE_WIN iterations must be less than this. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} eV/A ^2 ^2 PHONON_FINE_METHOD fine phonon calculation method (String) Selects which calculation method to use for phonon calculation on a fine grid. Allowed values: NONE, SUPERCELL, INTERPOLATE Default value : SUPERCELL if TASK=THERMODYNAMICS else NONE PHONON_FINITE_DISP finite displacement amplitude (Physical) The amplitude of the ionic perturbation to be used in a finite displacement phonon calculation. Allowed values: (any) > > 0.0 Default value : 0.01 a_0 a_0 PHONON_FORCE_CONSTANT_CUTOFF Cutoff for force constant matrix (Physical) The cutoff for the force constant matrix in a phonon calculation on a fine grid with supercell method. Allowed values: (any) \\ge \\ge 0.0 Default value : 0.0 PHONON_FINE_CUTOFF_METHOD Selects which method to use to extract non-periodic force constant matrix from periodic supercell. (String) With the CUMULANT method, all contributions from the periodic supercell are summed with a suitable weighting factor to avoid double counting of image contributions. The SPHERICAL method, uses a minimum image convention with a spherical cutoff given by PHONON_FORCE_CONSTANT_CUTOFF . Allowed values: CUMULANT and SPHERICAL . Default value : CUMULANT . PHONON_FORCE_CONSTANT_CUT_SCALE Scaling factor for aspherical force constant matrix cutoff (Real) The range of force constant terms included is up to s times halfway to the Wigner Seitz cell boundary. This parameter supplies the value of s. Allowed values: 0.0 \\le \\le (any) \\ge \\ge 1.0 Default value : 0.0 PHONON_FORCE_CONSTANT_ELLIPSOID Ellipsoid size for force constant matrix (Real) Alias for PHONON_FORCE_CONSTANT_CUT_SCALE (deprecated). PHONON_MAX_CG_STEPS max. number of cg steps in LR (Integer) The maximum number of conjugate gradient steps in PHONON calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 PHONON_MAX_CYCLES maximum cycles in LR (Integer) The maximum number of SCF cycles in PHONON calculation regardless of convergence. Allowed values: (any integer) \\ge \\ge 0 or if TASK=PHONON etc \\ge \\ge PHONON_CONVERGENCE_WIN Default value : 50 PHONON_METHOD phonon calculation method (String) Selects which calculation method to use for phonons. Allowed values: DFPT, LINEARRESPONSE, FINITEDISPLACEMENT Default value : set by PHONON_FINE_METHOD PHONON_DFPT_METHOD phonon DFPT solver method (String) Selects the solver for phonon density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : DM if FIX_OCCUPANCY : FALSE , otherwise ALLBANDS PHONON_PRECONDITIONER scheme to use in LR (String) The preconditioning scheme used by the CG minimiser in LR. Allowed values: RTPA, TPA, PS, NONE Default value : TPA PHONON_SUM_RULE enforce phonon sum rule (Logical) Selects whether to explicitly correct the dynamical matrix to enforce the acoustic q=0 phonon sum rule, i.e. that 3 modes have zero frequency at q=0. Allowed values: TRUE or FALSE Default value : FALSE PHONON_SUM_RULE_METHOD select method to enforce phonon sum rule (String) Selects a method to use when enforcing acoustic phonon sum rule. Allowed values: NONE : No sum-rule correction will be applied. RECIPROCAL : Correct dynamical matrix D(q) at each q using D(q=0). REALSPACE : Correct the real-space force constant matrix C(R). REAL-RECIP : Correct C(R) in realspace followed by D(q) in reciprocal space. MOLECULAR : Correct D(0) using rotational as well as translational sum-rule. MOLECULAR-1D : Correct D(0) for a linear molecule using rotational as well as translational sum-rule. Default value : RECIPROCAL PHONON_USE_KPOINT_SYMMETRY reduced or full kpoint set in LR (Logical) Selects which k-point set to use For each phonon q-vector in LR: T => use the irreducible k-point set of the (reduced) symmetry, F => use the complete fully symmetric k-point set. Allowed values: TRUE or FALSE Default value : TRUE PHONON_WRITE_FORCE_CONSTANTS Write out real-space force constant matrix (Logical) Selects whether to write out the real-space force constant matrix from a phonon supercell or interpolation calculation (to the .castep file) for the case of PHONON_FINE_METHOD /= NONE. Allowed values: TRUE or FALSE Default value : FALSE PHONON_WRITE_DYNAMICAL Write out reciprocal space dynamical matrix (Logical) Selects whether to write out the reciprocal space dynamical matrices from a phonon calculation (to the .castep file). /= NONE. Allowed values: TRUE or FALSE Default value : FALSE THERMO_T_NPOINTS Number of points in temperature interval (Integer) The number of points in the temperature interval for the thermodynamics calculation. Allowed values: (any integer) \\ge \\ge 1 Default value : 2 if THERMO_T_STOP /= THERMO_T_START or 1 otherwise THERMO_T_SPACING Temperature spacing (Physical) The spacing between temperature values for the thermodynamics calculation. Allowed values: (any) > > (-epsilon) Default value : THERMO_T_STOP - THERMO_T_START THERMO_T_START Starting temperature (Physical) The desired starting temperature for the thermodynamics calculation. Allowed values: (any) > > 0.0 Default value : 298 K THERMO_T_STOP Final temperature (Physical) The desired final temperature for the thermodynamics calculation. Allowed values: (any) \\ge \\ge THERMO_T_START Default value : 298","title":"Keyword-Reference"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/#sec:cellkw","text":"PHONON_FINE_KPOINT_LIST List of phonon wavevectors on the fine grid (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer list of points. PHONON_FINE_KPOINT_MP_GRID Fine MP-grid of phonon wavevectors (Integer Vector) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer grid of wavevectors. PHONON_FINE_KPOINT_MP_OFFSET Origin offset of the fine phonon MP grid (Real Vector) The offset of the fine MP grid at which the phonons calculated using DFPT are interpolated. PHONON_FINE_KPOINT_MP_SPACING The spacing of points on the fine MP set for phonons (Physical) This specifies the minimum spacing between points on a Monkhorst-Pack grid that phonons will be interpolated onto from the coarser phonon grid. PHONON_FINE_KPOINT_PATH Path of phonon wavevectors on a fine scale (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer path. PHONON_FINE_KPOINT_PATH_SPACING The fine spacing of points on a path at which phonons are calculated (Physical) The spacing of k-points along a path (specified by PHONON_FINE_KPOINT_PATH ) at which phonons will be interpolated from a coarser grid PHONON_GAMMA_DIRECTIONS Phonon gamma-point LO/TO splitting (Block) This is a list of directions along which {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 will be calculated for the non-analytic LO/TO term in a phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 . Fractional coordinates must be used. Default value: The k-point before gamma in the k-point list, or the one after or (0.1, 0, 0) PHONON_KPOINTS_LIST Alias for PHONON_KPOINT_LIST (Block) Default value: Determined from PHONON_KPOINT_LIST PHONON_KPOINTS_PATH Alias for PHONON_KPOINT_PATH (Block) Default value: Determined from PHONON_KPOINT_PATH PHONON_KPOINTS_PATH_SPACING Alias for PHONON_KPOINT_PATH_SPACING (Physical) Default value: Determined from PHONON_KPOINT_PATH_SPACING PHONON_KPOINT_LIST List of phonon k-points (Block) A list of discrete k-points at which phonon frequencies and eigenvectors will be calculated. Default value: SCF k-points are used if an alternative PHONON_KPOINT_* specifier is not given. PHONON_KPOINT_MP_GRID Phonon wavevector Monkhorst-Pack grid (Integer Vector) The phonon wavevectors defined by a Monkhorst-Pack grid. Symmetry (if specified) will be used to generate the wavevector list and weights. PHONON_KPOINT_MP_OFFSET Phonon wavevector Monkhorst Pack grid offset (Real Vector) The offset of the origin of the Monkhorst-Pack set for phonons in fractional coordinates, or the keyword INCLUDE_GAMMA . Default value: INCLUDE_GAMMA PHONON_KPOINT_MP_SPACING Phonon wavevector Monkhorst-Pack grid density (Physical) The density of wavevectors on a a Monkhorst-Pack grid for phonon calculations. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_KPOINT_PATH Phonon dispersion k-point path (Block) The path continuous through the BZ on which phonon dispersion is calculated. This is specified in fractional coordinates. Default value: None. PHONON_KPOINT_PATH_SPACING Phonon dispersion path spacing (Physical) The maximum spacing between kpoints along the path specified by PHONON_KPOINT_PATH . Units of inverse length must be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_SUPERCELL_MATRIX Supercell matrix for finite difference phonon calculations (Block) The supercelling matrix for force constant matrix calculations. The supercell matrix is specified by a 3x3 integer matrix which gives the supercell used in finite-difference phonon calculations. SUPERCELL_KPOINTS_LIST SCF k-points for FD phonon supercell (Block) A list of k-points in the Brillouin zone (with associated weights) used for BZ integration during a supercell FD phonon calculation. The k-point weights must sum to 1. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING and the crystal symmetry. SUPERCELL_KPOINTS_MP_GRID SCF Monkhorst-Pack grid for FD phonon supercell calculation (Integer Vector) The k-points defined by a Monkhorst-Pack grid when doing a finite displacement phonon calculation. Symmetry (if specified) will be used to generate the k-point list and weights. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING . SUPERCELL_KPOINTS_MP_OFFSET SCF Monkhorst Pack grid offset for a FD phonon supercell calculation (Real Vector) The offset of the origin of the Monkhorst-Pack set in fractional coordinates when performing a finite displacement phonon calculation. Default value: (0, 0, 0). SUPERCELL_KPOINTS_MP_SPACING SCF Monkhorst-Pack grid density for FD phonon supercell calculation (Physical) The k-point density of a Monkhorst-Pack grid for a supercell FD phonon calculation. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} .","title":"CELL file keywords"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/#sec:paramkw","text":"NUM_BACKUP_ITER md/geom iterations between backups (Integer) Specifies the number of iterations between backups of all data for restarts, for a geometry optimization or molecular dynamics run. Allowed values: (any integer) > > 0 Default value : 5 BACKUP_INTERVAL seconds between backups (Integer) Specifies the interval, in seconds, between backups of all data for restarts, for a geometry optimization/molecular dynamics/phonon run - if less than or equal to zero then no timed backups. Allowed values: (any) Default value : 0 BORN_CHARGE_SUM_RULE enforce Born charge sum rule (Logical) Selects whether to explicitly correct the Born effective charge tensor to enforce the sum rule that effective charges sum to zero. CALCULATE_BORN_CHARGES calculate Born effective charges (Logical) Selects whether to compute Born effective charge tensors as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : TRUE CALCULATE_RAMAN calculate Raman intensities (Logical) Selects whether to compute Raman intensities as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : FALSE EFIELD_CALC_ION_PERMITTIVITY calculate zero-frequency permittivity (Logical) Specifies whether or not to compute the zero-frequency dielectric permittivity based on the ionic response to electric fields. This requires a gamma-point phonon calculation in addition to the EFIELD linear response one. Allowed values: TRUE or FALSE Default value : TRUE EFIELD_CALCULATE_NONLINEAR calculate non-linear optical susceptibility (String) Select which non-linear optical property to calculate during TASK=EFIELD calculation. Allowed values: NONE, CHI2 Default value : NONE EFIELD_CONVERGENCE_WIN convergence tolerance window in EFIELD (Integer) The LR convergence criteria must be met for EFIELD_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 EFIELD_DFPT_METHOD E-field DFPT solver method (String) Selects the solver for E-field density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : ALLBANDS EFIELD_ENERGY_TOL E(2) convergence tolerance in EFIELD (Physical) Tolerance for accepting convergence of the field constants during PHONON calculation. The difference between max and min E(2) values over EFIELD_CONVERGENCE_WIN iterations must be less than this. NB This is an INTENSIVE parameter and has units of volume. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} A ^3 ^3 EFIELD_FREQ_SPACING Spacing of frequencies in permittivity calculation (Physical) Spacing of frequencies in calculation of frequency-dependent permittivity. Allowed values: (any) > > 0.0 Default value : 1.0 cm ^{-1} ^{-1} EFIELD_IGNORE_MOLEC_MODES Ignore lowest modes in permittivity calculation (String) Ignore the lowest lying (3,5,6) modes when computing the ionic contribution to the permittivity and polarizability. Allowed values: CRYSTAL , MOLECULE , LINEAR_MOLECULE Default value : CRYSTAL EFIELD_MAX_CG_STEPS max. number of cg steps in EFIELD (Integer) The maximum number of conjugate gradient steps in EFIELD calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 EFIELD_MAX_CYCLES maximum cycles in EFIELD (Integer) The maximum number of SCF cycles in EFIELD calculation regardless of convergence. Allowed values: (any integer) > > 0 Default value : 50 EFIELD_OSCILLATOR_Q Q-factor for line-shape broadening (Real) Oscillator Q-factor for line-shape broadening in calculation of frequency- dependent permittivity. Allowed values: (any) > > 0.0 Default value : 50.0 EFIELD_UNIT unit of electric field in output (String) Controls the units used for all electric field in output - many different units are supported. Default value : eV/A/E ELEC_METHOD treatment of metals or finite temperature insulator (String) The treatment of metals or finite temperature insulator to be used. An alias for METALS_METHOD . Allowed values: NONE (=ALLBANDS), DM, EDFT Default value : DM EXCITED_STATE_SCISSORS \u201cscissors\u201d operator band-gap correction (Physical) Effectively adds an offset to conduction-band eigenvalues as empirical correction for LDA/GGA underestimation of band-gaps. Allowed values: (any) Default value : 0.0 FIX_OCCUPANCY treat system as an insulator (Logical) Determines if the system is treated as an insulator or a metal. Allowed values: TRUE or FALSE Default value : FALSE GEOM_FORCE_TOL geometry optimization force convergence tolerance (Physical) Tolerance for accepting convergence of the maximum |ionic force| during geometry optimization. Allowed values: (any) > > 0.0 Default value : 0.05 eV/A PHONON_CALCULATE_DOS density of states calculation (Logical) Determines whether or not the phonon density of states will be calculated. Allowed values: TRUE or FALSE Default value : FALSE PHONON_DOS_SPACING density of states calculation (Physical) The resolution at which a phonon density-of-states will be calculated. Allowed values: (any) > 0.0 > 0.0 Default value : 10.0 cm ^{-1} ^{-1} . PHONON_DOS_LIMIT density of states calculation (Logical) The largest phonon to be included in a phonon density-of-states calculation. Allowed values: (any) > > PHONON_DOS_SPACING Default value : 5000.0 cm ^{-1} ^{-1} . PHONON_CALC_LO_TO_SPLITTING gamma-point phonon LO/TO correction (Logical) Selects whether to compute non-analytic contribution to dynamical matrix from long-ranged electric field effects responsible for LO/TO splitting. This requires calculation of the dielectric permittivity by E-field linear-response and the Born effective charges. Allowed values: TRUE or FALSE Default value : TRUE PHONON_CONVERGENCE_WIN convergence tolerance window in LR (Integer) The LR convergence criteria must be met for PHONON_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 PHONON_ENERGY_TOL E(2) convergence tolerance in LR (Physical) Tolerance for accepting convergence of the force constants during PHONON calculation. The difference between max and min E(2) values over PHONON_CONVERGENCE_WIN iterations must be less than this. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} eV/A ^2 ^2 PHONON_FINE_METHOD fine phonon calculation method (String) Selects which calculation method to use for phonon calculation on a fine grid. Allowed values: NONE, SUPERCELL, INTERPOLATE Default value : SUPERCELL if TASK=THERMODYNAMICS else NONE PHONON_FINITE_DISP finite displacement amplitude (Physical) The amplitude of the ionic perturbation to be used in a finite displacement phonon calculation. Allowed values: (any) > > 0.0 Default value : 0.01 a_0 a_0 PHONON_FORCE_CONSTANT_CUTOFF Cutoff for force constant matrix (Physical) The cutoff for the force constant matrix in a phonon calculation on a fine grid with supercell method. Allowed values: (any) \\ge \\ge 0.0 Default value : 0.0 PHONON_FINE_CUTOFF_METHOD Selects which method to use to extract non-periodic force constant matrix from periodic supercell. (String) With the CUMULANT method, all contributions from the periodic supercell are summed with a suitable weighting factor to avoid double counting of image contributions. The SPHERICAL method, uses a minimum image convention with a spherical cutoff given by PHONON_FORCE_CONSTANT_CUTOFF . Allowed values: CUMULANT and SPHERICAL . Default value : CUMULANT . PHONON_FORCE_CONSTANT_CUT_SCALE Scaling factor for aspherical force constant matrix cutoff (Real) The range of force constant terms included is up to s times halfway to the Wigner Seitz cell boundary. This parameter supplies the value of s. Allowed values: 0.0 \\le \\le (any) \\ge \\ge 1.0 Default value : 0.0 PHONON_FORCE_CONSTANT_ELLIPSOID Ellipsoid size for force constant matrix (Real) Alias for PHONON_FORCE_CONSTANT_CUT_SCALE (deprecated). PHONON_MAX_CG_STEPS max. number of cg steps in LR (Integer) The maximum number of conjugate gradient steps in PHONON calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 PHONON_MAX_CYCLES maximum cycles in LR (Integer) The maximum number of SCF cycles in PHONON calculation regardless of convergence. Allowed values: (any integer) \\ge \\ge 0 or if TASK=PHONON etc \\ge \\ge PHONON_CONVERGENCE_WIN Default value : 50 PHONON_METHOD phonon calculation method (String) Selects which calculation method to use for phonons. Allowed values: DFPT, LINEARRESPONSE, FINITEDISPLACEMENT Default value : set by PHONON_FINE_METHOD PHONON_DFPT_METHOD phonon DFPT solver method (String) Selects the solver for phonon density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : DM if FIX_OCCUPANCY : FALSE , otherwise ALLBANDS PHONON_PRECONDITIONER scheme to use in LR (String) The preconditioning scheme used by the CG minimiser in LR. Allowed values: RTPA, TPA, PS, NONE Default value : TPA PHONON_SUM_RULE enforce phonon sum rule (Logical) Selects whether to explicitly correct the dynamical matrix to enforce the acoustic q=0 phonon sum rule, i.e. that 3 modes have zero frequency at q=0. Allowed values: TRUE or FALSE Default value : FALSE PHONON_SUM_RULE_METHOD select method to enforce phonon sum rule (String) Selects a method to use when enforcing acoustic phonon sum rule. Allowed values: NONE : No sum-rule correction will be applied. RECIPROCAL : Correct dynamical matrix D(q) at each q using D(q=0). REALSPACE : Correct the real-space force constant matrix C(R). REAL-RECIP : Correct C(R) in realspace followed by D(q) in reciprocal space. MOLECULAR : Correct D(0) using rotational as well as translational sum-rule. MOLECULAR-1D : Correct D(0) for a linear molecule using rotational as well as translational sum-rule. Default value : RECIPROCAL PHONON_USE_KPOINT_SYMMETRY reduced or full kpoint set in LR (Logical) Selects which k-point set to use For each phonon q-vector in LR: T => use the irreducible k-point set of the (reduced) symmetry, F => use the complete fully symmetric k-point set. Allowed values: TRUE or FALSE Default value : TRUE PHONON_WRITE_FORCE_CONSTANTS Write out real-space force constant matrix (Logical) Selects whether to write out the real-space force constant matrix from a phonon supercell or interpolation calculation (to the .castep file) for the case of PHONON_FINE_METHOD /= NONE. Allowed values: TRUE or FALSE Default value : FALSE PHONON_WRITE_DYNAMICAL Write out reciprocal space dynamical matrix (Logical) Selects whether to write out the reciprocal space dynamical matrices from a phonon calculation (to the .castep file). /= NONE. Allowed values: TRUE or FALSE Default value : FALSE THERMO_T_NPOINTS Number of points in temperature interval (Integer) The number of points in the temperature interval for the thermodynamics calculation. Allowed values: (any integer) \\ge \\ge 1 Default value : 2 if THERMO_T_STOP /= THERMO_T_START or 1 otherwise THERMO_T_SPACING Temperature spacing (Physical) The spacing between temperature values for the thermodynamics calculation. Allowed values: (any) > > (-epsilon) Default value : THERMO_T_STOP - THERMO_T_START THERMO_T_START Starting temperature (Physical) The desired starting temperature for the thermodynamics calculation. Allowed values: (any) > > 0.0 Default value : 298 K THERMO_T_STOP Final temperature (Physical) The desired final temperature for the thermodynamics calculation. Allowed values: (any) \\ge \\ge THERMO_T_START Default value : 298","title":"PARAM file keywords"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/","text":"Several tools and programs are available to help automate post-processing analysis and plotting of the results of phonon calculations. The tools described below are supplied as part of the CASTEP source code distribution Other independently-developed spectroscopy modelling tools may be installed to perform more advanced modelling of, for example inelastic neutron and IR spectra. Two programs dispersion.pl and dos.pl are supplied as part of the CASTEP source distribution to analyse and plot the results. Both of them read the phonon information from the .castep or .phonon files and can generate plots of phonon dispersion curves across the Brillouin Zone, and of phonon densities of states respectively 1 . These programs are written in the PERL language which is almost universally available on modern operating systems. Generation of the plots is handled by either of the xmgrace or gnuplot graphics programs (the perl programs generate an xmgrace script and invoke it automatically). 2 dos.pl The dos.pl program can read any of a .castep , a .phonon , or a .phonon_dos file and generate a phonon density of states plot. Arguments are given in \u201cunix style\u201d following a minus sign (dash). The command dos.pl -xg -w 10 .phonon will generate a phonon density of states using a Gaussian broadening with a FWHM of 10 cm ^{-1} ^{-1} , and invoke xmgrace to generate the plot. If a .phonon file is specified the DOS is constructed as a weighted average over all q-points present in the file. Alternatively an adaptively-weighted dos computed by CASTEP is read from a .phonon_dos file if given as command-line argument. The options -np , -ps , -eps change the default output and write an xmgrace file, a PostScript or Encapsulated PostScript file respectively. These files are written to standard output so use a shell redirect ( > > ) to name your plot file. The option -ir option weights the computed DOS by the computed infra-red intensity in the .castep or .phonon file. This simple algorithm is not a fully realistic model of an infrared powder spectrum, and should be regarded as a simple approximation only. 3 Likewise the -raman option extracts Raman intensities and computes the weighted spectrum. The computed spectrum does include the frequency-dependent and Stokes thermal factors, and is therefore a more realistic model spectrum than in the infrared case. The -lorentz option switches from Gaussian to a Lorentzian broadening and the -temp T option sets the temperature for the Stokes thermal population term in Kelvin. Figure [bn-dos-ir] shows an example derived from the output produced by using dos.pl on the example run of figure [example-gamma-out] . Figure 8 Example output from dos.pl based on the run of figure [example-gamma-out] . Infrared spectrum and DOS curves based on just the TO modes or TO plus LO have been combined into into one plot with a slightly shifted baseline, scaled, and legends added. dispersion.pl The dispersion.pl program can read either a .castep or a .phonon file and generate a dispersion curve plot using xmgrace. Unlike the behaviour of dos.pl there is an important difference between the behaviour when reading these two different output files concerning the detection of branch crossings. A high-quality dispersion plot requires that phonon branches are drawn as continuous lines even when two branches cross in between the computed wavevectors. Dispersion.pl contains an algorithm based on matching of eigenvectors at adjacent points to determine branch connectivity. Only the .phonon file contains eigenvector information, so only in this case is crossing detection enabled. The algorithm can be time consuming and take several minutes to complete in large cases, so patience is sometimes required. The -nj option (\u201cno-join\u201d) disables the crossing detection even when the input file is a .phonon one. The options -np , -ps , -eps behave exactly as for dos.pl . One useful output option is -symmetry which attempts to label the high symmetry points using the conventional Brillouin zone notation of Bradley and Cracknell. The symmetry keywords cubic , fcc , bcc , tetragonal , tetragonal , tetragonal-I , orthorhombic , hexagonal , trigonal , trigonal-h (and minor variants) are understood. Figure [rbbr-dispersion] demonstrates the effect of the flags and the branch joining algorithm. The plots were produced from a Fourier interpolation calculation of fcc RbBr using the commands dispersion.pl -xg -symmetry fcc RbBr.phonon and dispersion.pl -xg -symmetry fcc -nj RbBr.phonon respectively. Figure 9 Phonon dispersion curve plots of RbBr generated using the dispersion.pl script and xmgrace. The Brillouin zone labelling is generated using the -symmetry fcc option. The left-hand plot was generated using the default branch crossing detection algorithm, which was disabled using the -nj option for the right-hand plot. The algorithm has discriminated between modes which do cross and the four genuine avoided crossings in the left-hand plot. mode_follow mode_follow is one of the Fortran tools suite in the CASTEP source, which is compiled using the command make tools . As the name implies its function is to generate new \u201cfrozen phonon\u201d configurations based on perturbation by a mode generated from a previous phonon calculation, which it outputs by writing one or more new .cell files. In fact it has two modes of operation. To generate a sequence of .cell files perturbed by the a frozen phonon at a range of amplitudes, which may be used to explore the energy profile along the mode it is invoked as mode follow -mode mode_num -namp num_amplitudes -amp max_amplitude -qpoint qx qy qz < < seedname > > | < < seedname > > .phonon which reads the .phonon and corresponding .cell files and generates a sequence of N+1 N+1 files seedname - i .cell containing structures perturbed by the selected eigenvector scaled by a non-dimensional amplitude factor f=A i/N, i=0 .. N f=A i/N, i=0 .. N . The arguments are mode_num is the integer index number selecting which mode to use (default 1) qx qy qz is the q-point to extract from the .phonon file (default (0,0,0)) max_amplitude is A A the non-dimensional scale of the eigenvectors used to create the (largest) displacement num_amplitudes is N N , one less than the number of configurations to generate (default 2). seedname is the seed name of a previous, successful phonon run. The file seedname .phonon must exist and be readable. If mode_follow is invoked without the .phonon extension, it will also attempt to read seedname .cell file if it exists and will copy most other cell parameters and settings to its output .cell files. As an alternative to specifying the arguments on the command line mode_follow will also attempt to read them from a file named seedname .mode-param if it exists. This file should contain a Fortran namelist named freeze , whose entries are the identical to the command-line argument names. For example &freeze mode=4 num_amplitudes=5, / To produce a frozen phonon configuration for a nonzero {\\mathbf{q}} {\\mathbf{q}} -vector it is also necessary to generate a supercell which is commensurate with a frozen phonon at wavevector {\\mathbf{q}} {\\mathbf{q}} . This supercell may be specified in the .cell file using the usual phonon_supercell_matrix block, or by the entry SUPERCELL in namelist freeze in the .mode-param file. (There is no corresponding command line argument). For example a .mode-param file requesting a zone-boundary phonon might contain &freeze mode=4 num_amplitudes=5, qpoint=0,0.5,0 supercell=1,0,0,0,2,0,0,0,1 / Mode_follow \u2019s second mode of operation is to generate output files with the structure perturbed by a frozen phonon at the same amplitude but a progressive sequence of phases, which could be used for an animation of the mode. In that case the num_amplitudes argument should be omitted, and the alternative nframes argument given instead (either on the command line or in the .mode-param file). This will generate a sequence of N N frames with phases separated by 2 \\pi/N 2 \\pi/N . Otherwise the arguments and behaviour are identical. One of the scripts in the cteprouts package, e.g. cell2xtl , cell2pdb , cell2xyz may be then be used to convert the .cell files to a form suitable for visualisation. phonons The program phonons , one of the CASTEP tools suite is a general purpose phonon post-processing tool. It can read all of the dynamical matrix or force constant matrix data from a .check or .castep_bin file generated in any phonon calculation and re-generate the final phonon output with changes to one or several \u201cfinalisation\u201d options, without needing to repeat the expensive \u201celectronic\u201d DFPT or supercell parts of a lattice dynamics calculation. For example, an acoustic sum-rule correction may be applied to a calculation where this was not chosen initially. phonons is invoked exactly as is CASTEP and reads a .cell and a .param file exactly as CASTEP does. These may be identical to or near copies of the original calculation, but the .param file must contain the continuation keyword which must point to the .check or .castep_bin file which contains the dynamical matrix data. If the run is successful it will write a log file with the extension .phonon_out and a new .phonon file. In this respect a run of phonons on a continuation deck is very similar to re-running castep on the same deck. However it will not attempt to perform any \u201celectronic\u201d calculation and will ignore any attempt to try. For example, if the parameter elec_energy_tol was changed castep would discard the saved dynamical matrix data and restart from the beginning. phonons will ignore this and process the saved data as a continuation run. This post-processing can be used for a number of tasks, including Turning on or off or modifying an acoustic sum-rule correction by changing the parameters keywords phonon_sum_rule or phonon_sum_rule_method . turning on or off the inclusion of LO/TO splitting terms by changing parameters keyword phonon_calc_lo_to_splitting or changing the set of directions for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 by adding or changing cell %block PHONON_GAMMA_DIRECTIONS . adding or omitting the low-frequency ionic term in an E-field calculation by changing parameter efield_calc_ion_permittivity . Note that an attempt to turn this on will only succeed if there result of a \\Gamma \\Gamma -point phonon calculation is already stored in the .check file. phonons will not attempt the electronic calculation necessary to compute this if it is not. changing the set of fine phonon k-points used as the target of a supercell or interpolation calculation by adding or changing %block PHONON_FINE_KPOINT_LIST , %block PHONON_FINE_KPOINT_PATH , phonon_fine_kpoint_mp_grid or similar in the .cell file. This permits the calculation of both a set of dispersion curves and a DOS from the same electronic run (DFPT/Interpolation or supercell). taking the result of a phonon calculation on a Monkhorst Pack grid of standard (not fine) phonon kpoints and performing Fourier interpolation as a post-processing step. switching interpolation methods between spherical and anisotropic schemes. All of the above could also be performed using castep rather than phonons provided care is taken not to change any parameters which control the properties of the \u201celectronic\u201d part of the calculation. However phonons can also perform some additional processing which castep can not, most notably isotopically substituted lattice dynamics calculations. dispersion.pl and dos.pl are also able perform very similar analysis and plotting of electronic eigenvalues from .castep or .bands files and generate band structure and electronic DOS plots. \u21a9 On linux systems xmgrace can usually be found as a contributed package and installed using the system package manager. Xmgrace is also available for Microsoft Windows systems as part of the \u201ccygwin\u201d suite of programs ( http://www.cygwin.com ) along with shells, the PERL interpreter and an X-windows server (Xmgrace is an X-windows program and requires a running X server to display). \u21a9 A more sophisticated model of infra-red spectra was introduced by Balan and Mauri (( Balan et al. 2001 ; Kendrick and Burnett 2016 ) and subsequent works). Modelling of inelastic neutron spectra is discussed by Fair ( Fair et al. 2022 ), Ramirez-Cuesta ( Ramirez-Cuesta 2004 ; Cheng and Ramirez-Cuesta 2020 ) \u21a9","title":"Plotting-and-analysis-tools"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:dos-pl","text":"The dos.pl program can read any of a .castep , a .phonon , or a .phonon_dos file and generate a phonon density of states plot. Arguments are given in \u201cunix style\u201d following a minus sign (dash). The command dos.pl -xg -w 10 .phonon will generate a phonon density of states using a Gaussian broadening with a FWHM of 10 cm ^{-1} ^{-1} , and invoke xmgrace to generate the plot. If a .phonon file is specified the DOS is constructed as a weighted average over all q-points present in the file. Alternatively an adaptively-weighted dos computed by CASTEP is read from a .phonon_dos file if given as command-line argument. The options -np , -ps , -eps change the default output and write an xmgrace file, a PostScript or Encapsulated PostScript file respectively. These files are written to standard output so use a shell redirect ( > > ) to name your plot file. The option -ir option weights the computed DOS by the computed infra-red intensity in the .castep or .phonon file. This simple algorithm is not a fully realistic model of an infrared powder spectrum, and should be regarded as a simple approximation only. 3 Likewise the -raman option extracts Raman intensities and computes the weighted spectrum. The computed spectrum does include the frequency-dependent and Stokes thermal factors, and is therefore a more realistic model spectrum than in the infrared case. The -lorentz option switches from Gaussian to a Lorentzian broadening and the -temp T option sets the temperature for the Stokes thermal population term in Kelvin. Figure [bn-dos-ir] shows an example derived from the output produced by using dos.pl on the example run of figure [example-gamma-out] . Figure 8 Example output from dos.pl based on the run of figure [example-gamma-out] . Infrared spectrum and DOS curves based on just the TO modes or TO plus LO have been combined into into one plot with a slightly shifted baseline, scaled, and legends added.","title":"dos.pl"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:dispersion-pl","text":"The dispersion.pl program can read either a .castep or a .phonon file and generate a dispersion curve plot using xmgrace. Unlike the behaviour of dos.pl there is an important difference between the behaviour when reading these two different output files concerning the detection of branch crossings. A high-quality dispersion plot requires that phonon branches are drawn as continuous lines even when two branches cross in between the computed wavevectors. Dispersion.pl contains an algorithm based on matching of eigenvectors at adjacent points to determine branch connectivity. Only the .phonon file contains eigenvector information, so only in this case is crossing detection enabled. The algorithm can be time consuming and take several minutes to complete in large cases, so patience is sometimes required. The -nj option (\u201cno-join\u201d) disables the crossing detection even when the input file is a .phonon one. The options -np , -ps , -eps behave exactly as for dos.pl . One useful output option is -symmetry which attempts to label the high symmetry points using the conventional Brillouin zone notation of Bradley and Cracknell. The symmetry keywords cubic , fcc , bcc , tetragonal , tetragonal , tetragonal-I , orthorhombic , hexagonal , trigonal , trigonal-h (and minor variants) are understood. Figure [rbbr-dispersion] demonstrates the effect of the flags and the branch joining algorithm. The plots were produced from a Fourier interpolation calculation of fcc RbBr using the commands dispersion.pl -xg -symmetry fcc RbBr.phonon and dispersion.pl -xg -symmetry fcc -nj RbBr.phonon respectively. Figure 9 Phonon dispersion curve plots of RbBr generated using the dispersion.pl script and xmgrace. The Brillouin zone labelling is generated using the -symmetry fcc option. The left-hand plot was generated using the default branch crossing detection algorithm, which was disabled using the -nj option for the right-hand plot. The algorithm has discriminated between modes which do cross and the four genuine avoided crossings in the left-hand plot.","title":"dispersion.pl"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#mode_follow","text":"mode_follow is one of the Fortran tools suite in the CASTEP source, which is compiled using the command make tools . As the name implies its function is to generate new \u201cfrozen phonon\u201d configurations based on perturbation by a mode generated from a previous phonon calculation, which it outputs by writing one or more new .cell files. In fact it has two modes of operation. To generate a sequence of .cell files perturbed by the a frozen phonon at a range of amplitudes, which may be used to explore the energy profile along the mode it is invoked as mode follow -mode mode_num -namp num_amplitudes -amp max_amplitude -qpoint qx qy qz < < seedname > > | < < seedname > > .phonon which reads the .phonon and corresponding .cell files and generates a sequence of N+1 N+1 files seedname - i .cell containing structures perturbed by the selected eigenvector scaled by a non-dimensional amplitude factor f=A i/N, i=0 .. N f=A i/N, i=0 .. N . The arguments are mode_num is the integer index number selecting which mode to use (default 1) qx qy qz is the q-point to extract from the .phonon file (default (0,0,0)) max_amplitude is A A the non-dimensional scale of the eigenvectors used to create the (largest) displacement num_amplitudes is N N , one less than the number of configurations to generate (default 2). seedname is the seed name of a previous, successful phonon run. The file seedname .phonon must exist and be readable. If mode_follow is invoked without the .phonon extension, it will also attempt to read seedname .cell file if it exists and will copy most other cell parameters and settings to its output .cell files. As an alternative to specifying the arguments on the command line mode_follow will also attempt to read them from a file named seedname .mode-param if it exists. This file should contain a Fortran namelist named freeze , whose entries are the identical to the command-line argument names. For example &freeze mode=4 num_amplitudes=5, / To produce a frozen phonon configuration for a nonzero {\\mathbf{q}} {\\mathbf{q}} -vector it is also necessary to generate a supercell which is commensurate with a frozen phonon at wavevector {\\mathbf{q}} {\\mathbf{q}} . This supercell may be specified in the .cell file using the usual phonon_supercell_matrix block, or by the entry SUPERCELL in namelist freeze in the .mode-param file. (There is no corresponding command line argument). For example a .mode-param file requesting a zone-boundary phonon might contain &freeze mode=4 num_amplitudes=5, qpoint=0,0.5,0 supercell=1,0,0,0,2,0,0,0,1 / Mode_follow \u2019s second mode of operation is to generate output files with the structure perturbed by a frozen phonon at the same amplitude but a progressive sequence of phases, which could be used for an animation of the mode. In that case the num_amplitudes argument should be omitted, and the alternative nframes argument given instead (either on the command line or in the .mode-param file). This will generate a sequence of N N frames with phases separated by 2 \\pi/N 2 \\pi/N . Otherwise the arguments and behaviour are identical. One of the scripts in the cteprouts package, e.g. cell2xtl , cell2pdb , cell2xyz may be then be used to convert the .cell files to a form suitable for visualisation.","title":"mode_follow"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:phonons-tool","text":"The program phonons , one of the CASTEP tools suite is a general purpose phonon post-processing tool. It can read all of the dynamical matrix or force constant matrix data from a .check or .castep_bin file generated in any phonon calculation and re-generate the final phonon output with changes to one or several \u201cfinalisation\u201d options, without needing to repeat the expensive \u201celectronic\u201d DFPT or supercell parts of a lattice dynamics calculation. For example, an acoustic sum-rule correction may be applied to a calculation where this was not chosen initially. phonons is invoked exactly as is CASTEP and reads a .cell and a .param file exactly as CASTEP does. These may be identical to or near copies of the original calculation, but the .param file must contain the continuation keyword which must point to the .check or .castep_bin file which contains the dynamical matrix data. If the run is successful it will write a log file with the extension .phonon_out and a new .phonon file. In this respect a run of phonons on a continuation deck is very similar to re-running castep on the same deck. However it will not attempt to perform any \u201celectronic\u201d calculation and will ignore any attempt to try. For example, if the parameter elec_energy_tol was changed castep would discard the saved dynamical matrix data and restart from the beginning. phonons will ignore this and process the saved data as a continuation run. This post-processing can be used for a number of tasks, including Turning on or off or modifying an acoustic sum-rule correction by changing the parameters keywords phonon_sum_rule or phonon_sum_rule_method . turning on or off the inclusion of LO/TO splitting terms by changing parameters keyword phonon_calc_lo_to_splitting or changing the set of directions for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 by adding or changing cell %block PHONON_GAMMA_DIRECTIONS . adding or omitting the low-frequency ionic term in an E-field calculation by changing parameter efield_calc_ion_permittivity . Note that an attempt to turn this on will only succeed if there result of a \\Gamma \\Gamma -point phonon calculation is already stored in the .check file. phonons will not attempt the electronic calculation necessary to compute this if it is not. changing the set of fine phonon k-points used as the target of a supercell or interpolation calculation by adding or changing %block PHONON_FINE_KPOINT_LIST , %block PHONON_FINE_KPOINT_PATH , phonon_fine_kpoint_mp_grid or similar in the .cell file. This permits the calculation of both a set of dispersion curves and a DOS from the same electronic run (DFPT/Interpolation or supercell). taking the result of a phonon calculation on a Monkhorst Pack grid of standard (not fine) phonon kpoints and performing Fourier interpolation as a post-processing step. switching interpolation methods between spherical and anisotropic schemes. All of the above could also be performed using castep rather than phonons provided care is taken not to change any parameters which control the properties of the \u201celectronic\u201d part of the calculation. However phonons can also perform some additional processing which castep can not, most notably isotopically substituted lattice dynamics calculations. dispersion.pl and dos.pl are also able perform very similar analysis and plotting of electronic eigenvalues from .castep or .bands files and generate band structure and electronic DOS plots. \u21a9 On linux systems xmgrace can usually be found as a contributed package and installed using the system package manager. Xmgrace is also available for Microsoft Windows systems as part of the \u201ccygwin\u201d suite of programs ( http://www.cygwin.com ) along with shells, the PERL interpreter and an X-windows server (Xmgrace is an X-windows program and requires a running X server to display). \u21a9 A more sophisticated model of infra-red spectra was introduced by Balan and Mauri (( Balan et al. 2001 ; Kendrick and Burnett 2016 ) and subsequent works). Modelling of inelastic neutron spectra is discussed by Fair ( Fair et al. 2022 ), Ramirez-Cuesta ( Ramirez-Cuesta 2004 ; Cheng and Ramirez-Cuesta 2020 ) \u21a9","title":"phonons"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/","text":"Phonon calculations even on small crystalline systems typically require many times the CPU resources of a ground state calculation. DFPT calculations of phonon dispersion compute dynamical matrices at a number of phonon wavevectors, each of which contains calculations of several perturbations. Each perturbation will typically require a large k-point set due to symmetry breaking by the perturbation. If the supercell method is used, converged calculations require a system of a typical size of a few hundred atoms, and many perturbations, although the k-point set used is smaller. Consequently, calculations on systems of scientific interest frequently require departmental, university or national-level supercomputing facilities, usually parallel cluster class machines. Much of the advice for effective use of cluster or supercomputer class resources is the same as for ground-state or other types of CASTEP calculations, but there are a few special considerations for phonon calculations, set out below. Among the particularly relevant general items are the choice of memory/speed tradeoff; usually the best approach is to select the highest speed option opt_strategy_bias : 3 1 which retains wavefunction coefficients in memory rather than paging to disk. For large calculations it is very frequently the case that that the memory requirement (in particular of the wavefunctions) is the most important consideration in choosing a parallel distribution. If a run fails due to exceeding the available memory per node, the processor count requested should be increased to distribute the wavefunction arrays across a larger set of processors, reducing the memory/processor requirement. If increasing the degree of parallel distribution is not possible, opt_strategy_bias can be reduced to 0 2 , which will page wavefunctions to disk. In that case it is vital to ensure that the temporary scratch files are written to high-speed disk (either local or a high-performance filesystem). This is usually controlled by setting the environment variable CASTEP_PAGE_TMPDIR to point to a directory on an appropriate filesystem 3 . Parallel execution CASTEP implements a parallel strategy based on a hierarchical distribution of wavefunction data by k-points, plane-waves, bands and OpenMP across processors 4 . In a phonon calculation this is used to speed up the execution within each perturbation and q-point which are still executed serially in sequence. Normally an efficient distribution is chosen automatically providing that the data_distribution parameter is not changed from the default value MIXED . K-points, plane-wave, band and task farm parallelism are all implemented using the Message-Passing Interface (MPI) system, and CASTEP must usually be launched by starting the executable using the mpiexec or similar commands, viz mpiexec -n 1024 castep.mpi which will start 1024 MPI processes and distribute the calculation across them. By contrast OpenMP parallelism is is activated by setting the environment variable CASTEP_NUM_THREADS : , which may be done before the mpiexec command to activate hybrid MPI+OpenMP mode. k-point and g-vector parallelism To best exploit the k-point component of the parallel distribution, the total number of the processors requested should be a multiple of the number of electronic k-points or have a large common divisor. The parallel distribution is printed to the .castep file, where in this example four k-points are used: Calculation parallelised over 32 nodes. K-points are distributed over 4 groups, each containing 8 nodes. For non-phonon CASTEP calculations it is sufficient to choose a processor count which is a multiple of N_{\\text{k}} N_{\\text{k}} , and that the degree of plane-wave-parallelism is not so large that efficiency is lost. However the choice of processor number in a phonon calculation is severely complicated by the fact that the number of electronic k-points in the irreducible Brillouin Zone changes during the run as the perturbations and phonon q-points have different symmetries. It is not convenient to compute the number for any perturbation individually without a detailed analysis, and some compromise between all of the perturbations should be chosen. To assist in this choice a utility program, phonon_kpoints is provided. This reads the configuration of the proposed calculation from the .cell file and is simply invoked by phonon_kpoints seedname It then determines and prints the k-point counts, and provides a \u201cfigure of merit\u201d for a range of possible processor counts. On most parallel architectures the efficiency of the plane-wave parallelism becomes unacceptable if there are fewer than around 200 plane-waves per node. It is usually possible to choose a processor count which allows a highly parallel run while keeping the number of plane-waves per node considerably higher than this. band parallelism From CASTEP version 24.1 band parallelism is implemented for FD calculations, but not yet DFPT. This may be enabled using a \u201cdevel-code\u201d string in the .param file 5 %block DEVEL_CODE PARALLEL:NBANDS=8:ENDPARALLEL %endblock DEVEL_CODE will attempt to set up 8-way band parallelism in addition to k-point and g-vector. perturbation parallelism From CASTEP release 24.1, a further level of parallelism called task-farming may be used to distribute perturbations across processors. This is set up and run in the same manner as for PIMD or NEB calculations by setting parameters file keyword num_farms : . The value of n n should not be too large, as the performance will be limited by load-balance issues, and in any case never greater than the number of perturbations. This will produce n n output files named _farm00.castep instead of the usual, single .castep file. Of these, _farm001.castep will contain the calculated final frequencies, Born effective charges etc. but a single instance of the .phonon , .efield , .phonon_dos and .check files are written as with other parallel schemes. hybrid OpenMP parallelism In addition to the above-described parallel distribution strategies - all based on MPI parallelism, CASTEP also offers a degree of OpenMP parallelism 6 . This can speed up some operations such as matrix diagonalisations and is activated by setting the environment variable CASTEP_NUM_THREADS : where n n in the range 2-16 is most effective (only a modest speed-up is accessible using OpenMP). However this can give a useful gain in addition to MPI parallelism especially in the case where compute nodes must be underpopulated because of memory requirements. Checkpointing and Restarting Even with a parallel computer, it is frequently the case that a calculation can not be completed in a single run. Many machines have a maximum time limit on a batch queue which may be too short. On desktop machines, run time may be limited by reliability and uptime limitations. CASTEP is capable of periodically writing \u201ccheckpoint\u201d files containing a complete record of the state of the calculation and of restarting and completing a calculation from such a checkpoint file. In particular dynamical matrices from complete q-points, and partial dynamical matrices from each perturbation are saved and can be used in a restart calculation. To enable the writing of periodic checkpoint files, set the parameter backup_interval 3600 which will write a checkpoint file named seedname .check every hour (the time is specified in seconds) or on completion of the next perturbation thereafter. To restart a calculation, set the parameter continuation : default in the .param file before resubmitting the job. This will attempt to read seedname .check and restart the calculation from there. Alternatively the full filename of a checkpoint file may be given as argument to the continuation keyword to read an explicitly named file. At the end of the calculation a checkpoint file seedname .check is always written. As with the intermediate checkpoint files this contains a (now complete) record of the dynamical matrices or force constant matrix resulting from phonon calculation. This may be analysed in a post-processing phase using the phonons utility. equivalent to opt_strategy : SPEED \u21a9 equivalent to opt_strategy : MEMORY \u21a9 If CASTEP_PAGE_TMPDIR is not set, the code falls back to the value of CASTEP_TMPDIR . \u21a9 k-points, plane-waves, bands correspond to indices of the wavefunction data, so parallelism in any of these will distribute the wavefunctions across MPI processes and reduce the memory/process requirement. \u21a9 This activation mechanism will be replaced by a \u201cfirst-class\u201d parameter to set parallelism in future releases of CASTEP. N.B. DEVEL_CODE is the only %block allowed in the .param file. \u21a9 See eCSE report for a description of the implementation and benchmark results \u21a9","title":"Running-Large-Calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#sec:parallelism","text":"CASTEP implements a parallel strategy based on a hierarchical distribution of wavefunction data by k-points, plane-waves, bands and OpenMP across processors 4 . In a phonon calculation this is used to speed up the execution within each perturbation and q-point which are still executed serially in sequence. Normally an efficient distribution is chosen automatically providing that the data_distribution parameter is not changed from the default value MIXED . K-points, plane-wave, band and task farm parallelism are all implemented using the Message-Passing Interface (MPI) system, and CASTEP must usually be launched by starting the executable using the mpiexec or similar commands, viz mpiexec -n 1024 castep.mpi which will start 1024 MPI processes and distribute the calculation across them. By contrast OpenMP parallelism is is activated by setting the environment variable CASTEP_NUM_THREADS : , which may be done before the mpiexec command to activate hybrid MPI+OpenMP mode.","title":"Parallel execution"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#k-point-and-g-vector-parallelism","text":"To best exploit the k-point component of the parallel distribution, the total number of the processors requested should be a multiple of the number of electronic k-points or have a large common divisor. The parallel distribution is printed to the .castep file, where in this example four k-points are used: Calculation parallelised over 32 nodes. K-points are distributed over 4 groups, each containing 8 nodes. For non-phonon CASTEP calculations it is sufficient to choose a processor count which is a multiple of N_{\\text{k}} N_{\\text{k}} , and that the degree of plane-wave-parallelism is not so large that efficiency is lost. However the choice of processor number in a phonon calculation is severely complicated by the fact that the number of electronic k-points in the irreducible Brillouin Zone changes during the run as the perturbations and phonon q-points have different symmetries. It is not convenient to compute the number for any perturbation individually without a detailed analysis, and some compromise between all of the perturbations should be chosen. To assist in this choice a utility program, phonon_kpoints is provided. This reads the configuration of the proposed calculation from the .cell file and is simply invoked by phonon_kpoints seedname It then determines and prints the k-point counts, and provides a \u201cfigure of merit\u201d for a range of possible processor counts. On most parallel architectures the efficiency of the plane-wave parallelism becomes unacceptable if there are fewer than around 200 plane-waves per node. It is usually possible to choose a processor count which allows a highly parallel run while keeping the number of plane-waves per node considerably higher than this.","title":"k-point and g-vector parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#band-parallelism","text":"From CASTEP version 24.1 band parallelism is implemented for FD calculations, but not yet DFPT. This may be enabled using a \u201cdevel-code\u201d string in the .param file 5 %block DEVEL_CODE PARALLEL:NBANDS=8:ENDPARALLEL %endblock DEVEL_CODE will attempt to set up 8-way band parallelism in addition to k-point and g-vector.","title":"band parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#perturbation-parallelism","text":"From CASTEP release 24.1, a further level of parallelism called task-farming may be used to distribute perturbations across processors. This is set up and run in the same manner as for PIMD or NEB calculations by setting parameters file keyword num_farms : . The value of n n should not be too large, as the performance will be limited by load-balance issues, and in any case never greater than the number of perturbations. This will produce n n output files named _farm00.castep instead of the usual, single .castep file. Of these, _farm001.castep will contain the calculated final frequencies, Born effective charges etc. but a single instance of the .phonon , .efield , .phonon_dos and .check files are written as with other parallel schemes.","title":"perturbation parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#hybrid-openmp-parallelism","text":"In addition to the above-described parallel distribution strategies - all based on MPI parallelism, CASTEP also offers a degree of OpenMP parallelism 6 . This can speed up some operations such as matrix diagonalisations and is activated by setting the environment variable CASTEP_NUM_THREADS : where n n in the range 2-16 is most effective (only a modest speed-up is accessible using OpenMP). However this can give a useful gain in addition to MPI parallelism especially in the case where compute nodes must be underpopulated because of memory requirements.","title":"hybrid OpenMP parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#sec:checkpointing","text":"Even with a parallel computer, it is frequently the case that a calculation can not be completed in a single run. Many machines have a maximum time limit on a batch queue which may be too short. On desktop machines, run time may be limited by reliability and uptime limitations. CASTEP is capable of periodically writing \u201ccheckpoint\u201d files containing a complete record of the state of the calculation and of restarting and completing a calculation from such a checkpoint file. In particular dynamical matrices from complete q-points, and partial dynamical matrices from each perturbation are saved and can be used in a restart calculation. To enable the writing of periodic checkpoint files, set the parameter backup_interval 3600 which will write a checkpoint file named seedname .check every hour (the time is specified in seconds) or on completion of the next perturbation thereafter. To restart a calculation, set the parameter continuation : default in the .param file before resubmitting the job. This will attempt to read seedname .check and restart the calculation from there. Alternatively the full filename of a checkpoint file may be given as argument to the continuation keyword to read an explicitly named file. At the end of the calculation a checkpoint file seedname .check is always written. As with the intermediate checkpoint files this contains a (now complete) record of the dynamical matrices or force constant matrix resulting from phonon calculation. This may be analysed in a post-processing phase using the phonons utility. equivalent to opt_strategy : SPEED \u21a9 equivalent to opt_strategy : MEMORY \u21a9 If CASTEP_PAGE_TMPDIR is not set, the code falls back to the value of CASTEP_TMPDIR . \u21a9 k-points, plane-waves, bands correspond to indices of the wavefunction data, so parallelism in any of these will distribute the wavefunctions across MPI processes and reduce the memory/process requirement. \u21a9 This activation mechanism will be replaced by a \u201cfirst-class\u201d parameter to set parallelism in future releases of CASTEP. N.B. DEVEL_CODE is the only %block allowed in the .param file. \u21a9 See eCSE report for a description of the implementation and benchmark results \u21a9","title":"Checkpointing and Restarting"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/","text":"CASTEP contains implementations of several methods for computing the electronic response orbitals and the dynamical matrix ( Refson, Tulip, and Clark 2006 ). There are implementation restrictions and the choice of the most suitable one depends on the type of calculation, the Hamiltonian, and the property calculations required. See table [captable] for details. For straightforward semi-local DFT calculations (LDA, PBE etc.) the density-functional perturbation theory method (DFPT) method is preferred (section [dfpt-gamma] ), as this is not only the most efficient, but also allows the calculation of infra red and Raman intensities for modelling of spectra. DFPT is not yet implemented for ultrasoft pseudopotentials, or for Hubbard U or some dispersion-corrected DFT methods (as of release 24.1), and in these cases the finite displacement method should be used (section [fd] ). If a density of states or finely sampled dispersion curve along high symmetry directions is needed, then either the DFPT method with Fourier interpolation (section [ddos] ) is the most suitable or the finite-displacement supercell (section [supercell] ; if ultrasoft pseudopotentials are required). A summary of the recommended approach for various property calculations is given in table [method-selection] . DFPT (Phonon) DFPT (E-field) FD (Phonon) USP \u2718 \u2718 \u2713 NCP \u2713 \u2713 \u2713 LDA, GGA \u2713 \u2713 \u2713 MGGA \u2718 \u2718 \u2713 DFT+U \u2718 \u2718 \u2713 NCM/SOC \u2718 \u2718 \u2713 PBE0, Hybrid XC \u2718 \u2718 \u2713 DFT+D: TS, D2 \u2713 \u2713 \u2713 DFT+D: D3,D4, MBD*,XDM \u2718 \u2713 \u2713 Table 1: CASTEP phonons implementation matrix. In general DFPT is avalable for semilocal DFPT, but not other Hamiltonians. The combination of DFPT and USPs is not implemented. Target Property Preferred method IR spectrum DFPT at q=0 with NCP potentials (section. [dfpt-gamma] ) FD at q=0 with NCP potentials and DFPT e-field (section. [fd] ) FD at q=0 with USP potentials and Berry Phase Z^{*} Z^{*} (section. [berry-fd] ) Raman spectrum DFPT at q=0 with NCP potentials (2n+1 theorem) (section. [raman] ) Born Effective Charges ( Z^{*} Z^{*} ) DFPT E-field using NCP potentials (section. [efield] ) FD at q=0 with USP potentials and Berry Phase Z^{*} Z^{*} (section. [berry-fd] ) Dielectric Permittivity ( \\epsilon_\\infty \\epsilon_\\infty ) DFPT E-field using NCP potentials (section. [efield] ) Nonlinear optical susceptibility ( \\chi^{(2)} \\chi^{(2)} ) DFPT E-field (2n+1 theorem) using NCP potentials (section. [nlo] ) Phonon dispersion or DOS DFPT plus interpolation with NCP potentials (section. [ddos] ) FD plus interpolation using USP or NCP potentials (section. [ndsc] ) FD with supercell using USP or NCP potentials (section. [supercell] ) Vibrational Thermodynamics same as DOS (section. [thermodynamics] ) Table 2: Available and recommended methods for different property calculations. A DFPT phonon calculation at the \\Gamma \\Gamma -point Many of the principles of setting up and running phonon calculations can be illustrated in the simplest case - computing phonon frequencies at the q=(0,0,0) q=(0,0,0) , often referred to as the \\Gamma \\Gamma point. This is a very common calculation, as it forms the basis of modelling of infra-red or Raman spectra and group theoretical analysis and assignment of the modes. Input files The setup for a CASTEP phonon calculation requires a few additional keywords in the seedname .cell file. Like any type of calculation, the unit cell must be specified using either of %block LATTICE_ABC or %block LATTICE_CART , and the atomic co-ordinates using %block POSITIONS_FRAC or %block POSITIONS_ABS . Figure [example-gamma] shows a complete input file for a calculation on boron nitride in the hexagonal Wurtzite structure. The additional keywords. phonon_kpoint_list is used to specify that a single phonon wavevector (0,0,0) is to be computed 1 . More wavevectors could be specified using additional lines in this block. 2 %block LATTICE_ABC 2.536000 2.536000 4.199000 ! a, b, c 90.000000 90.000000 120.000000 ! alpha, beta, gamma %endblock LATTICE_ABC %block POSITIONS_FRAC B 2/3 1/3 0.000000 ! Atom co-ordinates in crystallographic N 2/3 1/3 0.374536 ! fractional system. B 1/3 2/3 0.500000 N 1/3 2/3 0.874536 %endblock POSITIONS_FRAC %block SPECIES_POT B B_00.recpot ! File names of pseudopotential to use for B N N_00.recpot %endblock SPECIES_POT kpoints_mp_spacing 0.07 ! Generate MP grid of electronic k-points. symmetry_generate ! Find symmetry operations of crystal structure %block PHONON_KPOINT_LIST 0.0 0.0 0.0 1.0 ! Wavevector of phonon(s) to compute ( qx qy qz, weight) %endblock PHONON_KPOINT_LIST task : PHONON ! Choose a phonon calculation xc_functional : LDA opt_strategy : SPEED ! Optimise for speed over memory saving cut_off_energy : 700.0 eV ! Plane-wave cutoff for this system elec_method : DM ! Use fast DM solver even for insulating system phonon_sum_rule : TRUE ! Enforce acoustic sum rule on calculated D Figure 1: Annotated example cell and parameter files for BN in the Wurtzite structure. Note that phonon_method defaults to DFPT . Reading the output Figure [example-gamma-out] shows part of the phonon-relevant output extracted from the .castep file obtained by running the input files of the previous section. There are several blocks of output, one per direction chosen for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 in the LO-TO splitting terms. Note that CASTEP has added a calculation without LO-TO splitting (the first block), even though this was not explicitly requested. Within each block frequencies are listed one per line. Also on the line are (a) a label indicating the irreducible representation of the mode from a group theory analysis, (b) the computed absorptivity of the mode in a powder (or otherwise orientationally averaged) infrared experiment, \u00a9 whether the mode is IR active, (d) the Raman activity (if computed) and (e) whether the mode is Raman active. ============================================================================== + Vibrational Frequencies + + ----------------------- + + + + Performing frequency calculation at 1 wavevector (q-pt ) + + ========================================================================== + + + + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 1.0000000000 + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.049170 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1016.312039 a 28.5895083 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1051.124801 b 25.8079204 Y Y + + 12 1123.472590 d 0.0000000 N N + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + Figure 2 Output in the .castep file generated by the preceding input files for wurtzite BN. The columns show the mode frequencies, a letter labelling of the irreducible representation of the mode, the infrared absorptivity and Raman activity, and whether or not the mode is Raman and/or IR active. Not all of these are present in every calculation depending on the use of symmetry and input options. + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 0.0000000000 + + q->0 along ( 0.000000 0.000000 1.000000) + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.037851 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1051.124801 b 25.8079204 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1123.472590 d 0.0000000 N N + + 12 1262.933291 a 28.5895083 Y Y + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + (Due to LO/TO splitting this character table may not contain some symmetry + + operations of the full crystallographic point group. Additional + + representations may be also be present corresponding to split LO modes. + + A conventional analysis can be generated by specifying an additional null + + (all zero) field direction or one along any unique crystallographic axis + + in %BLOCK PHONON_GAMMA_DIRECTIONS in .cell.) + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + ============================================================================== Figure 2 Run output (continued): If the LO-TO-splitting calculation is active the \\Gamma \\Gamma point frequency table is repeated, both without and including the non-analytic contribution which generates the LO/TO splitting in one or more directions (See Gonze and Lee ( Gonze and Lee 1997 )). (The group theory analysis for LO modes is less useful than might be wanted and is likely to be the subject of future developments.) As with other calculations the amount of information written to the .castep file is controlled by the value of the parameter iprint . The levels of output are iprint : 0 Minimal output as in figure [example-gamma-out] . No progress info. iprint : 1 As for iprint : 0 but including a reassuring progress report of q-points and perturbations. iprint : 2 More detailed output including details of k-points and symmetry for each perturbation, cycle-by cycle DFPT minimiser report, printing of dynamical matrices (and force constant matrices). In addition to the user-readable output in the .castep file 3 , every phonon calculation generates an additional output file with the suffix .phonon which is intended for postprocessing analysis by other programs. This includes not only the frequencies but also the eigenvectors {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} resulting from diagonalising the dynamical matrix. These eigenvectors are orthonormal and the relationship between the eigenvectors and atomic displacements is given by u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) where Q_M Q_M is the amplitude of mode m m and the other notation is as set out in the introduction. Raman activity calculations In addition to the infrared absorptivity computed as a default part of a \\Gamma \\Gamma -point phonon calculation, CASTEP is also capable of computing the Raman activity tensors in the case of non-resonant scattering for an insulating system 4 . This calculation uses an extension of DFPT known as the \u201c2n+1 theorem\u201d ( Baroni et al. 2001 ; Miwa 2011 ) which requires substantially more computational effort than a bare phonon calculation and is therefore not enabled by default. To compute Raman activity set calculate_raman : TRUE in the .param file, which calculates and prints the Raman atomic susceptibility tensors and the mode susceptibility tensors to the .castep file. These may be extracted for use when modelling the Raman scattering in a polarised single-crystal geometry. 5 As with the Born effective charges and dynamical matrices, there is a sum rule on the values of the atomic polar tensors, which may not be well satisfied because of numerical approximations. A correction will be applied if parameter raman_sum_rule : TRUE is set. A 3d-average Raman activity (see Porezag and Pedersen ( Porezag and Pederson 1996 )) is computed from the susceptibility tensors and printed as an additional column in the usual frequency output given in figure [example-gamma-out] . This may be used for simple modelling of a powder spectrum, for example using the dos.pl tool (see section [dos-pl] ). Dispersion and density of states Phonons of a nonzero wavevector play an important role in the thermophysical properties of crystalline solids and the physics of many solid-state phase transitions. Proving the mechanical stability of a crystal structure by testing for real frequencies requires a vibrational calculation over the full Brillouin Zone. And dispersion curves and densities of states are frequently required for comparison with inelastic neutron and X-ray scattering experiments. One of the benefits of density functional perturbation theory is that CASTEP can calculate vibrational modes at {\\mathbf{q}}\\ne \\mathbf{0} {\\mathbf{q}}\\ne \\mathbf{0} as easily as at {\\mathbf{q}}= \\mathbf{0} {\\mathbf{q}}= \\mathbf{0} (but at the cost of an increase in CPU time due to the decreased symmetry). It is possible to perform this calculation simply by providing a list of q-points in the .cell file ( using one of the blocks %block PHONON_KPOINT_LIST , or %block PHONON_KPOINT_PATH or keyword phonon_kpoint_mp_grid ). However to generate a reasonable quality dispersion plot or density of states will usually require hundreds or thousands of q-points. The time required by such a calculation would be several hundred times that for a single-point energy and therefore infeasibly large. Fortunately there is a way to achieve the same result at a far smaller computational cost. This method exploits the fact that the interatomic interactions in a solid have a finite range and decay rapidly to zero. Specifically, the elements of the force constant matrix in Eq. [fcmat] decrease as 1 / r^{5} 1 / r^{5} with interatomic distance. Consequently the dynamical matrix defined by Eq. [dmat] and its eigenvalues \\omega^{2}({\\mathbf{q}}) \\omega^{2}({\\mathbf{q}}) are smoothly varying with wavevector {\\mathbf{q}} {\\mathbf{q}} . Fourier interpolation is used to generate dynamical matrices on an arbitrarily fine grid or linear path in reciprocal space from a set of DFPT calculations on a much coarser grid. For a full description of the method see references ( Baroni et al. 2001 ; Giannozzi et al. 1991 ; Gonze and Lee 1997 ). A complication arises in the case of polar solids where the dipole-dipole interaction generated upon displacing an atom leads to a longer ranged force constant matrix which decays only as 1 / r^{3} 1 / r^{3} . CASTEP models this term analytically using Born effective charges and dielectric permittivity calculated using an electric field response DFPT calculation (see section [efield] and Ref. ( Gonze and Lee 1997 )). It is therefore able to perform the Fourier interpolation for only the part of the force constant matrix which varies as 1 / r^{5} 1 / r^{5} , and does not require a finer grid than in the case of non-polar solids. Setting up an interpolation calculation In the .cell file choose the q-points of the coarse grid of points at which to perform DFPT calculations. This may be specified as a %block PHONON_KPOINT_LIST containing the reduced set of points in the irreducible Brillouin Zone, but is is almost always more straightforward to use the alternative keywords phonon_kpoint_mp_grid : p q r phonon_kpoint_mp_offset : INCLUDE_GAMMA to specify the grid parameters and offset 6 . The grid parameters p , q and r should normally be chosen to give a roughly uniform sampling of reciprocal space taking length of the reciprocal lattice vectors into account, and should be compatible with the symmetry of the simulation cell. Alternatively a grid may be specified using the minimum spacing, for example phonon_kpoint_mp_grid_spacing 0.1 1/ang Normally the grid should be chosen to contain the \\Gamma \\Gamma point, which usually gives better convergence properties of the interpolation ( i.e.*convergence at smaller *p,q,r ) than otherwise. This is the opposite behaviour to electronic k-point sampling (see Ref. ( Probert and Payne 2003 )). The special keyword value phonon_kpoint_mp_offset : INCLUDE_GAMMA avoids the need to work out the offset explicitly. The choice of grid parameters p , q and r is governed by three considerations: For a 3-dimensional crystal, p,q,r should obey the crystallographic symmetry , so for a cubic or rhombohedral crystal you should set p = q = r p = q = r . In the case of a uniaxial crystal, such as tetragonal or hexagonal we have p = q \\neq r p = q \\neq r (assuming that c c is the unique axis) and for lower symmetry there is no constraint. The value in any of the directions limits the range of the force constant matrix in much the same way as the supercell multiplier does in a finite-difference/supercell calculation (Section [supercell] ). Exactly how large this should be depends on the nature of the chemical bonding. Ionically bonded systems tend to have fairly short-ranged force-constant matrices and need relatively coarse grids for convergence. For sodium chloride in the rocksalt structure with a primitive lattice parameter 3.75\u00c5 a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 grid is reasonably close to convergence. This corresponds to a truncation of the force constant matrix at a distance of approximately 7 7 \u00c5 ( \\approx p \\times 2 \\pi / a \\approx p \\times 2 \\pi / a ). On the other hand covalent systems tend to have fairly long-ranged force-constant matrices and need finer grids for convergence. Silicon is a good example of this. The primitive lattice parameter is similar to sodium chloride at 3.81 3.81 \u00c5, but the dispersion curve is not fully converged until an 8 \\times 8 \\times 8 8 \\times 8 \\times 8 grid is used. A more detailed examination of this point may be found in reference ( Ackland, Warren, and Clark 1997 ). While there is no essential physics relationship between the grid sizes for phonon {\\mathbf{q}} {\\mathbf{q}} -points and that required for electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling 7 , there is a technical connection resulting from the implementation of density-functional perturbation theory and the requirement to generate and use ground-state Kohn-Sham wavefunctions on grids containing both \\{{\\mathbf{k}}\\} \\{{\\mathbf{k}}\\} and \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} (See ref. ( Gonze 1997 ) for the mathematical details). For best performance and stability of the DFPT calculation the phonon grid parameters should be commensurate with the electronic grid with an exact divisor as the simplest case. For example, in an elemental metal with an hcp structure such as Mg, an electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling of 21 \\times 21 \\times 12 21 \\times 21 \\times 12 and a phonon {\\mathbf{q}} {\\mathbf{q}} -point sampling of 7 \\times 7 \\times 6 7 \\times 7 \\times 6 might be most effective. This is not a hard requirement and CASTEP will attempt to work with whatever grids are specified, but in some cases there may be a performance advantage to rounding up one or other of the grids to meet the commensurability criterion. Additional keywords in the .param file control the interpolation. Most importantly phonon_fine_method : INTERPOLATE instructs CASTEP to perform the Fourier interpolation step following the usual DFPT calculation. The target set of wavevectors for the interpolation is set up using additional keywords or blocks in the .cell file. Either phonon_fine_kpoint_mp_grid p q r phonon_fine_kpoint_mp_offset o _1 _1 o _2 _2 o _3 _3 or phonon_fine_kpoint_mp_spacing 0.03 1/ang . will perform interpolation onto a regular (possibly offset) grid. In fact only the points in the irreducible wedge of the Brillouin Zone are included, and a suitable weight is computed so that the weighted average is identical to a uniform sampling of the BZ. This is the usual method for computing a phonon density of states. If a set of dispersion curves along high symmetry directions is required, an empty cell keyword block %block PHONON_FINE_KPOINT_PATH %endblock PHONON_FINE_KPOINT_PATH will internally generate a list of {\\mathbf{q}} {\\mathbf{q}} -points sampling a default path through the Brillouin-Zone according to the symmetry of the calculation. Alternatively a list of {\\mathbf{q}} {\\mathbf{q}} -points explicitly specifying the vertices of the path may be input as %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 0.5 0.5 0.5 break 0.0 0.0 0.0 0.5 0.5 0.5 ... %endblock PHONON_FINE_KPOINT_PATH which traverses the directions between the vertices specified, except in the presence of the break keyword where the path jumps without including any intermediate points. The fineness of sampling along the path is set by an additional keyword phonon_fine_kpoint_path_spacing : 0.03 1/ang . As a final alternative, a simple list of points can be directly input to model any sampling you choose using %block PHONON_FINE_KPOINT_LIST 0.0 0.0 0.0 0.1 0.2 0.3 ... %endblock PHONON_FINE_KPOINT_LIST This is the approach used for files generated by Accelrys Materials Studio. The same keywords are used in the closely related method of a finite difference calculation; see the example .cell file of figure [al-sc-cell] . Continuation CASTEP stores the results of all phonon calculations - dynamical matrices and force constant matrices - in the binary seedname .check file written at the end of a successful run. This can be used to change some values of parameters relating to interpolation, and to change or indeed replace the entire fine phonon k-point set without any need to repeat the expensive DFPT (or supercell) part of the calculation. In fact a single calculation of the force constant matrix is sufficient to compute a DOS at a variety of sampling densities plus arbitrarily smooth dispersion curves. Setting up a continuation calculation is simple. Just add the continuation keyword in the usual way to a renamed copy of the param file continuation orig-seedname .check and make any changes to the fine phonon k-point sampling parameters in a copy of the seedname .cell file. It is recommended that you work with renamed copies to avoid overwriting the original and valuable seedname .check file. Running CASTEP on the new set of input files is exactly the same as running a new calculation, except that the result will be generated much more quickly. When setting up a continuation run, take care not to change the standard phonon k-point set, the electronic k-point set or any electronic structure parameters such as elec_energy_tol . If a mismatch is detected with the values stored in the checkpoint file, CASTEP will discard the saved dynamical matrix data and restart the full calculation from the beginning. Continuation calculations are also used in conjunction with checkpointing where a partially complete calculation is written to a file, also in .check format and which may be used to restart an interrupted calculation. See section [checkpointing] for a description. Control of interpolation scheme The final representation of the force constant matrix derived from the dynamical matrices is actually a periodic representation and is equivalent to the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a (fictitious) p \\times q \\times r p \\times q \\times r supercell. (See section [supercell] for more explanation.) CASTEP must determine a mapping between elements of the periodic dynamical matrix and aperiodic force constant matrix using a minimum-image convention for ionic site pairs and impose a cutoff scheme in real space to exclude (supercell-) periodic images. In fact CASTEP implements two distinct schemes. The cumulant scheme ( Parlinski, Li, and Kawazoe 1997 ) includes all image force constants with a suitable weighting to avoid multiple counting of images. This is achieved by including image force constants in any direction if they lie within half the distance to the nearest periodic repeat of the fictitious supercell lattice in that direction. If an atom-atom pair vector lies exactly half way to the supercell repeat so that image force constants occur, for example, at both \\mathbf{L} \\mathbf{L} and -\\mathbf{L} -\\mathbf{L} , all images at the same distance are included with a suitable weighting factor to preserve the symmetry of the cumulant force constant matrix. (See Refs. ( Parlinski, Li, and Kawazoe 1997 ) and ( Ye et al. 2004 ) for a more detailed explanation). This scheme is selected by specifying the param file keyword phonon_fine_cutoff_method CUMULANT and is in fact the default method in CASTEP. CASTEP also implements a simple spherical cutoff, controlled by the parameter R_c R_c and specified by parameter phonon_force_constant_cutoff 10.0 ang The value R_c R_c should be chosen to satisfy 2 R_c < min(p L_1,q L_2,r L_3) L 2 R_c < min(p L_1,q L_2,r L_3) L where L_n L_n is the cell edge of the simulation cell and p,q,r p,q,r are the (coarse) grid of phonon wavevectors. It is usually easiest to specify a value of zero, in which case CASTEP chooses the largest allowable value automatically. This scheme is most suitable for bulk materials of cubic symmetry. The spherical scheme is chosen using keyword phonon_fine_cutoff_method SPHERICAL . Within the default method a smaller cutoff volume can be decreased by a radius scaling factor, e.g. phonon_force_constant_cut_scale : 1.0 . This may be useful for testing the effect of long-ranged contributions to the IFC matrix. However any departure of this parameter\u2019s value from 1 does not preserve the superior convergence properties of the cumulant scheme and will in general require a larger supercell than the exact cumulant method. Acoustic Sum Rule correction The vibrational Hamiltonian is invariant to a uniform translation of the system in space. This symmetry is the origin of the well-known result that any crystal has three acoustic vibrational modes at {\\mathbf{q}}=0 {\\mathbf{q}}=0 with a frequency of zero. This leads to the so-called acoustic sum rule (or ASR) ( Ackland, Warren, and Clark 1997 ; Pick, Cohen, and Martin 1970 ) which has mathematical expressions for the force constant and \\Gamma \\Gamma -point dynamical matrices \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} In plane-wave calculations the translational invariance is broken as atoms translate with respect to the fixed FFT grid, so the sum rule is never exactly satisfied. Consequently it is sometimes observed even in an otherwise apparently very well converged calculation that the three acoustic modes at \\Gamma \\Gamma depart significantly from zero frequency. Depending on the XC functional 8 these frequencies may reach or exceed 50 cm ^{\\text{-1}} ^{\\text{-1}} . One solution is simply to increase number of grid points of CASTEP\u2019s \u201cfine\u201d FFT grid used for densities and potentials by increasing fine_grid_scale 9 . (N. B. This is distinct from grid_scale which controls the FFT grid used to represent wavefunctions.) However this can be very costly in computer time and memory. Provided that the amplitude of the symmetry violation is not too large, it is possible to apply a transformation to the computed dynamical or force constant matrix so that it exactly satisfies the ASR. CASTEP implements a scheme which projects out the acoustic mode eigenvectors and adjusts their frequency to zero, while having minimal impact on the optic mode frequencies. This scheme is controlled by parameters (in the .param file) phonon_sum_rule_method : REAL / RECIP / REAL-RECIP / NONE The first of these simply activates or deactivates the correction. The second chooses which of the variants of the ASR in equation [asr] to enforce, the real-space force constant matrix, the reciprocal-space dynamical matrix, or both. ( phonon_sum_rule_method : NONE is a synonym for phonon_sum_rule : FALSE ). The real-space method is only applicable to interpolation or supercell/finite displacement calculations, but the reciprocal-space method can be used for any type of phonon calculation. Both variants change the acoustic mode frequencies away from but near {\\mathbf{q}}=0 {\\mathbf{q}}=0 , the realspace method implicitly, and the reciprocal space method explicitly, by determining the correction to {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} and subtracting it from {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} as suggested by Gonze ( Gonze and Lee 1997 ). This usually results in acoustic mode behaviour which is indistinguishable from a very well converged calculation using a very fine FFT grid 10 . In addition to the sum rule on frequencies there is another for the Born effective charges (see section [efield] ) \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 which is activated by parameter born_charge_sum_rule : TRUE The default behaviour of CASTEP is that neither sum rule is enforced. If this was not requested in the original run, then it may be added in post-processing fashion in a continuation run, as per section [continuation] . Only the raw dynamical and/or force constant matrices are stored in the checkpoint file without the effect of ASR enforcement, which is only applied at the printout stage. Therefore the effect can be turned off, or altered by a post-processing calculation as well as turned on. Density of States The definition of the phonon density of states requires an integration of the calculated frequencies \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} over the Brillouin-Zone g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . A simple computational approximation would be to compute \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} on a regular, discrete grid of {\\mathbf{q}} {\\mathbf{q}} , replace the integral with a sum over the grid and convolute the result with some peak shape function h(\\omega) h(\\omega) such as a Gaussian g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . In the CASTEP toolset, this is implemented by performing a Fourier interpolation calculation onto a suitably fine {\\mathbf{q}} {\\mathbf{q}} -point set, specifying either phonon_fine_kpoint_mp_grid or phonon_fine_kpoint_mp_spacing . The resulting .phonon file may then be analysed using the dos.pl tool (see section [dos-pl] ) which implements equation [broadendos] . However the broadening smooths out any sharp features of the DOS, and fails to reproduce the smoothly-curved or sharply peaked segments typical of theoretical densities-of-states. This is discussed in more detail in references ( Yates et al. 2007 ) and ( Pickard 1997 ). A more faithful rendering may be obtained using the so-called adaptive broadening approach of Yates et. al ( Yates et al. 2007 ) which uses the gradients of the phonon branch dispersion to narrow or widen the broadening for flat or steep branches respectively. It is activated by the parameters keyword phonon_calculate_dos : TRUE which computes an adaptively-broadened DOS during the Fourier interpolation stage of the calculation and writes an output file named .phonon_dos containing the tabulated DOS, plus the per-atomic-species resolved DOS in additional columns. The dos.pl script is able to read and present .phonon_dos files just as with .phonon . The range and resolution may be modified using additional parameters, for example phonon_dos_spacing : 0.01 THz phonon_dos_limit : 10.0 THz Example output for the phonons of diamond is shown in figure [c2-pdos] . Figure 3 Phonon DOS for Diamond, with an 18^3 18^3 fine grid comparing Gaussian broadened (red) vs adaptively broadened (black) methods. Artefactual wiggles are clearly visible in the Gaussian-broadened case, and the height of the sharp peaks is not well reproduced. Finite Displacement In addition to the DFPT method of computing force constants, CASTEP implements schemes based on numerical differentiation of forces when atoms are displaced by a small amount from their equilibrium positions. This method is useful for cases where DFPT has not been implemented, which as of CASTEP release 24.1 includes ultrasoft pseudopotentials, Hubbard U and exact exchange and hybrid functionals, and some of the newer classes of dispersion correction. There are three variants of this scheme. Primitive Cell Finite Displacement The basic finite displacement method is selected by setting parameter phonon_method : FINITEDISPLACEMENT In contrast to DFPT such displacements are necessarily periodic with the simulation cell, and therefore only {\\mathbf{q}}=0 {\\mathbf{q}}=0 phonons are commensurate with this condition. As in the case of DFPT lattice dynamics the phonon wavevectors are specified by %block PHONON_KPOINT_LIST , %block PHONON_KPOINT_PATH or phonon_kpoint_mp_grid in the .cell file but only the \\Gamma \\Gamma point, (0,0,0) (0,0,0) is meaningful. CASTEP will print a warning in the output file and ignore any non-zero value in the list. CASTEP proceeds by shifting each atom by a small amount, then performing a SCF calculation to evaluate the forces on the perturbed configuration. Both positive and negative displacements are performed in each direction so that the corresponding force constants can be evaluated using the accurate \u201ccentral difference\u201d method of numerical differentiation. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. Equation [finite-diff] demonstrates that a single pair of displaced calculation yields an entire row of the dynamical matrix. As with DFPT calculations, only the minimal set of perturbations is performed and the space-group symmetry is used to build the complete dynamical matrix. The SCF calculations on the perturbed configuration are efficient, typically taking only only a few cycles in CASTEP 5.0 or later. This efficiency is achieved by first making a good guess for the electron density of the perturbed system based on the ground state of the unperturbed system, and applying a displacement of an atomic-like density of the pseudo-atom in question. Second, the SCF is started using the Kohn-Sham orbitals of the unperturbed state as the initial guess for the perturbed configuration. To exploit this efficiency it is essential to use the density-mixing (Davidson) minimiser, selected by elec_method : DM in the .param file. (As the all-bands method has no means of initialising the density). The default displacement used is 0.01 0.01 bohr This can be changed if necessary by setting a parameter, phonon_finite_disp : 0.02 ang in the .param file. Except for the differences discussed above, input and output formats are the same as for DFPT calculations. Born Charges, Permittivity and LO/TO splitting with FD FD phonon calculations are useful where atomic-displacement response DFPT is not implemented, notably for ultrasoft pseudopotentials (USPs) and post-DFT exchange and correlation including LDA+U, SOC, hybrid functionals (see table [captable] ). However properties including IR spectral intensity, LO/TO splitting and the effectiveness of Fourier interpolation of dynamical matrices depend on the Born effective charges and dielectric permittivity (see section [efield] ), whose calculation by electric field response DFPT is not implemented. In some cases it may be convenient to read in externally computed or approximate values of Born charges and permittivity to be used to calculate IR spectra, LO/TO splitting etc. For example, a DFT+U, meta-GGA, or hybrid calculation might make use of values calculated using PBE-DFPT and NCPs as a fair approximation, or even computed using a different DFT code. This may be accomplished by specifying the name of an external file containing the values (in this case BORN.DAT ) in the .param file %block DEVEL_CODE PHONON:READ_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE The file should be formatted as for the Phonopy code ( https://phonopy.github.io/phonopy/input-files.html#born-optional ). A file of this format may be written at the end of a DFT, NCP E-field response calculation by %block DEVEL_CODE PHONON:WRITE_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE Born charges from Berry Phase Polarization As of CASTEP release 25.1, it will be possible to calculate Born effective charges (but not dielectric permittivity) using a finite-difference numerical differentiation of the Berry-phase polarization. This is performed as an adjunct to the FD phonon calculation, and will be automatically selected in the case of an FD phonon calculation with USPs. This works for any compatible Hamiltonian, including DFT+U, mGGAs such as rSCAN as well as hybrid XC functionals. Finite Displacement using non-diagonal supercells As with the DFPT method, calculation of phonon dispersion and DOS using the finite displacement method is achieved using Fourier interpolation of dynamical matrixes. First, an approximation of the full force-constant-matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is calculated by explicitly computing a set of {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} with {\\mathbf{q}} {\\mathbf{q}} sampling a coarse grid of {\\mathbf{q}} {\\mathbf{q}} and using the inverse Fourier relation to equation [dmat] . Then equation [dmat] is used to generate the dynamical matrices at all of the (fine) phonon wavevectors required. The key step of computing every {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} on the \u201ccoarse\u201d regular grid is achieved by constructing a list of supercells commensurate with each of the coarse {\\mathbf{q}} {\\mathbf{q}} -points in turn (so that {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi where T_{\\text{SC}} T_{\\text{SC}} is a lattice vector of that supercell). This {\\mathbf{q}} {\\mathbf{q}} maps to a \\Gamma \\Gamma point calculation on the corresponding supercell despite being incommensurate with the primitive cell, and {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} for the primitive cell at {\\mathbf{q}} {\\mathbf{q}} may be extracted using equation [dmat] . It was shown by Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ) that by using so-called non-diagonal supercells such a set need contain only the least common multiple of the coarse grid subdivisions ( p, q, r p, q, r ). Consequently the number of distinct supercell calculations requires is much smaller than the number of {\\mathbf{q}} {\\mathbf{q}} -vectors of the grid, and most importantly increases with the linear dimension of the grid instead of the product. A non-diagonal supercell calculation is selected by setting the parameters phonon_method : FINITEDISPLACEMENT phonon_fine_method : INTERPOLATE , the cell keywords phonon_kpoint_mp_grid : p q r and one of the specifications of phonon_fine_kpoints exactly as in the case of a DFPT calculation. When the phonon calculation begins, CASTEP generates a list of supercells using the algorithm of Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ). For each of these, CASTEP generates the corresponding supercell and performs a finite-displacement phonon calculation. The dynamical matrices {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} are then extracted for each {\\mathbf{q}} {\\mathbf{q}} on the coarse KPOINT grid, and the calculation proceeds exactly as if the DFPT method has been used. The choice of coarse {\\mathbf{q}} {\\mathbf{q}} -point sampling set by phonon_kpoint_mp_grid requires one additional consideration compared to the DFPT case to give best computational performance. The supercell-generation algorithm of Lloyd Williams and Monserrat guarantees that the largest supercell in the generated list contains N_\\text{SC} = \\text{LCM} (p, q, r) N_\\text{SC} = \\text{LCM} (p, q, r) replications of the primitive cell. For example, an 4 \\times 4 \\times 4 4 \\times 4 \\times 4 sampling of a cubic cell gives N_\\text{SC} = 4 N_\\text{SC} = 4 . However a 2 \\times 3 \\times 4 2 \\times 3 \\times 4 sampling of an orthorhombic primitive cell yields N_\\text{SC} = 12 N_\\text{SC} = 12 , the LCM of 4 and 3. In that case it might be more efficient to use a 2 \\times 4 \\times 4 2 \\times 4 \\times 4 sampling which only requires N_\\text{SC} = 8 N_\\text{SC} = 8 for the largest of the generated supercells. As well as the {\\mathbf{q}} {\\mathbf{q}} -point sampling, FD interpolation calculations require one further parameter choice, namely to select the electronic k-point sampling for the supercell calculations. This may most conveniently be set using the cell keyword supercell_kpoint_mp_spacing : 0.1 1/ang . An explicit setting of grid sampling divisions with supercell_kpoint_mp_grid would be inappropriate as the correct choice will be different for each supercell, and unknown until run-time. By default CASTEP chooses a default spacing which is consistent with the primitive cell spacing, in an attempt to achieve a consistent level of convergence across supercells. Apart from the above two considerations, the setting up and execution of the FD interpolation follows exactly the same lines as with DFPT. In particular sum-rule, DOS and thermodynamics calculations and interpolation scheme tweaks apply identically. Legacy Finite Displacement/Supercell The limitation of the primitive-cell finite displacement approach to {\\mathbf{q}}=0 {\\mathbf{q}}=0 may also be overcome by combining the method with the use of a supercell. This method, sometimes known as the \u201cdirect method\u201d ( Kunc and Martin 1982, sec. 19.2 ) relies on the short-ranged decay of the force constant matrix with interatomic distance and makes the assumption that force constants for separations larger than some value, R_c R_c are negligibly small and can be treated as zero. A supercell can be constructed to contain an imaginary sphere of radius R_c R_c beyond which force constants may be neglected. Then the dynamical matrix of a supercell satisfying L > 2 R_{c} L > 2 R_{c} is identical to the force constant matrix , i.e. {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} . Therefore complete knowledge of the force constant matrix to a reasonable approximation may be derived from a single calculation of the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a supercell containing several primitive cells. From this set of force constants the dynamical matrices at any phonon wavevector may be computed using equation [dmat] in exactly the same way as used in an interpolation calculation. Note: This method is mostly superceded by the non-diagonal supercell/finite displacement approach of section [ndsc] . That method gives an equivalent calculation of the force constant matrix, usually with a smaller computational cost, because of its superior scaling with cell size. %block LATTICE_CART 0 2.02475 2.02475 2.02475 0 2.02475 2.02475 2.02475 0 %endblock LATTICE_CART %block POSITIONS_ABS Al 0 0 0 %endblock POSITIONS_ABS %block SPECIES_POT Al Al_00.usp %endblock SPECIES_POT kpoint_mp_grid 14 14 14 supercell_kpoint_mp_grid 2 2 2 symmetry_generate %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 1.0 1.0 1.0 0.5 0.5 0.5 0.5 0.5 0.0 0.5 0.75 0.25 0.5 0.5 0.5 %endblock PHONON_FINE_KPOINT_PATH %block PHONON_SUPERCELL_MATRIX -3 3 3 3 -3 3 3 3 -3 %endblock PHONON_SUPERCELL_MATRIX Figure 4 Example cell file for aluminium supercell phonon calculation. This calculation computes a set of dispersion curves along high-symmetry directions. Note that this calculation is not fully converged with supercell size - there is a noticeable change in frequency on some of the branches on increasing the supercell matrix entries from 3 to 4. task : PHONON phonon_fine_method : SUPERCELL phonon_calc_lo_to_splitting : FALSE phonon_sum_rule : TRUE calculate_born_charges : FALSE phonon_force_constant_ellipsoid : 1.0 cut_off_energy : 150 eV elec_method : DM smearing_width : 0.04 eV nextra_bands : 4 spin_polarized : FALSE opt_strategy : SPEED num_dump_cycles : 0 xc_functional : LDA Figure 5 Example param file for aluminium supercell phonon calculation. It is not strictly necessary to turn off the LO/TO splitting calculation - CASTEP will warn that this is not possible and turn it off anyway. The explicit request for a non-spin polarized calculation is necessary for fcc Al, because CASTEP chooses spin-polarized by default due to the odd number of electrons. In a CASTEP calculation the supercell must be chosen and explicitly specified in the input files. It is defined by a matrix, which multiplies the ordinary simulation cell vectors and is specified as a 3\\times3 3\\times3 matrix in the .cell file of the form %block PHONON_SUPERCELL_MATRIX 4 0 0 0 4 0 0 0 4 %endblock PHONON_SUPERCELL_MATRIX This typical example using a diagonal matrix creates a supercell expanded along each lattice vector a , b and c by factor of 4. The supercell to be used in a phonon calculation needs to be chosen with care. It must be large enough to contain a sphere of radius R_c R_c , the typical range of a force constant matrix. In a simple metal a value of R_c R_c as small as 6\u00c5 may be satisfactory, but more complex and structured systems will need a larger value 11 . In a covalent semiconductor the required R_c R_c may be 10\u00c5 or larger. However a supercell can quickly grow to generate a very large calculation indeed. For example a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 supercell of even a 2 atom primitive cell contains 128 atoms. Consequently it is rarely feasible to use this method on a uniprocessor or desktop computer, and a substantial parallel computer is usually required. The shape of the supercell should usually be as near cubic as possible, irrespective of the shape of the primitive cell, to optimise the supercell size/ R_c R_c ratio. This can be achieved using an off-diagonal supercell matrix, as in the example input files of figure [al-sc-cell] where a cubic supercell containing 108 atoms ( 3 \\times 4 = 12 3 \\times 4 = 12 unit cells) is generated from the rhombohedral primitive cell of aluminium containing a single atom. If the system is highly anisotropic, perhaps a slab model of a surface then a uniform supercell is clearly not appropriate and a suitable supercell must be designed from a consideration of the exact nature of the model. The electronic Brillouin-Zone integrals for the supercell calculation use the special k-points method, which are specified in the . cell file using an separate but analogous set of keywords to those pertaining to the primitive cell sampling. Specifically, %block SUPERCELL_KPOINT_LIST allows an exact specification of k-points and weights supercell_kpoint_mp_grid_spacing d chooses a Monkhorst-Pack grid with the specified spacing. supercell_kpoint_mp_grid p q r (and optionally supercell_kpoint_mp_offset ) allow an exact specification of a Monkhorst-Pack grid. Finally if no supercell kpoint keywords or blocks are given, a grid is chosen to generate a similar sampling density to the primitive cell calculation. Once the force constant matrix has been calculated using the supercell, the remainder of the lattice dynamics proceeds exactly as in the case of a Fourier interpolation calculation. The keywords controlling the interpolation scheme and cutoff radius, the fine phonon kpoint set and the acoustic sum rule enforcement work in exactly the same way. See section [interpolation-setup] for details. Convergence Phonon and dielectric response calculations give rise to a number of issues with convergence, in addition to those encountered in ground-state calculations, and a systematic and step-by-step approach is necessary to achieve well-converged results. CASTEP assists the user by setting default values for many convergence parameters based on the particular task which incorporate the experience of many calculations. Therefore it is a good practice not to specify convergence parameters explicitly unless specific convergence test results are known - otherwise a well-chosen default could be overridden with an untested value. (The example input of figure [example-gamma] contains no phonon-specific convergence parameters.) It was emphasised previously (section [geometry] ) that a well-converged geometry optimisation is a prerequisite for a phonon calculation. In turn this mandates a reasonably high level of convergence of plane-wave cutoff, SCF convergence and electronic k-point sampling. It is typical to run phonon calculations at a basis_precision : FINE level of plane-wave cutoff, (The header of each .usp or .recpot pseudopotential file contains a translation into eV units.) DFPT electric field response calculations can require finer electronic k-point sampling than suffices for a ground state calculation, so the effect of the kpoint_mp_grid on the dielectric permittivity should be tested. Convergence of DFPT solver The second stage of a phonon or E-field calculation is the variational DFPT solver, and there are a number of associated parameters to control the convergence. Parameters phonon_energy_tol 1.0e-5 eV/ang**2 and efield_energy_tol 1.0e-5 ang**3 govern the exit criterion for the DFPT self-consistency loop. The above default values are usually sufficient for frequencies converged to < 1 \\text{cm}^{-1} < 1 \\text{cm}^{-1} and permittivities to two or three decimal places and rarely need to be changed. However the converged results depend not only on the DFPT SCF calculation, but also, and rather strongly on the degree of convergence of the ground state electron density and wavefunctions. These enter the DFPT equations both directly and as a consequence of the orthogonality condition between ground-state and first-order response orbitals ( Refson, Tulip, and Clark 2006 ; Gonze and Lee 1997 ). To generate sufficiently accurate ground-state wavefunctions, the value of elec_energy_tol should be much lower than needed for an SCF or geometry optimuzation calculation. CASTEP sets a default value of roughly phonon_energy_tol squared and it is wise to rely on this and not to set elec_energy_tol explicitly in a phonon calculation. 12 Convergence of finite displacement forces The criteria for choosing the \u201cground-state\u201d convergence parameters for a finite-displacement phonon calculation (in either primitive or supercell mode) are naturally almost identical to those governing DFPT calculations. In this case there is no additional self-consistent electronic calculation; instead there is a sequence of additional ground-state calculations at displaced geometries. Finite-displacement calculations require very well converged forces to be computed in the ground state SCF calculation. This is because the numerical evaluation of the second derivative depends on differences between the (small) forces at perturbed configurations (equation [finite-diff] ). Clearly the numerical derivative has lower relative precision than the argument (the forces), which must therefore be evaluated to a rather high precision. Unlike the ground-state energy , which is variational with respect to the orbitals, the forces are not and the error in the forces is linear in the error in the orbitals. The main parameter governing their accuracy is again elec_energy_tol which is again set by default from the value of phonon_energy_tol ^2 ^2 . It is normally sufficient to use the default value of elec_energy_tol chosen as the default in a phonon calculation. However there is also a way of directly achieving the requested force tolerance, by setting parameter elec_force_tol 1e-3 eV/ang . This is not used by default as it adds some overhead to the SCF calculation resulting in longer run times. However it does guarantee that the forces really are converged to the required accuracy, unlike setting elec_energy_tol . Convergence of Interpolation and Supercell Fourier interpolation and supercell calculations add yet another criterion which must be satisfied to achieve well-converged results - the range of the force-constant matrix in real space. Sections [interpolation-setup] and [supercell] discuss some of the criteria applicable to these types of calculation. Unfortunately convergence testing of the size of the supercell for FD/supercell calculations can be prohibitively expensive as the the volume and number of atoms increase as the cube of the linear dimension under test. Consequently the CPU time will increase with the sixth power or higher! There is no easy solution to this problem and the reader is cautioned not to necessarily take on trust that FD/supercell phonon calculations published in the literature are fully converged! However some progress may be made by performing a calculation using the largest feasible supercell. If phonon_fine_cutoff_method : SPHERICAL is selected, it is then possible to vary the cutoff radius using parameter phonon_force_constant_CUTOFF to lower values than the maximum of half the largest box size. These tests may be performed using the \u201ccontinuation\u201d method (section [continuation] ) or the \u201cphonons\u201d utility (section [phonons-tool] ) without repeating the expensive supercell calculation. Another convergence test is automatically performed if the spherical cutoff method is selected. The frequencies resulting from the interpolation with the spherical cutoff are compared to those from an \u201cexact\u201d interpolation at wavevectors commensurate with the supercell. The results are written to the .castep file. This provides a quantitative measure of the interpolation error. A similar cutoff scaling test might be possible for the phonon_fine_cutoff_method : DEFAULT case, although it is considerably less useful. Parameter phonon_force_constant_cut_scale 0.9 will scale the range of the cutoff by the factor specified. However the default value of 1.0 is \u201cspecial\u201d in including constants separated by exactly half the supercell Wigner Seitz cell. Consequently convergence is not smooth in this parameter and while 0.95 might be underconverged, 1.0 could be very well converged. (This is also the reason for its superior convergence performance over the spherical cutoff scheme.) In general phonon wavevectors {\\mathbf{q}} {\\mathbf{q}} are specified using one of the variants of the phonon_kpoint_* cell keywords for lists, grids or paths. The example given uses a list of length 1 to specify a single point. \u21a9 This example will use the DFPT method which is the default if phonon_method is not present. \u21a9 Further optional output writing to .castep of the dynamical matrixes and force constant matrices is enabled at any iprint level by the parameters phonon_write_dynamical and phonon_write_force_constants respectively. \u21a9 The Placzek theory applies to the case of insulators only, and no general formulation to compute the activity for Raman scattering of conducting systems is available \u21a9 If the parameter raman_method : FINITEDISPLACEMENT is set the calculation uses an older, finite-difference implementation (see section [fd] ) to compute the mode displacement derivatives of the polarizability tensor (section [efield] ) using the approach of Porezag and Pedersen ( Porezag and Pederson 1996 ). The first stage is to perform a full phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 , to determine the mode eigenvectors and identify the Raman-active modes. Then CASTEP loops over the active modes only computing the Raman tensor, activity and depolarization for each. This method is deprecated as obsolete and computationally expensive. \u21a9 The offset may be specified as three fractions of the grid spacing, so 1/2p \\; 1/2q \\; 1/2r 1/2p \\; 1/2q \\; 1/2r shifts the grid exactly half a subdivision in each of the three directions. As of release 24.1 the INCLUDE_GAMMA keyword will automate this calculation and in fact is the default so that omitting phonon_kpoint_mp_offset entirely will do the right thing. \u21a9 The latter is governed by the effective range of electronic interactions which bears no relationship to the elastic range of the atomic displacements as required for the force constants. \u21a9 The effect is usually small for LDA, intermediate for PBE and largest for PW91, as the gradient terms are most sensitive to the ASR violation. \u21a9 (or fine_gmax or fine_cut_off_energy \u21a9 There is one known case where the reciprocal-space ASR correction fails to give the correct behaviour. Two-dimensional planar or layered systems with weak inter-layer bonding such as graphene or graphite exhibit a quadratic behaviour of an acoustic mode near \\Gamma \\Gamma . The reciprocal space scheme fails to reproduce the correct, quadratic behaviour and linearises the dispersion. The realspace method generates correct behaviour in these cases. \u21a9 A non-negligible force constant at longer range may also occur in a metallic system in the presence of a Kohn anomaly. \u21a9 Specifically, the error in the second-order energy or force constants is variational, and therefore depends quadratically on the error in the DFPT first-order response orbitals. However it is non-variational and linear with respect to the error in the ground-state orbitals. The practical consequence is that there is an error in DFPT results which varies as the square root of the ground-state convergence parameter elec_energy_tol which therefore must be very small for good accuracy. A heuristic rule of thumb is that elec_energy_tol \\approx \\approx phonon_energy_tol ^2 ^2 is necessary to converge the second order energy to the value of phonon_energy_tol . \u21a9","title":"Running-phonon-calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:dfpt-gamma","text":"Many of the principles of setting up and running phonon calculations can be illustrated in the simplest case - computing phonon frequencies at the q=(0,0,0) q=(0,0,0) , often referred to as the \\Gamma \\Gamma point. This is a very common calculation, as it forms the basis of modelling of infra-red or Raman spectra and group theoretical analysis and assignment of the modes.","title":"A DFPT phonon calculation at the \\Gamma\\Gamma-point"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:input-basic","text":"The setup for a CASTEP phonon calculation requires a few additional keywords in the seedname .cell file. Like any type of calculation, the unit cell must be specified using either of %block LATTICE_ABC or %block LATTICE_CART , and the atomic co-ordinates using %block POSITIONS_FRAC or %block POSITIONS_ABS . Figure [example-gamma] shows a complete input file for a calculation on boron nitride in the hexagonal Wurtzite structure. The additional keywords. phonon_kpoint_list is used to specify that a single phonon wavevector (0,0,0) is to be computed 1 . More wavevectors could be specified using additional lines in this block. 2 %block LATTICE_ABC 2.536000 2.536000 4.199000 ! a, b, c 90.000000 90.000000 120.000000 ! alpha, beta, gamma %endblock LATTICE_ABC %block POSITIONS_FRAC B 2/3 1/3 0.000000 ! Atom co-ordinates in crystallographic N 2/3 1/3 0.374536 ! fractional system. B 1/3 2/3 0.500000 N 1/3 2/3 0.874536 %endblock POSITIONS_FRAC %block SPECIES_POT B B_00.recpot ! File names of pseudopotential to use for B N N_00.recpot %endblock SPECIES_POT kpoints_mp_spacing 0.07 ! Generate MP grid of electronic k-points. symmetry_generate ! Find symmetry operations of crystal structure %block PHONON_KPOINT_LIST 0.0 0.0 0.0 1.0 ! Wavevector of phonon(s) to compute ( qx qy qz, weight) %endblock PHONON_KPOINT_LIST task : PHONON ! Choose a phonon calculation xc_functional : LDA opt_strategy : SPEED ! Optimise for speed over memory saving cut_off_energy : 700.0 eV ! Plane-wave cutoff for this system elec_method : DM ! Use fast DM solver even for insulating system phonon_sum_rule : TRUE ! Enforce acoustic sum rule on calculated D Figure 1: Annotated example cell and parameter files for BN in the Wurtzite structure. Note that phonon_method defaults to DFPT .","title":"Input files"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:output-gamma","text":"Figure [example-gamma-out] shows part of the phonon-relevant output extracted from the .castep file obtained by running the input files of the previous section. There are several blocks of output, one per direction chosen for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 in the LO-TO splitting terms. Note that CASTEP has added a calculation without LO-TO splitting (the first block), even though this was not explicitly requested. Within each block frequencies are listed one per line. Also on the line are (a) a label indicating the irreducible representation of the mode from a group theory analysis, (b) the computed absorptivity of the mode in a powder (or otherwise orientationally averaged) infrared experiment, \u00a9 whether the mode is IR active, (d) the Raman activity (if computed) and (e) whether the mode is Raman active. ============================================================================== + Vibrational Frequencies + + ----------------------- + + + + Performing frequency calculation at 1 wavevector (q-pt ) + + ========================================================================== + + + + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 1.0000000000 + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.049170 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1016.312039 a 28.5895083 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1051.124801 b 25.8079204 Y Y + + 12 1123.472590 d 0.0000000 N N + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + Figure 2 Output in the .castep file generated by the preceding input files for wurtzite BN. The columns show the mode frequencies, a letter labelling of the irreducible representation of the mode, the infrared absorptivity and Raman activity, and whether or not the mode is Raman and/or IR active. Not all of these are present in every calculation depending on the use of symmetry and input options. + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 0.0000000000 + + q->0 along ( 0.000000 0.000000 1.000000) + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.037851 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1051.124801 b 25.8079204 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1123.472590 d 0.0000000 N N + + 12 1262.933291 a 28.5895083 Y Y + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + (Due to LO/TO splitting this character table may not contain some symmetry + + operations of the full crystallographic point group. Additional + + representations may be also be present corresponding to split LO modes. + + A conventional analysis can be generated by specifying an additional null + + (all zero) field direction or one along any unique crystallographic axis + + in %BLOCK PHONON_GAMMA_DIRECTIONS in .cell.) + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + ============================================================================== Figure 2 Run output (continued): If the LO-TO-splitting calculation is active the \\Gamma \\Gamma point frequency table is repeated, both without and including the non-analytic contribution which generates the LO/TO splitting in one or more directions (See Gonze and Lee ( Gonze and Lee 1997 )). (The group theory analysis for LO modes is less useful than might be wanted and is likely to be the subject of future developments.) As with other calculations the amount of information written to the .castep file is controlled by the value of the parameter iprint . The levels of output are iprint : 0 Minimal output as in figure [example-gamma-out] . No progress info. iprint : 1 As for iprint : 0 but including a reassuring progress report of q-points and perturbations. iprint : 2 More detailed output including details of k-points and symmetry for each perturbation, cycle-by cycle DFPT minimiser report, printing of dynamical matrices (and force constant matrices). In addition to the user-readable output in the .castep file 3 , every phonon calculation generates an additional output file with the suffix .phonon which is intended for postprocessing analysis by other programs. This includes not only the frequencies but also the eigenvectors {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} resulting from diagonalising the dynamical matrix. These eigenvectors are orthonormal and the relationship between the eigenvectors and atomic displacements is given by u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) where Q_M Q_M is the amplitude of mode m m and the other notation is as set out in the introduction.","title":"Reading the output"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:raman","text":"In addition to the infrared absorptivity computed as a default part of a \\Gamma \\Gamma -point phonon calculation, CASTEP is also capable of computing the Raman activity tensors in the case of non-resonant scattering for an insulating system 4 . This calculation uses an extension of DFPT known as the \u201c2n+1 theorem\u201d ( Baroni et al. 2001 ; Miwa 2011 ) which requires substantially more computational effort than a bare phonon calculation and is therefore not enabled by default. To compute Raman activity set calculate_raman : TRUE in the .param file, which calculates and prints the Raman atomic susceptibility tensors and the mode susceptibility tensors to the .castep file. These may be extracted for use when modelling the Raman scattering in a polarised single-crystal geometry. 5 As with the Born effective charges and dynamical matrices, there is a sum rule on the values of the atomic polar tensors, which may not be well satisfied because of numerical approximations. A correction will be applied if parameter raman_sum_rule : TRUE is set. A 3d-average Raman activity (see Porezag and Pedersen ( Porezag and Pederson 1996 )) is computed from the susceptibility tensors and printed as an additional column in the usual frequency output given in figure [example-gamma-out] . This may be used for simple modelling of a powder spectrum, for example using the dos.pl tool (see section [dos-pl] ).","title":"Raman activity calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:ddos","text":"Phonons of a nonzero wavevector play an important role in the thermophysical properties of crystalline solids and the physics of many solid-state phase transitions. Proving the mechanical stability of a crystal structure by testing for real frequencies requires a vibrational calculation over the full Brillouin Zone. And dispersion curves and densities of states are frequently required for comparison with inelastic neutron and X-ray scattering experiments. One of the benefits of density functional perturbation theory is that CASTEP can calculate vibrational modes at {\\mathbf{q}}\\ne \\mathbf{0} {\\mathbf{q}}\\ne \\mathbf{0} as easily as at {\\mathbf{q}}= \\mathbf{0} {\\mathbf{q}}= \\mathbf{0} (but at the cost of an increase in CPU time due to the decreased symmetry). It is possible to perform this calculation simply by providing a list of q-points in the .cell file ( using one of the blocks %block PHONON_KPOINT_LIST , or %block PHONON_KPOINT_PATH or keyword phonon_kpoint_mp_grid ). However to generate a reasonable quality dispersion plot or density of states will usually require hundreds or thousands of q-points. The time required by such a calculation would be several hundred times that for a single-point energy and therefore infeasibly large. Fortunately there is a way to achieve the same result at a far smaller computational cost. This method exploits the fact that the interatomic interactions in a solid have a finite range and decay rapidly to zero. Specifically, the elements of the force constant matrix in Eq. [fcmat] decrease as 1 / r^{5} 1 / r^{5} with interatomic distance. Consequently the dynamical matrix defined by Eq. [dmat] and its eigenvalues \\omega^{2}({\\mathbf{q}}) \\omega^{2}({\\mathbf{q}}) are smoothly varying with wavevector {\\mathbf{q}} {\\mathbf{q}} . Fourier interpolation is used to generate dynamical matrices on an arbitrarily fine grid or linear path in reciprocal space from a set of DFPT calculations on a much coarser grid. For a full description of the method see references ( Baroni et al. 2001 ; Giannozzi et al. 1991 ; Gonze and Lee 1997 ). A complication arises in the case of polar solids where the dipole-dipole interaction generated upon displacing an atom leads to a longer ranged force constant matrix which decays only as 1 / r^{3} 1 / r^{3} . CASTEP models this term analytically using Born effective charges and dielectric permittivity calculated using an electric field response DFPT calculation (see section [efield] and Ref. ( Gonze and Lee 1997 )). It is therefore able to perform the Fourier interpolation for only the part of the force constant matrix which varies as 1 / r^{5} 1 / r^{5} , and does not require a finer grid than in the case of non-polar solids.","title":"Dispersion and density of states"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:interpolation-setup","text":"In the .cell file choose the q-points of the coarse grid of points at which to perform DFPT calculations. This may be specified as a %block PHONON_KPOINT_LIST containing the reduced set of points in the irreducible Brillouin Zone, but is is almost always more straightforward to use the alternative keywords phonon_kpoint_mp_grid : p q r phonon_kpoint_mp_offset : INCLUDE_GAMMA to specify the grid parameters and offset 6 . The grid parameters p , q and r should normally be chosen to give a roughly uniform sampling of reciprocal space taking length of the reciprocal lattice vectors into account, and should be compatible with the symmetry of the simulation cell. Alternatively a grid may be specified using the minimum spacing, for example phonon_kpoint_mp_grid_spacing 0.1 1/ang Normally the grid should be chosen to contain the \\Gamma \\Gamma point, which usually gives better convergence properties of the interpolation ( i.e.*convergence at smaller *p,q,r ) than otherwise. This is the opposite behaviour to electronic k-point sampling (see Ref. ( Probert and Payne 2003 )). The special keyword value phonon_kpoint_mp_offset : INCLUDE_GAMMA avoids the need to work out the offset explicitly. The choice of grid parameters p , q and r is governed by three considerations: For a 3-dimensional crystal, p,q,r should obey the crystallographic symmetry , so for a cubic or rhombohedral crystal you should set p = q = r p = q = r . In the case of a uniaxial crystal, such as tetragonal or hexagonal we have p = q \\neq r p = q \\neq r (assuming that c c is the unique axis) and for lower symmetry there is no constraint. The value in any of the directions limits the range of the force constant matrix in much the same way as the supercell multiplier does in a finite-difference/supercell calculation (Section [supercell] ). Exactly how large this should be depends on the nature of the chemical bonding. Ionically bonded systems tend to have fairly short-ranged force-constant matrices and need relatively coarse grids for convergence. For sodium chloride in the rocksalt structure with a primitive lattice parameter 3.75\u00c5 a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 grid is reasonably close to convergence. This corresponds to a truncation of the force constant matrix at a distance of approximately 7 7 \u00c5 ( \\approx p \\times 2 \\pi / a \\approx p \\times 2 \\pi / a ). On the other hand covalent systems tend to have fairly long-ranged force-constant matrices and need finer grids for convergence. Silicon is a good example of this. The primitive lattice parameter is similar to sodium chloride at 3.81 3.81 \u00c5, but the dispersion curve is not fully converged until an 8 \\times 8 \\times 8 8 \\times 8 \\times 8 grid is used. A more detailed examination of this point may be found in reference ( Ackland, Warren, and Clark 1997 ). While there is no essential physics relationship between the grid sizes for phonon {\\mathbf{q}} {\\mathbf{q}} -points and that required for electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling 7 , there is a technical connection resulting from the implementation of density-functional perturbation theory and the requirement to generate and use ground-state Kohn-Sham wavefunctions on grids containing both \\{{\\mathbf{k}}\\} \\{{\\mathbf{k}}\\} and \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} (See ref. ( Gonze 1997 ) for the mathematical details). For best performance and stability of the DFPT calculation the phonon grid parameters should be commensurate with the electronic grid with an exact divisor as the simplest case. For example, in an elemental metal with an hcp structure such as Mg, an electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling of 21 \\times 21 \\times 12 21 \\times 21 \\times 12 and a phonon {\\mathbf{q}} {\\mathbf{q}} -point sampling of 7 \\times 7 \\times 6 7 \\times 7 \\times 6 might be most effective. This is not a hard requirement and CASTEP will attempt to work with whatever grids are specified, but in some cases there may be a performance advantage to rounding up one or other of the grids to meet the commensurability criterion. Additional keywords in the .param file control the interpolation. Most importantly phonon_fine_method : INTERPOLATE instructs CASTEP to perform the Fourier interpolation step following the usual DFPT calculation. The target set of wavevectors for the interpolation is set up using additional keywords or blocks in the .cell file. Either phonon_fine_kpoint_mp_grid p q r phonon_fine_kpoint_mp_offset o _1 _1 o _2 _2 o _3 _3 or phonon_fine_kpoint_mp_spacing 0.03 1/ang . will perform interpolation onto a regular (possibly offset) grid. In fact only the points in the irreducible wedge of the Brillouin Zone are included, and a suitable weight is computed so that the weighted average is identical to a uniform sampling of the BZ. This is the usual method for computing a phonon density of states. If a set of dispersion curves along high symmetry directions is required, an empty cell keyword block %block PHONON_FINE_KPOINT_PATH %endblock PHONON_FINE_KPOINT_PATH will internally generate a list of {\\mathbf{q}} {\\mathbf{q}} -points sampling a default path through the Brillouin-Zone according to the symmetry of the calculation. Alternatively a list of {\\mathbf{q}} {\\mathbf{q}} -points explicitly specifying the vertices of the path may be input as %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 0.5 0.5 0.5 break 0.0 0.0 0.0 0.5 0.5 0.5 ... %endblock PHONON_FINE_KPOINT_PATH which traverses the directions between the vertices specified, except in the presence of the break keyword where the path jumps without including any intermediate points. The fineness of sampling along the path is set by an additional keyword phonon_fine_kpoint_path_spacing : 0.03 1/ang . As a final alternative, a simple list of points can be directly input to model any sampling you choose using %block PHONON_FINE_KPOINT_LIST 0.0 0.0 0.0 0.1 0.2 0.3 ... %endblock PHONON_FINE_KPOINT_LIST This is the approach used for files generated by Accelrys Materials Studio. The same keywords are used in the closely related method of a finite difference calculation; see the example .cell file of figure [al-sc-cell] .","title":"Setting up an interpolation calculation"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:continuation","text":"CASTEP stores the results of all phonon calculations - dynamical matrices and force constant matrices - in the binary seedname .check file written at the end of a successful run. This can be used to change some values of parameters relating to interpolation, and to change or indeed replace the entire fine phonon k-point set without any need to repeat the expensive DFPT (or supercell) part of the calculation. In fact a single calculation of the force constant matrix is sufficient to compute a DOS at a variety of sampling densities plus arbitrarily smooth dispersion curves. Setting up a continuation calculation is simple. Just add the continuation keyword in the usual way to a renamed copy of the param file continuation orig-seedname .check and make any changes to the fine phonon k-point sampling parameters in a copy of the seedname .cell file. It is recommended that you work with renamed copies to avoid overwriting the original and valuable seedname .check file. Running CASTEP on the new set of input files is exactly the same as running a new calculation, except that the result will be generated much more quickly. When setting up a continuation run, take care not to change the standard phonon k-point set, the electronic k-point set or any electronic structure parameters such as elec_energy_tol . If a mismatch is detected with the values stored in the checkpoint file, CASTEP will discard the saved dynamical matrix data and restart the full calculation from the beginning. Continuation calculations are also used in conjunction with checkpointing where a partially complete calculation is written to a file, also in .check format and which may be used to restart an interrupted calculation. See section [checkpointing] for a description.","title":"Continuation"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:interpolation-control","text":"The final representation of the force constant matrix derived from the dynamical matrices is actually a periodic representation and is equivalent to the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a (fictitious) p \\times q \\times r p \\times q \\times r supercell. (See section [supercell] for more explanation.) CASTEP must determine a mapping between elements of the periodic dynamical matrix and aperiodic force constant matrix using a minimum-image convention for ionic site pairs and impose a cutoff scheme in real space to exclude (supercell-) periodic images. In fact CASTEP implements two distinct schemes. The cumulant scheme ( Parlinski, Li, and Kawazoe 1997 ) includes all image force constants with a suitable weighting to avoid multiple counting of images. This is achieved by including image force constants in any direction if they lie within half the distance to the nearest periodic repeat of the fictitious supercell lattice in that direction. If an atom-atom pair vector lies exactly half way to the supercell repeat so that image force constants occur, for example, at both \\mathbf{L} \\mathbf{L} and -\\mathbf{L} -\\mathbf{L} , all images at the same distance are included with a suitable weighting factor to preserve the symmetry of the cumulant force constant matrix. (See Refs. ( Parlinski, Li, and Kawazoe 1997 ) and ( Ye et al. 2004 ) for a more detailed explanation). This scheme is selected by specifying the param file keyword phonon_fine_cutoff_method CUMULANT and is in fact the default method in CASTEP. CASTEP also implements a simple spherical cutoff, controlled by the parameter R_c R_c and specified by parameter phonon_force_constant_cutoff 10.0 ang The value R_c R_c should be chosen to satisfy 2 R_c < min(p L_1,q L_2,r L_3) L 2 R_c < min(p L_1,q L_2,r L_3) L where L_n L_n is the cell edge of the simulation cell and p,q,r p,q,r are the (coarse) grid of phonon wavevectors. It is usually easiest to specify a value of zero, in which case CASTEP chooses the largest allowable value automatically. This scheme is most suitable for bulk materials of cubic symmetry. The spherical scheme is chosen using keyword phonon_fine_cutoff_method SPHERICAL . Within the default method a smaller cutoff volume can be decreased by a radius scaling factor, e.g. phonon_force_constant_cut_scale : 1.0 . This may be useful for testing the effect of long-ranged contributions to the IFC matrix. However any departure of this parameter\u2019s value from 1 does not preserve the superior convergence properties of the cumulant scheme and will in general require a larger supercell than the exact cumulant method.","title":"Control of interpolation scheme"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:asr","text":"The vibrational Hamiltonian is invariant to a uniform translation of the system in space. This symmetry is the origin of the well-known result that any crystal has three acoustic vibrational modes at {\\mathbf{q}}=0 {\\mathbf{q}}=0 with a frequency of zero. This leads to the so-called acoustic sum rule (or ASR) ( Ackland, Warren, and Clark 1997 ; Pick, Cohen, and Martin 1970 ) which has mathematical expressions for the force constant and \\Gamma \\Gamma -point dynamical matrices \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} In plane-wave calculations the translational invariance is broken as atoms translate with respect to the fixed FFT grid, so the sum rule is never exactly satisfied. Consequently it is sometimes observed even in an otherwise apparently very well converged calculation that the three acoustic modes at \\Gamma \\Gamma depart significantly from zero frequency. Depending on the XC functional 8 these frequencies may reach or exceed 50 cm ^{\\text{-1}} ^{\\text{-1}} . One solution is simply to increase number of grid points of CASTEP\u2019s \u201cfine\u201d FFT grid used for densities and potentials by increasing fine_grid_scale 9 . (N. B. This is distinct from grid_scale which controls the FFT grid used to represent wavefunctions.) However this can be very costly in computer time and memory. Provided that the amplitude of the symmetry violation is not too large, it is possible to apply a transformation to the computed dynamical or force constant matrix so that it exactly satisfies the ASR. CASTEP implements a scheme which projects out the acoustic mode eigenvectors and adjusts their frequency to zero, while having minimal impact on the optic mode frequencies. This scheme is controlled by parameters (in the .param file) phonon_sum_rule_method : REAL / RECIP / REAL-RECIP / NONE The first of these simply activates or deactivates the correction. The second chooses which of the variants of the ASR in equation [asr] to enforce, the real-space force constant matrix, the reciprocal-space dynamical matrix, or both. ( phonon_sum_rule_method : NONE is a synonym for phonon_sum_rule : FALSE ). The real-space method is only applicable to interpolation or supercell/finite displacement calculations, but the reciprocal-space method can be used for any type of phonon calculation. Both variants change the acoustic mode frequencies away from but near {\\mathbf{q}}=0 {\\mathbf{q}}=0 , the realspace method implicitly, and the reciprocal space method explicitly, by determining the correction to {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} and subtracting it from {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} as suggested by Gonze ( Gonze and Lee 1997 ). This usually results in acoustic mode behaviour which is indistinguishable from a very well converged calculation using a very fine FFT grid 10 . In addition to the sum rule on frequencies there is another for the Born effective charges (see section [efield] ) \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 which is activated by parameter born_charge_sum_rule : TRUE The default behaviour of CASTEP is that neither sum rule is enforced. If this was not requested in the original run, then it may be added in post-processing fashion in a continuation run, as per section [continuation] . Only the raw dynamical and/or force constant matrices are stored in the checkpoint file without the effect of ASR enforcement, which is only applied at the printout stage. Therefore the effect can be turned off, or altered by a post-processing calculation as well as turned on.","title":"Acoustic Sum Rule correction"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#density-of-states","text":"The definition of the phonon density of states requires an integration of the calculated frequencies \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} over the Brillouin-Zone g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . A simple computational approximation would be to compute \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} on a regular, discrete grid of {\\mathbf{q}} {\\mathbf{q}} , replace the integral with a sum over the grid and convolute the result with some peak shape function h(\\omega) h(\\omega) such as a Gaussian g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . In the CASTEP toolset, this is implemented by performing a Fourier interpolation calculation onto a suitably fine {\\mathbf{q}} {\\mathbf{q}} -point set, specifying either phonon_fine_kpoint_mp_grid or phonon_fine_kpoint_mp_spacing . The resulting .phonon file may then be analysed using the dos.pl tool (see section [dos-pl] ) which implements equation [broadendos] . However the broadening smooths out any sharp features of the DOS, and fails to reproduce the smoothly-curved or sharply peaked segments typical of theoretical densities-of-states. This is discussed in more detail in references ( Yates et al. 2007 ) and ( Pickard 1997 ). A more faithful rendering may be obtained using the so-called adaptive broadening approach of Yates et. al ( Yates et al. 2007 ) which uses the gradients of the phonon branch dispersion to narrow or widen the broadening for flat or steep branches respectively. It is activated by the parameters keyword phonon_calculate_dos : TRUE which computes an adaptively-broadened DOS during the Fourier interpolation stage of the calculation and writes an output file named .phonon_dos containing the tabulated DOS, plus the per-atomic-species resolved DOS in additional columns. The dos.pl script is able to read and present .phonon_dos files just as with .phonon . The range and resolution may be modified using additional parameters, for example phonon_dos_spacing : 0.01 THz phonon_dos_limit : 10.0 THz Example output for the phonons of diamond is shown in figure [c2-pdos] . Figure 3 Phonon DOS for Diamond, with an 18^3 18^3 fine grid comparing Gaussian broadened (red) vs adaptively broadened (black) methods. Artefactual wiggles are clearly visible in the Gaussian-broadened case, and the height of the sharp peaks is not well reproduced.","title":"Density of States"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:fd","text":"In addition to the DFPT method of computing force constants, CASTEP implements schemes based on numerical differentiation of forces when atoms are displaced by a small amount from their equilibrium positions. This method is useful for cases where DFPT has not been implemented, which as of CASTEP release 24.1 includes ultrasoft pseudopotentials, Hubbard U and exact exchange and hybrid functionals, and some of the newer classes of dispersion correction. There are three variants of this scheme.","title":"Finite Displacement"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#primitive-cell-finite-displacement","text":"The basic finite displacement method is selected by setting parameter phonon_method : FINITEDISPLACEMENT In contrast to DFPT such displacements are necessarily periodic with the simulation cell, and therefore only {\\mathbf{q}}=0 {\\mathbf{q}}=0 phonons are commensurate with this condition. As in the case of DFPT lattice dynamics the phonon wavevectors are specified by %block PHONON_KPOINT_LIST , %block PHONON_KPOINT_PATH or phonon_kpoint_mp_grid in the .cell file but only the \\Gamma \\Gamma point, (0,0,0) (0,0,0) is meaningful. CASTEP will print a warning in the output file and ignore any non-zero value in the list. CASTEP proceeds by shifting each atom by a small amount, then performing a SCF calculation to evaluate the forces on the perturbed configuration. Both positive and negative displacements are performed in each direction so that the corresponding force constants can be evaluated using the accurate \u201ccentral difference\u201d method of numerical differentiation. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. Equation [finite-diff] demonstrates that a single pair of displaced calculation yields an entire row of the dynamical matrix. As with DFPT calculations, only the minimal set of perturbations is performed and the space-group symmetry is used to build the complete dynamical matrix. The SCF calculations on the perturbed configuration are efficient, typically taking only only a few cycles in CASTEP 5.0 or later. This efficiency is achieved by first making a good guess for the electron density of the perturbed system based on the ground state of the unperturbed system, and applying a displacement of an atomic-like density of the pseudo-atom in question. Second, the SCF is started using the Kohn-Sham orbitals of the unperturbed state as the initial guess for the perturbed configuration. To exploit this efficiency it is essential to use the density-mixing (Davidson) minimiser, selected by elec_method : DM in the .param file. (As the all-bands method has no means of initialising the density). The default displacement used is 0.01 0.01 bohr This can be changed if necessary by setting a parameter, phonon_finite_disp : 0.02 ang in the .param file. Except for the differences discussed above, input and output formats are the same as for DFPT calculations.","title":"Primitive Cell Finite Displacement"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#born-charges-permittivity-and-loto-splitting-with-fd","text":"FD phonon calculations are useful where atomic-displacement response DFPT is not implemented, notably for ultrasoft pseudopotentials (USPs) and post-DFT exchange and correlation including LDA+U, SOC, hybrid functionals (see table [captable] ). However properties including IR spectral intensity, LO/TO splitting and the effectiveness of Fourier interpolation of dynamical matrices depend on the Born effective charges and dielectric permittivity (see section [efield] ), whose calculation by electric field response DFPT is not implemented. In some cases it may be convenient to read in externally computed or approximate values of Born charges and permittivity to be used to calculate IR spectra, LO/TO splitting etc. For example, a DFT+U, meta-GGA, or hybrid calculation might make use of values calculated using PBE-DFPT and NCPs as a fair approximation, or even computed using a different DFT code. This may be accomplished by specifying the name of an external file containing the values (in this case BORN.DAT ) in the .param file %block DEVEL_CODE PHONON:READ_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE The file should be formatted as for the Phonopy code ( https://phonopy.github.io/phonopy/input-files.html#born-optional ). A file of this format may be written at the end of a DFT, NCP E-field response calculation by %block DEVEL_CODE PHONON:WRITE_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE","title":"Born Charges, Permittivity and LO/TO splitting with FD"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:berry-fd","text":"As of CASTEP release 25.1, it will be possible to calculate Born effective charges (but not dielectric permittivity) using a finite-difference numerical differentiation of the Berry-phase polarization. This is performed as an adjunct to the FD phonon calculation, and will be automatically selected in the case of an FD phonon calculation with USPs. This works for any compatible Hamiltonian, including DFT+U, mGGAs such as rSCAN as well as hybrid XC functionals.","title":"Born charges from Berry Phase Polarization"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:ndsc","text":"As with the DFPT method, calculation of phonon dispersion and DOS using the finite displacement method is achieved using Fourier interpolation of dynamical matrixes. First, an approximation of the full force-constant-matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is calculated by explicitly computing a set of {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} with {\\mathbf{q}} {\\mathbf{q}} sampling a coarse grid of {\\mathbf{q}} {\\mathbf{q}} and using the inverse Fourier relation to equation [dmat] . Then equation [dmat] is used to generate the dynamical matrices at all of the (fine) phonon wavevectors required. The key step of computing every {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} on the \u201ccoarse\u201d regular grid is achieved by constructing a list of supercells commensurate with each of the coarse {\\mathbf{q}} {\\mathbf{q}} -points in turn (so that {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi where T_{\\text{SC}} T_{\\text{SC}} is a lattice vector of that supercell). This {\\mathbf{q}} {\\mathbf{q}} maps to a \\Gamma \\Gamma point calculation on the corresponding supercell despite being incommensurate with the primitive cell, and {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} for the primitive cell at {\\mathbf{q}} {\\mathbf{q}} may be extracted using equation [dmat] . It was shown by Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ) that by using so-called non-diagonal supercells such a set need contain only the least common multiple of the coarse grid subdivisions ( p, q, r p, q, r ). Consequently the number of distinct supercell calculations requires is much smaller than the number of {\\mathbf{q}} {\\mathbf{q}} -vectors of the grid, and most importantly increases with the linear dimension of the grid instead of the product. A non-diagonal supercell calculation is selected by setting the parameters phonon_method : FINITEDISPLACEMENT phonon_fine_method : INTERPOLATE , the cell keywords phonon_kpoint_mp_grid : p q r and one of the specifications of phonon_fine_kpoints exactly as in the case of a DFPT calculation. When the phonon calculation begins, CASTEP generates a list of supercells using the algorithm of Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ). For each of these, CASTEP generates the corresponding supercell and performs a finite-displacement phonon calculation. The dynamical matrices {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} are then extracted for each {\\mathbf{q}} {\\mathbf{q}} on the coarse KPOINT grid, and the calculation proceeds exactly as if the DFPT method has been used. The choice of coarse {\\mathbf{q}} {\\mathbf{q}} -point sampling set by phonon_kpoint_mp_grid requires one additional consideration compared to the DFPT case to give best computational performance. The supercell-generation algorithm of Lloyd Williams and Monserrat guarantees that the largest supercell in the generated list contains N_\\text{SC} = \\text{LCM} (p, q, r) N_\\text{SC} = \\text{LCM} (p, q, r) replications of the primitive cell. For example, an 4 \\times 4 \\times 4 4 \\times 4 \\times 4 sampling of a cubic cell gives N_\\text{SC} = 4 N_\\text{SC} = 4 . However a 2 \\times 3 \\times 4 2 \\times 3 \\times 4 sampling of an orthorhombic primitive cell yields N_\\text{SC} = 12 N_\\text{SC} = 12 , the LCM of 4 and 3. In that case it might be more efficient to use a 2 \\times 4 \\times 4 2 \\times 4 \\times 4 sampling which only requires N_\\text{SC} = 8 N_\\text{SC} = 8 for the largest of the generated supercells. As well as the {\\mathbf{q}} {\\mathbf{q}} -point sampling, FD interpolation calculations require one further parameter choice, namely to select the electronic k-point sampling for the supercell calculations. This may most conveniently be set using the cell keyword supercell_kpoint_mp_spacing : 0.1 1/ang . An explicit setting of grid sampling divisions with supercell_kpoint_mp_grid would be inappropriate as the correct choice will be different for each supercell, and unknown until run-time. By default CASTEP chooses a default spacing which is consistent with the primitive cell spacing, in an attempt to achieve a consistent level of convergence across supercells. Apart from the above two considerations, the setting up and execution of the FD interpolation follows exactly the same lines as with DFPT. In particular sum-rule, DOS and thermodynamics calculations and interpolation scheme tweaks apply identically.","title":"Finite Displacement using non-diagonal supercells"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:supercell","text":"The limitation of the primitive-cell finite displacement approach to {\\mathbf{q}}=0 {\\mathbf{q}}=0 may also be overcome by combining the method with the use of a supercell. This method, sometimes known as the \u201cdirect method\u201d ( Kunc and Martin 1982, sec. 19.2 ) relies on the short-ranged decay of the force constant matrix with interatomic distance and makes the assumption that force constants for separations larger than some value, R_c R_c are negligibly small and can be treated as zero. A supercell can be constructed to contain an imaginary sphere of radius R_c R_c beyond which force constants may be neglected. Then the dynamical matrix of a supercell satisfying L > 2 R_{c} L > 2 R_{c} is identical to the force constant matrix , i.e. {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} . Therefore complete knowledge of the force constant matrix to a reasonable approximation may be derived from a single calculation of the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a supercell containing several primitive cells. From this set of force constants the dynamical matrices at any phonon wavevector may be computed using equation [dmat] in exactly the same way as used in an interpolation calculation. Note: This method is mostly superceded by the non-diagonal supercell/finite displacement approach of section [ndsc] . That method gives an equivalent calculation of the force constant matrix, usually with a smaller computational cost, because of its superior scaling with cell size. %block LATTICE_CART 0 2.02475 2.02475 2.02475 0 2.02475 2.02475 2.02475 0 %endblock LATTICE_CART %block POSITIONS_ABS Al 0 0 0 %endblock POSITIONS_ABS %block SPECIES_POT Al Al_00.usp %endblock SPECIES_POT kpoint_mp_grid 14 14 14 supercell_kpoint_mp_grid 2 2 2 symmetry_generate %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 1.0 1.0 1.0 0.5 0.5 0.5 0.5 0.5 0.0 0.5 0.75 0.25 0.5 0.5 0.5 %endblock PHONON_FINE_KPOINT_PATH %block PHONON_SUPERCELL_MATRIX -3 3 3 3 -3 3 3 3 -3 %endblock PHONON_SUPERCELL_MATRIX Figure 4 Example cell file for aluminium supercell phonon calculation. This calculation computes a set of dispersion curves along high-symmetry directions. Note that this calculation is not fully converged with supercell size - there is a noticeable change in frequency on some of the branches on increasing the supercell matrix entries from 3 to 4. task : PHONON phonon_fine_method : SUPERCELL phonon_calc_lo_to_splitting : FALSE phonon_sum_rule : TRUE calculate_born_charges : FALSE phonon_force_constant_ellipsoid : 1.0 cut_off_energy : 150 eV elec_method : DM smearing_width : 0.04 eV nextra_bands : 4 spin_polarized : FALSE opt_strategy : SPEED num_dump_cycles : 0 xc_functional : LDA Figure 5 Example param file for aluminium supercell phonon calculation. It is not strictly necessary to turn off the LO/TO splitting calculation - CASTEP will warn that this is not possible and turn it off anyway. The explicit request for a non-spin polarized calculation is necessary for fcc Al, because CASTEP chooses spin-polarized by default due to the odd number of electrons. In a CASTEP calculation the supercell must be chosen and explicitly specified in the input files. It is defined by a matrix, which multiplies the ordinary simulation cell vectors and is specified as a 3\\times3 3\\times3 matrix in the .cell file of the form %block PHONON_SUPERCELL_MATRIX 4 0 0 0 4 0 0 0 4 %endblock PHONON_SUPERCELL_MATRIX This typical example using a diagonal matrix creates a supercell expanded along each lattice vector a , b and c by factor of 4. The supercell to be used in a phonon calculation needs to be chosen with care. It must be large enough to contain a sphere of radius R_c R_c , the typical range of a force constant matrix. In a simple metal a value of R_c R_c as small as 6\u00c5 may be satisfactory, but more complex and structured systems will need a larger value 11 . In a covalent semiconductor the required R_c R_c may be 10\u00c5 or larger. However a supercell can quickly grow to generate a very large calculation indeed. For example a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 supercell of even a 2 atom primitive cell contains 128 atoms. Consequently it is rarely feasible to use this method on a uniprocessor or desktop computer, and a substantial parallel computer is usually required. The shape of the supercell should usually be as near cubic as possible, irrespective of the shape of the primitive cell, to optimise the supercell size/ R_c R_c ratio. This can be achieved using an off-diagonal supercell matrix, as in the example input files of figure [al-sc-cell] where a cubic supercell containing 108 atoms ( 3 \\times 4 = 12 3 \\times 4 = 12 unit cells) is generated from the rhombohedral primitive cell of aluminium containing a single atom. If the system is highly anisotropic, perhaps a slab model of a surface then a uniform supercell is clearly not appropriate and a suitable supercell must be designed from a consideration of the exact nature of the model. The electronic Brillouin-Zone integrals for the supercell calculation use the special k-points method, which are specified in the . cell file using an separate but analogous set of keywords to those pertaining to the primitive cell sampling. Specifically, %block SUPERCELL_KPOINT_LIST allows an exact specification of k-points and weights supercell_kpoint_mp_grid_spacing d chooses a Monkhorst-Pack grid with the specified spacing. supercell_kpoint_mp_grid p q r (and optionally supercell_kpoint_mp_offset ) allow an exact specification of a Monkhorst-Pack grid. Finally if no supercell kpoint keywords or blocks are given, a grid is chosen to generate a similar sampling density to the primitive cell calculation. Once the force constant matrix has been calculated using the supercell, the remainder of the lattice dynamics proceeds exactly as in the case of a Fourier interpolation calculation. The keywords controlling the interpolation scheme and cutoff radius, the fine phonon kpoint set and the acoustic sum rule enforcement work in exactly the same way. See section [interpolation-setup] for details.","title":"Legacy Finite Displacement/Supercell"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:convergence","text":"Phonon and dielectric response calculations give rise to a number of issues with convergence, in addition to those encountered in ground-state calculations, and a systematic and step-by-step approach is necessary to achieve well-converged results. CASTEP assists the user by setting default values for many convergence parameters based on the particular task which incorporate the experience of many calculations. Therefore it is a good practice not to specify convergence parameters explicitly unless specific convergence test results are known - otherwise a well-chosen default could be overridden with an untested value. (The example input of figure [example-gamma] contains no phonon-specific convergence parameters.) It was emphasised previously (section [geometry] ) that a well-converged geometry optimisation is a prerequisite for a phonon calculation. In turn this mandates a reasonably high level of convergence of plane-wave cutoff, SCF convergence and electronic k-point sampling. It is typical to run phonon calculations at a basis_precision : FINE level of plane-wave cutoff, (The header of each .usp or .recpot pseudopotential file contains a translation into eV units.) DFPT electric field response calculations can require finer electronic k-point sampling than suffices for a ground state calculation, so the effect of the kpoint_mp_grid on the dielectric permittivity should be tested.","title":"Convergence"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-dfpt-solver","text":"The second stage of a phonon or E-field calculation is the variational DFPT solver, and there are a number of associated parameters to control the convergence. Parameters phonon_energy_tol 1.0e-5 eV/ang**2 and efield_energy_tol 1.0e-5 ang**3 govern the exit criterion for the DFPT self-consistency loop. The above default values are usually sufficient for frequencies converged to < 1 \\text{cm}^{-1} < 1 \\text{cm}^{-1} and permittivities to two or three decimal places and rarely need to be changed. However the converged results depend not only on the DFPT SCF calculation, but also, and rather strongly on the degree of convergence of the ground state electron density and wavefunctions. These enter the DFPT equations both directly and as a consequence of the orthogonality condition between ground-state and first-order response orbitals ( Refson, Tulip, and Clark 2006 ; Gonze and Lee 1997 ). To generate sufficiently accurate ground-state wavefunctions, the value of elec_energy_tol should be much lower than needed for an SCF or geometry optimuzation calculation. CASTEP sets a default value of roughly phonon_energy_tol squared and it is wise to rely on this and not to set elec_energy_tol explicitly in a phonon calculation. 12","title":"Convergence of DFPT solver"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-finite-displacement-forces","text":"The criteria for choosing the \u201cground-state\u201d convergence parameters for a finite-displacement phonon calculation (in either primitive or supercell mode) are naturally almost identical to those governing DFPT calculations. In this case there is no additional self-consistent electronic calculation; instead there is a sequence of additional ground-state calculations at displaced geometries. Finite-displacement calculations require very well converged forces to be computed in the ground state SCF calculation. This is because the numerical evaluation of the second derivative depends on differences between the (small) forces at perturbed configurations (equation [finite-diff] ). Clearly the numerical derivative has lower relative precision than the argument (the forces), which must therefore be evaluated to a rather high precision. Unlike the ground-state energy , which is variational with respect to the orbitals, the forces are not and the error in the forces is linear in the error in the orbitals. The main parameter governing their accuracy is again elec_energy_tol which is again set by default from the value of phonon_energy_tol ^2 ^2 . It is normally sufficient to use the default value of elec_energy_tol chosen as the default in a phonon calculation. However there is also a way of directly achieving the requested force tolerance, by setting parameter elec_force_tol 1e-3 eV/ang . This is not used by default as it adds some overhead to the SCF calculation resulting in longer run times. However it does guarantee that the forces really are converged to the required accuracy, unlike setting elec_energy_tol .","title":"Convergence of finite displacement forces"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-interpolation-and-supercell","text":"Fourier interpolation and supercell calculations add yet another criterion which must be satisfied to achieve well-converged results - the range of the force-constant matrix in real space. Sections [interpolation-setup] and [supercell] discuss some of the criteria applicable to these types of calculation. Unfortunately convergence testing of the size of the supercell for FD/supercell calculations can be prohibitively expensive as the the volume and number of atoms increase as the cube of the linear dimension under test. Consequently the CPU time will increase with the sixth power or higher! There is no easy solution to this problem and the reader is cautioned not to necessarily take on trust that FD/supercell phonon calculations published in the literature are fully converged! However some progress may be made by performing a calculation using the largest feasible supercell. If phonon_fine_cutoff_method : SPHERICAL is selected, it is then possible to vary the cutoff radius using parameter phonon_force_constant_CUTOFF to lower values than the maximum of half the largest box size. These tests may be performed using the \u201ccontinuation\u201d method (section [continuation] ) or the \u201cphonons\u201d utility (section [phonons-tool] ) without repeating the expensive supercell calculation. Another convergence test is automatically performed if the spherical cutoff method is selected. The frequencies resulting from the interpolation with the spherical cutoff are compared to those from an \u201cexact\u201d interpolation at wavevectors commensurate with the supercell. The results are written to the .castep file. This provides a quantitative measure of the interpolation error. A similar cutoff scaling test might be possible for the phonon_fine_cutoff_method : DEFAULT case, although it is considerably less useful. Parameter phonon_force_constant_cut_scale 0.9 will scale the range of the cutoff by the factor specified. However the default value of 1.0 is \u201cspecial\u201d in including constants separated by exactly half the supercell Wigner Seitz cell. Consequently convergence is not smooth in this parameter and while 0.95 might be underconverged, 1.0 could be very well converged. (This is also the reason for its superior convergence performance over the spherical cutoff scheme.) In general phonon wavevectors {\\mathbf{q}} {\\mathbf{q}} are specified using one of the variants of the phonon_kpoint_* cell keywords for lists, grids or paths. The example given uses a list of length 1 to specify a single point. \u21a9 This example will use the DFPT method which is the default if phonon_method is not present. \u21a9 Further optional output writing to .castep of the dynamical matrixes and force constant matrices is enabled at any iprint level by the parameters phonon_write_dynamical and phonon_write_force_constants respectively. \u21a9 The Placzek theory applies to the case of insulators only, and no general formulation to compute the activity for Raman scattering of conducting systems is available \u21a9 If the parameter raman_method : FINITEDISPLACEMENT is set the calculation uses an older, finite-difference implementation (see section [fd] ) to compute the mode displacement derivatives of the polarizability tensor (section [efield] ) using the approach of Porezag and Pedersen ( Porezag and Pederson 1996 ). The first stage is to perform a full phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 , to determine the mode eigenvectors and identify the Raman-active modes. Then CASTEP loops over the active modes only computing the Raman tensor, activity and depolarization for each. This method is deprecated as obsolete and computationally expensive. \u21a9 The offset may be specified as three fractions of the grid spacing, so 1/2p \\; 1/2q \\; 1/2r 1/2p \\; 1/2q \\; 1/2r shifts the grid exactly half a subdivision in each of the three directions. As of release 24.1 the INCLUDE_GAMMA keyword will automate this calculation and in fact is the default so that omitting phonon_kpoint_mp_offset entirely will do the right thing. \u21a9 The latter is governed by the effective range of electronic interactions which bears no relationship to the elastic range of the atomic displacements as required for the force constants. \u21a9 The effect is usually small for LDA, intermediate for PBE and largest for PW91, as the gradient terms are most sensitive to the ASR violation. \u21a9 (or fine_gmax or fine_cut_off_energy \u21a9 There is one known case where the reciprocal-space ASR correction fails to give the correct behaviour. Two-dimensional planar or layered systems with weak inter-layer bonding such as graphene or graphite exhibit a quadratic behaviour of an acoustic mode near \\Gamma \\Gamma . The reciprocal space scheme fails to reproduce the correct, quadratic behaviour and linearises the dispersion. The realspace method generates correct behaviour in these cases. \u21a9 A non-negligible force constant at longer range may also occur in a metallic system in the presence of a Kohn anomaly. \u21a9 Specifically, the error in the second-order energy or force constants is variational, and therefore depends quadratically on the error in the DFPT first-order response orbitals. However it is non-variational and linear with respect to the error in the ground-state orbitals. The practical consequence is that there is an error in DFPT results which varies as the square root of the ground-state convergence parameter elec_energy_tol which therefore must be very small for good accuracy. A heuristic rule of thumb is that elec_energy_tol \\approx \\approx phonon_energy_tol ^2 ^2 is necessary to converge the second order energy to the value of phonon_energy_tol . \u21a9","title":"Convergence of Interpolation and Supercell"},{"location":"documentation/Phonons/Castep_Phonons/Thermodynamic-properties/","text":"One of the important motivations for lattice dynamical calculations of crystalline solids is that the harmonic approximation gives access to thermodynamic properties including the zero-point energy and the free energy as a function of temperature. CASTEP lattice dynamics calculations can be followed by a thermodynamics calculation to calculate the zero-point energy and temperature dependent free energy, entropy, and specific heat \\begin{aligned} F &= E_{\\text{elec}} + k_{B} T \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ S &= \\frac{1}{2T} \\sum_{{\\mathbf{q}},i} \\hbar \\omega_{{\\mathbf{q}},i} \\coth \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) - k_{B} \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ C_V &= \\sum_{{\\mathbf{q}},i} k_{B} \\left ( \\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right )^2 \\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} /% \\left [\\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} -1 \\right ]^2 . \\end{aligned} \\begin{aligned} F &= E_{\\text{elec}} + k_{B} T \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ S &= \\frac{1}{2T} \\sum_{{\\mathbf{q}},i} \\hbar \\omega_{{\\mathbf{q}},i} \\coth \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) - k_{B} \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ C_V &= \\sum_{{\\mathbf{q}},i} k_{B} \\left ( \\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right )^2 \\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} /% \\left [\\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} -1 \\right ]^2 . \\end{aligned} The thermodynamics calculation follows a previous phonon calculation. It is selected by setting the parameter task : THERMODYNAMICS This may be used in a continuation run from a previous phonon calculation, where the value of the continuation parameter is the name of the previous .check file. Alternatively it may be configured as a new run from scratch by setting the remainder of the parameters exactly as if this were a phonon task, and the phonon calculation will be performed first. Only the phonons defined on the \u201cfine\u201d set of phonon kpoints will be used to compute the free energy as it is normally expected that a thermodynamics calculation will follow an interpolation or supercell calculation. However provided that the standard and fine sets of phonon k-points are identical, it may also be used following a standard phonon calculation. This task will compute and print the free energy, entropy and specific heat plus the vibrational atomic displacement parameters (\u201cADP\u201ds) in the range of temperatures specified by the parameters thermo_t_start and thermo_t_stop . The number of temperatures is set by one or other of the parameters thermo_t_spacing or thermo_t_npoints . All temperatures are absolute and the default unit is K. The results of the calculation are written to the .castep file. The harmonic approximation free energy is only defined if all frequencies are greater than or equal to zero. Any zero or imaginary frequencies are automatically omitted from the calculation and a warning message is printed. It is the responsibility of the end user to check that the computed free energy is not rendered meaningless by the presence of an imaginary mode.","title":"Thermodynamic-properties"},{"location":"documentation/Phonons/Castep_Phonons/frontmatter/","text":"Copyright \u00a9 Science and Technology Facilities Council, 2009","title":"Phonon and related calculations using CASTEP"},{"location":"documentation/Pseudopotentials/otfg_string/","text":"In addition to Chris' OTFG document, some more description of the OTF string 2|3.1|4.0|2.2|2|3|5|50U3.4:60U3.1:51:52U3.1{6s1.45,5d0.05}(qc=3)[] Quantities in <> are descriptions not literals. All chars outside <> are literal ||||||| :...{}(flags)[] Local cpt : 0,1,2 for s,p,d r_c(loc) : pseudisation radius for local component (atomic units) r_c(nl) : pseudisation radius for nonlocal components (atomic units) (can be overridden as part of projector description) rinner/rcore : Pseudisation radius for augmentation functions and pseudo-core charge COARSE/MEDIUM/FINE : Recommended cutoff energies in atomic units (Hartree) projn : Descriptions of projectors to include, separated by semicolons. Syntax of a projector is in its briefest form where digits and denote the atomic quantum numbers eg 30 for 3s In fact this is equivalent to the expanded form \"UU\" where the projector flags \"UU\" mean include two ultrasoft beta projectors for this channel. The full form is [[]][+/-][@] where anything in brackets [] is optional (here only). can be U - a single ultrasoft projector UU - Two ultrasoft projectors N - a single norm-conserving projector L - use this projector as the local component G - an ultrasoft GIPAW Gamma projector H - an norm-conserving GIPAW Gamma projector P - Dummy: do not make a projector. LG - Make Gammas for local channel (not done by default) - the projector specific pseudisation radius. - the reference energy for the projector. A floating-point value beginning with an explicit '=', '+' or '-' in Hartree. '=E' means absolute energy, '+/-E' is relative to AE eigenvalue. - Add this value to the projector, it shift it in energy. config : Reference configuration used to generate pseudopotential specified in obvious way, eg {3s1,3d0.5}. It is not necessary to explicitly mention all core states - CASTEP figures this out. flags : Options controlling the type of pseudisation applied and parameters. Syntax (flag1,flag2, ) allows multiple, comma separated flags qc= The optmisation parameter - KE for q < qc is minimised in optimised projector scheme. Can also write (qc=3,qc1=3.5) to specify angular momentum channel-specific value of qc. tm Troullier-Martins pseudosation scheme pn polynomial fit pb bessel fit es \"extra soft\" scheme esr=val extra-soft with explicit specification of r_c nonlcc Do not generate of unscreen with a pseudo-core charge. schro Use non-relativistic schroedinger equation for AE calculation (default is scalar relativistic eqn) aug Explicitly turn on augmentation charges scpsp Generate a self-consistent pseudopotential test config : Specify a non-default test configuration eg, [4s1.5,3d0.5].","title":"OTFG string"},{"location":"documentation/Pseudopotentials/overview/","text":"CASTEP has a built-in library of pseudopotentials which is usually updated each release. We refer to CASTEP's build-in pseudopotentials as on-the-fly generated (or OTFG). The default OTFG pseudopotentials are accurate ultrasoft pseudopotentials. These are used if species_pot block is not defined in the cell file - or an empty block is given %block species_pot %endblock species_pot For preliminary investigations and high-throughput calculations you might want to choose the QC5 set of ultrasoftpotentials which are faster, but slightly less accurate than the default set. These are designed to give converged results at 500eV for all elements: %block species_pot QC5 %endblock species_pot For properties that require norm-conserving pseudopotentials, you can select CASTEP's latest OTFG norm-conserving set with the following in the in your .cell file. %block species_pot NCP %endblock species_pot For backwards compatibility you can also select pseudopotentials from earlier versions on the on-the-fly database, e.g. use %block species_pot C17 %endblock species_pot to select the ultrasoft pseudopotentials from CASTEP version 17. You can also specify the pseudopotential on a per-element basis, e.g. %block species_pot Fe C17 O NCP Ba QC5 %endblock species_pot A complete list of the availible OTFG definitions follows: String Description NCP Alias for the most recent set of norm conserving potentials QC5 High through put set (delta=1.7meV, 0.8meV excluding N,O,Cr,Mn) HARD \"Ultimate\" set of HARD pseudopotentials C7 USP definitions as of CASTEP 7.0 (C7) C8 USP definitions as of CASTEP 8.0 (C8) C9 USP definitions as of CASTEP 9.0/16.0 delta=0.5meV NCP9 Set of Norm Conserving pseudopotentials CASTEP 9.0/16.0 (NCP9)(delta=1.1meV) C17 USP definitions, CASTEP 17.0 (C17) NCP17 Set of Norm Conserving pseudopotentials CASTEP 17.0 (NCP17) C18 USP definitions, CASTEP 18.0 (C18) NCP18 Norm Conserving pseudopotentials CASTEP 18.0 (NCP18) C19 USP definitions, CASTEP 19.0 (C19) delta=0.442 meV (default for CASTEPv19 up to and including CASTEPv24) 1 NCP19 Norm Conserving pseudopotentials CASTEP 19.0 (NCP19) delta=1.098 meV C19mk2 USP definitions. Updated Lanthanide and Actinide definitions, but otherwise identical to C19. Default for CASTEPv25 and later 2 Pseudopotential files CASTEP can also read in pseudopotentials from files Format Origin .usp as generated by CASTEP (note both USP and NCP use this format) .uspso as generated by CASTEP, with spin-orbit coupling .recpot as generated by OPIUM (also legacy CASTEP files) .UPF as generated by Quantum Espresso Note that properties using PAW augmentation will not be available when using file based pseudopotentials (OTFG is required) - this includes all NMR/EPR properties and EELS spectra. Kurt Lejaeghere, Gustav Bihlmayer, Torbj\u00f6rn Bj\u00f6rkman, Peter Blaha, Stefan Bl\u00fcgel, Volker Blum, Damien Caliste, Ivano E. Castelli, Stewart J. Clark, Andrea Dal Corso, Stefano de Gironcoli, Thierry Deutsch, John Kay Dewhurst, Igor Di Marco, Claudia Draxl, Marcin Du\u0142ak, Olle Eriksson, Jos\u00e9 A. Flores-Livas, Kevin F. Garrity, Luigi Genovese, Paolo Giannozzi, Matteo Giantomassi, Stefan Goedecker, Xavier Gonze, Oscar Gr\u00e5n\u00e4s, E. K. U. Gross, Andris Gulans, Fran\u00e7ois Gygi, D. R. Hamann, Phil J. Hasnip, N. A. W. Holzwarth, Diana Iu\u015fan, Dominik B. Jochym, Fran\u00e7ois Jollet, Daniel Jones, Georg Kresse, Klaus Koepernik, Emine K\u00fc\u00e7\u00fckbenli, Yaroslav O. Kvashnin, Inka L. M. Locht, Sven Lubeck, Martijn Marsman, Nicola Marzari, Ulrike Nitzsche, Lars Nordstr\u00f6m, Taisuke Ozaki, Lorenzo Paulatto, Chris J. Pickard, Ward Poelmans, Matt I. J. Probert, Keith Refson, Manuel Richter, Gian-Marco Rignanese, Santanu Saha, Matthias Scheffler, Martin Schlipf, Karlheinz Schwarz, Sangeeta Sharma, Francesca Tavazza, Patrik Thunstr\u00f6m, Alexandre Tkatchenko, Marc Torrent, David Vanderbilt, Michiel J. van Setten, Veronique Van Speybroeck, John M. Wills, Jonathan R. Yates, Guo-Xu Zhang, and Stefaan Cottenier. Reproducibility in density functional theory calculations of solids. Science , 351(6280):aad3000, 2016. URL: https://www.science.org/doi/abs/10.1126/science.aad3000 , arXiv:https://www.science.org/doi/pdf/10.1126/science.aad3000 , doi:10.1126/science.aad3000 . \u21a9 Sebastiaan P. Huber, Emanuele Bosoni, Marnik Bercx, Jens Br\u00f6der, Augustin Degomme, Vladimir Dikan, Kristjan Eimre, Espen Flage-Larsen, Alberto Garcia, Luigi Genovese, Dominik Gresch, Conrad Johnston, Guido Petretto, Samuel Ponc\u00e9, Gian-Marco Rignanese, Christopher J. Sewell, Berend Smit, Vasily Tseplyaev, Martin Uhrin, Daniel Wortmann, Aliaksandr V. Yakutovich, Austin Zadoks, Pezhman Zarabadi-Poor, Bonan Zhu, Nicola Marzari, and Giovanni Pizzi. Common workflows for computing material properties using different quantum engines. npj Computational Materials , 7(1):136, Aug 2021. URL: https://doi.org/10.1038/s41524-021-00594-6 , doi:10.1038/s41524-021-00594-6 . \u21a9","title":"Overview"},{"location":"documentation/Pseudopotentials/overview/#pseudopotential-files","text":"CASTEP can also read in pseudopotentials from files Format Origin .usp as generated by CASTEP (note both USP and NCP use this format) .uspso as generated by CASTEP, with spin-orbit coupling .recpot as generated by OPIUM (also legacy CASTEP files) .UPF as generated by Quantum Espresso Note that properties using PAW augmentation will not be available when using file based pseudopotentials (OTFG is required) - this includes all NMR/EPR properties and EELS spectra. Kurt Lejaeghere, Gustav Bihlmayer, Torbj\u00f6rn Bj\u00f6rkman, Peter Blaha, Stefan Bl\u00fcgel, Volker Blum, Damien Caliste, Ivano E. Castelli, Stewart J. Clark, Andrea Dal Corso, Stefano de Gironcoli, Thierry Deutsch, John Kay Dewhurst, Igor Di Marco, Claudia Draxl, Marcin Du\u0142ak, Olle Eriksson, Jos\u00e9 A. Flores-Livas, Kevin F. Garrity, Luigi Genovese, Paolo Giannozzi, Matteo Giantomassi, Stefan Goedecker, Xavier Gonze, Oscar Gr\u00e5n\u00e4s, E. K. U. Gross, Andris Gulans, Fran\u00e7ois Gygi, D. R. Hamann, Phil J. Hasnip, N. A. W. Holzwarth, Diana Iu\u015fan, Dominik B. Jochym, Fran\u00e7ois Jollet, Daniel Jones, Georg Kresse, Klaus Koepernik, Emine K\u00fc\u00e7\u00fckbenli, Yaroslav O. Kvashnin, Inka L. M. Locht, Sven Lubeck, Martijn Marsman, Nicola Marzari, Ulrike Nitzsche, Lars Nordstr\u00f6m, Taisuke Ozaki, Lorenzo Paulatto, Chris J. Pickard, Ward Poelmans, Matt I. J. Probert, Keith Refson, Manuel Richter, Gian-Marco Rignanese, Santanu Saha, Matthias Scheffler, Martin Schlipf, Karlheinz Schwarz, Sangeeta Sharma, Francesca Tavazza, Patrik Thunstr\u00f6m, Alexandre Tkatchenko, Marc Torrent, David Vanderbilt, Michiel J. van Setten, Veronique Van Speybroeck, John M. Wills, Jonathan R. Yates, Guo-Xu Zhang, and Stefaan Cottenier. Reproducibility in density functional theory calculations of solids. Science , 351(6280):aad3000, 2016. URL: https://www.science.org/doi/abs/10.1126/science.aad3000 , arXiv:https://www.science.org/doi/pdf/10.1126/science.aad3000 , doi:10.1126/science.aad3000 . \u21a9 Sebastiaan P. Huber, Emanuele Bosoni, Marnik Bercx, Jens Br\u00f6der, Augustin Degomme, Vladimir Dikan, Kristjan Eimre, Espen Flage-Larsen, Alberto Garcia, Luigi Genovese, Dominik Gresch, Conrad Johnston, Guido Petretto, Samuel Ponc\u00e9, Gian-Marco Rignanese, Christopher J. Sewell, Berend Smit, Vasily Tseplyaev, Martin Uhrin, Daniel Wortmann, Aliaksandr V. Yakutovich, Austin Zadoks, Pezhman Zarabadi-Poor, Bonan Zhu, Nicola Marzari, and Giovanni Pizzi. Common workflows for computing material properties using different quantum engines. npj Computational Materials , 7(1):136, Aug 2021. URL: https://doi.org/10.1038/s41524-021-00594-6 , doi:10.1038/s41524-021-00594-6 . \u21a9","title":"Pseudopotential files"},{"location":"documentation/Pseudopotentials/reading_headers/","text":"At the start of a calculation CASTEP will generate the require pseudopotentials. A report is written into the start of the .castep file. This page explains what information is contained within this header. Carbon - Ultrasoft ============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.395 qc 0 | | 2 0 0.250 1.395 qc 0 | | 3 1 -0.194 1.395 qc 0 | | 4 1 0.250 1.395 qc 0 | | loc 2 0.000 1.395 pn 0 | | | | Augmentation charge Rinner = 0.983 | | Partial core correction Rc = 0.983 | ------------------------------------------------------------ | \"2|1.4|10|12|13|20:21(qc=7)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ All quantities are given in atomic units - so energies in Hartree (1Ha =26.4eV) and lengths in Bohr (1 bohr = 0.88Ang) Element: This is just the symbol for the element Ionic Charge: Sum of nuclear charge and the core electrons (C Z=6 core=1s2 gives ionic charge as +6-2=+4) Level of theory: The Exchange-Correlation potential used. Atomic-solver: Koelling-Harmon is the default atomic solver. Reference electronic structure. This section describes the valence states included in the calculation. For Carbon these are the 2s and 2p states. Their occupations and energies are given. Pseudopotential Definition (Advanced) The definitions of each of the non-local projector (aka beta projectors) is given here. Beta - the number of the projector l - angular momentum quantum number e - energy of the corresponding orbital Rc - Cutoff (matching) radius for the orbital scheme - pseudization scheme (qc = qc tuned) norm - 1=norm-conserving 0-ultrasoft (norm not conserved) This is a standard Ultrasoft pseudopotential with two beta projectors per angular momentum channel. One projector is from an orbital at the eigen-energy (i.e. -0.505Ha for 2s) while the second projector corresponds to a non-bound orbital at an energy of 0.25Ha. The final line gives the choice of local potential. In this case the local potential is constructed from a l=2 state with the same cutoff radius as for the local projectors. Augmentation charge Rinner . This is specific to the Ultrasoft scheme - and describes the radius outside which the augmentation charge matches the all-electron charge. Partial core correction . As the exchange correlation energy is a non-linear function of charge there is an error introduced if we compute the xc energy of the valence and core electron separately. We therefore include the core charge in the calculation of the xc energy. The core charge is challenging to represent on a grid - and so a pseudized core charge is used. Rc is the cut-off for this pseudized core charge. Carbon - Normconserving ============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.201 qc 1 | | loc 1 -0.194 1.201 qc 1 | | | | No charge augmentation | | Partial core correction Rc = 0.839 | ------------------------------------------------------------ | \"1|1.2|17|20|23|20N:21L(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ Note that the Reference Electronic Structure section is identical to the ultrasoft potential above. This relates to the all-electron atom and is unaffected by the details of the pseudopotential. From the pseudopotential definition we see there is one beta projector for l=0 (s) and the local potential is set to be l=1 (p). For norm-conserving potentials it is common to only need one projector per angular momentum chanel, and for one of the occupied channels to be represented by the local potential. There is no charge augmentation (this is only needed for ultrasofts) however, a non-linear core correction is used. Uranium - J-dependent ============================================================ | Pseudopotential Report - Date of generation 4-07-2020 | ------------------------------------------------------------ | Element: U Ionic charge: 14.00 Level of theory: LDA | | Atomic Solver: Dirac (FR) | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 6s1/2 2.000 -1.748 | | 6p1/2 2.000 -1.101 | | 6p3/2 4.000 -0.776 | | 7s1/2 2.000 -0.161 | | 5f5/2 1.286 -0.147 | | 5f7/2 1.714 -0.116 | | 6d3/2 0.400 -0.103 | | 6d5/2 0.600 -0.085 | | | | Pseudopotential Definition | | Beta l 2j e Rc scheme norm | | 1 0 1 -1.748 2.106 qc 1 | | 2 0 1 -0.161 2.106 qc 1 | | 3 1 3 -0.776 2.106 qc 1 | | 4 1 1 -1.101 2.106 qc 1 | | 5 2 5 -0.085 2.106 qc 1 | | 6 2 3 -0.103 2.106 qc 1 | | 7 3 7 -0.116 2.106 qc 1 | | 8 3 5 -0.147 2.106 qc 1 | | loc 4 0 0.000 2.106 pn 0 | | | | No charge augmentation | | Partial core correction Rc = 1.472 | ------------------------------------------------------------ | \"4|2.1|17|19|22|60N:70N:61N:62N:53N(qc=6,q3=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ This pseudopotential is calculated by using a Dirac equation solver including the spin-orbit interaction (FR=fully relativistic). It is a norm-conserving potential. There are 14 electrons included in the valence (6s2,7s2,6p6,6d1,5f3). Because of the spin orbit splitting states with different j quantum numbers have different energies. States with l>0 are split into j=l+1/2 j=l+1/2 and j=l-1/2 j=l-1/2 (e.g. the 6p states are split into 6p\u00bd and 6p3/2, the 5f into 5f5/2 5f7/2).","title":"Headers"},{"location":"documentation/Pseudopotentials/reading_headers/#carbon-ultrasoft","text":"============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.395 qc 0 | | 2 0 0.250 1.395 qc 0 | | 3 1 -0.194 1.395 qc 0 | | 4 1 0.250 1.395 qc 0 | | loc 2 0.000 1.395 pn 0 | | | | Augmentation charge Rinner = 0.983 | | Partial core correction Rc = 0.983 | ------------------------------------------------------------ | \"2|1.4|10|12|13|20:21(qc=7)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ All quantities are given in atomic units - so energies in Hartree (1Ha =26.4eV) and lengths in Bohr (1 bohr = 0.88Ang) Element: This is just the symbol for the element Ionic Charge: Sum of nuclear charge and the core electrons (C Z=6 core=1s2 gives ionic charge as +6-2=+4) Level of theory: The Exchange-Correlation potential used. Atomic-solver: Koelling-Harmon is the default atomic solver.","title":"Carbon - Ultrasoft"},{"location":"documentation/Pseudopotentials/reading_headers/#reference-electronic-structure","text":"This section describes the valence states included in the calculation. For Carbon these are the 2s and 2p states. Their occupations and energies are given.","title":"Reference electronic structure."},{"location":"documentation/Pseudopotentials/reading_headers/#pseudopotential-definition-advanced","text":"The definitions of each of the non-local projector (aka beta projectors) is given here. Beta - the number of the projector l - angular momentum quantum number e - energy of the corresponding orbital Rc - Cutoff (matching) radius for the orbital scheme - pseudization scheme (qc = qc tuned) norm - 1=norm-conserving 0-ultrasoft (norm not conserved) This is a standard Ultrasoft pseudopotential with two beta projectors per angular momentum channel. One projector is from an orbital at the eigen-energy (i.e. -0.505Ha for 2s) while the second projector corresponds to a non-bound orbital at an energy of 0.25Ha. The final line gives the choice of local potential. In this case the local potential is constructed from a l=2 state with the same cutoff radius as for the local projectors. Augmentation charge Rinner . This is specific to the Ultrasoft scheme - and describes the radius outside which the augmentation charge matches the all-electron charge. Partial core correction . As the exchange correlation energy is a non-linear function of charge there is an error introduced if we compute the xc energy of the valence and core electron separately. We therefore include the core charge in the calculation of the xc energy. The core charge is challenging to represent on a grid - and so a pseudized core charge is used. Rc is the cut-off for this pseudized core charge.","title":"Pseudopotential Definition (Advanced)"},{"location":"documentation/Pseudopotentials/reading_headers/#carbon-normconserving","text":"============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.201 qc 1 | | loc 1 -0.194 1.201 qc 1 | | | | No charge augmentation | | Partial core correction Rc = 0.839 | ------------------------------------------------------------ | \"1|1.2|17|20|23|20N:21L(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ Note that the Reference Electronic Structure section is identical to the ultrasoft potential above. This relates to the all-electron atom and is unaffected by the details of the pseudopotential. From the pseudopotential definition we see there is one beta projector for l=0 (s) and the local potential is set to be l=1 (p). For norm-conserving potentials it is common to only need one projector per angular momentum chanel, and for one of the occupied channels to be represented by the local potential. There is no charge augmentation (this is only needed for ultrasofts) however, a non-linear core correction is used.","title":"Carbon - Normconserving"},{"location":"documentation/Pseudopotentials/reading_headers/#uranium-j-dependent","text":"============================================================ | Pseudopotential Report - Date of generation 4-07-2020 | ------------------------------------------------------------ | Element: U Ionic charge: 14.00 Level of theory: LDA | | Atomic Solver: Dirac (FR) | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 6s1/2 2.000 -1.748 | | 6p1/2 2.000 -1.101 | | 6p3/2 4.000 -0.776 | | 7s1/2 2.000 -0.161 | | 5f5/2 1.286 -0.147 | | 5f7/2 1.714 -0.116 | | 6d3/2 0.400 -0.103 | | 6d5/2 0.600 -0.085 | | | | Pseudopotential Definition | | Beta l 2j e Rc scheme norm | | 1 0 1 -1.748 2.106 qc 1 | | 2 0 1 -0.161 2.106 qc 1 | | 3 1 3 -0.776 2.106 qc 1 | | 4 1 1 -1.101 2.106 qc 1 | | 5 2 5 -0.085 2.106 qc 1 | | 6 2 3 -0.103 2.106 qc 1 | | 7 3 7 -0.116 2.106 qc 1 | | 8 3 5 -0.147 2.106 qc 1 | | loc 4 0 0.000 2.106 pn 0 | | | | No charge augmentation | | Partial core correction Rc = 1.472 | ------------------------------------------------------------ | \"4|2.1|17|19|22|60N:70N:61N:62N:53N(qc=6,q3=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ This pseudopotential is calculated by using a Dirac equation solver including the spin-orbit interaction (FR=fully relativistic). It is a norm-conserving potential. There are 14 electrons included in the valence (6s2,7s2,6p6,6d1,5f3). Because of the spin orbit splitting states with different j quantum numbers have different energies. States with l>0 are split into j=l+1/2 j=l+1/2 and j=l-1/2 j=l-1/2 (e.g. the 6p states are split into 6p\u00bd and 6p3/2, the 5f into 5f5/2 5f7/2).","title":"Uranium - J-dependent"},{"location":"documentation/Pseudopotentials/theory/","text":"The electrons in an atom can be divided into two types --- core electrons and valence electrons. The core electrons are tightly bound to the nucleus, while the valence electrons are more extended. A working definition for core electrons is that they are the ones which play no part in the interactions between atoms, while the valence electrons dictate most of the properties of the material. It is common to make the frozen core approximation; the core electrons are constrained not to differ from their free atomic nature when placed in the solid state environment. This reduces the number of electronic degrees of freedom in an all-electron calculation. It is a very good approximation. A different, but physically related, approach is taken in the pseudopotential approximation. Since, in an all-electron calculation, the valence electron wavefunctions must be orthogonal to the core wavefunctions they necessarily have strong oscillations in the region near the nucleus (see the all-electron wavefunction in Figure~\\ref{fig:wvfn}). Given that a planewave basis set is to be used to describe the wavefunctions, these strong oscillations are undesirable --- requiring many plane waves for an accurate description. Further, these oscillations are of very little consequence for the electronic structure in the solid, since they occur close to the nucleus. In the pseudopotential approach only the valence electrons are explicitly considered, the effects of the core electrons being integrated within a new ionic potential. The valence wavefunctions need no longer be orthogonal to the core states, and so the orthogonality oscillations disappear; hence far fewer plane waves are required to describe the valence wavefunctions. Numerous schemes to produce optimally soft pseudopotentials have been developed. Common choices are the norm-conserving potentials due to Troullier and Martins 1 and Vanderbilt's ultrasoft scheme 2 . N. Troullier and Jos\u00e9 Lu\u00eds Martins. Efficient pseudopotentials for plane-wave calculations. Phys. Rev. B , 43:1993\u20132006, Jan 1991. doi:10.1103/PhysRevB.43.1993 . \u21a9 David Vanderbilt. Soft self-consistent pseudopotentials in a generalized eigenvalue formalism. Phys. Rev. B , 41:7892\u20137895, Apr 1990. doi:10.1103/PhysRevB.41.7892 . \u21a9","title":"Theory"},{"location":"documentation/Spectral/keywords/","text":"SPECTRAL_TASK - determines what will be calculated. All tasks will compute the eigenenergies (aka bands). The list of tasks, and the extra properties calculated are as follows: bandstructure dos band gradients optics optical matrix elements pdos atomic projections coreloss dipole matrix elements with core states Most spectral calculations will involve the calculation of unoccupied states. One of the following parameters should be set to determine the number of states calculated. SPECTRAL_NEXTRA_BANDS number of extra spectral bands SPECTRAL_PERC_EXTRA_BANDS percentage of extra spectral bands SPECTRAL_NBANDS number of bands/k-point in spectral calc It is possible to use a different exchange-correlation functional to the one used for the groundstate. An example might be when a semi-local functional (such as PBE) is used for the groundstate, and a more expensive non-local functional (e.g. PBE0) is used for the spectral calculation. This is an approximation and should be done with cuation. To set the xc functional use one of the two keywords. SPECTRAL_XC_FUNCTIONAL spectral exchange-correlation functional SPECTRAL_XC_DEFINITION spectral exchange-correlation functional To change the convergence tolerance for the eigenvalues set SPECTRAL_EIGENVALUE_TOL ! default: 10E-6 eV SPECTRAL_MAX_ITER maximum iterations in spectral calculation SPECTRAL_MAX_STEPS_PER_ITER maximum steps per iter in spectral calculation","title":"Keywords"},{"location":"documentation/Spectral/overview/","text":"`","title":"Overview"},{"location":"documentation/Spectral/restarts/","text":"Spectral calculations do not write a check file - however, they can write backups to enable restarting an unfinished calculation. The limitation is that a parallel calculation must be restarted on the same number of processors. #Sample param file cut_off_energy : 550 eV fix_occupancy : true task : spectral spectral_task : coreloss %block devel_code SPECTRAL_RESTART %endblock devel_code backup_interval 1800 ! time in seconds The devel_code keyword SPECTRAL_RESTART triggers both the writing an reading of Spectral backup files. backup_interval determines the time between writing backups. Backup will slow down the calculation as they require disk access (which is always slow). If you expect a job to run for several hours backing up every 30min is a reasonable compromise. After completing each k-point the CASTEP will check to see if time since the last backup is greater than backup_interval - is it is a backup will be written - if not CASTEP carries on with the next k-point. Note that a backup is always written (if backup_interval>0) after the final kpoint. This is useful insurance in case there is any problem when CASTEP writes the final output files. Here is an example .castep file with backup ===================================================================== + + + Calculation of Spectral Properties + + + + Calculation re-parallelised over 2 processes. + + Data distributed by G-vector(1-way), k-point(2-way), band(1-way) + + Data distributed by k-point(2-way) + + + ===================================================================== Starting k-point: 1 of 5 on this process |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC Starting k-point: 5 of 5 on this process |<-- SPEC Starting k-point: 1 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC We see that backups were written every three k-points. The last backup was done after the 1 st k-point for spin 2. As this calculation was run on two processors, we find two backup files have been created -rw-r--r-- 1 317700 18 Jul 10:53 Si2-core.0001.spec -rw-r--r-- 1 317700 18 Jul 10:53 Si2-core.0002.spec To restart, keep everything the same but add to the param file continuation : xxx.check Where xxx.check is the name of the check file containing the ground-state density etc. This will have been written during the first run - and xxx will be replaced with whatever is the seedname of your run. We now re-run the calculation. CASTEP will read the ground-state from the check file (so there should be no electronic minimisation) Restarting spectral calculation from restart file |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 5 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Total time to compute matrix elements 3500.45 sec |<\u2014- SPEC So the calculation did restart from the 2 nd k-point on spin 2.","title":"Restarts"},{"location":"documentation/TDDFT/overview/","text":"","title":"TDDFT Overview"},{"location":"documentation/Tools/tools/","text":"This page lists various analysis codes (some supplied with the CASTEP distribution as well as other third-party codes) which interoperate with CASTEP. Some of these programs require additional interface codes/scripts to take CASTEP output as their input, etc. Pre-processing Tools c2x (also bundled with the CASTEP distribution) reads and converts a selection of crystal structure file formats including .cif which relate to DFT and perform structure manipulations. It can rotate cells, make supercells, add vacuum space, create slabs and nanotubes. Cif2Cell is a tool to generate the geometrical setup for various electronic structure codes from a CIF (Crystallographic Information Framework) file. Also supports supercell generation and formats for visualisation tools. SeeK-path is a k-path finder that provides band paths compatible with space group symmetry, and an interactive 3D visualiser. Convergence Testing castepconv CASTEPconv (also bundled with the CASTEP distribution) automates convergence testing of plane-wave cutoff, k-point density and fine grid scale. Based on a proforma input, it prepares the files, analyses the output and generates summary data files. A standalone version is shipped with CASTEP source. Later versions depend upon ASE and can be downloaded from github ( https://github.com/CCP-NC/castepconv ) and can also generate plots. General Postprocessing castep-outputs is a Python package to read and parse all of the output files of CASTEP into a standard form. This is the recommended CASTEP output parser interface. A simple CLI tool is provided to dump a .json file, but its main use is intended as a library to be called from future analysis codes. This is the recommended interface for developers of Python analysis tools. Currently this reads and parses all CASTEP text-format files but not the binary ones. castepxbin is a collection of readers for CASTEP binary output files .check , .castep_bin , .orbitals etc. c2x (also bundled with the CASTEP distribution) can read CASTEP binary output files .check , .castep_bin , .orbitals and extract cell geometry data, electron densities , wavefunctions and prepare for visualization and further analysis. It can interpolate densities via a combination of trilinear and Fourier interpolation, integrate densities and calculate their dipole moments, and analyse bands for inversion symmetry. It can be used to produce output formats compatible with XCrysDen, VESTA, VMD and Jmol amongst others, and can also produce 1D data in a format suitable for gnuplot. Spectroscopy Modelling Tools dispersion.pl and dos.pl (part of CASTEP distribution) are tools for producing band-structure and density of states plots from a CASTEP .bands file. They also support creating phonon dispersion and DOS plots. Dispersion.pl will perform simple modelling of a powder Raman spectrum for a specified laser frequency and temperature. OptaDOS is a code for calculating optical, core-level excitation spectra along with full, partial and joint electronic density of states (DOS). SUMO is a suite of tools for electronic band structure and phonon dispersion analysis and plotting. PDielec calculates model powder infra-red spectra including optical cavity effects from CASTEP (and other) phonon calculations. orbitals2bands (part of CASTEP distribution) Reads a CASTEP .orbitals file from a spectral/bandstructure calculation, analyses the band crossings and generates a .bands file with reordered eigenvalues for producing a bandstructure plot with crossings taken into account. bs_sc2pc (part of CASTEP distribution) is a band structure unfolding tool for CASTEP. It implements the effective band structure method described by Popescu and Zunger http://dx.doi.org/10.1103/PhysRevB.85.085201|10.1103/PhysRevB.85.085201 , and is distributed as part of the CASTEP academic distribution. Peter Brommer and David Quigley (2014) \"Automated effective band structures for defective and mismatched supercells.\" J. Phys.: Condens. Matter 26 485501. http://dx.doi.org/10.1088/0953-8984/26/48/485501|10.1088/0953-8984/26/48/485501 . band_up is another program for performing band unfolding calculations on defective supercells. easyunfold is yet another band unfolding tool, with CASTEP support. PhononUnfolding is a program for unfolding of phonon dispersions. mode_follow (part of CASTEP distribution) reads a .phonon output file and generates a sequence of .cell input files for single-point energy calculations to compute the energy profile along a mode for plotting and to analyse for anharmonicity or double-well depth. molpdos (part of CASTEP distribution) calculates DOS, and DOS projected onto molecular states, as part of a Delta SCF calculation. Abins is a plugin for Mantid which allows scientists to compare experimental and theoretical inelastic neutron scattering spectra. AbINS uses the phonon data calculated by DFT programs, such as CASTEP, to generate an INS spectra of a powder sample, which makes it easier to establish a connection between theory and experiments. Euphonic is a library and front-end for calculating the inelastic neutron scattering spectral function in 4-D ( Q , \\omega \\omega ) space to compare with data from a in a single-crystal time-of-flight INS spectrometer. OCLIMAX is a free program for simulation of inelastic neutron scattering using vibrational frequencies and polarization vectors as input. It can perform simulations on both powder and single crystal samples, and the input phonon data can be obtained from first-principles or empirical calculations. phonopy is an open source package for phonon calculations at harmonic and quasi-harmonic levels. phono3py calculates phonon-phonon interaction and related properties using the supercell approach. These properties include the lattice thermal conductivity, joint density of states and the phonon lifetimes. Visualisation CrystalMaker is a visualisation suite for designing and investigating crystal and molecular structures. It also provides support for modelling and animation of atomistic and electronic properties. JMOL is an open-source browser-based HTML5 viewer and stand-alone Java viewer for chemical structures in 3D with features for molecules, crystals, materials, and biomolecules. It is able to read CASTEP .cell , .castep , .den_fmt , . elf-fmt , .geom , .md , .phonon and more, with rendering of crystal structure, densities, ELF etc. and animation of optimization or MD trajectories and phonon vibrations. MagresView is a tool for visualization and processing of computed solid-state NMR parameters. OVITO is a scientific visualization and analysis software for atomistic and particle simulation data. VESTA is a 3D visualization program for structural models, volumetric data such as electron/nuclear densities, and crystal morphologies. XCrysDen is a crystalline and molecular structure visualisation program aiming at display of isosurfaces and contours, which can be superimposed on crystalline structures and interactively rotated and manipulated. ( .c2x can convert CASTEP output to the .xsf format, and other converters are supplied as part of the CASTEP distribution) castep2fs is a CASTEP utility for taking a CASTEP output and producing publication quality Fermi Surfaces and related quantities. castep2cube (Part of CASTEP distribution) reads .check or .castep_bin output files and converts the electron density to Gaussian .cube format which many other visualisation tools can read. Databases, Big Data and Workflow NOMAD supports CASTEP and its users. The service includes uploading, downloading, sharing, assigning DOIs, and more. Storing is guaranteed for at least 10 years, a requirement set by several funding agencies. The NOMAD Repository is also the only repository in Computational Materials Science that is recommended by NATURE Scientific Data. The repository currently contains over 10 8 entries - see the archive for the latest data. aiida-castep Interface to AiiDA workflow infrastructure. Soprano is a Python library meant to help crystallographers with the search and classification of new crystal forms for a given material. It provides a number of classes and functions to handle large amounts of candidate structures, compare them, sort them and cluster them. Structure Prediction CASTEP_GA (part of CASTEP distribution) is a crystal structure prediction tool based upon a modified Genetic Algorithm (GA) for periodic systems. It can handle 3D bulk materials, and also 2D surface reconstructions/interfaces and 1D edges of nanoribbons etc. It has a population of parent crystals, that are mutated and bred to make candidate children, that are then fed to CASTEP for (local) structure optimization. It is also possible to add structures that are randomly generated according to a random space group. After a number of generations, a candidate global minimum enthalpy structure can emerge. The functionality has also been extended to a MOGA (Multi-Objective GA) so that a Pareto front of optimal structures is generated, with minimum enthalpy on one axis, and a user defined property on the other. Example scripts that can be used to generate this property value are included in the distribution. Finally, recent work has been on the CHGA (Convex Hull GA) approach, wherein the stoichiometry is optimized as well, resulting in the generation of a multi-dimensional convex hull. More detailed documentation is included in the 'ReadMe' directory. AIRSS (''Ab initio Random Structure Searching'') is a very simple, yet powerful and highly parallel, approach to structure prediction. It generates random sensible structures and relaxes them to nearby minima. The sensible random structures are constructed so that they have reasonable densities, and atomic separations. Additionally they may embody crystallographic, chemical or prior experimental/computational knowledge. Beyond these explicit constraints the emphasis is on a broad, uniform, sampling of structure space. It is tightly integrated with CASTEP and has been used in a number of landmark studies to find novel phases of materials. Calypso (''Crystal structure AnaLYsis by Particle Swarm Optimization'') is an efficient structure prediction code. The approach requires only chemical compositions for a given compound to predict stable or metastable structures at given external conditions and can be used to predict/determine the crystal structure and design multi-functional materials. USPEX (''Universal Structure Predictor: Evolutionary Xtallography'') is a method developed by the Oganov laboratory for crystal structure prediction. It can very efficiently handle molecular crystals (including those with flexible and very complex molecules) and can predict stable chemical compositions and corresponding crystal structures, given just the names of the chemical elements. In addition to this fully non-empirical search, USPEX allows one to predict also a large set of robust metastable structures and perform several types of simulations using various degrees of prior knowledge. XtalOPT is a free and truly open source evolutionary algorithm designed for a priori crystal structure prediction implemented as an extension to the Avogadro molecular editor. MD analysis geom2xyz.pl , geom2xsf , geom2dcd (part of CASTEP distribution) are filters to convert CASTEP .geom and .md output files to other trajectory formats and may be used to interface with a number of other analysis codes. md_to_phonon (part of CASTEP distribution) is a simple python tool for reading a CASTEP trajectory file and performing various phonon-based analyses, including mass-weighted velocity autocorrelation function (VACF) vs frequency (which is close to the experimental VDOS). It can also project out a particular eigenmode and eigenvector from a user specified peak in the VACF and write as a single-mode CASTEP phonon file for visualization by other tools, e.g. JMol. MDANSE (''Molecular Dynamics Analysis for Neutron Scattering Experiments'') is a python application designed for computing properties that can be directly compared with neutron scattering experiments such as the coherent and incoherent intermediate scattering functions and their Fourier transforms, the elastic incoherent structure factor, the static coherent structure factor or the radial distribution function. LiquidLib is a \"comprehensive toolbox for analyzing classical and ab initio molecular dynamics simulations of liquids and liquid-like matter with applications to neutron scattering experiments\". potfit attempts to fit a model forcefield to a data set provided. There is a python converter tool in the CASTEP distribution for reading a CASTEP trajectory file and generating an atomic configuration file to be used as input for the potfit code. MDTEP is a simple code for analysing MD trajectories and calculating thermodynamic properties such as the heat capacity and the velocity autocorrelation function. Machine-Learned Potentials QUIP is is a collection of software tools to carry out molecular dynamics simulations. It implements a variety of interatomic potentials and tight binding quantum mechanics. See https://pubs.aip.org/aip/jcp/article/159/4/044803/2904492/Machine-learned-acceleration-for-molecular . Transport ShengBTE is a software package for solving the Boltzmann Transport Equation for phonons. Its main purpose is to compute the lattice contribution to the thermal conductivity of bulk crystalline solids, but nanowires can also be treated under a hypothesis of diffusive boundary conditions. AlmaBTA extends the ShengBTE approach currently employed for homogeneous bulk materials, into the mesoscale, to fully describe thermal transport from the electronic ab initio level, through the atomistic one, all the way into the mesoscopic structure level. BoltzTraP is a program for calculating the semi-classic transport coefficients. BoltzTrap2 is a modern implementation of the smoothed Fourier interpolation algorithm for electronic bands that formed the base of the original and widely used BoltzTraP code. One of the most typical uses of BoltzTraP is the calculation of thermoelectric transport coefficients as functions of temperature and chemical potential in the rigid-band picture. However, many other features are available, including 3D plots of Fermi surfaces based on the reconstructed bands. EMC (''Effective Mass Calculator'') implements calculation of the effective masses at the bands extrema using finite difference method. There are two versions of the program: written in FORTRAN and Python. Miscellaneous ASE is a set of tools and Python modules for setting up, manipulating, running, visualizing and analyzing atomistic simulations. The code is freely available under the GNU LGPL license. It can interface with many different electronic structure codes. Bader is a tool to perform Bader charge analysis on a charge density grid. Typically in molecular systems, the charge density reaches a minimum between atoms and this is a natural place to separate atoms from each other. Besides being an intuitive scheme for visualizing atoms in molecules, Bader's definition is often useful for charge analysis. For example, the charge enclosed within the Bader volume is a good approximation to the total electronic charge of an atom. ATAT (Alloy Theoretic Automated Toolkit) is a collection of alloy theory tools developed by Axel van de Walle. CASINO is a computer program system for performing quantum Monte Carlo (QMC) electronic structure calculations that has been developed by members of the Theory of Condensed Matter group in the Cambridge University physics department, and their collaborators, over more than 20 years. It is capable of calculating incredibly accurate solutions to the Schr\u00f6dinger equation of quantum mechanics for realistic systems built from atoms. An interface castep2casino is supplied with the CASTEP distribution. Emacs mode (part of CASTEP distribution) is an emacs major mode for CASTEP input files with datatype based syntax highlighting and inbuilt help functionality. i-PI is a package for performing molecular dynamics and path-integral MD via a unix socket driver interface. More details elsewhere in this site. Commercial Codes BIOVIA Materials Studio is a suite of graphical tools and codes for quantum and classical simulation of materials, and is how CASTEP is distributed commercially.","title":"Other Codes and Tools"},{"location":"documentation/Tools/tools/#pre-processing-tools","text":"c2x (also bundled with the CASTEP distribution) reads and converts a selection of crystal structure file formats including .cif which relate to DFT and perform structure manipulations. It can rotate cells, make supercells, add vacuum space, create slabs and nanotubes. Cif2Cell is a tool to generate the geometrical setup for various electronic structure codes from a CIF (Crystallographic Information Framework) file. Also supports supercell generation and formats for visualisation tools. SeeK-path is a k-path finder that provides band paths compatible with space group symmetry, and an interactive 3D visualiser.","title":"Pre-processing Tools"},{"location":"documentation/Tools/tools/#convergence-testing","text":"castepconv CASTEPconv (also bundled with the CASTEP distribution) automates convergence testing of plane-wave cutoff, k-point density and fine grid scale. Based on a proforma input, it prepares the files, analyses the output and generates summary data files. A standalone version is shipped with CASTEP source. Later versions depend upon ASE and can be downloaded from github ( https://github.com/CCP-NC/castepconv ) and can also generate plots.","title":"Convergence Testing"},{"location":"documentation/Tools/tools/#general-postprocessing","text":"castep-outputs is a Python package to read and parse all of the output files of CASTEP into a standard form. This is the recommended CASTEP output parser interface. A simple CLI tool is provided to dump a .json file, but its main use is intended as a library to be called from future analysis codes. This is the recommended interface for developers of Python analysis tools. Currently this reads and parses all CASTEP text-format files but not the binary ones. castepxbin is a collection of readers for CASTEP binary output files .check , .castep_bin , .orbitals etc. c2x (also bundled with the CASTEP distribution) can read CASTEP binary output files .check , .castep_bin , .orbitals and extract cell geometry data, electron densities , wavefunctions and prepare for visualization and further analysis. It can interpolate densities via a combination of trilinear and Fourier interpolation, integrate densities and calculate their dipole moments, and analyse bands for inversion symmetry. It can be used to produce output formats compatible with XCrysDen, VESTA, VMD and Jmol amongst others, and can also produce 1D data in a format suitable for gnuplot.","title":"General Postprocessing"},{"location":"documentation/Tools/tools/#spectroscopy-modelling-tools","text":"dispersion.pl and dos.pl (part of CASTEP distribution) are tools for producing band-structure and density of states plots from a CASTEP .bands file. They also support creating phonon dispersion and DOS plots. Dispersion.pl will perform simple modelling of a powder Raman spectrum for a specified laser frequency and temperature. OptaDOS is a code for calculating optical, core-level excitation spectra along with full, partial and joint electronic density of states (DOS). SUMO is a suite of tools for electronic band structure and phonon dispersion analysis and plotting. PDielec calculates model powder infra-red spectra including optical cavity effects from CASTEP (and other) phonon calculations. orbitals2bands (part of CASTEP distribution) Reads a CASTEP .orbitals file from a spectral/bandstructure calculation, analyses the band crossings and generates a .bands file with reordered eigenvalues for producing a bandstructure plot with crossings taken into account. bs_sc2pc (part of CASTEP distribution) is a band structure unfolding tool for CASTEP. It implements the effective band structure method described by Popescu and Zunger http://dx.doi.org/10.1103/PhysRevB.85.085201|10.1103/PhysRevB.85.085201 , and is distributed as part of the CASTEP academic distribution. Peter Brommer and David Quigley (2014) \"Automated effective band structures for defective and mismatched supercells.\" J. Phys.: Condens. Matter 26 485501. http://dx.doi.org/10.1088/0953-8984/26/48/485501|10.1088/0953-8984/26/48/485501 . band_up is another program for performing band unfolding calculations on defective supercells. easyunfold is yet another band unfolding tool, with CASTEP support. PhononUnfolding is a program for unfolding of phonon dispersions. mode_follow (part of CASTEP distribution) reads a .phonon output file and generates a sequence of .cell input files for single-point energy calculations to compute the energy profile along a mode for plotting and to analyse for anharmonicity or double-well depth. molpdos (part of CASTEP distribution) calculates DOS, and DOS projected onto molecular states, as part of a Delta SCF calculation. Abins is a plugin for Mantid which allows scientists to compare experimental and theoretical inelastic neutron scattering spectra. AbINS uses the phonon data calculated by DFT programs, such as CASTEP, to generate an INS spectra of a powder sample, which makes it easier to establish a connection between theory and experiments. Euphonic is a library and front-end for calculating the inelastic neutron scattering spectral function in 4-D ( Q , \\omega \\omega ) space to compare with data from a in a single-crystal time-of-flight INS spectrometer. OCLIMAX is a free program for simulation of inelastic neutron scattering using vibrational frequencies and polarization vectors as input. It can perform simulations on both powder and single crystal samples, and the input phonon data can be obtained from first-principles or empirical calculations. phonopy is an open source package for phonon calculations at harmonic and quasi-harmonic levels. phono3py calculates phonon-phonon interaction and related properties using the supercell approach. These properties include the lattice thermal conductivity, joint density of states and the phonon lifetimes.","title":"Spectroscopy Modelling Tools"},{"location":"documentation/Tools/tools/#visualisation","text":"CrystalMaker is a visualisation suite for designing and investigating crystal and molecular structures. It also provides support for modelling and animation of atomistic and electronic properties. JMOL is an open-source browser-based HTML5 viewer and stand-alone Java viewer for chemical structures in 3D with features for molecules, crystals, materials, and biomolecules. It is able to read CASTEP .cell , .castep , .den_fmt , . elf-fmt , .geom , .md , .phonon and more, with rendering of crystal structure, densities, ELF etc. and animation of optimization or MD trajectories and phonon vibrations. MagresView is a tool for visualization and processing of computed solid-state NMR parameters. OVITO is a scientific visualization and analysis software for atomistic and particle simulation data. VESTA is a 3D visualization program for structural models, volumetric data such as electron/nuclear densities, and crystal morphologies. XCrysDen is a crystalline and molecular structure visualisation program aiming at display of isosurfaces and contours, which can be superimposed on crystalline structures and interactively rotated and manipulated. ( .c2x can convert CASTEP output to the .xsf format, and other converters are supplied as part of the CASTEP distribution) castep2fs is a CASTEP utility for taking a CASTEP output and producing publication quality Fermi Surfaces and related quantities. castep2cube (Part of CASTEP distribution) reads .check or .castep_bin output files and converts the electron density to Gaussian .cube format which many other visualisation tools can read.","title":"Visualisation"},{"location":"documentation/Tools/tools/#databases-big-data-and-workflow","text":"NOMAD supports CASTEP and its users. The service includes uploading, downloading, sharing, assigning DOIs, and more. Storing is guaranteed for at least 10 years, a requirement set by several funding agencies. The NOMAD Repository is also the only repository in Computational Materials Science that is recommended by NATURE Scientific Data. The repository currently contains over 10 8 entries - see the archive for the latest data. aiida-castep Interface to AiiDA workflow infrastructure. Soprano is a Python library meant to help crystallographers with the search and classification of new crystal forms for a given material. It provides a number of classes and functions to handle large amounts of candidate structures, compare them, sort them and cluster them.","title":"Databases, Big Data and Workflow"},{"location":"documentation/Tools/tools/#structure-prediction","text":"CASTEP_GA (part of CASTEP distribution) is a crystal structure prediction tool based upon a modified Genetic Algorithm (GA) for periodic systems. It can handle 3D bulk materials, and also 2D surface reconstructions/interfaces and 1D edges of nanoribbons etc. It has a population of parent crystals, that are mutated and bred to make candidate children, that are then fed to CASTEP for (local) structure optimization. It is also possible to add structures that are randomly generated according to a random space group. After a number of generations, a candidate global minimum enthalpy structure can emerge. The functionality has also been extended to a MOGA (Multi-Objective GA) so that a Pareto front of optimal structures is generated, with minimum enthalpy on one axis, and a user defined property on the other. Example scripts that can be used to generate this property value are included in the distribution. Finally, recent work has been on the CHGA (Convex Hull GA) approach, wherein the stoichiometry is optimized as well, resulting in the generation of a multi-dimensional convex hull. More detailed documentation is included in the 'ReadMe' directory. AIRSS (''Ab initio Random Structure Searching'') is a very simple, yet powerful and highly parallel, approach to structure prediction. It generates random sensible structures and relaxes them to nearby minima. The sensible random structures are constructed so that they have reasonable densities, and atomic separations. Additionally they may embody crystallographic, chemical or prior experimental/computational knowledge. Beyond these explicit constraints the emphasis is on a broad, uniform, sampling of structure space. It is tightly integrated with CASTEP and has been used in a number of landmark studies to find novel phases of materials. Calypso (''Crystal structure AnaLYsis by Particle Swarm Optimization'') is an efficient structure prediction code. The approach requires only chemical compositions for a given compound to predict stable or metastable structures at given external conditions and can be used to predict/determine the crystal structure and design multi-functional materials. USPEX (''Universal Structure Predictor: Evolutionary Xtallography'') is a method developed by the Oganov laboratory for crystal structure prediction. It can very efficiently handle molecular crystals (including those with flexible and very complex molecules) and can predict stable chemical compositions and corresponding crystal structures, given just the names of the chemical elements. In addition to this fully non-empirical search, USPEX allows one to predict also a large set of robust metastable structures and perform several types of simulations using various degrees of prior knowledge. XtalOPT is a free and truly open source evolutionary algorithm designed for a priori crystal structure prediction implemented as an extension to the Avogadro molecular editor.","title":"Structure Prediction"},{"location":"documentation/Tools/tools/#md-analysis","text":"geom2xyz.pl , geom2xsf , geom2dcd (part of CASTEP distribution) are filters to convert CASTEP .geom and .md output files to other trajectory formats and may be used to interface with a number of other analysis codes. md_to_phonon (part of CASTEP distribution) is a simple python tool for reading a CASTEP trajectory file and performing various phonon-based analyses, including mass-weighted velocity autocorrelation function (VACF) vs frequency (which is close to the experimental VDOS). It can also project out a particular eigenmode and eigenvector from a user specified peak in the VACF and write as a single-mode CASTEP phonon file for visualization by other tools, e.g. JMol. MDANSE (''Molecular Dynamics Analysis for Neutron Scattering Experiments'') is a python application designed for computing properties that can be directly compared with neutron scattering experiments such as the coherent and incoherent intermediate scattering functions and their Fourier transforms, the elastic incoherent structure factor, the static coherent structure factor or the radial distribution function. LiquidLib is a \"comprehensive toolbox for analyzing classical and ab initio molecular dynamics simulations of liquids and liquid-like matter with applications to neutron scattering experiments\". potfit attempts to fit a model forcefield to a data set provided. There is a python converter tool in the CASTEP distribution for reading a CASTEP trajectory file and generating an atomic configuration file to be used as input for the potfit code. MDTEP is a simple code for analysing MD trajectories and calculating thermodynamic properties such as the heat capacity and the velocity autocorrelation function.","title":"MD analysis"},{"location":"documentation/Tools/tools/#machine-learned-potentials","text":"QUIP is is a collection of software tools to carry out molecular dynamics simulations. It implements a variety of interatomic potentials and tight binding quantum mechanics. See https://pubs.aip.org/aip/jcp/article/159/4/044803/2904492/Machine-learned-acceleration-for-molecular .","title":"Machine-Learned Potentials"},{"location":"documentation/Tools/tools/#transport","text":"ShengBTE is a software package for solving the Boltzmann Transport Equation for phonons. Its main purpose is to compute the lattice contribution to the thermal conductivity of bulk crystalline solids, but nanowires can also be treated under a hypothesis of diffusive boundary conditions. AlmaBTA extends the ShengBTE approach currently employed for homogeneous bulk materials, into the mesoscale, to fully describe thermal transport from the electronic ab initio level, through the atomistic one, all the way into the mesoscopic structure level. BoltzTraP is a program for calculating the semi-classic transport coefficients. BoltzTrap2 is a modern implementation of the smoothed Fourier interpolation algorithm for electronic bands that formed the base of the original and widely used BoltzTraP code. One of the most typical uses of BoltzTraP is the calculation of thermoelectric transport coefficients as functions of temperature and chemical potential in the rigid-band picture. However, many other features are available, including 3D plots of Fermi surfaces based on the reconstructed bands. EMC (''Effective Mass Calculator'') implements calculation of the effective masses at the bands extrema using finite difference method. There are two versions of the program: written in FORTRAN and Python.","title":"Transport"},{"location":"documentation/Tools/tools/#miscellaneous","text":"ASE is a set of tools and Python modules for setting up, manipulating, running, visualizing and analyzing atomistic simulations. The code is freely available under the GNU LGPL license. It can interface with many different electronic structure codes. Bader is a tool to perform Bader charge analysis on a charge density grid. Typically in molecular systems, the charge density reaches a minimum between atoms and this is a natural place to separate atoms from each other. Besides being an intuitive scheme for visualizing atoms in molecules, Bader's definition is often useful for charge analysis. For example, the charge enclosed within the Bader volume is a good approximation to the total electronic charge of an atom. ATAT (Alloy Theoretic Automated Toolkit) is a collection of alloy theory tools developed by Axel van de Walle. CASINO is a computer program system for performing quantum Monte Carlo (QMC) electronic structure calculations that has been developed by members of the Theory of Condensed Matter group in the Cambridge University physics department, and their collaborators, over more than 20 years. It is capable of calculating incredibly accurate solutions to the Schr\u00f6dinger equation of quantum mechanics for realistic systems built from atoms. An interface castep2casino is supplied with the CASTEP distribution. Emacs mode (part of CASTEP distribution) is an emacs major mode for CASTEP input files with datatype based syntax highlighting and inbuilt help functionality. i-PI is a package for performing molecular dynamics and path-integral MD via a unix socket driver interface. More details elsewhere in this site.","title":"Miscellaneous"},{"location":"documentation/Tools/tools/#commercial-codes","text":"BIOVIA Materials Studio is a suite of graphical tools and codes for quantum and classical simulation of materials, and is how CASTEP is distributed commercially.","title":"Commercial Codes"},{"location":"documentation/Transition_State_Search/neb/","text":"Note The NEB functionality in CASTEP was overhauled in version 22, with more efficient algorithms available. In order to use this new functionality, make sure you're **using CASTEP 22 or later**. Background and theory The nudged elastic band method is a widely-used method for finding a minimum energy pathway between two structures. You can use the method to estimate the barrier for the system to transition between the two structures. In our NEB implementation the update rule for atomic position is given by: x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] where x^{k}_n x^{k}_n are the positions of image n n at iteration k k . \\alpha^k \\alpha^k is the step size, which can either be fixed or chosen in an adaptive manner, \\nabla^\\perp V(x^{k}_n) \\nabla^\\perp V(x^{k}_n) is the gradient of the total energy, projected to remove the component along the reaction path, and \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') is the NEB spring force. As a consequence of the projection step, the NEB forces do not have a corresponding energy functional and hence linesearch is not possible, making quasi-Newton searches such as (L)BFGS inapplicable. Standard approaches are either to use simple gradient-only based methods or to add a maximum step size constraint in place of the linesearch. Both of these can exhibit slow convergence; a solution is instead to choose the step size adaptively using a custom time-stepping algorithm. A promising solution to this problem is the ODE12r adaptive scheme 1 , which combines two distinct step selection criteria: one based on minimising the change in the residual force from one step to the next as is typically done to control error in adaptive ODE solvers, and a second based on minimising the residual itself. The key idea is that adaptive ODE step selection should be used in the pre-asymptotic regime, while minimising the residual is suitable in the asymptotic regime. We have implemented three optimisation schemes for NEB paths, with the approach to be used controlled by the TSSEARCH_NEB_METHOD parameter: (i) the two point steepest descent scheme of Barzilai and Borwein 2 ; (ii) the fast inertial relaxation engine ( FIRE 3 ) and (iii) the ODE12R 1 scheme discussed above. In all three cases, convergence is controlled by the existing TSSEARCH_FORCE_TOL parameter. To better fit user intuition, the default value of this parameter is now equal to the force tolerance used during geometry optimisation, GEOM_FORCE_TOL . We also provide three alternative algorithms to compute the tangents (x^{k}_n)' (x^{k}_n)' and curvatures (x^{k}_n)'' (x^{k}_n)'' at each image along the path, controlled by the TSSEARCH_NEB_TANGENT_MODE parameter. The three approaches are based on bisection, the improved tangent scheme of FIRE 3 , and cubic spline interpolation as used in ODE12R 1 . The latter was found to be the most robust so has been made the default. Keywords As with other functionality in CASTEP, you can use the built-in help tool to find information on NEB-related keywords. For example, you could run: castep -s tssearch The relevant .param keywords are summarised in the table below: Parameter Default Level Notes TASK SINGLEPOINT Basic Set to TRANSITIONSTATESEARCH to perform a transition state calculation. TSSEARCH_METHOD LSTQST Basic The search method used to locate transition states. Must be set to NEB to perform a NEB calculation. Previous default retained for backwards compatibility. Modifiable: restart only. Allowed values: LSTQST , NEB Default value : LSTQST TSSEARCH_FORCE_TOL Same as GEOM_FORCE_TOL Basic Tolerance for accepting convergence of the maximum |ionic force| during QST search. Modifiable: restart and on the fly TSSEARCH_MAX_PATH_POINTS 20 Intermediate The maximum number of path points for NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_METHOD ODE12R 1 Intermediate Method used to optimize the NEB shape. Modifiable: restart and on the fly. Allowed values: GRAD_BB 2 , FIRE 3 , ODE12R 1 TSSEARCH_NEB_TANGENT_MODE SPLINE Basic Method used to calculate the tangents of the NEB. Modifiable: restart and on the fly. Allowed values: NONE , BISECT , HIGH_E , SPLINE TSSEARCH_NEB_SPRING_CONSTANT 0.1 eV/ang2 Basic Spring constant used between the images in NEB search. Modifiable: restart and on the fly. Allowed values: (any) > 0.0 TSSEARCH_NEB_CLIMBING FALSE Basic If TRUE then the central bead in NEB search climbs up the potential and TSSEARCH_MAX_PATH_POINTS must be odd (may be increased by +1). If FALSE then the central bead in NEB search slides down the potential. Modifiable: restart only. Allowed values: TRUE or FALSE. Default value: FALSE TSSEARCH_NEB_MAX_ITER 20 Intermediate The maximum number of steps during NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_NORMED FALSE if TSSEARCH_NEB_TANGENT_MODE = SPLINE , TRUE otherwise Expert If TRUE then the spring forces applied along the tangents in the NEB are normed to the displacement between beads. If FALSE then the spring forces are projected along the tangents in the NEB and may result in null forces if displacements are orthogonal to the NEB tangents. Modifiable: restart only. Allowed values: TRUE or FALSE As a minimum, you need to specify TASK: TRANSITIONSTATESEARCH and TSSEARCH_METHOD: NEB in the .param file and specify the product (final) ionic positions (using e.g. the POSITIONS_ABS_PRODUCT block) and a transition state guess configuration (using e.g. the POSITIONS_ABS_INTERMEDIATE block) in the .cell file, in addition to the normal POSITIONS_ABS block. CASTEP will then linearly interpolate from the initial to intermediate and from the intermediate to product configurations to begin the NEB calculation. However, it's advisable to also: change the number of images used ( TSSEARCH_MAX_PATH_POINTS ), decide on whether you want the climbing image method ( TSSEARCH_NEB_CLIMBING ), and think about the relevant force criterion to be used ( TSSEARCH_FORCE_TOL ). For a practical guide on how to use the NEB method in CASTEP, see the tutorial . Output files In addition to information in the .castep file, a .ts file will be generated during a transition state search calculation. Below is the start of a typical .ts file, with annotations explaing what each line means (you can see these by clicking on the ( ) symbols). Note Like `.geom` and `.md` files, `.ts` files use atomic units (Ha for energies, Bohr for distances and Bohr/Ha for forces etc.). TSTYPE TSConfirmation # (1)! REA 1 0.00000000E+000 # (2)! -1.19447739E+001 -1.19447739E+001 <-- E #(3)! 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h #(4)! 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61419707E+000 8.39780193E+000 5.86117838E+000 <-- R #(5)! H 2 8.15635294E+000 5.72185774E+000 5.85777350E+000 <-- R H 3 5.06964224E+000 5.72278559E+000 5.86095165E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 8.47021636E-007 3.11793289E-005 2.28609226E-005 <-- F #(6)! H 2 1.38512779E-006 -2.45087447E-005 -4.65186359E-005 <-- F H 3 -4.12781162E-005 -4.76763241E-006 1.75643331E-005 <-- F N 1 3.90459667E-005 -1.90295182E-006 6.09338019E-006 <-- F PRO 1 1.00000000E+000 #(7)! -1.19447351E+001 -1.19447351E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61608080E+000 8.39796599E+000 7.36585209E+000 <-- R H 2 8.15724653E+000 5.72090835E+000 7.36726384E+000 <-- R H 3 5.07119891E+000 5.72404366E+000 7.37171850E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 6.09749957E-005 4.97392811E-005 -4.85624696E-005 <-- F H 2 6.57602570E-005 -1.92918456E-005 -3.12188543E-005 <-- F H 3 -5.16484028E-005 2.80445001E-005 5.83274956E-005 <-- F N 1 -7.50868499E-005 -5.84919355E-005 2.14538282E-005 <-- F TST 1 1.25000056E-001 #(8)! -1.19415297E+001 -1.19415297E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61443264E+000 8.39782206E+000 6.04926187E+000 <-- R H 2 8.15646486E+000 5.72173929E+000 6.04646018E+000 <-- R H 3 5.06983587E+000 5.72294304E+000 6.04979810E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 -9.19085803E-006 2.32501273E-002 -1.04092397E-002 <-- F H 2 2.02903385E-002 -1.17660606E-002 -1.06346944E-002 <-- F H 3 -2.03961322E-002 -1.17795791E-002 -1.05604406E-002 <-- F N 1 1.14984498E-004 2.95512341E-004 3.16043747E-002 <-- F This is a comment line stating what type of calculation was carried out. This is the initial (i.e. the REA ctant) configuration. The integer indicates it is the configuration for the first NEB iteration. As the REActant (and PROduct) configurations are the same for every NEB iteration, they are only printed out once. The float at the end of the line is a measure of where the configuration lies between 0 (reactant) and 1 (product). <-- E is the total energy and enthalpy of the system, in atomic units. <-- h is the unit cell matrix (atomic units). <-- R are the atomic coordinates (Cartesian), in atomic units. <-- F are the forces (atomic units). This is the end-point (or PRO duct) configuration for the first iteration. As this is the same for every NEB iteration, it is only printed out once. This is the first of the transition state configurations (NEB images) for iteration 1 of the NEB. For example, if you have 7 images, then there will be 7 blocks that start with TST 1 . Stela Makri, Christoph Ortner, and James R. Kermode. A preconditioning scheme for minimum energy path finding methods. The Journal of Chemical Physics , 150(9):094109, 03 2019. doi:10.1063/1.5064465 . \u21a9 \u21a9 \u21a9 \u21a9 \u21a9 Jonathan Barzilai and Jonathan M. Borwein. Two-Point Step Size Gradient Methods. IMA Journal of Numerical Analysis , 8(1):141\u2013148, 01 1988. doi:10.1093/imanum/8.1.141 . \u21a9 \u21a9 Erik Bitzek, Pekka Koskinen, Franz G\u00e4hler, Michael Moseler, and Peter Gumbsch. Structural relaxation made simple. Phys. Rev. Lett. , 97:170201, Oct 2006. doi:10.1103/PhysRevLett.97.170201 . \u21a9 \u21a9 \u21a9","title":"Nudged Elastic Band"},{"location":"documentation/Transition_State_Search/neb/#background-and-theory","text":"The nudged elastic band method is a widely-used method for finding a minimum energy pathway between two structures. You can use the method to estimate the barrier for the system to transition between the two structures. In our NEB implementation the update rule for atomic position is given by: x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] where x^{k}_n x^{k}_n are the positions of image n n at iteration k k . \\alpha^k \\alpha^k is the step size, which can either be fixed or chosen in an adaptive manner, \\nabla^\\perp V(x^{k}_n) \\nabla^\\perp V(x^{k}_n) is the gradient of the total energy, projected to remove the component along the reaction path, and \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') is the NEB spring force. As a consequence of the projection step, the NEB forces do not have a corresponding energy functional and hence linesearch is not possible, making quasi-Newton searches such as (L)BFGS inapplicable. Standard approaches are either to use simple gradient-only based methods or to add a maximum step size constraint in place of the linesearch. Both of these can exhibit slow convergence; a solution is instead to choose the step size adaptively using a custom time-stepping algorithm. A promising solution to this problem is the ODE12r adaptive scheme 1 , which combines two distinct step selection criteria: one based on minimising the change in the residual force from one step to the next as is typically done to control error in adaptive ODE solvers, and a second based on minimising the residual itself. The key idea is that adaptive ODE step selection should be used in the pre-asymptotic regime, while minimising the residual is suitable in the asymptotic regime. We have implemented three optimisation schemes for NEB paths, with the approach to be used controlled by the TSSEARCH_NEB_METHOD parameter: (i) the two point steepest descent scheme of Barzilai and Borwein 2 ; (ii) the fast inertial relaxation engine ( FIRE 3 ) and (iii) the ODE12R 1 scheme discussed above. In all three cases, convergence is controlled by the existing TSSEARCH_FORCE_TOL parameter. To better fit user intuition, the default value of this parameter is now equal to the force tolerance used during geometry optimisation, GEOM_FORCE_TOL . We also provide three alternative algorithms to compute the tangents (x^{k}_n)' (x^{k}_n)' and curvatures (x^{k}_n)'' (x^{k}_n)'' at each image along the path, controlled by the TSSEARCH_NEB_TANGENT_MODE parameter. The three approaches are based on bisection, the improved tangent scheme of FIRE 3 , and cubic spline interpolation as used in ODE12R 1 . The latter was found to be the most robust so has been made the default.","title":"Background and theory"},{"location":"documentation/Transition_State_Search/neb/#keywords","text":"As with other functionality in CASTEP, you can use the built-in help tool to find information on NEB-related keywords. For example, you could run: castep -s tssearch The relevant .param keywords are summarised in the table below: Parameter Default Level Notes TASK SINGLEPOINT Basic Set to TRANSITIONSTATESEARCH to perform a transition state calculation. TSSEARCH_METHOD LSTQST Basic The search method used to locate transition states. Must be set to NEB to perform a NEB calculation. Previous default retained for backwards compatibility. Modifiable: restart only. Allowed values: LSTQST , NEB Default value : LSTQST TSSEARCH_FORCE_TOL Same as GEOM_FORCE_TOL Basic Tolerance for accepting convergence of the maximum |ionic force| during QST search. Modifiable: restart and on the fly TSSEARCH_MAX_PATH_POINTS 20 Intermediate The maximum number of path points for NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_METHOD ODE12R 1 Intermediate Method used to optimize the NEB shape. Modifiable: restart and on the fly. Allowed values: GRAD_BB 2 , FIRE 3 , ODE12R 1 TSSEARCH_NEB_TANGENT_MODE SPLINE Basic Method used to calculate the tangents of the NEB. Modifiable: restart and on the fly. Allowed values: NONE , BISECT , HIGH_E , SPLINE TSSEARCH_NEB_SPRING_CONSTANT 0.1 eV/ang2 Basic Spring constant used between the images in NEB search. Modifiable: restart and on the fly. Allowed values: (any) > 0.0 TSSEARCH_NEB_CLIMBING FALSE Basic If TRUE then the central bead in NEB search climbs up the potential and TSSEARCH_MAX_PATH_POINTS must be odd (may be increased by +1). If FALSE then the central bead in NEB search slides down the potential. Modifiable: restart only. Allowed values: TRUE or FALSE. Default value: FALSE TSSEARCH_NEB_MAX_ITER 20 Intermediate The maximum number of steps during NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_NORMED FALSE if TSSEARCH_NEB_TANGENT_MODE = SPLINE , TRUE otherwise Expert If TRUE then the spring forces applied along the tangents in the NEB are normed to the displacement between beads. If FALSE then the spring forces are projected along the tangents in the NEB and may result in null forces if displacements are orthogonal to the NEB tangents. Modifiable: restart only. Allowed values: TRUE or FALSE As a minimum, you need to specify TASK: TRANSITIONSTATESEARCH and TSSEARCH_METHOD: NEB in the .param file and specify the product (final) ionic positions (using e.g. the POSITIONS_ABS_PRODUCT block) and a transition state guess configuration (using e.g. the POSITIONS_ABS_INTERMEDIATE block) in the .cell file, in addition to the normal POSITIONS_ABS block. CASTEP will then linearly interpolate from the initial to intermediate and from the intermediate to product configurations to begin the NEB calculation. However, it's advisable to also: change the number of images used ( TSSEARCH_MAX_PATH_POINTS ), decide on whether you want the climbing image method ( TSSEARCH_NEB_CLIMBING ), and think about the relevant force criterion to be used ( TSSEARCH_FORCE_TOL ). For a practical guide on how to use the NEB method in CASTEP, see the tutorial .","title":"Keywords"},{"location":"documentation/Transition_State_Search/neb/#output-files","text":"In addition to information in the .castep file, a .ts file will be generated during a transition state search calculation. Below is the start of a typical .ts file, with annotations explaing what each line means (you can see these by clicking on the ( ) symbols). Note Like `.geom` and `.md` files, `.ts` files use atomic units (Ha for energies, Bohr for distances and Bohr/Ha for forces etc.). TSTYPE TSConfirmation # (1)! REA 1 0.00000000E+000 # (2)! -1.19447739E+001 -1.19447739E+001 <-- E #(3)! 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h #(4)! 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61419707E+000 8.39780193E+000 5.86117838E+000 <-- R #(5)! H 2 8.15635294E+000 5.72185774E+000 5.85777350E+000 <-- R H 3 5.06964224E+000 5.72278559E+000 5.86095165E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 8.47021636E-007 3.11793289E-005 2.28609226E-005 <-- F #(6)! H 2 1.38512779E-006 -2.45087447E-005 -4.65186359E-005 <-- F H 3 -4.12781162E-005 -4.76763241E-006 1.75643331E-005 <-- F N 1 3.90459667E-005 -1.90295182E-006 6.09338019E-006 <-- F PRO 1 1.00000000E+000 #(7)! -1.19447351E+001 -1.19447351E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61608080E+000 8.39796599E+000 7.36585209E+000 <-- R H 2 8.15724653E+000 5.72090835E+000 7.36726384E+000 <-- R H 3 5.07119891E+000 5.72404366E+000 7.37171850E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 6.09749957E-005 4.97392811E-005 -4.85624696E-005 <-- F H 2 6.57602570E-005 -1.92918456E-005 -3.12188543E-005 <-- F H 3 -5.16484028E-005 2.80445001E-005 5.83274956E-005 <-- F N 1 -7.50868499E-005 -5.84919355E-005 2.14538282E-005 <-- F TST 1 1.25000056E-001 #(8)! -1.19415297E+001 -1.19415297E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61443264E+000 8.39782206E+000 6.04926187E+000 <-- R H 2 8.15646486E+000 5.72173929E+000 6.04646018E+000 <-- R H 3 5.06983587E+000 5.72294304E+000 6.04979810E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 -9.19085803E-006 2.32501273E-002 -1.04092397E-002 <-- F H 2 2.02903385E-002 -1.17660606E-002 -1.06346944E-002 <-- F H 3 -2.03961322E-002 -1.17795791E-002 -1.05604406E-002 <-- F N 1 1.14984498E-004 2.95512341E-004 3.16043747E-002 <-- F This is a comment line stating what type of calculation was carried out. This is the initial (i.e. the REA ctant) configuration. The integer indicates it is the configuration for the first NEB iteration. As the REActant (and PROduct) configurations are the same for every NEB iteration, they are only printed out once. The float at the end of the line is a measure of where the configuration lies between 0 (reactant) and 1 (product). <-- E is the total energy and enthalpy of the system, in atomic units. <-- h is the unit cell matrix (atomic units). <-- R are the atomic coordinates (Cartesian), in atomic units. <-- F are the forces (atomic units). This is the end-point (or PRO duct) configuration for the first iteration. As this is the same for every NEB iteration, it is only printed out once. This is the first of the transition state configurations (NEB images) for iteration 1 of the NEB. For example, if you have 7 images, then there will be 7 blocks that start with TST 1 . Stela Makri, Christoph Ortner, and James R. Kermode. A preconditioning scheme for minimum energy path finding methods. The Journal of Chemical Physics , 150(9):094109, 03 2019. doi:10.1063/1.5064465 . \u21a9 \u21a9 \u21a9 \u21a9 \u21a9 Jonathan Barzilai and Jonathan M. Borwein. Two-Point Step Size Gradient Methods. IMA Journal of Numerical Analysis , 8(1):141\u2013148, 01 1988. doi:10.1093/imanum/8.1.141 . \u21a9 \u21a9 Erik Bitzek, Pekka Koskinen, Franz G\u00e4hler, Michael Moseler, and Peter Gumbsch. Structural relaxation made simple. Phys. Rev. Lett. , 97:170201, Oct 2006. doi:10.1103/PhysRevLett.97.170201 . \u21a9 \u21a9 \u21a9","title":"Output files"},{"location":"documentation/Troubleshooting/linux_path/","text":"Command not found When you type castep , Linux doesn't know where that command is, so it looks in the places where programs are usually put (often /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin ; \"bin\" here is short for \"binary\"). Unless CASTEP is there, it will tell you that it can't find it. Notice in particular that the directory you're in when you type the command is not in Linux's list of usual places to look, which is especially confusing when you first encounter it! Telling Linux where to find CASTEP There are several ways to fix this. If you're on a shared machine, it is usually best to make a subdirectory in your home directory, perhaps called \"bin\": mkdir ~/bin and put CASTEP in there (along with any other programs you compile yourself), e.g. cp ~/CASTEP-22.1/obj/linux_x86_64_gfortran--serial/castep.serial ~/bin This still won't mean that Linux will find CASTEP, because this is also not a place it will look for programs. The places Linux looks in are stored in a special Linux environment variable called the \"path\", and the final step is to add the new directory to this \"path\". Exactly how you do this depends on what kind of command-line interpreter (called a \"shell\") you're using in Linux, but there are only really two main kinds: bash and csh. Type export PATH=${PATH}:~/bin if you're using bash, or setenv PATH ${PATH}:~/bin if you're using csh. These commands tell Linux to look in all the places it's looking in already, and also \"~/bin\". If you don't know which shell you're using, try typing: echo $SHELL and see what it says. If it says something like \"/bin/bash\" then you're using bash, if it's \"/bin/csh\" or \"/bin/tcsh\" then it's csh (or close enough). If it gives something else, just try the line starting \"export\" and if it gives an error, try the \"setenv\" one instead. Now try typing \"castep.serial\" and you should see this: Usage: castep : Run files .cell [and .param] \" [-d|--dryrun] : Perform a dryrun calculation on files .cell \" [-s|--search] : print list of keywords with match in description \" [-v|--version] : print version information \" [-h|--help] : describe specific keyword in <>.cell or <>.param \" \" all : print list of all keywords \" \" basic : print list of basic-level keywords \" \" inter : print list of intermediate-level keywords \" \" expert : print list of expert-level keywords \" \" dummy : print list of dummy keywords Automatically adding to your PATH The changes so far will be lost when you exit the command-line. We need to make sure that your directory is added to the PATH variable every time you log in or open a new terminal. If you're using bash, edit the file ~/.bashrc with a text editor (e.g. gedit), go to the end, and add the line to set the PATH: export PATH=${PATH}:~/bin Note that the file is in your home directory (\"~/\"), and the name starts with a dot (\".\" a full stop). Save and exit, and it should all be set up for you. If you're using csh, edit the file \"~/.cshrc\" instead, and add the appropriate line to set the PATH: setenv PATH ${PATH}:~/bin Save and exit, and it should all be set up for you.","title":"Linux help"},{"location":"documentation/Troubleshooting/linux_path/#command-not-found","text":"When you type castep , Linux doesn't know where that command is, so it looks in the places where programs are usually put (often /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin ; \"bin\" here is short for \"binary\"). Unless CASTEP is there, it will tell you that it can't find it. Notice in particular that the directory you're in when you type the command is not in Linux's list of usual places to look, which is especially confusing when you first encounter it!","title":"Command not found"},{"location":"documentation/Troubleshooting/linux_path/#telling-linux-where-to-find-castep","text":"There are several ways to fix this. If you're on a shared machine, it is usually best to make a subdirectory in your home directory, perhaps called \"bin\": mkdir ~/bin and put CASTEP in there (along with any other programs you compile yourself), e.g. cp ~/CASTEP-22.1/obj/linux_x86_64_gfortran--serial/castep.serial ~/bin This still won't mean that Linux will find CASTEP, because this is also not a place it will look for programs. The places Linux looks in are stored in a special Linux environment variable called the \"path\", and the final step is to add the new directory to this \"path\". Exactly how you do this depends on what kind of command-line interpreter (called a \"shell\") you're using in Linux, but there are only really two main kinds: bash and csh. Type export PATH=${PATH}:~/bin if you're using bash, or setenv PATH ${PATH}:~/bin if you're using csh. These commands tell Linux to look in all the places it's looking in already, and also \"~/bin\". If you don't know which shell you're using, try typing: echo $SHELL and see what it says. If it says something like \"/bin/bash\" then you're using bash, if it's \"/bin/csh\" or \"/bin/tcsh\" then it's csh (or close enough). If it gives something else, just try the line starting \"export\" and if it gives an error, try the \"setenv\" one instead. Now try typing \"castep.serial\" and you should see this: Usage: castep : Run files .cell [and .param] \" [-d|--dryrun] : Perform a dryrun calculation on files .cell \" [-s|--search] : print list of keywords with match in description \" [-v|--version] : print version information \" [-h|--help] : describe specific keyword in <>.cell or <>.param \" \" all : print list of all keywords \" \" basic : print list of basic-level keywords \" \" inter : print list of intermediate-level keywords \" \" expert : print list of expert-level keywords \" \" dummy : print list of dummy keywords","title":"Telling Linux where to find CASTEP"},{"location":"documentation/Troubleshooting/linux_path/#automatically-adding-to-your-path","text":"The changes so far will be lost when you exit the command-line. We need to make sure that your directory is added to the PATH variable every time you log in or open a new terminal. If you're using bash, edit the file ~/.bashrc with a text editor (e.g. gedit), go to the end, and add the line to set the PATH: export PATH=${PATH}:~/bin Note that the file is in your home directory (\"~/\"), and the name starts with a dot (\".\" a full stop). Save and exit, and it should all be set up for you. If you're using csh, edit the file \"~/.cshrc\" instead, and add the appropriate line to set the PATH: setenv PATH ${PATH}:~/bin Save and exit, and it should all be set up for you.","title":"Automatically adding to your PATH"},{"location":"documentation/Troubleshooting/troubleshooting/","text":"CASTEP fails to start Command not found If you see a message like this on the command-line when you run CASTEP: castep mytest castep: command not found then your computer has not located the CASTEP program. Check that: you've used the correct CASTEP name ( castep.serial or castep.mpi ) the CASTEP program is somewhere your computer expects programs to be See here for details of where Linux looks for programs, and how to change it. CASTEP aborts a calculation If CASTEP detects a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error messages from each of these cores. They are named using the same seedname, but with the process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them. Failed to converge","title":"Common errors"},{"location":"documentation/Troubleshooting/troubleshooting/#castep-fails-to-start","text":"","title":"CASTEP fails to start"},{"location":"documentation/Troubleshooting/troubleshooting/#command-not-found","text":"If you see a message like this on the command-line when you run CASTEP: castep mytest castep: command not found then your computer has not located the CASTEP program. Check that: you've used the correct CASTEP name ( castep.serial or castep.mpi ) the CASTEP program is somewhere your computer expects programs to be See here for details of where Linux looks for programs, and how to change it.","title":"Command not found"},{"location":"documentation/Troubleshooting/troubleshooting/#castep-aborts-a-calculation","text":"If CASTEP detects a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error messages from each of these cores. They are named using the same seedname, but with the process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them.","title":"CASTEP aborts a calculation"},{"location":"documentation/Troubleshooting/troubleshooting/#failed-to-converge","text":"","title":"Failed to converge"},{"location":"documentation/XC/XC/","text":"The exchange and correlation functional used for calculations in CASTEP can be specified in one of two main ways. xc_functional The most straightforward is with the .param file keyword xc_functional . For example to use the PBE functional in the .param file simply use xc_functional : PBE There are a number of standard functionals that can be used in CASTEP with the xc_functional keyword: Local density approximation: LDA LDA-X LDA-C Generalised gradient approximations (GGA): PW91 PBE PBEsol RPBE WC BLYP B86PBE PBE_X PBE_C PBEsol_X PBEsol_C B88_X LYP_C Hybrid (non-local) functionals: HF SHF-LDA PBE0 B3LYP HSE03 HSE06 SPBE0 Meta-GGA functionals: RSCAN MS2 xc_definition The keyword xc_definition in the .param file (used instead of xc_functional) is used when you want to modify the standard behaviour of hybrid functionals, or if you want to construct your own hybrid functionals. The simplest use of xc_definition is to replicate that of xc_functional , for example %block xc_definition PBE 1.0 %endblock xc_definition is the same as xc_functional : PBE The \"1.0\" is what weighted fraction of the functional you want, so in this case 1.0 (i.e. 100% PBE). Recall that hybrids are (usually) a mixture of pure (or screened) non-local Hartree-Fock exchange, some local exchange and local correlation. So you could, for example, build a functional that could be 20% Hartree Fock, 80% LDA exchange and 100% LDA correlation. You can run a CASTEP calculation with this using %block xc_definition HF 0.2 LDA-X 0.8 LDA-C 1.0 %endblock xc_definition Examples: 1. B3LYP Firstly you cansimply use xc_functional : B3LYP , however B3LYP is a hybrid functional consisting of a mixture of Hartree-Fock, LDA and B88 exchange, LYP and LDA correlation. This functional can be specified component by component: %block xc_definition LDA-X 0.08 B88_X 0.72 LYP_C 0.81 LDA-C 0.19 HF 0.20 %endblock xc_definition Using the full specification in xc_definition makes it straightforward to adjust the various component weightings to your own specification. There are other adjustments that can be made within the functional. For example the popular functional HSE06 contains a screened Hartree-Fock component, with a mixture of other local functionals. It can be specified component by component as %block xc_definition SHF 0.25 PBE 1.0 PBE_X_SR -0.25 NLXC_SCREENING_LENGTH 0.11 NLXC_SCREENING_FUNCTION ERRORFUNCTION %endblock xc_definition In this case we have 25% screened Hartree-Fock offsetting -25% screened PBE exchange (and 100% PBE correlation within PBE). The default HF screening is exponential, but this can be changed to an error function as shown in the block. Also the strength of the screening can be altered by the NLXC_SCREENING_LENGTH parameter (natural units). 2. Hybrid functionals are expensive calculations, much(!) more computationally intensive than (semi-)local functionals. They are often used because they are able to give much better electronic band gaps. If we do LDA and SHF-LDA band structure for silicon we can use the cell file %block lattice_cart 2.7 2.7 0.0 2.7 0.0 2.7 0.0 2.7 2.7 %endblock lattice_cart %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac symmetry_generate %block spectral_kpoint_path W G X W L G %endblock spectral_kpoint_path %block species_pot NCP %endblock species_pot and then the .param file for LDA task : spectral spectral_task : BandStructure xc_functional : lda and for screened exchange, task : spectral spectral_task : BandStructure xc_functional : shf-lda If we then plot these two band structures together, the difference in results can be seen, the band gap opens from the LDA value of around 0.5eV to a more realistic 1.","title":"Controlling XC"},{"location":"documentation/XC/XCoverview/","text":"There are many sources of description of the role of exchange and correlation within density functional theory, https://en.wikipedia.org/wiki/Density_functional_theory Here we will look at how to give both a basic control over the XC functional that your calculation will use and well as giving finer control over functionals that have free parameters.","title":"Overview"},{"location":"documentation/XC/libXC/","text":"There are many (many!) XC functionals (of varying quality and applicability). LIBXC ( https://www.tddft.org/programs/libxc/ ) is a maintained library of functionals that is upgraded regularly. The list of functionals available in LIBXC is at https://www.tddft.org/programs/libxc/functionals/ . CASTEP interfaces to this library which can be used instead of CASTEP's in-built library of XC functionals. Prepend the string LIBXC_ to CASTEP's functional name in the parameter keyword xc_functional to use LIBXC. For example: xc_functional : PBE for CASTEP's in-built PBE functional xc_functional : LIBXC_PBE for the LIBXC version of the PBE functional In the LIBXC library there are many functionals, covering LDAs, GGAs, Meta-GGAs, Hybrids, etc. Most of these are separated into exchange and correlation contributions. To use these functionals, build your own combination using CASTEP's xc_definition keyword in the .param file. Firstly at https://www.tddft.org/programs/libxc/functionals/ find the exchange and correlation functionals that you require, note the name LIBXC calls is and then prepend the string LIBXC_ to them. For example to construct Perdew and Zunger's LDA, LDA exchange is called LDA_X and correlation is called LDA_C_PZ. In the .param file use %block xc_definition LIBXC_LDA_X 1.0 LIBXC_LDA_C_PZ 1.0 %endblock xc_definition The \"1.0\" after each is the fraction of how much of each you require to use, in this case 100% of each. Example, construct the PBE functional from LIBXC: In LIBXC, PBE exchange is called GGA_X_PBE and its correlation is called GGA_C_PBE. Prepend with LIBXC_ and construct xc_definition : %block xc_definition LIBXC_GGA_X_PBE 1.0 LIBXC_GGA_C_PBE 1.0 %endblock xc_definition There are a few functional in LIBXC that have combined exchange and correlation parts, so this can be listed in xc_definition on its own. For example the HCTH93 XC functional is called GGA_XC_HCTH_93 in LIBXC hence it can be used in CASTEP with %block xc_definition LIBXC_GGA_XC_HCTH_93 1.0 %endblock xc_definition LIBXC can also be used to construct hybrid (non-local) functionals that contain (screened) Hartree-Fock components. Note that LIBXC does not contain the non-local part of such functionals, just the local part. Construct the functional using CASTEP's non-local functionality. For example, the PBE0 functional is called HYB_GGA_XC_PBE0 in LIBXC, so to construct this use %block xc_definition LIBXC_HYB_GGA_XC_PBE0 1.0 HF 0.25 %endblock xc_definition Note here you need to know (ie. read the HYB_GGA_XC_PBE0 reference given in https://www.tddft.org/programs/libxc/functionals/ ) what fraction of local exchange is in the functional and so infer what the fraction of non-local exchange is required (here 0.25). If you want to vary the fraction of non-local exchange then you need to balance this with offsetting it with the correct fraction of local exchange. For this construct the whole functional yourself. For example PBE0 is 0.25HF + 0.75PBE_X + 1.0PBE_C. Varying the HF component in PBE0 can be done with %block xc_definition HF 0.20 LIBXC_GGA_PBE_X 0.80 LIBXC_GGA_PBE_C_1.0 %endblock xc_definition where here it's set to 20% non-local and 80% local exchange, with 100% PBE correlation. Meta-GGAs are also supported. For example the RSCAN functional can be used with %block xc_definition LIBXC_MGGA_X_RSCAN 1.0 LIBXC_MGGA_C_RSCAN 1.0 %endblock xc_definition (although RSCAN is also natively supported in CASTEP with xc_functional : RSCAN ). The xc_definition keyword in the .param file will allow you to mix and match any of the hundreds of functionals in LIBXC https://www.tddft.org/programs/libxc/functionals/ . DO SO WITH EXTREME CAUTION!","title":"libXC"},{"location":"documentation/XRD/overview/","text":"X-ray Structure Factors Basic Theory The X-ray structure factor (SF) intensities can be measured by diffraction experiments involving either X-rays, \\gamma \\gamma -rays or electron beams. It is directly related to the electron density within the unit cell of a material, n(\\mathbf{r}) n(\\mathbf{r}) , by a Fourier transformation 1 : F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, where \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* is the scattering vector corresponding to the (hkl) (hkl) plane, with \\mathbf{a}^*, \\mathbf{b}^* \\mathbf{a}^*, \\mathbf{b}^* and \\mathbf{c}^* \\mathbf{c}^* being the reciprocal lattice vectors of the conventional unit cell. Computation of the SF is difficult within plane-wave pseudopotential DFT codes since the total \"all-electron'' electron density is not normally directly computed and the FFT grids used to house the pseudised valence electron density do not have enough spatial resolution to capture the rapid oscillations near the atomic cores of the total electron density, requiring large plane-wave energy cutoffs in the order of several thousands of eV. Within CASTEP, we have developed an efficient and accurate approach towards calculating these SFs without having to move to large FFT grids or plane-wave energy cutoffs. Details of this implementation can be found in the paper (CITE PAPER WHEN PUBLISHED) but the key observation that has enabled this development is that the electron density can be separated into atom-centred contributions which can be treated on separate radial grids. The resulting structure factor has the form 2 : F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), where f_j(\\mathbf{H}) f_j(\\mathbf{H}) is an effective atomic scattering factor of atom j j within the unit cell, defined to be the Fourier transform of its effective atomic density \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) : f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. Incorporating Thermal Effects Within experiments, thermal vibrations (i.e. phonons) can modify the (time-averaged) electron density and, hence, SFs. Making the approximation that the electron density assigned to each atom \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) directly follows its nuclear motion perfectly, the structure factors can incorporate these thermal vibration effects by including an atomic temperature factor T(\\mathbf{H}) T(\\mathbf{H}) : F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). Taking the vibrations of an atom to follow that of a harmonic oscillator, the temperature factor can be shown to be of the form: T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), where \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle are the averaged, squared, thermal displacements of the atom. For the case where the vibrations are isotropic, this equation reduces to: T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), where B is termed the Debye-Waller factor. Keywords Currently, to enable CASTEP (versions 21 and beyond) to calculate X-ray SFs, the desired SFs must be placed between CALCULATE_XRD_SF: and :ENDCALCULATE_XRD_SF within the devel_code block of the seed.param file. For example, the (111) (111) and (200) (200) and (220) (220) SFs can be calculated by appending the following code to the end of the seed.param file: %block devel_code CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, if no structure factors are listed, as in: %block devel_code CALCULATE_XRD_SF: :ENDCALCULATE_XRD_SF %endblock devel_code then the SFs on the entire FFT grid will be written out. Thermal effects can also be incoporated by placing the desired atomic Debye-Waller (DW) factors between DW_FACTOR: and :ENDDW_FACTOR within the devel_code block of the seed.param file. For isotropic DW factors, the value of the DW factor can be written next to the corresponding atomic symbol as below: %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, the entire anisotropic displacement tensor of each atomic species may be specified as follows: %block devel_code DW_FACTOR: Mg 0.305 0.000 0.000 0.000 0.305 0.000 0.000 0.000 0.305 O 0.340 0.000 0.000 0.000 0.340 0.000 0.000 0.000 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Note Structure factor calculations are a post-processing calculation, so they can be restarted from a previous DFT calculation's .check file by using the CONTINUATION parameter in CASTEP. Output Files The resulting structure factors that have been calculated will be outputted into a file named seed.xrd_sf . For the following inputs: ! MgO.param xc_functional : PBE %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 0 0 2 0 2 2 :ENDCALCULATE_XRD_SF %endblock devel_code ! MgO.cell %BLOCK LATTICE_CART ang 4.2112 0.0 0.0 0.0 4.2112 0.0 0.0 0.0 4.2112 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Mg 0.00 0.00 0.00 Mg 0.50 0.50 0.00 Mg 0.50 0.00 0.50 Mg 0.00 0.50 0.50 O 0.00 0.50 0.00 O 0.50 0.00 0.00 O 0.00 0.00 0.50 O 0.50 0.50 0.50 %ENDBLOCK POSITIONS_FRAC kpoint_mp_grid 8 8 8 SYMMETRY_GENERATE We get a resulting seed.xrd_sf file with the output: h k l Re(F_PAW) Im(F_PAW) Re(F_IAM) Im(F_IAM) Re(F_PP) Im(F_PP) Re(F_core) Im(F_core) Re(F_soft) Im(F_soft) Re(F_aug) Im(F_aug) 1 1 1 11.115757 -0.000000 12.492143 -0.000000 10.926445 -0.000000 0.085890 -0.000000 -9.892234 0.000000 20.922101 -0.000000 0 0 2 52.877502 0.000000 51.830521 -0.000000 52.626486 0.000000 15.464656 -0.000000 15.585172 -0.000000 21.827675 0.000000 0 2 2 41.051122 0.000000 40.948429 -0.000000 40.609195 0.000000 14.950468 -0.000000 7.954567 -0.000000 18.146087 0.000000 After the header, the structure factors are listed along each row based on the order in which they have been listed in the seed.param file. Across the columns along each row, the h, k,l h, k,l vectors are first listed before the real and imaginary components of the SF are listed under Re(F_PAW) and Im(F_PAW) respectively. Several other (less accurate) SFs that are commonly found in literature as well as charge contributions to F_PAW are also listed in columns further to the right, as described below: Label Description F_PAW DFT structure factor with all-electron augmentation charge F_IAM Indepedent atom model structure factor; electron densit formed from superposition of atomic electron densities obtained by numerically solving the Koelling-Harmon equation F_PP DFT structure factor with pseudised (inaccurate) augmentation charge F_core Structure factor contribution to F_PAW due to the (frozen) core electrons F_soft Structure factor contribution to F_PAW due to the soft valence charge (where augmentation charge contribute is removed) F_aug Structure factor contribution due to the all-electron valence augmentation charge Philip Coppens. X-ray charge densities and chemical bonding . Volume 4. International Union of Crystallography, 1997. \u21a9 U. Shmueli and Internationale Union f\u00fcr Kristallographie, editors. International Tables for Crystallography . Volume B: Reciprocal Space. Kluwer Acad. Publ, Dordrecht, 2. edition, 2001. \u21a9","title":"XRD"},{"location":"documentation/XRD/overview/#x-ray-structure-factors","text":"","title":"X-ray Structure Factors"},{"location":"documentation/XRD/overview/#basic-theory","text":"The X-ray structure factor (SF) intensities can be measured by diffraction experiments involving either X-rays, \\gamma \\gamma -rays or electron beams. It is directly related to the electron density within the unit cell of a material, n(\\mathbf{r}) n(\\mathbf{r}) , by a Fourier transformation 1 : F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, where \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* is the scattering vector corresponding to the (hkl) (hkl) plane, with \\mathbf{a}^*, \\mathbf{b}^* \\mathbf{a}^*, \\mathbf{b}^* and \\mathbf{c}^* \\mathbf{c}^* being the reciprocal lattice vectors of the conventional unit cell. Computation of the SF is difficult within plane-wave pseudopotential DFT codes since the total \"all-electron'' electron density is not normally directly computed and the FFT grids used to house the pseudised valence electron density do not have enough spatial resolution to capture the rapid oscillations near the atomic cores of the total electron density, requiring large plane-wave energy cutoffs in the order of several thousands of eV. Within CASTEP, we have developed an efficient and accurate approach towards calculating these SFs without having to move to large FFT grids or plane-wave energy cutoffs. Details of this implementation can be found in the paper (CITE PAPER WHEN PUBLISHED) but the key observation that has enabled this development is that the electron density can be separated into atom-centred contributions which can be treated on separate radial grids. The resulting structure factor has the form 2 : F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), where f_j(\\mathbf{H}) f_j(\\mathbf{H}) is an effective atomic scattering factor of atom j j within the unit cell, defined to be the Fourier transform of its effective atomic density \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) : f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}.","title":"Basic Theory"},{"location":"documentation/XRD/overview/#incorporating-thermal-effects","text":"Within experiments, thermal vibrations (i.e. phonons) can modify the (time-averaged) electron density and, hence, SFs. Making the approximation that the electron density assigned to each atom \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) directly follows its nuclear motion perfectly, the structure factors can incorporate these thermal vibration effects by including an atomic temperature factor T(\\mathbf{H}) T(\\mathbf{H}) : F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). Taking the vibrations of an atom to follow that of a harmonic oscillator, the temperature factor can be shown to be of the form: T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), where \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle are the averaged, squared, thermal displacements of the atom. For the case where the vibrations are isotropic, this equation reduces to: T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), where B is termed the Debye-Waller factor.","title":"Incorporating Thermal Effects"},{"location":"documentation/XRD/overview/#keywords","text":"Currently, to enable CASTEP (versions 21 and beyond) to calculate X-ray SFs, the desired SFs must be placed between CALCULATE_XRD_SF: and :ENDCALCULATE_XRD_SF within the devel_code block of the seed.param file. For example, the (111) (111) and (200) (200) and (220) (220) SFs can be calculated by appending the following code to the end of the seed.param file: %block devel_code CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, if no structure factors are listed, as in: %block devel_code CALCULATE_XRD_SF: :ENDCALCULATE_XRD_SF %endblock devel_code then the SFs on the entire FFT grid will be written out. Thermal effects can also be incoporated by placing the desired atomic Debye-Waller (DW) factors between DW_FACTOR: and :ENDDW_FACTOR within the devel_code block of the seed.param file. For isotropic DW factors, the value of the DW factor can be written next to the corresponding atomic symbol as below: %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, the entire anisotropic displacement tensor of each atomic species may be specified as follows: %block devel_code DW_FACTOR: Mg 0.305 0.000 0.000 0.000 0.305 0.000 0.000 0.000 0.305 O 0.340 0.000 0.000 0.000 0.340 0.000 0.000 0.000 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Note Structure factor calculations are a post-processing calculation, so they can be restarted from a previous DFT calculation's .check file by using the CONTINUATION parameter in CASTEP.","title":"Keywords"},{"location":"documentation/XRD/overview/#output-files","text":"The resulting structure factors that have been calculated will be outputted into a file named seed.xrd_sf . For the following inputs: ! MgO.param xc_functional : PBE %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 0 0 2 0 2 2 :ENDCALCULATE_XRD_SF %endblock devel_code ! MgO.cell %BLOCK LATTICE_CART ang 4.2112 0.0 0.0 0.0 4.2112 0.0 0.0 0.0 4.2112 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Mg 0.00 0.00 0.00 Mg 0.50 0.50 0.00 Mg 0.50 0.00 0.50 Mg 0.00 0.50 0.50 O 0.00 0.50 0.00 O 0.50 0.00 0.00 O 0.00 0.00 0.50 O 0.50 0.50 0.50 %ENDBLOCK POSITIONS_FRAC kpoint_mp_grid 8 8 8 SYMMETRY_GENERATE We get a resulting seed.xrd_sf file with the output: h k l Re(F_PAW) Im(F_PAW) Re(F_IAM) Im(F_IAM) Re(F_PP) Im(F_PP) Re(F_core) Im(F_core) Re(F_soft) Im(F_soft) Re(F_aug) Im(F_aug) 1 1 1 11.115757 -0.000000 12.492143 -0.000000 10.926445 -0.000000 0.085890 -0.000000 -9.892234 0.000000 20.922101 -0.000000 0 0 2 52.877502 0.000000 51.830521 -0.000000 52.626486 0.000000 15.464656 -0.000000 15.585172 -0.000000 21.827675 0.000000 0 2 2 41.051122 0.000000 40.948429 -0.000000 40.609195 0.000000 14.950468 -0.000000 7.954567 -0.000000 18.146087 0.000000 After the header, the structure factors are listed along each row based on the order in which they have been listed in the seed.param file. Across the columns along each row, the h, k,l h, k,l vectors are first listed before the real and imaginary components of the SF are listed under Re(F_PAW) and Im(F_PAW) respectively. Several other (less accurate) SFs that are commonly found in literature as well as charge contributions to F_PAW are also listed in columns further to the right, as described below: Label Description F_PAW DFT structure factor with all-electron augmentation charge F_IAM Indepedent atom model structure factor; electron densit formed from superposition of atomic electron densities obtained by numerically solving the Koelling-Harmon equation F_PP DFT structure factor with pseudised (inaccurate) augmentation charge F_core Structure factor contribution to F_PAW due to the (frozen) core electrons F_soft Structure factor contribution to F_PAW due to the soft valence charge (where augmentation charge contribute is removed) F_aug Structure factor contribution due to the all-electron valence augmentation charge Philip Coppens. X-ray charge densities and chemical bonding . Volume 4. International Union of Crystallography, 1997. \u21a9 U. Shmueli and Internationale Union f\u00fcr Kristallographie, editors. International Tables for Crystallography . Volume B: Reciprocal Space. Kluwer Acad. Publ, Dordrecht, 2. edition, 2001. \u21a9","title":"Output Files"},{"location":"tutorials/Bands_and_DOS/magnetic/","text":"Iron ! Fe.cell %BLOCK LATTICE_CART -1.433199999999999 1.433200000000001 1.433200000000001 1.433200000000001 -1.433200000000000 1.433200000000000 1.433200000000000 1.433200000000000 -1.433200000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Fe 0.0000000000000000 0.0000000000000000 0.0000000000000000 %ENDBLOCK POSITIONS_FRAC symmetry_generate ! Kpoint grid for the Groundstate (SCF) calculation kpoint_mp_grid 8 8 8 ! kpoint path through the Brillouin Zone for the Bandstructure %BLOCK spectral_KPOINT_PATH 0.0 0.0 0.0 !G 0.5 0.5 0.5 !H 0.5 0.0 0.0 !N 0.0 0.0 0.0 !G 0.75 0.25 -0.25 !P 0.5 0.0 0.0 !N %ENDBLOCK spectral_KPOINT_PATH In the param file we set spin_polarised true in order to allow the up and down spin electrons to take different configurations. It is important to start the calculation with an initial spin density using e.g. spin: 1 . The value of the initial spin should not affect the final answer - a non-zero value is just needed to break the symmetry between the spin channels. ! Fe.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! grid_scale 2.0 ! opt_strategy speed ! Choose algorithms for best speed spin 1 ! Set the spin in the original cell to 1. spin_polarised true ! Run a spin polarised calculation spectral_nbands 6 ! number of bands to compute during the BS run At the end of the calculation the net spin of the unit cell is reported in the castep file e.g. Integrated Spin Density = 2.15322 hbar/2 Note The band structure has similarities with that of Copper - and other 3d elements - with flat 3d bands and dispersive s bands. We colour code the bands according to their spin chactacter (red=up, blue=down). We can see that there is an almost constant exchange splitting of 1.5eV between the up and down 3d bands. The splitting between the s-like bands is much smaller. More up states lie below the fermi energy than down states - hence the net spin of the unit cell. FeO FeO is an anti-ferromagnetic oxide. We set up the calculation with initial spins on the two Fe atoms pointing in opposite directions. ! FeO.cell %BLOCK LATTICE_CART 1.768531594289456 0.000000000000001 5.002162732258922 -0.884265797144728 1.531593288050063 5.002162732258921 -0.884265797144728 -1.531593288050063 5.002162732258922 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC O 0.75 0.750 -1.250 O -0.75 -0.750 1.250 Fe 0.00 0.000 -0.000 spin=-4.0 Fe 1.50 -0.500 -0.500 spin=4.0 %ENDBLOCK POSITIONS_FRAC kpoints_mp_grid: 6 6 6 symmetry_generate %block spectral_kpoint_path 0.500 0.500 0.000 0.000 0.000 0.000 0.500 0.500 0.500 0.000 0.500 0.000 0.000 0.000 0.000 %endblock spectral_kpoint_path ! FeO.param task : spectral ! The TASK keyword instructs CASTEP what to do xc_functional : PBE ! Which exchange-correlation functional to use. cutoff_energy 600 eV opt_strategy speed ! Choose algorithms for speed. nextra_bands : 6 spin_polarized : true A PBE calculation incorrectly finds FeO to be a metal (bandstructure on left below). Add the following to the cell file to run a PBE+U calculation %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u FeO band structure with PBE (left) and with PBE+U (right) Note Adding a Hubbard U term to the calculation opens the band gap and FeO is (correctly) predicted to be an antiferromangetic insulator.","title":"Magnetic Materials"},{"location":"tutorials/Bands_and_DOS/magnetic/#iron","text":"! Fe.cell %BLOCK LATTICE_CART -1.433199999999999 1.433200000000001 1.433200000000001 1.433200000000001 -1.433200000000000 1.433200000000000 1.433200000000000 1.433200000000000 -1.433200000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Fe 0.0000000000000000 0.0000000000000000 0.0000000000000000 %ENDBLOCK POSITIONS_FRAC symmetry_generate ! Kpoint grid for the Groundstate (SCF) calculation kpoint_mp_grid 8 8 8 ! kpoint path through the Brillouin Zone for the Bandstructure %BLOCK spectral_KPOINT_PATH 0.0 0.0 0.0 !G 0.5 0.5 0.5 !H 0.5 0.0 0.0 !N 0.0 0.0 0.0 !G 0.75 0.25 -0.25 !P 0.5 0.0 0.0 !N %ENDBLOCK spectral_KPOINT_PATH In the param file we set spin_polarised true in order to allow the up and down spin electrons to take different configurations. It is important to start the calculation with an initial spin density using e.g. spin: 1 . The value of the initial spin should not affect the final answer - a non-zero value is just needed to break the symmetry between the spin channels. ! Fe.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! grid_scale 2.0 ! opt_strategy speed ! Choose algorithms for best speed spin 1 ! Set the spin in the original cell to 1. spin_polarised true ! Run a spin polarised calculation spectral_nbands 6 ! number of bands to compute during the BS run At the end of the calculation the net spin of the unit cell is reported in the castep file e.g. Integrated Spin Density = 2.15322 hbar/2 Note The band structure has similarities with that of Copper - and other 3d elements - with flat 3d bands and dispersive s bands. We colour code the bands according to their spin chactacter (red=up, blue=down). We can see that there is an almost constant exchange splitting of 1.5eV between the up and down 3d bands. The splitting between the s-like bands is much smaller. More up states lie below the fermi energy than down states - hence the net spin of the unit cell.","title":"Iron"},{"location":"tutorials/Bands_and_DOS/magnetic/#feo","text":"FeO is an anti-ferromagnetic oxide. We set up the calculation with initial spins on the two Fe atoms pointing in opposite directions. ! FeO.cell %BLOCK LATTICE_CART 1.768531594289456 0.000000000000001 5.002162732258922 -0.884265797144728 1.531593288050063 5.002162732258921 -0.884265797144728 -1.531593288050063 5.002162732258922 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC O 0.75 0.750 -1.250 O -0.75 -0.750 1.250 Fe 0.00 0.000 -0.000 spin=-4.0 Fe 1.50 -0.500 -0.500 spin=4.0 %ENDBLOCK POSITIONS_FRAC kpoints_mp_grid: 6 6 6 symmetry_generate %block spectral_kpoint_path 0.500 0.500 0.000 0.000 0.000 0.000 0.500 0.500 0.500 0.000 0.500 0.000 0.000 0.000 0.000 %endblock spectral_kpoint_path ! FeO.param task : spectral ! The TASK keyword instructs CASTEP what to do xc_functional : PBE ! Which exchange-correlation functional to use. cutoff_energy 600 eV opt_strategy speed ! Choose algorithms for speed. nextra_bands : 6 spin_polarized : true A PBE calculation incorrectly finds FeO to be a metal (bandstructure on left below). Add the following to the cell file to run a PBE+U calculation %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u FeO band structure with PBE (left) and with PBE+U (right) Note Adding a Hubbard U term to the calculation opens the band gap and FeO is (correctly) predicted to be an antiferromangetic insulator.","title":"FeO"},{"location":"tutorials/Bands_and_DOS/metals/","text":"Here we use CASTEP to calculate the bandstructure of two typical metals. The cell and param files are very similar to the semiconductor examples - the one difference is that we use a finer sampling of the Brillouin Zone with the keyword kpoint_mp_grid . A finer sampling is needed to correctly represent the change in occupancy at the Fermi energy. Aluminium ! Al.cell %BLOCK LATTICE_ABC 2.86 2.86 2.86 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Al 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Al.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Aluminium is a metal - there is no gap energy between the occupied and unoccupied states. The bands are close to parabolic (this is particularly noticeable around Gamma) - the electronic structure of aluminium closely follows a nearly-free electron model. Copper ! Cu.cell %BLOCK LATTICE_ABC 2.55 2.55 2.55 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Cu 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Cu.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed at expense of memory. spectral_nbands 8 ! Note Copper is a metal - there is no gap energy between the occupied and unoccupied states. The bandstructure of copper is typical for a transition metal - we have highly dispersive parabolic bands corresponding to the s electrons, these are crossed by 5 quite flat bands corresponding to more localised 3d electrons. In copper the 3d states are filled, and we see the flat bands lie below the Fermi level.","title":"Metals"},{"location":"tutorials/Bands_and_DOS/metals/#aluminium","text":"! Al.cell %BLOCK LATTICE_ABC 2.86 2.86 2.86 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Al 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Al.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Aluminium is a metal - there is no gap energy between the occupied and unoccupied states. The bands are close to parabolic (this is particularly noticeable around Gamma) - the electronic structure of aluminium closely follows a nearly-free electron model.","title":"Aluminium"},{"location":"tutorials/Bands_and_DOS/metals/#copper","text":"! Cu.cell %BLOCK LATTICE_ABC 2.55 2.55 2.55 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Cu 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Cu.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed at expense of memory. spectral_nbands 8 ! Note Copper is a metal - there is no gap energy between the occupied and unoccupied states. The bandstructure of copper is typical for a transition metal - we have highly dispersive parabolic bands corresponding to the s electrons, these are crossed by 5 quite flat bands corresponding to more localised 3d electrons. In copper the 3d states are filled, and we see the flat bands lie below the Fermi level.","title":"Copper"},{"location":"tutorials/Bands_and_DOS/semiconductors/","text":"In this tutorial we will show you the cell and param files needed to plot bandstructures and density of states plots for various semiconductors. For the commands needed to make the plots refer to earlier tutorials. Silicon ! Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path ! Si.cell task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Silicon is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is indirect as the valence band maximum is as Gamma, but the conduction band minimum lies between Gamma and X. Gallium Arsenide The cell file is almost identical to the silicon example above, except that the unitc cell length is slighly larger, and we have replaced one Si atom with Ga, and the other Si with As. ! GaAs.cell %block lattice_abc 4 4 4 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Ga 0.00 0.00 0.00 As 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path The param file is unchanged from the Silicon example ! GaAs.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note GaAs is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is direct both the valence band maximum and conduction band minimum are at Gamma. Compared with Silicon we see that the original bandstructure contains low lying flat bands at around -32eV and -12eV. This is because both the Ga and As pseudopotentials include semi-core states in the valence. The red states are the As 3d and the green are the Ga 3d.","title":"Semiconductors"},{"location":"tutorials/Bands_and_DOS/semiconductors/#silicon","text":"! Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path ! Si.cell task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Silicon is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is indirect as the valence band maximum is as Gamma, but the conduction band minimum lies between Gamma and X.","title":"Silicon"},{"location":"tutorials/Bands_and_DOS/semiconductors/#gallium-arsenide","text":"The cell file is almost identical to the silicon example above, except that the unitc cell length is slighly larger, and we have replaced one Si atom with Ga, and the other Si with As. ! GaAs.cell %block lattice_abc 4 4 4 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Ga 0.00 0.00 0.00 As 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path The param file is unchanged from the Silicon example ! GaAs.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note GaAs is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is direct both the valence band maximum and conduction band minimum are at Gamma. Compared with Silicon we see that the original bandstructure contains low lying flat bands at around -32eV and -12eV. This is because both the Ga and As pseudopotentials include semi-core states in the valence. The red states are the As 3d and the green are the Ga 3d.","title":"Gallium Arsenide"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/","text":"In this tutorial we will walk through plotting a bandstructure and density of states using the perl utilities supplied with CASTEP. We will use Xmgace for plotting - however, the scripts also support gnuplot. Bandstructure Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dispersion.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dispersion.pl -h' castep si-bands dispersion.pl -sym fcc -xg si-bands.bands You should get a plot Density of States Here is a cell file. It is the same as a bandstructure cell file except we have replaced the path through the Brillioun zone with a regular grid of k-points. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a uniform sampling of the Brillouin Zone ! spectral_kpoint_mp_grid 17 17 17 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task dos ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dos.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dos.pl -h' castep si-dos dos.pl -xg si-dos.bands -w 0.3 You should get a plot like Note The procedure above is inefficient as we computed the groundstate of the system twice, once when computing the bandstructure and again when computing the dos. To avoid this we could put the following line in the si-dos.param file continuation: si-bands.check . This will restart the calculation of the dos using the previously computed groundstate.","title":"Plotting - CASTEP tools"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/#bandstructure","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dispersion.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dispersion.pl -h' castep si-bands dispersion.pl -sym fcc -xg si-bands.bands You should get a plot","title":"Bandstructure"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/#density-of-states","text":"Here is a cell file. It is the same as a bandstructure cell file except we have replaced the path through the Brillioun zone with a regular grid of k-points. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a uniform sampling of the Brillouin Zone ! spectral_kpoint_mp_grid 17 17 17 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task dos ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dos.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dos.pl -h' castep si-dos dos.pl -xg si-dos.bands -w 0.3 You should get a plot like Note The procedure above is inefficient as we computed the groundstate of the system twice, once when computing the bandstructure and again when computing the dos. To avoid this we could put the following line in the si-dos.param file continuation: si-bands.check . This will restart the calculation of the dos using the previously computed groundstate.","title":"Density of States"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_sumo/","text":"This is stub for https://github.com/ajjackson/castep-sumo-tutorial/blob/master/castep-sumo.org","title":"Plotting - SUMO"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/","text":"Density of States In this tutorial, we will go through a simple example of using Optados to calculate the electronic density of states (DoS) of crystalline silicon in a 2 atom cell. We will then examine how Optados' adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. ODO Output Firstly, we will run the calculation and examine the Optados output file Si.odo . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 together with the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE SPIN_POLARIZED : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 The first 2 lines are what determine that we will be doing a DoS calculation. Run castep as usual, and then run optados on Si with the Optados input file Si.odi TASK : dos EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default One interesting thing to note here is the line efermi : optados - this sets the internal value of the Fermi level to the one it has derived from the DoS. This is important for subsequent calculations. Other valid options are: file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues insulator , where optados uses a value calculated from assuming the system is non-metallic A custom value you may want to use This generates 3 files: Si.odo - Optados general output file. Si.adaptive.dat - The adaptive broadened DOS raw output data. Si.adaptive.agr - The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Let's have a look at the file Si.odo Towards the top of the data output, we have a table looking like this: ``` +--------------- Fermi Energy Analysis ---------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99964 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99964 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 4.4479 eV <- EfA | +-----------------------------------------------------------------+ ``` It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. Optados now performs some analysis of the DOS at the Fermi level, +----------------------- DOS at Fermi Energy Analysis -----------------------+ | Fermi energy used : 4.4479 eV | | From Adaptive broadening | | Spin Component : 1 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | | Spin Component : 2 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | +----------------------------------------------------------------------------+ From this we may assume that there is a band gap. A bit further down, Optados then calculates the band energy from the DOS is has calculated. +--------------------------- Band Energy Analysis ---------------------------+ | Band energy (Adaptive broadening) : -6.3472 eV <- BEA | | Band energy (From CASTEP) : -6.3471 eV <- BEC | +----------------------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Other Output Files Finally, Optados shifts the Fermi level to 0 eV for the output files - let's have a look at the other 2 files generated. The DoS is written to Si2.adaptive.dat . This contains 5 columns - the 1 st is the energy, the 2 nd is the up-spin DoS, the 3 rd is the down-spin DoS, the 4 th is the up-spin integrated DoS, and the 5 th is the down-spin integrated DoS. If instead SPIN_POLARIZED : FALSE were set in the param file, there would only be 3 columns: energy, DoS and integrated DoS. This file can be plotted by your preferred graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace - to get a plot all you have to run is: $ xmgrace Si2.adaptive.agr The graph should look a bit like this: What is important to mention is that this agr file only contains the data for DoS, not integrated DoS. If you want to plot all the data, including up and down integrated DoS, run xmgrace -batch other_data.bat on the batch file other_data.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Up DOS\" BLOCK XY \"1:3\" S1 LEGEND \"Down DOS\" BLOCK XY \"1:4\" S2 LEGEND \"Up IntDos\" BLOCK XY \"1:5\" S3 LEGEND \"Down IntDos\" This should give a graph that looks like: Band Gap Analysis Let's go back to looking at the odo output file. Because COMPUTE_BAND_GAP : TRUE is set by default, the band gap analysis section should already be present. The results are a table that looks like: +----------------------------- Bandgap Analysis -----------------------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6724150536 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000 | | and CBM kpoint: -0.45000 -0.45000 -0.05000 | | ==> Indirect Gap | +----------------------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5639496096 eV <- OBg | | Spin : 2 : 2.5639441673 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +----------------------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8132681742 eV <- ABg | | Spin : 2 : 3.8132658290 eV <- ABg | | Weighted Average : 3.8132670016 eV <- wAB | +----------------------------------------------------------------------------+ Optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Broadening We will now compare the different forms of broadening. This can be done quickly by changing the first in Si.odi to task : compare_dos and re-running Optados. This gives us 4 new output files - Si_linear.dat and Si_fixed.dat , plus their accompanying agr files. Let's compare them by running xmgrace -batch compare.bat on the batch file compare.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Adaptive DOS\" READ BLOCK \"Si.linear.dat\" BLOCK XY \"1:2\" S1 LEGEND \"Linear DOS\" READ BLOCK \"Si.fixed.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Fixed DOS\" WORLD XMIN 0 WORLD XMAX 5 Note We're looking at a small region, between 0 and 5 eV, so it is easier to see the differences The graph should look like this: To further improve the appearance of the graph, you can lower DOS_SPACING and tinker with the value of ADAPTIVE_SMEARING in the odi file.","title":"OptaDOS - DOS"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#density-of-states","text":"In this tutorial, we will go through a simple example of using Optados to calculate the electronic density of states (DoS) of crystalline silicon in a 2 atom cell. We will then examine how Optados' adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure.","title":"Density of States"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#odo-output","text":"Firstly, we will run the calculation and examine the Optados output file Si.odo . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 together with the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE SPIN_POLARIZED : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 The first 2 lines are what determine that we will be doing a DoS calculation. Run castep as usual, and then run optados on Si with the Optados input file Si.odi TASK : dos EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default One interesting thing to note here is the line efermi : optados - this sets the internal value of the Fermi level to the one it has derived from the DoS. This is important for subsequent calculations. Other valid options are: file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues insulator , where optados uses a value calculated from assuming the system is non-metallic A custom value you may want to use This generates 3 files: Si.odo - Optados general output file. Si.adaptive.dat - The adaptive broadened DOS raw output data. Si.adaptive.agr - The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Let's have a look at the file Si.odo Towards the top of the data output, we have a table looking like this: ``` +--------------- Fermi Energy Analysis ---------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99964 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99964 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 4.4479 eV <- EfA | +-----------------------------------------------------------------+ ``` It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. Optados now performs some analysis of the DOS at the Fermi level, +----------------------- DOS at Fermi Energy Analysis -----------------------+ | Fermi energy used : 4.4479 eV | | From Adaptive broadening | | Spin Component : 1 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | | Spin Component : 2 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | +----------------------------------------------------------------------------+ From this we may assume that there is a band gap. A bit further down, Optados then calculates the band energy from the DOS is has calculated. +--------------------------- Band Energy Analysis ---------------------------+ | Band energy (Adaptive broadening) : -6.3472 eV <- BEA | | Band energy (From CASTEP) : -6.3471 eV <- BEC | +----------------------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer.","title":"ODO Output"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#other-output-files","text":"Finally, Optados shifts the Fermi level to 0 eV for the output files - let's have a look at the other 2 files generated. The DoS is written to Si2.adaptive.dat . This contains 5 columns - the 1 st is the energy, the 2 nd is the up-spin DoS, the 3 rd is the down-spin DoS, the 4 th is the up-spin integrated DoS, and the 5 th is the down-spin integrated DoS. If instead SPIN_POLARIZED : FALSE were set in the param file, there would only be 3 columns: energy, DoS and integrated DoS. This file can be plotted by your preferred graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace - to get a plot all you have to run is: $ xmgrace Si2.adaptive.agr The graph should look a bit like this: What is important to mention is that this agr file only contains the data for DoS, not integrated DoS. If you want to plot all the data, including up and down integrated DoS, run xmgrace -batch other_data.bat on the batch file other_data.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Up DOS\" BLOCK XY \"1:3\" S1 LEGEND \"Down DOS\" BLOCK XY \"1:4\" S2 LEGEND \"Up IntDos\" BLOCK XY \"1:5\" S3 LEGEND \"Down IntDos\" This should give a graph that looks like:","title":"Other Output Files"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#band-gap-analysis","text":"Let's go back to looking at the odo output file. Because COMPUTE_BAND_GAP : TRUE is set by default, the band gap analysis section should already be present. The results are a table that looks like: +----------------------------- Bandgap Analysis -----------------------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6724150536 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000 | | and CBM kpoint: -0.45000 -0.45000 -0.05000 | | ==> Indirect Gap | +----------------------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5639496096 eV <- OBg | | Spin : 2 : 2.5639441673 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +----------------------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8132681742 eV <- ABg | | Spin : 2 : 3.8132658290 eV <- ABg | | Weighted Average : 3.8132670016 eV <- wAB | +----------------------------------------------------------------------------+ Optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap.","title":"Band Gap Analysis"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#broadening","text":"We will now compare the different forms of broadening. This can be done quickly by changing the first in Si.odi to task : compare_dos and re-running Optados. This gives us 4 new output files - Si_linear.dat and Si_fixed.dat , plus their accompanying agr files. Let's compare them by running xmgrace -batch compare.bat on the batch file compare.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Adaptive DOS\" READ BLOCK \"Si.linear.dat\" BLOCK XY \"1:2\" S1 LEGEND \"Linear DOS\" READ BLOCK \"Si.fixed.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Fixed DOS\" WORLD XMIN 0 WORLD XMAX 5 Note We're looking at a small region, between 0 and 5 eV, so it is easier to see the differences The graph should look like this: To further improve the appearance of the graph, you can lower DOS_SPACING and tinker with the value of ADAPTIVE_SMEARING in the odi file.","title":"Broadening"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/pDOS/","text":"Projected Density of States In this tutorial, we will using Optados to calculate the electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. It may be helpful to have gone through the previous tutorial on calculating the DoS . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 12 12 12 and the param file Si.param TASK : SPECTRAL %BLOCK devel_code spectral: check_output: true :endspectral %ENDBLOCK devel_code SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 Run castep. Then, run Optados with the Optados input file Si.odi TASK : pdos PDOS : angular EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default Note the line TASK : pdos - this is what allows us to calculate the PDoS. We have chosen to decompose the DOS into angular momentum channels with the line PDOS : angular , and as in the previous example , we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by Castep. The output can be found in Si2.pdos.dat - it contains the header below to tell us what each column represnts. ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ This shows that there are four projectors described below - each one corresponding to a column in the actual data. The 1 st contains the s-channels of both silicon atoms, the 2 nd the p-channels etc. The values correspond to the sums of the values of both Si atoms. You can change which projectors you will gain by changing the line PDOS : ANGULAR . Changing the value to SPECIES_ANG will give you only the first 2 projectors. SPECIES will yield the sum of all the orbitals and atoms. SITES will give you 1 projector of the sum of all orbitals of Si atom 1, and 1 of atom 2 (note that they're identical). You can also make custom projectors - write down the element, number and orbital in brackets, with columns separating adjacent projectors if you want multiple. For example, Si1(s):Si2(p) will give you 1 column of the PDoS of the s orbital on silicon atom 1, and a column of the p orbital on silicon atom 2. Note Using custom projectors won't save the data in Si.pdos.dat , but a file named based on the projectors chosen - in the example above, it'd be saved in Si.pdos.proj-0001-0002.dat . The output is easily plotted by using xmgrace on the dat file. To plot multiple bits of data, it is easiest to use a batch file - this is the plot of the s and p channels: We can run xmgrace -batch pdos_plot.bat on the batch file pdos_plot.bat READ BLOCK \"Si.pdos.dat\" BLOCK XY \"1:2\" S0 LEGEND \"s-channel\" BLOCK XY \"1:3\" S1 LEGEND \"p-channel\" to get the following output:","title":"OptaDOS - pDOS"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/pDOS/#projected-density-of-states","text":"In this tutorial, we will using Optados to calculate the electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. It may be helpful to have gone through the previous tutorial on calculating the DoS . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 12 12 12 and the param file Si.param TASK : SPECTRAL %BLOCK devel_code spectral: check_output: true :endspectral %ENDBLOCK devel_code SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 Run castep. Then, run Optados with the Optados input file Si.odi TASK : pdos PDOS : angular EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default Note the line TASK : pdos - this is what allows us to calculate the PDoS. We have chosen to decompose the DOS into angular momentum channels with the line PDOS : angular , and as in the previous example , we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by Castep. The output can be found in Si2.pdos.dat - it contains the header below to tell us what each column represnts. ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ This shows that there are four projectors described below - each one corresponding to a column in the actual data. The 1 st contains the s-channels of both silicon atoms, the 2 nd the p-channels etc. The values correspond to the sums of the values of both Si atoms. You can change which projectors you will gain by changing the line PDOS : ANGULAR . Changing the value to SPECIES_ANG will give you only the first 2 projectors. SPECIES will yield the sum of all the orbitals and atoms. SITES will give you 1 projector of the sum of all orbitals of Si atom 1, and 1 of atom 2 (note that they're identical). You can also make custom projectors - write down the element, number and orbital in brackets, with columns separating adjacent projectors if you want multiple. For example, Si1(s):Si2(p) will give you 1 column of the PDoS of the s orbital on silicon atom 1, and a column of the p orbital on silicon atom 2. Note Using custom projectors won't save the data in Si.pdos.dat , but a file named based on the projectors chosen - in the example above, it'd be saved in Si.pdos.proj-0001-0002.dat . The output is easily plotted by using xmgrace on the dat file. To plot multiple bits of data, it is easiest to use a batch file - this is the plot of the s and p channels: We can run xmgrace -batch pdos_plot.bat on the batch file pdos_plot.bat READ BLOCK \"Si.pdos.dat\" BLOCK XY \"1:2\" S0 LEGEND \"s-channel\" BLOCK XY \"1:3\" S1 LEGEND \"p-channel\" to get the following output:","title":"Projected Density of States"},{"location":"tutorials/Bonding_and_Charge/ELF/","text":"ELF (Electron Localization Function) measures how \"local\" electrons are - the higher the value, the more likely electrons are to make opposite-spin pairs and generally be more \"fixed\" in place. We will use it to examine ionic and covalent bonding, and then use it to examine lone pairs (and hydrogen bonding) in HF, H 2 O and NH 3 molecules. A lot of the steps on examining the data are the same as in Plotting Charge Density - if you prefer, you may use that (and its accompanying video tutorial ), though the cells and planes used are slightly different. For visualising the results, this tutorial will use Vesta , but feel free to use another software if you prefer. NaCl We will start by looking at how electrons in an NaCl crystal behave - to illustrate what ELF exactly does and doesn't do, we will compare it to the results of a standard population analysis. For both calculations we will use the cell file NaCl.cell %block lattice_cart 5.693 0.000 0.000 0.000 5.693 0.000 0.000 0.000 5.693 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 Na 0.0 0.5 0.5 Na 0.5 0.0 0.5 Na 0.5 0.5 0.0 Cl 0.5 0.5 0.5 Cl 0.5 0.0 0.0 Cl 0.0 0.5 0.0 Cl 0.0 0.0 0.5 %endblock positions_frac and the param file NaCl.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false WRITE_FORMATTED_DENSITY : TRUE CALCULATE_ELF : TRUE WRITE_FORMATTED_ELF : TRUE Running castep will yield 2 files of interest: NaCl.elf_fmt and NaCl.den_fmt . We will want to compare the 2 outputs, so: Make 2 copies of the cell file by copying NaCl.cell to NaCl_elf.cell and NaCl_den.cell . 2. Copy NaCl.elf_fmt to NaCl_elf.charg_frm Copy NaCl.den_fmt to NaCl_den.charg_frm . In both .charg_frm files remove the header. Following this, they should look like: 1 1 1 0.000000 2 1 1 0.000000 3 1 1 0.000000 4 1 1 0.000000 5 1 1 0.000000 Now we will be able to visualise the results. Note If you wish to move the files around, make sure that the .charg_frm file is located in the same directory as its respective cell file - for example, NaCl_elf.charg_frm should be with NaCl_elf.cell . We will first look at the density output. Open it in Vesta, and, at the top-bar, go to Utilities -> 2D Data Display . It should open a window which looks like: There, click Slice - this will open another window You should keep the hkl (lattice Miller indices) as 001 , but make a 2x2 supercell and change x(min) , y(min) and z(min) to -1 . Click Ok and you should get an output which looks like: This is what we'd expect of a the charge density in an ionic crystal: a regular pattern where a region with a low relative electron density (the cation) is adjacent to one with a high electron density (the anion). Now let's follow the exact same procedure, except this time with NaCl_elf for the ELF result. This is the outcome: This is rather interesting: though the electron density around the Na + cation is very low, the electrons are much more localised around it - the opposite is true for Cl - : the ELF is high where density is low and vice versa. While both, in the simplest model, have full outer shells and thus should both be highly localised (in fact they are both localised, Na + just moreso), Cl - simply has larger orbitals and has a full valence shell (rather than core), leading to lower localisation. This helps illustrate the key difference between ELF and population analysis: ELF is purely a measure of how localised the electrons are in space, and doesn't always correspond to a higher density. Covalent bonding - Si We will now use ELF to demonstrate covalent bonding in diamond-silicon. We will use the cell file Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac Run castep with an identical param file (you may remove WRITE_FORMATTED_DENSITY : TRUE if not you're not interested in the charge density). Follow the exact same procedure as above (though again you can ignore anything to do with the charge density). After opening it in Vesta, rather than taking a slice, click Edit -> Lattice planes , which will open the window below: Click New and use the 100 plane as before. Then click Ok . Create a supercell. This time click Boundary... on the left side of the main window. Make a 2x2 supercell as before. Rotate the cell around until you see what's happening. You should see something like: You can uncheck Show models to see it better without the atoms This tells us a rather interesting story - the atoms are highly localised along the covalent Si-Si bonds, but relatively delocalised near the atoms themselves. They are especially delocalised in regions where is no bonding or atoms. If you wish to also examine and compare the charge density, this is covered in another tutorial HF Now that we have a good understand of what ELF actually does, let's use it for a more interesting purpose: to demonstrate lone pairs and hydrogen bonding. Lone pairs are by their nature highly localised, pairing up with each other and being held largely in place by strong repulsions to any negative charges (including other lone pairs) and strong attractions to positive ones (such as adjacent dipoles - this leads to hydrogen bonding) For HF we will use the cell file: HF.cell %block lattice_abc 6 6 6 90 90 90 %endblock lattice_abc %block positions_abs H 3 3 3 F 3.92 3 3 %endblock positions_abs kpoints_mp_grid 4 4 4 and again the same param file. Following the exact same steps as with NaCl, slicing the (010) plane (with the distance from the origin, set in the same slice window, set as 0.5d - 0.5 * the size of the side lengths) we get an output looking like: This gives us an interesting picture: the small regions of high electron locality look like what we'd expect of lone pairs. The fluorine has 3 around it (as expected), yet the hydrogen also has 1. Considering that this will be interacting with adjacent cells, which is inevitable given that this is calculated with periodic boundaries, this is a good indication that it has formed a hydrogen bond. Water and ammonia The procedure for H 2 O and NH 3 is almost identical. We use exactly the same param file as above, and perform the same procedures following the elf_fmt output. The cell files we use are: H2O.cell %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs O 2.5 2.5 2.5 H 2.5 1.95 3.29 H 2.5 1.95 1.72 %endblock positions_abs for water and NH3.cell %BLOCK LATTICE_ABC 8 8 8 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS N 4 4 4 H 4 4 5 H 4.95 4 3.67 H 3.53 3.18 3.67 %ENDBLOCK POSITIONS_ABS For ammonia. From then, we again go to 2D display data and Slice... . This is where the procedure might be a bit different: by shift clicking on all the atoms in H 2 O (and the atoms within the plane you wish to look at in NH 3 ) and clicking Calculate the best plane for the selected atoms it'll give us the plane that we may be most interested in. In the case of water it is a simple (100), but for NH 3 you may wish to play around with it by selecting different combinations - alternatively manually choose a plane in which you are interested. Note In VESTA, plane selection may work a bit differently from how you'd expect. In this example, since you're cutting through the middle you'd normally call it a (200) plane. However, here it is considered a (100) plane 2.5 \\mathring{\\text{A}} \\mathring{\\text{A}} (or 0.5d - since the unit cell lengths are 5 \\mathring{\\text{A}} \\mathring{\\text{A}} ) from the origin The result for water in the (100) plane should look like: Alternatively, to better see which bonds/atoms are corresponding to the regions of high/low electron locality, use the Lattice planes method so you can see the cell along with the ELF map. You can again Calculate the best plane for the selected atoms like we did for ammonia with slicing. Feel free to also select different planes and look at how it looks in them. Note Don't forget you can turn off Show isosurfaces and Show sections under Volumetric data - if you're going to be looking at the cell itself this may obscure what you're trying to look at Lastly, let's take a quick look at the NH 3 result. Selecting the best plane containing 2 hydrogens and a nitrogen should give a result looking like: Here we see evidence of lone pairs on both of the hydrogens in the plane (as both can form hydrogen bonds - and so can the third if you look at that one). This is rather unexpected - in the classical view, NH 3 has a nitrogen with 1 lone pair that simply forms a single hydrogen bond with a hydrogen in an adjacent NH 3 . However, because every hydrogen is capable of forming a hydrogen bond, ELF registers them as having regions of high locality near them. The same applies to nitrogen - though it should classically only have 1 pair near it, it is seen as having 2 as it is capable of making 2 hydrogen bonds in that plane. Warning The results will likely look different depending on which 2 hydrogens you pick along with the nitrogen. This can be mostly explained due to how adjacent ammonia molecules are aligned relative to it, which is defined by the cell.","title":"ELF"},{"location":"tutorials/Bonding_and_Charge/ELF/#nacl","text":"We will start by looking at how electrons in an NaCl crystal behave - to illustrate what ELF exactly does and doesn't do, we will compare it to the results of a standard population analysis. For both calculations we will use the cell file NaCl.cell %block lattice_cart 5.693 0.000 0.000 0.000 5.693 0.000 0.000 0.000 5.693 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 Na 0.0 0.5 0.5 Na 0.5 0.0 0.5 Na 0.5 0.5 0.0 Cl 0.5 0.5 0.5 Cl 0.5 0.0 0.0 Cl 0.0 0.5 0.0 Cl 0.0 0.0 0.5 %endblock positions_frac and the param file NaCl.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false WRITE_FORMATTED_DENSITY : TRUE CALCULATE_ELF : TRUE WRITE_FORMATTED_ELF : TRUE Running castep will yield 2 files of interest: NaCl.elf_fmt and NaCl.den_fmt . We will want to compare the 2 outputs, so: Make 2 copies of the cell file by copying NaCl.cell to NaCl_elf.cell and NaCl_den.cell . 2. Copy NaCl.elf_fmt to NaCl_elf.charg_frm Copy NaCl.den_fmt to NaCl_den.charg_frm . In both .charg_frm files remove the header. Following this, they should look like: 1 1 1 0.000000 2 1 1 0.000000 3 1 1 0.000000 4 1 1 0.000000 5 1 1 0.000000 Now we will be able to visualise the results. Note If you wish to move the files around, make sure that the .charg_frm file is located in the same directory as its respective cell file - for example, NaCl_elf.charg_frm should be with NaCl_elf.cell . We will first look at the density output. Open it in Vesta, and, at the top-bar, go to Utilities -> 2D Data Display . It should open a window which looks like: There, click Slice - this will open another window You should keep the hkl (lattice Miller indices) as 001 , but make a 2x2 supercell and change x(min) , y(min) and z(min) to -1 . Click Ok and you should get an output which looks like: This is what we'd expect of a the charge density in an ionic crystal: a regular pattern where a region with a low relative electron density (the cation) is adjacent to one with a high electron density (the anion). Now let's follow the exact same procedure, except this time with NaCl_elf for the ELF result. This is the outcome: This is rather interesting: though the electron density around the Na + cation is very low, the electrons are much more localised around it - the opposite is true for Cl - : the ELF is high where density is low and vice versa. While both, in the simplest model, have full outer shells and thus should both be highly localised (in fact they are both localised, Na + just moreso), Cl - simply has larger orbitals and has a full valence shell (rather than core), leading to lower localisation. This helps illustrate the key difference between ELF and population analysis: ELF is purely a measure of how localised the electrons are in space, and doesn't always correspond to a higher density.","title":"NaCl"},{"location":"tutorials/Bonding_and_Charge/ELF/#covalent-bonding-si","text":"We will now use ELF to demonstrate covalent bonding in diamond-silicon. We will use the cell file Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac Run castep with an identical param file (you may remove WRITE_FORMATTED_DENSITY : TRUE if not you're not interested in the charge density). Follow the exact same procedure as above (though again you can ignore anything to do with the charge density). After opening it in Vesta, rather than taking a slice, click Edit -> Lattice planes , which will open the window below: Click New and use the 100 plane as before. Then click Ok . Create a supercell. This time click Boundary... on the left side of the main window. Make a 2x2 supercell as before. Rotate the cell around until you see what's happening. You should see something like: You can uncheck Show models to see it better without the atoms This tells us a rather interesting story - the atoms are highly localised along the covalent Si-Si bonds, but relatively delocalised near the atoms themselves. They are especially delocalised in regions where is no bonding or atoms. If you wish to also examine and compare the charge density, this is covered in another tutorial","title":"Covalent bonding - Si"},{"location":"tutorials/Bonding_and_Charge/ELF/#hf","text":"Now that we have a good understand of what ELF actually does, let's use it for a more interesting purpose: to demonstrate lone pairs and hydrogen bonding. Lone pairs are by their nature highly localised, pairing up with each other and being held largely in place by strong repulsions to any negative charges (including other lone pairs) and strong attractions to positive ones (such as adjacent dipoles - this leads to hydrogen bonding) For HF we will use the cell file: HF.cell %block lattice_abc 6 6 6 90 90 90 %endblock lattice_abc %block positions_abs H 3 3 3 F 3.92 3 3 %endblock positions_abs kpoints_mp_grid 4 4 4 and again the same param file. Following the exact same steps as with NaCl, slicing the (010) plane (with the distance from the origin, set in the same slice window, set as 0.5d - 0.5 * the size of the side lengths) we get an output looking like: This gives us an interesting picture: the small regions of high electron locality look like what we'd expect of lone pairs. The fluorine has 3 around it (as expected), yet the hydrogen also has 1. Considering that this will be interacting with adjacent cells, which is inevitable given that this is calculated with periodic boundaries, this is a good indication that it has formed a hydrogen bond.","title":"HF"},{"location":"tutorials/Bonding_and_Charge/ELF/#water-and-ammonia","text":"The procedure for H 2 O and NH 3 is almost identical. We use exactly the same param file as above, and perform the same procedures following the elf_fmt output. The cell files we use are: H2O.cell %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs O 2.5 2.5 2.5 H 2.5 1.95 3.29 H 2.5 1.95 1.72 %endblock positions_abs for water and NH3.cell %BLOCK LATTICE_ABC 8 8 8 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS N 4 4 4 H 4 4 5 H 4.95 4 3.67 H 3.53 3.18 3.67 %ENDBLOCK POSITIONS_ABS For ammonia. From then, we again go to 2D display data and Slice... . This is where the procedure might be a bit different: by shift clicking on all the atoms in H 2 O (and the atoms within the plane you wish to look at in NH 3 ) and clicking Calculate the best plane for the selected atoms it'll give us the plane that we may be most interested in. In the case of water it is a simple (100), but for NH 3 you may wish to play around with it by selecting different combinations - alternatively manually choose a plane in which you are interested. Note In VESTA, plane selection may work a bit differently from how you'd expect. In this example, since you're cutting through the middle you'd normally call it a (200) plane. However, here it is considered a (100) plane 2.5 \\mathring{\\text{A}} \\mathring{\\text{A}} (or 0.5d - since the unit cell lengths are 5 \\mathring{\\text{A}} \\mathring{\\text{A}} ) from the origin The result for water in the (100) plane should look like: Alternatively, to better see which bonds/atoms are corresponding to the regions of high/low electron locality, use the Lattice planes method so you can see the cell along with the ELF map. You can again Calculate the best plane for the selected atoms like we did for ammonia with slicing. Feel free to also select different planes and look at how it looks in them. Note Don't forget you can turn off Show isosurfaces and Show sections under Volumetric data - if you're going to be looking at the cell itself this may obscure what you're trying to look at Lastly, let's take a quick look at the NH 3 result. Selecting the best plane containing 2 hydrogens and a nitrogen should give a result looking like: Here we see evidence of lone pairs on both of the hydrogens in the plane (as both can form hydrogen bonds - and so can the third if you look at that one). This is rather unexpected - in the classical view, NH 3 has a nitrogen with 1 lone pair that simply forms a single hydrogen bond with a hydrogen in an adjacent NH 3 . However, because every hydrogen is capable of forming a hydrogen bond, ELF registers them as having regions of high locality near them. The same applies to nitrogen - though it should classically only have 1 pair near it, it is seen as having 2 as it is capable of making 2 hydrogen bonds in that plane. Warning The results will likely look different depending on which 2 hydrogens you pick along with the nitrogen. This can be mostly explained due to how adjacent ammonia molecules are aligned relative to it, which is defined by the cell.","title":"Water and ammonia"},{"location":"tutorials/Bonding_and_Charge/charge_density/","text":"In this tutorial we will walk through plotting a charge density with Vesta https://jp-minerals.org/vesta/en/ Silicon Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 1500 eV #this next line causes the charge to be written in a den_fmt file write_formatted_density : T spin_polarised : false The cutoff energy is somewhat higher than needed for a converged total energy - but it helps when making a smoother looking charge density plot. Run castep. You will see a file called silicon.den_fmt this contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called silicon.charg_frm cp silicon.den_fmt silicon.charg_frm Now edit the file silicon.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open silicon.charg_frm with Vesta. Note that Vesta needs both the cell and charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process at https://youtu.be/_c2Hk4jxmm4 An alternative way to plot charge densities (and much more besides) is c2x https://www.c2x.org.uk","title":"Plotting Charge Density"},{"location":"tutorials/Bonding_and_Charge/charge_density/#silicon","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 1500 eV #this next line causes the charge to be written in a den_fmt file write_formatted_density : T spin_polarised : false The cutoff energy is somewhat higher than needed for a converged total energy - but it helps when making a smoother looking charge density plot. Run castep. You will see a file called silicon.den_fmt this contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called silicon.charg_frm cp silicon.den_fmt silicon.charg_frm Now edit the file silicon.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open silicon.charg_frm with Vesta. Note that Vesta needs both the cell and charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process at https://youtu.be/_c2Hk4jxmm4 An alternative way to plot charge densities (and much more besides) is c2x https://www.c2x.org.uk","title":"Silicon"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/","text":"By default castep will calculate the Mulliken Population analysis at the end of every calculation (the keyword popn_calculate is set to true by default). Silicon Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false Run castep. Toward the end of the file silicon.castep you will find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Si 1 1.356 2.644 0.000 0.000 4.000 0.000 Si 2 1.356 2.644 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== Si 1 -- Si 2 2.99 2.32702 ====================================================================== The atoms are not charged overall, and there is a large bond population. This is all indicative of a strong covalent bond. Comparing to Other Diamond Structures To understand the results of this further, we will compare them to 2 other diamond structures - GaAs and diamond (as in carbon-diamond). For both of these cases, we will use an identical .param file (just rename them to diamond.param and GaAs.param ). The cell files will be slightly different - for diamond we will change the lattice_abc block lattice dimensions with 2.52 \\mathring{\\text{A}} \\mathring{\\text{A}} (rather than 3.8 \\mathring{\\text{A}} \\mathring{\\text{A}} - the structure is the same but the cell size is different). Naturally the Si 's in the positions_frac block need to be replaced with C 's Towards the end of diamond.castep we find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== C 1 1.076 2.924 0.000 0.000 4.000 0.000 C 2 1.076 2.924 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== C 1 -- C 2 3.00 1.54318 ====================================================================== The results are rather similar but there are a couple of interesting things to note: The ratio of the populations in s and p orbitals is closer to 1:3, which is expected for sp 3 hybridization - this indicates that the bonds are much more perfectly hybridized, meaning it's more overlapped: this indicates stronger bonding, as well as showing that silicon is a semimetal The population of electrons in the bonds is the same (indicating that the same type of bonding is present), but the bond length is smaller - again indicating more overlap and thus stronger bonding. Now we will compare it with GaAs. The same procedure is used, except the lattice length is now 3.93 \\mathring{\\text{A}} \\mathring{\\text{A}} and the atoms in positions_frac should be Ga and As (it doesn't matter which one goes in which position/line). We get an output looking like this: Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Ga 1 1.180 1.743 9.994 0.000 12.917 0.083 As 1 1.488 3.595 10.000 0.000 15.083 -0.083 ========================================================================== Bond Population Length (A) ====================================================================== Ga 1 -- As 1 0.34 2.44652 ====================================================================== Despite having the same structure, the results are very different now: Unlike before, the Ga and As ions have charges on them - this is indicative of ionic/polar character There is now a much smaller population in the Ga-As bond. This indicates less covalent character Especially in the case of Ga, the s:p shell ratio is far off from 1:3 - this again indicates that the bonding is not like in the cases above Diatomic molecules Next we will examine a few diatomic molecules - HF, HCl and HBr. Here is the HF.cell file %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs H 2 2 2 F 2.91 2 2 %endblock positions_abs Since we are just trying to look at a single diatomic molecule, the cell is defined rather simply - an arbitrarily large cube for the cell (making it too large would make the calculation take longer, but make it too small and it'll simulate a loose crystal rather than a disperse molecule), 1 atom placed about in the middle, and the 2 nd atom placed a bond length away from it - in this case F is 0.91 \\mathring{\\text{A}} \\mathring{\\text{A}} to the right of the H . The bond lengths can be found on a database , or you may perform a geometry optimisation to find it yourself if you wish. Using a param file identical to before and running castep yields this towards the end of HF.castep Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.309 0.000 0.000 0.000 0.309 0.691 F 1 1.960 5.731 0.000 0.000 7.691 -0.691 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- F 1 0.34 0.91000 ====================================================================== There are a couple of interesting things to note: Like GaAs (and unlike Si and diamond), there are 2 opposite charges on both atoms. However, the charge is significantly larger, indicating that the molecule is highly polar/ionic. The population of the H-F bond is rather low - this indicates that the molecule has little covalent character We will now compare HF to very similar molecules - HCl and HBr - keeping the trend of hydrogen bonded to a group 7 element. The param files are completely identical and in the cell files the bond lengths used are 1.275 \\mathring{\\text{A}} \\mathring{\\text{A}} for HCl and 1.44 \\mathring{\\text{A}} \\mathring{\\text{A}} for HBr. HCl has the result Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.620 0.000 0.000 0.000 0.620 0.380 Cl 1 1.936 5.443 0.000 0.000 7.379 -0.379 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Cl 1 0.56 1.27500 ====================================================================== While HBr has Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.824 0.000 0.000 0.000 0.824 0.176 Br 1 1.908 5.267 0.000 0.000 7.176 -0.176 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Br 1 0.53 1.44000 ====================================================================== The most significant thing this shows us is that the charges on both atoms decrease as you go down group 7. This successfully demonstrates something we already know: as you go down group 7, the electronegativity decreases. The same principle can be applied to estimate relative electronegativities of different atoms.","title":"Population Analysis"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#silicon","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false Run castep. Toward the end of the file silicon.castep you will find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Si 1 1.356 2.644 0.000 0.000 4.000 0.000 Si 2 1.356 2.644 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== Si 1 -- Si 2 2.99 2.32702 ====================================================================== The atoms are not charged overall, and there is a large bond population. This is all indicative of a strong covalent bond.","title":"Silicon"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#comparing-to-other-diamond-structures","text":"To understand the results of this further, we will compare them to 2 other diamond structures - GaAs and diamond (as in carbon-diamond). For both of these cases, we will use an identical .param file (just rename them to diamond.param and GaAs.param ). The cell files will be slightly different - for diamond we will change the lattice_abc block lattice dimensions with 2.52 \\mathring{\\text{A}} \\mathring{\\text{A}} (rather than 3.8 \\mathring{\\text{A}} \\mathring{\\text{A}} - the structure is the same but the cell size is different). Naturally the Si 's in the positions_frac block need to be replaced with C 's Towards the end of diamond.castep we find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== C 1 1.076 2.924 0.000 0.000 4.000 0.000 C 2 1.076 2.924 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== C 1 -- C 2 3.00 1.54318 ====================================================================== The results are rather similar but there are a couple of interesting things to note: The ratio of the populations in s and p orbitals is closer to 1:3, which is expected for sp 3 hybridization - this indicates that the bonds are much more perfectly hybridized, meaning it's more overlapped: this indicates stronger bonding, as well as showing that silicon is a semimetal The population of electrons in the bonds is the same (indicating that the same type of bonding is present), but the bond length is smaller - again indicating more overlap and thus stronger bonding. Now we will compare it with GaAs. The same procedure is used, except the lattice length is now 3.93 \\mathring{\\text{A}} \\mathring{\\text{A}} and the atoms in positions_frac should be Ga and As (it doesn't matter which one goes in which position/line). We get an output looking like this: Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Ga 1 1.180 1.743 9.994 0.000 12.917 0.083 As 1 1.488 3.595 10.000 0.000 15.083 -0.083 ========================================================================== Bond Population Length (A) ====================================================================== Ga 1 -- As 1 0.34 2.44652 ====================================================================== Despite having the same structure, the results are very different now: Unlike before, the Ga and As ions have charges on them - this is indicative of ionic/polar character There is now a much smaller population in the Ga-As bond. This indicates less covalent character Especially in the case of Ga, the s:p shell ratio is far off from 1:3 - this again indicates that the bonding is not like in the cases above","title":"Comparing to Other Diamond Structures"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#diatomic-molecules","text":"Next we will examine a few diatomic molecules - HF, HCl and HBr. Here is the HF.cell file %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs H 2 2 2 F 2.91 2 2 %endblock positions_abs Since we are just trying to look at a single diatomic molecule, the cell is defined rather simply - an arbitrarily large cube for the cell (making it too large would make the calculation take longer, but make it too small and it'll simulate a loose crystal rather than a disperse molecule), 1 atom placed about in the middle, and the 2 nd atom placed a bond length away from it - in this case F is 0.91 \\mathring{\\text{A}} \\mathring{\\text{A}} to the right of the H . The bond lengths can be found on a database , or you may perform a geometry optimisation to find it yourself if you wish. Using a param file identical to before and running castep yields this towards the end of HF.castep Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.309 0.000 0.000 0.000 0.309 0.691 F 1 1.960 5.731 0.000 0.000 7.691 -0.691 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- F 1 0.34 0.91000 ====================================================================== There are a couple of interesting things to note: Like GaAs (and unlike Si and diamond), there are 2 opposite charges on both atoms. However, the charge is significantly larger, indicating that the molecule is highly polar/ionic. The population of the H-F bond is rather low - this indicates that the molecule has little covalent character We will now compare HF to very similar molecules - HCl and HBr - keeping the trend of hydrogen bonded to a group 7 element. The param files are completely identical and in the cell files the bond lengths used are 1.275 \\mathring{\\text{A}} \\mathring{\\text{A}} for HCl and 1.44 \\mathring{\\text{A}} \\mathring{\\text{A}} for HBr. HCl has the result Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.620 0.000 0.000 0.000 0.620 0.380 Cl 1 1.936 5.443 0.000 0.000 7.379 -0.379 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Cl 1 0.56 1.27500 ====================================================================== While HBr has Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.824 0.000 0.000 0.000 0.824 0.176 Br 1 1.908 5.267 0.000 0.000 7.176 -0.176 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Br 1 0.53 1.44000 ====================================================================== The most significant thing this shows us is that the charges on both atoms decrease as you go down group 7. This successfully demonstrates something we already know: as you go down group 7, the electronegativity decreases. The same principle can be applied to estimate relative electronegativities of different atoms.","title":"Diatomic molecules"},{"location":"tutorials/Coreloss/Coreloss/","text":"Coreloss Calculation of core-loss spectra for cBN Core-loss calculations effectively calculate the probability of an electron being excited from a core state into the conduction band. This is useful for calculating the core-loss (ionisation edge) peaks - by performing these calculations, you can get a simulation of what you would see in an experimental EELS or XANES spectrum. In this tutorial, we will look at the results of such a calculation on cubic boron nitride (cBN), looking at the boron K-edge. In the end, we will compare it to the spectrum in the EELS Database . We will use the cell file cbn.cell %block lattice_abc 2.5 2.5 2.5 60 60 60 %endblock lattice_abc %block positions_frac B 0.00 0.00 0.00 N 0.25 0.25 0.25 %endblock positions_frac kpoints_mp_grid 10 10 10 spectral_kpoint_mp_grid 12 12 12 with the param file cbn.param task: spectral spectral_task: coreloss xc_functional: LDA opt_strategy: speed Note that a larger number of spectral k-point than standard one is usually required, and, to test if it is converged, you'd have to look at the whole spectrum (rather than examining a single value/result as in some other convergence tests). It is also important that you do not have SYMMETRY_GENERATE on for coreloss calculations. After running Castep, run Optados with the Optados input file cbn.odi TASK : core DOS_SPACING : 0.01 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default CORE_GEOM : polycrystalline # Default CORE_LAI_BROADENING : false # Default true LAI_GAUSSIAN_WIDTH : 1.0 The line TASK : core is what determines that a core-loss calculation will be performed. CORE_GEOM : polycrystalline could also be replaced by core_geom : polarized , in which case you'd also have to add a line specifying the direction - for example, CORE_QDIR : 1 1 1 would simulate the results of an electron (or X-ray) beam going through a single crystal in the [1 1 1] direction. In this tutorial, we will be looking at the polycrystalline case, where it effectively uses the average of all directions. Running Optados should generate 2 files of interest: cbn_B1K1_core_edge.dat and cbn_N1K1_core_edge.dat - these are the results of the core-loss calculations. We will focus on the first dat file - let's look at the boron part specifically. The file starts off like -15.720790912312673 0.0000000000000000 -15.710790160394351 0.0000000000000000 -15.700789408476030 0.0000000000000000 The 1 st column is the energy and the 2 nd is the (smeared) core-loss for that energy. Let's try plotting the dat file with xmgrace - the graph should look like Let's now add some experimental broadening to the results, in order to more accurately simulate experiment. You can do so by re-running Optados (no need to re-run Castep) with CORE_LAI_BROADENING set to true and the lines LAI_GAUSSIAN_WIDTH : 1.8 LAI_LORENTZIAN_WIDTH : 0.1 LAI_LORENTZIAN_SCALE : 0.1 added to the odi file. Gaussian broadening is to simulate the instrument used, and is the same for the whole spectrum, while Lorentzian is to simulate the lifetime effects of the experiment, and is energy-dependent. A Gaussian width of 1.8 is used because we are going to compare it to the spectrum in the EELS Database , and that experiment had a resolution of 1.8eV. A Lorentzian can be used to account for the energy broadening due to the lifetime of the initial and final states. The width depends on the element and edge you are examining, and the value used is recommended here (boron is not there, but 0.1 is recommended for carbon, which is close). A Lorentzian scale of 0.1 is a general and commonly-used value. Re-running it now yields 3 columns in the dat file - it now starts like -15.720790912312673 0.0000000000000000 4.6792920824784473E-005 -15.710790160394351 0.0000000000000000 4.7285842629847867E-005 The 1 st and 2 nd columns are the same, and the 3 rd column is the lifetime and instrumentation (LAI) broadened core-loss results. To plot this with xmgrace, it is easiest to run xmgrace -batch plot.bat on the batch file plot.bat READ BLOCK \"cbn_B1K1_core_edge.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Unbroadened\" BLOCK XY \"1:3\" S1 LEGEND \"Broadened\" WORLD XMIN 0 This gives the graph below Including a core-hole The above was effectively calculating the probability of an electron being able to be excited into the conduction band, corresponding to that same energy being lost from an X-ray/electron and thus XANES/EELs data. However, when calculating that, it was not accounting for the fact that there'd be a core-hole as a result (which naturally will affect energy, DOS and thus probability of occurring): that must be factored in for more realistic results. This is done rather simply by specifying the missing electron when describing the potential in the cell file. If you look at the cbn.castep file generated earlier, you may see that the pseudopotential report contains the line \"2|1.2|12|14|16|20:21(qc=8)\" This tells us what kind of pseudopotential is used for the boron. To specify that there is a 1s electron missing, all you have to do is add {1s1.00} at the end: with only 1 electron in the 1s shell, there is a core electron missing: a core hole. Go into cbn.cell , and add the lines %block species_pot B 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot to calculate the core edge data factoring in the missing 1s electron. Note Your potential may be different, depending on your version of Castep etc. - but don't worry, as the procedure is the same. Also add the line CHARGE : +1 to the cbn.param file - this must be done to maintain charge neutrality. Next, re-run Castep. Let's have a quick look at the pseudopotential report of boron in cbn.castep ============================================================ | Pseudopotential Report - Date of generation 29-07-2024 | ------------------------------------------------------------ | Element: B Ionic charge: 4.00 Level of theory: LDA | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.865 | | 2p 1.000 -0.654 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.865 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.654 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8){1s1.00}\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ You should notice that the energies in the 2s and 2p orbitals are lower, the beta values are all different, and, most importantly, that the pseudopotential used is the one we manually wrote in: the one with only 1 electron in the 1s shell. Now, re-run Optados. This create the same files as before. Again, let's focus on the boron result. The output file cbn_B1K1_core_edge.dat now starts like: -16.879627404257498 0.0000000000000000 4.3418325679994708E-005 -16.869627177952179 0.0000000000000000 4.3433042280034070E-005 The columns represent the same information as before. Plotting it with the same batch file yields us this graph: Supercell The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. To do this, we will create a 2x2x2 supercell - the larger the supercell the better the simulation (as this reduces the core-hole interaction effect more), but the calculation time also shoots up significantly. There are multiple ways of doing this, but this tutorial will cover how it can be done using Vesta . First, upload the cell file we used to Vesta. From the top of the toolbar, go into Edit -> Edit Data -> Unit cell... . This should open up the window below Click Transform... . This opens up a new window To create the 2x2x2 supercell, the transformation matrix is rather simple: make the diagonal values 2 like in the figure above (so it becomes 2x larger in all directions) and click Ok . Select Search atoms in the new unit-cell and add them as new sites in the next pop-up window. Now that the supercell has been generated, we must save it and turn it into a cell file. Click File -> Export Data and save it as cbn.cif file (saving it as a cell file is not an option). We can use cif2cell cbn.cif to get information on how to make the new cell. In the end, we change cbn.cell to: cbn.cell %block lattice_abc 5 5 5 60 60 60 %endblock lattice_abc %block positions_frac B:exi 0.0000000 0.0000000 0.0000000 B 0.0000000 0.0000000 0.5000000 B 0.0000000 0.5000000 0.0000000 B 0.0000000 0.5000000 0.5000000 B 0.5000000 0.0000000 0.0000000 B 0.5000000 0.0000000 0.5000000 B 0.5000000 0.5000000 0.0000000 B 0.5000000 0.5000000 0.5000000 N 0.1250000 0.1250000 0.1250000 N 0.1250000 0.1250000 0.6250000 N 0.1250000 0.6250000 0.1250000 N 0.1250000 0.6250000 0.6250000 N 0.6250000 0.1250000 0.1250000 N 0.6250000 0.1250000 0.6250000 N 0.6250000 0.6250000 0.1250000 N 0.6250000 0.6250000 0.6250000 %endblock positions_frac kpoints_mp_grid 5 5 5 %block species_pot B:exi 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot spectral_kpoint_mp_grid 6 6 6 With double the size of the supercell, you may also halve the kpoints: this allows it to be calculated faster without losing accuracy. However, it will still take significantly longer to calculate. Specifying 1 of the boron atoms to be called B:exi and making changing the potential block to only affect that means that we simulate only 1 of the boron atoms losing that electron - by doing this we prevent the interaction problem mentioned above. In the param file, also add the line NEXTRA_BANDS : 100 This makes Castep perform the calculation for higher-energy bands, and is necessary to prevent too sudden of a drop in the core-loss values towards the higher energies (you may notice that in the above figures the value drops towards 0 after the peaks, but tends towards a finite non-zero value in experiment). Re-run Castep and Optados. There will now be 16 output files, rather than just 2 - there is a core edge output for every atom - cbn_ B 1 K1 B:exi_core_edge.dat is the core edge result for the boron with the missing 1s electron. The spaces in the file name can be a bit awkward so let's rename it to cbn_BExi.dat . Let's plot it the same as we have before We can see the resemblance to the database spectrum. Comparison to Experiment To get a good comparison to experiment, we will plot the results from the database and our calculation together on the same graph. You may already notice that, though the shape is similar, the x and y-axis values are very different. The y-axis corresponds to intensity (while in our calculation it is more akin to a probability), so we will scale that by just multiplying by a flat value. The x-axis needs to be adjusted by simply adding a fixed value. We can adjust our results with a simple Python script. with open ( 'cbn_BExi.dat' , 'r' ) as infile , open ( 'cbn_BExi_ss.dat' , 'w' ) as outfile : for line in infile : columns = line . split () col1 = float ( columns [ 0 ]) + 180 col2 = float ( columns [ 2 ]) * 1000000 outfile . write ( f \" { col1 } { col2 } \\n \" ) Now let's plot our Castep and the experimental results together by xmgrace with the batch file READ BLOCK \"cbn_BExi_ss.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Castep\" READ BLOCK \"Dspec.60967.1.msa\" BLOCK XY \"1:2\" S1 LEGEND \"EELS Database\" The output should look like this: They are reasonably similar, but the Optados calculation retains the problem of dropping off faster towards higher energies.","title":"Coreloss"},{"location":"tutorials/Coreloss/Coreloss/#coreloss","text":"","title":"Coreloss"},{"location":"tutorials/Coreloss/Coreloss/#calculation-of-core-loss-spectra-for-cbn","text":"Core-loss calculations effectively calculate the probability of an electron being excited from a core state into the conduction band. This is useful for calculating the core-loss (ionisation edge) peaks - by performing these calculations, you can get a simulation of what you would see in an experimental EELS or XANES spectrum. In this tutorial, we will look at the results of such a calculation on cubic boron nitride (cBN), looking at the boron K-edge. In the end, we will compare it to the spectrum in the EELS Database . We will use the cell file cbn.cell %block lattice_abc 2.5 2.5 2.5 60 60 60 %endblock lattice_abc %block positions_frac B 0.00 0.00 0.00 N 0.25 0.25 0.25 %endblock positions_frac kpoints_mp_grid 10 10 10 spectral_kpoint_mp_grid 12 12 12 with the param file cbn.param task: spectral spectral_task: coreloss xc_functional: LDA opt_strategy: speed Note that a larger number of spectral k-point than standard one is usually required, and, to test if it is converged, you'd have to look at the whole spectrum (rather than examining a single value/result as in some other convergence tests). It is also important that you do not have SYMMETRY_GENERATE on for coreloss calculations. After running Castep, run Optados with the Optados input file cbn.odi TASK : core DOS_SPACING : 0.01 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default CORE_GEOM : polycrystalline # Default CORE_LAI_BROADENING : false # Default true LAI_GAUSSIAN_WIDTH : 1.0 The line TASK : core is what determines that a core-loss calculation will be performed. CORE_GEOM : polycrystalline could also be replaced by core_geom : polarized , in which case you'd also have to add a line specifying the direction - for example, CORE_QDIR : 1 1 1 would simulate the results of an electron (or X-ray) beam going through a single crystal in the [1 1 1] direction. In this tutorial, we will be looking at the polycrystalline case, where it effectively uses the average of all directions. Running Optados should generate 2 files of interest: cbn_B1K1_core_edge.dat and cbn_N1K1_core_edge.dat - these are the results of the core-loss calculations. We will focus on the first dat file - let's look at the boron part specifically. The file starts off like -15.720790912312673 0.0000000000000000 -15.710790160394351 0.0000000000000000 -15.700789408476030 0.0000000000000000 The 1 st column is the energy and the 2 nd is the (smeared) core-loss for that energy. Let's try plotting the dat file with xmgrace - the graph should look like Let's now add some experimental broadening to the results, in order to more accurately simulate experiment. You can do so by re-running Optados (no need to re-run Castep) with CORE_LAI_BROADENING set to true and the lines LAI_GAUSSIAN_WIDTH : 1.8 LAI_LORENTZIAN_WIDTH : 0.1 LAI_LORENTZIAN_SCALE : 0.1 added to the odi file. Gaussian broadening is to simulate the instrument used, and is the same for the whole spectrum, while Lorentzian is to simulate the lifetime effects of the experiment, and is energy-dependent. A Gaussian width of 1.8 is used because we are going to compare it to the spectrum in the EELS Database , and that experiment had a resolution of 1.8eV. A Lorentzian can be used to account for the energy broadening due to the lifetime of the initial and final states. The width depends on the element and edge you are examining, and the value used is recommended here (boron is not there, but 0.1 is recommended for carbon, which is close). A Lorentzian scale of 0.1 is a general and commonly-used value. Re-running it now yields 3 columns in the dat file - it now starts like -15.720790912312673 0.0000000000000000 4.6792920824784473E-005 -15.710790160394351 0.0000000000000000 4.7285842629847867E-005 The 1 st and 2 nd columns are the same, and the 3 rd column is the lifetime and instrumentation (LAI) broadened core-loss results. To plot this with xmgrace, it is easiest to run xmgrace -batch plot.bat on the batch file plot.bat READ BLOCK \"cbn_B1K1_core_edge.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Unbroadened\" BLOCK XY \"1:3\" S1 LEGEND \"Broadened\" WORLD XMIN 0 This gives the graph below","title":"Calculation of core-loss spectra for cBN"},{"location":"tutorials/Coreloss/Coreloss/#including-a-core-hole","text":"The above was effectively calculating the probability of an electron being able to be excited into the conduction band, corresponding to that same energy being lost from an X-ray/electron and thus XANES/EELs data. However, when calculating that, it was not accounting for the fact that there'd be a core-hole as a result (which naturally will affect energy, DOS and thus probability of occurring): that must be factored in for more realistic results. This is done rather simply by specifying the missing electron when describing the potential in the cell file. If you look at the cbn.castep file generated earlier, you may see that the pseudopotential report contains the line \"2|1.2|12|14|16|20:21(qc=8)\" This tells us what kind of pseudopotential is used for the boron. To specify that there is a 1s electron missing, all you have to do is add {1s1.00} at the end: with only 1 electron in the 1s shell, there is a core electron missing: a core hole. Go into cbn.cell , and add the lines %block species_pot B 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot to calculate the core edge data factoring in the missing 1s electron. Note Your potential may be different, depending on your version of Castep etc. - but don't worry, as the procedure is the same. Also add the line CHARGE : +1 to the cbn.param file - this must be done to maintain charge neutrality. Next, re-run Castep. Let's have a quick look at the pseudopotential report of boron in cbn.castep ============================================================ | Pseudopotential Report - Date of generation 29-07-2024 | ------------------------------------------------------------ | Element: B Ionic charge: 4.00 Level of theory: LDA | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.865 | | 2p 1.000 -0.654 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.865 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.654 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8){1s1.00}\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ You should notice that the energies in the 2s and 2p orbitals are lower, the beta values are all different, and, most importantly, that the pseudopotential used is the one we manually wrote in: the one with only 1 electron in the 1s shell. Now, re-run Optados. This create the same files as before. Again, let's focus on the boron result. The output file cbn_B1K1_core_edge.dat now starts like: -16.879627404257498 0.0000000000000000 4.3418325679994708E-005 -16.869627177952179 0.0000000000000000 4.3433042280034070E-005 The columns represent the same information as before. Plotting it with the same batch file yields us this graph:","title":"Including a core-hole"},{"location":"tutorials/Coreloss/Coreloss/#supercell","text":"The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. To do this, we will create a 2x2x2 supercell - the larger the supercell the better the simulation (as this reduces the core-hole interaction effect more), but the calculation time also shoots up significantly. There are multiple ways of doing this, but this tutorial will cover how it can be done using Vesta . First, upload the cell file we used to Vesta. From the top of the toolbar, go into Edit -> Edit Data -> Unit cell... . This should open up the window below Click Transform... . This opens up a new window To create the 2x2x2 supercell, the transformation matrix is rather simple: make the diagonal values 2 like in the figure above (so it becomes 2x larger in all directions) and click Ok . Select Search atoms in the new unit-cell and add them as new sites in the next pop-up window. Now that the supercell has been generated, we must save it and turn it into a cell file. Click File -> Export Data and save it as cbn.cif file (saving it as a cell file is not an option). We can use cif2cell cbn.cif to get information on how to make the new cell. In the end, we change cbn.cell to: cbn.cell %block lattice_abc 5 5 5 60 60 60 %endblock lattice_abc %block positions_frac B:exi 0.0000000 0.0000000 0.0000000 B 0.0000000 0.0000000 0.5000000 B 0.0000000 0.5000000 0.0000000 B 0.0000000 0.5000000 0.5000000 B 0.5000000 0.0000000 0.0000000 B 0.5000000 0.0000000 0.5000000 B 0.5000000 0.5000000 0.0000000 B 0.5000000 0.5000000 0.5000000 N 0.1250000 0.1250000 0.1250000 N 0.1250000 0.1250000 0.6250000 N 0.1250000 0.6250000 0.1250000 N 0.1250000 0.6250000 0.6250000 N 0.6250000 0.1250000 0.1250000 N 0.6250000 0.1250000 0.6250000 N 0.6250000 0.6250000 0.1250000 N 0.6250000 0.6250000 0.6250000 %endblock positions_frac kpoints_mp_grid 5 5 5 %block species_pot B:exi 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot spectral_kpoint_mp_grid 6 6 6 With double the size of the supercell, you may also halve the kpoints: this allows it to be calculated faster without losing accuracy. However, it will still take significantly longer to calculate. Specifying 1 of the boron atoms to be called B:exi and making changing the potential block to only affect that means that we simulate only 1 of the boron atoms losing that electron - by doing this we prevent the interaction problem mentioned above. In the param file, also add the line NEXTRA_BANDS : 100 This makes Castep perform the calculation for higher-energy bands, and is necessary to prevent too sudden of a drop in the core-loss values towards the higher energies (you may notice that in the above figures the value drops towards 0 after the peaks, but tends towards a finite non-zero value in experiment). Re-run Castep and Optados. There will now be 16 output files, rather than just 2 - there is a core edge output for every atom - cbn_ B 1 K1 B:exi_core_edge.dat is the core edge result for the boron with the missing 1s electron. The spaces in the file name can be a bit awkward so let's rename it to cbn_BExi.dat . Let's plot it the same as we have before We can see the resemblance to the database spectrum.","title":"Supercell"},{"location":"tutorials/Coreloss/Coreloss/#comparison-to-experiment","text":"To get a good comparison to experiment, we will plot the results from the database and our calculation together on the same graph. You may already notice that, though the shape is similar, the x and y-axis values are very different. The y-axis corresponds to intensity (while in our calculation it is more akin to a probability), so we will scale that by just multiplying by a flat value. The x-axis needs to be adjusted by simply adding a fixed value. We can adjust our results with a simple Python script. with open ( 'cbn_BExi.dat' , 'r' ) as infile , open ( 'cbn_BExi_ss.dat' , 'w' ) as outfile : for line in infile : columns = line . split () col1 = float ( columns [ 0 ]) + 180 col2 = float ( columns [ 2 ]) * 1000000 outfile . write ( f \" { col1 } { col2 } \\n \" ) Now let's plot our Castep and the experimental results together by xmgrace with the batch file READ BLOCK \"cbn_BExi_ss.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Castep\" READ BLOCK \"Dspec.60967.1.msa\" BLOCK XY \"1:2\" S1 LEGEND \"EELS Database\" The output should look like this: They are reasonably similar, but the Optados calculation retains the problem of dropping off faster towards higher energies.","title":"Comparison to Experiment"},{"location":"tutorials/Delta_SCF/lin_ex_delta_scf/","text":"Electronic excitations of NO on Ni(001) ATTENTION: These calculations are done using standard on-the-fly pseudopotentials from CASTEP-6.0.1 For this example we calculate a charge neutral HOMO->LUMO excitation and a charge transfer excitation between a nickel substrate and a NO molecule In the following, the required input files are: no-on-ni001.param, no-on-ni001.cell, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param #reuse: default calculate_deltascf : true deltascf_method : linear expansion deltascf_checkpoint : gasphase.check #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay mix_history_length : 7 nextra_bands : 50 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.15 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE The workflow is as follows: Calculate reference states (gasphase.check). These can be ground state Kohn-Sham states or themselves excited KS states Calculate the ground state of NO on Ni(001) Final energy, E = -7867.950085034 eV Calculate the leDeltaSCF excitation We calculate a charge transfer from the molecule to the surface by removing an electron from the HOMO in the majority spin channel #band occ spin %block deltascf_constraints 5 0.0000 1 %endblock deltascf_constraints WARNING A sufficient number of virtual states in the calculation, controlled by the keyword nextra_states, is very important. The more virtual states are used explicitly, the more complete is the projection onto the space of KS states. Sometimes states are almost degenerate and we also need to constrain the occupation of the other state to ensure that the population doesn\\'t just switch between the two. In some cases, convergence can be very slow and a large number of SCF steps is necessary. The resulting excitation energy is 0.46 eV. Final energy, E = -7867.487338823 eV We can calculate an intramolecular triplet excitation from HOMO to LUMO with the following constraint sequence in \\.deltascf. This excites 1 electron from the HOMO in the majority spin channel to the LUMO in the minority spin channel. #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints The resulting excitation energy is 9.17 eV. Final energy, E = -7858.779610351 eV","title":"Linear expansion DeltaSCF"},{"location":"tutorials/Delta_SCF/lin_ex_delta_scf/#electronic-excitations-of-no-on-ni001","text":"ATTENTION: These calculations are done using standard on-the-fly pseudopotentials from CASTEP-6.0.1 For this example we calculate a charge neutral HOMO->LUMO excitation and a charge transfer excitation between a nickel substrate and a NO molecule In the following, the required input files are: no-on-ni001.param, no-on-ni001.cell, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param #reuse: default calculate_deltascf : true deltascf_method : linear expansion deltascf_checkpoint : gasphase.check #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay mix_history_length : 7 nextra_bands : 50 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.15 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE The workflow is as follows: Calculate reference states (gasphase.check). These can be ground state Kohn-Sham states or themselves excited KS states Calculate the ground state of NO on Ni(001) Final energy, E = -7867.950085034 eV Calculate the leDeltaSCF excitation We calculate a charge transfer from the molecule to the surface by removing an electron from the HOMO in the majority spin channel #band occ spin %block deltascf_constraints 5 0.0000 1 %endblock deltascf_constraints WARNING A sufficient number of virtual states in the calculation, controlled by the keyword nextra_states, is very important. The more virtual states are used explicitly, the more complete is the projection onto the space of KS states. Sometimes states are almost degenerate and we also need to constrain the occupation of the other state to ensure that the population doesn\\'t just switch between the two. In some cases, convergence can be very slow and a large number of SCF steps is necessary. The resulting excitation energy is 0.46 eV. Final energy, E = -7867.487338823 eV We can calculate an intramolecular triplet excitation from HOMO to LUMO with the following constraint sequence in \\.deltascf. This excites 1 electron from the HOMO in the majority spin channel to the LUMO in the minority spin channel. #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints The resulting excitation energy is 9.17 eV. Final energy, E = -7858.779610351 eV","title":"Electronic excitations of NO on Ni(001)"},{"location":"tutorials/Delta_SCF/molpdos/","text":"NO molecule on Ni(001) For this example we calculate the projected MOs of a NO molecule on a Ni(001) slab. In the following the required input files are: no-on-ni001.param, no-on-ni001.cell, no-on-ni001.molpdos, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param calculate_modos : true deltascf_checkpoint : gasphase task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 no-on-ni001.molpdos molpdos_state : 4 1 molpdos_state : 5 1 molpdos_state : 6 1 molpdos_state : 4 2 molpdos_state : 5 2 molpdos_state : 6 2 molpdos_bin_width : 0.01 molpdos_smearing : 0.10 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE After generating gasphase.check by running CASTEP on the gasphase.param and gasphase.cell files, we execute CASTEP and post-process with MolPDOS. This will write x-y data files for the Total DOS, the separate spin channels, and the MolPDOS peaks. The following image shows the Total DOS and the two spin channels. The next picture shows the frontier orbitals of spin channel 1 projected on the total DOS. Especially the LUMO shows strong hybridization with the Nickel d-bands and also is partially occupied. The left scale refers to the total DOS, whereas the right y-scale shows the peak height of the projected MOs. GOOD TO KNOW If you ever forget the correct input for .molpdos, just run the MolPDOS tool without seed. The printed information is all you need!","title":"Molecular Projected DOS"},{"location":"tutorials/Delta_SCF/molpdos/#no-molecule-on-ni001","text":"For this example we calculate the projected MOs of a NO molecule on a Ni(001) slab. In the following the required input files are: no-on-ni001.param, no-on-ni001.cell, no-on-ni001.molpdos, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param calculate_modos : true deltascf_checkpoint : gasphase task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 no-on-ni001.molpdos molpdos_state : 4 1 molpdos_state : 5 1 molpdos_state : 6 1 molpdos_state : 4 2 molpdos_state : 5 2 molpdos_state : 6 2 molpdos_bin_width : 0.01 molpdos_smearing : 0.10 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE After generating gasphase.check by running CASTEP on the gasphase.param and gasphase.cell files, we execute CASTEP and post-process with MolPDOS. This will write x-y data files for the Total DOS, the separate spin channels, and the MolPDOS peaks. The following image shows the Total DOS and the two spin channels. The next picture shows the frontier orbitals of spin channel 1 projected on the total DOS. Especially the LUMO shows strong hybridization with the Nickel d-bands and also is partially occupied. The left scale refers to the total DOS, whereas the right y-scale shows the peak height of the projected MOs. GOOD TO KNOW If you ever forget the correct input for .molpdos, just run the MolPDOS tool without seed. The printed information is all you need!","title":"NO molecule on Ni(001)"},{"location":"tutorials/Delta_SCF/simple_delta_scf/","text":"Electronic excitations of the Azobenzene molecule In this example we calculate the first two electronic excited states of E-Azobenzene in a supercell. The required files are azo.cell and azo.param: azo.param task: SinglePoint reuse: default calculate_deltascf : true deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints spin_polarized : False cut_off_energy : 350.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : PBE azo.cell %BLOCK LATTICE_CART 10.0000000 0.0000000000 0.0000000000 0.0000000000 20.0000000 0.0000000000 0.0000000000 0.0000000000 10.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS C -6.72081 -1.66625 0.00000 C -6.64967 -0.26964 0.00000 C -5.40647 0.36858 -0.00000 C -4.23175 -0.38857 -0.00000 C -4.29745 -1.78579 -0.00000 C -5.54882 -2.43430 -0.00000 H -7.68820 -2.15296 0.00000 H -7.55879 0.31772 0.00000 H -5.35348 1.44963 -0.00000 H -3.26966 0.10734 -0.00000 H -3.37789 -2.35693 -0.00000 N -5.65342 -3.85046 -0.00000 N -4.64259 -4.58194 -0.00000 C -4.75058 -5.99808 -0.00000 C -6.00434 -6.64214 -0.00000 C -6.07567 -8.03881 -0.00000 C -4.90409 -8.80053 -0.00000 C -3.65828 -8.16721 -0.00000 C -3.58139 -6.77065 -0.00000 H -2.61200 -6.28795 -0.00000 H -6.92178 -6.06761 -0.00000 H -7.03986 -8.53061 -0.00000 H -4.96168 -9.88134 -0.00000 H -2.75170 -8.75849 -0.00000 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 1 1 1 We start by calculating the total DFT ground state energy as Final energy, E = -2597.665647686 eV Now we reuse the calculated wavefunctions and switch to the DeltaSCF calculation (param file above) There are 68 valence electrons. Therefore, for this non-spin-polarized system the HOMO orbital is orbital no. 34. The LUMO is orbital no. 35. The first two excited states of azobenzene are known to be S1(n->pi*) and S2(pi->pi*) transitions between the HOMO and LUMO and the HOMO-1 and the LUMO. The corresponding constraint sequence in azo.deltascf for the S1 excitation is #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints WARNING When running non-spin-polarized calculations, orbital occupations range from 0 to 1. !!When running a spin-polarized calculation, they also range from 0 to 1, although they contain 0 to 2 electrons. In this (non-spin-polarized) case, if we want to transfer an electron from the HOMO(34) to LUMO(35) we need to enforce the occupation of both to be 0.50. Feel free to increase the print level with iprint to study the output in more detail. The corresponding total energy is Final energy, E = -2595.702720896 eV This corresponds to an S1 excitation energy of 1.96 eV. The constraint sequence for an S2 excitation is #band occ spin from_band to_band %block deltascf_constraints 33 0.5000 1 33 33 35 0.5000 1 35 35 %endblock deltascf_constraints The resulting final energy is Final energy, E = -2594.762182241 eV The corresponding S2 excitation energy is 2.90 eV.","title":"Simple Delta SCF"},{"location":"tutorials/Delta_SCF/simple_delta_scf/#electronic-excitations-of-the-azobenzene-molecule","text":"In this example we calculate the first two electronic excited states of E-Azobenzene in a supercell. The required files are azo.cell and azo.param: azo.param task: SinglePoint reuse: default calculate_deltascf : true deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints spin_polarized : False cut_off_energy : 350.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : PBE azo.cell %BLOCK LATTICE_CART 10.0000000 0.0000000000 0.0000000000 0.0000000000 20.0000000 0.0000000000 0.0000000000 0.0000000000 10.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS C -6.72081 -1.66625 0.00000 C -6.64967 -0.26964 0.00000 C -5.40647 0.36858 -0.00000 C -4.23175 -0.38857 -0.00000 C -4.29745 -1.78579 -0.00000 C -5.54882 -2.43430 -0.00000 H -7.68820 -2.15296 0.00000 H -7.55879 0.31772 0.00000 H -5.35348 1.44963 -0.00000 H -3.26966 0.10734 -0.00000 H -3.37789 -2.35693 -0.00000 N -5.65342 -3.85046 -0.00000 N -4.64259 -4.58194 -0.00000 C -4.75058 -5.99808 -0.00000 C -6.00434 -6.64214 -0.00000 C -6.07567 -8.03881 -0.00000 C -4.90409 -8.80053 -0.00000 C -3.65828 -8.16721 -0.00000 C -3.58139 -6.77065 -0.00000 H -2.61200 -6.28795 -0.00000 H -6.92178 -6.06761 -0.00000 H -7.03986 -8.53061 -0.00000 H -4.96168 -9.88134 -0.00000 H -2.75170 -8.75849 -0.00000 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 1 1 1 We start by calculating the total DFT ground state energy as Final energy, E = -2597.665647686 eV Now we reuse the calculated wavefunctions and switch to the DeltaSCF calculation (param file above) There are 68 valence electrons. Therefore, for this non-spin-polarized system the HOMO orbital is orbital no. 34. The LUMO is orbital no. 35. The first two excited states of azobenzene are known to be S1(n->pi*) and S2(pi->pi*) transitions between the HOMO and LUMO and the HOMO-1 and the LUMO. The corresponding constraint sequence in azo.deltascf for the S1 excitation is #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints WARNING When running non-spin-polarized calculations, orbital occupations range from 0 to 1. !!When running a spin-polarized calculation, they also range from 0 to 1, although they contain 0 to 2 electrons. In this (non-spin-polarized) case, if we want to transfer an electron from the HOMO(34) to LUMO(35) we need to enforce the occupation of both to be 0.50. Feel free to increase the print level with iprint to study the output in more detail. The corresponding total energy is Final energy, E = -2595.702720896 eV This corresponds to an S1 excitation energy of 1.96 eV. The constraint sequence for an S2 excitation is #band occ spin from_band to_band %block deltascf_constraints 33 0.5000 1 33 33 35 0.5000 1 35 35 %endblock deltascf_constraints The resulting final energy is Final energy, E = -2594.762182241 eV The corresponding S2 excitation energy is 2.90 eV.","title":"Electronic excitations of the Azobenzene molecule"},{"location":"tutorials/GA/Introduction/","text":"Introduction In this tutorial we will look at exactly what castep GA is doing when it is used, examining what the input files do what the output files tell us. We will go through a silicon example to do so - starting from a heavily distorted diamond cell and ending in a diamond structure. Input Files We will use the cell file Si.cell %block LATTICE_ABC ang 5.4 5.4 5.4 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.2 0.01 0.04 Si 0.21 0.29 0.30 Si 0.59 0.43 0.03 Si 0.9 0.81 0.30 Si 0.53 0.03 0.58 Si 0.72 0.21 0.79 Si 0.04 0.45 0.4 Si 0.28 0.85 0.69 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang Note that this is just a heavily distorted version of a ideal diamond silicon cell - LATTICE_ABC defines its cubic structure with the lattice parameter that is expected, while the fractional positions of all the Si's are slightly moved from where they'd be expected for diamond - for example the first line Si 0.2 0.01 0.04 is only a bit off from where it'd be in a perfect diamond, which is Si 0 0 0 In a normal castep GA run the positions of all the Si's, and even the starting unit cell, is completely arbitrary, and in most cases it should have little impact on the run. However, in this case we are trying to get it to get to diamond quickly, so that it is easier to analyse what is going on. For the param file we will use task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 6 # Max number of generations to run for ga_mutate_amp = 0.05 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.1 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 129189 # Random seed for replicability # continuation = Si.xyz ################################################################# # CASTEP Geomtery Optimisation Parameters # # These will be used for each cells geom opt/fitenss evaluation # ################################################################# comment = Si_Convex_hull #rand_seed = 100003 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=11 RSC=T RSN=1 CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code There is a lot more to discuss here. For more information on all the key words look at the documentation (ADD LINK LATER). However, let's look at the key information here: ga_max_gens defines the number of generations it will run for. 6 is a very low amount, but it does the job here ga_mutate_amp describes how severe the mutations are. Again, this is using a low number because we're starting not too far off the final result ga_mutate_rate tells you the probability of different parts of the cell mutating - 0.1 is a fairly ordinary value to use A key line for this tutorial is rand_seed = 129189 This means that you may be able to replicate similar results, though that isn't guranteed [[CHECK IF EVEN TRUE]] Running We can now run castep GA on the Si. This should take about 3 minutes to run, but look at what is happening as it is running - you can use tail -f Si.castep to keep track of how the castep output file is being generated. Also, refresh your directory regularly to see what's being generated. The first files to be generated will have the same format as Si.gen_000_mem_001.cell and Si.gen_000_mem_001.param - this is the 1 st member of the 0 th generation, which is generated randomly using the Si.cell as well as the mutation values specified in the Si.param file Note I will refer to future files as being .file_ending in the interest of brevity, specifying details where necessary You should get a total of 12 members like that, up to mem_012 . As it's running, the 0 th generation will start to get .geom and -out.cell outputs for each member. These are obtained as fast geometry optimisations (ADD LINK) are performed on the randomly generated cells. After the last member finishes its geometry optimisation, the next generation is generated: you'll get .cell and .param files. This is the point where the castep output file gets interesting. You have a table that starts like GA: gen # 1 parent # 1 enthalpy = -3.940733E+000 eV/atom un-scaled fitness = 0.684242 conv = T member error = F seed = Si.gen_000_mem_001 vol/ion = 19.4307 A**3/atom GA: gen # 1 parent # 2 enthalpy = -4.070795E+000 eV/atom un-scaled fitness = 0.791433 conv = T member error = F seed = Si.gen_000_mem_002 vol/ion = 20.4806 A**3/atom and ends with GA: gen # 1 child # 11 enthalpy = -4.200422E+000 eV/atom un-scaled fitness = 0.868980 conv = T member error = F seed = Si.gen_001_mem_011 vol/ion = 20.7893 A**3/atom GA: gen # 1 child # 12 enthalpy = -3.296903E+000 eV/atom un-scaled fitness = 0.119203 conv = T member error = F seed = Si.gen_001_mem_012 vol/ion = 28.3264 A**3/atom The parent rows all using generation 0 members as the seed, and giving them an un-scaled fitness . What this means is that all the geometry-optimised cells from generation 0 have their enthalpy and similarity checked - the lower the enthalpy the fitter it is considered, as that is desirable to get the best structure. However, a structure that is similar to another parent will be penalised to encourage diversity. Those parents then breed together to form the children, which are then mutated and geometry optimised like before. The probability of a parent breeding is based on its fitness evaluation - in the example above, parent 2 is more likely to breed than parent 1 (ADD LINK TO ROULETTE RANDOMNESS) You may find the ancestry of each individual child by looking for parts of the castep file such as GA: Member filename Si.gen_002_mem_011 GA: Parent 1 generation 0 and member 9 GA: Parent 2 generation 1 and member 9 Here you see that generation 2 member 11 was made by using the parents generation 0 member 9 and generation 1 member 9. After the children are generated and geometry optimised, they are treated exactly the same as the parents and every member has their fitness (re)evaluated - the enthalpy is already calculated but similarities must be penalised. This leads to a very similar table labelled GA: updated fitnesses with weighted fitness function For generation 2 the table starts with GA: gen # 2 parent # 1 enthalpy = -4.225502E+000 eV/atom un-scaled fitness = 0.866683 conv = T member error = F seed = Si.gen_001_mem_006 vol/ion = 19.0994 A**3/atom GA: gen # 2 parent # 2 enthalpy = -4.200403E+000 eV/atom un-scaled fitness = 0.839781 conv = T member error = F seed = Si.gen_000_mem_009 vol/ion = 20.7940 A**3/atom Here you'll notice that there are parents from both generation 0 (2 nd line) and generation (1 st ) - based on their fitness, 12 got eliminated while the other 12 stayed to become parents in the next generation. The same exact procedure repeats - parents breed (with fitter ones doing moreso), children mutate and optimise, the parents and children are compared together as equal members and the best ones move on to become parents of the next generation. This is done until generation 6. The best structure Finding the best structure found is fairly simple - if using Linux you may use the command grep 'child' Si.castep | sort -k10,10n | head -20 In my case I got generation 6 member 7 to be the lowest enthalpy. Running c2x --int -e=0.1-0.0001 Si.gen_006_mem_007-out.cell tells me that it is Fd-3m - diamond (though the lower tolerance structure is R-3m - this was a very short run so it hasn't got the perfect structure still, but it is close). The 'family tree' of that cell looks like this: Let's go through the steps above to see what happened in this specific case - The 0 th generation was randomly generated. In this case, members 2, 5, 9, 10 and 12 ended up being ancestors of the final structure Members 2 and 5 bred to generate 1,4 (which mutated). The same happened for member 9 Generation 2 member 11 was created using 0, 9 and 1,9. This means that out of the 24 potential parents from generation 1 (12 parents and 12 children generated from said parents), both of them were fit enough to become parents for generation 2. Generation 3 member 4 was created by breeding 2,11 and 1,4. This means that 1,4 survived the fitness tests of generations 1 (where it was made as a child) and 2, where it competed with other parents and their children alike. In generations 4, 5 and 6, no ancestors were generated. Looking forward, that means that 1,4 and 2,11 either didn't breed at all (the parent combinations are ROULETTE RANDOM) or whatever child they made didn't have a mutation favourable enough to be the lowest enthalpy structure. Finally, in generation 6, 3,4 bred with 2,11 (its own parent - again after the children are generated they are all treated as equal parent candidates) to generate 6,7. Please note that in actual runs the family tree will most likely be significantly more complicated - as noted before, both cell and param files were geared towards getting a good structure in few generations and modest mutations. Even with such files it is highly chance-based whether you will get such a result. This was just a simple demonstration.","title":"Introduction"},{"location":"tutorials/GA/Introduction/#introduction","text":"In this tutorial we will look at exactly what castep GA is doing when it is used, examining what the input files do what the output files tell us. We will go through a silicon example to do so - starting from a heavily distorted diamond cell and ending in a diamond structure.","title":"Introduction"},{"location":"tutorials/GA/Introduction/#input-files","text":"We will use the cell file Si.cell %block LATTICE_ABC ang 5.4 5.4 5.4 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.2 0.01 0.04 Si 0.21 0.29 0.30 Si 0.59 0.43 0.03 Si 0.9 0.81 0.30 Si 0.53 0.03 0.58 Si 0.72 0.21 0.79 Si 0.04 0.45 0.4 Si 0.28 0.85 0.69 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang Note that this is just a heavily distorted version of a ideal diamond silicon cell - LATTICE_ABC defines its cubic structure with the lattice parameter that is expected, while the fractional positions of all the Si's are slightly moved from where they'd be expected for diamond - for example the first line Si 0.2 0.01 0.04 is only a bit off from where it'd be in a perfect diamond, which is Si 0 0 0 In a normal castep GA run the positions of all the Si's, and even the starting unit cell, is completely arbitrary, and in most cases it should have little impact on the run. However, in this case we are trying to get it to get to diamond quickly, so that it is easier to analyse what is going on. For the param file we will use task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 6 # Max number of generations to run for ga_mutate_amp = 0.05 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.1 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 129189 # Random seed for replicability # continuation = Si.xyz ################################################################# # CASTEP Geomtery Optimisation Parameters # # These will be used for each cells geom opt/fitenss evaluation # ################################################################# comment = Si_Convex_hull #rand_seed = 100003 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=11 RSC=T RSN=1 CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code There is a lot more to discuss here. For more information on all the key words look at the documentation (ADD LINK LATER). However, let's look at the key information here: ga_max_gens defines the number of generations it will run for. 6 is a very low amount, but it does the job here ga_mutate_amp describes how severe the mutations are. Again, this is using a low number because we're starting not too far off the final result ga_mutate_rate tells you the probability of different parts of the cell mutating - 0.1 is a fairly ordinary value to use A key line for this tutorial is rand_seed = 129189 This means that you may be able to replicate similar results, though that isn't guranteed [[CHECK IF EVEN TRUE]]","title":"Input Files"},{"location":"tutorials/GA/Introduction/#running","text":"We can now run castep GA on the Si. This should take about 3 minutes to run, but look at what is happening as it is running - you can use tail -f Si.castep to keep track of how the castep output file is being generated. Also, refresh your directory regularly to see what's being generated. The first files to be generated will have the same format as Si.gen_000_mem_001.cell and Si.gen_000_mem_001.param - this is the 1 st member of the 0 th generation, which is generated randomly using the Si.cell as well as the mutation values specified in the Si.param file Note I will refer to future files as being .file_ending in the interest of brevity, specifying details where necessary You should get a total of 12 members like that, up to mem_012 . As it's running, the 0 th generation will start to get .geom and -out.cell outputs for each member. These are obtained as fast geometry optimisations (ADD LINK) are performed on the randomly generated cells. After the last member finishes its geometry optimisation, the next generation is generated: you'll get .cell and .param files. This is the point where the castep output file gets interesting. You have a table that starts like GA: gen # 1 parent # 1 enthalpy = -3.940733E+000 eV/atom un-scaled fitness = 0.684242 conv = T member error = F seed = Si.gen_000_mem_001 vol/ion = 19.4307 A**3/atom GA: gen # 1 parent # 2 enthalpy = -4.070795E+000 eV/atom un-scaled fitness = 0.791433 conv = T member error = F seed = Si.gen_000_mem_002 vol/ion = 20.4806 A**3/atom and ends with GA: gen # 1 child # 11 enthalpy = -4.200422E+000 eV/atom un-scaled fitness = 0.868980 conv = T member error = F seed = Si.gen_001_mem_011 vol/ion = 20.7893 A**3/atom GA: gen # 1 child # 12 enthalpy = -3.296903E+000 eV/atom un-scaled fitness = 0.119203 conv = T member error = F seed = Si.gen_001_mem_012 vol/ion = 28.3264 A**3/atom The parent rows all using generation 0 members as the seed, and giving them an un-scaled fitness . What this means is that all the geometry-optimised cells from generation 0 have their enthalpy and similarity checked - the lower the enthalpy the fitter it is considered, as that is desirable to get the best structure. However, a structure that is similar to another parent will be penalised to encourage diversity. Those parents then breed together to form the children, which are then mutated and geometry optimised like before. The probability of a parent breeding is based on its fitness evaluation - in the example above, parent 2 is more likely to breed than parent 1 (ADD LINK TO ROULETTE RANDOMNESS) You may find the ancestry of each individual child by looking for parts of the castep file such as GA: Member filename Si.gen_002_mem_011 GA: Parent 1 generation 0 and member 9 GA: Parent 2 generation 1 and member 9 Here you see that generation 2 member 11 was made by using the parents generation 0 member 9 and generation 1 member 9. After the children are generated and geometry optimised, they are treated exactly the same as the parents and every member has their fitness (re)evaluated - the enthalpy is already calculated but similarities must be penalised. This leads to a very similar table labelled GA: updated fitnesses with weighted fitness function For generation 2 the table starts with GA: gen # 2 parent # 1 enthalpy = -4.225502E+000 eV/atom un-scaled fitness = 0.866683 conv = T member error = F seed = Si.gen_001_mem_006 vol/ion = 19.0994 A**3/atom GA: gen # 2 parent # 2 enthalpy = -4.200403E+000 eV/atom un-scaled fitness = 0.839781 conv = T member error = F seed = Si.gen_000_mem_009 vol/ion = 20.7940 A**3/atom Here you'll notice that there are parents from both generation 0 (2 nd line) and generation (1 st ) - based on their fitness, 12 got eliminated while the other 12 stayed to become parents in the next generation. The same exact procedure repeats - parents breed (with fitter ones doing moreso), children mutate and optimise, the parents and children are compared together as equal members and the best ones move on to become parents of the next generation. This is done until generation 6.","title":"Running"},{"location":"tutorials/GA/Introduction/#the-best-structure","text":"Finding the best structure found is fairly simple - if using Linux you may use the command grep 'child' Si.castep | sort -k10,10n | head -20 In my case I got generation 6 member 7 to be the lowest enthalpy. Running c2x --int -e=0.1-0.0001 Si.gen_006_mem_007-out.cell tells me that it is Fd-3m - diamond (though the lower tolerance structure is R-3m - this was a very short run so it hasn't got the perfect structure still, but it is close). The 'family tree' of that cell looks like this: Let's go through the steps above to see what happened in this specific case - The 0 th generation was randomly generated. In this case, members 2, 5, 9, 10 and 12 ended up being ancestors of the final structure Members 2 and 5 bred to generate 1,4 (which mutated). The same happened for member 9 Generation 2 member 11 was created using 0, 9 and 1,9. This means that out of the 24 potential parents from generation 1 (12 parents and 12 children generated from said parents), both of them were fit enough to become parents for generation 2. Generation 3 member 4 was created by breeding 2,11 and 1,4. This means that 1,4 survived the fitness tests of generations 1 (where it was made as a child) and 2, where it competed with other parents and their children alike. In generations 4, 5 and 6, no ancestors were generated. Looking forward, that means that 1,4 and 2,11 either didn't breed at all (the parent combinations are ROULETTE RANDOM) or whatever child they made didn't have a mutation favourable enough to be the lowest enthalpy structure. Finally, in generation 6, 3,4 bred with 2,11 (its own parent - again after the children are generated they are all treated as equal parent candidates) to generate 6,7. Please note that in actual runs the family tree will most likely be significantly more complicated - as noted before, both cell and param files were geared towards getting a good structure in few generations and modest mutations. Even with such files it is highly chance-based whether you will get such a result. This was just a simple demonstration.","title":"The best structure"},{"location":"tutorials/GA/Silicon/","text":"Castep GA for silicon Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA! Input Files We will use the cell file Si.cell %block LATTICE_ABC ang 3.8 3.8 3.8 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.203 0.617 0.209 Si 0.844 0.442 0.350 Si 0.964 0.379 0.096 Si 0.762 0.524 0.941 Si 0.544 0.605 0.781 Si 0.238 0.597 0.531 Si 0.728 0.914 0.742 Si 0.209 0.929 0.435 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang The definition of the lattice and positions of the atoms is fairly inconsequential to the result you will get: in the 0 th generation it gets effectively randomised. The only thing that matters is the amount of Si atoms defined in the POSITIONS_FRAC block - here it is 8 so future structures will also have 8 atoms. Another thing worth noting is the QC5 potential being used - it is used due to its speed, which is essential considering how many calculations will be done. For the param file we will use Si.param task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 12 # Max number of generations to run for ga_mutate_amp = 1.00 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.15 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 101213 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=12 RSC=F CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code It is important to understand what is going on in this file. The line task = genetic algor is what tells is to actually run GA. The GA parameters tell the GA how to run- unlike in the previous tutorial (ADD LINK), all of these values are reasonable (the mutation amplitude and rate shouldn't be far off those values in most cases). As you can see, we will have 12 parents in each generation (meaning 12 cells will be chosen to breed), and it will run for 12 generations. ga_fixed_N is what ensures that there are fixed 8 ions in the cell (the more information is fixed, the faster it'll get a decent result as it'll have fewer things to try). There are numerous lines that speed up the GA - with how many calculations are being performed, this is essential to be feasible. op_strategy = SPEED and geom_max_iter = 211 help ensure that the geometry optimisations (of which there are 12 per generation - so 144 in total for this first run!) are fast but reasonably accurate. AS=T and MS=3 allow asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. The devel_code block is a bit more complex. The fact that pair potentials are used are defined in both the GA sub-block and GEOM sub-block, again necessary for speed. The CMD sub-block is there so that geometry optimisations are performed on all members: what happens is cell files are generated (initially randomly and in the 1 st generation onwards by breeding + mutation), as well as respective param files that tell them to geometry optimise, for each member, and then they are run. A very important thing to note are the lines NUM_CHILDREN = 12 RSC = F This is highly atypical and would not be used in most actual calculations: instead, it would look like this NUM_CHILDREN=11 RSC=T RSN=1 With the general rule that NUM_CHILREN + RSN = ga_pop_size (defined earlier). What that does is, in every generation, it creates 1 child as a random high-symmetry structure (with the other 11, NUM_CHILDREN , being bred). The reason this is not used here is because Silicon is a very simple example: it is likely to simply randomly guess that it's diamond, meaning the actual GA was inconsequential and the result is uninteresting. Note Though not a gurantee, using an identical RAND_SEED makes it likely that you'll get identical results to this tutorial, so you can follow along more easily Running and Output Now we can run castep GA on Si. You may use tail -f Si.castep If you wish to see what's going on in the castep file as it runs (it's explained in more detail in the previous tutorial ADD LINK). Once it is done running, we will use the scripts get_data.sh and plot_results.py - first run ./get_data.sh to get the output file out.put . Run the python script to see that data visually in all_gens.png . The graph should look like this Each dot in this graph is a member, showing the spread of enthalpy against their volume per ion. The lowest enthalpy member (in this generation generation 6, member 9) is highlighted - this is is currently considered the most stable structure found. You can also find the lowest enthalpy structure by running grep 'child' Si.castep | sort -k10,10n | head -20 This gives the 10 lowest enthalpy members (each one repeats twice - don't worry about that). The output looks a bit like GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom un-scaled fitness = 0.880788 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom updated fitness = 0.452993 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom un-scaled fitness = 0.828518 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom updated fitness = 0.456619 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom un-scaled fitness = 0.835359 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom updated fitness = 0.432991 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom un-scaled fitness = 0.835345 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom updated fitness = 0.432963 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom un-scaled fitness = 0.801207 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom updated fitness = 0.420408 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom un-scaled fitness = 0.865596 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom updated fitness = 0.444351 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom This further confirms that 6,9 is the most stable member. Now we will examine the structure of it. Running c2x on it via c2x --int -e=0.1-0.0001 Si.gen_006_mem_009 tells us its approximation of the structure of it. In my case it gives the output Tol=0.1 International symmetry is P6_3/mmc Tol=0.00316 International symmetry is C2/m From this we can immediately tell that the result is imperfect: the actual structure should be diamond (Fd-3m). Do not worry, however, as looking at a 2x2 supercell in VESTA one can see the resemblance to what we'd expect: This is promising - though it started off by generating random structures, it has already arrived at one resembling diamond. Let's see if more generations will improve the results. Change the initial param file to have ga_max_gens = 18 and add the line continuation = Si.xyz This tells it to continue to run, up to 18 generations, using the previous results as its history. Running castep GA on Si again will make it run as before. After it's done running, if you wish to save the previous graph, simply rename it. Then run the bash, and then python, script again to get a new all_gens.png for the continued, longer run. The new image will have more points on the graph, as more members have been examined, and (hopefully) a new minimum enthalpy member. Running the same grep command will give this in the top 4 GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom This is rather interesting: even after 6 * 12 = 72 new members have been generated, the original minimum is still the 2 nd lowest enthalpy: it certainly is a good structure. However, 16,7 is now considered the best: let's look at how it improved. Running c2x on it tells me this Tol=0.1 International symmetry is Fd-3m Tol=0.0001 International symmetry is P-1 According to c2x it is now more similar to diamond (though if you're being very strict with it it, is not - it is still imperfect, though closer). Looking at it on VESTA (again a 2x2 supercell) tells us a similar story As expected of GA, it has managed to improve the structure through multiple generations. If you wish, you could continue to run it for more generations by keeping the continuation line and increasing ga_max_gens more - in fact, if using a different seed or if your environment processed said seed differently, you may have to - 6 more generations aren't guranteed to find a new lowest enthalpy structure!","title":"Silicon"},{"location":"tutorials/GA/Silicon/#castep-ga-for-silicon","text":"Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA!","title":"Castep GA for silicon"},{"location":"tutorials/GA/Silicon/#input-files","text":"We will use the cell file Si.cell %block LATTICE_ABC ang 3.8 3.8 3.8 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.203 0.617 0.209 Si 0.844 0.442 0.350 Si 0.964 0.379 0.096 Si 0.762 0.524 0.941 Si 0.544 0.605 0.781 Si 0.238 0.597 0.531 Si 0.728 0.914 0.742 Si 0.209 0.929 0.435 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang The definition of the lattice and positions of the atoms is fairly inconsequential to the result you will get: in the 0 th generation it gets effectively randomised. The only thing that matters is the amount of Si atoms defined in the POSITIONS_FRAC block - here it is 8 so future structures will also have 8 atoms. Another thing worth noting is the QC5 potential being used - it is used due to its speed, which is essential considering how many calculations will be done. For the param file we will use Si.param task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 12 # Max number of generations to run for ga_mutate_amp = 1.00 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.15 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 101213 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=12 RSC=F CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code It is important to understand what is going on in this file. The line task = genetic algor is what tells is to actually run GA. The GA parameters tell the GA how to run- unlike in the previous tutorial (ADD LINK), all of these values are reasonable (the mutation amplitude and rate shouldn't be far off those values in most cases). As you can see, we will have 12 parents in each generation (meaning 12 cells will be chosen to breed), and it will run for 12 generations. ga_fixed_N is what ensures that there are fixed 8 ions in the cell (the more information is fixed, the faster it'll get a decent result as it'll have fewer things to try). There are numerous lines that speed up the GA - with how many calculations are being performed, this is essential to be feasible. op_strategy = SPEED and geom_max_iter = 211 help ensure that the geometry optimisations (of which there are 12 per generation - so 144 in total for this first run!) are fast but reasonably accurate. AS=T and MS=3 allow asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. The devel_code block is a bit more complex. The fact that pair potentials are used are defined in both the GA sub-block and GEOM sub-block, again necessary for speed. The CMD sub-block is there so that geometry optimisations are performed on all members: what happens is cell files are generated (initially randomly and in the 1 st generation onwards by breeding + mutation), as well as respective param files that tell them to geometry optimise, for each member, and then they are run. A very important thing to note are the lines NUM_CHILDREN = 12 RSC = F This is highly atypical and would not be used in most actual calculations: instead, it would look like this NUM_CHILDREN=11 RSC=T RSN=1 With the general rule that NUM_CHILREN + RSN = ga_pop_size (defined earlier). What that does is, in every generation, it creates 1 child as a random high-symmetry structure (with the other 11, NUM_CHILDREN , being bred). The reason this is not used here is because Silicon is a very simple example: it is likely to simply randomly guess that it's diamond, meaning the actual GA was inconsequential and the result is uninteresting. Note Though not a gurantee, using an identical RAND_SEED makes it likely that you'll get identical results to this tutorial, so you can follow along more easily","title":"Input Files"},{"location":"tutorials/GA/Silicon/#running-and-output","text":"Now we can run castep GA on Si. You may use tail -f Si.castep If you wish to see what's going on in the castep file as it runs (it's explained in more detail in the previous tutorial ADD LINK). Once it is done running, we will use the scripts get_data.sh and plot_results.py - first run ./get_data.sh to get the output file out.put . Run the python script to see that data visually in all_gens.png . The graph should look like this Each dot in this graph is a member, showing the spread of enthalpy against their volume per ion. The lowest enthalpy member (in this generation generation 6, member 9) is highlighted - this is is currently considered the most stable structure found. You can also find the lowest enthalpy structure by running grep 'child' Si.castep | sort -k10,10n | head -20 This gives the 10 lowest enthalpy members (each one repeats twice - don't worry about that). The output looks a bit like GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom un-scaled fitness = 0.880788 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom updated fitness = 0.452993 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom un-scaled fitness = 0.828518 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom updated fitness = 0.456619 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom un-scaled fitness = 0.835359 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom updated fitness = 0.432991 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom un-scaled fitness = 0.835345 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom updated fitness = 0.432963 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom un-scaled fitness = 0.801207 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom updated fitness = 0.420408 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom un-scaled fitness = 0.865596 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom updated fitness = 0.444351 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom This further confirms that 6,9 is the most stable member. Now we will examine the structure of it. Running c2x on it via c2x --int -e=0.1-0.0001 Si.gen_006_mem_009 tells us its approximation of the structure of it. In my case it gives the output Tol=0.1 International symmetry is P6_3/mmc Tol=0.00316 International symmetry is C2/m From this we can immediately tell that the result is imperfect: the actual structure should be diamond (Fd-3m). Do not worry, however, as looking at a 2x2 supercell in VESTA one can see the resemblance to what we'd expect: This is promising - though it started off by generating random structures, it has already arrived at one resembling diamond. Let's see if more generations will improve the results. Change the initial param file to have ga_max_gens = 18 and add the line continuation = Si.xyz This tells it to continue to run, up to 18 generations, using the previous results as its history. Running castep GA on Si again will make it run as before. After it's done running, if you wish to save the previous graph, simply rename it. Then run the bash, and then python, script again to get a new all_gens.png for the continued, longer run. The new image will have more points on the graph, as more members have been examined, and (hopefully) a new minimum enthalpy member. Running the same grep command will give this in the top 4 GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom This is rather interesting: even after 6 * 12 = 72 new members have been generated, the original minimum is still the 2 nd lowest enthalpy: it certainly is a good structure. However, 16,7 is now considered the best: let's look at how it improved. Running c2x on it tells me this Tol=0.1 International symmetry is Fd-3m Tol=0.0001 International symmetry is P-1 According to c2x it is now more similar to diamond (though if you're being very strict with it it, is not - it is still imperfect, though closer). Looking at it on VESTA (again a 2x2 supercell) tells us a similar story As expected of GA, it has managed to improve the structure through multiple generations. If you wish, you could continue to run it for more generations by keeping the continuation line and increasing ga_max_gens more - in fact, if using a different seed or if your environment processed said seed differently, you may have to - 6 more generations aren't guranteed to find a new lowest enthalpy structure!","title":"Running and Output"},{"location":"tutorials/NEB/neb_tutorial/","text":"Nudged elastic band tutorial Overview and background The nudged elastic band (NEB) approach is a widely-used method for finding a minimum energy pathway between two configurations of atoms. You can use the method to estimate the barrier for the system to transition between the two structures. The technique starts with two fixed end points which are fully relaxed (local) minima: the initial and final configurations. It then connects these end points with a series of \"images\" via fictitious springs that \"pull\" the structures taut over one or more intermediate transition states. In this tutorial, we will use the well-known example of an ammonia molecule's pyramidal inversion We will cover: How to set up the initial, final (and intermediate) structures How to actually run the NEB calculation efficiently How to analyse the results Other tips and tricks Files You can find all the files needed for this tutorial here: neb_tutorial.tar.gz Setting up the structures Setting up the initial and final states These are the local minima structures you want to find the barrier between. They can be equivalent structures, e.g. differing by a symmetry operation, such reflection through a mirror plane, or they can be configurations with different energies (in which case your forward and reverse barriers will not be the same!). Two crucial conditions must be met before running the NEB calculation : The end point structures must be fully relaxed (geometry optimised) before you start the NEB. Note that both the initial relaxations and the actual NEB calculation must use consistent parameters (e.g. basis set, pseudopotentials, k-points, XC functional etc.). The atoms must be in the correct order. A common mistake is to use a software tool to generate the final state from the initial state and end up with atoms that don't match the initial atom order. Atoms then \"pass through each other\" when CASTEP interpolates between the two structures, causing the calculation to blow up. Always check that the atoms connect up in the way you expect. Note that, for CASTEP, only the atom order within a given species matters, not the order of the species themselves. In this example, we make sure that the H atoms are in the same order in the initial, final and intermediate structures and we can have the N coordinate either before or after the H atom coordinates. The initial state is specified in the same way as a normal .cell file, e.g.: %BLOCK positions_frac H 0.500011764912384 0.634846485697942 0.443086003907125 H 0.616593728396204 0.432553816946042 0.442828605918639 H 0.383248448613152 0.432623959245757 0.443068863520867 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac The final state is specified using a similar block in the same .cell file but with _product appended to the name of the block, e.g.: %BLOCK positions_frac_product H 0.500154169007758 0.634858887961251 0.556834437330747 H 0.616661280589956 0.432482046338754 0.556941161085851 H 0.383366127862304 0.432719065607707 0.557277918851780 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac_product Setting up the transition state guess CASTEP requires you to provide one intermediate structure between the initial and final configurations in order to get the NEB on the right track. The intermediate configuration is added using, e.g.: %BLOCK POSITIONS_ABS_INTERMEDIATE ang N 3.500000 3.500000 3.500000 H 3.500000 4.443968 3.500000 H 4.316393 3.027626 3.500000 H 2.683149 3.028701 3.501215 %ENDBLOCK POSITIONS_ABS_INTERMEDIATE CASTEP will linearly interpolate from the initial to intermediate and the intermediate to final structures provided to generate the rest of the path, depending on the number of images you have chosen. In many cases, a suitable transition state guess structure is simply the halfway point between the initial and final structures (a linear interpolation between the coordinates). However, if your minimum energy pathway contains e.g. a rotation of a (group of) atom(s) around a bond or something similar, then the linear path between initial and final configurations may be a bad starting guess/non-physical structure. For example, if your end points correspond to a C2 rotation, then a linearly interpolated intermediate structure would not be a physical one. It's important to visualise or otherwise check all of your structures before running a calculation. Intermediate structures can also be chosen in such a way as to bias your results to one pathway over another. How many images do I need? It depends... It's usually preferable to start with a small number of images and increase the number if you need to. Starting small can quickly give you a rough sense of the energy landscape and that will determine the actual number of images needed. In addition, if you start with too many images then you might never get close to the converged TS because the optimisation takes too long. If you instead start with a small number and get a reasonable TS structure, you can then use that as your initial intermediate structure in a restarted calculation with more images. Using many (i.e. > 15) will result in slow convergence, but may lead to a more accurate minimum energy pathway for complex barriers. If you do find a particularly complex pathway, however, you might be better off splitting the work up into more than one NEB calculation, each with fewer images. Just remember to always fully relax the end points (even if the end point is a meta-stable local minimum)! Using too few (i.e. < 5) might fail to find the minimum energy pathway if the energy landscape is complex. The TS guess structure that you specify in the .cell file will be assigned to the middle image, with the other images being initially linearly interpolated between the initial, TS guess and final structures. If you choose an even number of images, the 'middle' one is taken to be the one to the right of the centre. e.g. for 6 images, the TS guess will be assigned to image 4. This will make your initial NEB asymmetric in the sense that there will be more images to the left of the TS guess than to the right. If the TS guess is estimated to be in the geometric centre of the minimum energy pathway, then it's probably best to use an odd number of images. As the minimum energy pathway is very simple in this example, we can actually get away with just one image. However, we'll use 7 images here to illustrate the process. As an exercise, you can try running the same calculation with tssearch_max_path_points: 1, 2, 3, 4, 5 images and note how the results change. Some questions to help answer how many images you need: How complex is the landscape between the initial and final state? For example, if you expect more than one maximum between the end points, you probably need more images than for the single peak example we look at here. Note The number of images is the number of structures between the end points. The total number of structures in the path (i.e. including the end points) is therefore the number of images + 2. Constraints We can often dramatically improve the efficiency of the transition state search by imposing constraints on the atomic positions, although this must be done with care so as not to introduce artifacts. For example, when looking at NEB barriers for adsorbates on a surface slab, we can usefully constrain the bottom slab layers, but probably want the top layer(s) unconstrained. In the ammonia case, we can constrain the N atom position without affecting the physical set up by adding the block: %BLOCK IONIC_CONSTRAINTS fix: N %ENDBLOCK IONIC_CONSTRAINTS to the nh3.cell file. You should then see something like: --- Initialising NEB constraints --- Fixed 3 degrees of freedom in the .castep output file. Do I need climbing NEB? The climbing NEB method modifies the force on the highest-energy image such that it tries to climb up the barrier. This is very useful to get an accurate estimate of the transition state configuration and barrier since you ensure that one image sits exactly at the saddle point of the minimum energy pathway. However, care must be taken when exploring more complex pathways (i.e. with multiple maxima) since it might become ambiguous as to which image should be the one to \"climb\". In our example the path is quite straightforward and will not make a large difference whether we use the climbing or regular NEB method. We can set: TSSEARCH_NEB_CLIMBING: TRUE in the .param file. Though it's not necessary in this case, we will use it here to illustrate the process. To illustrate a case in which climbing NEB is more important, consider briefly another example: that of the HCN - HNC isomerisation. In this case, the minimum energy pathway is not a simple linear interpolation between the initial and final states and the minimum energy pathway is not symmetric. The climbing NEB method is very important to get an accurate estimate of the barrier and transition state structure. In Fig 1., we compare the regular and climbing NEB methods using 7 images. While we can find similar barrier heights using both methods if we use a suitable interpolation scheme for the regular NEB, the regular NEB does not find the correct transition state structure. The climbing NEB, on the other hand, finds the correct transition state structure and barrier height. Fig1. Comparison of the regular NEB (left) and the climbing NEB (right) methods for the case of an HCN - HNC isomerisation. The red circle markers indicate the highest-energy structure in each case. The initial, transition state and final configurations are shown for the climbing NEB, with white, blue and brown spheres representing H, N and C respectively. Note that these are not converged calculations, but are simply provided as a simple comparison of the NEB methods. Note The climbing image method in CASTEP requires an odd number total number of images. Therefore, if you choose an even number of images in your .param file, CASTEP will automatically add one more image. Running the NEB Parallelisation Because the NEB calculation essentially involves N independent CASTEP calculations (where N is the number of images), we can make very efficient use of high-performance computers. This is done via \"task farming\", running the calculations for the N images independently. For example, if one CASTEP calculation fits on one node, and you have 7 images, then you could run on a total of 7 nodes by setting the keyword: NUM_FARMS: 7 in the .param file. A good rule of thumb is to aim for NUM_FARMS = number of NEB images. That way each 'farm' is responsible for one NEB image. Since each farm will effectively run a series of single-point calculations on each NEB image they are responsible for, the compute resources of that farm should be appropriately sized for such calculations. Too small and you could get an out-of-memory error, too large and you might end up over-parallelising, leading to reduced overall performance. i.e. you should aim to run on a total of NUM_FARMS times as many cores as you would use for a single-point calculation on one of the structures. This also assumes that your available compute resources can be neatly split into NUM_FARMS . The easy case is when each farm can run on a single node; i.e. NUM_FARMS = number of NEB images = number of nodes. Note that the total number of cores available must be divisible by NUM_FARMS . If you choose NUM_FARMS < number of images, each of the images will run sequentially on one farm as soon as that farm becomes available. If the number of images is not a multiple of NUM_FARMS , some farms will end up being responsible for more images than others, leading poor overall efficiency. If you choose NUM_FARMS > number of images, then some farms will be left with nothing to do, resulting in poor overall efficiency. Setting NUM_FARMS = 1 is equivalent to not setting NUM_FARMS . You will notice that if you enable task farming, the seedname.castep output file will look relatively empty, as most output is split into the different task farm .castep files. The first indexed one contains the most important information (for example, the \"Max NEB force\") and will be called e.g. seedname_farm001.castep . Is the calculation converging? You can monitor the convergence by searching for \"Max NEB force\" within the .castep output file. Common convergence issues include: Not having consistent atom order in the initial and final structures, i.e. non-physical initial path. This is one of the more common reasons for failed calculation. It's always important to visualise the initial and final structures and check that the atoms connect up in the way you expect. Too many (or too few) images. Too many images can lead to slow convergence, too few can lead to the calculation failing to find the minimum energy pathway. Initial or final state (endpoints) not being fully relaxed structures Restarting / Continuing Sometimes the calculation will run out of time/number of iterations before the NEB calculation is finished. You will probably see a \"Failed to converge\" message in the .castep output in that case; always read through your output files! If you re-run the calculation without changing anything, it will simply start from the beginning again -- probably not what you want! In order restart the NEB from the last checkpointed state, you need to explicitly set the name of the .check file you want to continue from in your .param file. In our example that would be: continuation: nh3.check In the .castep output you would then see: Coordinates of NEB images loaded from checkpoint file . Warning Unlike other CASTEP tasks, setting continuation: default does not seem to work for continuing/restarting NEB calculations! You must explicitly set the name of checkpoint file. Analysis Once you have a converged NEB, the provided Python utility readTS can be used to parse and analyse the NEB. To add the readTS module to your PYTHONPATH, you can find a setup.py script in the castep/Utilities/readts directory of your CASTEP source directory. Running python setup.py should install the module to your path. You can also manually add it by inserting the following line into your ~/.bashrc or equivalent and restarting the terminal: export PYTHONPATH = \"/path/to/castep/Utilities/readts: $PYTHONPATH \" (changing the /path/to/castep/ bit to wherever CASTEP is on your machine). You can then extract the NEB path using something like this python code: ## get this by adding castep/Utilities/readts to your PYTHONPATH from readts import TSFile from ase.neb import NEBTools def get_images ( tsfile ): ''' Function to extract the final NEB images from a tsfile object Args: tsfile (TSFile): tsfile object Returns: images (list): list of ASE atoms objects ''' diam_tst = tsfile . blocks [ 'TST' ] diam_i = tsfile . blocks [ 'REA' ][ 1 ][ 0 ] diam_f = tsfile . blocks [ 'PRO' ][ 1 ][ 0 ] nbeads = len ( diam_tst [ 1 ]) max_idx = diam_tst . last_index images = [ diam_i . atoms ] images += [ diam_tst [ max_idx ][ i ] . atoms for i in range ( 0 , nbeads , 1 )] images . append ( diam_f . atoms ) return images def plot_band ( images , filename = 'neb.png' ): nt = NEBTools ( images ) energies = nt . get_barrier () print ( f 'Barrier height: { energies [ 0 ] : 16.5f } eV' ) print ( f 'E_final - E_initial: { energies [ 1 ] : 16.5f } eV' ) nebplot = nt . plot_band () nebplot . savefig ( filename ) if __name__ == '__main__' : import sys seedname = sys . argv [ 1 ] path = './' tolerant = False if len ( sys . argv ) > 2 : tolerant = bool ( sys . argv [ 2 ]) tsfile = TSFile ( seedname , path = path , tolerant = tolerant ) images = get_images ( tsfile ) plot_band ( images ) # we can use ASE to write out the structure # in whatever format we want print ( 'Image \\t\\t Energy (eV)' ) for i , atoms in enumerate ( images ): print ( f ' { i : 03d } \\t { atoms . get_potential_energy () : 16.5f } eV' ) ## this format includes the energy of the image atoms . write ( f 'image- { i : 03d } .xyz' ) ## We can also use the ASE GUI to ## view the images and analyse the NEB path. ## Select Tools -> NEB Plot # from ase.visualize import view # view(images) If we save this script as analysis.py and run it in the directory containing both the nh3.cell and nh3.ts files like this: python analysis.py nh3 we will get an .xyz file for each structure in the optimised NEB path and the energy of each image. We will also get the barrier estimate and a NEB plot showing the barrier. The ASE GUI can also be used to plot the NEB band (uncomment the last two lines in the above script and Select Tools \u2192 NEB Plot from the GUI). The ASE-generated plot looks like this: The green lines show the tangents at those points; these can be useful indicators of convergence. The barrier we obtained is about 0.23 eV, which compares well with the value of 0.25 eV (24.2 kJ/mol) from Wikipedia . We might also notice the slight difference in energy between the two end-points of the path (about 1 meV). These should be identical, so any difference can be used as a very rough guide for the amount of numerical noise in the geometry optimisations. If equivalent structures (the end-points in this example) were found to have very different energies, you would need to go back and tighten up your convergence criteria or force/energy tolerances in the initial geometry optimisations and re-run the NEB calculation with these tightened parameters. Using our favourite visualisation software (here we used the ASE POV-Ray interface ), we can then look at how the structure evolves along the minimum energy pathway found via the NEB. Zero point energy corrections All of the above calculations were done while treating the nuclei as classical particles. In many cases, particularly when lighter atoms are involved, the energy barrier estimates would need to be corrected for quantum-nuclear effects. The simplest approach to accounting for the true quantum nature of nuclei is to compute the vibrational frequencies of the nuclei within the harmonic approximation. You need would need to do this for the reactant and transition state configurations and use, for example, equation 2 from [J. Chem. Phys. 124, 044706 (2006)](http://theory.cm.utexas.edu/henkelman/pubs/henkelman06_044706.pdf) to obtain the Harmonic quantum correction to the barrier.","title":"Nudged elastic band"},{"location":"tutorials/NEB/neb_tutorial/#nudged-elastic-band-tutorial","text":"","title":"Nudged elastic band tutorial"},{"location":"tutorials/NEB/neb_tutorial/#overview-and-background","text":"The nudged elastic band (NEB) approach is a widely-used method for finding a minimum energy pathway between two configurations of atoms. You can use the method to estimate the barrier for the system to transition between the two structures. The technique starts with two fixed end points which are fully relaxed (local) minima: the initial and final configurations. It then connects these end points with a series of \"images\" via fictitious springs that \"pull\" the structures taut over one or more intermediate transition states. In this tutorial, we will use the well-known example of an ammonia molecule's pyramidal inversion We will cover: How to set up the initial, final (and intermediate) structures How to actually run the NEB calculation efficiently How to analyse the results Other tips and tricks","title":"Overview and background"},{"location":"tutorials/NEB/neb_tutorial/#files","text":"You can find all the files needed for this tutorial here: neb_tutorial.tar.gz","title":"Files"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-structures","text":"","title":"Setting up the structures"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-initial-and-final-states","text":"These are the local minima structures you want to find the barrier between. They can be equivalent structures, e.g. differing by a symmetry operation, such reflection through a mirror plane, or they can be configurations with different energies (in which case your forward and reverse barriers will not be the same!). Two crucial conditions must be met before running the NEB calculation : The end point structures must be fully relaxed (geometry optimised) before you start the NEB. Note that both the initial relaxations and the actual NEB calculation must use consistent parameters (e.g. basis set, pseudopotentials, k-points, XC functional etc.). The atoms must be in the correct order. A common mistake is to use a software tool to generate the final state from the initial state and end up with atoms that don't match the initial atom order. Atoms then \"pass through each other\" when CASTEP interpolates between the two structures, causing the calculation to blow up. Always check that the atoms connect up in the way you expect. Note that, for CASTEP, only the atom order within a given species matters, not the order of the species themselves. In this example, we make sure that the H atoms are in the same order in the initial, final and intermediate structures and we can have the N coordinate either before or after the H atom coordinates. The initial state is specified in the same way as a normal .cell file, e.g.: %BLOCK positions_frac H 0.500011764912384 0.634846485697942 0.443086003907125 H 0.616593728396204 0.432553816946042 0.442828605918639 H 0.383248448613152 0.432623959245757 0.443068863520867 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac The final state is specified using a similar block in the same .cell file but with _product appended to the name of the block, e.g.: %BLOCK positions_frac_product H 0.500154169007758 0.634858887961251 0.556834437330747 H 0.616661280589956 0.432482046338754 0.556941161085851 H 0.383366127862304 0.432719065607707 0.557277918851780 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac_product","title":"Setting up the initial and final states"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-transition-state-guess","text":"CASTEP requires you to provide one intermediate structure between the initial and final configurations in order to get the NEB on the right track. The intermediate configuration is added using, e.g.: %BLOCK POSITIONS_ABS_INTERMEDIATE ang N 3.500000 3.500000 3.500000 H 3.500000 4.443968 3.500000 H 4.316393 3.027626 3.500000 H 2.683149 3.028701 3.501215 %ENDBLOCK POSITIONS_ABS_INTERMEDIATE CASTEP will linearly interpolate from the initial to intermediate and the intermediate to final structures provided to generate the rest of the path, depending on the number of images you have chosen. In many cases, a suitable transition state guess structure is simply the halfway point between the initial and final structures (a linear interpolation between the coordinates). However, if your minimum energy pathway contains e.g. a rotation of a (group of) atom(s) around a bond or something similar, then the linear path between initial and final configurations may be a bad starting guess/non-physical structure. For example, if your end points correspond to a C2 rotation, then a linearly interpolated intermediate structure would not be a physical one. It's important to visualise or otherwise check all of your structures before running a calculation. Intermediate structures can also be chosen in such a way as to bias your results to one pathway over another.","title":"Setting up the transition state guess"},{"location":"tutorials/NEB/neb_tutorial/#how-many-images-do-i-need","text":"It depends... It's usually preferable to start with a small number of images and increase the number if you need to. Starting small can quickly give you a rough sense of the energy landscape and that will determine the actual number of images needed. In addition, if you start with too many images then you might never get close to the converged TS because the optimisation takes too long. If you instead start with a small number and get a reasonable TS structure, you can then use that as your initial intermediate structure in a restarted calculation with more images. Using many (i.e. > 15) will result in slow convergence, but may lead to a more accurate minimum energy pathway for complex barriers. If you do find a particularly complex pathway, however, you might be better off splitting the work up into more than one NEB calculation, each with fewer images. Just remember to always fully relax the end points (even if the end point is a meta-stable local minimum)! Using too few (i.e. < 5) might fail to find the minimum energy pathway if the energy landscape is complex. The TS guess structure that you specify in the .cell file will be assigned to the middle image, with the other images being initially linearly interpolated between the initial, TS guess and final structures. If you choose an even number of images, the 'middle' one is taken to be the one to the right of the centre. e.g. for 6 images, the TS guess will be assigned to image 4. This will make your initial NEB asymmetric in the sense that there will be more images to the left of the TS guess than to the right. If the TS guess is estimated to be in the geometric centre of the minimum energy pathway, then it's probably best to use an odd number of images. As the minimum energy pathway is very simple in this example, we can actually get away with just one image. However, we'll use 7 images here to illustrate the process. As an exercise, you can try running the same calculation with tssearch_max_path_points: 1, 2, 3, 4, 5 images and note how the results change. Some questions to help answer how many images you need: How complex is the landscape between the initial and final state? For example, if you expect more than one maximum between the end points, you probably need more images than for the single peak example we look at here. Note The number of images is the number of structures between the end points. The total number of structures in the path (i.e. including the end points) is therefore the number of images + 2.","title":"How many images do I need?"},{"location":"tutorials/NEB/neb_tutorial/#constraints","text":"We can often dramatically improve the efficiency of the transition state search by imposing constraints on the atomic positions, although this must be done with care so as not to introduce artifacts. For example, when looking at NEB barriers for adsorbates on a surface slab, we can usefully constrain the bottom slab layers, but probably want the top layer(s) unconstrained. In the ammonia case, we can constrain the N atom position without affecting the physical set up by adding the block: %BLOCK IONIC_CONSTRAINTS fix: N %ENDBLOCK IONIC_CONSTRAINTS to the nh3.cell file. You should then see something like: --- Initialising NEB constraints --- Fixed 3 degrees of freedom in the .castep output file.","title":"Constraints"},{"location":"tutorials/NEB/neb_tutorial/#do-i-need-climbing-neb","text":"The climbing NEB method modifies the force on the highest-energy image such that it tries to climb up the barrier. This is very useful to get an accurate estimate of the transition state configuration and barrier since you ensure that one image sits exactly at the saddle point of the minimum energy pathway. However, care must be taken when exploring more complex pathways (i.e. with multiple maxima) since it might become ambiguous as to which image should be the one to \"climb\". In our example the path is quite straightforward and will not make a large difference whether we use the climbing or regular NEB method. We can set: TSSEARCH_NEB_CLIMBING: TRUE in the .param file. Though it's not necessary in this case, we will use it here to illustrate the process. To illustrate a case in which climbing NEB is more important, consider briefly another example: that of the HCN - HNC isomerisation. In this case, the minimum energy pathway is not a simple linear interpolation between the initial and final states and the minimum energy pathway is not symmetric. The climbing NEB method is very important to get an accurate estimate of the barrier and transition state structure. In Fig 1., we compare the regular and climbing NEB methods using 7 images. While we can find similar barrier heights using both methods if we use a suitable interpolation scheme for the regular NEB, the regular NEB does not find the correct transition state structure. The climbing NEB, on the other hand, finds the correct transition state structure and barrier height. Fig1. Comparison of the regular NEB (left) and the climbing NEB (right) methods for the case of an HCN - HNC isomerisation. The red circle markers indicate the highest-energy structure in each case. The initial, transition state and final configurations are shown for the climbing NEB, with white, blue and brown spheres representing H, N and C respectively. Note that these are not converged calculations, but are simply provided as a simple comparison of the NEB methods. Note The climbing image method in CASTEP requires an odd number total number of images. Therefore, if you choose an even number of images in your .param file, CASTEP will automatically add one more image.","title":"Do I need climbing NEB?"},{"location":"tutorials/NEB/neb_tutorial/#running-the-neb","text":"","title":"Running the NEB"},{"location":"tutorials/NEB/neb_tutorial/#parallelisation","text":"Because the NEB calculation essentially involves N independent CASTEP calculations (where N is the number of images), we can make very efficient use of high-performance computers. This is done via \"task farming\", running the calculations for the N images independently. For example, if one CASTEP calculation fits on one node, and you have 7 images, then you could run on a total of 7 nodes by setting the keyword: NUM_FARMS: 7 in the .param file. A good rule of thumb is to aim for NUM_FARMS = number of NEB images. That way each 'farm' is responsible for one NEB image. Since each farm will effectively run a series of single-point calculations on each NEB image they are responsible for, the compute resources of that farm should be appropriately sized for such calculations. Too small and you could get an out-of-memory error, too large and you might end up over-parallelising, leading to reduced overall performance. i.e. you should aim to run on a total of NUM_FARMS times as many cores as you would use for a single-point calculation on one of the structures. This also assumes that your available compute resources can be neatly split into NUM_FARMS . The easy case is when each farm can run on a single node; i.e. NUM_FARMS = number of NEB images = number of nodes. Note that the total number of cores available must be divisible by NUM_FARMS . If you choose NUM_FARMS < number of images, each of the images will run sequentially on one farm as soon as that farm becomes available. If the number of images is not a multiple of NUM_FARMS , some farms will end up being responsible for more images than others, leading poor overall efficiency. If you choose NUM_FARMS > number of images, then some farms will be left with nothing to do, resulting in poor overall efficiency. Setting NUM_FARMS = 1 is equivalent to not setting NUM_FARMS . You will notice that if you enable task farming, the seedname.castep output file will look relatively empty, as most output is split into the different task farm .castep files. The first indexed one contains the most important information (for example, the \"Max NEB force\") and will be called e.g. seedname_farm001.castep .","title":"Parallelisation"},{"location":"tutorials/NEB/neb_tutorial/#is-the-calculation-converging","text":"You can monitor the convergence by searching for \"Max NEB force\" within the .castep output file. Common convergence issues include: Not having consistent atom order in the initial and final structures, i.e. non-physical initial path. This is one of the more common reasons for failed calculation. It's always important to visualise the initial and final structures and check that the atoms connect up in the way you expect. Too many (or too few) images. Too many images can lead to slow convergence, too few can lead to the calculation failing to find the minimum energy pathway. Initial or final state (endpoints) not being fully relaxed structures","title":"Is the calculation converging?"},{"location":"tutorials/NEB/neb_tutorial/#restarting-continuing","text":"Sometimes the calculation will run out of time/number of iterations before the NEB calculation is finished. You will probably see a \"Failed to converge\" message in the .castep output in that case; always read through your output files! If you re-run the calculation without changing anything, it will simply start from the beginning again -- probably not what you want! In order restart the NEB from the last checkpointed state, you need to explicitly set the name of the .check file you want to continue from in your .param file. In our example that would be: continuation: nh3.check In the .castep output you would then see: Coordinates of NEB images loaded from checkpoint file . Warning Unlike other CASTEP tasks, setting continuation: default does not seem to work for continuing/restarting NEB calculations! You must explicitly set the name of checkpoint file.","title":"Restarting / Continuing"},{"location":"tutorials/NEB/neb_tutorial/#analysis","text":"Once you have a converged NEB, the provided Python utility readTS can be used to parse and analyse the NEB. To add the readTS module to your PYTHONPATH, you can find a setup.py script in the castep/Utilities/readts directory of your CASTEP source directory. Running python setup.py should install the module to your path. You can also manually add it by inserting the following line into your ~/.bashrc or equivalent and restarting the terminal: export PYTHONPATH = \"/path/to/castep/Utilities/readts: $PYTHONPATH \" (changing the /path/to/castep/ bit to wherever CASTEP is on your machine). You can then extract the NEB path using something like this python code: ## get this by adding castep/Utilities/readts to your PYTHONPATH from readts import TSFile from ase.neb import NEBTools def get_images ( tsfile ): ''' Function to extract the final NEB images from a tsfile object Args: tsfile (TSFile): tsfile object Returns: images (list): list of ASE atoms objects ''' diam_tst = tsfile . blocks [ 'TST' ] diam_i = tsfile . blocks [ 'REA' ][ 1 ][ 0 ] diam_f = tsfile . blocks [ 'PRO' ][ 1 ][ 0 ] nbeads = len ( diam_tst [ 1 ]) max_idx = diam_tst . last_index images = [ diam_i . atoms ] images += [ diam_tst [ max_idx ][ i ] . atoms for i in range ( 0 , nbeads , 1 )] images . append ( diam_f . atoms ) return images def plot_band ( images , filename = 'neb.png' ): nt = NEBTools ( images ) energies = nt . get_barrier () print ( f 'Barrier height: { energies [ 0 ] : 16.5f } eV' ) print ( f 'E_final - E_initial: { energies [ 1 ] : 16.5f } eV' ) nebplot = nt . plot_band () nebplot . savefig ( filename ) if __name__ == '__main__' : import sys seedname = sys . argv [ 1 ] path = './' tolerant = False if len ( sys . argv ) > 2 : tolerant = bool ( sys . argv [ 2 ]) tsfile = TSFile ( seedname , path = path , tolerant = tolerant ) images = get_images ( tsfile ) plot_band ( images ) # we can use ASE to write out the structure # in whatever format we want print ( 'Image \\t\\t Energy (eV)' ) for i , atoms in enumerate ( images ): print ( f ' { i : 03d } \\t { atoms . get_potential_energy () : 16.5f } eV' ) ## this format includes the energy of the image atoms . write ( f 'image- { i : 03d } .xyz' ) ## We can also use the ASE GUI to ## view the images and analyse the NEB path. ## Select Tools -> NEB Plot # from ase.visualize import view # view(images) If we save this script as analysis.py and run it in the directory containing both the nh3.cell and nh3.ts files like this: python analysis.py nh3 we will get an .xyz file for each structure in the optimised NEB path and the energy of each image. We will also get the barrier estimate and a NEB plot showing the barrier. The ASE GUI can also be used to plot the NEB band (uncomment the last two lines in the above script and Select Tools \u2192 NEB Plot from the GUI). The ASE-generated plot looks like this: The green lines show the tangents at those points; these can be useful indicators of convergence. The barrier we obtained is about 0.23 eV, which compares well with the value of 0.25 eV (24.2 kJ/mol) from Wikipedia . We might also notice the slight difference in energy between the two end-points of the path (about 1 meV). These should be identical, so any difference can be used as a very rough guide for the amount of numerical noise in the geometry optimisations. If equivalent structures (the end-points in this example) were found to have very different energies, you would need to go back and tighten up your convergence criteria or force/energy tolerances in the initial geometry optimisations and re-run the NEB calculation with these tightened parameters. Using our favourite visualisation software (here we used the ASE POV-Ray interface ), we can then look at how the structure evolves along the minimum energy pathway found via the NEB. Zero point energy corrections All of the above calculations were done while treating the nuclei as classical particles. In many cases, particularly when lighter atoms are involved, the energy barrier estimates would need to be corrected for quantum-nuclear effects. The simplest approach to accounting for the true quantum nature of nuclei is to compute the vibrational frequencies of the nuclei within the harmonic approximation. You need would need to do this for the reactant and transition state configurations and use, for example, equation 2 from [J. Chem. Phys. 124, 044706 (2006)](http://theory.cm.utexas.edu/henkelman/pubs/henkelman06_044706.pdf) to obtain the Harmonic quantum correction to the barrier.","title":"Analysis"},{"location":"tutorials/NMR/Example_1_-Ethanol/","text":"Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig1.). In this tutorial, we will try to reproduce this result. Getting outputs This tutorial will go through the calculations for ethanol, using these 2 files: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strategy = speed task = magres cutoff_energy = 300 eV Look at the cell and param files. Note that the only special part of the ethanol.param file is task = magres Run a standard castep calculation for ethanol. Look at the ethanol.castep output file. Towards the end, you should be able to find the isotropic chemical shielding, anisotropy, and asymmetry in a table like this: ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | H 1 29.45 8.84 0.14 | | H 2 30.10 8.07 0.20 | | H 3 29.94 7.12 0.06 | | H 4 26.83 8.02 0.95 | | H 5 27.24 -7.07 0.90 | | H 6 31.93 13.99 0.46 | | C 1 157.27 33.77 0.70 | | C 2 110.73 69.91 0.42 | | O 1 268.63 -50.78 0.96 | ==================================================================== Here we are only interested in the isotropic values for the hydrogen atoms You may also find this information (as well as extra detail) in the file ethanol.magres , which contains tables such as ============ Atom: H 1 ============ H 1 Coordinates 3.981 4.178 3.295 A TOTAL Shielding Tensor 30.1276 1.2172 3.7366 1.9301 27.4802 2.4707 4.0710 2.2023 30.7511 H 1 Eigenvalue sigma_xx 26.1030 (ppm) H 1 Eigenvector sigma_xx 0.3550 0.6810 -0.6405 H 1 Eigenvalue sigma_yy 26.9119 (ppm) H 1 Eigenvector sigma_yy 0.6932 -0.6514 -0.3085 H 1 Eigenvalue sigma_zz 35.3439 (ppm) H 1 Eigenvector sigma_zz 0.6273 0.3345 0.7033 H 1 Isotropic: 29.4529 (ppm) H 1 Anisotropy: 8.8365 (ppm) H 1 Asymmetry: 0.1373 for each atom. You can see here that it also gives the same information - the isotropic value for atom 1 is the same. You may note that the isotropic value is the average of the diagonal values in the total shielding tensor. You might wish to open the ethanol.magres with MagresView . Analysis Next we identify which (hydrogen) ion corresponds to which part of the molecule - in the case of ethanol, we find out which ones correspond to CH 3 CH 2 and OH. This can be done by uploading the cell file to VESTA or MagresView and clicking each atom. Here you can see that one of the CH 3 hydrogens is atom 3. If you do the same for all of them, you should find that atoms 1, 2 and 3 are the CH 3 hydrogens, 4 and 5 are the CH 2 hydrogens and 6 is the OH hydrogen. It is important to check if the results are converged. Running a convergence test plot ranging the cut_off_energy = 200 eV from 200 to 1600eV gives the plot Here a cut off energy of 600 eV is reasonable - it's still relatively fast and should be fairly well-converged. 800eV is better converged. The cut off is quite high due to the presence of oxygen. Next we will look at the converged isotropic hydrogen shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Then we can average the CH 3 and CH 2 chemical shieldings. For example, the shieldings of the CH 2 hydrogens (atoms 4 and 5) are found in the ethanol.castep file (shown above) to be 26.83ppm and 27.24ppm: the average CH 2 shielding is 27.04ppm. CH 3 , meanwhile, has an average of 29.83ppm. Lastly, the single OH hydrogen has a value of 31.93ppm. We now have 3 unique chemical shieldings (though in your case the values will likely slightly differ) We now need to convert the chemical shieldings \\sigma_{iso} \\sigma_{iso} ; to chemical shifts \\delta_{iso} \\delta_{iso} on the experimental scale. We use the relation: \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma . A suitable \\sigma_{ref} \\sigma_{ref} for 1 H is 30.97ppm. Fig2. 1 H NMR spectrum of liquid ethanol Fig2. shows a modern high-resolution 1 H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1 H magnetic moments. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm - in this tutorial the shifts were found to be 1.14ppm (the CH 3 shielding), 3.94ppm (CH 2 ) and -0.96ppm (OH). The OH hydrogen clearly has a very different result while the other 2 roughly agree. The OH hydrogen shift is very sensitive to hydrogen bonding. It is has a very different value in as isolated molecule (as per our calculation) compared to liquid ethanol. The experimental value in a non-polar solvent should be closer to our isolated molecule - but note that the measurement is sensitive to even small traces of absorbed water, which will affect the OH shift.","title":"Example 1 - Ethanol"},{"location":"tutorials/NMR/Example_1_-Ethanol/#getting-outputs","text":"This tutorial will go through the calculations for ethanol, using these 2 files: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strategy = speed task = magres cutoff_energy = 300 eV Look at the cell and param files. Note that the only special part of the ethanol.param file is task = magres Run a standard castep calculation for ethanol. Look at the ethanol.castep output file. Towards the end, you should be able to find the isotropic chemical shielding, anisotropy, and asymmetry in a table like this: ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | H 1 29.45 8.84 0.14 | | H 2 30.10 8.07 0.20 | | H 3 29.94 7.12 0.06 | | H 4 26.83 8.02 0.95 | | H 5 27.24 -7.07 0.90 | | H 6 31.93 13.99 0.46 | | C 1 157.27 33.77 0.70 | | C 2 110.73 69.91 0.42 | | O 1 268.63 -50.78 0.96 | ==================================================================== Here we are only interested in the isotropic values for the hydrogen atoms You may also find this information (as well as extra detail) in the file ethanol.magres , which contains tables such as ============ Atom: H 1 ============ H 1 Coordinates 3.981 4.178 3.295 A TOTAL Shielding Tensor 30.1276 1.2172 3.7366 1.9301 27.4802 2.4707 4.0710 2.2023 30.7511 H 1 Eigenvalue sigma_xx 26.1030 (ppm) H 1 Eigenvector sigma_xx 0.3550 0.6810 -0.6405 H 1 Eigenvalue sigma_yy 26.9119 (ppm) H 1 Eigenvector sigma_yy 0.6932 -0.6514 -0.3085 H 1 Eigenvalue sigma_zz 35.3439 (ppm) H 1 Eigenvector sigma_zz 0.6273 0.3345 0.7033 H 1 Isotropic: 29.4529 (ppm) H 1 Anisotropy: 8.8365 (ppm) H 1 Asymmetry: 0.1373 for each atom. You can see here that it also gives the same information - the isotropic value for atom 1 is the same. You may note that the isotropic value is the average of the diagonal values in the total shielding tensor. You might wish to open the ethanol.magres with MagresView .","title":"Getting outputs"},{"location":"tutorials/NMR/Example_1_-Ethanol/#analysis","text":"Next we identify which (hydrogen) ion corresponds to which part of the molecule - in the case of ethanol, we find out which ones correspond to CH 3 CH 2 and OH. This can be done by uploading the cell file to VESTA or MagresView and clicking each atom. Here you can see that one of the CH 3 hydrogens is atom 3. If you do the same for all of them, you should find that atoms 1, 2 and 3 are the CH 3 hydrogens, 4 and 5 are the CH 2 hydrogens and 6 is the OH hydrogen. It is important to check if the results are converged. Running a convergence test plot ranging the cut_off_energy = 200 eV from 200 to 1600eV gives the plot Here a cut off energy of 600 eV is reasonable - it's still relatively fast and should be fairly well-converged. 800eV is better converged. The cut off is quite high due to the presence of oxygen. Next we will look at the converged isotropic hydrogen shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Then we can average the CH 3 and CH 2 chemical shieldings. For example, the shieldings of the CH 2 hydrogens (atoms 4 and 5) are found in the ethanol.castep file (shown above) to be 26.83ppm and 27.24ppm: the average CH 2 shielding is 27.04ppm. CH 3 , meanwhile, has an average of 29.83ppm. Lastly, the single OH hydrogen has a value of 31.93ppm. We now have 3 unique chemical shieldings (though in your case the values will likely slightly differ) We now need to convert the chemical shieldings \\sigma_{iso} \\sigma_{iso} ; to chemical shifts \\delta_{iso} \\delta_{iso} on the experimental scale. We use the relation: \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma . A suitable \\sigma_{ref} \\sigma_{ref} for 1 H is 30.97ppm. Fig2. 1 H NMR spectrum of liquid ethanol Fig2. shows a modern high-resolution 1 H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1 H magnetic moments. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm - in this tutorial the shifts were found to be 1.14ppm (the CH 3 shielding), 3.94ppm (CH 2 ) and -0.96ppm (OH). The OH hydrogen clearly has a very different result while the other 2 roughly agree. The OH hydrogen shift is very sensitive to hydrogen bonding. It is has a very different value in as isolated molecule (as per our calculation) compared to liquid ethanol. The experimental value in a non-polar solvent should be closer to our isolated molecule - but note that the measurement is sensitive to even small traces of absorbed water, which will affect the OH shift.","title":"Analysis"},{"location":"tutorials/NMR/Example_2_-Diamond/","text":"Here we will look more into convergence of chemical shielding calculations, examining what happens as we change the sampling of the Birllouin zone (BZ). We will examine diamond for this purpose. Varying k-point grid size We will use the cell and param files below for our calculations: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry Running castep on these files will lead to the diamond.castep output file which will contain the table ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | C 1 164.79 -0.00 N/A | | C 2 164.79 -0.00 N/A | ==================================================================== Note We have already done a convergence test of the cut-off energy, which is specified in that file, in example 1 What we are going to be looking at is isometric shielding tensor of carbon (with both atoms being identical). While there is nothing particularly special in diamond.param , we have specified the k-points in the diamond.cell file using the keyword kpoints_mp_grid 4 4 4 We will test the convergence of the chemical shielding with varying k-point mesh grid sizes. To do so, we will run castep for a range of k-point meshes (2, 4, 6, 8, 10), and then make a convergence plot of k-point mesh size against of the chemical shielding of carbon. The convergence plot should look like this: We can see from this that it converges at a k-point grid size of 4, and the converged value is around 160ppm. Single k-point test The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point, reducing computational cost and increasing speed considerably. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). First, we delete the line kpoints_mp_grid x x x Then we specify the kpoint we are examining in the diamond.cell file using %BLOCK KPOINTS_LIST 0 0 0 1.0 %ENDBLOCK KPOINTS_LIST to check (0,0,0) - in this case it resulted in an isometric chemical shielding of about 5798.71ppm (though, as in previous and future cases, the exact values you get may be slightly different) Similarly, we can change that block to %BLOCK KPOINTS_LIST 0.5 0.5 0.5 1.0 %ENDBLOCK KPOINTS_LIST to check (\u00bd,\u00bd,\u00bd), which led to 303.21ppm. Lastly,we replace that block with %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1 %ENDBLOCK KPOINTS_LIST to check (\u00bc,\u00bc,\u00bc) - this gave a value of 164.79ppm, which is by far the closest to the converged value (around 160ppm, as found by the convergence graph above). as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells","title":"Example 2 - Diamond"},{"location":"tutorials/NMR/Example_2_-Diamond/#varying-k-point-grid-size","text":"We will use the cell and param files below for our calculations: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry Running castep on these files will lead to the diamond.castep output file which will contain the table ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | C 1 164.79 -0.00 N/A | | C 2 164.79 -0.00 N/A | ==================================================================== Note We have already done a convergence test of the cut-off energy, which is specified in that file, in example 1 What we are going to be looking at is isometric shielding tensor of carbon (with both atoms being identical). While there is nothing particularly special in diamond.param , we have specified the k-points in the diamond.cell file using the keyword kpoints_mp_grid 4 4 4 We will test the convergence of the chemical shielding with varying k-point mesh grid sizes. To do so, we will run castep for a range of k-point meshes (2, 4, 6, 8, 10), and then make a convergence plot of k-point mesh size against of the chemical shielding of carbon. The convergence plot should look like this: We can see from this that it converges at a k-point grid size of 4, and the converged value is around 160ppm.","title":"Varying k-point grid size"},{"location":"tutorials/NMR/Example_2_-Diamond/#single-k-point-test","text":"The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point, reducing computational cost and increasing speed considerably. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). First, we delete the line kpoints_mp_grid x x x Then we specify the kpoint we are examining in the diamond.cell file using %BLOCK KPOINTS_LIST 0 0 0 1.0 %ENDBLOCK KPOINTS_LIST to check (0,0,0) - in this case it resulted in an isometric chemical shielding of about 5798.71ppm (though, as in previous and future cases, the exact values you get may be slightly different) Similarly, we can change that block to %BLOCK KPOINTS_LIST 0.5 0.5 0.5 1.0 %ENDBLOCK KPOINTS_LIST to check (\u00bd,\u00bd,\u00bd), which led to 303.21ppm. Lastly,we replace that block with %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1 %ENDBLOCK KPOINTS_LIST to check (\u00bc,\u00bc,\u00bc) - this gave a value of 164.79ppm, which is by far the closest to the converged value (around 160ppm, as found by the convergence graph above). as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells","title":"Single k-point test"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/","text":"Examples 3 - Alanine and Silicates We now look at some more realistic and complex structures - the amino acid alanine and 2 different silicates: cristoballite and qartz. These are fairly large crystals - to get them to complete in a short time we will run them on a cluster. Use the following number of CPUs: analine - 4 cristoballite - 6 quartz - 13 (these numbers are chosen to give efficient k-point scaling) We will also perform EFG calculations for the above structures and examine the respective data. Oxygen-17 NMR Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure. Alanine Examining input and output We will use the cell file alanine.cell Note Don't worry about how long/complex it is - it is no different from any other cell file - it just simply defines a large cell and param file alanine.param fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr cut_off_energy = 35 ry xc_functional : PBE Note that the only difference to the previous files is the line magres_task = nmr This leads to EFG calculations being performed. alanine.param](alanine/alanine.param) You may also want to view the file alanine.pdb in Materials Studio or another software - this allows better examination of features like hydrogen bonding. This is the original file downloaded from the Cambridge Crystallographic Database (and was used to obtain the alanine.cell file). The cell structure was obtained experimentally by neutron diffraction. We will now run castep. The alanine.castep output file should contain the table This is much like our previous results , except there are now 2 more columns - C_Q C_Q and Eta Eta - these are both there because an EFG calculation was now performed. This result is not fully converged (we will not be testing this in this tutorial, but feel free to check), but the relative shift between some of the sites is converged (again you may verify that if inclined). Analysing and comparing to experiment We will now compare these results with experiment. The figure below is an experimental 17 O NMR spectrum of L-alanine. It shows 2 peaks, which are very broad due to the quadripolar coupling, and overlap. Fig3. Solid-State 17 O NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) The experimental parameters are given in Table 1 below. \\delta \\delta (A)- \\delta \\delta (B) (ppm) 23.5 C_Q C_Q (A) (MHz) 7.86 \\eta_Q \\eta_Q (A) 0.28 C_Q C_Q (B) (MHz) 6.53 \\eta_Q \\eta_Q (B) 0.70 Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labelled A and B. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_{Q} C_{Q} , and EFG asymmetry \\eta_Q \\eta_Q . From this, we will try to find what A and B are. To do so, we will look at the alanine.castep tensor table . By a quick glance at the table, we see that the the chemical shift of hydrogen ranges from 20-30ppm, carbon around 0, 124 or 159ppm, nitrogen 194ppm and oxygen 48 or 63ppm. Because of this we can tell that the 2 resonances are going to belong to carbon and oxygen: to get a chemical shift difference of 23.5ppm, oxygen's 48ppm and a hydrogen (ideally of 24.5ppm) are the only option of coming close to that value. We see in the oxygen portion of the table =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 48.29 352.85 0.51 7.125E+00 0.25 | | O 2 62.86 255.66 0.71 5.794E+00 0.64 | | O 3 48.29 352.85 0.51 7.125E+00 0.25 | | O 4 62.86 255.66 0.71 5.794E+00 0.64 | | O 5 48.29 352.85 0.51 7.125E+00 0.25 | | O 6 62.86 255.66 0.71 5.794E+00 0.64 | | O 7 48.29 352.85 0.51 7.125E+00 0.25 | | O 8 62.86 255.66 0.71 5.794E+00 0.64 | =============================================================================== that the chemical shift alternates consistently between 48.29 and 62.86. To examine why this is the case we may look at the alanine.cell file in Vesta (or the alanine.pdb file in Materials Studio, or any other option of your choice that shows hydrogen bonding). Similarly to example 1 , we will examine which atoms correspond to which environment. The cell and a purposely highlighted atom are shown below. The oxygens are the red atoms. We see here that there are effectively 2 types of oxygen here - ones with hydrogen bonding (dashed lines joining to a hydrogen (grey atom)) and ones without. Here atom 52 (oxygen ion 8 in the table ; it starts at 44 as there are 44 atoms before it) is selected: this has a chemical shielding value of 62.86ppm, as seen above. When clicking any oxygen with 2 hydrogen bonds it corresponds to an atom number that has a shielding tensor of 62.86ppm, while all the ones with 1 hydrogen bond have a value of 48.29ppm. For this exercise, we have now identified that resonance A comes from a single-hydrogen-bonded oxygen. There are a lot more hydrogens and thus it is harder to find which specific one A is referring to. Because \\delta \\delta (A) - \\delta \\delta (B) = 23.5ppm, we know that the chemical shielding should have a value of around 48.29 - 23.5 = 24.79ppm 48.29 - 23.5 = 24.79ppm From the table, we see that the closest value is 24.01ppm, corresponding to atoms 1, 8, 15 and 22. By clicking on hydrogens until one of those is found, we find that all 3 of those hydrogens are bonded to a nitrogen that is also bonded to 2 other hydrogens and a carbon. It is different from the other 2 hydrogens because the oxygen it is hydrogen-bonded to has no other hydrogen bonds: A and B are hydrogen-bonded to each other. These results are confirmed by the other values provided in the table. To confirm A being oxygen 1 (or 3 or 5... - all the values are identical), C_Q C_Q in the table is 7.125MHz compared to the expected 7.86MHz, and \\eta_Q \\eta_Q is 0.25 compared to the expected 0.28 - the results are very similar. However, this is not the case for hydrogen - a C_Q C_Q of 6.53MHz and an \\eta_Q \\eta_Q of 0.7 are expected, but the castep results are 0.21MHz and 0.06 respectively. In fact, the only ion that comes close to matching the C_Q C_Q eta_Q eta_Q expectation is the other (even-numbered) oxygen type: the oxygen that the hydrogen of interest (1, 8 and 15) is hydrogen-bonded to. Silicates - Quartz and Cristoballite As an extra example, we will now perform similar calculations and corresponding analysis with 2 forms of silicate - cristoballite and quartz. Naturally, we wiil do the castep calculations separately Input and output files For quartz we will use the cell file quartz.cell And the param file quartz.param cut_off_energy = 40 ry xc_functional : PBE fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr elec_energy_tol = 1.0e-12 ry The param file is identical to the alanine one above. For cristoballite we will use the cell file crist.cell And exactly the same param file as above (just named crist.param instead) We then run castep on both crystal structures as usual, getting the output files quartz.castep and crist.castep . Within those files, we will have the same types of tables as above: For quartz: =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 234.54 68.31 0.12 -5.085E+00 0.20 | | O 2 234.54 68.30 0.12 -5.086E+00 0.20 | | O 3 234.54 68.30 0.12 -5.086E+00 0.20 | | O 4 234.54 68.30 0.12 -5.086E+00 0.20 | | O 5 234.54 68.30 0.12 -5.086E+00 0.20 | | O 6 234.54 68.31 0.12 -5.085E+00 0.20 | | Si 1 435.01 -5.44 0.82 2.067E+01 0.72 | | Si 2 435.01 -5.45 0.81 2.067E+01 0.72 | | Si 3 435.01 -5.44 0.82 2.067E+01 0.72 | =============================================================================== and for cristoballite =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 239.47 79.97 0.08 -5.055E+00 0.14 | | O 2 239.47 79.97 0.08 -5.055E+00 0.14 | | O 3 239.47 79.97 0.08 -5.055E+00 0.14 | | O 4 239.47 79.97 0.08 -5.055E+00 0.14 | | O 5 239.47 79.97 0.08 -5.055E+00 0.14 | | O 6 239.47 79.97 0.08 -5.055E+00 0.14 | | O 7 239.47 79.97 0.08 -5.055E+00 0.14 | | O 8 239.47 79.97 0.08 -5.055E+00 0.14 | | Si 1 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 2 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 3 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 4 437.12 -9.36 0.61 -1.077E+01 0.88 | =============================================================================== Analysing and comparing to experiment Like with alanine, we will compare it to an experimental 17 O NMR parameter table - this is shown below as Table 2 \\delta \\delta (ppm) C_Q C_Q (MHz) \\eta_Q \\eta_Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19 Table 2: Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_Q C_Q , and EFG asymmetry \\eta_Q \\eta_Q . This example is much more straightforward - all the atoms of a certain element are identical. We are given that a suitable \\sigma_{ref} \\sigma_{ref} (for oxygen) is 263ppm. Using the equation \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma - used before in Example 1 - we are able to convert the isometric chemical shielding tensor into a relative chemical shift: O in quartz has a shift of 28.46ppm and in cristoballite it has a shift of 23.53ppm","title":"Examples 3 - Alanine and Silicates"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#examples-3-alanine-and-silicates","text":"We now look at some more realistic and complex structures - the amino acid alanine and 2 different silicates: cristoballite and qartz. These are fairly large crystals - to get them to complete in a short time we will run them on a cluster. Use the following number of CPUs: analine - 4 cristoballite - 6 quartz - 13 (these numbers are chosen to give efficient k-point scaling) We will also perform EFG calculations for the above structures and examine the respective data.","title":"Examples 3 - Alanine and Silicates"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#oxygen-17-nmr","text":"Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure.","title":"Oxygen-17 NMR"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#alanine","text":"","title":"Alanine"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#examining-input-and-output","text":"We will use the cell file alanine.cell Note Don't worry about how long/complex it is - it is no different from any other cell file - it just simply defines a large cell and param file alanine.param fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr cut_off_energy = 35 ry xc_functional : PBE Note that the only difference to the previous files is the line magres_task = nmr This leads to EFG calculations being performed. alanine.param](alanine/alanine.param) You may also want to view the file alanine.pdb in Materials Studio or another software - this allows better examination of features like hydrogen bonding. This is the original file downloaded from the Cambridge Crystallographic Database (and was used to obtain the alanine.cell file). The cell structure was obtained experimentally by neutron diffraction. We will now run castep. The alanine.castep output file should contain the table This is much like our previous results , except there are now 2 more columns - C_Q C_Q and Eta Eta - these are both there because an EFG calculation was now performed. This result is not fully converged (we will not be testing this in this tutorial, but feel free to check), but the relative shift between some of the sites is converged (again you may verify that if inclined).","title":"Examining input and output"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#analysing-and-comparing-to-experiment","text":"We will now compare these results with experiment. The figure below is an experimental 17 O NMR spectrum of L-alanine. It shows 2 peaks, which are very broad due to the quadripolar coupling, and overlap. Fig3. Solid-State 17 O NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) The experimental parameters are given in Table 1 below. \\delta \\delta (A)- \\delta \\delta (B) (ppm) 23.5 C_Q C_Q (A) (MHz) 7.86 \\eta_Q \\eta_Q (A) 0.28 C_Q C_Q (B) (MHz) 6.53 \\eta_Q \\eta_Q (B) 0.70 Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labelled A and B. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_{Q} C_{Q} , and EFG asymmetry \\eta_Q \\eta_Q . From this, we will try to find what A and B are. To do so, we will look at the alanine.castep tensor table . By a quick glance at the table, we see that the the chemical shift of hydrogen ranges from 20-30ppm, carbon around 0, 124 or 159ppm, nitrogen 194ppm and oxygen 48 or 63ppm. Because of this we can tell that the 2 resonances are going to belong to carbon and oxygen: to get a chemical shift difference of 23.5ppm, oxygen's 48ppm and a hydrogen (ideally of 24.5ppm) are the only option of coming close to that value. We see in the oxygen portion of the table =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 48.29 352.85 0.51 7.125E+00 0.25 | | O 2 62.86 255.66 0.71 5.794E+00 0.64 | | O 3 48.29 352.85 0.51 7.125E+00 0.25 | | O 4 62.86 255.66 0.71 5.794E+00 0.64 | | O 5 48.29 352.85 0.51 7.125E+00 0.25 | | O 6 62.86 255.66 0.71 5.794E+00 0.64 | | O 7 48.29 352.85 0.51 7.125E+00 0.25 | | O 8 62.86 255.66 0.71 5.794E+00 0.64 | =============================================================================== that the chemical shift alternates consistently between 48.29 and 62.86. To examine why this is the case we may look at the alanine.cell file in Vesta (or the alanine.pdb file in Materials Studio, or any other option of your choice that shows hydrogen bonding). Similarly to example 1 , we will examine which atoms correspond to which environment. The cell and a purposely highlighted atom are shown below. The oxygens are the red atoms. We see here that there are effectively 2 types of oxygen here - ones with hydrogen bonding (dashed lines joining to a hydrogen (grey atom)) and ones without. Here atom 52 (oxygen ion 8 in the table ; it starts at 44 as there are 44 atoms before it) is selected: this has a chemical shielding value of 62.86ppm, as seen above. When clicking any oxygen with 2 hydrogen bonds it corresponds to an atom number that has a shielding tensor of 62.86ppm, while all the ones with 1 hydrogen bond have a value of 48.29ppm. For this exercise, we have now identified that resonance A comes from a single-hydrogen-bonded oxygen. There are a lot more hydrogens and thus it is harder to find which specific one A is referring to. Because \\delta \\delta (A) - \\delta \\delta (B) = 23.5ppm, we know that the chemical shielding should have a value of around 48.29 - 23.5 = 24.79ppm 48.29 - 23.5 = 24.79ppm From the table, we see that the closest value is 24.01ppm, corresponding to atoms 1, 8, 15 and 22. By clicking on hydrogens until one of those is found, we find that all 3 of those hydrogens are bonded to a nitrogen that is also bonded to 2 other hydrogens and a carbon. It is different from the other 2 hydrogens because the oxygen it is hydrogen-bonded to has no other hydrogen bonds: A and B are hydrogen-bonded to each other. These results are confirmed by the other values provided in the table. To confirm A being oxygen 1 (or 3 or 5... - all the values are identical), C_Q C_Q in the table is 7.125MHz compared to the expected 7.86MHz, and \\eta_Q \\eta_Q is 0.25 compared to the expected 0.28 - the results are very similar. However, this is not the case for hydrogen - a C_Q C_Q of 6.53MHz and an \\eta_Q \\eta_Q of 0.7 are expected, but the castep results are 0.21MHz and 0.06 respectively. In fact, the only ion that comes close to matching the C_Q C_Q eta_Q eta_Q expectation is the other (even-numbered) oxygen type: the oxygen that the hydrogen of interest (1, 8 and 15) is hydrogen-bonded to.","title":"Analysing and comparing to experiment"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#silicates-quartz-and-cristoballite","text":"As an extra example, we will now perform similar calculations and corresponding analysis with 2 forms of silicate - cristoballite and quartz. Naturally, we wiil do the castep calculations separately","title":"Silicates - Quartz and Cristoballite"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#input-and-output-files","text":"For quartz we will use the cell file quartz.cell And the param file quartz.param cut_off_energy = 40 ry xc_functional : PBE fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr elec_energy_tol = 1.0e-12 ry The param file is identical to the alanine one above. For cristoballite we will use the cell file crist.cell And exactly the same param file as above (just named crist.param instead) We then run castep on both crystal structures as usual, getting the output files quartz.castep and crist.castep . Within those files, we will have the same types of tables as above: For quartz: =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 234.54 68.31 0.12 -5.085E+00 0.20 | | O 2 234.54 68.30 0.12 -5.086E+00 0.20 | | O 3 234.54 68.30 0.12 -5.086E+00 0.20 | | O 4 234.54 68.30 0.12 -5.086E+00 0.20 | | O 5 234.54 68.30 0.12 -5.086E+00 0.20 | | O 6 234.54 68.31 0.12 -5.085E+00 0.20 | | Si 1 435.01 -5.44 0.82 2.067E+01 0.72 | | Si 2 435.01 -5.45 0.81 2.067E+01 0.72 | | Si 3 435.01 -5.44 0.82 2.067E+01 0.72 | =============================================================================== and for cristoballite =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 239.47 79.97 0.08 -5.055E+00 0.14 | | O 2 239.47 79.97 0.08 -5.055E+00 0.14 | | O 3 239.47 79.97 0.08 -5.055E+00 0.14 | | O 4 239.47 79.97 0.08 -5.055E+00 0.14 | | O 5 239.47 79.97 0.08 -5.055E+00 0.14 | | O 6 239.47 79.97 0.08 -5.055E+00 0.14 | | O 7 239.47 79.97 0.08 -5.055E+00 0.14 | | O 8 239.47 79.97 0.08 -5.055E+00 0.14 | | Si 1 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 2 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 3 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 4 437.12 -9.36 0.61 -1.077E+01 0.88 | ===============================================================================","title":"Input and output files"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#analysing-and-comparing-to-experiment_1","text":"Like with alanine, we will compare it to an experimental 17 O NMR parameter table - this is shown below as Table 2 \\delta \\delta (ppm) C_Q C_Q (MHz) \\eta_Q \\eta_Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19 Table 2: Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_Q C_Q , and EFG asymmetry \\eta_Q \\eta_Q . This example is much more straightforward - all the atoms of a certain element are identical. We are given that a suitable \\sigma_{ref} \\sigma_{ref} (for oxygen) is 263ppm. Using the equation \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma - used before in Example 1 - we are able to convert the isometric chemical shielding tensor into a relative chemical shift: O in quartz has a shift of 28.46ppm and in cristoballite it has a shift of 23.53ppm","title":"Analysing and comparing to experiment"},{"location":"tutorials/Optics/JDOS/","text":"JDOS The JDOS (Joint Density of States) is effectively the density of states for an energy range which is equal to the difference between conduction and valence bands - this leads to being able to calculate the probability of an excitation occurring for a given photon energy. One can intuitively understand how this leads to the calculation of optical properties: photons that have energies that correspond to gaps between conduction and valence bands will interact with the material and give rise to its optical properties. In this tutorial, we will calculate the JDOS for silicon, and then relate that to the imaginary and real part of the dielectric function. JDOS Calculation Let's start by actually getting the JDOS results. Run Castep on the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 and param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 Afterwards, run Optados with the Optados input file Si.odi TASK : jdos JDOS_MAX_ENERGY : 30 JDOS_SPACING : 0.01 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default The line TASK : jdos is what tells it to calculate the JDOS in which we are interested. This will generate the file Si.jadaptive.dat (as well as the accompanying agr file). The dat file data table should start like this 0.0000000000000E+00 0.3375085335870E-14 0.1000333444481E-01 0.3869643667676E-14 The 1 st column is the energy, and the 2 nd is the JDOS. The agr file allows us to make a nice plot with xmgrace (though of course you could plot the results with your software of choice) - let's run xmgrace Si.jadaptive.agr The result should look like this: Imaginary Dielectric Now that we have the results, let's examine how they are used to get the dielectric function. You may immediately notice that the shape of the graph above is completely different from either component of the dielectric function. We will need to process the results for them to be meaningful. We will start processing the data by using the Python script energies = [] imaginaries = [] input_file = 'Si.jadaptive.dat' output_file = 'imaginary.dat' new_lines = [] with open ( input_file , 'r' ) as infile : for line in infile : if \"#\" in line : continue parts = line . split () if len ( parts ) == 2 : energy = float ( parts [ 0 ]) jdos = float ( parts [ 1 ]) energies . append ( energy ) if jdos == 0.0 or energy == 0 : eps2 = 0 else : eps2 = ( jdos / energy ** 2 ) imaginaries . append ( eps2 ) new_line = f \" { energy } { jdos } { test } \\n \" new_lines . append ( new_line ) with open ( output_file , 'w' ) as outfile : outfile . writelines ( new_lines ) This creates a new file imaginary.dat that contains the energy, JDOS and our first approximation of the imaginary dielectric function in the 3 rd column. This is approximated by the relationship \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} which was implemented in the line eps2 = ( jdos / energy ** 2 ) We can plot this dat file by using xmgrace on the batch script plot.bat READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" to get just the imaginary output. The graph should look like this: We're starting to see a bit of a resemblance to the imaginary component of the imaginary dielectric function, but it still clearly has room for improvement - the calculation is performed by multiplying what we found by a matrix element, which in this case we are assuming to be constant with energy - which is not the case in reality. We can improve the approximation by using the relationship \\epsilon_2 \\propto \\frac{1}{m^*} \\epsilon_2 \\propto \\frac{1}{m^*} This is a hard thing to implement properly; the effective mass is very difficult to get, depends on position in k-space etc. However, we can simply this with the approximation that, near the band edges, the effective mass is directly proportional to the energy. Note This does have some mathematical merit - if you wish to see where this comes from, have a look at this paper Let's change the line where eps2 is calculated in the Python script to eps2 = ( dos / energy ** 3 ) Re-running the same procedure now yields the graph: At a glance, you can see that it levels off much more quickly - just as it happens in the more-properly calculated dielectric function. To confirm that the results are reasonable, let's plot this together with the results from an actual Optados optics calculation. You can see how to obtain this data at the start of the optics tutorial , or you can download the relevant dat file here . Because we have gotten the results using simple proportionality relations, we'll have to scale the results to make them match experiment - adjust the Python script by changing the eps2 calculation line to eps2 = (dos/energy**3) * 650 650 was found by trial and error to give a reasonable match - again this is simply estimating the constant of proportionality that has been ignored throughout this approximation. You can use the batch file READ BLOCK \"Si_epsilon.dat\" BLOCK XY \"1:3\" S0 LEGEND \"Optics Calculated\" READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" S1 LEGEND \"JDOS Approximated\" to plot it with xmgrace. You can see that they are fairly similar in the graph produced: Real Dielectric We have seen how the JDOS is used to calculate the imaginary dielectric function, and now we will look at how the real component is calculated. The real component is actually calculated only using the imaginary component, using the Kramers-Kroniger relations - and we will demonstrate that. The equation we will use is \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' We'll ignore the constants of proportionality again and just adjust the results. Adding this block of code to the previous Python script import numpy as np energies_arr = np . array ( energies ) eps2_arr = np . array ( imaginaries ) def kramers (): eps1_arr = [] for i , e in enumerate ( energies_arr ): real = 0 sub = ( energies_arr ** 2 ) - ( e ** 2 ) sub [ i ] = np . inf integrand = ( energies_arr * eps2_arr ) / sub real = 1 + 0.6 ( np . trapz ( integrand , energies_arr )) eps1_arr . append ( real ) return eps1_arr eps1_arr = kramers () data = np . column_stack (( energies_arr , eps2_arr , eps1_arr )) np . savetxt ( \"both.dat\" , data ) The implementation is fairly straightforward: for every energy: the integral as in the equation is simply performed for every energy. While adding 1 to the integral is specified in the equation, again the constant of proportionality was found by trial and error until it was a decent fit (and the imaginary part was already scaled the same way). The data is then saved in both.dat with the 1 st column being energy, the 2 nd imaginary dielectric and the 3 rd real dielectric. Let's now compare the imaginary components using xmgrace. Adjust the batch file appropriately, and you should get a graph that looks like: Now we have demonstrated how both parts of the dielectric are related to the JDOS. Sampling Parameters We will now have a look at the effect of increasing and decreasing the JDOS_MAX_ENERGY and JDOS_SPACING parameters. JDOS_MAX_ENERGY determines the highest energy band that is examined, while JDOS_SPACING determines how frequently the results are sampled. We will perform exactly the same procedure as above (including calculating the real and imaginary dielectric - this is the crucial part). It is recommended that you do these calculations in new directories to make it easier to compare results. Maximum Energy Let's first look at increasing and decreasing the maximum energy. We'll start off by increasing it to 100eV. Run the full procedure as above (ending up with both.dat in the new directory), except with the odi file having the line JDOS_MAX_ENERGY : 100 instead of 30. In this case, it is most useful to compare with the result we got from the 30eV maximum energy - plot them both on the same graph. This is what was obtained using an appropriate batch file: We see that the overlap is virtually perfect: sampling beyond 30eV does not improve any results. This indicates that all contributing bands have an energy of 30eV or lower. Let's now try lowering the maximum energy. If we try 20eV and plotting it together with the 30eV result the same way we see this: Now the overlap is no longer perfect: especially towards the end, the real part is becoming increasingly different. Feel free to try different lower energies - you should notice that the lower the maximum energy, the more different the real part becomes, while the imaginary component is unchanging. The example below is for very low 5eV: This shows us that the imaginary component is calculated independently for each energy, but, because the real component is calculated by integrating over all energies, the imaginary component becomes increasingly incorrect as the integral becomes performed not over the full relevant range. Spacing Now let's try decreasing and increasing the rate of sampling by changing the JDOS_SPACING parameter. We will compare it to the standard 0.01eV results we calculated before. First, let's try lowering it - be warned that making it too low will make the python script used to get the real component run extremely slowly; the integral becomes too demanding with too many points. JDOS_SPACING : 0.0005 was used in for the result below: We see here that the results are virtually the same for low and high frequencies, and even the middle part is mostly the same, except for a very narrow range of energies - precisely where the most extreme jumps are occurring. Having a larger sampling failed to capture the largest increases, and increasing the sampling rate meant that they are now seen. Since the other parts of the dielectric function doesn't have such extreme changes, nothing was missed by a slightly higher sampling spacing. Let's now have a look at what happens when we increase the spacing. The result is about what you'd expect: the graph simply loses some of the detail, as seen below. The graph is smoothened out, and, if you were to increase the spacing further, increasing amounts of detail would be lost. Though both results are affected, the real component is more affected: due to it being calculated by integrating the imaginary part, it is much more sensitive to any kind of change in sampling.","title":"JDOS"},{"location":"tutorials/Optics/JDOS/#jdos","text":"The JDOS (Joint Density of States) is effectively the density of states for an energy range which is equal to the difference between conduction and valence bands - this leads to being able to calculate the probability of an excitation occurring for a given photon energy. One can intuitively understand how this leads to the calculation of optical properties: photons that have energies that correspond to gaps between conduction and valence bands will interact with the material and give rise to its optical properties. In this tutorial, we will calculate the JDOS for silicon, and then relate that to the imaginary and real part of the dielectric function.","title":"JDOS"},{"location":"tutorials/Optics/JDOS/#jdos-calculation","text":"Let's start by actually getting the JDOS results. Run Castep on the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 and param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 Afterwards, run Optados with the Optados input file Si.odi TASK : jdos JDOS_MAX_ENERGY : 30 JDOS_SPACING : 0.01 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default The line TASK : jdos is what tells it to calculate the JDOS in which we are interested. This will generate the file Si.jadaptive.dat (as well as the accompanying agr file). The dat file data table should start like this 0.0000000000000E+00 0.3375085335870E-14 0.1000333444481E-01 0.3869643667676E-14 The 1 st column is the energy, and the 2 nd is the JDOS. The agr file allows us to make a nice plot with xmgrace (though of course you could plot the results with your software of choice) - let's run xmgrace Si.jadaptive.agr The result should look like this:","title":"JDOS Calculation"},{"location":"tutorials/Optics/JDOS/#imaginary-dielectric","text":"Now that we have the results, let's examine how they are used to get the dielectric function. You may immediately notice that the shape of the graph above is completely different from either component of the dielectric function. We will need to process the results for them to be meaningful. We will start processing the data by using the Python script energies = [] imaginaries = [] input_file = 'Si.jadaptive.dat' output_file = 'imaginary.dat' new_lines = [] with open ( input_file , 'r' ) as infile : for line in infile : if \"#\" in line : continue parts = line . split () if len ( parts ) == 2 : energy = float ( parts [ 0 ]) jdos = float ( parts [ 1 ]) energies . append ( energy ) if jdos == 0.0 or energy == 0 : eps2 = 0 else : eps2 = ( jdos / energy ** 2 ) imaginaries . append ( eps2 ) new_line = f \" { energy } { jdos } { test } \\n \" new_lines . append ( new_line ) with open ( output_file , 'w' ) as outfile : outfile . writelines ( new_lines ) This creates a new file imaginary.dat that contains the energy, JDOS and our first approximation of the imaginary dielectric function in the 3 rd column. This is approximated by the relationship \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} which was implemented in the line eps2 = ( jdos / energy ** 2 ) We can plot this dat file by using xmgrace on the batch script plot.bat READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" to get just the imaginary output. The graph should look like this: We're starting to see a bit of a resemblance to the imaginary component of the imaginary dielectric function, but it still clearly has room for improvement - the calculation is performed by multiplying what we found by a matrix element, which in this case we are assuming to be constant with energy - which is not the case in reality. We can improve the approximation by using the relationship \\epsilon_2 \\propto \\frac{1}{m^*} \\epsilon_2 \\propto \\frac{1}{m^*} This is a hard thing to implement properly; the effective mass is very difficult to get, depends on position in k-space etc. However, we can simply this with the approximation that, near the band edges, the effective mass is directly proportional to the energy. Note This does have some mathematical merit - if you wish to see where this comes from, have a look at this paper Let's change the line where eps2 is calculated in the Python script to eps2 = ( dos / energy ** 3 ) Re-running the same procedure now yields the graph: At a glance, you can see that it levels off much more quickly - just as it happens in the more-properly calculated dielectric function. To confirm that the results are reasonable, let's plot this together with the results from an actual Optados optics calculation. You can see how to obtain this data at the start of the optics tutorial , or you can download the relevant dat file here . Because we have gotten the results using simple proportionality relations, we'll have to scale the results to make them match experiment - adjust the Python script by changing the eps2 calculation line to eps2 = (dos/energy**3) * 650 650 was found by trial and error to give a reasonable match - again this is simply estimating the constant of proportionality that has been ignored throughout this approximation. You can use the batch file READ BLOCK \"Si_epsilon.dat\" BLOCK XY \"1:3\" S0 LEGEND \"Optics Calculated\" READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" S1 LEGEND \"JDOS Approximated\" to plot it with xmgrace. You can see that they are fairly similar in the graph produced:","title":"Imaginary Dielectric"},{"location":"tutorials/Optics/JDOS/#real-dielectric","text":"We have seen how the JDOS is used to calculate the imaginary dielectric function, and now we will look at how the real component is calculated. The real component is actually calculated only using the imaginary component, using the Kramers-Kroniger relations - and we will demonstrate that. The equation we will use is \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' We'll ignore the constants of proportionality again and just adjust the results. Adding this block of code to the previous Python script import numpy as np energies_arr = np . array ( energies ) eps2_arr = np . array ( imaginaries ) def kramers (): eps1_arr = [] for i , e in enumerate ( energies_arr ): real = 0 sub = ( energies_arr ** 2 ) - ( e ** 2 ) sub [ i ] = np . inf integrand = ( energies_arr * eps2_arr ) / sub real = 1 + 0.6 ( np . trapz ( integrand , energies_arr )) eps1_arr . append ( real ) return eps1_arr eps1_arr = kramers () data = np . column_stack (( energies_arr , eps2_arr , eps1_arr )) np . savetxt ( \"both.dat\" , data ) The implementation is fairly straightforward: for every energy: the integral as in the equation is simply performed for every energy. While adding 1 to the integral is specified in the equation, again the constant of proportionality was found by trial and error until it was a decent fit (and the imaginary part was already scaled the same way). The data is then saved in both.dat with the 1 st column being energy, the 2 nd imaginary dielectric and the 3 rd real dielectric. Let's now compare the imaginary components using xmgrace. Adjust the batch file appropriately, and you should get a graph that looks like: Now we have demonstrated how both parts of the dielectric are related to the JDOS.","title":"Real Dielectric"},{"location":"tutorials/Optics/JDOS/#sampling-parameters","text":"We will now have a look at the effect of increasing and decreasing the JDOS_MAX_ENERGY and JDOS_SPACING parameters. JDOS_MAX_ENERGY determines the highest energy band that is examined, while JDOS_SPACING determines how frequently the results are sampled. We will perform exactly the same procedure as above (including calculating the real and imaginary dielectric - this is the crucial part). It is recommended that you do these calculations in new directories to make it easier to compare results.","title":"Sampling Parameters"},{"location":"tutorials/Optics/JDOS/#maximum-energy","text":"Let's first look at increasing and decreasing the maximum energy. We'll start off by increasing it to 100eV. Run the full procedure as above (ending up with both.dat in the new directory), except with the odi file having the line JDOS_MAX_ENERGY : 100 instead of 30. In this case, it is most useful to compare with the result we got from the 30eV maximum energy - plot them both on the same graph. This is what was obtained using an appropriate batch file: We see that the overlap is virtually perfect: sampling beyond 30eV does not improve any results. This indicates that all contributing bands have an energy of 30eV or lower. Let's now try lowering the maximum energy. If we try 20eV and plotting it together with the 30eV result the same way we see this: Now the overlap is no longer perfect: especially towards the end, the real part is becoming increasingly different. Feel free to try different lower energies - you should notice that the lower the maximum energy, the more different the real part becomes, while the imaginary component is unchanging. The example below is for very low 5eV: This shows us that the imaginary component is calculated independently for each energy, but, because the real component is calculated by integrating over all energies, the imaginary component becomes increasingly incorrect as the integral becomes performed not over the full relevant range.","title":"Maximum Energy"},{"location":"tutorials/Optics/JDOS/#spacing","text":"Now let's try decreasing and increasing the rate of sampling by changing the JDOS_SPACING parameter. We will compare it to the standard 0.01eV results we calculated before. First, let's try lowering it - be warned that making it too low will make the python script used to get the real component run extremely slowly; the integral becomes too demanding with too many points. JDOS_SPACING : 0.0005 was used in for the result below: We see here that the results are virtually the same for low and high frequencies, and even the middle part is mostly the same, except for a very narrow range of energies - precisely where the most extreme jumps are occurring. Having a larger sampling failed to capture the largest increases, and increasing the sampling rate meant that they are now seen. Since the other parts of the dielectric function doesn't have such extreme changes, nothing was missed by a slightly higher sampling spacing. Let's now have a look at what happens when we increase the spacing. The result is about what you'd expect: the graph simply loses some of the detail, as seen below. The graph is smoothened out, and, if you were to increase the spacing further, increasing amounts of detail would be lost. Though both results are affected, the real component is more affected: due to it being calculated by integrating the imaginary part, it is much more sensitive to any kind of change in sampling.","title":"Spacing"},{"location":"tutorials/Optics/Optics/","text":"Optics In this tutorial, we will use Optados to examine the optical properties of silicon and aluminium. Silicon Properties For Silicon, we will use the input cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 and the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 IPRINT : 2 Run Castep as usual. When it is done, run Optados on Si with the Optados input file Si.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : polycrystalline # Default OPTICS_LOSSFN_BROADENING : 0.0 After running Optados, we get several output .dat and .agr files. We will now examine them. Epsilon.dat First let's look at the file containing the (polycrystalline) dielectric function - Si_epsilon.dat . The contents of the file look like 0.0000000000000000 14.107263205387552 0.0000000000000000 1.0003334444814937E-002 14.107363765236455 0.0000000000000000 2.0006668889629875E-002 14.107665455817445 0.0000000000000000 3.0010003334444812E-002 14.108168310237140 0.0000000000000000 The 1 st column corresponds to the energy (of the photon interacting with it), the 2 nd is the real component of the dielectric function, and the 3 rd is the imaginary component. The header also contains the results of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') # Result of sum rule: Neff(E) = 7.0939380864459736 Where N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Let's plot it using xmgrace. Although you could plot the dat file (after configuring a bit to get it to plot everything properly), but luckily Optados has also generated an equivalent agr file that contains the same data, but also formats the xmgrace graph nicely. So let's use xmgrace Si_epsilon.agr and get an output looking like This is a very neat result: it looks just like what you'd expect from the Debye equations This file gives us all the data necessary for the calculation of any optical property of the cell examined. As we will see in the remainder of the tutorial, it is the basis of the generation of all the other files. Absorption Next let's look at the absorption data. The dat file is very similar, this time with 2 columns: the 1 st is the energy of the photon, and the 2 nd is the absorption coefficient. It doesn't look particularly different, but if you wish to check, the data table should start like 0.0000000000000000 0.0000000000000000 1.0020040080160320E-002 0.0000000000000000 You can plot it with xmgrace the same way as before (again the agr file is prepared by Optados). It should look like this Let's examine how this is calculated. The absorption coefficient is calculated as \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} Where \\omega \\omega is the energy divided by \\hbar \\hbar , \\kappa \\kappa is the imaginary refractive index and c c is the speed of light. \\kappa \\kappa can be easily obtained from the real and imaginary dielectric functions, knowing that the complex refractive index is the square root of the complex dielectric function - this leads to the equation \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} To check that this is really what's going on in the absorption calculation, we can use the Python script import numpy as np c = 3e8 hbar = 6.582119569e-16 def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar kappa = np . sqrt ( 0.5 * ( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c return alpha data = np . loadtxt ( 'Si2_OPTICS_epsilon.dat' ) energy = data [:, 0 ] epsilon_1 = data [:, 1 ] epsilon_2 = data [:, 2 ] result = calculate_property_coefficient ( energy , epsilon_1 , epsilon_2 ) output_data = np . column_stack (( energy , result )) np . savetxt ( 'predicted_abs.dat' , output_data , fmt = ' %e ' , delimiter = ' ' ) If plot this together with Si_absorption.dat , you should get an identical result to above . For the next properties we will calculate, we will also see where they come from using an almost identical Python script: simply change the calculate_property function. Refractive Index Next we will look at the (real and imaginary) refractive index. This data is found in the Si_refractive_index.dat (and .agr ) files. The file is similar to the previous, this time having 3 columns again - the 1 st is energy, the 2 nd is the real refractive index and the 3 rd is the imaginary refractive index. We have already looked at how to calculate the imaginary refractive index above (multiply it by some constants and you have the absorption coefficient). The calculation of the real refractive index is very similar, instead becoming n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} and the accompanying Python script to verify if this is right is also very similar: the function becomes def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar # Convert energy (eV) to angular frequency (rad/s) kappa = np . sqrt ( 0.5 * ( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c # Absorption coefficient (1/m) return alpha If you're not interested in the Python output, just plot the Si_refractive_index.agr file using xmgrace, but if you wish to plot them together it is easiest to use xmgrace -batch double.bat on the batch file double.bat READ BLOCK \"predicted_refractive_indices.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Predicted real\" BLOCK XY \"1:3\" S1 LEGEND \"Predicted imaginary\" READ BLOCK \"Si2_OPTICS_refractive_index.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Optados real\" BLOCK XY \"1:3\" S3 LEGEND \"Optados imaginary\" LEGEND 0.9, 0.9 This gives a graph that looks like this: Once again, the values derived from the dielectric function dataset are identical, so they overlap - confirming for us how the properties are calculated. You may note that the imaginary refractive index's shape is identical to that of the absorption - as we've seen, it's just that multiplied by a constant. Reflectivity Next we will look at the reflectivity. This can be found in Si_reflection.dat (and .agr again). The 1 st column represents the energy, as usual, while the 2 nd is the corresponding reflection coefficient. The reflectivity is calculated using the Fresnel equations , using normal incidence and assuming the incoming light ray is coming out of air/vacuum (real and imaginary refractive index n 1 and n 2 of the first medium = 1). The imaginary component was also neglected. Under these conditions, the equation for reflectivity becomes R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 Where \\tilde{n} \\tilde{n} is the complex refractive index (real + imaginary part). We can implement this in the Python script more easily by separating it into functions to find the refractive indices (like we did before ), and then use that to find the reflectivity. def calculate_refractive_indices ( epsilon_1 , epsilon_2 ): n = np . sqrt (( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) kappa = np . sqrt (( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) return n , kappa def calculate_property ( n , kappa ): n_complex = n + 1 j * kappa reflectivity = np . abs (( n_complex - 1 ) / ( n_complex + 1 )) ** 2 return reflectivity Once again, we plot the output file of the script along with the .dat file and see that they're identical: If you are interested, you could change the Fresnel equation used and appropriately adjust the script to include the imaginary part, see how it behaves coming from a different medium, different angle etc. - there is a lot you could look at in terms of reflectivity. Conductivity Next we will look the optical conductivity of silicon in Si_conductivity.dat . The 1 st column is the energy, while the 2 nd and 3 rd columns are the real and imaginary parts of conductivity, both in the SI units Siemens per meter. The complex optical conductivity can be found by approximating in the high frequency limit and rearranging the equation to: \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) where \\sigma_1 \\sigma_1 is the real part and \\sigma_2 \\sigma_2 is the imaginary. As usual \\epsilon_1 \\epsilon_1 corresponds to the real dielectric and \\epsilon_2 \\epsilon_2 to the imaginary. In this calculation, \\epsilon_\\infty \\epsilon_\\infty is approximated as 1. This can be implemented in our Python script as def calculate_conductivity ( epsilon_1 , epsilon_2 , energy ): omega = energy / hbar sigma_1 = epsilon_0 * omega * epsilon_2 sigma_2 = - epsilon_0 * omega * ( epsilon_1 - epsilon_inf ) return sigma_1 , sigma_2 As in previous cases, make sure all constants are defined and any file/variable names adjusted as you implement it. Since there are 3 columns, it is easier to plot them together - we can simply repurpose our previous batch file - just make sure to change file names as appropriate. The output should look like: Loss Function Lastly, we will examine the loss function in Si_loss_fn.dat . The 1 st column is the energy, while the 2 nd is the loss function for that energy. The header of the file shows the results of the two sum rules associated with the loss function: \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} The loss function itself is calculated rather simply from the dielectric: it is simply the imaginary component of the inverse of the complex dielectric: \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) This leads to \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} Let's implement this into our Python script by changing the function to def calculate_property ( epsilon_1 , epsilon_2 ): loss_function = epsilon_2 / ( epsilon_1 ** 2 + epsilon_2 ** 2 ) return loss_function Plotting it together with Si_loss_fn.dat on xmgrace gives us the graph Changing Parameters Now that we know what Optados optics does and how it works, let's try changing some parameters in the Optados input file Si.odi , and re-running Optados, to see what effects it has. JDOS Parameters First let's have a look at the effect of changing the line JDOS_MAX_ENERGY : 30 . We'll set it to 10 and 100 and plot Si_epsilon.agr using xmgrace. Doing it for 10 gives the graph while 100 gives us You can also compare with the result for 30 . What you should notice is that all the plots are the same - what this does is change the maximum energy it calculates the optical properties up to. The graphs aren't particularly interesting (you could do a higher max energy calculation and just set WORLD XMAX 10 to see it up to 10eV for example), but it does affect the results of the sum rules - which are in headers and thus not seen in graphs. Let's try seeing the results for JDOS_MAX_ENERGY : 2, 5, 10, 30 and 100. In Si_epsilon.dat the sum rule results for the different max energies should be around as follows: JDOS Max E Sum Rule Result 2 1.58E-6 5 4.40 10 6.42 30 7.09 100 7.11 This tells us that at 2eV barely any electrons contribute to the absorption process, at 5eV over half do, and beyond that slowly increasing amounts do. Most electrons seem to act for energies between 2 and 30eV. Meanwhile, the results of the 1 st and 2 nd sum rules in Si_loss_fn look rather different: JDOS Max E Sum Rule 1 Sum Rule 2 2 1.58E-6 2.18E-5 5 4.25E-3 1.54E-2 10 7.07E-2 7.58E-2 30 7.08 1.46 100 7.10 1.46 Here the 1 st rule seems to shoot up much more drastically and in a different region (between 10 and 30eV), while the 2 nd tends towards a different value, and again shoots up faster and in the same region. Now we'll take a look at the effects of changing the JDOS_SPACING value. Let's change JDOS_SPACING : 0.01 to 1 and 0.001. We'll do this for JDOS_MAX_ENERGY : 30 . For 1 the graph looks like while for 0.001 it looks like As we see here, changing JDOS_SPACING simply affects the frequency of the sampling: the smaller the value, the smaller the energy intervals at which it examines the dielectric function and thus the smoother the curve. You may note that the graphs look the same as the when we first did it with the default 0.01 above - 0.01 is sufficient, and increasing the sampling frequency gives us virtually the same results but slower. This is reflected in the sum rule calculations - the higher the spacing, the more rough of an estimate they are, and that typically leads to them being larger, with it not getting much more accurate being 0.01. JDOS Spacing Epsilon Sum Loss Sum 1 Loss Sum 2 0.001 6.73 6.72 1.50 0.01 6.74 6.73 1.50 1 8.28 7.22 1.39 Loss Function Broadening Additional broadening can be included in the calculation of the loss function. This is done by setting the keyword optics_lossfn_broadening in the odi file to a non-zero value. To have a look at what it does, let's set optics_lossfn_broadening : 1 and rerun Optados. The only files that are different are the Si_loss_fn.dat and .agr files - they now contain a 3 rd column. The 1 st is still energy, the 2 nd is the unbroadened spectrum (the same result as when we did it above ), and the 3 rd is the broadened spectrum. Plotting thr agr file using xmgrace gives us this graph: Broadening it has effectively \"smoothed out\" the curve, and the agr file has the unbroadened results for comparison.","title":"Optics"},{"location":"tutorials/Optics/Optics/#optics","text":"In this tutorial, we will use Optados to examine the optical properties of silicon and aluminium.","title":"Optics"},{"location":"tutorials/Optics/Optics/#silicon-properties","text":"For Silicon, we will use the input cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 and the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 IPRINT : 2 Run Castep as usual. When it is done, run Optados on Si with the Optados input file Si.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : polycrystalline # Default OPTICS_LOSSFN_BROADENING : 0.0 After running Optados, we get several output .dat and .agr files. We will now examine them.","title":"Silicon Properties"},{"location":"tutorials/Optics/Optics/#epsilondat","text":"First let's look at the file containing the (polycrystalline) dielectric function - Si_epsilon.dat . The contents of the file look like 0.0000000000000000 14.107263205387552 0.0000000000000000 1.0003334444814937E-002 14.107363765236455 0.0000000000000000 2.0006668889629875E-002 14.107665455817445 0.0000000000000000 3.0010003334444812E-002 14.108168310237140 0.0000000000000000 The 1 st column corresponds to the energy (of the photon interacting with it), the 2 nd is the real component of the dielectric function, and the 3 rd is the imaginary component. The header also contains the results of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') # Result of sum rule: Neff(E) = 7.0939380864459736 Where N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Let's plot it using xmgrace. Although you could plot the dat file (after configuring a bit to get it to plot everything properly), but luckily Optados has also generated an equivalent agr file that contains the same data, but also formats the xmgrace graph nicely. So let's use xmgrace Si_epsilon.agr and get an output looking like This is a very neat result: it looks just like what you'd expect from the Debye equations This file gives us all the data necessary for the calculation of any optical property of the cell examined. As we will see in the remainder of the tutorial, it is the basis of the generation of all the other files.","title":"Epsilon.dat"},{"location":"tutorials/Optics/Optics/#absorption","text":"Next let's look at the absorption data. The dat file is very similar, this time with 2 columns: the 1 st is the energy of the photon, and the 2 nd is the absorption coefficient. It doesn't look particularly different, but if you wish to check, the data table should start like 0.0000000000000000 0.0000000000000000 1.0020040080160320E-002 0.0000000000000000 You can plot it with xmgrace the same way as before (again the agr file is prepared by Optados). It should look like this Let's examine how this is calculated. The absorption coefficient is calculated as \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} Where \\omega \\omega is the energy divided by \\hbar \\hbar , \\kappa \\kappa is the imaginary refractive index and c c is the speed of light. \\kappa \\kappa can be easily obtained from the real and imaginary dielectric functions, knowing that the complex refractive index is the square root of the complex dielectric function - this leads to the equation \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} To check that this is really what's going on in the absorption calculation, we can use the Python script import numpy as np c = 3e8 hbar = 6.582119569e-16 def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar kappa = np . sqrt ( 0.5 * ( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c return alpha data = np . loadtxt ( 'Si2_OPTICS_epsilon.dat' ) energy = data [:, 0 ] epsilon_1 = data [:, 1 ] epsilon_2 = data [:, 2 ] result = calculate_property_coefficient ( energy , epsilon_1 , epsilon_2 ) output_data = np . column_stack (( energy , result )) np . savetxt ( 'predicted_abs.dat' , output_data , fmt = ' %e ' , delimiter = ' ' ) If plot this together with Si_absorption.dat , you should get an identical result to above . For the next properties we will calculate, we will also see where they come from using an almost identical Python script: simply change the calculate_property function.","title":"Absorption"},{"location":"tutorials/Optics/Optics/#refractive-index","text":"Next we will look at the (real and imaginary) refractive index. This data is found in the Si_refractive_index.dat (and .agr ) files. The file is similar to the previous, this time having 3 columns again - the 1 st is energy, the 2 nd is the real refractive index and the 3 rd is the imaginary refractive index. We have already looked at how to calculate the imaginary refractive index above (multiply it by some constants and you have the absorption coefficient). The calculation of the real refractive index is very similar, instead becoming n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} and the accompanying Python script to verify if this is right is also very similar: the function becomes def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar # Convert energy (eV) to angular frequency (rad/s) kappa = np . sqrt ( 0.5 * ( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c # Absorption coefficient (1/m) return alpha If you're not interested in the Python output, just plot the Si_refractive_index.agr file using xmgrace, but if you wish to plot them together it is easiest to use xmgrace -batch double.bat on the batch file double.bat READ BLOCK \"predicted_refractive_indices.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Predicted real\" BLOCK XY \"1:3\" S1 LEGEND \"Predicted imaginary\" READ BLOCK \"Si2_OPTICS_refractive_index.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Optados real\" BLOCK XY \"1:3\" S3 LEGEND \"Optados imaginary\" LEGEND 0.9, 0.9 This gives a graph that looks like this: Once again, the values derived from the dielectric function dataset are identical, so they overlap - confirming for us how the properties are calculated. You may note that the imaginary refractive index's shape is identical to that of the absorption - as we've seen, it's just that multiplied by a constant.","title":"Refractive Index"},{"location":"tutorials/Optics/Optics/#reflectivity","text":"Next we will look at the reflectivity. This can be found in Si_reflection.dat (and .agr again). The 1 st column represents the energy, as usual, while the 2 nd is the corresponding reflection coefficient. The reflectivity is calculated using the Fresnel equations , using normal incidence and assuming the incoming light ray is coming out of air/vacuum (real and imaginary refractive index n 1 and n 2 of the first medium = 1). The imaginary component was also neglected. Under these conditions, the equation for reflectivity becomes R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 Where \\tilde{n} \\tilde{n} is the complex refractive index (real + imaginary part). We can implement this in the Python script more easily by separating it into functions to find the refractive indices (like we did before ), and then use that to find the reflectivity. def calculate_refractive_indices ( epsilon_1 , epsilon_2 ): n = np . sqrt (( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) kappa = np . sqrt (( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) return n , kappa def calculate_property ( n , kappa ): n_complex = n + 1 j * kappa reflectivity = np . abs (( n_complex - 1 ) / ( n_complex + 1 )) ** 2 return reflectivity Once again, we plot the output file of the script along with the .dat file and see that they're identical: If you are interested, you could change the Fresnel equation used and appropriately adjust the script to include the imaginary part, see how it behaves coming from a different medium, different angle etc. - there is a lot you could look at in terms of reflectivity.","title":"Reflectivity"},{"location":"tutorials/Optics/Optics/#conductivity","text":"Next we will look the optical conductivity of silicon in Si_conductivity.dat . The 1 st column is the energy, while the 2 nd and 3 rd columns are the real and imaginary parts of conductivity, both in the SI units Siemens per meter. The complex optical conductivity can be found by approximating in the high frequency limit and rearranging the equation to: \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) where \\sigma_1 \\sigma_1 is the real part and \\sigma_2 \\sigma_2 is the imaginary. As usual \\epsilon_1 \\epsilon_1 corresponds to the real dielectric and \\epsilon_2 \\epsilon_2 to the imaginary. In this calculation, \\epsilon_\\infty \\epsilon_\\infty is approximated as 1. This can be implemented in our Python script as def calculate_conductivity ( epsilon_1 , epsilon_2 , energy ): omega = energy / hbar sigma_1 = epsilon_0 * omega * epsilon_2 sigma_2 = - epsilon_0 * omega * ( epsilon_1 - epsilon_inf ) return sigma_1 , sigma_2 As in previous cases, make sure all constants are defined and any file/variable names adjusted as you implement it. Since there are 3 columns, it is easier to plot them together - we can simply repurpose our previous batch file - just make sure to change file names as appropriate. The output should look like:","title":"Conductivity"},{"location":"tutorials/Optics/Optics/#loss-function","text":"Lastly, we will examine the loss function in Si_loss_fn.dat . The 1 st column is the energy, while the 2 nd is the loss function for that energy. The header of the file shows the results of the two sum rules associated with the loss function: \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} The loss function itself is calculated rather simply from the dielectric: it is simply the imaginary component of the inverse of the complex dielectric: \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) This leads to \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} Let's implement this into our Python script by changing the function to def calculate_property ( epsilon_1 , epsilon_2 ): loss_function = epsilon_2 / ( epsilon_1 ** 2 + epsilon_2 ** 2 ) return loss_function Plotting it together with Si_loss_fn.dat on xmgrace gives us the graph","title":"Loss Function"},{"location":"tutorials/Optics/Optics/#changing-parameters","text":"Now that we know what Optados optics does and how it works, let's try changing some parameters in the Optados input file Si.odi , and re-running Optados, to see what effects it has.","title":"Changing Parameters"},{"location":"tutorials/Optics/Optics/#jdos-parameters","text":"First let's have a look at the effect of changing the line JDOS_MAX_ENERGY : 30 . We'll set it to 10 and 100 and plot Si_epsilon.agr using xmgrace. Doing it for 10 gives the graph while 100 gives us You can also compare with the result for 30 . What you should notice is that all the plots are the same - what this does is change the maximum energy it calculates the optical properties up to. The graphs aren't particularly interesting (you could do a higher max energy calculation and just set WORLD XMAX 10 to see it up to 10eV for example), but it does affect the results of the sum rules - which are in headers and thus not seen in graphs. Let's try seeing the results for JDOS_MAX_ENERGY : 2, 5, 10, 30 and 100. In Si_epsilon.dat the sum rule results for the different max energies should be around as follows: JDOS Max E Sum Rule Result 2 1.58E-6 5 4.40 10 6.42 30 7.09 100 7.11 This tells us that at 2eV barely any electrons contribute to the absorption process, at 5eV over half do, and beyond that slowly increasing amounts do. Most electrons seem to act for energies between 2 and 30eV. Meanwhile, the results of the 1 st and 2 nd sum rules in Si_loss_fn look rather different: JDOS Max E Sum Rule 1 Sum Rule 2 2 1.58E-6 2.18E-5 5 4.25E-3 1.54E-2 10 7.07E-2 7.58E-2 30 7.08 1.46 100 7.10 1.46 Here the 1 st rule seems to shoot up much more drastically and in a different region (between 10 and 30eV), while the 2 nd tends towards a different value, and again shoots up faster and in the same region. Now we'll take a look at the effects of changing the JDOS_SPACING value. Let's change JDOS_SPACING : 0.01 to 1 and 0.001. We'll do this for JDOS_MAX_ENERGY : 30 . For 1 the graph looks like while for 0.001 it looks like As we see here, changing JDOS_SPACING simply affects the frequency of the sampling: the smaller the value, the smaller the energy intervals at which it examines the dielectric function and thus the smoother the curve. You may note that the graphs look the same as the when we first did it with the default 0.01 above - 0.01 is sufficient, and increasing the sampling frequency gives us virtually the same results but slower. This is reflected in the sum rule calculations - the higher the spacing, the more rough of an estimate they are, and that typically leads to them being larger, with it not getting much more accurate being 0.01. JDOS Spacing Epsilon Sum Loss Sum 1 Loss Sum 2 0.001 6.73 6.72 1.50 0.01 6.74 6.73 1.50 1 8.28 7.22 1.39","title":"JDOS Parameters"},{"location":"tutorials/Optics/Optics/#loss-function-broadening","text":"Additional broadening can be included in the calculation of the loss function. This is done by setting the keyword optics_lossfn_broadening in the odi file to a non-zero value. To have a look at what it does, let's set optics_lossfn_broadening : 1 and rerun Optados. The only files that are different are the Si_loss_fn.dat and .agr files - they now contain a 3 rd column. The 1 st is still energy, the 2 nd is the unbroadened spectrum (the same result as when we did it above ), and the 3 rd is the broadened spectrum. Plotting thr agr file using xmgrace gives us this graph: Broadening it has effectively \"smoothed out\" the curve, and the agr file has the unbroadened results for comparison.","title":"Loss Function Broadening"},{"location":"tutorials/Optics/Optics_aluminium/","text":"Optics - Aluminium In this tutorial, we will have brief look at how to calculate the optical properties of metals, looking at aluminium in particular, and how the results are different from a standard Optados optics calculation. It is highly recommended that you first go through the previous tutorial , where we go more into depth on it - this tutorial is mostly just highlighting how it is slightly different for metals. We will use the cell file Al.cell %BLOCK LATTICE_CART 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Al 0.0000000000000000 0.0000000000000000 0.0000000000000000 Al 0.5000000000000000 0.5000000000000000 0.0000000000000000 Al 0.5000000000000000 0.0000000000000000 0.5000000000000000 Al 0.0000000000000000 0.5000000000000000 0.5000000000000000 %ENDBLOCK POSITIONS_FRAC KPOINTS_MP_GRID 15 15 15 SPECTRAL_KPOINTS_MP_GRID 15 15 15 SYMMETRY_GENERATE and param file Al.param TASK : SPECTRAL SPECTRAL_TASK : optics NEXTRA_BANDS : 10 Run Castep as usual. Then run Optados with the Optados input file Al.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 OPTICS_INTRABAND : true EFERMI : optados DOS_SPACING : 0.1 ADAPTIVE_SMEARING : 0.8 BROADENING : adaptive # Default OPTICS_GEOM : polycrystalline # Default There is 1 key difference to before: it contains the line OPTICS_INTRABAND : true . This is to include the intraband contribution, which is necessary for metals. We're starting with the high spacing so we get few results (measuring only at 3 energies) - this makes it easier to have a quick look at what's going on. We will use those results for the remainder of the tutorial. Dielectric Dat File The file Al_epsilon.dat contains the following data: 0.0000000000000000 2.1445746376579851 0.0000000000000000 15.000000000000000 1.1673581523361172 1.6007294583641971 30.000000000000000 0.66031465886470098 0.39432835642313052 0.0000000000000000 -32490.319172606654 NaN 15.000000000000000 0.37438389209757406 2.7452531094084771E-003 30.000000000000000 0.84359371433743857 3.4316159432482577E-004 0.0000000000000000 -32489.174597968995 NaN 15.000000000000000 0.54174204443369112 1.6034747114736059 30.000000000000000 0.50390837320213944 0.39467151801745531 You can see here that there are 3 columns like before (energy, real and imaginary dielectric), but there's 3 separate sets of them, separated by a double space. The 1 st set corresponds to the interband contribution, the 2 nd to the intraband, and the 3 rd to the total. Though normally it'd be easiest to visualise this data by plotting the agr file on xmgrace, this would only give the interband term - if you're interested in other information you will have to use the .dat file. You may choose to use/plot this data in your preferred method, but this tutorial will give you the necessary files to plot it using xmgrace. Firstly, we will create a new file called Al_epsilon_sep.dat file that turns separates the data into columns - we can do that with this Python script . The output file looks like 0.0000000000000000 2.1445746376579851 0.0000000000000000 -32490.3191726066543197 0.0000000000000000 -32489.1745979689949309 0.0000000000000000 15.0000000000000000 1.1673581523361172 1.6007294583641971 0.3743838920975741 0.0027452531094085 0.5417420444336911 1.6034747114736059 30.0000000000000000 0.6603146588647010 0.3943283564231305 0.8435937143374386 0.0003431615943248 0.5039083732021394 0.3946715180174553 It's exactly the same data except all the data is in separate columns now: 1 is still energy, 2 is interband real, 3 is interband imaginary, 4 is intraband real, 5 is intraband imaginary, 6 is total real and 7 is total imaginary dielectric. Now let's make a graph of more useful data: rerun Optados with JDOS_SPACING : 0.01 set instead (to get more data for more meaningful graphs), and rerun the Python script. You could plot it with xmgrace (and using any accompanying batch files as you wish), but it is more convenient to plot it using plotly (and Bokeh to add a bit more functionality) - this is because the values vary greatly. To replicate this, you may use this Python script to use plotly to get a basic output, and to get 1 with a bit of extra functionality (such as being able to manually select the range of values to look at) use this script . Make sure you have all the required libraries installed if doing this: pandas and plotly are required for the 1 st , and Bokeh is also required for the 2 nd . The 1 st generates an output HTML file called interactive_graph.html and the 2 nd generates interactive_graph_extra.html . The latter is embedded here for your convenience: document.addEventListener(\"DOMContentLoaded\", function() { var basePath = window.location.origin; var iframe = document.getElementById(\"embed_link\"); iframe.src = basePath + \"/tutorials/Optics/interactive_graph_extra.html\"; }); Alternatively download the data and HTML file and view it on your browser - or just view that HTML link on a new tab. As loaded, the graph doesn't look great: because the values become extremely high towards 0eV, it just looks like 2 straight lines followed by 0. In the HTML, let's set the y min to -10 and y max to 10. Now we can make some general observations. At very low energies, the total dielectric (both real and imaginary) shoot up/down to extremely large values - it seems to settle down around 2eV The imaginary components tend towards 0, while the real parts tend towards a non-zero finite value Try setting x min to 2 (and y min to -50 - just to get no cut-offs): you'll see that the lines are fairly straightforward beyond 2eV. So let's try examine in more detail what is happening between 0 and 2eV. Feel free to drag and (box)-zoom with the widgets provided in the HTML to look at different sections of the graph. Try looking at the region where energy (x) is between 1.3 and 1.6 - you should see that there is a distinct discontinuity there - while the intraband imaginary term remains close to 0, the interband jumps up (up to around 700) and then goes down - the total is the same. The real part also follows the of shape of the interband contribution, being adjusted slightly by a barely-changing intraband term. Try having a look at other regions in the 0-2eV range to see what else you can find. Other files Running Optados generates the same files as without its contribution, except some of the files are slightly different different. For example, the file Al_epsilon.agr only contains the interband term - it only has 2 columns. Similarly to Al_epsilon.dat , Al_loss_fn.dat contains the interband, intraband and total loss function (though this time the components aren't separated by a double space - you'd have to adjust the Python script used before). Unlike epsilon , the Al_loss_fn.agr file contains all the terms - you can plot all the loss function data easily using xmgrace Al_loss_fn.agr The graph should look a bit like For the loss function, you could also include optics_lossfn_broadening : x where x is the value of broadening you wish to use: this will generate a 4 th column containing the broadened total loss function (again well-included in the agr file) If you change the Optados input file to find the tensor properties - which can be done by changing the line OPTICS_GEOM : POLYCRYSTALLINE to OPTICS_GEOM : TENSOR in Al.odi - you'll also get all the contributions in the outputted Al_epsilon.dat file - so you have 3 parts of 6 components, leading to 18 bits of data in total. Only the dielectric dat output is created.","title":"Optics - Aluminium"},{"location":"tutorials/Optics/Optics_aluminium/#optics-aluminium","text":"In this tutorial, we will have brief look at how to calculate the optical properties of metals, looking at aluminium in particular, and how the results are different from a standard Optados optics calculation. It is highly recommended that you first go through the previous tutorial , where we go more into depth on it - this tutorial is mostly just highlighting how it is slightly different for metals. We will use the cell file Al.cell %BLOCK LATTICE_CART 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Al 0.0000000000000000 0.0000000000000000 0.0000000000000000 Al 0.5000000000000000 0.5000000000000000 0.0000000000000000 Al 0.5000000000000000 0.0000000000000000 0.5000000000000000 Al 0.0000000000000000 0.5000000000000000 0.5000000000000000 %ENDBLOCK POSITIONS_FRAC KPOINTS_MP_GRID 15 15 15 SPECTRAL_KPOINTS_MP_GRID 15 15 15 SYMMETRY_GENERATE and param file Al.param TASK : SPECTRAL SPECTRAL_TASK : optics NEXTRA_BANDS : 10 Run Castep as usual. Then run Optados with the Optados input file Al.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 OPTICS_INTRABAND : true EFERMI : optados DOS_SPACING : 0.1 ADAPTIVE_SMEARING : 0.8 BROADENING : adaptive # Default OPTICS_GEOM : polycrystalline # Default There is 1 key difference to before: it contains the line OPTICS_INTRABAND : true . This is to include the intraband contribution, which is necessary for metals. We're starting with the high spacing so we get few results (measuring only at 3 energies) - this makes it easier to have a quick look at what's going on. We will use those results for the remainder of the tutorial.","title":"Optics - Aluminium"},{"location":"tutorials/Optics/Optics_aluminium/#dielectric-dat-file","text":"The file Al_epsilon.dat contains the following data: 0.0000000000000000 2.1445746376579851 0.0000000000000000 15.000000000000000 1.1673581523361172 1.6007294583641971 30.000000000000000 0.66031465886470098 0.39432835642313052 0.0000000000000000 -32490.319172606654 NaN 15.000000000000000 0.37438389209757406 2.7452531094084771E-003 30.000000000000000 0.84359371433743857 3.4316159432482577E-004 0.0000000000000000 -32489.174597968995 NaN 15.000000000000000 0.54174204443369112 1.6034747114736059 30.000000000000000 0.50390837320213944 0.39467151801745531 You can see here that there are 3 columns like before (energy, real and imaginary dielectric), but there's 3 separate sets of them, separated by a double space. The 1 st set corresponds to the interband contribution, the 2 nd to the intraband, and the 3 rd to the total. Though normally it'd be easiest to visualise this data by plotting the agr file on xmgrace, this would only give the interband term - if you're interested in other information you will have to use the .dat file. You may choose to use/plot this data in your preferred method, but this tutorial will give you the necessary files to plot it using xmgrace. Firstly, we will create a new file called Al_epsilon_sep.dat file that turns separates the data into columns - we can do that with this Python script . The output file looks like 0.0000000000000000 2.1445746376579851 0.0000000000000000 -32490.3191726066543197 0.0000000000000000 -32489.1745979689949309 0.0000000000000000 15.0000000000000000 1.1673581523361172 1.6007294583641971 0.3743838920975741 0.0027452531094085 0.5417420444336911 1.6034747114736059 30.0000000000000000 0.6603146588647010 0.3943283564231305 0.8435937143374386 0.0003431615943248 0.5039083732021394 0.3946715180174553 It's exactly the same data except all the data is in separate columns now: 1 is still energy, 2 is interband real, 3 is interband imaginary, 4 is intraband real, 5 is intraband imaginary, 6 is total real and 7 is total imaginary dielectric. Now let's make a graph of more useful data: rerun Optados with JDOS_SPACING : 0.01 set instead (to get more data for more meaningful graphs), and rerun the Python script. You could plot it with xmgrace (and using any accompanying batch files as you wish), but it is more convenient to plot it using plotly (and Bokeh to add a bit more functionality) - this is because the values vary greatly. To replicate this, you may use this Python script to use plotly to get a basic output, and to get 1 with a bit of extra functionality (such as being able to manually select the range of values to look at) use this script . Make sure you have all the required libraries installed if doing this: pandas and plotly are required for the 1 st , and Bokeh is also required for the 2 nd . The 1 st generates an output HTML file called interactive_graph.html and the 2 nd generates interactive_graph_extra.html . The latter is embedded here for your convenience: document.addEventListener(\"DOMContentLoaded\", function() { var basePath = window.location.origin; var iframe = document.getElementById(\"embed_link\"); iframe.src = basePath + \"/tutorials/Optics/interactive_graph_extra.html\"; }); Alternatively download the data and HTML file and view it on your browser - or just view that HTML link on a new tab. As loaded, the graph doesn't look great: because the values become extremely high towards 0eV, it just looks like 2 straight lines followed by 0. In the HTML, let's set the y min to -10 and y max to 10. Now we can make some general observations. At very low energies, the total dielectric (both real and imaginary) shoot up/down to extremely large values - it seems to settle down around 2eV The imaginary components tend towards 0, while the real parts tend towards a non-zero finite value Try setting x min to 2 (and y min to -50 - just to get no cut-offs): you'll see that the lines are fairly straightforward beyond 2eV. So let's try examine in more detail what is happening between 0 and 2eV. Feel free to drag and (box)-zoom with the widgets provided in the HTML to look at different sections of the graph. Try looking at the region where energy (x) is between 1.3 and 1.6 - you should see that there is a distinct discontinuity there - while the intraband imaginary term remains close to 0, the interband jumps up (up to around 700) and then goes down - the total is the same. The real part also follows the of shape of the interband contribution, being adjusted slightly by a barely-changing intraband term. Try having a look at other regions in the 0-2eV range to see what else you can find.","title":"Dielectric Dat File"},{"location":"tutorials/Optics/Optics_aluminium/#other-files","text":"Running Optados generates the same files as without its contribution, except some of the files are slightly different different. For example, the file Al_epsilon.agr only contains the interband term - it only has 2 columns. Similarly to Al_epsilon.dat , Al_loss_fn.dat contains the interband, intraband and total loss function (though this time the components aren't separated by a double space - you'd have to adjust the Python script used before). Unlike epsilon , the Al_loss_fn.agr file contains all the terms - you can plot all the loss function data easily using xmgrace Al_loss_fn.agr The graph should look a bit like For the loss function, you could also include optics_lossfn_broadening : x where x is the value of broadening you wish to use: this will generate a 4 th column containing the broadened total loss function (again well-included in the agr file) If you change the Optados input file to find the tensor properties - which can be done by changing the line OPTICS_GEOM : POLYCRYSTALLINE to OPTICS_GEOM : TENSOR in Al.odi - you'll also get all the contributions in the outputted Al_epsilon.dat file - so you have 3 parts of 6 components, leading to 18 bits of data in total. Only the dielectric dat output is created.","title":"Other files"},{"location":"tutorials/Optics/Optics_ani/","text":"Optics Optados is capable of getting numerous optical properties of different structures, all of which depend on the wavelength (energy) of light interacting with it. In this tutorial, we will perform an Optados optics calculation on rutile (TiO 2 ) - a birefringent crystal with anisotropic optical properties, examining its single-crystal and polycrystalline (isotropic) properties. Throughout this tutorial, we will be using xmgrace to plot everything, but feel free to use your preferred software. We will use the cell file rut.cell %BLOCK LATTICE_ABC 4.6257000 4.6257000 2.9806000 90.0000000 90.0000000 90.0000000 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_FRAC Ti 0.0000000 0.0000000 0.0000000 O 0.2821000 0.2821000 0.0000000 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 This cell file was obtained using cif2cell using the structure with the COD ID 1010942, found on the Crystallography Open Database We will first run a castep calculation using the above cell with the param file rut.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 Once that is done, we can perform the optical Optados calculations. Demonstrating Birefringence We will begin by examining the dielectric tensor. We will do this by using the Opdatos input file rut.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 60 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : tensor # Default OPTICS_LOSSFN_BROADENING : 0.0 # Default The line TASK : optics is key here, as that is what tells us to perform an optical calculation. The other crucial line is OPTICS_GEOM : tensor - this tells it to calculate the full dielectric tensor of rutile. This produces 2 output files: rut.odo and rut_epsilon.dat - we are interested in the latter. The output file starts off looking like # Component 1 0.0000000000000000 10.985963719914423 0.0000000000000000 1.0001666944490749E-002 10.986133776534746 4.5560614006426980E-003 2.0003333888981498E-002 10.990669467897412 5.9329124271557589E-003 The 1 st column corresponds to energy (in eV), the 2 nd is the real part of the dielectric constant and the 3 rd is the imaginary part. The file contains 6 components, each having their own table. This is bothersome to plot, so let's use a Python script to separate it into its components separate.py input_file = 'rut_epsilon.dat' def write_to_file ( component , lines ): file_name = \"rut_tens\" + str ( component ) + \".dat\" with open ( file_name , \"w\" ) as f : f . writelines ( lines ) with open ( \"rut_tens.dat\" , \"r\" ) as f : lines = f . readlines ()[:: - 1 ] component_lines = [] component = 6 for line in lines : component_lines . append ( line ) if \"Componen\" in line : write_to_file ( component , component_lines ) component -= 1 component_lines = [] Note It is recommended to copy and do this is in a separate directory - we will be comparing this output to subsequent calculations. In future instructions this will be in the directory \"tensors\" We now have 6 files for each component of the 3x3 tensor (keep in mind that it is symmetric ie. \\epsilon_{xy} \\epsilon_{xy} = \\epsilon_{yx} \\epsilon_{yx} ). rut_tens1.dat corresponds to \\epsilon_{xx} \\epsilon_{xx} , 2 and 3 and to yy and zz, while 4, 5 and 6 correspond to xy, xz and yz. Now that we have all the components, let's start actually looking at the results. First, let's plot the real parts of \\epsilon_{xx} \\epsilon_{xx} and \\epsilon_{yy} \\epsilon_{yy} on the same graph. We can do this by using the batch file plot_12_together.bat READ BLOCK \"rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"rut_tens2.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real YY component\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" and plotting it with xmgrace via xmgrace -batch plot_12_together.bat This gives us a graph looking like this: There is only 1 line visible - they (almost) perfectly overlap, meaning that \\epsilon_{xx} \\epsilon_{xx} = \\epsilon_{yy} \\epsilon_{yy} . Now let's try comparing \\epsilon_{xx} \\epsilon_{xx} with \\epsilon_{zz} \\epsilon_{zz} - all you have to do is make the 2 nd block rut_tens3.dat (and change the legend appropriately). This is a rather interesting result: this seems that the dielectric function in different directions is different - the material is optically anisotropic. Since it is identical in 2 directions, it would be considered birefringent. Examining Dielectric Tensor So now that we have the dielectric function tensor, let's examine how this corresponds to its (anisotropic) optical properties We will run Optados again (no need to rerun Castep), changing the line OPTICS_GEOM : tensor in the rut.odi file to the lines OPTICS_GEOM : polarised # Default OPTICS_QDIR : 1 0 0 Let's compare the dielectric function output with the \\epsilon_{xx} \\epsilon_{xx} output we got from the tensor. Run xmgrace rut_epsilon.dat tensors/rut_tens1.dat We will get the same graph as the 1 st one . This is no surprise at all: if light is polarised in the xx direction, it'll effectively feel the \\epsilon_{xx} \\epsilon_{xx} dielectric function. Let's try a more interesting example - change the direction line to OPTICS_QDIR : 1 1 1 Now the result shouldn't align with anything. To demonstrate that let's compare it to \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{zz} \\epsilon_{zz} and \\epsilon_{xy} \\epsilon_{xy} , all on the same graph - luckily xmgrace makes it very easy to plot them together. We'll modify the batch file to include all of them - compare.bat READ BLOCK \"tensors/rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"tensors/rut_tens3.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real ZZ component\" READ BLOCK \"tensors/rut_tens4.dat\" BLOCK xy \"1:2\" S2 LEGEND \"Real XY component\" READ BLOCK \"rut_epsilon.dat\" BLOCK xy \"1:2\" S3 LEGEND \"1 1 1 result\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" WORLD XMAX 5 We have also made the graph smaller (only goes up to 5eV) in the last line to make it easier to see overlaps (or lack of them). This is the kind of output we get: You can try comparing it to any other value, but you'll find it's completely different. So how is this related to the tensor? Considering the properties of tensors in general, we know that the value from a tensor in any direction is given by the equation \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} Where \\epsilon' \\epsilon' is the dielectric constant in the direction of \\hat{\\mathbf{n}} \\hat{\\mathbf{n}} , and \\mathbf{\\epsilon} \\mathbf{\\epsilon} is the dielectric matrix. Note In this tutorial, a symbol being bold and underlined (like \\underline{\\mathbf{\\epsilon}} \\underline{\\mathbf{\\epsilon}} ) shows that it's a matrix, while being just bold (like \\mathbf{n} \\mathbf{n} ) shows that it's a vector. Let's quickly work through what we'd expect in the (111) direction and compare that with what we get from Optados. To get $$ \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} $$ we do \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} Then to get the final result we do \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) $$ = \\frac{1}{3} \\bigg ( \\epsilon_{xx} + \\epsilon_{yy} + \\epsilon_{zz} + 2(\\epsilon_{xy} + \\epsilon_{yz} + \\epsilon_{zx}) \\bigg ) $$ Let's check if this is true using our separated dielectric function tensor files. We will get a function that is equal to the above equation using a Python script, and plot it on the same graph as the case polarised in the (111) direction. You may use the script get_in_direction.py import numpy as np eps = { key : np . loadtxt ( f \"rut_tens { i } .dat\" ) for i , key in enumerate (( 'xx' , 'yy' , 'zz' , 'xy' , 'xz' , 'yz' ))} eps_vals = { key : val [:, 1 ] for key , val in eps . items ()} energies = eps [ 'xx' ][:, 0 ] eps_111_values = ( sum ( eps [ ind ] for ind in ( 'xx' , 'yy' , 'zz' )) + 2 * sum ( eps [ ind ] for ind in ( 'xy' , 'xz' , 'yz' )) / 3 output_data = np . column_stack (( energies , eps_111_values )) output_filename = \"rut_111_out.dat\" np . savetxt ( output_filename , output_data , fmt = ' % .16e ' , header = \"Energy (eV) Effective Epsilon_111\" ) This gives the output of the above equation acting on the dielectric function tensor we calculate, stored in rut_111.dat . Now let's see if the 2 results agree: let's try xmgrace rut_epsilon.dat tensors/rut_111_out.dat Using rut_epsilon.dat from our last Optados calculation . We should see that the lines almost perfectly overlap: Now we properly understand what is going on when choosing a certain polarisation direction, and what the dielectric function tensor truly means. Isotropic Dielectric Function There is another case to have a look at: what is the dielectric function when the material is polycrystalline, and thus behaves isotropically? Optados can easily find this by changing the keyword in the rut.odi file to OPTICS_GEOM : tensor and removing the OPTICS_QDIR line (as the direction no longer matters). If you wish to verify how this is being calculated, use the same Python script as above but change the calculation eps_111_values = ( eps [ 'xx' ] + eps [ 'yy' ] + eps [ 'zz' ] + 2 * eps [ 'xy' ] + 2 * eps [ 'xz' ] + 2 * eps [ 'yz' ]) / 3 to for i in range ( len ( energies )): tensor = np . array ([ [ eps [ 'xx' ][ i ], eps [ 'xy' ][ i ], eps [ 'xz' ][ i ]], [ eps [ 'xy' ][ i ], eps [ 'yy' ][ i ], eps [ 'yz' ][ i ]], [ eps [ 'xz' ][ i ], eps [ 'yz' ][ i ], eps [ 'zz' ][ i ]] ]) eigenvalues = np . linalg . eigvals ( tensor ) iso_value = np . mean ( eigenvalues ) iso_values . append ( eps_111_value ) and change variable, output file name etc. as appropraite output_data = np . column_stack (( energies , iso_values )) output_filename = \"rut_111_eigen.dat\" This gives us the average of the eigenvalues of the dielectric matrix for every enegy, giving us the isotropic value. Let's plot them together to see if they're identical: xmgrace rut_epsilon.dat tensors/rut_111_eigen.dat We get a graph looking like this: As expected, the 2 lines overlap: this demonstrates that the polycrystalline calculation is effectively the \"average\" of the dielectric tensor in all directions, which is what we'd expect for a polycrystalline sample, where we can assume that all directions are equally likely.","title":"Optical Anisotropy"},{"location":"tutorials/Optics/Optics_ani/#optics","text":"Optados is capable of getting numerous optical properties of different structures, all of which depend on the wavelength (energy) of light interacting with it. In this tutorial, we will perform an Optados optics calculation on rutile (TiO 2 ) - a birefringent crystal with anisotropic optical properties, examining its single-crystal and polycrystalline (isotropic) properties. Throughout this tutorial, we will be using xmgrace to plot everything, but feel free to use your preferred software. We will use the cell file rut.cell %BLOCK LATTICE_ABC 4.6257000 4.6257000 2.9806000 90.0000000 90.0000000 90.0000000 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_FRAC Ti 0.0000000 0.0000000 0.0000000 O 0.2821000 0.2821000 0.0000000 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 This cell file was obtained using cif2cell using the structure with the COD ID 1010942, found on the Crystallography Open Database We will first run a castep calculation using the above cell with the param file rut.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 Once that is done, we can perform the optical Optados calculations.","title":"Optics"},{"location":"tutorials/Optics/Optics_ani/#demonstrating-birefringence","text":"We will begin by examining the dielectric tensor. We will do this by using the Opdatos input file rut.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 60 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : tensor # Default OPTICS_LOSSFN_BROADENING : 0.0 # Default The line TASK : optics is key here, as that is what tells us to perform an optical calculation. The other crucial line is OPTICS_GEOM : tensor - this tells it to calculate the full dielectric tensor of rutile. This produces 2 output files: rut.odo and rut_epsilon.dat - we are interested in the latter. The output file starts off looking like # Component 1 0.0000000000000000 10.985963719914423 0.0000000000000000 1.0001666944490749E-002 10.986133776534746 4.5560614006426980E-003 2.0003333888981498E-002 10.990669467897412 5.9329124271557589E-003 The 1 st column corresponds to energy (in eV), the 2 nd is the real part of the dielectric constant and the 3 rd is the imaginary part. The file contains 6 components, each having their own table. This is bothersome to plot, so let's use a Python script to separate it into its components separate.py input_file = 'rut_epsilon.dat' def write_to_file ( component , lines ): file_name = \"rut_tens\" + str ( component ) + \".dat\" with open ( file_name , \"w\" ) as f : f . writelines ( lines ) with open ( \"rut_tens.dat\" , \"r\" ) as f : lines = f . readlines ()[:: - 1 ] component_lines = [] component = 6 for line in lines : component_lines . append ( line ) if \"Componen\" in line : write_to_file ( component , component_lines ) component -= 1 component_lines = [] Note It is recommended to copy and do this is in a separate directory - we will be comparing this output to subsequent calculations. In future instructions this will be in the directory \"tensors\" We now have 6 files for each component of the 3x3 tensor (keep in mind that it is symmetric ie. \\epsilon_{xy} \\epsilon_{xy} = \\epsilon_{yx} \\epsilon_{yx} ). rut_tens1.dat corresponds to \\epsilon_{xx} \\epsilon_{xx} , 2 and 3 and to yy and zz, while 4, 5 and 6 correspond to xy, xz and yz. Now that we have all the components, let's start actually looking at the results. First, let's plot the real parts of \\epsilon_{xx} \\epsilon_{xx} and \\epsilon_{yy} \\epsilon_{yy} on the same graph. We can do this by using the batch file plot_12_together.bat READ BLOCK \"rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"rut_tens2.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real YY component\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" and plotting it with xmgrace via xmgrace -batch plot_12_together.bat This gives us a graph looking like this: There is only 1 line visible - they (almost) perfectly overlap, meaning that \\epsilon_{xx} \\epsilon_{xx} = \\epsilon_{yy} \\epsilon_{yy} . Now let's try comparing \\epsilon_{xx} \\epsilon_{xx} with \\epsilon_{zz} \\epsilon_{zz} - all you have to do is make the 2 nd block rut_tens3.dat (and change the legend appropriately). This is a rather interesting result: this seems that the dielectric function in different directions is different - the material is optically anisotropic. Since it is identical in 2 directions, it would be considered birefringent.","title":"Demonstrating Birefringence"},{"location":"tutorials/Optics/Optics_ani/#examining-dielectric-tensor","text":"So now that we have the dielectric function tensor, let's examine how this corresponds to its (anisotropic) optical properties We will run Optados again (no need to rerun Castep), changing the line OPTICS_GEOM : tensor in the rut.odi file to the lines OPTICS_GEOM : polarised # Default OPTICS_QDIR : 1 0 0 Let's compare the dielectric function output with the \\epsilon_{xx} \\epsilon_{xx} output we got from the tensor. Run xmgrace rut_epsilon.dat tensors/rut_tens1.dat We will get the same graph as the 1 st one . This is no surprise at all: if light is polarised in the xx direction, it'll effectively feel the \\epsilon_{xx} \\epsilon_{xx} dielectric function. Let's try a more interesting example - change the direction line to OPTICS_QDIR : 1 1 1 Now the result shouldn't align with anything. To demonstrate that let's compare it to \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{zz} \\epsilon_{zz} and \\epsilon_{xy} \\epsilon_{xy} , all on the same graph - luckily xmgrace makes it very easy to plot them together. We'll modify the batch file to include all of them - compare.bat READ BLOCK \"tensors/rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"tensors/rut_tens3.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real ZZ component\" READ BLOCK \"tensors/rut_tens4.dat\" BLOCK xy \"1:2\" S2 LEGEND \"Real XY component\" READ BLOCK \"rut_epsilon.dat\" BLOCK xy \"1:2\" S3 LEGEND \"1 1 1 result\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" WORLD XMAX 5 We have also made the graph smaller (only goes up to 5eV) in the last line to make it easier to see overlaps (or lack of them). This is the kind of output we get: You can try comparing it to any other value, but you'll find it's completely different. So how is this related to the tensor? Considering the properties of tensors in general, we know that the value from a tensor in any direction is given by the equation \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} Where \\epsilon' \\epsilon' is the dielectric constant in the direction of \\hat{\\mathbf{n}} \\hat{\\mathbf{n}} , and \\mathbf{\\epsilon} \\mathbf{\\epsilon} is the dielectric matrix. Note In this tutorial, a symbol being bold and underlined (like \\underline{\\mathbf{\\epsilon}} \\underline{\\mathbf{\\epsilon}} ) shows that it's a matrix, while being just bold (like \\mathbf{n} \\mathbf{n} ) shows that it's a vector. Let's quickly work through what we'd expect in the (111) direction and compare that with what we get from Optados. To get $$ \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} $$ we do \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} Then to get the final result we do \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) $$ = \\frac{1}{3} \\bigg ( \\epsilon_{xx} + \\epsilon_{yy} + \\epsilon_{zz} + 2(\\epsilon_{xy} + \\epsilon_{yz} + \\epsilon_{zx}) \\bigg ) $$ Let's check if this is true using our separated dielectric function tensor files. We will get a function that is equal to the above equation using a Python script, and plot it on the same graph as the case polarised in the (111) direction. You may use the script get_in_direction.py import numpy as np eps = { key : np . loadtxt ( f \"rut_tens { i } .dat\" ) for i , key in enumerate (( 'xx' , 'yy' , 'zz' , 'xy' , 'xz' , 'yz' ))} eps_vals = { key : val [:, 1 ] for key , val in eps . items ()} energies = eps [ 'xx' ][:, 0 ] eps_111_values = ( sum ( eps [ ind ] for ind in ( 'xx' , 'yy' , 'zz' )) + 2 * sum ( eps [ ind ] for ind in ( 'xy' , 'xz' , 'yz' )) / 3 output_data = np . column_stack (( energies , eps_111_values )) output_filename = \"rut_111_out.dat\" np . savetxt ( output_filename , output_data , fmt = ' % .16e ' , header = \"Energy (eV) Effective Epsilon_111\" ) This gives the output of the above equation acting on the dielectric function tensor we calculate, stored in rut_111.dat . Now let's see if the 2 results agree: let's try xmgrace rut_epsilon.dat tensors/rut_111_out.dat Using rut_epsilon.dat from our last Optados calculation . We should see that the lines almost perfectly overlap: Now we properly understand what is going on when choosing a certain polarisation direction, and what the dielectric function tensor truly means.","title":"Examining Dielectric Tensor"},{"location":"tutorials/Optics/Optics_ani/#isotropic-dielectric-function","text":"There is another case to have a look at: what is the dielectric function when the material is polycrystalline, and thus behaves isotropically? Optados can easily find this by changing the keyword in the rut.odi file to OPTICS_GEOM : tensor and removing the OPTICS_QDIR line (as the direction no longer matters). If you wish to verify how this is being calculated, use the same Python script as above but change the calculation eps_111_values = ( eps [ 'xx' ] + eps [ 'yy' ] + eps [ 'zz' ] + 2 * eps [ 'xy' ] + 2 * eps [ 'xz' ] + 2 * eps [ 'yz' ]) / 3 to for i in range ( len ( energies )): tensor = np . array ([ [ eps [ 'xx' ][ i ], eps [ 'xy' ][ i ], eps [ 'xz' ][ i ]], [ eps [ 'xy' ][ i ], eps [ 'yy' ][ i ], eps [ 'yz' ][ i ]], [ eps [ 'xz' ][ i ], eps [ 'yz' ][ i ], eps [ 'zz' ][ i ]] ]) eigenvalues = np . linalg . eigvals ( tensor ) iso_value = np . mean ( eigenvalues ) iso_values . append ( eps_111_value ) and change variable, output file name etc. as appropraite output_data = np . column_stack (( energies , iso_values )) output_filename = \"rut_111_eigen.dat\" This gives us the average of the eigenvalues of the dielectric matrix for every enegy, giving us the isotropic value. Let's plot them together to see if they're identical: xmgrace rut_epsilon.dat tensors/rut_111_eigen.dat We get a graph looking like this: As expected, the 2 lines overlap: this demonstrates that the polycrystalline calculation is effectively the \"average\" of the dielectric tensor in all directions, which is what we'd expect for a polycrystalline sample, where we can assume that all directions are equally likely.","title":"Isotropic Dielectric Function"},{"location":"tutorials/Tools/elastic_constants/","text":"Andrew Walker (building on work by Dan Wilson) provides some python scripts for calculating elastic constants using CASTEP, available from https://github.com/andreww/elastic-constants . The tool comes in two parts - first is generate_strain.py, this takes the results of a successful variable cell geometry optimisation and creates a set of input files to be run through CASTEP. The second part is elastics.py, which takes the CASTEP results and constructs the matrix of elastic constants, Young's modulus, Poisson's ratios and bulk and shear moduli. Usage information for each script can be obtained by using the --help option. For this exercise we will use rutile - titanium dioxide. Below are example .cell and .param files to start from. It is assumed that the scripts generate_strain.py and elastics.py are in your PATH and that python is installed. #TiO2.cell %BLOCK lattice_cart 4.594 0.000 0.000 0.000 4.594 0.000 0.000 0.000 2.959 %ENDBLOCK lattice_cart %BLOCK positions_frac Ti 0.000 0.000 0.000 Ti 0.500 0.500 0.500 O 0.305 0.305 0.000 O -0.305 -0.305 0.000 O 0.805 0.195 0.500 O -0.805 -0.195 0.500 %ENDBLOCK positions_frac symmetry_generate kpoint_mp_grid 3 3 3 #TiO2.param task : geometryoptimisation cutoff_energy : 700 eV xc_functional : PBE max_scf_cycles : 100 calculate_stress : true opt_strategy : speed num_dump_cycles : 0 Task 1: Perform a variable cell geometry optimisation and make sure to include calculate_stress : true in your param file. Test the kinetic energy cut-off and k-point grid such that the stress is converged to within the default geom_stress_tol value. (Hint: Use CASTEP's built-in help utility to find the default.) Task 2: Use the generate_strain.py script to generate a set of .cell files deformed according to the appropriate strain pattern. The command generate_strain.py TiO2 should be sufficient. You should now have twelve (in this case) sets of input files - individual .cell files and corresponding .param , symbolically linked to the original TiO2.param file. Notice that the new .cell files all have the FIX_ALL_CELL true option set. Task 3: Run CASTEP on each of the 12 sets of input files. Note that the cell distortions can break the symmetry of the crystal, hence changing the number of k-points in the symmetry reduced sample. The -dryrun option of CASTEP can be used to do a quick check for how many k-points are required. This can help when selecting how many cores to run the calculation on if you are running CASTEP in parallel. Task 4: Run the elastics.py script to obtain the elastic constants. The command elastics.py TiO2 will print the results to the terminal. The --latex option generates a LaTeX formatted summary of the results and the --graphics option produces a graphical representation of the stress-strain fits in a .png file. Task 5: Investigate how the results and their errors change with smaller values of the elec_energy_tol parameter. Also investigate the effect of changing the --strain option to generate_strain.py . Move any old *cij*.castep files to another directory - the elastics.py script only checks the first set of data in a concatenated .castep file.","title":"Elastic Constants"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/","text":"Interlayer binding energy of graphite Here we'll explore the van der Waals interaction that holds sheets of graphene together to form graphite. We will see how a standard semi-local density functional approximation fails to predict the correct interlayer binding energy in graphite and how we can do better using semi-empirical dispersion corrections in CASTEP. For this tutorial we will use the CASTEP-ASE interface to setup and run many short calculations and analyse the results, though you can of course adapt the content here to use a scripting language of your choice. I have broken up the parts of the script to add clarification in places, but you can download the jupyter notebook with all the cells here . We start by importing several python libraries. For more information on using the atomic simulation environment (ASE) with CASTEP, see the documentation here . # ASE version 3.23 from ase.io import read , write from ase.calculators.castep import Castep from ase.io.castep import read_seed from ase.visualize import view # pandas version 1.3.4 import pandas as pd # castep.mpi on path already, version 24.1 castep_cmd = 'mpirun -n 4 castep.mpi' # plotting from matplotlib import pyplot as plt % matplotlib inline # Python version: 3.9.5 The CASTEP-ASE interface returns the 'Final energy' from the .castep file, though for this tutorial we will actually want the dispersion-corrected energy. The function below reads the .castep file and extracts the dispersion-corrected final energy. def extract_dispersion_corrected_energy ( file_path ): \"\"\" Extracts the dispersion corrected final energy from a .castep file. Parameters: file_path (str): Path to the .castep file. Returns: float: The extracted energy value in eV. \"\"\" energy = None with open ( file_path , 'r' ) as file : lines = file . readlines () # Iterate over the lines in reverse order to find the last occurrence for line in reversed ( lines ): if \"Dispersion corrected final energy\" in line : energy = float ( line . split ()[ - 2 ]) break if energy is None : raise ValueError ( \"Energy not found in the file.\" ) return energy For this tutorial I will use CASTEP version 24.1. See here for a list of the different dispersion correction schemes and which version of CASTEP they are available from. Separation of layers: setup and run the calculations The script below loops over several different dispersion corrections schemes and, for each one, calculates the total energy of a 4-atom graphite cell at several different values of the c lattice constant. This effectively increases the interlayer spacing between the sheets of graphene. By separating them far enough apart, we can estimate the interlayer binding energy predicted by each method. The script took about 10 minutes to run using 4 cores on a relatively powerful laptop. You can decrease the k-point sampling or basis set precision, or loop over fewer methods or c parameters in order to speed things up. # run in this directory directory = 'separate-layers-tutorial/' # k-point grid -- not converged! kpts = [ 13 , 13 , 5 ] # xc functional to use xc = 'PBE' # range of unit c parameters in Angstroms (interlayer spacings are half these!) crange = [ 4 , 5 , 6 , 6.25 , 6.5 , 6.75 , 7 , 7.25 , 7.5 , 8.5 , 10 , 14 , 16 ] #SEDC correction schemes to try: schemes = [ '' , 'G06' , 'D3' , 'D3-BJ' , 'D4' , 'TS' , 'MBD' , 'XDM' ] # pandas dataframe to store the results df = pd . DataFrame ({ 'crange' : crange }) # loop over the different correction schemes for sedc_scheme in schemes : print ( ' \\n ' , 50 * '=' ) print ( f ' { xc } + { sedc_scheme } \\n ' ) # list to temporarily hold the total energy for each calculation energies = [] # loop over c parameters: for c in crange : label = f ' { xc } - { sedc_scheme } - { c : 3.2f } ' try : graphite = read_seed ( directory + label ) except : # if the calculation doesn't already exist, we set it up and # run it # read in cif file (taken from here: https://materialsproject.org/materials/mp-48 ) graphite = read ( 'C_mp-48_primitive.cif' ) # For CASTEP < 24.1 we might need a supercell to get more accurate results # for TS, MBD and XDM schemes that rely on Hirshfeld charges. # graphite = graphite * (3,3,1) # scale c parameter to new value cellpar = graphite . cell . cellpar () cellpar [ 2 ] = c graphite . set_cell ( cellpar , scale_atoms = True ) # set up castep calculator calc = Castep ( kpts = kpts , label = label , castep_command = castep_cmd , directory = directory , _rename_existing_dir = False , # allows us to write all these calculations to the same directory... ) calc . param . xc_functional = xc calc . param . basis_precision = 'precise' # switch to something cheaper (e.g. FINE) to speed things up for this example.. calc . param . write_checkpoint = 'None' # don't need the checkpoint files now calc . param . write_cst_esp = False # don't need the electrostatic potential file now calc . param . write_bands = False # don't need the bands file now calc . cell . symmetry_generate = True # use symmetry to speed up the calculation calc . cell . snap_to_symmetry = True # enforce symmetry # Switch on the SEDC flags if sedc_scheme != '' : calc . param . sedc_apply = True calc . param . sedc_scheme = sedc_scheme # For the XDM scheme we need to set this manually # otherwise the calculation crashes... if sedc_scheme == 'XDM' : calc . param . SEDC_SC_XDM = 1.0 graphite . calc = calc e = graphite . get_potential_energy () # If a SEDC scheme is used, # we need to extract the dispersion corrected energy if sedc_scheme != '' : e = extract_dispersion_corrected_energy ( directory + label + '.castep' ) energies . append ( e ) print ( f ' { c : 8.3f } A \\t { e : 12.8f } eV' ) # save the energy wrt to furthest energy: energies = [ e - energies [ - 1 ] for e in energies ] df [ f ' { xc } - { sedc_scheme } ' ] = energies # Save to a .csv file: df . to_csv ( 'graphite_layer_separation.csv' ) The .param files generated look something like this: WRITE_CST_ESP: FALSE WRITE_BANDS: FALSE WRITE_CHECKPOINT: None XC_FUNCTIONAL: PBE SEDC_APPLY: TRUE SEDC_SCHEME: D3 # or TS or D3-BJ etc. BASIS_PRECISION: precise The task defaults to SINGLEPOINT (which is what we want in this case). The .cell files simply have the crystal structure in which the cell is scaled in the c direction. Read in and analyse the results We can now read in and analyse the results from the previous step. Reading the data into a pandas dataframe object is convenient. df = pd . read_csv ( './graphite_layer_separation.csv' ) # scale by 1000 / 4 to get the energies per atom and in units of meV dfdiff = ( df . iloc [:, 1 :]) * 1000 / 4 # energy per atom in meV # the c parmeter is 2x the interlayer spacing, d dfdiff [ 'c/2' ] = df [ 'crange' ] / 2 styles = [ f ' { m } -' for m in [ \"o\" , \"v\" , \"^\" , \"s\" , \"H\" , \"+\" , \"x\" , \"D\" ]] # compared to this reference (and many others!) https://doi.org/10.1039/C3RA47187J ax = dfdiff . plot ( x = 'c/2' , y = [ 'PBE-' , 'PBE-G06' , 'PBE-D3' , 'PBE-D3-BJ' , 'D4' , 'PBE-TS' , 'PBE-MBD' , 'PBE-XDM' ], ylabel = 'energy/atom (meV)' , ylim = ( - 100 , 80 ), xlabel = r 'interlayer spacing d ( = c/2) (${\\AA}$)' , figsize = ( 16 , 10 ), style = styles , ) ax . axhline ( 0 , color = '0.3' ) ax . axvline ( 3.355 , ls = '--' , color = '0.4' ) # Experimental binding energies reported shown in the figure are 31 \u00b1 2, 43, 52 \u00b1 5 and 35 (+15 to \u201310) meV per atom ax . axhspan ( ymin =- 57 , ymax =- 25 , color = '0.8' , alpha = 0.5 ) ax . set_title ( 'graphite interlayer binding energy' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.pdf' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.png' , dpi = 300 ) which produces the following figure: Fig1. Graphite interlayer binding energy using the PBE XC functional with various dispersion corrections. The dashed vertical line is the experimental interlayer spacing and the shaded grey region is the range of experimentally obtained interlayer binding energies. Please note that these are not fully converged calculations and so do not represent the actual performance of these methods but is simply a guide for how to use them with CASTEP. We can see that the plain PBE functional severely underestimates the binding energy of graphite and that many of the dispersion-corrected results are in much better agreement. The TS scheme strongly overbinds graphite, but has been found to be accurate for other types of systems. Testing such methods carefully is always required when you encounter a new system. Further suggestions For the D3 and D3-BJ methods, try to switch on the three-body interaction term by setting: %BLOCK devel_code d3_threebody TRUE %ENDBLOCK devel_code in the .param file. What effect does this have on the interlayer binding energy in graphite? (You may also want to set IPRINT = 2 to see more information about the dispersion correction parameters.) Compare to other XC functionals with and without the dispersion corrections (though note that of the corrections are only parameterised for a few functionals .) For CASTEP < 24.1 we get a warning for the TS, MBD and XDM schemes about the unit cell being too small for accurate corrections. If you get this warning, try repeating the above calculations for these three methods using a larger supercell to see what the effect is and what sized supercell you would need to converge the dispersion correction.","title":"Dispersion corrections"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#interlayer-binding-energy-of-graphite","text":"Here we'll explore the van der Waals interaction that holds sheets of graphene together to form graphite. We will see how a standard semi-local density functional approximation fails to predict the correct interlayer binding energy in graphite and how we can do better using semi-empirical dispersion corrections in CASTEP. For this tutorial we will use the CASTEP-ASE interface to setup and run many short calculations and analyse the results, though you can of course adapt the content here to use a scripting language of your choice. I have broken up the parts of the script to add clarification in places, but you can download the jupyter notebook with all the cells here . We start by importing several python libraries. For more information on using the atomic simulation environment (ASE) with CASTEP, see the documentation here . # ASE version 3.23 from ase.io import read , write from ase.calculators.castep import Castep from ase.io.castep import read_seed from ase.visualize import view # pandas version 1.3.4 import pandas as pd # castep.mpi on path already, version 24.1 castep_cmd = 'mpirun -n 4 castep.mpi' # plotting from matplotlib import pyplot as plt % matplotlib inline # Python version: 3.9.5 The CASTEP-ASE interface returns the 'Final energy' from the .castep file, though for this tutorial we will actually want the dispersion-corrected energy. The function below reads the .castep file and extracts the dispersion-corrected final energy. def extract_dispersion_corrected_energy ( file_path ): \"\"\" Extracts the dispersion corrected final energy from a .castep file. Parameters: file_path (str): Path to the .castep file. Returns: float: The extracted energy value in eV. \"\"\" energy = None with open ( file_path , 'r' ) as file : lines = file . readlines () # Iterate over the lines in reverse order to find the last occurrence for line in reversed ( lines ): if \"Dispersion corrected final energy\" in line : energy = float ( line . split ()[ - 2 ]) break if energy is None : raise ValueError ( \"Energy not found in the file.\" ) return energy For this tutorial I will use CASTEP version 24.1. See here for a list of the different dispersion correction schemes and which version of CASTEP they are available from.","title":"Interlayer binding energy of graphite"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#separation-of-layers-setup-and-run-the-calculations","text":"The script below loops over several different dispersion corrections schemes and, for each one, calculates the total energy of a 4-atom graphite cell at several different values of the c lattice constant. This effectively increases the interlayer spacing between the sheets of graphene. By separating them far enough apart, we can estimate the interlayer binding energy predicted by each method. The script took about 10 minutes to run using 4 cores on a relatively powerful laptop. You can decrease the k-point sampling or basis set precision, or loop over fewer methods or c parameters in order to speed things up. # run in this directory directory = 'separate-layers-tutorial/' # k-point grid -- not converged! kpts = [ 13 , 13 , 5 ] # xc functional to use xc = 'PBE' # range of unit c parameters in Angstroms (interlayer spacings are half these!) crange = [ 4 , 5 , 6 , 6.25 , 6.5 , 6.75 , 7 , 7.25 , 7.5 , 8.5 , 10 , 14 , 16 ] #SEDC correction schemes to try: schemes = [ '' , 'G06' , 'D3' , 'D3-BJ' , 'D4' , 'TS' , 'MBD' , 'XDM' ] # pandas dataframe to store the results df = pd . DataFrame ({ 'crange' : crange }) # loop over the different correction schemes for sedc_scheme in schemes : print ( ' \\n ' , 50 * '=' ) print ( f ' { xc } + { sedc_scheme } \\n ' ) # list to temporarily hold the total energy for each calculation energies = [] # loop over c parameters: for c in crange : label = f ' { xc } - { sedc_scheme } - { c : 3.2f } ' try : graphite = read_seed ( directory + label ) except : # if the calculation doesn't already exist, we set it up and # run it # read in cif file (taken from here: https://materialsproject.org/materials/mp-48 ) graphite = read ( 'C_mp-48_primitive.cif' ) # For CASTEP < 24.1 we might need a supercell to get more accurate results # for TS, MBD and XDM schemes that rely on Hirshfeld charges. # graphite = graphite * (3,3,1) # scale c parameter to new value cellpar = graphite . cell . cellpar () cellpar [ 2 ] = c graphite . set_cell ( cellpar , scale_atoms = True ) # set up castep calculator calc = Castep ( kpts = kpts , label = label , castep_command = castep_cmd , directory = directory , _rename_existing_dir = False , # allows us to write all these calculations to the same directory... ) calc . param . xc_functional = xc calc . param . basis_precision = 'precise' # switch to something cheaper (e.g. FINE) to speed things up for this example.. calc . param . write_checkpoint = 'None' # don't need the checkpoint files now calc . param . write_cst_esp = False # don't need the electrostatic potential file now calc . param . write_bands = False # don't need the bands file now calc . cell . symmetry_generate = True # use symmetry to speed up the calculation calc . cell . snap_to_symmetry = True # enforce symmetry # Switch on the SEDC flags if sedc_scheme != '' : calc . param . sedc_apply = True calc . param . sedc_scheme = sedc_scheme # For the XDM scheme we need to set this manually # otherwise the calculation crashes... if sedc_scheme == 'XDM' : calc . param . SEDC_SC_XDM = 1.0 graphite . calc = calc e = graphite . get_potential_energy () # If a SEDC scheme is used, # we need to extract the dispersion corrected energy if sedc_scheme != '' : e = extract_dispersion_corrected_energy ( directory + label + '.castep' ) energies . append ( e ) print ( f ' { c : 8.3f } A \\t { e : 12.8f } eV' ) # save the energy wrt to furthest energy: energies = [ e - energies [ - 1 ] for e in energies ] df [ f ' { xc } - { sedc_scheme } ' ] = energies # Save to a .csv file: df . to_csv ( 'graphite_layer_separation.csv' ) The .param files generated look something like this: WRITE_CST_ESP: FALSE WRITE_BANDS: FALSE WRITE_CHECKPOINT: None XC_FUNCTIONAL: PBE SEDC_APPLY: TRUE SEDC_SCHEME: D3 # or TS or D3-BJ etc. BASIS_PRECISION: precise The task defaults to SINGLEPOINT (which is what we want in this case). The .cell files simply have the crystal structure in which the cell is scaled in the c direction.","title":"Separation of layers: setup and run the calculations"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#read-in-and-analyse-the-results","text":"We can now read in and analyse the results from the previous step. Reading the data into a pandas dataframe object is convenient. df = pd . read_csv ( './graphite_layer_separation.csv' ) # scale by 1000 / 4 to get the energies per atom and in units of meV dfdiff = ( df . iloc [:, 1 :]) * 1000 / 4 # energy per atom in meV # the c parmeter is 2x the interlayer spacing, d dfdiff [ 'c/2' ] = df [ 'crange' ] / 2 styles = [ f ' { m } -' for m in [ \"o\" , \"v\" , \"^\" , \"s\" , \"H\" , \"+\" , \"x\" , \"D\" ]] # compared to this reference (and many others!) https://doi.org/10.1039/C3RA47187J ax = dfdiff . plot ( x = 'c/2' , y = [ 'PBE-' , 'PBE-G06' , 'PBE-D3' , 'PBE-D3-BJ' , 'D4' , 'PBE-TS' , 'PBE-MBD' , 'PBE-XDM' ], ylabel = 'energy/atom (meV)' , ylim = ( - 100 , 80 ), xlabel = r 'interlayer spacing d ( = c/2) (${\\AA}$)' , figsize = ( 16 , 10 ), style = styles , ) ax . axhline ( 0 , color = '0.3' ) ax . axvline ( 3.355 , ls = '--' , color = '0.4' ) # Experimental binding energies reported shown in the figure are 31 \u00b1 2, 43, 52 \u00b1 5 and 35 (+15 to \u201310) meV per atom ax . axhspan ( ymin =- 57 , ymax =- 25 , color = '0.8' , alpha = 0.5 ) ax . set_title ( 'graphite interlayer binding energy' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.pdf' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.png' , dpi = 300 ) which produces the following figure: Fig1. Graphite interlayer binding energy using the PBE XC functional with various dispersion corrections. The dashed vertical line is the experimental interlayer spacing and the shaded grey region is the range of experimentally obtained interlayer binding energies. Please note that these are not fully converged calculations and so do not represent the actual performance of these methods but is simply a guide for how to use them with CASTEP. We can see that the plain PBE functional severely underestimates the binding energy of graphite and that many of the dispersion-corrected results are in much better agreement. The TS scheme strongly overbinds graphite, but has been found to be accurate for other types of systems. Testing such methods carefully is always required when you encounter a new system.","title":"Read in and analyse the results"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#further-suggestions","text":"For the D3 and D3-BJ methods, try to switch on the three-body interaction term by setting: %BLOCK devel_code d3_threebody TRUE %ENDBLOCK devel_code in the .param file. What effect does this have on the interlayer binding energy in graphite? (You may also want to set IPRINT = 2 to see more information about the dispersion correction parameters.) Compare to other XC functionals with and without the dispersion corrections (though note that of the corrections are only parameterised for a few functionals .) For CASTEP < 24.1 we get a warning for the TS, MBD and XDM schemes about the unit cell being too small for accurate corrections. If you get this warning, try repeating the above calculations for these three methods using a larger supercell to see what the effect is and what sized supercell you would need to converge the dispersion correction.","title":"Further suggestions"},{"location":"workshop/00_starting/","text":"Getting Started Settting up the Virtual Workspace Signing up to the STFC Training Workspace Open a browser and navigate to the link you have been emailed - the one that contains training.analysis.stfc.ac.uk. This should prompt you for some information and it will then send your account for authorisation. Once the account is authorised, you will recieve and email with a link to login. Creating the CASTEP Workspace You should recieve an email with a link that you can use to connect to the STFC system. Save this email as you will use it to login during the training. Select New Workspace and then select CASTEP TRAINING WORKSHOP 2024 and click create workspace. This will generate you a virtual desktop on the STFC cloud service with access to CASTEP. Connecting to the virual desktop Mouse over the workspace and you should be presented with buttons to launch the workspace in either a new tab or new window. This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several visualisations available. Loading CASTEP Click the applications button in the bottom left and select software -> CASTEP. This will launch a terminal with shortcuts for running CASTEP. Accessing the CASTEP help system To search the castep help system for keywords containing castep: castep-serial castep.serial -s lattice To view detailed information on a particular keyword: castep-serial castep.serial -h lattice_abc Running CASTEP To run castep in serial with Si2 as the seedname, type castep-serial castep.serial Si2 To run castep in parallel using 16 core (the maximum for these virutal machines) with same Si2 seedname, type castep-mpi mpirun -n 16 castep.mpi Si2 Note that the castep-serial and castep-mpi parts that the start of the above lines are particular to these virtual machines for the tutorial. Running castep on your own machines would typically involve either castep.serial Si2 for the serial version or mpirun -n 4 castep.mpi Si2 for the parallel version. Tuorial files The files needed for these tutorials can be found by navigating from Applications -> Data -> Course Materials (that will open up a file browser in the right place). They can also be accessed via the command line from this location: /course_materials/ . Copy the files to somewhere in your home directory before trying to run CASTEP (you can't run CASTEP in the /course_materials directory. You can do that either using the graphical file browser or using the command line. For example: Make a folder called Si2 in your home directory: mkdir ~/Si2 Then copy in the corresponding tutorial file: cp /course_materials/Si2.tar.gz ~/Si2/ Summary of useful commands mv - rename (or move) a file eg. mv oldfile newfile cp - copy a file eg. cp original copy pwd - print current (working) directory mkdir - make a new directory (aka folder) nano - a file editor eg. nano filename . Note you can use this to edit an existing file, or to create a new file. eg nano mynewfile will create a new file called mynewfile ls - list files in the current directory ls -l - list files - but give more details than plain ls exit - to close the terminal when you are finished cp fred/* jim/ - copy all the files in the folder fred into the folder jim cp ../myfile ./ - copy the file myfile in the folder below to the current folder cp ~/myfile ./ - copy the file myfile in your home folder to the current folder qstat - look at the list of jobs running and queued on the cluster castep-mpi mpirun -np 8 castep.mpi diamond - submits a castep job with diamond.cell and diamond.param as inputs onto 8 cores with a time limit of 1 hour c2x This is a handy free program written by Michael Rutter (TCM group Cambridge). It can convert castep.cell and castep.check files into various formats eg .cell , .pdb . (and many other things!) castep-serial c2x -h - list all the options castep-serial c2x --pdbn castep.cell castep.pdb castep-serial c2x --pdbn castep.check castep.pdb castep-serial c2x --cell castep.check new.cell (useful at the end of geometry optimisation)","title":" 0 Logging on"},{"location":"workshop/00_starting/#getting-started","text":"","title":"Getting Started"},{"location":"workshop/00_starting/#settting-up-the-virtual-workspace","text":"","title":"Settting up the Virtual Workspace"},{"location":"workshop/00_starting/#signing-up-to-the-stfc-training-workspace","text":"Open a browser and navigate to the link you have been emailed - the one that contains training.analysis.stfc.ac.uk. This should prompt you for some information and it will then send your account for authorisation. Once the account is authorised, you will recieve and email with a link to login.","title":"Signing up to the STFC Training Workspace"},{"location":"workshop/00_starting/#creating-the-castep-workspace","text":"You should recieve an email with a link that you can use to connect to the STFC system. Save this email as you will use it to login during the training. Select New Workspace and then select CASTEP TRAINING WORKSHOP 2024 and click create workspace. This will generate you a virtual desktop on the STFC cloud service with access to CASTEP.","title":"Creating the CASTEP Workspace"},{"location":"workshop/00_starting/#connecting-to-the-virual-desktop","text":"Mouse over the workspace and you should be presented with buttons to launch the workspace in either a new tab or new window. This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several visualisations available.","title":"Connecting to the virual desktop"},{"location":"workshop/00_starting/#loading-castep","text":"Click the applications button in the bottom left and select software -> CASTEP. This will launch a terminal with shortcuts for running CASTEP.","title":"Loading CASTEP"},{"location":"workshop/00_starting/#accessing-the-castep-help-system","text":"To search the castep help system for keywords containing castep: castep-serial castep.serial -s lattice To view detailed information on a particular keyword: castep-serial castep.serial -h lattice_abc","title":"Accessing the CASTEP help system"},{"location":"workshop/00_starting/#running-castep","text":"To run castep in serial with Si2 as the seedname, type castep-serial castep.serial Si2 To run castep in parallel using 16 core (the maximum for these virutal machines) with same Si2 seedname, type castep-mpi mpirun -n 16 castep.mpi Si2 Note that the castep-serial and castep-mpi parts that the start of the above lines are particular to these virtual machines for the tutorial. Running castep on your own machines would typically involve either castep.serial Si2 for the serial version or mpirun -n 4 castep.mpi Si2 for the parallel version.","title":"Running CASTEP"},{"location":"workshop/00_starting/#tuorial-files","text":"The files needed for these tutorials can be found by navigating from Applications -> Data -> Course Materials (that will open up a file browser in the right place). They can also be accessed via the command line from this location: /course_materials/ . Copy the files to somewhere in your home directory before trying to run CASTEP (you can't run CASTEP in the /course_materials directory. You can do that either using the graphical file browser or using the command line. For example: Make a folder called Si2 in your home directory: mkdir ~/Si2 Then copy in the corresponding tutorial file: cp /course_materials/Si2.tar.gz ~/Si2/","title":"Tuorial files"},{"location":"workshop/00_starting/#summary-of-useful-commands","text":"mv - rename (or move) a file eg. mv oldfile newfile cp - copy a file eg. cp original copy pwd - print current (working) directory mkdir - make a new directory (aka folder) nano - a file editor eg. nano filename . Note you can use this to edit an existing file, or to create a new file. eg nano mynewfile will create a new file called mynewfile ls - list files in the current directory ls -l - list files - but give more details than plain ls exit - to close the terminal when you are finished cp fred/* jim/ - copy all the files in the folder fred into the folder jim cp ../myfile ./ - copy the file myfile in the folder below to the current folder cp ~/myfile ./ - copy the file myfile in your home folder to the current folder qstat - look at the list of jobs running and queued on the cluster castep-mpi mpirun -np 8 castep.mpi diamond - submits a castep job with diamond.cell and diamond.param as inputs onto 8 cores with a time limit of 1 hour","title":"Summary of useful commands"},{"location":"workshop/00_starting/#c2x","text":"This is a handy free program written by Michael Rutter (TCM group Cambridge). It can convert castep.cell and castep.check files into various formats eg .cell , .pdb . (and many other things!) castep-serial c2x -h - list all the options castep-serial c2x --pdbn castep.cell castep.pdb castep-serial c2x --pdbn castep.check castep.pdb castep-serial c2x --cell castep.check new.cell (useful at the end of geometry optimisation)","title":"c2x"},{"location":"workshop/01_bonding/","text":"Learning Objectives Introduction to CASTEP input and output files. Running on the Arcus machine at Oxford University. Introduction The aim of this exercise is to familiarise you with CASTEP input and output files and running the code, some associated utilities and conversion programs. You will run some simple and small CASTEP calculations on canonical examples of covalently and ionically bonded materials - silicon and sodium chloride - and use the results to study the bonding from an electronic structure perspective. While performing the exercises try to think about the reasons for each step, and about how to interpret the results. The point of the exercise is not merely to reach the end but to learn the path. The exercise below contains a number of questions. Please take note when a question is asked of you, and think about the answer. Feel free to discuss the answer with one of the demonstrators after you have thought about it for a while. The secondary aim of this exercise is to learn to run programs on Oxford University's Arcus cluster. This is a powerful parallel computer. (Although the runs in this first exercise should take only seconds on a desktop.) For information about how to login to and use this cluster please refer to the instructions provided. ` Where To Find Help If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep --help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep --help kpoints_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep --search symmetry Finally, to list all keywords, use: $ castep --search all Note that the long-form arguments --help and --search can optionally be replaced with -h and -s , respectively. Example 1 - Silicon Download the files to arcus $ wget http://www.castep.org/files/Si2.tgz Unzip and untar them, then move into the new directory $ gunzip Si2.tgz $ tar -xvf Si2.tar $ cd Si2 Examine the CASTEP input files Si2.cell and Si2.param using your favourite text editor (e.g. nano ). The Si_00.usp file is a pseudopotential file, you do not need to understand it at the moment. $ nano Si2.cell $ nano Si2.param It is useful to view the structure before submitting your calculation using CASTEP. Copy the Si2.cell to your local machine using the sftp window (left) in mobaXterm. Cell Structure Visualisation Jmol To open the Si2.cell file using Jmol : Open Jmol (You will need to copy it from the h: drive to your desktop. Then double click jmol.jar ) then use File => Open and navigate to your Si2.cell file. Alternatively, you can drag and drop the Si2.cell file into the Jmol window, and Jmol will open it. It can be helpful to view multiple repeat units of your unit cell. The easiest way to do this in Jmol is to open a console window, click File => Console and type: $ load \"\" { 2 2 2 } to show a 2x2x2 supercell. Check the geometry of the input file is what you expect it to be before moving onto the next step. Vesta To open the Si2.cell file using VESTA : Open VESTA (You will need to copy it from the h: drive to your desktop. Then double click VESTA.exe ) then use File => Open and navigate to your Si2.cell file. You cannot drag and drop into VESTA. If you wish to create a supercell as above, use Objects => Boundary . Then edit the maximum and/or minimum values of x, y, and z in order to change your boundaries. Setting x(max) , y(max) , and z(max) to 2 will create the 2 by 2 by 2 supercell as above. Check the geometry of the input file is as expected before moving on to the next step. Now run CASTEP on Arcus using the 2-atom input files. $ castep.mpi Si2 This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Find the section of the file which monitors the SCF loop and the approach to convergence. How many SCF iterations did it need? Copy the output files Si2.castep and Si2.den_fmt to the local machine using sftp . Visualisation of the charge density Jmol Jmol can also be used to view the isodensity map, open the .castep file by dragging and dropping the Si2.castep file into the Jmol window. Open the Jmol console (File => Console) and type the following commands: $ load \"\" { 2 2 2 } $ isosurface rho cutoff 14 \"Si2.den_fmt\" lattice { 2 2 2 } Note: you can use the cd command within Jmol to navigate to the folder with your .castep files. Jmol uses forward slash for paths to files on windows and linux based machines. This Si2.den_fmt file is a formatted file produced by CASTEP that contains the value of the electron density on a grid of points. This isosurface command in Jmol plots an isodensity surface over your atomic positions. Vesta You will see a file called Si2.den_fmt which contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called Si2.charg_frm cp Si2.den_fmt Si2.charg_frm Now edit the file Si2.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open Si2.charg_frm with Vesta. Note that Vesta needs both the .cell and .charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process here . An alternative way to plot charge densities (and much more besides) is c2x . Answer the following questions: Can you explain what you see as you vary the isosurface value? Can you see any features which might be characteristic of a covalently-bonded crystal. Do you notice anything strange about the electron density close to the Si nucleus? Can you explain this as a consequence of the particular kind of electronic structure calculation you have just performed? Repeat steps 1-8 using input files for sodium chloride and aluminium. $ wget http://www.castep.org/files/Al.tgz $ wget http://www.castep.org/files/NaCl.tgz Think about the following questions: Note what similarities and differences you find compared to silicon? Does this help explain the difference in bond chemistry between silicon, sodium chloride and aluminium? Does this help explain why there are many reasonable classical potential functions for NaCl to be found in the simulation literature, but that finding good potentials for silicon is a very tough challenge? What about aluminium, can you find good potentials for aluminium?","title":" 1 Bonding "},{"location":"workshop/01_bonding/#learning-objectives","text":"Introduction to CASTEP input and output files. Running on the Arcus machine at Oxford University.","title":"Learning Objectives"},{"location":"workshop/01_bonding/#introduction","text":"The aim of this exercise is to familiarise you with CASTEP input and output files and running the code, some associated utilities and conversion programs. You will run some simple and small CASTEP calculations on canonical examples of covalently and ionically bonded materials - silicon and sodium chloride - and use the results to study the bonding from an electronic structure perspective. While performing the exercises try to think about the reasons for each step, and about how to interpret the results. The point of the exercise is not merely to reach the end but to learn the path. The exercise below contains a number of questions. Please take note when a question is asked of you, and think about the answer. Feel free to discuss the answer with one of the demonstrators after you have thought about it for a while. The secondary aim of this exercise is to learn to run programs on Oxford University's Arcus cluster. This is a powerful parallel computer. (Although the runs in this first exercise should take only seconds on a desktop.) For information about how to login to and use this cluster please refer to the instructions provided. `","title":"Introduction"},{"location":"workshop/01_bonding/#where-to-find-help","text":"If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep --help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep --help kpoints_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep --search symmetry Finally, to list all keywords, use: $ castep --search all Note that the long-form arguments --help and --search can optionally be replaced with -h and -s , respectively.","title":"Where To Find Help"},{"location":"workshop/01_bonding/#example-1-silicon","text":"Download the files to arcus $ wget http://www.castep.org/files/Si2.tgz Unzip and untar them, then move into the new directory $ gunzip Si2.tgz $ tar -xvf Si2.tar $ cd Si2 Examine the CASTEP input files Si2.cell and Si2.param using your favourite text editor (e.g. nano ). The Si_00.usp file is a pseudopotential file, you do not need to understand it at the moment. $ nano Si2.cell $ nano Si2.param It is useful to view the structure before submitting your calculation using CASTEP. Copy the Si2.cell to your local machine using the sftp window (left) in mobaXterm. Cell Structure Visualisation","title":"Example 1 - Silicon"},{"location":"workshop/01_bonding/#jmol","text":"To open the Si2.cell file using Jmol : Open Jmol (You will need to copy it from the h: drive to your desktop. Then double click jmol.jar ) then use File => Open and navigate to your Si2.cell file. Alternatively, you can drag and drop the Si2.cell file into the Jmol window, and Jmol will open it. It can be helpful to view multiple repeat units of your unit cell. The easiest way to do this in Jmol is to open a console window, click File => Console and type: $ load \"\" { 2 2 2 } to show a 2x2x2 supercell. Check the geometry of the input file is what you expect it to be before moving onto the next step.","title":"Jmol"},{"location":"workshop/01_bonding/#vesta","text":"To open the Si2.cell file using VESTA : Open VESTA (You will need to copy it from the h: drive to your desktop. Then double click VESTA.exe ) then use File => Open and navigate to your Si2.cell file. You cannot drag and drop into VESTA. If you wish to create a supercell as above, use Objects => Boundary . Then edit the maximum and/or minimum values of x, y, and z in order to change your boundaries. Setting x(max) , y(max) , and z(max) to 2 will create the 2 by 2 by 2 supercell as above. Check the geometry of the input file is as expected before moving on to the next step. Now run CASTEP on Arcus using the 2-atom input files. $ castep.mpi Si2 This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Find the section of the file which monitors the SCF loop and the approach to convergence. How many SCF iterations did it need? Copy the output files Si2.castep and Si2.den_fmt to the local machine using sftp . Visualisation of the charge density","title":"Vesta"},{"location":"workshop/01_bonding/#jmol_1","text":"Jmol can also be used to view the isodensity map, open the .castep file by dragging and dropping the Si2.castep file into the Jmol window. Open the Jmol console (File => Console) and type the following commands: $ load \"\" { 2 2 2 } $ isosurface rho cutoff 14 \"Si2.den_fmt\" lattice { 2 2 2 } Note: you can use the cd command within Jmol to navigate to the folder with your .castep files. Jmol uses forward slash for paths to files on windows and linux based machines. This Si2.den_fmt file is a formatted file produced by CASTEP that contains the value of the electron density on a grid of points. This isosurface command in Jmol plots an isodensity surface over your atomic positions.","title":"Jmol"},{"location":"workshop/01_bonding/#vesta_1","text":"You will see a file called Si2.den_fmt which contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called Si2.charg_frm cp Si2.den_fmt Si2.charg_frm Now edit the file Si2.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open Si2.charg_frm with Vesta. Note that Vesta needs both the .cell and .charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process here . An alternative way to plot charge densities (and much more besides) is c2x .","title":"Vesta"},{"location":"workshop/01_bonding/#answer-the-following-questions","text":"Can you explain what you see as you vary the isosurface value? Can you see any features which might be characteristic of a covalently-bonded crystal. Do you notice anything strange about the electron density close to the Si nucleus? Can you explain this as a consequence of the particular kind of electronic structure calculation you have just performed? Repeat steps 1-8 using input files for sodium chloride and aluminium. $ wget http://www.castep.org/files/Al.tgz $ wget http://www.castep.org/files/NaCl.tgz","title":"Answer the following questions:"},{"location":"workshop/01_bonding/#think-about-the-following-questions","text":"Note what similarities and differences you find compared to silicon? Does this help explain the difference in bond chemistry between silicon, sodium chloride and aluminium? Does this help explain why there are many reasonable classical potential functions for NaCl to be found in the simulation literature, but that finding good potentials for silicon is a very tough challenge? What about aluminium, can you find good potentials for aluminium?","title":"Think about the following questions:"},{"location":"workshop/02_bands_dos/","text":"Learning Objectives Gain awareness and familiarity with the tools available to produce band structure and density of states plots with CASTEP. Investigate how band structures differ for metallic and semiconductor systems differ. Running spin polarised calculations in CASTEP. Note This tutorial we will be running on Arcus, you should be able to complete this tutorial without copying files backwards and forwards; however if you wish to visualise your system (e.g. using VESTA) then you will need to copy files to your local machine to do so. If you don't remember how to do this, remind yourself by referring to Tutorial 0 and Tutorial 1 Xterminals, Plotting and other computational hassle To save some effort transferring files backwards and forwards to and from Arcus we are going to use Arcus to plot the band structure and DOS and send the image to your monitor. Introduction The aim of this tutorial is to enable you to compute band structures using CASTEP and introduce you to a few of the tools which allow you to visualise the band structure and density of electronic states computed using CASTEP. The band structure of metals and semiconductors will be plotted so that you can look at the differences between different types of systems. First you will look at the CASTEP input files (.cell and .param) used to produce band structure information. Next you will use the perl script dispersion.pl which can be used to take CASTEP output and plot band structure diagrams. Then you will use orbitals2bands. A tool which provides more information about the orbitals that contribute to different bands in your band structure diagram. Finally you will look at the band structure of iron, to show how magnetic systems can be studied using CASTEP, you will also plot the density of states of iron using dos.pl. You will need: In addition to CASTEP and the suite of tools it comes with you will need: Grace - A 2D plotting program. Perl - a scripting language. These are available on the Arcus cluster. Example files: Download the input files wget http://www.castep.org/files/bandstructure.tgz Then untar and unzip it using: gunzip bandstructure.tgz tar -xvf bandstructure.tar Example 1 - Graphite. Move into the graphite directory, look at the CASTEP .cell and .param files and notice the differences from the previous single point energy runs. To the .param file the task (which lets CASTEP know what you want it to do) needs to be changed to: task : bandstructure The .cell file requires a path through the Brillouin Zone along which you want the bandstructure to be plotted: %BLOCK BS_KPOINT_PATH 0.0000 0.00000 0.00000 ! G 0.0000 0.00000 0.50000 ! A -0.3333 0.66667 0.50000 ! H -0.3333 0.66667 0.00000 ! K 0.0000 0.00000 0.00000 ! G 0.0000 0.50000 0.00000 ! M 0.0000 0.50000 0.50000 ! L -0.3333 0.66667 0.50000 ! H %ENDBLOCK BS_KPOINT_PATH Run CASTEP using: $ mpirun -np 16 castep.mpi graphite Once the CASTEP calculation has finished a graphite.bands file will be present in the directory. A band structure plot can be viewed by using the dispersion.pl tool. $ dispersion.pl -xg -bs -symmetry hexagonal graphite.bands The -xg option tells dispersion.pl that you are using grace to plot the band structure, the -bs option tells the script that you want to plot using CASTEP output files, the -symmetry hexagonal option labels the high symmetry points on the bands structure plot. When you view this band structure plot you will notice the bands are coloured from lowest to highest energy. Using information about the wavefunction CASTEP can improve this band structure plot, so bands are coloured due to the orbitals that contribute. The orbitals2bands tool can be used to alter the Si.bands file represent the orbitals that contribute to the bands. This tool can be run in the same directory that you ran CASTEP in. The program orbitals2bands overwrites your Si.bands file, so it's best to copy it to another file to preserve it $ cp graphite.bands graphite.bands.orig $ mpirun -np 16 orbitals2bands graphite Example 2 - Silicon and Aluminium. Very similar to example 1, but this time comparing a semiconductor and a metal, both with FCC crystal structures. Go into the silicon and aluminium directories and compute the band structures as above. The dispersion symmetry option needs to be told that these are FCC materials, not hexagonal. Compare the band structure of the Silicon and Aluminium crystals. What are the main similarities and differences? Can you explain this using your knowledge of the bonding in these materials? Example 3 - Iron In the iron directory there is a set of input files for iron. As iron is a magnetic system you need to instruct CASTEP that it is spin polarised. You also need to set up the calculation with the total spin set to a non-zero value, in order to find the magnetic ground state. (If you're interested you could try removing the spin : 1 line from the Fe.param file and see what happens). You set the spin in the .param file: spin : 1 spin_polarised : true The path through the Brillouin Zone is found in the Fe.cell file. Run the iron computation using CASTEP and plot the band structure for iron using dispersion.pl . You might find the -mono option to dispersion.pl to be useful - it colours the bands by spin channel. Iron's Density of States To plot the density of states of iron, we need to run CASTEP again, instead of computing the band structure along a high symmetry line, we compute it on a grid. To your Fe.cell file, remove the bs_kpoint_path block and replace it with: BS_KPOINT_MP_GRID 12 12 12 Run CASTEP using these new input files then use the dos.pl plotting script dos.pl -xg -bs -w 0.2 Fe.bands Can you relate the features in the DOS to those in the Bandstructure? You might find the -mirror option useful. The -w option sets the Gaussian broadening in eV. Try smaller (0.05) and larger (0.5) values - explain what you see. DOS for the other crystals in this tutorial can be computed in a similar way. Further work a) Compute the band-structure of hexagonal monolayer boron nitride. What is the key difference to graphene? b) MoS2 has attracted much recent interest. What is its structure? Can you make a cell file for this (if not ask). What about its band structure - metal or insulator, direct vs indirect gap.","title":" 2 Bandstructure and DOS"},{"location":"workshop/02_bands_dos/#learning-objectives","text":"Gain awareness and familiarity with the tools available to produce band structure and density of states plots with CASTEP. Investigate how band structures differ for metallic and semiconductor systems differ. Running spin polarised calculations in CASTEP.","title":"Learning Objectives"},{"location":"workshop/02_bands_dos/#note","text":"This tutorial we will be running on Arcus, you should be able to complete this tutorial without copying files backwards and forwards; however if you wish to visualise your system (e.g. using VESTA) then you will need to copy files to your local machine to do so. If you don't remember how to do this, remind yourself by referring to Tutorial 0 and Tutorial 1","title":"Note"},{"location":"workshop/02_bands_dos/#xterminals-plotting-and-other-computational-hassle","text":"To save some effort transferring files backwards and forwards to and from Arcus we are going to use Arcus to plot the band structure and DOS and send the image to your monitor.","title":"Xterminals, Plotting and other computational hassle"},{"location":"workshop/02_bands_dos/#introduction","text":"The aim of this tutorial is to enable you to compute band structures using CASTEP and introduce you to a few of the tools which allow you to visualise the band structure and density of electronic states computed using CASTEP. The band structure of metals and semiconductors will be plotted so that you can look at the differences between different types of systems. First you will look at the CASTEP input files (.cell and .param) used to produce band structure information. Next you will use the perl script dispersion.pl which can be used to take CASTEP output and plot band structure diagrams. Then you will use orbitals2bands. A tool which provides more information about the orbitals that contribute to different bands in your band structure diagram. Finally you will look at the band structure of iron, to show how magnetic systems can be studied using CASTEP, you will also plot the density of states of iron using dos.pl.","title":"Introduction"},{"location":"workshop/02_bands_dos/#you-will-need","text":"In addition to CASTEP and the suite of tools it comes with you will need: Grace - A 2D plotting program. Perl - a scripting language. These are available on the Arcus cluster.","title":"You will need:"},{"location":"workshop/02_bands_dos/#example-files","text":"Download the input files wget http://www.castep.org/files/bandstructure.tgz Then untar and unzip it using: gunzip bandstructure.tgz tar -xvf bandstructure.tar","title":"Example files:"},{"location":"workshop/02_bands_dos/#example-1-graphite","text":"Move into the graphite directory, look at the CASTEP .cell and .param files and notice the differences from the previous single point energy runs. To the .param file the task (which lets CASTEP know what you want it to do) needs to be changed to: task : bandstructure The .cell file requires a path through the Brillouin Zone along which you want the bandstructure to be plotted: %BLOCK BS_KPOINT_PATH 0.0000 0.00000 0.00000 ! G 0.0000 0.00000 0.50000 ! A -0.3333 0.66667 0.50000 ! H -0.3333 0.66667 0.00000 ! K 0.0000 0.00000 0.00000 ! G 0.0000 0.50000 0.00000 ! M 0.0000 0.50000 0.50000 ! L -0.3333 0.66667 0.50000 ! H %ENDBLOCK BS_KPOINT_PATH Run CASTEP using: $ mpirun -np 16 castep.mpi graphite Once the CASTEP calculation has finished a graphite.bands file will be present in the directory. A band structure plot can be viewed by using the dispersion.pl tool. $ dispersion.pl -xg -bs -symmetry hexagonal graphite.bands The -xg option tells dispersion.pl that you are using grace to plot the band structure, the -bs option tells the script that you want to plot using CASTEP output files, the -symmetry hexagonal option labels the high symmetry points on the bands structure plot. When you view this band structure plot you will notice the bands are coloured from lowest to highest energy. Using information about the wavefunction CASTEP can improve this band structure plot, so bands are coloured due to the orbitals that contribute. The orbitals2bands tool can be used to alter the Si.bands file represent the orbitals that contribute to the bands. This tool can be run in the same directory that you ran CASTEP in. The program orbitals2bands overwrites your Si.bands file, so it's best to copy it to another file to preserve it $ cp graphite.bands graphite.bands.orig $ mpirun -np 16 orbitals2bands graphite","title":"Example 1 - Graphite."},{"location":"workshop/02_bands_dos/#example-2-silicon-and-aluminium","text":"Very similar to example 1, but this time comparing a semiconductor and a metal, both with FCC crystal structures. Go into the silicon and aluminium directories and compute the band structures as above. The dispersion symmetry option needs to be told that these are FCC materials, not hexagonal. Compare the band structure of the Silicon and Aluminium crystals. What are the main similarities and differences? Can you explain this using your knowledge of the bonding in these materials?","title":"Example 2 - Silicon and Aluminium."},{"location":"workshop/02_bands_dos/#example-3-iron","text":"In the iron directory there is a set of input files for iron. As iron is a magnetic system you need to instruct CASTEP that it is spin polarised. You also need to set up the calculation with the total spin set to a non-zero value, in order to find the magnetic ground state. (If you're interested you could try removing the spin : 1 line from the Fe.param file and see what happens). You set the spin in the .param file: spin : 1 spin_polarised : true The path through the Brillouin Zone is found in the Fe.cell file. Run the iron computation using CASTEP and plot the band structure for iron using dispersion.pl . You might find the -mono option to dispersion.pl to be useful - it colours the bands by spin channel.","title":"Example 3 - Iron"},{"location":"workshop/02_bands_dos/#irons-density-of-states","text":"To plot the density of states of iron, we need to run CASTEP again, instead of computing the band structure along a high symmetry line, we compute it on a grid. To your Fe.cell file, remove the bs_kpoint_path block and replace it with: BS_KPOINT_MP_GRID 12 12 12 Run CASTEP using these new input files then use the dos.pl plotting script dos.pl -xg -bs -w 0.2 Fe.bands Can you relate the features in the DOS to those in the Bandstructure? You might find the -mirror option useful. The -w option sets the Gaussian broadening in eV. Try smaller (0.05) and larger (0.5) values - explain what you see. DOS for the other crystals in this tutorial can be computed in a similar way.","title":"Iron's Density of States"},{"location":"workshop/02_bands_dos/#further-work","text":"a) Compute the band-structure of hexagonal monolayer boron nitride. What is the key difference to graphene? b) MoS2 has attracted much recent interest. What is its structure? Can you make a cell file for this (if not ask). What about its band structure - metal or insulator, direct vs indirect gap.","title":"Further work"},{"location":"workshop/03_geometry/","text":"Geometry Optimisation Exercise 1 - Dihydrogen dimer In this tutorial we will model the bond length of a H2 molecule. This will give you the opportunity to get used to geometry optimisations and gain familiarity Remember you can use castep --help to assist you with finding the appropriate input parameters. Create a new file, H2.cell using your favourite text editor, e.g. nano H2.cell Start by creating a lattice block in your cell file. %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc or %block lattice_cart 5 0 0 0 5 0 0 0 5 %endblock lattice_cart Will produce a cube 5 Angstroms long on each side. NOTE: ONLY USE ONE OF THESE TWO FORMATS Q: Is this a big enough box to represent a molecule? (Recall Periodic Boundary Conditions) A: You may wish to test this by changing the size of the box. Add atoms into our cell. This can be done either relative to the lattice vectors using %block positions_frac H 0.5 0.5 0.5 H 0.5 0.5 0.2 %endblock positions_frac or relative to the origin of the cell file %block positions_abs H 3 3 3 H 3 3 4 %endblock positions_abs Q: If you are varying the size of your unit cell for tests, which one will be more convenient? Add final components to unit cell fix_all_cell: true kpoint_mp_grid: 1 1 1 Q: Why do we only want to use a single k-point? Q: Why do we want to fix the lattice parameters rather than letting them relax? Now close H2.cell and create a H2.param file. In H2.param add Task: GeometryOptimisation XC_Functional: LDA Cut_Off_Energy: 300 If you want to get Castep to automatically print out the final structure, you can also add write_cell_structure: true You can now use mpirun (or your submission script!) to submit your geometry optimisation! Results Analysis Scroll down through the file. Check to see how the forces and bond-length varies over iterations. For advanced bash users, try grep \"F|max\" H2.castep to extract this from the file. You may also want to visualise the H2.cell and (if you told castep to print it) the H2-out.cell files as in previous tutorials Finally, consider watching the optimisation by drag-and-dropping the H2.geom file into Jmol (VESTA will not animate it) The experimental H2 bond length is about 0.74 Angstroms. How does your result compare? Extension A may give some insight into this! Extensions You may wish to split these between groups and discuss the results A. Functional Choice So far you've used the local density approximation (LDA) for the exchange-correlation functional in this exercise. Repeat your calculation with the PBE exchange-correlation functional (a popular GGA): xc_functional : PBE You may also want to consider a hybrid functional such as HSE06 or the meta-GGA RSCAN B. More Precise Structural Optimisations You may wish to have more precise structure for certain calculations such as NMR or Phonons . These may be controlled in the .param file with geom_force_tol: 0.05 eV/ang geom_energy_tol: 2e-5 eV geom_stress_tol: 0.1 GPa geom_disp_tol: 0.001 ang These are the default values; what happens to your final values when you alter them? Hint: You have fixed the lattice - what will stress do? C. Wavefunction Convergence If you have a bad wavefunction you will get bad forces. To demonstrate this try adding elec_energy_tol: 0.1 This overwrites the default of 0.00001 ev and will make the SCF convergence very fast. What does this do to the geometry optimisation? NOTE: This is not something you want to do in practice! Hopefully working through this example will demonstrate why. Exercise 2 Run a geometry optimisation on silicon. You can use a silicon input file from one of the previous tutorials as a starting point for your input files. Set CASTEP's parameters to perform a geometry optimisation using a 160 eV plane-wave cut-off energy and an 8x8x8 Monkhorst-Pack k-point grid: In Si2.param : task : geometry optimisation cut_off_energy : 160 eV In Si2.cell : kpoints_MP_grid 8 8 8 Because you're going to change the lattice vectors, CASTEP will do a finite basis-set correction (FBSC); this will calculate and print out dEtotal/dlog(Ecut) \u2013 anything more than 0.1 eV/atom is big and a sign of incomplete convergence. Q: What is the final lattice parameter? Do convergence tests (cut_off_energy, kpoints etc). The experimental lattice constant is 3.84 Angstrom - how does your value compare? What is the difference in your results between calculations using an LDA and a PBE exchange-correlation functional? Exercise 3 - Graphene It can be useful to know how to construct a monolayer material, such as graphene. This requires the use of cell constraints so that we force a large distance between periodic images (and we don't have the system collapse to form graphite!) In your .cell file: %block cell_constraints 1 1 0 3 4 5 %endblock cell_constraints Will force the a and b lattice parameters to be the same (though free to vary jointly), fix the c lattice vector, and let all angles relax independently. This is similar to the %block lattice_abc structure you saw earlier. For the mathematically minded, this is taking the limit that the interlayer spacing, controlled by the out-of-plane lattice vector, goes to infinity! Practically, we cannot actually set the lattice parameter to infinity - try varying it and seeing how it converges with distance.","title":" 3 Geometry Optimisation"},{"location":"workshop/03_geometry/#geometry-optimisation","text":"","title":"Geometry Optimisation"},{"location":"workshop/03_geometry/#exercise-1-dihydrogen-dimer","text":"In this tutorial we will model the bond length of a H2 molecule. This will give you the opportunity to get used to geometry optimisations and gain familiarity Remember you can use castep --help to assist you with finding the appropriate input parameters. Create a new file, H2.cell using your favourite text editor, e.g. nano H2.cell Start by creating a lattice block in your cell file. %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc or %block lattice_cart 5 0 0 0 5 0 0 0 5 %endblock lattice_cart Will produce a cube 5 Angstroms long on each side. NOTE: ONLY USE ONE OF THESE TWO FORMATS Q: Is this a big enough box to represent a molecule? (Recall Periodic Boundary Conditions) A: You may wish to test this by changing the size of the box. Add atoms into our cell. This can be done either relative to the lattice vectors using %block positions_frac H 0.5 0.5 0.5 H 0.5 0.5 0.2 %endblock positions_frac or relative to the origin of the cell file %block positions_abs H 3 3 3 H 3 3 4 %endblock positions_abs Q: If you are varying the size of your unit cell for tests, which one will be more convenient? Add final components to unit cell fix_all_cell: true kpoint_mp_grid: 1 1 1 Q: Why do we only want to use a single k-point? Q: Why do we want to fix the lattice parameters rather than letting them relax? Now close H2.cell and create a H2.param file. In H2.param add Task: GeometryOptimisation XC_Functional: LDA Cut_Off_Energy: 300 If you want to get Castep to automatically print out the final structure, you can also add write_cell_structure: true You can now use mpirun (or your submission script!) to submit your geometry optimisation! Results Analysis Scroll down through the file. Check to see how the forces and bond-length varies over iterations. For advanced bash users, try grep \"F|max\" H2.castep to extract this from the file. You may also want to visualise the H2.cell and (if you told castep to print it) the H2-out.cell files as in previous tutorials Finally, consider watching the optimisation by drag-and-dropping the H2.geom file into Jmol (VESTA will not animate it) The experimental H2 bond length is about 0.74 Angstroms. How does your result compare? Extension A may give some insight into this!","title":"Exercise 1 - Dihydrogen dimer"},{"location":"workshop/03_geometry/#extensions","text":"You may wish to split these between groups and discuss the results","title":"Extensions"},{"location":"workshop/03_geometry/#a-functional-choice","text":"So far you've used the local density approximation (LDA) for the exchange-correlation functional in this exercise. Repeat your calculation with the PBE exchange-correlation functional (a popular GGA): xc_functional : PBE You may also want to consider a hybrid functional such as HSE06 or the meta-GGA RSCAN","title":"A. Functional Choice"},{"location":"workshop/03_geometry/#b-more-precise-structural-optimisations","text":"You may wish to have more precise structure for certain calculations such as NMR or Phonons . These may be controlled in the .param file with geom_force_tol: 0.05 eV/ang geom_energy_tol: 2e-5 eV geom_stress_tol: 0.1 GPa geom_disp_tol: 0.001 ang These are the default values; what happens to your final values when you alter them? Hint: You have fixed the lattice - what will stress do?","title":"B. More Precise Structural Optimisations"},{"location":"workshop/03_geometry/#c-wavefunction-convergence","text":"If you have a bad wavefunction you will get bad forces. To demonstrate this try adding elec_energy_tol: 0.1 This overwrites the default of 0.00001 ev and will make the SCF convergence very fast. What does this do to the geometry optimisation? NOTE: This is not something you want to do in practice! Hopefully working through this example will demonstrate why.","title":"C. Wavefunction Convergence"},{"location":"workshop/03_geometry/#exercise-2","text":"Run a geometry optimisation on silicon. You can use a silicon input file from one of the previous tutorials as a starting point for your input files. Set CASTEP's parameters to perform a geometry optimisation using a 160 eV plane-wave cut-off energy and an 8x8x8 Monkhorst-Pack k-point grid: In Si2.param : task : geometry optimisation cut_off_energy : 160 eV In Si2.cell : kpoints_MP_grid 8 8 8 Because you're going to change the lattice vectors, CASTEP will do a finite basis-set correction (FBSC); this will calculate and print out dEtotal/dlog(Ecut) \u2013 anything more than 0.1 eV/atom is big and a sign of incomplete convergence. Q: What is the final lattice parameter? Do convergence tests (cut_off_energy, kpoints etc). The experimental lattice constant is 3.84 Angstrom - how does your value compare? What is the difference in your results between calculations using an LDA and a PBE exchange-correlation functional?","title":"Exercise 2"},{"location":"workshop/03_geometry/#exercise-3-graphene","text":"It can be useful to know how to construct a monolayer material, such as graphene. This requires the use of cell constraints so that we force a large distance between periodic images (and we don't have the system collapse to form graphite!) In your .cell file: %block cell_constraints 1 1 0 3 4 5 %endblock cell_constraints Will force the a and b lattice parameters to be the same (though free to vary jointly), fix the c lattice vector, and let all angles relax independently. This is similar to the %block lattice_abc structure you saw earlier. For the mathematically minded, this is taking the limit that the interlayer spacing, controlled by the out-of-plane lattice vector, goes to infinity! Practically, we cannot actually set the lattice parameter to infinity - try varying it and seeing how it converges with distance.","title":"Exercise 3 - Graphene"},{"location":"workshop/04_nmr_shiedling_efg/","text":"4 NMR shielding and EFG Part 1 We start running castep calculations by looking at two small systems, and examining the issue of \"convergence\". Start by copying the input files into your home directory i.e. wget http://www.tcm.phy.cam.ac.uk/castep/oxford/workshop_nmr_intro.tgz unpack it tar -zxvf workshop_nmr_intro.tgz Example 1 - Ethanol CH 3 CH 2 OH Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig 1). We will try to reproduce this result. FILES: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strate.g.y : speed task = magres cut_off_energy = 20 ry OBJECTIVES: Examine the convergence of the chemical shieldings with planewave cutoff Compare to experiment. INSTRUCTIONS: Look at the cell and param file. Note that the only special keyword is task = magres Run castep. mpirun -np 16 castep.mpi ethanol Look at the output file. At the end the isotropic chemical shielding, anisotropy, and asymmetry are reported (here we are only interested in the isotropic value.) This information, plus the full tensors is also given in the file ethanol.magres You might wish to transfer the *.magres file back to your desktop to visualise with MagresView . Examine the effect of increasing the cutoff energy (say 20-50 Ryd in steps of 10 Ryd). It always helps to plot a graph of the convergence (e.g. with gnuplot or xmgrace on the cluster - or with excel on the pc) Find the \"converged\" hydrogen (or proton in NMR language) shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Average the CH 3 and CH 2 chemical shieldings. This will give you 3 unique chemical shieldings. We now need to convert the chemical shieldings \u03c3 iso to chemical shifts \u03b4 iso on the experimental scale. We use the relation: \u03b4 iso =\u03c3 ref -\u03c3 A suitable \u03c3 ref for 1H is 30.97ppm. Fig2. 1H NMR spectrum of liquid ethanol Fig. 2 shows a modern high-resolution 1H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1H magnetic moments - but let's ignore that for now. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm. You should find that your computed values agree for two sites. Do you know why the other site has such a large disagreement with experiment? Example 2 - Diamond FILES: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate * diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry OBJECTIVES: Examine the convergence of the chemical shielding as the sampling of the electronic Brillouin zone (BZ) is increased. INSTRUCTIONS: Look at the files diamond.cell and diamond.param We have specified the kpoints in the cell file using the keyword kpoints_mp_grid 4 4 4 Run CASTEP for a range of kpoint meshes (say 2,4,6,8,10) Examine (plot?) the convergence of the chemical shielding. The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). Specify the kpoint in the cell file using %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST Which gives a result closest to the converged answer? (as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells) Part 2 We now look at some more realistic examples. Oxygen-17 Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure. Example 3 - Alanine, a simple amino acid FILES: alanine.cell alanine.param alanine.pdb OBJECTIVES: Compute the chemical shift and Electric field gradient for alanine Assign the 17 NMR spectrum Fig3. Solid-State O17 NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) INSTRUCTIONS: Look at the cell and param files. The geometry for alanine was obtained by neutron diffraction and was downloaded from the Cambridge Crystallographic database. View the original pdb file note the hydrogen bonding Run the example - the calculation is not fully converged. However, the relative shift between the two sites is fairly converged. The experimental 17 O NMR spectrum shows two peaks (Fig 3 (b)) - they are very broad due to the quadrupolar coupling, and overlap. The experimental parameters are given in Table 1. Assign the two resonances A and B. Do all three computed parameters support this assignment? Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labeled A and B. Isotropic chemical shift \u03b4, quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4(A)-\u03b4 (B) (ppm) 23.5 C Q (A) (MHz) 7.86 \u03b7 Q (A) 0.28 C Q (B) (MHz) 6.53 \u03b7 Q (B) 0.70 Example 4 - Silicates Quartz and Cristoballite FILES: quartz.cell quartz.param crist.cell crist.param OBJECTIVES: Compute the chemical shift and Electric field gradient for two silicates. Assign the 17 O NMR spectrum INSTRUCTIONS: The 17 O parameters for two silicates are reported in Table 2. From the values you compute can you tell which one is quartz? (a suitable \u03c3 ref is 263ppm) Table 2 : Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \u03b4 , quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4 (ppm) C Q (MHz) \u03b7 Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19","title":" 5 NMR Shielding"},{"location":"workshop/04_nmr_shiedling_efg/#4-nmr-shielding-and-efg","text":"","title":"4 NMR shielding and EFG"},{"location":"workshop/04_nmr_shiedling_efg/#part-1","text":"We start running castep calculations by looking at two small systems, and examining the issue of \"convergence\". Start by copying the input files into your home directory i.e. wget http://www.tcm.phy.cam.ac.uk/castep/oxford/workshop_nmr_intro.tgz unpack it tar -zxvf workshop_nmr_intro.tgz","title":"Part 1"},{"location":"workshop/04_nmr_shiedling_efg/#example-1-ethanol-ch3ch2oh","text":"Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig 1). We will try to reproduce this result. FILES: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strate.g.y : speed task = magres cut_off_energy = 20 ry OBJECTIVES: Examine the convergence of the chemical shieldings with planewave cutoff Compare to experiment. INSTRUCTIONS: Look at the cell and param file. Note that the only special keyword is task = magres Run castep. mpirun -np 16 castep.mpi ethanol Look at the output file. At the end the isotropic chemical shielding, anisotropy, and asymmetry are reported (here we are only interested in the isotropic value.) This information, plus the full tensors is also given in the file ethanol.magres You might wish to transfer the *.magres file back to your desktop to visualise with MagresView . Examine the effect of increasing the cutoff energy (say 20-50 Ryd in steps of 10 Ryd). It always helps to plot a graph of the convergence (e.g. with gnuplot or xmgrace on the cluster - or with excel on the pc) Find the \"converged\" hydrogen (or proton in NMR language) shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Average the CH 3 and CH 2 chemical shieldings. This will give you 3 unique chemical shieldings. We now need to convert the chemical shieldings \u03c3 iso to chemical shifts \u03b4 iso on the experimental scale. We use the relation: \u03b4 iso =\u03c3 ref -\u03c3 A suitable \u03c3 ref for 1H is 30.97ppm. Fig2. 1H NMR spectrum of liquid ethanol Fig. 2 shows a modern high-resolution 1H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1H magnetic moments - but let's ignore that for now. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm. You should find that your computed values agree for two sites. Do you know why the other site has such a large disagreement with experiment?","title":"Example 1 - Ethanol CH3CH2OH"},{"location":"workshop/04_nmr_shiedling_efg/#example-2-diamond","text":"FILES: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate * diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry OBJECTIVES: Examine the convergence of the chemical shielding as the sampling of the electronic Brillouin zone (BZ) is increased. INSTRUCTIONS: Look at the files diamond.cell and diamond.param We have specified the kpoints in the cell file using the keyword kpoints_mp_grid 4 4 4 Run CASTEP for a range of kpoint meshes (say 2,4,6,8,10) Examine (plot?) the convergence of the chemical shielding. The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). Specify the kpoint in the cell file using %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST Which gives a result closest to the converged answer? (as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells)","title":"Example 2 - Diamond"},{"location":"workshop/04_nmr_shiedling_efg/#part-2","text":"We now look at some more realistic examples. Oxygen-17 Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure.","title":"Part 2"},{"location":"workshop/04_nmr_shiedling_efg/#example-3-alanine-a-simple-amino-acid","text":"FILES: alanine.cell alanine.param alanine.pdb OBJECTIVES: Compute the chemical shift and Electric field gradient for alanine Assign the 17 NMR spectrum Fig3. Solid-State O17 NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) INSTRUCTIONS: Look at the cell and param files. The geometry for alanine was obtained by neutron diffraction and was downloaded from the Cambridge Crystallographic database. View the original pdb file note the hydrogen bonding Run the example - the calculation is not fully converged. However, the relative shift between the two sites is fairly converged. The experimental 17 O NMR spectrum shows two peaks (Fig 3 (b)) - they are very broad due to the quadrupolar coupling, and overlap. The experimental parameters are given in Table 1. Assign the two resonances A and B. Do all three computed parameters support this assignment? Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labeled A and B. Isotropic chemical shift \u03b4, quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4(A)-\u03b4 (B) (ppm) 23.5 C Q (A) (MHz) 7.86 \u03b7 Q (A) 0.28 C Q (B) (MHz) 6.53 \u03b7 Q (B) 0.70","title":"Example 3 - Alanine, a simple amino acid"},{"location":"workshop/04_nmr_shiedling_efg/#example-4-silicates-quartz-and-cristoballite","text":"FILES: quartz.cell quartz.param crist.cell crist.param OBJECTIVES: Compute the chemical shift and Electric field gradient for two silicates. Assign the 17 O NMR spectrum INSTRUCTIONS: The 17 O parameters for two silicates are reported in Table 2. From the values you compute can you tell which one is quartz? (a suitable \u03c3 ref is 263ppm) Table 2 : Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \u03b4 , quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4 (ppm) C Q (MHz) \u03b7 Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19","title":"Example 4 - Silicates Quartz and Cristoballite"},{"location":"workshop/05_phonon/","text":"Phonons and Spectroscopy Tutorial The aims of this tutorial session is to introduce you to running larger-scale CASTEP jobs on supercomputer clusters, editing of input files for and setup of CASTEP jobs, and analysis of the results using standalone tools. To achieve results without waiting too long for jobs to complete the initial runs will be small ones, but the aim by the end of this afternoon should be to set up larger and more significant runs. Today's session will entirely comprise insulators or semiconductors. You may need to consult the CASTEP phonon users guide, which may be accessed here The practical will be conducted using the arc service. Make a directory called (e.g.) Phonons and copy the files h-BN.cell and h-BN.param into the new folder. A. \\Gamma \\Gamma -Point phonon in h-BN The first exercise will take you through the construction of a \\Gamma \\Gamma point phonon calculation and the generation of a simple model infrared spectrum of a semiconductor. It will also introduce you to the use of some additional analysis and visualisation tools. BN is one of a family of Nitride semiconductors, which occurs in cubic zincblende (c-BN), hexagonal wurtzite (h-BN) and graphite-like hexagonal (h-BN) polymorphs. We will calculate the phonons, infrared spectrum and Raman spectrum of h-BN. Phonon Calculation Set-up Your starting point will be the structure which is provided in the .cell file. The Phonons Manual contains a very similar example for the Wurtzite-structure polymorph of BN. Edit the .cell file using one of the text editors installed on the system (e.g. nano ). Uncomment the species_pot block and change it to read %block species_pot NCP %endblock species_pot to select norm-conserving pseudopotentials. Choose the k-point set to use \u2013 remove any block KPOINT_LIST and replace with the line kpoint_mp_grid 7 7 4 and one to specify a gamma-point phonon wavevector phonon_kpoint_mp_grid 1 1 1 Have a look in the .param file, look up the meaning of any keywords you don\u2019t know (you can use castep.serial -h ). Test your configuration using castep.serial \u2013dryrun h-BN This tells CASTEP to read the intput files and summaries the calculation in the .castep file, but does not run the electronic structure calculation. It is very useful to check syntax before submitting to a batch queue (and finding out later you\u2019d made a spelling mistake!). Check to see if any .err files are produced and fix issues, if any. If / when no errors are returned, congratulations. You have set up the input files, and you can delete the dryrun .castep file. Once you have in place the .cell and .param files you are ready to submit the CASTEP job. This is done using our general script: mpirun -n 4 castep.mpi h-BN which requests a 16-core parallel run. Use the qstat command to monitor the progress of your calculation. When it has finished, you can examine the output file h-BN.castep and find the frequencies. What you see is explained further in the Phonons user guide linked above. There is also a machine-readable file h-BN.phonon which contains the frequencies and also the eigenvectors which we will analyse. Analysis of h-BN phonon output. We will use Castep\u2019s tools to visualise the modes using the free Jmol visualiser. Use secure file transfer to copy the .phonon file back to the PC where Jmol is installed. Start Jmol and bring up a console window from the right-mouse menu. To use the full power of the command-line and find the files it is most convenient to set Jmol's current directory to the location of your working directory containing your output files. (It is possible and simpler to drag and drop the .phonon file onto Jmol window, but you need the power of the command line to display additional periodic repeats.) cd --- report the current directory cd .. or cd -- navigate up/down the directory tree. Then type the Jmol command to load your .castep file load h-BN.phonon {3 3 2} PACKED Note that while you can read in the .phonon file from Jmol's File menu, you need the additional opitions of the command line to display additional periodic repeats. You can then use the Tools-Vibrate menu to turn on mode animation, and navigate the modes. Can you see from the mode eigenvectors which modes are IR-active and which are Raman active? Do you agree with the IR and Raman activity printed in the .castep file? Generation of IR spectrum The easiest way to generate a simple model IR spectrum is to use Castep\u2019s dos.pl tool. To run this in the most effective way and automatically display a plot, you will need to be running an X windows server on the PC. In that case the command dos.pl -ir -xg h-BN.phonon will generate a plot script and use the xmgrace plotting program to display it. You can create a gnuplot script instead of xmgrace by changing the -xg flag to -gp . Alternatively you can generate a GNUPLOT script without plotting by dos.pl -ir -gp -np h-BN.phonon > h-BN-phonon.plt You can then copy the h-BN-phonon.plt back to the PC and read this into GNUPLOT. Generation of Raman spectrum The calculation of a raman intensities is fairly expensive compared to infrared matrix elements and it is therefore not turned on by default however the .param file turned this on: CALCULATE_RAMAN : TRUE RAMAN_METHOD : DFPT You can use the -raman flag of dos.pl to generate and plot a Raman spectrum. B. Molecular modes in benzene The next part of this practical is to compute the modes and spectrum of a molecule and compare the result with a calculation of a molecular crystal. Our example is benzene First run the isolated molecule calculation. Using the supplied PDB format file and using the pdb2cell utility, generate a .cell file for a single molecule calculation. There are a few other considerations to take into account for an isolated molecule calculation. The size of the simulation cell governs the interactions between periodic copies of the molecule and should be large enough that these are negligible. The shape of the simulation cell governs the crystallographic point groups allowed in the handling of the symmetry. It should be chosen to be commensurate (as far as possible) with the molecular point group to maximise the use of symmetry. In the case of benzene it should obviously be hexagonal, here we use a box 8A by 8A by 4A. Recall that there is no electronic dispersion for a molecule, so only a single electronic k-point is needed. The general rule is that all \u201cmolecule in a box\u201d calculations should use the G point only as Castep uses special performance optimisations in this case. Use the norm-conserving pseudopotentials ( NCP in the species_pot block) For simplicity use the local density approximation, LDA . In benzene not all atoms are on special symmetry sites so you should first perform a geometry optimisation, keeping the unit cell fixed (see fix_all_cell keyword in Castep\u2019s help). Then set up a follow-on calculation to compute the Gamma point phonons using the continuation keyword in the .param file. The Phonons User Guide linked above should help you fill in the details, but please ask if you are stuck. Check the phonon frequencies. How many zero frequency modes are there? What frequencies do you get? Can you explain? Benzene Phase III: The next stage is to compute the \\Gamma \\Gamma point phonon modes of the molecular crystal of benzene in the high pressure polymorph, Phase III. You are supplied with a .pdb file. You should use a 2x2x2 grid of electronic k-points, as dispersion is non-zero in this molecular crystal. Make sure that symmetry is detected and enabled using symmetry_generate in the .cell file. Also check that the unit cell parameters are fixed to optimise the geometry and NCP pseudopotentials are used. Use the same .param file as for the molecular case to ensure the settings are the same. Similar to the molecular case run a geometry optimisation followed by a phonon calculation. Once these calculations have completed you should generate a phonon DOS and IR spectra as in the previous practical and compare the molecule with the molecular crystal. You can also use Jmol to identify the modes. Are all your frequencies positive? If not, can you suggest why not? C. Phonon dispersion using interpolation in NaH From \\Gamma \\Gamma point only calculations we now explore the whole of the Brillouin zone of phonon wavevectors. Our example is the rocksalt-structured hydride, NaH which should run quickly enough to return results in a few minutes. Based on previous exercises, lectures and the user manual, you should be able to set up and run a DFPT phonon dispersion calculation and display a well converged set of dispersion curves. A starting point for your .cell file is: %block lattice_cart 2.0 2.0 0.0 2.0 0.0 2.0 0.0 2.0 2.0 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 H 0.5 0.5 0.5 %endblock positions_frac Symmetry_generate This contains the primitive fcc unit cell of the B1 rocksalt structure with the Na ion at (0,0,0) and the H ion at (\u00bd,\u00bd,\u00bd). This is a high-symmetry structure so it is important to instruct CASTEP to generate and use the full symmetry set. Also use norm-conserving pseudopotentials. A suitable list of points for the fine q-point path for an FCC crystal is: %block phonon_fine_kpoint_path 0.0 0.0 0.0 ! Gamma 0.5 0.5 0.0 ! X (along Delta 1.0 1.0 1.0 ! Gamma (Sigma ) 0.5 0.5 0.5 ! L (Delta) 0.5 0.75 0.25 ! W (Q) 0.5 0.5 0.0 ! X (Z) %endblock phonon_fine_kpoint_path Although you can now start the phonon calculation, knowing the accuracy of the result (error bounds) is good science. You should perform a k-point convergence test. For a phonon calculation, convergence of the forces is an appropriate test criterion. Since all of the ions are on symmetry positions the forces are zero by symmetry. Try to think of a way around this obstacle. And adopt a suitable compromise between accuracy and run-time. C.II Phonon DOS using interpolation The task here is to use the NaH example to compute and display not a dispersion curve but a density of states. This will exploit CASTEPs interpolation functionality, and you will be able to compute a good DOS without the need the repeat the expensive electronic structure calculation. To do this you will need to set up a calculation neatly identical to your previous one but with two differences. The calculation should be set up as a continuation. If your previous run wrote a .check file named NaH.check for example, then the param file should contain the line continuation : NaH.check Instead of a %block phonon_fine_kpoint_list in the .cell file, you can specify a grid phonon_fine_kpoint_mp_grid 16 16 16 You can run CASTEP on just 1-4 processors for this You can try this several times with different fine q-point grids. This will produce a .castep and .phonon file as before. You may analyse the .phonon file and generate a DOS using the dos.pl script dos.pl -xg NaH-dos.phonon (again, an X server running on the PC will be needed for grace to display; MobaXterm should have this enabled by default) .","title":" 6 Phonons"},{"location":"workshop/05_phonon/#phonons-and-spectroscopy-tutorial","text":"The aims of this tutorial session is to introduce you to running larger-scale CASTEP jobs on supercomputer clusters, editing of input files for and setup of CASTEP jobs, and analysis of the results using standalone tools. To achieve results without waiting too long for jobs to complete the initial runs will be small ones, but the aim by the end of this afternoon should be to set up larger and more significant runs. Today's session will entirely comprise insulators or semiconductors. You may need to consult the CASTEP phonon users guide, which may be accessed here The practical will be conducted using the arc service. Make a directory called (e.g.) Phonons and copy the files h-BN.cell and h-BN.param into the new folder.","title":"Phonons and Spectroscopy Tutorial"},{"location":"workshop/05_phonon/#a-gammagamma-point-phonon-in-h-bn","text":"The first exercise will take you through the construction of a \\Gamma \\Gamma point phonon calculation and the generation of a simple model infrared spectrum of a semiconductor. It will also introduce you to the use of some additional analysis and visualisation tools. BN is one of a family of Nitride semiconductors, which occurs in cubic zincblende (c-BN), hexagonal wurtzite (h-BN) and graphite-like hexagonal (h-BN) polymorphs. We will calculate the phonons, infrared spectrum and Raman spectrum of h-BN. Phonon Calculation Set-up Your starting point will be the structure which is provided in the .cell file. The Phonons Manual contains a very similar example for the Wurtzite-structure polymorph of BN. Edit the .cell file using one of the text editors installed on the system (e.g. nano ). Uncomment the species_pot block and change it to read %block species_pot NCP %endblock species_pot to select norm-conserving pseudopotentials. Choose the k-point set to use \u2013 remove any block KPOINT_LIST and replace with the line kpoint_mp_grid 7 7 4 and one to specify a gamma-point phonon wavevector phonon_kpoint_mp_grid 1 1 1 Have a look in the .param file, look up the meaning of any keywords you don\u2019t know (you can use castep.serial -h ). Test your configuration using castep.serial \u2013dryrun h-BN This tells CASTEP to read the intput files and summaries the calculation in the .castep file, but does not run the electronic structure calculation. It is very useful to check syntax before submitting to a batch queue (and finding out later you\u2019d made a spelling mistake!). Check to see if any .err files are produced and fix issues, if any. If / when no errors are returned, congratulations. You have set up the input files, and you can delete the dryrun .castep file. Once you have in place the .cell and .param files you are ready to submit the CASTEP job. This is done using our general script: mpirun -n 4 castep.mpi h-BN which requests a 16-core parallel run. Use the qstat command to monitor the progress of your calculation. When it has finished, you can examine the output file h-BN.castep and find the frequencies. What you see is explained further in the Phonons user guide linked above. There is also a machine-readable file h-BN.phonon which contains the frequencies and also the eigenvectors which we will analyse. Analysis of h-BN phonon output. We will use Castep\u2019s tools to visualise the modes using the free Jmol visualiser. Use secure file transfer to copy the .phonon file back to the PC where Jmol is installed. Start Jmol and bring up a console window from the right-mouse menu. To use the full power of the command-line and find the files it is most convenient to set Jmol's current directory to the location of your working directory containing your output files. (It is possible and simpler to drag and drop the .phonon file onto Jmol window, but you need the power of the command line to display additional periodic repeats.) cd --- report the current directory cd .. or cd -- navigate up/down the directory tree. Then type the Jmol command to load your .castep file load h-BN.phonon {3 3 2} PACKED Note that while you can read in the .phonon file from Jmol's File menu, you need the additional opitions of the command line to display additional periodic repeats. You can then use the Tools-Vibrate menu to turn on mode animation, and navigate the modes. Can you see from the mode eigenvectors which modes are IR-active and which are Raman active? Do you agree with the IR and Raman activity printed in the .castep file?","title":"A. \\Gamma\\Gamma-Point phonon in h-BN"},{"location":"workshop/05_phonon/#generation-of-ir-spectrum","text":"The easiest way to generate a simple model IR spectrum is to use Castep\u2019s dos.pl tool. To run this in the most effective way and automatically display a plot, you will need to be running an X windows server on the PC. In that case the command dos.pl -ir -xg h-BN.phonon will generate a plot script and use the xmgrace plotting program to display it. You can create a gnuplot script instead of xmgrace by changing the -xg flag to -gp . Alternatively you can generate a GNUPLOT script without plotting by dos.pl -ir -gp -np h-BN.phonon > h-BN-phonon.plt You can then copy the h-BN-phonon.plt back to the PC and read this into GNUPLOT.","title":"Generation of IR spectrum"},{"location":"workshop/05_phonon/#generation-of-raman-spectrum","text":"The calculation of a raman intensities is fairly expensive compared to infrared matrix elements and it is therefore not turned on by default however the .param file turned this on: CALCULATE_RAMAN : TRUE RAMAN_METHOD : DFPT You can use the -raman flag of dos.pl to generate and plot a Raman spectrum.","title":"Generation of Raman spectrum"},{"location":"workshop/05_phonon/#b-molecular-modes-in-benzene","text":"The next part of this practical is to compute the modes and spectrum of a molecule and compare the result with a calculation of a molecular crystal. Our example is benzene First run the isolated molecule calculation. Using the supplied PDB format file and using the pdb2cell utility, generate a .cell file for a single molecule calculation. There are a few other considerations to take into account for an isolated molecule calculation. The size of the simulation cell governs the interactions between periodic copies of the molecule and should be large enough that these are negligible. The shape of the simulation cell governs the crystallographic point groups allowed in the handling of the symmetry. It should be chosen to be commensurate (as far as possible) with the molecular point group to maximise the use of symmetry. In the case of benzene it should obviously be hexagonal, here we use a box 8A by 8A by 4A. Recall that there is no electronic dispersion for a molecule, so only a single electronic k-point is needed. The general rule is that all \u201cmolecule in a box\u201d calculations should use the G point only as Castep uses special performance optimisations in this case. Use the norm-conserving pseudopotentials ( NCP in the species_pot block) For simplicity use the local density approximation, LDA . In benzene not all atoms are on special symmetry sites so you should first perform a geometry optimisation, keeping the unit cell fixed (see fix_all_cell keyword in Castep\u2019s help). Then set up a follow-on calculation to compute the Gamma point phonons using the continuation keyword in the .param file. The Phonons User Guide linked above should help you fill in the details, but please ask if you are stuck. Check the phonon frequencies. How many zero frequency modes are there? What frequencies do you get? Can you explain? Benzene Phase III: The next stage is to compute the \\Gamma \\Gamma point phonon modes of the molecular crystal of benzene in the high pressure polymorph, Phase III. You are supplied with a .pdb file. You should use a 2x2x2 grid of electronic k-points, as dispersion is non-zero in this molecular crystal. Make sure that symmetry is detected and enabled using symmetry_generate in the .cell file. Also check that the unit cell parameters are fixed to optimise the geometry and NCP pseudopotentials are used. Use the same .param file as for the molecular case to ensure the settings are the same. Similar to the molecular case run a geometry optimisation followed by a phonon calculation. Once these calculations have completed you should generate a phonon DOS and IR spectra as in the previous practical and compare the molecule with the molecular crystal. You can also use Jmol to identify the modes. Are all your frequencies positive? If not, can you suggest why not?","title":"B. Molecular modes in benzene"},{"location":"workshop/05_phonon/#c-phonon-dispersion-using-interpolation-in-nah","text":"From \\Gamma \\Gamma point only calculations we now explore the whole of the Brillouin zone of phonon wavevectors. Our example is the rocksalt-structured hydride, NaH which should run quickly enough to return results in a few minutes. Based on previous exercises, lectures and the user manual, you should be able to set up and run a DFPT phonon dispersion calculation and display a well converged set of dispersion curves. A starting point for your .cell file is: %block lattice_cart 2.0 2.0 0.0 2.0 0.0 2.0 0.0 2.0 2.0 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 H 0.5 0.5 0.5 %endblock positions_frac Symmetry_generate This contains the primitive fcc unit cell of the B1 rocksalt structure with the Na ion at (0,0,0) and the H ion at (\u00bd,\u00bd,\u00bd). This is a high-symmetry structure so it is important to instruct CASTEP to generate and use the full symmetry set. Also use norm-conserving pseudopotentials. A suitable list of points for the fine q-point path for an FCC crystal is: %block phonon_fine_kpoint_path 0.0 0.0 0.0 ! Gamma 0.5 0.5 0.0 ! X (along Delta 1.0 1.0 1.0 ! Gamma (Sigma ) 0.5 0.5 0.5 ! L (Delta) 0.5 0.75 0.25 ! W (Q) 0.5 0.5 0.0 ! X (Z) %endblock phonon_fine_kpoint_path Although you can now start the phonon calculation, knowing the accuracy of the result (error bounds) is good science. You should perform a k-point convergence test. For a phonon calculation, convergence of the forces is an appropriate test criterion. Since all of the ions are on symmetry positions the forces are zero by symmetry. Try to think of a way around this obstacle. And adopt a suitable compromise between accuracy and run-time.","title":"C. Phonon dispersion using interpolation in NaH"},{"location":"workshop/05_phonon/#cii-phonon-dos-using-interpolation","text":"The task here is to use the NaH example to compute and display not a dispersion curve but a density of states. This will exploit CASTEPs interpolation functionality, and you will be able to compute a good DOS without the need the repeat the expensive electronic structure calculation. To do this you will need to set up a calculation neatly identical to your previous one but with two differences. The calculation should be set up as a continuation. If your previous run wrote a .check file named NaH.check for example, then the param file should contain the line continuation : NaH.check Instead of a %block phonon_fine_kpoint_list in the .cell file, you can specify a grid phonon_fine_kpoint_mp_grid 16 16 16 You can run CASTEP on just 1-4 processors for this You can try this several times with different fine q-point grids. This will produce a .castep and .phonon file as before. You may analyse the .phonon file and generate a DOS using the dos.pl script dos.pl -xg NaH-dos.phonon (again, an X server running on the PC will be needed for grace to display; MobaXterm should have this enabled by default) .","title":"C.II Phonon DOS using interpolation"},{"location":"workshop/07_xc/","text":"XC-Functionals Introduction These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these functionals. They will also demonstrate the effect of chosen functional upon different physical properties. It is important to remember throughout that no XC functional is perfect (as discussed in the XC functional talk). In choosing a functional, we must be guided by an understanding of the XC functional itself and the physics of the system under consideration. It is also important to realise that sometimes ''inappropriate functionals get the 'right' answer for the wrong reasons!'' Some of these exercises will further illustrate this point. Many of the post-LDA functionals (HF, sX-LDA) are computationally intensive. For that reason, this practical session focusses upon small systems. However, by the end of this session you should be able to set up more complex and demanding systems. Where To Find Help If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep -help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep -help kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep -help search symmetry Finally, to list all keywords, use: $ castep -help search all Example 1 - Si: LDA and GGA In this first exercise, we shall explore how to use different XC functionals to determine the electronic structure of silicon. Get the files required for this exercise : Si2 files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. You can use: tar -xvf Si2.tar.gz We will begin by performing a simple band structure calculation. To do this, we must edit the Si2.param file. Open this file. Find the line that says task: . Amend this to say: task : bandstructure We can also choose the XC functional that we wish to employ in the param file. If we set xc_functional : lda then we will run a calculation using the LDA. This is the functional that will be employed in the SCF calculation that determines the ground state electronic density. If we do not specify otherwise, then it will also be used for the band structure calculation. Now we shall examine the .cell file. Open Si2.cell . Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including: %block species_pot NCP %endblock species_pot in your .cell file. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path: %block bs_kpoint_path 0.5 0.5 0.5 0.0 0.0 0.0 0.5 0.0 0.5 0.625 0.25 0.625 0.0 0.0 0.0 %endblock bs_kpoint_path Add this block to the .cell file. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. Now run CASTEP on arcus using the 2-atom input files. $ castepsub -n Number Si2 where Number should be replaced by the number of processors that you wish to use. This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Note down how long the calculation takes for each k-point. We will now analyse the band structure. We can produce a plot of this from the Si2.bands file using: dispersion.pl -xg -bs Si2.bands Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this? I recommend that you save the output from this calculation as Si2_lda or similar as later on we wish to compare with GGA and non-local calculations. Repeat steps 1-8 using a GGA functional. To change the functional employed, amend the .param file as follows: xc_functional : pw91 There is no single unique flavour of GGA, and this specifies the Perdew-Wang 91 implementation of the GGA. Other flavours such as PBE would be specified in similar fashion. How does the use of the GGA affect the band gap? Does it improve upon the LDA value? Why? Example 2 - Si: Non-local functionals We shall now move onto examining what happens with a non-local functional. In principle, we should, for a new functional, determine a ground state electronic density that is consistent with the functional employed. However, CASTEP allows us to be more flexible and to specify a different functional for the band structure calculation. We will use this to save some computational effort by using a LDA-derived ground state density. To begin, carry out a single-point energy calculation on our silicon system using the LDA. This calculation will be very quick. Alongside the .castep file, CASTEP there will also be a file Si2.check. This is the restart file. We will use this restart file to perform a band structure calculation using a different functional from that employed for the SCF. In the Si2.param file, add the following line: continuation : default This tells CASTEP that this is a re-start, and that the restart file is the default, which in this case is Si2.check. We could specify a different file here, if we wished. Add the following line to the .param file: bs_xc_functional : HF This allows us to specify a different functional for the band structure calculation, which in this case will be a Hartree-Fock calculation. However, we are using a LDA-derived ground state density to feed into this calculation. Now run the band structure calculation as before. When examining the .castep output look at the band structure timings. How do these compare to the LDA and GGA cases performed earlier? This should give some idea as to the more computationally intensive nature of a non-local calculation. Similarly, how do the memory estimates change? It is important to understand that this increased memory overhead can limit non-local calculations, even on HPC platforms (indeed, it can be more of a problem than the increased computational effort per step of the calculation). Plot the resulting band structure. How does this compare to the LDA and GGA values? How does the band gap compare? Why is this? Repeat steps 1-5, but for screened exchange with LDA correlation (sX-LDA). To do this, in Step 3 set bs_xc_functional : sX-lda Example 3 - FeO and DFT+U In the XC Functional talk, data were shown illustrating the effect of functional upon the electronic structure of antiferromagnetic FeO. In this example you will learn how to perform DFT+U calculations. Get the files required for this exercise : FeO Files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .cell file. We are interested in examining an anti-ferromagnetic structure. Note the following in the block where the atomic positions are specified: Fe 0.0 0.0 0.0 spin=-4.0 Fe 0.0 0.0 0.0 spin=4.0 This specifies the initial antiferromagnetic spin arrangement, with spin = N_\\text{up}-N_\\text{down} N_\\text{up}-N_\\text{down} defining the initial spin polarisation on each Fe atom. NOTE: the spins specified here should be consistent with the overall spin (i.e. the initial number of unpaired electrons) specified in the .param file using the spin keyword. In this case, as the overall spin is zero (which is the CASTEP default value), we do not need to specify this, but if we examined a ferromagnetic structure then we would. CONVERGENCE NOTE: I suggest using a 6x6x6 MP grid. While not as converged as one would desire for serious science, this is sufficient for demonstrative purposes, and will allow us to perform several calculations in the time available. As we saw in the XC presentation, PBE obtains a metallic ground state for antiferromagnetic FeO. We shall therefore run this calculation as a metal. Ensure that the .param file has the following line: fix_occupancy : false which allows CASTEP to vary electronic occupancies. We shall use the default metals method, which is density mixing. Density mixing is the only method in CASTEP that allows us to specify initial magnetic moments on atoms. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 4. As we wish to examine an anti-ferromagnetic structure in which individual Fe ions have non-zero spin, we must allow the system to be spin-polarised. To do this, open up and edit the .param file. Set: spin_polarized : true 5. We will set the XC functional to be the PBE flavour of GGA ( xc_functional : pbe ). Now run a band structure calculation and produce a band structure plot as before. There are certain features of the band structure plot that you should understand: the dispersive bands are ''sp'' bands derived from ''s'' and ''p'' electrons. The flat non-dispersive bands are derived from Fe ''d'' electrons. Can you explain why the ''d'' bands are so flat? When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section Atomic Populations (Mulliken) Note the spin on each Fe atom. How does this vary from the initial value specified? A DFT+U calculation To do this, open up and edit the .cell file. Add the following block to it: %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use ab initio calculations to determine a value of U then specify this in the .cell file. Run a band structure calculation and plot the results. How does this band structure compare to the PBE+U result? Can you explain which features change and which stay the same? What happens to the band gap? Now examine the spin on each Fe atom. Compare to the PBE values. Can you explain your observations? Repeat steps 7-9 for differing U values. Explain your findings. Example 4 - Graphite and DFT+D Graphite represents a prototypical example of a layered system in which the layers are weakly bound by van der Waals forces. As is well known, local and semi-local functionals such as the LDA and GGA neglect such interactions, and we could perhaps anticipate that they therefore perform poorly for such a system. We will explore the performance of these functionals. This example will also show you how to run dispersion corrected DFT+D functionals. Get the files required for this exercise : Graphite files As before, we shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .param file using a text editor. We will do our first calculation with the PBE GGA functional. Ensure that this is the xc functional specified (see above if you cannot recall how to do this). Graphite has a semimetallic nature, with a non-zero DOS at the Fermi energy for the K and H points in reciprocal space. We will therefore run this calculation as a metal, as we did in the FeO example. Modify the .param file to ensure that this is the case. In contrast to FeO, however, we do not need to worry about spin polarisation. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 We will run a geometry optimisation. Change the .param file so that this is the task. Now open up the .cell file using a text editor. We will perform our calculations for the experimental graphite structure. However, our atomic positions are slightly incommensurate with the symmetry of the unit cell; to remedy this, add the following line to the .cell file: snap_to_symmetry which puts the atoms on the symmetry positions. Now run a variable cell geometry optimisation. If you cannot recall how to do this, consult the earlier tutorial concerning geometry optimisations. Ensure that the calculation is converged with respect to both plane wave and k-point sampling. As we are interested in a geometry optimisation, examining the convergence with respect to force is a suitable criterion. However, as we have placed the ions on high symmetry positions, the forces on them will be zero by symmetry - can you think of how we can still examine the convergence of forces, given this fact? Once the calculation has completed, examine the unit cell parameters - how do they compare to the original (experimental) parameters? Can you explain this behaviour? We shall now investigate what happens with LDA. Repeat the above calculation with the LDA as the XC functional. What happens to the unit cell parameters in this case? Pay particular attention to the c axis. How does this compare to the GGA value? Is this behaviour expected? Can you explain it? Does this mean that LDA is particularly suitable to use to describe van der Waals bound systems? We shall now carry out a GGA calculation with a DFT+D correction. For this you can leave the .cell file unaltered. Open up the .param file using an editor. Add the following line: sedc_apply : true which tells CASTEP that it should apply the semi-empirical dispersion correction (i.e. DFT+D). Now specify the correction scheme. Begin with the G06 scheme (also known as D2): sedc_scheme : g06 Ensure that the XC functional to use is the PBE. Run the geometry optimisation. How do the results compare to the LDA and GGA answers? Repeat 10-13 but using the D4 correction scheme. How do the results change? NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution. NOTE2: the OBS scheme is not compatible with the PBE functional. Further examples If you have worked through to this point in the tutorial, then feel free to apply these functionals to some more sophisticated systems that interest you. If you do not have particular systems in mind, then feel free to discuss possible choices with a demonstrator.","title":" 8 XC"},{"location":"workshop/07_xc/#xc-functionals","text":"","title":"XC-Functionals"},{"location":"workshop/07_xc/#introduction","text":"These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these functionals. They will also demonstrate the effect of chosen functional upon different physical properties. It is important to remember throughout that no XC functional is perfect (as discussed in the XC functional talk). In choosing a functional, we must be guided by an understanding of the XC functional itself and the physics of the system under consideration. It is also important to realise that sometimes ''inappropriate functionals get the 'right' answer for the wrong reasons!'' Some of these exercises will further illustrate this point. Many of the post-LDA functionals (HF, sX-LDA) are computationally intensive. For that reason, this practical session focusses upon small systems. However, by the end of this session you should be able to set up more complex and demanding systems.","title":"Introduction"},{"location":"workshop/07_xc/#where-to-find-help","text":"If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep -help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep -help kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep -help search symmetry Finally, to list all keywords, use: $ castep -help search all","title":"Where To Find Help"},{"location":"workshop/07_xc/#example-1-si-lda-and-gga","text":"In this first exercise, we shall explore how to use different XC functionals to determine the electronic structure of silicon. Get the files required for this exercise : Si2 files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. You can use: tar -xvf Si2.tar.gz We will begin by performing a simple band structure calculation. To do this, we must edit the Si2.param file. Open this file. Find the line that says task: . Amend this to say: task : bandstructure We can also choose the XC functional that we wish to employ in the param file. If we set xc_functional : lda then we will run a calculation using the LDA. This is the functional that will be employed in the SCF calculation that determines the ground state electronic density. If we do not specify otherwise, then it will also be used for the band structure calculation. Now we shall examine the .cell file. Open Si2.cell . Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including: %block species_pot NCP %endblock species_pot in your .cell file. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path: %block bs_kpoint_path 0.5 0.5 0.5 0.0 0.0 0.0 0.5 0.0 0.5 0.625 0.25 0.625 0.0 0.0 0.0 %endblock bs_kpoint_path Add this block to the .cell file. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. Now run CASTEP on arcus using the 2-atom input files. $ castepsub -n Number Si2 where Number should be replaced by the number of processors that you wish to use. This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Note down how long the calculation takes for each k-point. We will now analyse the band structure. We can produce a plot of this from the Si2.bands file using: dispersion.pl -xg -bs Si2.bands Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this? I recommend that you save the output from this calculation as Si2_lda or similar as later on we wish to compare with GGA and non-local calculations. Repeat steps 1-8 using a GGA functional. To change the functional employed, amend the .param file as follows: xc_functional : pw91 There is no single unique flavour of GGA, and this specifies the Perdew-Wang 91 implementation of the GGA. Other flavours such as PBE would be specified in similar fashion. How does the use of the GGA affect the band gap? Does it improve upon the LDA value? Why?","title":"Example 1 - Si: LDA and GGA"},{"location":"workshop/07_xc/#example-2-si-non-local-functionals","text":"We shall now move onto examining what happens with a non-local functional. In principle, we should, for a new functional, determine a ground state electronic density that is consistent with the functional employed. However, CASTEP allows us to be more flexible and to specify a different functional for the band structure calculation. We will use this to save some computational effort by using a LDA-derived ground state density. To begin, carry out a single-point energy calculation on our silicon system using the LDA. This calculation will be very quick. Alongside the .castep file, CASTEP there will also be a file Si2.check. This is the restart file. We will use this restart file to perform a band structure calculation using a different functional from that employed for the SCF. In the Si2.param file, add the following line: continuation : default This tells CASTEP that this is a re-start, and that the restart file is the default, which in this case is Si2.check. We could specify a different file here, if we wished. Add the following line to the .param file: bs_xc_functional : HF This allows us to specify a different functional for the band structure calculation, which in this case will be a Hartree-Fock calculation. However, we are using a LDA-derived ground state density to feed into this calculation. Now run the band structure calculation as before. When examining the .castep output look at the band structure timings. How do these compare to the LDA and GGA cases performed earlier? This should give some idea as to the more computationally intensive nature of a non-local calculation. Similarly, how do the memory estimates change? It is important to understand that this increased memory overhead can limit non-local calculations, even on HPC platforms (indeed, it can be more of a problem than the increased computational effort per step of the calculation). Plot the resulting band structure. How does this compare to the LDA and GGA values? How does the band gap compare? Why is this? Repeat steps 1-5, but for screened exchange with LDA correlation (sX-LDA). To do this, in Step 3 set bs_xc_functional : sX-lda","title":"Example 2 - Si: Non-local functionals"},{"location":"workshop/07_xc/#example-3-feo-and-dftu","text":"In the XC Functional talk, data were shown illustrating the effect of functional upon the electronic structure of antiferromagnetic FeO. In this example you will learn how to perform DFT+U calculations. Get the files required for this exercise : FeO Files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .cell file. We are interested in examining an anti-ferromagnetic structure. Note the following in the block where the atomic positions are specified: Fe 0.0 0.0 0.0 spin=-4.0 Fe 0.0 0.0 0.0 spin=4.0 This specifies the initial antiferromagnetic spin arrangement, with spin = N_\\text{up}-N_\\text{down} N_\\text{up}-N_\\text{down} defining the initial spin polarisation on each Fe atom. NOTE: the spins specified here should be consistent with the overall spin (i.e. the initial number of unpaired electrons) specified in the .param file using the spin keyword. In this case, as the overall spin is zero (which is the CASTEP default value), we do not need to specify this, but if we examined a ferromagnetic structure then we would. CONVERGENCE NOTE: I suggest using a 6x6x6 MP grid. While not as converged as one would desire for serious science, this is sufficient for demonstrative purposes, and will allow us to perform several calculations in the time available. As we saw in the XC presentation, PBE obtains a metallic ground state for antiferromagnetic FeO. We shall therefore run this calculation as a metal. Ensure that the .param file has the following line: fix_occupancy : false which allows CASTEP to vary electronic occupancies. We shall use the default metals method, which is density mixing. Density mixing is the only method in CASTEP that allows us to specify initial magnetic moments on atoms. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 4. As we wish to examine an anti-ferromagnetic structure in which individual Fe ions have non-zero spin, we must allow the system to be spin-polarised. To do this, open up and edit the .param file. Set: spin_polarized : true 5. We will set the XC functional to be the PBE flavour of GGA ( xc_functional : pbe ). Now run a band structure calculation and produce a band structure plot as before. There are certain features of the band structure plot that you should understand: the dispersive bands are ''sp'' bands derived from ''s'' and ''p'' electrons. The flat non-dispersive bands are derived from Fe ''d'' electrons. Can you explain why the ''d'' bands are so flat? When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section Atomic Populations (Mulliken) Note the spin on each Fe atom. How does this vary from the initial value specified?","title":"Example 3 - FeO and DFT+U"},{"location":"workshop/07_xc/#a-dftu-calculation","text":"To do this, open up and edit the .cell file. Add the following block to it: %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use ab initio calculations to determine a value of U then specify this in the .cell file. Run a band structure calculation and plot the results. How does this band structure compare to the PBE+U result? Can you explain which features change and which stay the same? What happens to the band gap? Now examine the spin on each Fe atom. Compare to the PBE values. Can you explain your observations? Repeat steps 7-9 for differing U values. Explain your findings.","title":"A DFT+U calculation"},{"location":"workshop/07_xc/#example-4-graphite-and-dftd","text":"Graphite represents a prototypical example of a layered system in which the layers are weakly bound by van der Waals forces. As is well known, local and semi-local functionals such as the LDA and GGA neglect such interactions, and we could perhaps anticipate that they therefore perform poorly for such a system. We will explore the performance of these functionals. This example will also show you how to run dispersion corrected DFT+D functionals. Get the files required for this exercise : Graphite files As before, we shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .param file using a text editor. We will do our first calculation with the PBE GGA functional. Ensure that this is the xc functional specified (see above if you cannot recall how to do this). Graphite has a semimetallic nature, with a non-zero DOS at the Fermi energy for the K and H points in reciprocal space. We will therefore run this calculation as a metal, as we did in the FeO example. Modify the .param file to ensure that this is the case. In contrast to FeO, however, we do not need to worry about spin polarisation. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 We will run a geometry optimisation. Change the .param file so that this is the task. Now open up the .cell file using a text editor. We will perform our calculations for the experimental graphite structure. However, our atomic positions are slightly incommensurate with the symmetry of the unit cell; to remedy this, add the following line to the .cell file: snap_to_symmetry which puts the atoms on the symmetry positions. Now run a variable cell geometry optimisation. If you cannot recall how to do this, consult the earlier tutorial concerning geometry optimisations. Ensure that the calculation is converged with respect to both plane wave and k-point sampling. As we are interested in a geometry optimisation, examining the convergence with respect to force is a suitable criterion. However, as we have placed the ions on high symmetry positions, the forces on them will be zero by symmetry - can you think of how we can still examine the convergence of forces, given this fact? Once the calculation has completed, examine the unit cell parameters - how do they compare to the original (experimental) parameters? Can you explain this behaviour? We shall now investigate what happens with LDA. Repeat the above calculation with the LDA as the XC functional. What happens to the unit cell parameters in this case? Pay particular attention to the c axis. How does this compare to the GGA value? Is this behaviour expected? Can you explain it? Does this mean that LDA is particularly suitable to use to describe van der Waals bound systems? We shall now carry out a GGA calculation with a DFT+D correction. For this you can leave the .cell file unaltered. Open up the .param file using an editor. Add the following line: sedc_apply : true which tells CASTEP that it should apply the semi-empirical dispersion correction (i.e. DFT+D). Now specify the correction scheme. Begin with the G06 scheme (also known as D2): sedc_scheme : g06 Ensure that the XC functional to use is the PBE. Run the geometry optimisation. How do the results compare to the LDA and GGA answers? Repeat 10-13 but using the D4 correction scheme. How do the results change? NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution. NOTE2: the OBS scheme is not compatible with the PBE functional.","title":"Example 4 - Graphite and DFT+D"},{"location":"workshop/07_xc/#further-examples","text":"If you have worked through to this point in the tutorial, then feel free to apply these functionals to some more sophisticated systems that interest you. If you do not have particular systems in mind, then feel free to discuss possible choices with a demonstrator.","title":"Further examples"},{"location":"workshop/08_cif2cell/","text":"We will use cif to cell to generate cell files from cif files. Cif files can be obtained from the ICSD (inorganic crystals) or the CSD (molecular crystals). '''MgO''' Examine the file . Look at the crystal structure with jmol or magresview (drag and drop the file onto the magresview window). You will see a cubic face-centre cubic cell. How many atoms in the cell? Use cif2cell to convert this cif file to a cell file. cif2cell MgO.cif --program=castep -o MgO.cell Look at the cell file. How many atoms in the cell? View this will jmol or magresview. Do you understand what cif2cell has done? '''Molecular Tweezers''' Examine the file","title":" 9 Cif2cell"},{"location":"workshop/09_md/","text":"Molecular Dynamics Learning Objectives Perform ab initio molecular dynamics calculations on simple systems. Investigate factors affecting energy conservation, etc. Use various tools to visualize and analyze the results. N 2 Dimer As a simple example, we will explore the system discussed in the lecture -- the N2 dimer. Download the input files MD_N2.tar.gz Unzip and untar the files, then move into the new directory tar -xzvf MD_N2.tar.gz cd N2 Run this and then read the N2.castep file -- see how the MD information is reported. Plot a graph of temperature vs. time -- does it look correct? Hint: try grep Temp N2.castep | awk '{print c++,$3}' > N2.T to get a 2-column file of temperature vs MD step. Is there an initial transient? What is the effect of electronic convergence ( cut_off_energy , elec_energy_tol , etc) on the energy conservation? What is the effect of changing the time step or the thermostat used? Plot a graph of \"Hamilt Energy\" vs MD step to see. Make a movie of your dynamics. Load the N2.md file in jmol and use Tools/Animate to see it in action. Calculate the average bond length, as a function of temperature -- is the system harmonic or anharmonic? Hint: try something like this: grep ' N 1' N2.castep | awk '{print $4,$5,$6}' > N2.r1 grep ' N 2' N2.castep | awk '{print $4,$5,$6}' > N2.r2 paste N2.r1 N2.r2 | awk '{print c++,10.0*sqrt(($4-$11)^2+($5-$12)^2+($6-$13)^2)}' > N2.r12 H 2 Molecule Copy the N2.cell and N2.param files to a new directory, and edit them to create a suitable set of input files for the H 2 molecule. Use CASTEP to run MD on this new system for a similar amount of time. Do you have any problems? How can you solve them? Extension activities If you wish to explore further, you can use MD to study any system (aperiodic, supercell, bulk etc) that you are interested in. There are many properties that can be calculated sampled within an MD run. For example, if you have population analysis turned on, set md_sample_iter=10 to re-calculate it every 10 steps during the MD run. You can also analyse the resulting MD trajectory using tools such as mdtep . Using MDTEP MDTEP is designed to analyse a CASTEP .md file. To use it you should take the example mdtep input file and customize it as you wish and put it in the directory with your MD run. You can then use it to analyse your MD run using: mdtep mdtep_sample.input Ovito You can also use the Ovito post-processing tool which can read CASTEP output files.","title":" 4 MD"},{"location":"workshop/09_md/#molecular-dynamics","text":"","title":"Molecular Dynamics"},{"location":"workshop/09_md/#learning-objectives","text":"Perform ab initio molecular dynamics calculations on simple systems. Investigate factors affecting energy conservation, etc. Use various tools to visualize and analyze the results.","title":"Learning Objectives"},{"location":"workshop/09_md/#n2-dimer","text":"As a simple example, we will explore the system discussed in the lecture -- the N2 dimer. Download the input files MD_N2.tar.gz Unzip and untar the files, then move into the new directory tar -xzvf MD_N2.tar.gz cd N2 Run this and then read the N2.castep file -- see how the MD information is reported. Plot a graph of temperature vs. time -- does it look correct? Hint: try grep Temp N2.castep | awk '{print c++,$3}' > N2.T to get a 2-column file of temperature vs MD step. Is there an initial transient? What is the effect of electronic convergence ( cut_off_energy , elec_energy_tol , etc) on the energy conservation? What is the effect of changing the time step or the thermostat used? Plot a graph of \"Hamilt Energy\" vs MD step to see. Make a movie of your dynamics. Load the N2.md file in jmol and use Tools/Animate to see it in action. Calculate the average bond length, as a function of temperature -- is the system harmonic or anharmonic? Hint: try something like this: grep ' N 1' N2.castep | awk '{print $4,$5,$6}' > N2.r1 grep ' N 2' N2.castep | awk '{print $4,$5,$6}' > N2.r2 paste N2.r1 N2.r2 | awk '{print c++,10.0*sqrt(($4-$11)^2+($5-$12)^2+($6-$13)^2)}' > N2.r12","title":"N2 Dimer"},{"location":"workshop/09_md/#h2-molecule","text":"Copy the N2.cell and N2.param files to a new directory, and edit them to create a suitable set of input files for the H 2 molecule. Use CASTEP to run MD on this new system for a similar amount of time. Do you have any problems? How can you solve them?","title":"H2 Molecule"},{"location":"workshop/09_md/#extension-activities","text":"If you wish to explore further, you can use MD to study any system (aperiodic, supercell, bulk etc) that you are interested in. There are many properties that can be calculated sampled within an MD run. For example, if you have population analysis turned on, set md_sample_iter=10 to re-calculate it every 10 steps during the MD run. You can also analyse the resulting MD trajectory using tools such as mdtep .","title":"Extension activities"},{"location":"workshop/09_md/#using-mdtep","text":"MDTEP is designed to analyse a CASTEP .md file. To use it you should take the example mdtep input file and customize it as you wish and put it in the directory with your MD run. You can then use it to analyse your MD run using: mdtep mdtep_sample.input","title":"Using MDTEP"},{"location":"workshop/09_md/#ovito","text":"You can also use the Ovito post-processing tool which can read CASTEP output files.","title":"Ovito"},{"location":"workshop/10_GA/","text":"Introduction In this practical we will gain hands on experience using the CASTEP GA to find some `unknown' structures. We will then utilise an on-the-fly machine learned GAP potential to reduce the cost of an ab-initio geometry optimisation. Throughout this practical we will make use of the Stillinger-Weber (SW) pair potential. This allows GA runs to be carried out in a short time on desktops, though all of the approaches translate directly to ab-initio methods. Pair potentials (PP) are fast but far from perfect. Specifically, resultant cells from PP GA runs may not match structures found in nature (or with DFT), but instead be the lowest enthalpy cells based in the PP energy landscape. N.B. The CASTEP GA (specifically the convex hull algorithm) is currently in development. This means that some of the devel code parameters will be promoted to standard input flags. Therefore, the exact keywords used for some of the options in this practical may differ from the release version (though all the functionality will be there). Therefore, if using the GA in future the documentation should be consulted first. As a quick recap the CASTEP GA has 7 main steps: Generate an initial randomised population of parent cells. Perform a geometry optimisation to relax the parents & find their enthalpy based fitness. Select parents based on their fitness for breeding and breed to create a population of children. Mutate the children with a given probability (and to ensure no ionic overlaps). Relax these children with a geometry optimisation & find the enthalpy based fitness of patents and children. If the population has converged, or we have reach maximum allowed generations, then exit. Select members of parents and children based of fitness to be the next generation of parents and go to 3. Setup In this workshop we will be running on a remote machine, teaching0 . However, you can also access all the files in your user directory from the desktop machines. This means, if you would prefer to edit or view files on the desktops rather than the command line you can. All CASTEP commands must however be carried out on the command line on teaching0 . We should then log on to teaching0 using ssh -Y USER@teaching0 where USER should be replaced with your username. We then need to load the environment that contains all the programs we will need ( castep.mpi , castep_GA etc) with source /tmp/castep_GA_workshop_venv/bin/activate This should make everything we need available to us and you should now see (castep_GA_workshop_venv) USER@teaching0: on your command line. Note: if the terminal window is closed, or we disconnect from teaching0 this source command will have to be re-ran to re-load all the required packages. You should be in your home directory, so now extract the GA workshop files into your home directory tar -zxf /tmp/CASTEP_workshop_GA.tar.gz which should create the directory CASTEP_workshop_GA containing all the files we will need in this workshop. Move into this directory with cd CASTEP_workshop_GA CASTEP GA for Ground State Silicon Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA! Input Files First navigate to the directory cd CASTEP_workshop_GA/1_Si_SW_GA which should contain a CASTEP Si.cell and Si.param file, as well as the bash script get_data.sh and a python script plot_results.py (which we will use for results analysis later). Like standard CASTEP, the CASTEP GA requires both a cell and a param file input. However, we likely do not know what the best cell structure is. As such, we give a cell that contains multiple ions of the species that we are interested in. The number of ions given in this cell is used as a baseline for the number of ions in cells created & bred over the course of the GA, where at least one ion of each species will always be represented at least once in each cell. We can also fix the number of ions in each population member to match that in the input cell. We should not add too few ions, as cells with more ions contain more `genetic information', meaning smaller cells don't benefit from breeding operations as much. The exact positions of the ions in the input cell file does not matter, as they will be randomised during the initial population generation. However, the cell given should be a `reasonable' guess w.r.t. the cell density (as the density of the input cell is used when creating the initial randomised population). I.e. the total density of the input cell should not be unreasonable, though the exact ionic positions do not matter. For example, looking at the Si.cell in ./1_Si_SW_GA/Si.cell we see the cell is cubic with a not unreasonable volume for 8 Si ions, though the positions of those 8 ions is random. The param file is similar to a standard CASTEP input file, with some extra GA specific parameters. The GA copies all of the parameters to each bred population member, changing only the task to geometry optimization , before performing geometry optimisations for fitness evaluation. This means we can use any of the tools CASTEP has available during the populations geometry optimisation. N.B. any GA parameters passed to a standard CASTEP geometry optimisation, e.g. ga_pop_size , are ignored by CASTEP. Looking at the Si.param file we see the task is set to genetic algor and we are running with a population size of 12 over 12 generations. There are a few GA specific parameters given in the devel code block, the main ones are CMD: mpirun -n 1 castep.mpi :ENDCMD This gives the command that will be used to call CASTEP to perform the geometry optimisations on each population member. This can be changed to any valid call, for example to run over many cores. A serial calculation is used here as we are using cheap pair potentials. AS=T and MS=3 This allows asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. These parameters are chosen due to computational resources available in this workshop, but can be trivially increased based on available resources. The large comment block at the bottom of the input file lists a lot of parameters that can be used with the various GA methods currently implemented. However, for now let's run a GA! Running the CASTEP GA (Approx. 5-6 mins runtime) First lets check our CASTEP and CASTEP GA binaries are accessible by running: which castep_GA && which castep.mpi This should return something like /tmp/castep_GA_workshop_venv/bin/castep_GA /tmp/castep_GA_workshop_venv/bin/castep.mpi Your paths may differ but as long as this command completes without error everything we need is (hopefully) set up correctly. To run CASTEP GA simply call castep_GA Si and the GA will start, which will take approximately 5-6 minutes to run. While this is running have a look at the next subsection for a description of the output files that are being created. CASTEP GA Output Files The CASTEP GA generates a lot of output files; as well as a main GA output .castep there are also input and output files for each population member. The population member seeds are labeled with the generation and population number, for example Si.gen_002_mem_006.cell is the input cell file for the 6 th member of generation 2. You should see input files being generated periodically (a generation at a time). In-between the output file generation geometry optimisations are automatically performed on each population member (here asynchronously 3 at a time). If the Si CASTEP run we started in the last section is still running we can have a look at the main output file. In a new terminal window navigate to ./CASTEP_workshop_GA/1_Si_SW_GA and run tail -f Si.castep This will show us the output of the main GA Si.castep file being generated in real time. The main output file contains a lot of information and can be a bit overwhelming. It gives all the parent structures and the pre and post geometry optimisation child structures as well as information about mutation operations. Once this GA run has completed move on to the next section to analyse our output files. Analysing the GA Output Files The GA saves the post geometry optimisation structures from all evaluated population members in the file .xyz in standard xyz format. We can view a nice animation of all of the structures the GA explored with jmol by opening this xyz file in jmol with Jmol.jar Si.xyz then going to tools -> animate -> once . In order to analyse the structures created by the GA in more detail we could look at just the enthalpy of the structures, where we may be most interested in the lowest enthalpy structure found. The GA always takes the lowest enthalpy cell into the next generation, so we can look at the last generation to find the lowest enthalpy cell with grep Si.castep -e \"GA: gen # 12\" | tail -n 24 | sort -k10,10g which gives the final generation in order of enthalpy (in eV/ion). However, we gain a lot of information about the phase space with the other cells the GA finds on the way to the minimum enthalpy cell. To explore this a bit more run ./get_data.sh You may need to make this executable by running chmod u+x get_data.sh . This script generates an output file out.put that contains a summary of the data for each population member in 9 columns: Generation number. Parent or child. Member number. Error file detected (T or F). Geometry optimisation converged (T or F). Number of ions in the cell. Enthalpy per ion of converged cell (in eV/ion). Volume of converged cell (in Angstrom/ion). Member filename. We can then plot the population as the enthalpy (per ion) against the cell volume (per ion) by running the python script python plot_results.py This will produce two plots; one is an animation of the population members in each generation, the other is every explored population member over all generations with the lowest enthalpy structure labeled. It will also save these to the current directory. From this representation we can gain information about the phase space of SW Si, where the lower enthalpy structures represent structures on the energy-volume curve for SW Si. There are also structures found by the GA above the energy-volume curve that are likely unstable. We can have a look at the structure of the lowest enthalpy cell (as labeled on your graph) with jmol (or your crystal structure viewing program of choice). If using jmol run Jmol.jar -out.cell where is the seed of the lowest enthalpy population member given on the output graph and the -out.cell postfix gives us the structure post geometry optimisation (it is important to look at this cell rather than the input cell). For example, for me (though your seed may be different than this) this is Jmol.jar Si.gen_006_mem_012-out.cell It can sometimes be difficult to figure out the exact space group of crystals from a visual inspection. So, we can use c2x to find the space group of our lowest enthalpy cell within a tolerance with c2x --int -e=0.1-0.0001 -out.cell which for my lowest enthalpy member is c2x --int -e=0.1-0.0001 Si.gen_006_mem_012-out.cell For me this gives the output Tol=0.001 International symmetry is Fd-3m which is the diamond structure space group we would expect for Si. GA Continuation (Approx. 2 mins runtime) It is possible you won't find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure (or one close to it, remember the GA is a coarse search) as there is some randomness in a GA run and our population size and number of generations is small. But don't worry, it is possible to restart a GA run from exactly where you left off. Let's do this now (even if you did find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure). To perform a continuation open the Si.param file in your text editor of choice. We then tell CASTEP GA we want to continue from where we left off. We do this by giving the location of the .xyz file that contains all explored structures by uncommenting the following in the Si.param file # continuation = Si.xyz so it reads continuation = Si.xyz Also, we want to run for more generations, so change the value for ga_max_gens from 12 to 18 (to run 6 more generations) i.e. in the Si.param file change the line ga_max_gens = 12 # Max number of generations to run for to ga_max_gens = 18 # Max number of generations to run for Important: Do not change the ga_pop_size as this will cause an error. We can then call CASTEP GA as before with castep_GA Si and it will read in the members from generation 12 of our last run and start generation 13 from these. Running for generations 13 to 16 should take approximately 1-2 minutes. Have a look at the outputs of this run by re-running ./get_data.sh and then plotting with python plot_results.py You may want to have a look at the lowest enthalpy structure with Jmol. You may also want to have a look at some of the other structures that are low on the energy/volume plot (a good way to find their seed names will be from the out.put file). SiC Stillinger-Weber GA Now we will look at exploring a more complicated potential energy landscape, to do this we first navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA Luckily CASTEP allows us to add our own parameterisation values for pair potentials. A parameterisation for an SiC SW pair potential has been added to the devel code block of the parameter file SiC.param . This parameterisation leads to a more complex potential energy landscape than we saw with Si. Due to the limitations of this pair potential parameterisation the GA will find different structures than we would find with ab-inito calculations as this is a pair potential energy landscape. However, it will run quickly enough to be usable with the computational and time resources available. As such we will use the GA to explore this unknown potential energy landscape as we did with Si. N.B. Everything we are doing here works just the same with DFT. Running the CASTEP GA (Approx. 5-10 mins runtime) The SiC.param file is very similar to the one used for Si, except the initial population is no longer completely random but instead generated as random high symmetry cells. The cell file contains an equal number of Si and C ions in random positions in a not unreasonably sized cell for this many ions Si and C ions. To run CASTEP GA execute castep_GA SiC and the GA will start, which will take approximately 6-7 minutes to run. You may want to look at the outputs as we did before, or take a quick break! Analysing the GA Output Files The GA outputs for this SiC run can be analysed in the same way as in the case of Si. We can use the same scripts as earlier to create energy volume plots by running ./get_data.sh && python plot_results.py Where this energy volume graph can be analysed as with Si. Make a note of the lowest enthalpy cell for use later. If it looks like would benefit from running a few more generations, we can run a continuation using the same methods as before. Have a look at the cell of the lowest enthalpy structure. It's likely that it seems a bit different to what we would expect in nature. As such, it would be good if we could run a full DFT calculation on some of the cells that have been found by the GA rather than relying on this pair potential parameterisation. However, we are a bit limited in computer power running, with all of the previous runs using only 3 cores. To overcome this hurdle we will exploit machine learning with Gaussian approximation potentials (GAP). Gaussain Approximation Potential Accelerated Geometry Optimisation A common approach to machine learning is to train a model on some dataset of known solutions to a problem. This presents an issue with the application of machine learning to crystal structure optimisation for materials discovery as by definition the parameter landscape is not explored. One approach to this in CASTEP is to use a number of initial geometry optimisation or molecular dynamics steps ran with ab-initio methods as the initial training data. Subsequent geometry optimisation steps are then ran with a machine learned potential using Gaussian approximation potentials (GAP). Ions move over the course of geometry optimisations (or molecular dynamics calculations), therefore the landscape may change such that the potential needs some extra ab-inito data to train on. As such, CASTEP adaptively chooses geometry optimisation steps over the course of the calculation to run with DFT which are then used to re-train the GAP potential. More information about this method is available in the paper by Stenczel et al 1 . In general, less and less DFT geometry optimisation or MD steps will be required as the calculation continues and samples the parameter space more thoroughly (again see 1 ). Note: All methods that are outlined here for the acceleration of a geometry optimisation can also be directly applied to molecular dynamics calculations. In practice, as the cost savings are generally greater the more steps are in the calculation, the cost savings of GAP are greatest for long running molecular dynamics calculations. Using GAP to Accelerate a Geometry Optimisation We now navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA/DFT_polish_GAP which contains 3 files. The first is the SiC_GA_best.cell , we should open this and replace the lattice and positions blocks with those from the best cell from our previous SiC run (that we made a note of earlier, if that note is lost open the image ../all_gens.png ). For me the best cell is ../SiC.gen_009_mem_006-out.cell , but for you this could be different. The cell file we also specifies the QC5 pseudopotential library, a kpoint grid spacing and that the geometry optimisation will be fixed cell. The SiC_GA_best.param file contains standard CASTEP parameters for a Damped Molecular Dynamics (DMD) geometry optimisation. Along with this is the devel code block required to call hybrid-md (which then calls gap_fit ) to perform the GAP fitting. Finally, there is an extra input file required for a GAP run, the .hybrid-md-input.yaml file. This contains specific inputs relating to the GAP fitting. Here we specify a mandatory 10 initial DFT steps for the initial training dataset. After this we specify a minimum of 10 steps with the machine learned potential before re-fitting, whilst allowing CASTEP to vary the number of steps between re-fittings. We also allow GAP to also parellise over 3 cores. N.B. The GAP run we carry out here has rather coarse convergence parameters, designed to allow for a fast run on a desktop in this workshop. Running CASTEP with GAP (Approx. 10-15 mins runtime) To run CASTEP to perform the damped MD geometry optimisation with the aid of GAP call mpirun -n 3 castep.mpi SiC_GA_best Whilst this is running (which will take 10 to 15 minutes) there will be information printed to the terminal window each DMD step. This states if the step is an initial (DFT) step, if the step is using the machine learned potential or if it is being ran with DFT in order to perform a re-fit. It may be illustrative to open a new terminal window, navigate to the working directory and tail the .castep output file with tail -f SiC_GA_best.castep in order to see the geometry optimisation running. Notice the steps using the machine learned potential are essentially free when compared with the DFT steps that require SCF calculations. Looking at the GAP Geometry Optimisation Results First, let us consider the cost of this geometry optimisation. My calculation ran for a total of 152 DMD steps, though your mileage may vary. Using the following command we can see on which DMD steps CASTEP decided to perform DFT calculations grep SiC_GA_best.castep -e \"Decided to perform\" We can also see how many of the DMD steps utilised DFT grep SiC_GA_best.castep -e \"Decided to perform\" | wc -l In my case this showed that 22 of the total DMD steps were using DFT, therefore approximately 85% of the DMD steps were carried out with the machine learned potential. Though there is a cost associated with these steps and with the re-fitting of the GAP potential, it is clear this represents a large cost saving. Very roughly (based on average time for one SCF cycle in my DMD run) without GAP this run would have taken approximately 4 times as long for no extra information. We can also visualize (using jmol or similar) both the output structure from the DMD run ( SiC_GA_best-out.cell ) and the pre-geometry optimisation structure ( SiC_GA_best.cell ). It is likely these are quite different. This is due to the difference (and lower quality!) of the SW parameterisation compared with any DFT approach. (Optional Extension) Running GA with Other Systems You may also want to try the CASTEP GA with another system or pair potential parameterisation (it is likely not possible to run a full DFT run of the GA in the timescale of this practical). If this is the case you can use the blank input file in ./CASTEP_workshop_GA/2.5_GA_blank (Optional Extension) Running GAP with Other Systems If you are interested in applying GAP to your calculations you may want to try GAP with a material of interest to you. If you would like to try with a cell and parameters of your choice there are blank input files in ./CASTEP_workshop_GA/2.5_GAP_blank Footnotes 1 Tam\u00e1s K. Stenczel, Zakariya El-Machachi, Guoda Liepuoniute, Joe D. Morrow, Albert P. Bart\u00f3k, Matt I. J. Probert, G\u00e1bor Cs\u00e1nyi, Volker L. Deringer; Machine-learned acceleration for molecular dynamics in CASTEP. J. Chem. Phys. 28 July 2023; 159 (4): 044803. https://doi.org/10.1063/5.0155621","title":"10 Genetic Algorithm"},{"location":"workshop/10_GA/#introduction","text":"In this practical we will gain hands on experience using the CASTEP GA to find some `unknown' structures. We will then utilise an on-the-fly machine learned GAP potential to reduce the cost of an ab-initio geometry optimisation. Throughout this practical we will make use of the Stillinger-Weber (SW) pair potential. This allows GA runs to be carried out in a short time on desktops, though all of the approaches translate directly to ab-initio methods. Pair potentials (PP) are fast but far from perfect. Specifically, resultant cells from PP GA runs may not match structures found in nature (or with DFT), but instead be the lowest enthalpy cells based in the PP energy landscape. N.B. The CASTEP GA (specifically the convex hull algorithm) is currently in development. This means that some of the devel code parameters will be promoted to standard input flags. Therefore, the exact keywords used for some of the options in this practical may differ from the release version (though all the functionality will be there). Therefore, if using the GA in future the documentation should be consulted first. As a quick recap the CASTEP GA has 7 main steps: Generate an initial randomised population of parent cells. Perform a geometry optimisation to relax the parents & find their enthalpy based fitness. Select parents based on their fitness for breeding and breed to create a population of children. Mutate the children with a given probability (and to ensure no ionic overlaps). Relax these children with a geometry optimisation & find the enthalpy based fitness of patents and children. If the population has converged, or we have reach maximum allowed generations, then exit. Select members of parents and children based of fitness to be the next generation of parents and go to 3.","title":"Introduction"},{"location":"workshop/10_GA/#setup","text":"In this workshop we will be running on a remote machine, teaching0 . However, you can also access all the files in your user directory from the desktop machines. This means, if you would prefer to edit or view files on the desktops rather than the command line you can. All CASTEP commands must however be carried out on the command line on teaching0 . We should then log on to teaching0 using ssh -Y USER@teaching0 where USER should be replaced with your username. We then need to load the environment that contains all the programs we will need ( castep.mpi , castep_GA etc) with source /tmp/castep_GA_workshop_venv/bin/activate This should make everything we need available to us and you should now see (castep_GA_workshop_venv) USER@teaching0: on your command line. Note: if the terminal window is closed, or we disconnect from teaching0 this source command will have to be re-ran to re-load all the required packages. You should be in your home directory, so now extract the GA workshop files into your home directory tar -zxf /tmp/CASTEP_workshop_GA.tar.gz which should create the directory CASTEP_workshop_GA containing all the files we will need in this workshop. Move into this directory with cd CASTEP_workshop_GA","title":"Setup"},{"location":"workshop/10_GA/#castep-ga-for-ground-state-silicon","text":"Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA!","title":"CASTEP GA for Ground State Silicon"},{"location":"workshop/10_GA/#input-files","text":"First navigate to the directory cd CASTEP_workshop_GA/1_Si_SW_GA which should contain a CASTEP Si.cell and Si.param file, as well as the bash script get_data.sh and a python script plot_results.py (which we will use for results analysis later). Like standard CASTEP, the CASTEP GA requires both a cell and a param file input. However, we likely do not know what the best cell structure is. As such, we give a cell that contains multiple ions of the species that we are interested in. The number of ions given in this cell is used as a baseline for the number of ions in cells created & bred over the course of the GA, where at least one ion of each species will always be represented at least once in each cell. We can also fix the number of ions in each population member to match that in the input cell. We should not add too few ions, as cells with more ions contain more `genetic information', meaning smaller cells don't benefit from breeding operations as much. The exact positions of the ions in the input cell file does not matter, as they will be randomised during the initial population generation. However, the cell given should be a `reasonable' guess w.r.t. the cell density (as the density of the input cell is used when creating the initial randomised population). I.e. the total density of the input cell should not be unreasonable, though the exact ionic positions do not matter. For example, looking at the Si.cell in ./1_Si_SW_GA/Si.cell we see the cell is cubic with a not unreasonable volume for 8 Si ions, though the positions of those 8 ions is random. The param file is similar to a standard CASTEP input file, with some extra GA specific parameters. The GA copies all of the parameters to each bred population member, changing only the task to geometry optimization , before performing geometry optimisations for fitness evaluation. This means we can use any of the tools CASTEP has available during the populations geometry optimisation. N.B. any GA parameters passed to a standard CASTEP geometry optimisation, e.g. ga_pop_size , are ignored by CASTEP. Looking at the Si.param file we see the task is set to genetic algor and we are running with a population size of 12 over 12 generations. There are a few GA specific parameters given in the devel code block, the main ones are CMD: mpirun -n 1 castep.mpi :ENDCMD This gives the command that will be used to call CASTEP to perform the geometry optimisations on each population member. This can be changed to any valid call, for example to run over many cores. A serial calculation is used here as we are using cheap pair potentials. AS=T and MS=3 This allows asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. These parameters are chosen due to computational resources available in this workshop, but can be trivially increased based on available resources. The large comment block at the bottom of the input file lists a lot of parameters that can be used with the various GA methods currently implemented. However, for now let's run a GA!","title":"Input Files"},{"location":"workshop/10_GA/#running-the-castep-ga-approx-5-6-mins-runtime","text":"First lets check our CASTEP and CASTEP GA binaries are accessible by running: which castep_GA && which castep.mpi This should return something like /tmp/castep_GA_workshop_venv/bin/castep_GA /tmp/castep_GA_workshop_venv/bin/castep.mpi Your paths may differ but as long as this command completes without error everything we need is (hopefully) set up correctly. To run CASTEP GA simply call castep_GA Si and the GA will start, which will take approximately 5-6 minutes to run. While this is running have a look at the next subsection for a description of the output files that are being created.","title":"Running the CASTEP GA (Approx. 5-6 mins runtime)"},{"location":"workshop/10_GA/#castep-ga-output-files","text":"The CASTEP GA generates a lot of output files; as well as a main GA output .castep there are also input and output files for each population member. The population member seeds are labeled with the generation and population number, for example Si.gen_002_mem_006.cell is the input cell file for the 6 th member of generation 2. You should see input files being generated periodically (a generation at a time). In-between the output file generation geometry optimisations are automatically performed on each population member (here asynchronously 3 at a time). If the Si CASTEP run we started in the last section is still running we can have a look at the main output file. In a new terminal window navigate to ./CASTEP_workshop_GA/1_Si_SW_GA and run tail -f Si.castep This will show us the output of the main GA Si.castep file being generated in real time. The main output file contains a lot of information and can be a bit overwhelming. It gives all the parent structures and the pre and post geometry optimisation child structures as well as information about mutation operations. Once this GA run has completed move on to the next section to analyse our output files.","title":"CASTEP GA Output Files"},{"location":"workshop/10_GA/#analysing-the-ga-output-files","text":"The GA saves the post geometry optimisation structures from all evaluated population members in the file .xyz in standard xyz format. We can view a nice animation of all of the structures the GA explored with jmol by opening this xyz file in jmol with Jmol.jar Si.xyz then going to tools -> animate -> once . In order to analyse the structures created by the GA in more detail we could look at just the enthalpy of the structures, where we may be most interested in the lowest enthalpy structure found. The GA always takes the lowest enthalpy cell into the next generation, so we can look at the last generation to find the lowest enthalpy cell with grep Si.castep -e \"GA: gen # 12\" | tail -n 24 | sort -k10,10g which gives the final generation in order of enthalpy (in eV/ion). However, we gain a lot of information about the phase space with the other cells the GA finds on the way to the minimum enthalpy cell. To explore this a bit more run ./get_data.sh You may need to make this executable by running chmod u+x get_data.sh . This script generates an output file out.put that contains a summary of the data for each population member in 9 columns: Generation number. Parent or child. Member number. Error file detected (T or F). Geometry optimisation converged (T or F). Number of ions in the cell. Enthalpy per ion of converged cell (in eV/ion). Volume of converged cell (in Angstrom/ion). Member filename. We can then plot the population as the enthalpy (per ion) against the cell volume (per ion) by running the python script python plot_results.py This will produce two plots; one is an animation of the population members in each generation, the other is every explored population member over all generations with the lowest enthalpy structure labeled. It will also save these to the current directory. From this representation we can gain information about the phase space of SW Si, where the lower enthalpy structures represent structures on the energy-volume curve for SW Si. There are also structures found by the GA above the energy-volume curve that are likely unstable. We can have a look at the structure of the lowest enthalpy cell (as labeled on your graph) with jmol (or your crystal structure viewing program of choice). If using jmol run Jmol.jar -out.cell where is the seed of the lowest enthalpy population member given on the output graph and the -out.cell postfix gives us the structure post geometry optimisation (it is important to look at this cell rather than the input cell). For example, for me (though your seed may be different than this) this is Jmol.jar Si.gen_006_mem_012-out.cell It can sometimes be difficult to figure out the exact space group of crystals from a visual inspection. So, we can use c2x to find the space group of our lowest enthalpy cell within a tolerance with c2x --int -e=0.1-0.0001 -out.cell which for my lowest enthalpy member is c2x --int -e=0.1-0.0001 Si.gen_006_mem_012-out.cell For me this gives the output Tol=0.001 International symmetry is Fd-3m which is the diamond structure space group we would expect for Si.","title":"Analysing the GA Output Files"},{"location":"workshop/10_GA/#ga-continuation-approx-2-mins-runtime","text":"It is possible you won't find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure (or one close to it, remember the GA is a coarse search) as there is some randomness in a GA run and our population size and number of generations is small. But don't worry, it is possible to restart a GA run from exactly where you left off. Let's do this now (even if you did find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure). To perform a continuation open the Si.param file in your text editor of choice. We then tell CASTEP GA we want to continue from where we left off. We do this by giving the location of the .xyz file that contains all explored structures by uncommenting the following in the Si.param file # continuation = Si.xyz so it reads continuation = Si.xyz Also, we want to run for more generations, so change the value for ga_max_gens from 12 to 18 (to run 6 more generations) i.e. in the Si.param file change the line ga_max_gens = 12 # Max number of generations to run for to ga_max_gens = 18 # Max number of generations to run for Important: Do not change the ga_pop_size as this will cause an error. We can then call CASTEP GA as before with castep_GA Si and it will read in the members from generation 12 of our last run and start generation 13 from these. Running for generations 13 to 16 should take approximately 1-2 minutes. Have a look at the outputs of this run by re-running ./get_data.sh and then plotting with python plot_results.py You may want to have a look at the lowest enthalpy structure with Jmol. You may also want to have a look at some of the other structures that are low on the energy/volume plot (a good way to find their seed names will be from the out.put file).","title":"GA Continuation (Approx. 2 mins runtime)"},{"location":"workshop/10_GA/#sic-stillinger-weber-ga","text":"Now we will look at exploring a more complicated potential energy landscape, to do this we first navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA Luckily CASTEP allows us to add our own parameterisation values for pair potentials. A parameterisation for an SiC SW pair potential has been added to the devel code block of the parameter file SiC.param . This parameterisation leads to a more complex potential energy landscape than we saw with Si. Due to the limitations of this pair potential parameterisation the GA will find different structures than we would find with ab-inito calculations as this is a pair potential energy landscape. However, it will run quickly enough to be usable with the computational and time resources available. As such we will use the GA to explore this unknown potential energy landscape as we did with Si. N.B. Everything we are doing here works just the same with DFT.","title":"SiC Stillinger-Weber GA"},{"location":"workshop/10_GA/#running-the-castep-ga-approx-5-10-mins-runtime","text":"The SiC.param file is very similar to the one used for Si, except the initial population is no longer completely random but instead generated as random high symmetry cells. The cell file contains an equal number of Si and C ions in random positions in a not unreasonably sized cell for this many ions Si and C ions. To run CASTEP GA execute castep_GA SiC and the GA will start, which will take approximately 6-7 minutes to run. You may want to look at the outputs as we did before, or take a quick break!","title":"Running the CASTEP GA (Approx. 5-10 mins runtime)"},{"location":"workshop/10_GA/#analysing-the-ga-output-files_1","text":"The GA outputs for this SiC run can be analysed in the same way as in the case of Si. We can use the same scripts as earlier to create energy volume plots by running ./get_data.sh && python plot_results.py Where this energy volume graph can be analysed as with Si. Make a note of the lowest enthalpy cell for use later. If it looks like would benefit from running a few more generations, we can run a continuation using the same methods as before. Have a look at the cell of the lowest enthalpy structure. It's likely that it seems a bit different to what we would expect in nature. As such, it would be good if we could run a full DFT calculation on some of the cells that have been found by the GA rather than relying on this pair potential parameterisation. However, we are a bit limited in computer power running, with all of the previous runs using only 3 cores. To overcome this hurdle we will exploit machine learning with Gaussian approximation potentials (GAP).","title":"Analysing the GA Output Files"},{"location":"workshop/10_GA/#gaussain-approximation-potential-accelerated-geometry-optimisation","text":"A common approach to machine learning is to train a model on some dataset of known solutions to a problem. This presents an issue with the application of machine learning to crystal structure optimisation for materials discovery as by definition the parameter landscape is not explored. One approach to this in CASTEP is to use a number of initial geometry optimisation or molecular dynamics steps ran with ab-initio methods as the initial training data. Subsequent geometry optimisation steps are then ran with a machine learned potential using Gaussian approximation potentials (GAP). Ions move over the course of geometry optimisations (or molecular dynamics calculations), therefore the landscape may change such that the potential needs some extra ab-inito data to train on. As such, CASTEP adaptively chooses geometry optimisation steps over the course of the calculation to run with DFT which are then used to re-train the GAP potential. More information about this method is available in the paper by Stenczel et al 1 . In general, less and less DFT geometry optimisation or MD steps will be required as the calculation continues and samples the parameter space more thoroughly (again see 1 ). Note: All methods that are outlined here for the acceleration of a geometry optimisation can also be directly applied to molecular dynamics calculations. In practice, as the cost savings are generally greater the more steps are in the calculation, the cost savings of GAP are greatest for long running molecular dynamics calculations.","title":"Gaussain Approximation Potential Accelerated Geometry Optimisation"},{"location":"workshop/10_GA/#using-gap-to-accelerate-a-geometry-optimisation","text":"We now navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA/DFT_polish_GAP which contains 3 files. The first is the SiC_GA_best.cell , we should open this and replace the lattice and positions blocks with those from the best cell from our previous SiC run (that we made a note of earlier, if that note is lost open the image ../all_gens.png ). For me the best cell is ../SiC.gen_009_mem_006-out.cell , but for you this could be different. The cell file we also specifies the QC5 pseudopotential library, a kpoint grid spacing and that the geometry optimisation will be fixed cell. The SiC_GA_best.param file contains standard CASTEP parameters for a Damped Molecular Dynamics (DMD) geometry optimisation. Along with this is the devel code block required to call hybrid-md (which then calls gap_fit ) to perform the GAP fitting. Finally, there is an extra input file required for a GAP run, the .hybrid-md-input.yaml file. This contains specific inputs relating to the GAP fitting. Here we specify a mandatory 10 initial DFT steps for the initial training dataset. After this we specify a minimum of 10 steps with the machine learned potential before re-fitting, whilst allowing CASTEP to vary the number of steps between re-fittings. We also allow GAP to also parellise over 3 cores. N.B. The GAP run we carry out here has rather coarse convergence parameters, designed to allow for a fast run on a desktop in this workshop.","title":"Using GAP to Accelerate a Geometry Optimisation"},{"location":"workshop/10_GA/#running-castep-with-gap-approx-10-15-mins-runtime","text":"To run CASTEP to perform the damped MD geometry optimisation with the aid of GAP call mpirun -n 3 castep.mpi SiC_GA_best Whilst this is running (which will take 10 to 15 minutes) there will be information printed to the terminal window each DMD step. This states if the step is an initial (DFT) step, if the step is using the machine learned potential or if it is being ran with DFT in order to perform a re-fit. It may be illustrative to open a new terminal window, navigate to the working directory and tail the .castep output file with tail -f SiC_GA_best.castep in order to see the geometry optimisation running. Notice the steps using the machine learned potential are essentially free when compared with the DFT steps that require SCF calculations.","title":"Running CASTEP with GAP (Approx. 10-15 mins runtime)"},{"location":"workshop/10_GA/#looking-at-the-gap-geometry-optimisation-results","text":"First, let us consider the cost of this geometry optimisation. My calculation ran for a total of 152 DMD steps, though your mileage may vary. Using the following command we can see on which DMD steps CASTEP decided to perform DFT calculations grep SiC_GA_best.castep -e \"Decided to perform\" We can also see how many of the DMD steps utilised DFT grep SiC_GA_best.castep -e \"Decided to perform\" | wc -l In my case this showed that 22 of the total DMD steps were using DFT, therefore approximately 85% of the DMD steps were carried out with the machine learned potential. Though there is a cost associated with these steps and with the re-fitting of the GAP potential, it is clear this represents a large cost saving. Very roughly (based on average time for one SCF cycle in my DMD run) without GAP this run would have taken approximately 4 times as long for no extra information. We can also visualize (using jmol or similar) both the output structure from the DMD run ( SiC_GA_best-out.cell ) and the pre-geometry optimisation structure ( SiC_GA_best.cell ). It is likely these are quite different. This is due to the difference (and lower quality!) of the SW parameterisation compared with any DFT approach.","title":"Looking at the GAP Geometry Optimisation Results"},{"location":"workshop/10_GA/#optional-extension-running-ga-with-other-systems","text":"You may also want to try the CASTEP GA with another system or pair potential parameterisation (it is likely not possible to run a full DFT run of the GA in the timescale of this practical). If this is the case you can use the blank input file in ./CASTEP_workshop_GA/2.5_GA_blank","title":"(Optional Extension) Running GA with Other Systems"},{"location":"workshop/10_GA/#optional-extension-running-gap-with-other-systems","text":"If you are interested in applying GAP to your calculations you may want to try GAP with a material of interest to you. If you would like to try with a cell and parameters of your choice there are blank input files in ./CASTEP_workshop_GA/2.5_GAP_blank","title":"(Optional Extension) Running GAP with Other Systems"},{"location":"workshop/10_GA/#footnotes","text":"1 Tam\u00e1s K. Stenczel, Zakariya El-Machachi, Guoda Liepuoniute, Joe D. Morrow, Albert P. Bart\u00f3k, Matt I. J. Probert, G\u00e1bor Cs\u00e1nyi, Volker L. Deringer; Machine-learned acceleration for molecular dynamics in CASTEP. J. Chem. Phys. 28 July 2023; 159 (4): 044803. https://doi.org/10.1063/5.0155621","title":"Footnotes"},{"location":"workshop/LST_QST/","text":"Transition State Search Tutorial How Transition State Searches Work There have been many suggestions for ways to identify transition states over the years, of which the two most popular are Linear Synchronous Transit / Quadratic Synchronous Transit (LST/QST) and Nudged Elastic Band (NEB) . These two techniques belong to the family of close-ended transition state searches - that is they require both an initial and final structure (reactant and product) and then they attempt to find the lowest barrier between them, the transition state. Open ended searches also exist in the literature, but they find the lowest barrier away from a reactant, which may not be useful for modelling a complex multi-step process. Finally, the gold standard technique (which can be performed in practice but is prohibitively expensive to use for more than verification of transition states) is mode following; the transition state is a stationary state at a saddle point, and accordingly it should have only one imaginary vibrational (phonon) mode. Once a transition structure is predicted, it is possible to perform a phonon calculation in CASTEP to verify this (see phonon tutorials). LST/QST LST/QST is probably the most conceptually simple of the transition state search techniques, and is in itself an extension to the simple LST technique. In LST, a linear interpolation between reactant and product states is made (with a variable weighting), and then the total energy of the system is evaluated at various points (choices of weighting) along this linear interpolation. A bisection search is then performed to find the local maximum along this path. Since LST performs a linear interpolation it is only guaranteed to find the energy maximum on that line - there is no guarantee that this sill in fact be the saddle point. Accordingly in QST , an energy minimisation is performed in directions orthogonal to the LST search direction. This then tends towards the saddle point, improving the estimate of the transition state. It is, however, possible that the QST optimisation will fall off the saddle point, which can make it a tricky process to converge, or cause the saddle point itself to be missed. Example: LST/QST Linear Synchronous Transit/ Quadratic Synchronous Transit (commonly known as LST/QST ) is a quick and reasonably accurate method to find a transition state. In this example, you will determine the transition barrier for a simple (and somewhat uninteresting) reaction, H + H2 -> H2 + H The files for this tutorial may be found at LST_Tutorial Geometry Optimisation Good transition state searches are based upon good structural relaxations of the initial and final states. The first step is therefore to perform geometry optimisations for your reactant H_Initial and product H_Final . Note that ionic constraints have been used in these to prevent translations of 2 of the ions and accelerate the geometry optimisation. You may wish to investigate what happens when these constraints are relaxed. For more complex constrained systems, it is often worthwhile changing the default geometry optimiser from Geom_Method: LBFGS to Geom_Method: TPSD , which is not disrupted by the sharp discontinuities the constraints can induce to the potential energy landscape. Once you have checked your end points are relaxed (ask if you are unsure how to confirm this!), you will need to create a new block: %block positions_frac_product . . . %endblock positions_frac_product where you need to place the atomic positions from H_Final-out.cell . If doing this manually, you may find the following bash commands useful cp reactant-out.cell TS.cell cat product-out.cell >> TS.cell This will append the contents of a hypothetical product-out.cell to the end of the reactant-out.cell in a new file TS.cell . You will then need to rename the second positions_frac block and delete any repeated entries. FOR THIS TUTORIAL: An Example TS.cell and TS.param file have been provided! Run the TS Search job Using castepsub submit the TS job. Results Interpretation To watch the path of the transition search, you can drag the .ts file into Jmol and watch the animations in the same way outlined in the geometry optimisation tutorial. Try and find the LST Transition State in the .castep file. Is this what you would expect? grep -A 7 \"LST Maximum Found\" TS.castep * Try and find the QST Transition state in the .castep file. grep -A 7 \"Transition State Found\" TS.castep * Can you explain why the QST result seems odd? What about the initial geometry optimisation could be improved to give a better result? Extensions Think about XC-functional choice; LDA overbinds - how does this affect the transition barrier and initial structures? What happens when the transition is between non-adjacent minima in the potential energy landscape? (This would require a more complex example than the tutorial) What about longer distances? When do we need Van der Waal's interactions (DFT+D) ? What effect did the constraints have? Can you improve them?","title":"Transition State Search Tutorial"},{"location":"workshop/LST_QST/#transition-state-search-tutorial","text":"","title":"Transition State Search Tutorial"},{"location":"workshop/LST_QST/#how-transition-state-searches-work","text":"There have been many suggestions for ways to identify transition states over the years, of which the two most popular are Linear Synchronous Transit / Quadratic Synchronous Transit (LST/QST) and Nudged Elastic Band (NEB) . These two techniques belong to the family of close-ended transition state searches - that is they require both an initial and final structure (reactant and product) and then they attempt to find the lowest barrier between them, the transition state. Open ended searches also exist in the literature, but they find the lowest barrier away from a reactant, which may not be useful for modelling a complex multi-step process. Finally, the gold standard technique (which can be performed in practice but is prohibitively expensive to use for more than verification of transition states) is mode following; the transition state is a stationary state at a saddle point, and accordingly it should have only one imaginary vibrational (phonon) mode. Once a transition structure is predicted, it is possible to perform a phonon calculation in CASTEP to verify this (see phonon tutorials).","title":"How Transition State Searches Work"},{"location":"workshop/LST_QST/#lstqst","text":"LST/QST is probably the most conceptually simple of the transition state search techniques, and is in itself an extension to the simple LST technique. In LST, a linear interpolation between reactant and product states is made (with a variable weighting), and then the total energy of the system is evaluated at various points (choices of weighting) along this linear interpolation. A bisection search is then performed to find the local maximum along this path. Since LST performs a linear interpolation it is only guaranteed to find the energy maximum on that line - there is no guarantee that this sill in fact be the saddle point. Accordingly in QST , an energy minimisation is performed in directions orthogonal to the LST search direction. This then tends towards the saddle point, improving the estimate of the transition state. It is, however, possible that the QST optimisation will fall off the saddle point, which can make it a tricky process to converge, or cause the saddle point itself to be missed.","title":"LST/QST"},{"location":"workshop/LST_QST/#example-lstqst","text":"Linear Synchronous Transit/ Quadratic Synchronous Transit (commonly known as LST/QST ) is a quick and reasonably accurate method to find a transition state. In this example, you will determine the transition barrier for a simple (and somewhat uninteresting) reaction, H + H2 -> H2 + H The files for this tutorial may be found at LST_Tutorial Geometry Optimisation Good transition state searches are based upon good structural relaxations of the initial and final states. The first step is therefore to perform geometry optimisations for your reactant H_Initial and product H_Final . Note that ionic constraints have been used in these to prevent translations of 2 of the ions and accelerate the geometry optimisation. You may wish to investigate what happens when these constraints are relaxed. For more complex constrained systems, it is often worthwhile changing the default geometry optimiser from Geom_Method: LBFGS to Geom_Method: TPSD , which is not disrupted by the sharp discontinuities the constraints can induce to the potential energy landscape. Once you have checked your end points are relaxed (ask if you are unsure how to confirm this!), you will need to create a new block: %block positions_frac_product . . . %endblock positions_frac_product where you need to place the atomic positions from H_Final-out.cell . If doing this manually, you may find the following bash commands useful cp reactant-out.cell TS.cell cat product-out.cell >> TS.cell This will append the contents of a hypothetical product-out.cell to the end of the reactant-out.cell in a new file TS.cell . You will then need to rename the second positions_frac block and delete any repeated entries. FOR THIS TUTORIAL: An Example TS.cell and TS.param file have been provided! Run the TS Search job Using castepsub submit the TS job. Results Interpretation To watch the path of the transition search, you can drag the .ts file into Jmol and watch the animations in the same way outlined in the geometry optimisation tutorial. Try and find the LST Transition State in the .castep file. Is this what you would expect? grep -A 7 \"LST Maximum Found\" TS.castep * Try and find the QST Transition state in the .castep file. grep -A 7 \"Transition State Found\" TS.castep * Can you explain why the QST result seems odd? What about the initial geometry optimisation could be improved to give a better result?","title":"Example: LST/QST"},{"location":"workshop/LST_QST/#extensions","text":"Think about XC-functional choice; LDA overbinds - how does this affect the transition barrier and initial structures? What happens when the transition is between non-adjacent minima in the potential energy landscape? (This would require a more complex example than the tutorial) What about longer distances? When do we need Van der Waal's interactions (DFT+D) ? What effect did the constraints have? Can you improve them?","title":"Extensions"},{"location":"workshop/optados/6a_dos/","text":"Density of States Outline This is a simple example of using optados for calculating electronic density of states of crystalline silicon in a 2 atom cell. It shows how optados's adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. The tarball for the tutorial files for all of the optados tutorials are here: optados-examples.tgz Input Files: examples/Si2_DOS/Si2.cell - The castep cell file containing information about the simulation cell. examples/Si2_DOS/Si2.param - The castep param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_DOS/Si2.odi - The optados input file, containing the parameters necessary to run optados. Instructions: Perform a castep calculation on the bulk silicon using the Si2.cell and Si2.param input files. This should take a couple of seconds to run. Examine the optados input file - Si2.odi Perform an optados calculation. $ optados.mpi Si2 This generates 3 files: Si2.odo -- optados general output file. Si2.adaptive.dat -- The adaptive broadened DOS raw output data. Si2.adaptive.agr -- The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Examine the Si2.odo file. optados has performed a Density of States calculation. +--------------- Fermi Energy Analysis ------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99961 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99961 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 5.4109 eV <- EfA | +--------------------------------------------------------------+ It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. +----------------------- Electronic Data ---------------------+ | Number of Bands : 23 | | Grid size : 10 x 10 x 10 | | Number of K-points : 110 | | Spin-Polarised Calculation : True | | Number of up-spin electrons : 4.00 | | Number of down-spin electrons : 4.00 | +-------------------------------------------------------------+ Since we had efermi : optados , optados sets the internal value of the Fermi level to the one it has derived from the DOS. This is important for subsequent calculations. Other valid options are file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues; insulator , where optados uses a value calculated from assuming the system is non-metallic; or a value set by the user. optados now performs some analysis of the DOS at the Fermi level, +-------------- DOS at Fermi Energy Analysis ----------------+ | Fermi energy used : 5.4109 eV | | From Adaptive broadening | | Spin Component:1 DOS at Fermi Energy:0.0011 eln/cell <-DEA | | Spin Component:2 DOS at Fermi Energy:0.0011 eln/cell<- DEA | +------------------------------------------------------------+ From this we may assume that there is a band gap. Importantly, then optados calculates the band energy from the DOS is has calculated. +------------------- Band Energy Analysis -------------------+ | Band energy (Adaptive broadening) : 1.3609 eV <- BEA | | Band energy (From CASTEP) : 1.3622 eV <- BEC | +------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Finally optados shifts the Fermi level to 0 eV, for the output files. The DOS is written to Si2.adaptive.dat . This contains 5 columns as described in the header of the file: ################################################################ # # O p t a D O S o u t p u t f i l e # # Density of States using adaptive broadening # Generated on 12 Feb 2012 at 16:50:37 # Column Data # 1 Energy (eV) # 2 Up-spin DOS (electrons per eV) # 3 Down-spin DOS (electrons per eV) # 4 Up-spin Integrated DOS (electrons) # 5 Down-spin Integrated DOS (electrons) # ################################################################ This file can be plotted by your favourite graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace . $ xmgrace Si2.adaptive.agr 1. We now try again with a better sampling of the DOS, by setting DOS_SPACING : 0.001 and also analyse the band gap, by setting COMPUTE_BAND_GAP : true . You can set IPRINT : 2 to see a progress report in Si2.odo . In Si2.odo we now have a new section analysing the band gap in various ways. +----------------------------- Bandgap Analysis ---------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6676272107 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000| | and CBM kpoint: -0.45000 -0.05000 -0.45000| | ==> Indirect Gap | +--------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5542517447 eV <- OBg | | Spin : 2 : 2.5542463024 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +--------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8121372691 eV <- ABg | | Spin : 2 : 3.8121342659 eV <- ABg | | Weighted Average : 3.8121357675 eV <- wAB | +--------------------------------------------------------------+ optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Increasing the number of integration points has improved the band energy of the adaptive smearing: | Band energy (Adaptive broadening) : 1.3623 eV <- BEA | We will now compare the DOS with the adaptive broadening scheme with simple Gaussian smearing. In the optados input file ( Si2.odi ) change the value of BROADENING to fixed . Plotting the fixed broadened DOS over the adaptive we see the advantages of the adaptive broadening. xmgrace Si2.adaptive.agr Si2.fixed.agr","title":"7a DOS"},{"location":"workshop/optados/6a_dos/#density-of-states","text":"","title":"Density of States"},{"location":"workshop/optados/6a_dos/#outline","text":"This is a simple example of using optados for calculating electronic density of states of crystalline silicon in a 2 atom cell. It shows how optados's adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. The tarball for the tutorial files for all of the optados tutorials are here: optados-examples.tgz","title":"Outline"},{"location":"workshop/optados/6a_dos/#input-files","text":"examples/Si2_DOS/Si2.cell - The castep cell file containing information about the simulation cell. examples/Si2_DOS/Si2.param - The castep param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_DOS/Si2.odi - The optados input file, containing the parameters necessary to run optados.","title":"Input Files:"},{"location":"workshop/optados/6a_dos/#instructions","text":"Perform a castep calculation on the bulk silicon using the Si2.cell and Si2.param input files. This should take a couple of seconds to run. Examine the optados input file - Si2.odi Perform an optados calculation. $ optados.mpi Si2 This generates 3 files: Si2.odo -- optados general output file. Si2.adaptive.dat -- The adaptive broadened DOS raw output data. Si2.adaptive.agr -- The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Examine the Si2.odo file. optados has performed a Density of States calculation. +--------------- Fermi Energy Analysis ------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99961 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99961 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 5.4109 eV <- EfA | +--------------------------------------------------------------+ It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. +----------------------- Electronic Data ---------------------+ | Number of Bands : 23 | | Grid size : 10 x 10 x 10 | | Number of K-points : 110 | | Spin-Polarised Calculation : True | | Number of up-spin electrons : 4.00 | | Number of down-spin electrons : 4.00 | +-------------------------------------------------------------+ Since we had efermi : optados , optados sets the internal value of the Fermi level to the one it has derived from the DOS. This is important for subsequent calculations. Other valid options are file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues; insulator , where optados uses a value calculated from assuming the system is non-metallic; or a value set by the user. optados now performs some analysis of the DOS at the Fermi level, +-------------- DOS at Fermi Energy Analysis ----------------+ | Fermi energy used : 5.4109 eV | | From Adaptive broadening | | Spin Component:1 DOS at Fermi Energy:0.0011 eln/cell <-DEA | | Spin Component:2 DOS at Fermi Energy:0.0011 eln/cell<- DEA | +------------------------------------------------------------+ From this we may assume that there is a band gap. Importantly, then optados calculates the band energy from the DOS is has calculated. +------------------- Band Energy Analysis -------------------+ | Band energy (Adaptive broadening) : 1.3609 eV <- BEA | | Band energy (From CASTEP) : 1.3622 eV <- BEC | +------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Finally optados shifts the Fermi level to 0 eV, for the output files. The DOS is written to Si2.adaptive.dat . This contains 5 columns as described in the header of the file: ################################################################ # # O p t a D O S o u t p u t f i l e # # Density of States using adaptive broadening # Generated on 12 Feb 2012 at 16:50:37 # Column Data # 1 Energy (eV) # 2 Up-spin DOS (electrons per eV) # 3 Down-spin DOS (electrons per eV) # 4 Up-spin Integrated DOS (electrons) # 5 Down-spin Integrated DOS (electrons) # ################################################################ This file can be plotted by your favourite graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace . $ xmgrace Si2.adaptive.agr 1. We now try again with a better sampling of the DOS, by setting DOS_SPACING : 0.001 and also analyse the band gap, by setting COMPUTE_BAND_GAP : true . You can set IPRINT : 2 to see a progress report in Si2.odo . In Si2.odo we now have a new section analysing the band gap in various ways. +----------------------------- Bandgap Analysis ---------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6676272107 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000| | and CBM kpoint: -0.45000 -0.05000 -0.45000| | ==> Indirect Gap | +--------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5542517447 eV <- OBg | | Spin : 2 : 2.5542463024 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +--------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8121372691 eV <- ABg | | Spin : 2 : 3.8121342659 eV <- ABg | | Weighted Average : 3.8121357675 eV <- wAB | +--------------------------------------------------------------+ optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Increasing the number of integration points has improved the band energy of the adaptive smearing: | Band energy (Adaptive broadening) : 1.3623 eV <- BEA | We will now compare the DOS with the adaptive broadening scheme with simple Gaussian smearing. In the optados input file ( Si2.odi ) change the value of BROADENING to fixed . Plotting the fixed broadened DOS over the adaptive we see the advantages of the adaptive broadening. xmgrace Si2.adaptive.agr Si2.fixed.agr","title":"Instructions:"},{"location":"workshop/optados/6b_pdos/","text":"Projected Density of States We assume the reader is familiar with the previous section on Density of States calculations and is now familiar with running optados . Outline This is a simple example of using optados for calculating electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. Input Files examples/Si2_PDOS/Si2.cell - The castep .cell file containing information about the simulation cell. examples/Si2_PDOS/Si2.param - The castep .param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_PDOS/Si2.odi - The optados input file, containing the parameters necessary to run optados. Instructions: Examine the optados input file noting TASK : pdos . We choose to decompose the DOS into angular momentum channels PDOS : angular and as in the previous example we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep. Execute optados. The output can be found in Si2.pdos.dat . ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ The header shows that there are four projectors described below. The first containing the s-channels of both silicon atoms, the second the p-channels etc. The output is easily plotted using xmgrace . Setting DOS_SPACING : 0.001 gives a high quality plot, as shown in the figure below. Density of States of Silicon generated by adaptive broadening projected onto LCAO momentum states Other projections to try are: PDOS : Si1;Si2(s) -- Output the PDOS on Si atom 1 and the PDOS on the s-channel of Si atom 2. (Resulting in two projectors) PDOS : sum:Si1-2(s) -- Output the sum of the s-channels on the two Si atoms. (Resulting in one projector) PDOS : Si1(p) -- Output the p-channel on Si atom 1. (Resulting in one projector)","title":"7b Projected DOS"},{"location":"workshop/optados/6b_pdos/#projected-density-of-states","text":"We assume the reader is familiar with the previous section on Density of States calculations and is now familiar with running optados .","title":"Projected Density of States"},{"location":"workshop/optados/6b_pdos/#outline","text":"This is a simple example of using optados for calculating electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states.","title":"Outline"},{"location":"workshop/optados/6b_pdos/#input-files","text":"examples/Si2_PDOS/Si2.cell - The castep .cell file containing information about the simulation cell. examples/Si2_PDOS/Si2.param - The castep .param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_PDOS/Si2.odi - The optados input file, containing the parameters necessary to run optados.","title":"Input Files"},{"location":"workshop/optados/6b_pdos/#instructions","text":"Examine the optados input file noting TASK : pdos . We choose to decompose the DOS into angular momentum channels PDOS : angular and as in the previous example we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep. Execute optados. The output can be found in Si2.pdos.dat . ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ The header shows that there are four projectors described below. The first containing the s-channels of both silicon atoms, the second the p-channels etc. The output is easily plotted using xmgrace . Setting DOS_SPACING : 0.001 gives a high quality plot, as shown in the figure below. Density of States of Silicon generated by adaptive broadening projected onto LCAO momentum states Other projections to try are: PDOS : Si1;Si2(s) -- Output the PDOS on Si atom 1 and the PDOS on the s-channel of Si atom 2. (Resulting in two projectors) PDOS : sum:Si1-2(s) -- Output the sum of the s-channels on the two Si atoms. (Resulting in one projector) PDOS : Si1(p) -- Output the p-channel on Si atom 1. (Resulting in one projector)","title":"Instructions:"},{"location":"workshop/optados/6c_coreloss/","text":"Calculation of core-loss spectra for hBN We begin by running a CASTEP calculation using the files provided. Note that we specify a pseudopotential file for one B atom and both N atom, and use an on-the-fly pseudopotential for the other B atom. This looks a bit weird! It is simply a way to only compute the EELS for one atomic site (core-loss spectra can only be computed for atoms described by on-the-fly potentials). An h-BN cell and param file are provided. Execute optados using the optados input file provided and the file hBN_core_edge.dat will be created. The file contains two columns, the first is the energy and the second is the spectrum. This file contains the following edges: B 1 K1 B:1 OptaDOS has also written a grace file $ xmgrace hBN_core_edge.agr This spectrum has lots of fine detail. To compare with experiment we can include lifetime and instrument broadening effects. First let's add some Gaussian broadening to simulate instrument effects. Add the following the odi file and re-run. CORE_LAI_BROADENING : true LAI_GAUSSIAN_WIDTH : 1.0 The file hBN_core_edge.dat now has three columns. The third column is the broadened spectrum. To compare the broadened and un-broadened spectra xmgrace hBN_core_edge_broad.agr hBN_core_edge.agr Now add some lifetime broadening (look up the meaning of the keywords in the optados user guide) LAI_LORENTZIAN_WIDTH : 0.5 LAI_LORENTZIAN_SCALE : 0.1 Now try running CASTEP and OptaDOS to produce a N K-edge Including a core-hole First we will include a core-hole on atom B:1. To do this we add a modified pseudopotential string into the hBN.cell file B:1 2|1.2|12|14|16|20:21{1s1.00}(qc=8) The core-hole is created by removing a 1s electron from the electronic configuration used in the generation of the pseudopotential. Information about the pseudopotential is included at the top of the hBN.castep file ============================================================ | Pseudopotential Report - Date of generation 17-08-2018 | ------------------------------------------------------------ | Element: B Ionic charge: 3.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.347 | | 2p 1.000 -0.133 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.347 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.133 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ The line | \"2|1.2|12|14|16|20:21(qc=8)\" | specifies the parameters used to create the OFT B pseudopotential. We use this as a starting point and remove one of the core 1s electrons to create the core-hole pseudopotential by including {1s1.00} . To maintain the neutrality of the cell, we include CHARGE : +1 in the hBN.param file. Run the calculation. Compare the K-edge from the core-hole calculation with the previous non-core-hole calculation. The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. Create a 2x2x1 supercell (talk to one of the tutors if you\u2019re unsure about how to do this) and carry out another core-loss B K-edge simulation. Compare the spectra to that from the primitive cell. Construct larger and larger unit cells until the spectrum stops changing with increasing separation between the periodic images. Other things to try include: Include the core-hole on the N atom rather than the B Compare your simulated spectra to experimental data (the EELS database is a good place to find experimental data) Compare to spectra from cubic BN Calculating spectra from graphite (graphene) and diamond","title":"7c Coreloss"},{"location":"workshop/optados/6c_coreloss/#calculation-of-core-loss-spectra-for-hbn","text":"We begin by running a CASTEP calculation using the files provided. Note that we specify a pseudopotential file for one B atom and both N atom, and use an on-the-fly pseudopotential for the other B atom. This looks a bit weird! It is simply a way to only compute the EELS for one atomic site (core-loss spectra can only be computed for atoms described by on-the-fly potentials). An h-BN cell and param file are provided. Execute optados using the optados input file provided and the file hBN_core_edge.dat will be created. The file contains two columns, the first is the energy and the second is the spectrum. This file contains the following edges: B 1 K1 B:1 OptaDOS has also written a grace file $ xmgrace hBN_core_edge.agr This spectrum has lots of fine detail. To compare with experiment we can include lifetime and instrument broadening effects. First let's add some Gaussian broadening to simulate instrument effects. Add the following the odi file and re-run. CORE_LAI_BROADENING : true LAI_GAUSSIAN_WIDTH : 1.0 The file hBN_core_edge.dat now has three columns. The third column is the broadened spectrum. To compare the broadened and un-broadened spectra xmgrace hBN_core_edge_broad.agr hBN_core_edge.agr Now add some lifetime broadening (look up the meaning of the keywords in the optados user guide) LAI_LORENTZIAN_WIDTH : 0.5 LAI_LORENTZIAN_SCALE : 0.1 Now try running CASTEP and OptaDOS to produce a N K-edge","title":"Calculation of core-loss spectra for hBN"},{"location":"workshop/optados/6c_coreloss/#including-a-core-hole","text":"First we will include a core-hole on atom B:1. To do this we add a modified pseudopotential string into the hBN.cell file B:1 2|1.2|12|14|16|20:21{1s1.00}(qc=8) The core-hole is created by removing a 1s electron from the electronic configuration used in the generation of the pseudopotential. Information about the pseudopotential is included at the top of the hBN.castep file ============================================================ | Pseudopotential Report - Date of generation 17-08-2018 | ------------------------------------------------------------ | Element: B Ionic charge: 3.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.347 | | 2p 1.000 -0.133 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.347 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.133 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ The line | \"2|1.2|12|14|16|20:21(qc=8)\" | specifies the parameters used to create the OFT B pseudopotential. We use this as a starting point and remove one of the core 1s electrons to create the core-hole pseudopotential by including {1s1.00} . To maintain the neutrality of the cell, we include CHARGE : +1 in the hBN.param file. Run the calculation. Compare the K-edge from the core-hole calculation with the previous non-core-hole calculation. The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. Create a 2x2x1 supercell (talk to one of the tutors if you\u2019re unsure about how to do this) and carry out another core-loss B K-edge simulation. Compare the spectra to that from the primitive cell. Construct larger and larger unit cells until the spectrum stops changing with increasing separation between the periodic images. Other things to try include: Include the core-hole on the N atom rather than the B Compare your simulated spectra to experimental data (the EELS database is a good place to find experimental data) Compare to spectra from cubic BN Calculating spectra from graphite (graphene) and diamond","title":"Including a core-hole"},{"location":"workshop/optados/6d_lowloss/","text":"JDOS and OPTICS Joint DOS See examples/Si2_JDOS . This is a simple example of using optados for calculating joint electronic density of states. We choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep, and so EFERMI: OPTADOS is included in the Si2.odi file. Execute castep and optados using the example files. The JDOS is written to Si2.jadaptive.dat . A file suitable for plotting using xmgrace is written to Si2.jadaptive.agr . Check the effect of changing the sampling by increasing and decreasing the value of JDOS_SPACING in the Si2.odi file. Optics Two sets of example files are provided for calculations of optical properties. For each example, the .castep files containing all the cell and simulation parameters are included, along with an optados input file. We assume that the reader is familiar with the previous sections on DOS and JDOS. Silicon See examples/Si2_OPTICS/ . This is a simple example of using optados to calculate the optical properties of crystalline silicon, which is an insulator. Instructions: Execute optados to calculate the optical properties. Several .dat files are produced: Si2_OPTICS_absorption.dat : This file contains the absorption coefficient (second column) as function of energy (first column). Si2_OPTICS_conductivity.dat : This file contains the conductivity outputted in SI units (Siemens per metre). The columns are the energy, real part and imaginary part of the conductivity respectively. Si2_OPTICS_epsilon.dat : This file contains the dielectric function. The columns are the energy and real and imaginary parts of the dielectric function respectively. The file header also includes the result of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') . N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Si2_OPTICS_loss_fn.dat : This file contains the loss function (second column) as a function of energy (first column). The header of the file shows the results of the two sum rules associated with the loss function \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} Si2_OPTICS_reflection.dat : This file contains the reflection coefficient (second column) as a function of energy (first column). Si2_OPTICS_refractive_index.dat : This file contains the refractive index. The columns are the energy and real and imaginary parts of the refractive index respectively. Corresponding .agr files are also generated which can be plotted easily using xmgrace. Change parameters JDOS_SPACING and JDOS_MAX and check the effect on the optical properties. Note: all of the other optical properties are derived from the dielectric function. The optados input file has been set up to calculate the optical properties in the polycrystalline geometry ( optics_geom = polycrystalline ). It is possible to calculate either polarised or unpolarised geometries, or to calculate the full dielectric tensor. To calculate the full dielectric tensor set optics_geom = tensor . This time only the file Si2_OPTICS_epsilon.dat is generated. The format of this file is the same as before (the columns are the energy and the real and imaginary parts of the dielectric function respectively), but this time the six different components of the tensor are listed sequentially in the order \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{yy} \\epsilon_{yy} , \\epsilon_{zz} \\epsilon_{zz} , \\epsilon_{xy} \\epsilon_{xy} , \\epsilon_{xz} \\epsilon_{xz} and \\epsilon_{yz} \\epsilon_{yz} . Additional broadening can be included in the calculation of the loss function. This is done by including the keyword optics_lossfn_broadening in the optados input file. If you include this keyword and re-run optados, you will find that the file Si2_OPTICS_loss_fn.dat now has three columns. These are the energy, unbroadened spectrum and broadened spectrum respectively. Aluminium Aluminium is a metal so we need to include both the interband and intraband contributions to the dielectric function. To include the intraband contribution optics_intraband = true must be included in the optados input file. When you run optados, the same files are generated as when only the interband term is included. The Al_OPTICS_epsilon.dat file has the same format as before, but it now contains sequentially the interband contribution, the intraband contribution and the total dielectric function. The file Al_OPTICS_epsilon.agr only contains the interband term. In the same way, Al_OPTICS_loss_fn.dat contains the interband contribution, intraband contribution and total loss function. All other optical properties are calculated from the total dielectric function and the format of the output files remains the same. In the case where the dielectric tensor is calculated and the intraband term is included, only the Al_OPTICS_epsilon.dat file is generated. As before it contains each component, but this time it lists sequentially the interband contribution, intraband contribution and total dielectric function for each component. This time, if additional broadening for the loss function is included by using the key word optics_lossfn_broadening , AL_OPTICS_loss_fn.dat will contains four sequential data sets. These are the interband contribution, the intraband contribution, the total loss function without the additional broadening and the broadened total loss function.","title":"7d Lowloss"},{"location":"workshop/optados/6d_lowloss/#jdos-and-optics","text":"","title":"JDOS and OPTICS"},{"location":"workshop/optados/6d_lowloss/#joint-dos","text":"See examples/Si2_JDOS . This is a simple example of using optados for calculating joint electronic density of states. We choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep, and so EFERMI: OPTADOS is included in the Si2.odi file. Execute castep and optados using the example files. The JDOS is written to Si2.jadaptive.dat . A file suitable for plotting using xmgrace is written to Si2.jadaptive.agr . Check the effect of changing the sampling by increasing and decreasing the value of JDOS_SPACING in the Si2.odi file.","title":"Joint DOS"},{"location":"workshop/optados/6d_lowloss/#optics","text":"Two sets of example files are provided for calculations of optical properties. For each example, the .castep files containing all the cell and simulation parameters are included, along with an optados input file. We assume that the reader is familiar with the previous sections on DOS and JDOS.","title":"Optics"},{"location":"workshop/optados/6d_lowloss/#silicon","text":"See examples/Si2_OPTICS/ . This is a simple example of using optados to calculate the optical properties of crystalline silicon, which is an insulator. Instructions: Execute optados to calculate the optical properties. Several .dat files are produced: Si2_OPTICS_absorption.dat : This file contains the absorption coefficient (second column) as function of energy (first column). Si2_OPTICS_conductivity.dat : This file contains the conductivity outputted in SI units (Siemens per metre). The columns are the energy, real part and imaginary part of the conductivity respectively. Si2_OPTICS_epsilon.dat : This file contains the dielectric function. The columns are the energy and real and imaginary parts of the dielectric function respectively. The file header also includes the result of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') . N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Si2_OPTICS_loss_fn.dat : This file contains the loss function (second column) as a function of energy (first column). The header of the file shows the results of the two sum rules associated with the loss function \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} Si2_OPTICS_reflection.dat : This file contains the reflection coefficient (second column) as a function of energy (first column). Si2_OPTICS_refractive_index.dat : This file contains the refractive index. The columns are the energy and real and imaginary parts of the refractive index respectively. Corresponding .agr files are also generated which can be plotted easily using xmgrace. Change parameters JDOS_SPACING and JDOS_MAX and check the effect on the optical properties. Note: all of the other optical properties are derived from the dielectric function. The optados input file has been set up to calculate the optical properties in the polycrystalline geometry ( optics_geom = polycrystalline ). It is possible to calculate either polarised or unpolarised geometries, or to calculate the full dielectric tensor. To calculate the full dielectric tensor set optics_geom = tensor . This time only the file Si2_OPTICS_epsilon.dat is generated. The format of this file is the same as before (the columns are the energy and the real and imaginary parts of the dielectric function respectively), but this time the six different components of the tensor are listed sequentially in the order \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{yy} \\epsilon_{yy} , \\epsilon_{zz} \\epsilon_{zz} , \\epsilon_{xy} \\epsilon_{xy} , \\epsilon_{xz} \\epsilon_{xz} and \\epsilon_{yz} \\epsilon_{yz} . Additional broadening can be included in the calculation of the loss function. This is done by including the keyword optics_lossfn_broadening in the optados input file. If you include this keyword and re-run optados, you will find that the file Si2_OPTICS_loss_fn.dat now has three columns. These are the energy, unbroadened spectrum and broadened spectrum respectively.","title":"Silicon"},{"location":"workshop/optados/6d_lowloss/#aluminium","text":"Aluminium is a metal so we need to include both the interband and intraband contributions to the dielectric function. To include the intraband contribution optics_intraband = true must be included in the optados input file. When you run optados, the same files are generated as when only the interband term is included. The Al_OPTICS_epsilon.dat file has the same format as before, but it now contains sequentially the interband contribution, the intraband contribution and the total dielectric function. The file Al_OPTICS_epsilon.agr only contains the interband term. In the same way, Al_OPTICS_loss_fn.dat contains the interband contribution, intraband contribution and total loss function. All other optical properties are calculated from the total dielectric function and the format of the output files remains the same. In the case where the dielectric tensor is calculated and the intraband term is included, only the Al_OPTICS_epsilon.dat file is generated. As before it contains each component, but this time it lists sequentially the interband contribution, intraband contribution and total dielectric function for each component. This time, if additional broadening for the loss function is included by using the key word optics_lossfn_broadening , AL_OPTICS_loss_fn.dat will contains four sequential data sets. These are the interband contribution, the intraband contribution, the total loss function without the additional broadening and the broadened total loss function.","title":"Aluminium"}]} \ No newline at end of file +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"CASTEP Documentation This is the CASTEP community documentation and tutorial site. For an overview of CASTEP, and to obtain a licence please see the castep website For the Dassault Syst\u00e8mes BIOVIA (Materials Studio) documentation for CASTEP see HTML documentation and a downloadable pdf user guide Contributors: Albert Bart\u00f3k-P\u00e1rtay, Stewart Clark, Phil Hasnip, Chris Pickard, Matt Probert, Keith Refson, Kane Shenton, Benjamin Shi, Jonathan Yates","title":"Home"},{"location":"#castep-documentation","text":"This is the CASTEP community documentation and tutorial site. For an overview of CASTEP, and to obtain a licence please see the castep website For the Dassault Syst\u00e8mes BIOVIA (Materials Studio) documentation for CASTEP see HTML documentation and a downloadable pdf user guide","title":"CASTEP Documentation"},{"location":"#contributors","text":"Albert Bart\u00f3k-P\u00e1rtay, Stewart Clark, Phil Hasnip, Chris Pickard, Matt Probert, Keith Refson, Kane Shenton, Benjamin Shi, Jonathan Yates","title":"Contributors:"},{"location":"developer/CI/","text":"CI Testing System Overview Notice The following document assumes you have access to both the CASTEP source and the ANVIL CI system. The CASTEP CI system is divided into 3 phases: Rapid Response (BitBucket) A short set of tests run whenever a PR is created or pushed to. CASTEP PR Tests (Jenkins) A more substantial set of tests run whenever a PR is created or pushed to. CASTEP Default Tests (Jenkins) A set of tests run whenever default or a release branch is merged to. The main CASTEP continuous integration (CI) system is a Jenkins instance run on the ANVIL service. The main CASTEP Jenkins instance is available at: https://anvil.softeng-support.ac.uk/jenkins/job/CASTEP/view/all/ Going through the Jenkins Dashboard will take you to the waterfall diagram landing page. Note The ANVIL service is an STFC-cloud managed system and requests to register will be considered by them on a case-by-case basis and are out of control of the CASTEP team. Personal Pipeline For the purposes of development testing you can request a personal pipeline in order to be able to rapidly test in the variety of environments under which the main CASTEP testing is performed. This is required for e.g. modifying the Jenkinsfile Access to this pipeline will require an ANVIL account and a reasonable cause for the request. Navigating Jenkins Waterfall diagram The landing page from the Jenkins dashboard is the Waterfall diagram which shows a quick display of the most recent results for the default , Release and PR_builds pipelines. Tip To enable accessibility options including text-scale and colourblind mode, select the gear in the top-right. The colours represent the status of the pipeline: Colour Colourblind Meaning Green Plain Previous run succeeded. Orange Diamonds Previous run failed tests, but built successfully. Red Diagonal stripe Previous run failed to build one or more pipelines successfully. Note The text below the pipeline describes how long the pipeline has been failing as well as the extent of the failure. Clicking on any of the pipeline names will take you to the pipeline menu for that pipeline. Pipeline Menu The pipeline menu is the display of the status for any single pipeline. It has a number of important displays and buttons. The figure below highlights these. Note The side-bar is dynamic and the options available to you may not match those in the figure above for any particular pipeline. For example, this pipeline has not generated a coverage report. Navigation Bar The navigation bar allows you to look at other pipelines, each name is a link to that section/level of the Jenkins. Warning The \"CASTEP\" level button will take you to the Waterfall landing page. In order to get to the top-level CASTEP dashboard, select \"All\" instead. When viewing linter and warning reports the navigation bar will also display the currently applied filters in the order they were applied and serves as the way to remove those filters. Pipeline Status The pipeline status shows the previous run statuses. It is possible to click on any stage, and then logs to get a step-by-step breakdown of the issue. Any step that failed will be coloured pink rather than the usual grey. It is then possible to click on the tab to expand the console output for that particular step. Generally in the case of: builds this will be the Compile step above the failure. tests this will be the Diff step below the failure. Note Clicking the step name will take you to a different page with a full-page display of the output of that step. Tip Tabs collapse when another is selected. Reports During a Jenkins run, several \"reports\" may be created and made available in the side-bar of a pipeline that generates them. Linting and Compiler Warnings Following a build, Jenkins will collect the compiler warnings issued during a build along with, if a linting phase is run, the resulting linter issues into a report accessible through the side-bar. Warning The warning collection will take the set of warnings from the first build using any of the following compilers: gfortran ifort nag This means that if the first item for each compiler in builds_to_run (see manual parametrised runs ) is not an opt=debug build, you may miss most warnings. The reports allow the types of issues to be selected and filtered: They can be grouped and sorted by clicking the appropriate buttons above the main table and table entries. The doughnut of severity is actually a clickable filter to filter to warnings of that level! The + icon to the left of the issue in \"Issues\" \"group by\" mode allows you to expand the issue to get more detail. Selecting the file from the \"File\" column displays annotated source, however, see the issue below. Known issue Due to the relatively large sizes of CASTEP source files, while selecting the file:line link will take you to an annotated copy of the source at the point of the issue in question, the rendering engine tends to bog down machines causing browsers to struggle or fail to load the annotated file. Test Coverage Report Whenever a coverage build is run (i.e. with either the ifort or gfortran compiler and opt=coverage ), Jenkins will accumulate the coverage reports and make them accessible in the side-bar. Known issue Due to current security settings on ANVIL the ifort reports are not viewable through this view and must be downloaded to be viewed. FORD API Documentation As part of the full build of the default branch following a merge, Jenkins will trigger a FORD API documentation build. The results of this build are accessible from the side-bar of the CASTEP > All > Default_branch > docs-trigger pipeline. Build Artefacts During a Jenkins run, various files will be preserved, making them available to download. Currently the artefacts that are preserved are: Linting reports Failed test data Coverage reports FORD Documentation Some artefacts are available for download at the top of the pipeline menu above the previous runs. For interactive reports (coverage and FORD), when opened the download button is available in the top-right. Jenkins Pipelines The tests run in the course of CI are controlled through the Jenkinsfile in the root CASTEP folder. Default builds run In general, the default set of configurations are run on rocky8 using: Intel 23 Ifx 24 GCC 13 GCC 9 NAG 7.1 NVFortran 23.7 with different combinations of arch , comms and external libraries attempting to cover a broad scope of possible use-cases. Note All default or manual builds will also run a test of the correctness and completeness of the source distribution GNU make and CMake dist targets. Default build keys At time of writing, the default build keys are: rocky8;linux_x86_64_ifort;debug;mpi#intel23 rocky8;linux_x86_64_gfortran;debug;mpi#gcc9 rocky8;linux_x86_64_nag;debug;serial rocky8;linux_x86_64_gfortran10;coverage;mpi#gcc13-libxc rocky8;linux_x86_64_ifort;coverage;serial#intel23-nocmake rocky8;linux_x86_64_ifort;fast;serial#intel23-nocmake rocky8;linux_x86_64_gfortran;fast;mpi#gcc9-nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-nocmake rocky8;linux_x86_64_gfortran10;fast;serial#gcc13-nocmake rocky8;linux_x86_64_nvfortran;fast;mpi#nogrimmed4 rocky8;linux_x86_64_ifx;fast;mpi#ifx24-nocmake However, these are subject to change. PR Builds run When a PR is opened, BitBucket triggers a small subset of the Jenkins tests. These builds only run the quick subset of the tests. Note If a PR only affects parts of CASTEP which are not tested, such as documentation or separate tools, it should have [skiptest] or [skipanvil] in the PR title. If a PR is not yet ready for testing, it should have [wip] or [draft] in the PR title. These will prevent the PR from triggering the Jenkins build saving resources. Default PR builds These builds are (at the time of writing): rocky8;linux_x86_64_nag;intermediate;serial#nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-fftw-nocmake rocky8;linux_x86_64_ifort;intermediate;serial#intel23-nocmake rocky8;linux_x86_64_nvfortran;fast;serial#nogrimmed4-nognumake However, these are subject to change. Manual Parametrised Runs If you wish to start a run with a particular subset of configurations or tests, it is possible to start a parametrised run manually. From the Jenkins interface select the pipeline to run the build on (see Personal Pipelines ) and select Build with Parameters . This allows one to manually specify the components to use. Parameters The parameters are as follows: Parameter Meaning Default repo_method Define method to retrieve repo. Should not need to be changed. https repo_host URL to repository if externally hosted. Should not need to be changed. bitbucket.org repo_path URL Path to workspace and repository. 1 castep/castep branch Branch to build and test. 2 default builds_to_run Builds to run as list of build keys . see: Default builds list tests_to_run List of tests to run. all except quick baseURL Slack URL to post mesasge to. N.B. Set to empty string to not send message. https://corecastepdevelopers.slack.com/services/hooks/ lint Run or skip linting stage. true 1 The command run as part of the checkout will be roughly equivalent to: git clone ${ repo_method } :// ${ repo_host } / ${ repo_path } --single-branch --branch ${ branch } 2 Jenkins will automatically push the run's status to the HEAD commit of the branch being tested at the time of the run. Warning Pushes to the branch while a test is running may result in Jenkins picking up the latest changes and running partial tests on the new HEAD Build keys The Jenkins tests are able to be run on a variety of different system configurations. In order to select a particular configuration, it is necessary to specify the key which identifies the configuration. The format of these keys is: agent;arch;opt;comms#comment Where agent is one of: rocky8 -- Rocky Linux 8 rocky8-gpu -- Rocky Linux 8 with GPU support rocky9 -- Rocky Linux 9 icdpacewin -- Windows and arch , opt and comms correspond to the CASTEP build system variables ARCH , OPT and COMMS . comment is used to distinguish otherwise similar variants and uniquely identify a particular configuration as well as apply modifications to the build (see comment tags ). It should be noted, however, that only certain combinations of variables are available on certain agents. For a full set of available combinations it is necessary to look into the Jenkinsfile itself as this list is frequently updated and changed. Comment Tags The comment section of the build key allows changes to the configuration outside of the usual build flags. These are added in the following way (adding nocmake ): If the base build does not have a comment rocky8;linux_x86_64_nag;debug;serial#nocmake If it does rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake Multiple comment tags are joined with - rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake-nognumake Comment tags Currently the available tags are: Tag Effect targetHost Compiles optimised CASTEP targetting the VM architecture targetPortable Compiles portable CASTEP libxc Links CASTEP against LibXC nogrimmed3 Does not compile (or test) D3 SEDC nogrimmed4 Does not compile (or test) D4 SEDC nodlmg Does not compile (or test) DLMG libraries debug Enable verbose build stages nocmake Disable the CMake build phase and test nognumake Disable the GNU Make build phase and test, run specified test suite on CMake build (if not disabled) BitBucket pipelines In addition to the main Jenkins tests, there is also a subset of short, fast tests which are run on BitBucket every commit to ascertain functionality quickly. The BitBucket pipelines are managed through the bitbucket-pipelines.yml in the root CASTEP folder. They currently run: lint -- Run the castep-linter on the source. build-castep -- A debug build of CASTEP with included LibXC build-castep-python -- debug build of CASTEP's Python bindings test-castep -- Run of CASTEP's quick test suite. test-python -- Run of CASTEP's python test suite. All of these are performed on a single image of a Linux system compiled with gfortran and static LAPACK and BLAS libraries. They are not to be considered comprehensive. Modifying the Jenkinsfile Adding new configurations To add a new combination (c.f. Modifications ), it is necessary to define it in the matrix variable in the Jenkinsfile . This matrix is a Groovy Map object which translates a particular configuration to a Map of extra parameters needed to perform the build. i.e. matrix = [ \"agent;arch#comment\" : [ \"modules\" : \"\" , \"fft\" : \"\" , ...], ... ] Note All parameters are optional. To specify an empty Map (no parameters) use: [:] The list build parameters is outlined in the get_buildconfig_from_map function. Build Parameters Currently the build parameters are: Parameter Description Default modules Modules to load on Linux agents 1 \"\" fft Passed as the CASTEP build system variable FFT \"generic\" math_libs Passed as the CASTEP build system variable MATHLIBS \"generic\" fft_lib_dir Passed as the CASTEP build system variable FFTLIBDIR \"\" math_lib_dir Passed as the CASTEP build system variable MATHLIBDIR \"\" extra_args Extra command-line arguments passed literally to the GNU make build system. \"\" cmake_extra_args Extra command-line arguments passed literally to the CMake build system. \"\" 1 The list of available modules can be found on the ANVIL system under Examples -> List of available software . Adding new comment tags Comment tags are managed in the get_buildconfig_from_map routine. They are processed out of the matrix key, so they can be applied to any particular build configuration. A closure within the routine ( process_buildconfig_arg ) handles this process, its signature is: process_buildconfig_arg ( String comment_key , String make_arg , String cmake_arg ) Where: comment_key Comment tag to process make_arg Extra CLI args to pass to GNU Make build cmake_arg Extra CLI args to pass to CMake build This routine checks for the presence of the comment tag, removes it from the build lookup key and adds make_arg and cmake_arg to their respective argument lists. Note In cases where you do not need to add or modify the compilation arguments, it is reasonable to put them as empty strings ( \"\" ). The comment tags are still passed through to config[0] which can be checked for the presence of the key. Submitting modifications to the Jenkinsfile For any PR with a modification to the Jenkinsfile to be accepted it must be provided with the following: Detailed description of the reasons for the change as well as the changes themselves A custom pipeline run demonstrating the use of the modified pipeline with all expected use-cases, which may include: Each agent in common usage (Currently rocky8 , icdpacewin , rocky8-gpu ) A significant selection of the build configurations in common usage Including at least one WITH a comment, and one without Combinations of common tags All tests (including quick which is not default) Note In order to develop and test a custom Jenkinsfile , it is necessary to make a request to one of the Jenkins admins to reconfigure your pipeline to point to the relevant repository prior to being able to run the custom Jenkinsfile .","title":"CI System"},{"location":"developer/CI/#ci-testing-system","text":"","title":"CI Testing System"},{"location":"developer/CI/#overview","text":"Notice The following document assumes you have access to both the CASTEP source and the ANVIL CI system. The CASTEP CI system is divided into 3 phases: Rapid Response (BitBucket) A short set of tests run whenever a PR is created or pushed to. CASTEP PR Tests (Jenkins) A more substantial set of tests run whenever a PR is created or pushed to. CASTEP Default Tests (Jenkins) A set of tests run whenever default or a release branch is merged to. The main CASTEP continuous integration (CI) system is a Jenkins instance run on the ANVIL service. The main CASTEP Jenkins instance is available at: https://anvil.softeng-support.ac.uk/jenkins/job/CASTEP/view/all/ Going through the Jenkins Dashboard will take you to the waterfall diagram landing page. Note The ANVIL service is an STFC-cloud managed system and requests to register will be considered by them on a case-by-case basis and are out of control of the CASTEP team.","title":"Overview"},{"location":"developer/CI/#personal-pipeline","text":"For the purposes of development testing you can request a personal pipeline in order to be able to rapidly test in the variety of environments under which the main CASTEP testing is performed. This is required for e.g. modifying the Jenkinsfile Access to this pipeline will require an ANVIL account and a reasonable cause for the request.","title":"Personal Pipeline"},{"location":"developer/CI/#navigating-jenkins","text":"","title":"Navigating Jenkins"},{"location":"developer/CI/#waterfall-diagram","text":"The landing page from the Jenkins dashboard is the Waterfall diagram which shows a quick display of the most recent results for the default , Release and PR_builds pipelines. Tip To enable accessibility options including text-scale and colourblind mode, select the gear in the top-right. The colours represent the status of the pipeline: Colour Colourblind Meaning Green Plain Previous run succeeded. Orange Diamonds Previous run failed tests, but built successfully. Red Diagonal stripe Previous run failed to build one or more pipelines successfully. Note The text below the pipeline describes how long the pipeline has been failing as well as the extent of the failure. Clicking on any of the pipeline names will take you to the pipeline menu for that pipeline.","title":"Waterfall diagram"},{"location":"developer/CI/#pipeline-menu","text":"The pipeline menu is the display of the status for any single pipeline. It has a number of important displays and buttons. The figure below highlights these. Note The side-bar is dynamic and the options available to you may not match those in the figure above for any particular pipeline. For example, this pipeline has not generated a coverage report.","title":"Pipeline Menu"},{"location":"developer/CI/#navigation-bar","text":"The navigation bar allows you to look at other pipelines, each name is a link to that section/level of the Jenkins. Warning The \"CASTEP\" level button will take you to the Waterfall landing page. In order to get to the top-level CASTEP dashboard, select \"All\" instead. When viewing linter and warning reports the navigation bar will also display the currently applied filters in the order they were applied and serves as the way to remove those filters.","title":"Navigation Bar"},{"location":"developer/CI/#pipeline-status","text":"The pipeline status shows the previous run statuses. It is possible to click on any stage, and then logs to get a step-by-step breakdown of the issue. Any step that failed will be coloured pink rather than the usual grey. It is then possible to click on the tab to expand the console output for that particular step. Generally in the case of: builds this will be the Compile step above the failure. tests this will be the Diff step below the failure. Note Clicking the step name will take you to a different page with a full-page display of the output of that step. Tip Tabs collapse when another is selected.","title":"Pipeline Status"},{"location":"developer/CI/#reports","text":"During a Jenkins run, several \"reports\" may be created and made available in the side-bar of a pipeline that generates them.","title":"Reports"},{"location":"developer/CI/#linting-and-compiler-warnings","text":"Following a build, Jenkins will collect the compiler warnings issued during a build along with, if a linting phase is run, the resulting linter issues into a report accessible through the side-bar. Warning The warning collection will take the set of warnings from the first build using any of the following compilers: gfortran ifort nag This means that if the first item for each compiler in builds_to_run (see manual parametrised runs ) is not an opt=debug build, you may miss most warnings. The reports allow the types of issues to be selected and filtered: They can be grouped and sorted by clicking the appropriate buttons above the main table and table entries. The doughnut of severity is actually a clickable filter to filter to warnings of that level! The + icon to the left of the issue in \"Issues\" \"group by\" mode allows you to expand the issue to get more detail. Selecting the file from the \"File\" column displays annotated source, however, see the issue below. Known issue Due to the relatively large sizes of CASTEP source files, while selecting the file:line link will take you to an annotated copy of the source at the point of the issue in question, the rendering engine tends to bog down machines causing browsers to struggle or fail to load the annotated file.","title":"Linting and Compiler Warnings"},{"location":"developer/CI/#test-coverage-report","text":"Whenever a coverage build is run (i.e. with either the ifort or gfortran compiler and opt=coverage ), Jenkins will accumulate the coverage reports and make them accessible in the side-bar. Known issue Due to current security settings on ANVIL the ifort reports are not viewable through this view and must be downloaded to be viewed.","title":"Test Coverage Report"},{"location":"developer/CI/#ford-api-documentation","text":"As part of the full build of the default branch following a merge, Jenkins will trigger a FORD API documentation build. The results of this build are accessible from the side-bar of the CASTEP > All > Default_branch > docs-trigger pipeline.","title":"FORD API Documentation"},{"location":"developer/CI/#build-artefacts","text":"During a Jenkins run, various files will be preserved, making them available to download. Currently the artefacts that are preserved are: Linting reports Failed test data Coverage reports FORD Documentation Some artefacts are available for download at the top of the pipeline menu above the previous runs. For interactive reports (coverage and FORD), when opened the download button is available in the top-right.","title":"Build Artefacts"},{"location":"developer/CI/#jenkins-pipelines","text":"The tests run in the course of CI are controlled through the Jenkinsfile in the root CASTEP folder.","title":"Jenkins Pipelines"},{"location":"developer/CI/#default-builds-run","text":"In general, the default set of configurations are run on rocky8 using: Intel 23 Ifx 24 GCC 13 GCC 9 NAG 7.1 NVFortran 23.7 with different combinations of arch , comms and external libraries attempting to cover a broad scope of possible use-cases. Note All default or manual builds will also run a test of the correctness and completeness of the source distribution GNU make and CMake dist targets. Default build keys At time of writing, the default build keys are: rocky8;linux_x86_64_ifort;debug;mpi#intel23 rocky8;linux_x86_64_gfortran;debug;mpi#gcc9 rocky8;linux_x86_64_nag;debug;serial rocky8;linux_x86_64_gfortran10;coverage;mpi#gcc13-libxc rocky8;linux_x86_64_ifort;coverage;serial#intel23-nocmake rocky8;linux_x86_64_ifort;fast;serial#intel23-nocmake rocky8;linux_x86_64_gfortran;fast;mpi#gcc9-nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-nocmake rocky8;linux_x86_64_gfortran10;fast;serial#gcc13-nocmake rocky8;linux_x86_64_nvfortran;fast;mpi#nogrimmed4 rocky8;linux_x86_64_ifx;fast;mpi#ifx24-nocmake However, these are subject to change.","title":"Default builds run"},{"location":"developer/CI/#pr-builds-run","text":"When a PR is opened, BitBucket triggers a small subset of the Jenkins tests. These builds only run the quick subset of the tests. Note If a PR only affects parts of CASTEP which are not tested, such as documentation or separate tools, it should have [skiptest] or [skipanvil] in the PR title. If a PR is not yet ready for testing, it should have [wip] or [draft] in the PR title. These will prevent the PR from triggering the Jenkins build saving resources. Default PR builds These builds are (at the time of writing): rocky8;linux_x86_64_nag;intermediate;serial#nocmake rocky8;linux_x86_64_gfortran10;fast;mpi#gcc13-fftw-nocmake rocky8;linux_x86_64_ifort;intermediate;serial#intel23-nocmake rocky8;linux_x86_64_nvfortran;fast;serial#nogrimmed4-nognumake However, these are subject to change.","title":"PR Builds run"},{"location":"developer/CI/#manual-parametrised-runs","text":"If you wish to start a run with a particular subset of configurations or tests, it is possible to start a parametrised run manually. From the Jenkins interface select the pipeline to run the build on (see Personal Pipelines ) and select Build with Parameters . This allows one to manually specify the components to use. Parameters The parameters are as follows: Parameter Meaning Default repo_method Define method to retrieve repo. Should not need to be changed. https repo_host URL to repository if externally hosted. Should not need to be changed. bitbucket.org repo_path URL Path to workspace and repository. 1 castep/castep branch Branch to build and test. 2 default builds_to_run Builds to run as list of build keys . see: Default builds list tests_to_run List of tests to run. all except quick baseURL Slack URL to post mesasge to. N.B. Set to empty string to not send message. https://corecastepdevelopers.slack.com/services/hooks/ lint Run or skip linting stage. true 1 The command run as part of the checkout will be roughly equivalent to: git clone ${ repo_method } :// ${ repo_host } / ${ repo_path } --single-branch --branch ${ branch } 2 Jenkins will automatically push the run's status to the HEAD commit of the branch being tested at the time of the run. Warning Pushes to the branch while a test is running may result in Jenkins picking up the latest changes and running partial tests on the new HEAD","title":"Manual Parametrised Runs"},{"location":"developer/CI/#build-keys","text":"The Jenkins tests are able to be run on a variety of different system configurations. In order to select a particular configuration, it is necessary to specify the key which identifies the configuration. The format of these keys is: agent;arch;opt;comms#comment Where agent is one of: rocky8 -- Rocky Linux 8 rocky8-gpu -- Rocky Linux 8 with GPU support rocky9 -- Rocky Linux 9 icdpacewin -- Windows and arch , opt and comms correspond to the CASTEP build system variables ARCH , OPT and COMMS . comment is used to distinguish otherwise similar variants and uniquely identify a particular configuration as well as apply modifications to the build (see comment tags ). It should be noted, however, that only certain combinations of variables are available on certain agents. For a full set of available combinations it is necessary to look into the Jenkinsfile itself as this list is frequently updated and changed.","title":"Build keys"},{"location":"developer/CI/#comment-tags","text":"The comment section of the build key allows changes to the configuration outside of the usual build flags. These are added in the following way (adding nocmake ): If the base build does not have a comment rocky8;linux_x86_64_nag;debug;serial#nocmake If it does rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake Multiple comment tags are joined with - rocky8;linux_x86_64_ifort;debug;mpi#intel23-nocmake-nognumake Comment tags Currently the available tags are: Tag Effect targetHost Compiles optimised CASTEP targetting the VM architecture targetPortable Compiles portable CASTEP libxc Links CASTEP against LibXC nogrimmed3 Does not compile (or test) D3 SEDC nogrimmed4 Does not compile (or test) D4 SEDC nodlmg Does not compile (or test) DLMG libraries debug Enable verbose build stages nocmake Disable the CMake build phase and test nognumake Disable the GNU Make build phase and test, run specified test suite on CMake build (if not disabled)","title":"Comment Tags"},{"location":"developer/CI/#bitbucket-pipelines","text":"In addition to the main Jenkins tests, there is also a subset of short, fast tests which are run on BitBucket every commit to ascertain functionality quickly. The BitBucket pipelines are managed through the bitbucket-pipelines.yml in the root CASTEP folder. They currently run: lint -- Run the castep-linter on the source. build-castep -- A debug build of CASTEP with included LibXC build-castep-python -- debug build of CASTEP's Python bindings test-castep -- Run of CASTEP's quick test suite. test-python -- Run of CASTEP's python test suite. All of these are performed on a single image of a Linux system compiled with gfortran and static LAPACK and BLAS libraries. They are not to be considered comprehensive.","title":"BitBucket pipelines"},{"location":"developer/CI/#modifying-the-jenkinsfile","text":"","title":"Modifying the Jenkinsfile"},{"location":"developer/CI/#adding-new-configurations","text":"To add a new combination (c.f. Modifications ), it is necessary to define it in the matrix variable in the Jenkinsfile . This matrix is a Groovy Map object which translates a particular configuration to a Map of extra parameters needed to perform the build. i.e. matrix = [ \"agent;arch#comment\" : [ \"modules\" : \"\" , \"fft\" : \"\" , ...], ... ] Note All parameters are optional. To specify an empty Map (no parameters) use: [:] The list build parameters is outlined in the get_buildconfig_from_map function. Build Parameters Currently the build parameters are: Parameter Description Default modules Modules to load on Linux agents 1 \"\" fft Passed as the CASTEP build system variable FFT \"generic\" math_libs Passed as the CASTEP build system variable MATHLIBS \"generic\" fft_lib_dir Passed as the CASTEP build system variable FFTLIBDIR \"\" math_lib_dir Passed as the CASTEP build system variable MATHLIBDIR \"\" extra_args Extra command-line arguments passed literally to the GNU make build system. \"\" cmake_extra_args Extra command-line arguments passed literally to the CMake build system. \"\" 1 The list of available modules can be found on the ANVIL system under Examples -> List of available software .","title":"Adding new configurations"},{"location":"developer/CI/#adding-new-comment-tags","text":"Comment tags are managed in the get_buildconfig_from_map routine. They are processed out of the matrix key, so they can be applied to any particular build configuration. A closure within the routine ( process_buildconfig_arg ) handles this process, its signature is: process_buildconfig_arg ( String comment_key , String make_arg , String cmake_arg ) Where: comment_key Comment tag to process make_arg Extra CLI args to pass to GNU Make build cmake_arg Extra CLI args to pass to CMake build This routine checks for the presence of the comment tag, removes it from the build lookup key and adds make_arg and cmake_arg to their respective argument lists. Note In cases where you do not need to add or modify the compilation arguments, it is reasonable to put them as empty strings ( \"\" ). The comment tags are still passed through to config[0] which can be checked for the presence of the key.","title":"Adding new comment tags"},{"location":"developer/CI/#submitting-modifications-to-the-jenkinsfile","text":"For any PR with a modification to the Jenkinsfile to be accepted it must be provided with the following: Detailed description of the reasons for the change as well as the changes themselves A custom pipeline run demonstrating the use of the modified pipeline with all expected use-cases, which may include: Each agent in common usage (Currently rocky8 , icdpacewin , rocky8-gpu ) A significant selection of the build configurations in common usage Including at least one WITH a comment, and one without Combinations of common tags All tests (including quick which is not default) Note In order to develop and test a custom Jenkinsfile , it is necessary to make a request to one of the Jenkins admins to reconfigure your pipeline to point to the relevant repository prior to being able to run the custom Jenkinsfile .","title":"Submitting modifications to the Jenkinsfile"},{"location":"developer/adding_pair_pots/","text":"Adding Empirical potentials If you have access to the source, it is possible to add a new formulation for an empirical potential easily. The idea of the module is that this should be trivial even to a beginner programmer with no expert knowledge of Fortran. A summary of how to do this is in the header of the pair_pot.f90 source, a more in-depth description is below. Setting up parameters First we need to make the pair_pot_type aware of your potential. There are several key things we need to update in order to use our potential. First, we need to update the number of potentials our code is looking for: BEFORE : integer , parameter :: num_pot = 9 AFTER : integer , parameter :: num_pot = 10 Next we need to tell the code what our potential's keyword is and its internal ID. This will be the highest number which isn't occupied. (NOTE: Keywords have to have a length of 4 characters and must be padded with spaces to this length): BEFORE : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' ] AFTER : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 , new = 10 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' , 'NEW ' ] We then need to add the parameters that our potential will use to the pair_pot_type . The style of these parameters should be: The variable name should be the keyword of your potential followed by an underscore, followed by the name or symbol for the parameter. They should be of type real(kind=dp) . They should be allocatable, and of dimensions equivalent to the number of particles involved in the interaction (i.e. 2-body \\Rightarrow{} \\Rightarrow{} dimension(:,:) ; 3-body \\Rightarrow{} \\Rightarrow{} dimension(:,:,:) ). They should have a comment describing the full name and form of your potential. It is also important to note that Fortran is case-insensitive, meaning it does not distinguish between upper and lower cases in variable names. !New example potential of the form b*exp(rij^-qi)*exp(rik^-qi) + (cos(rijk) - cos(s)) real ( kind = dp ), dimension (:), allocatable :: new_q real ( kind = dp ), dimension (:,:), allocatable :: new_b real ( kind = dp ), dimension (:,:,:), allocatable :: new_s We should now go into pair_pot_print and add our potential to the 1- and 2- (and possibly 3-)body sections of the potential printing. This is of the form: 1-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 103 ) pre_str , 'r' , pair_pot % cut_off ( pair_pot % new , 1 , 1 ), 'NEW' write ( unit_out , 103 ) pre_str , 'q' , pair_pot % new_q ( 1 , 1 ), 'NEW' end if 2-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 202 ) pre_str , 'r' , pair_pot_print_combinations ( pair_pot % cut_off ( pair_pot % new , :, :), ispec , jspec ), 'NEW' write ( unit_out , 202 ) pre_str , 'b' , pair_pot_print_combinations ( pair_pot % new_b , ispec , jspec ), 'NEW' end if 3-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 301 ) pre_str , ispec_name , jspec_name , kspec_name write ( unit_out , 103 ) pre_str , 'S' , pair_pot % new_s ( ispec , jspec , kspec ), 'NEW' end if And with that we should be done with setting up our potential in pair_pot_type , things like cut-off and the activation of the potential are handled automatically based on the potential keyword, although for some specialised potentials advanced rules can be necessary. Allocation and deallocation It is important in Fortran to ensure that our parameter arrays are allocated. We need to go into the routine pair_pot_allocate and add our new parameters to it. For our example potential, the syntax is as follows: if ( pair_pot % pot_present ( pair_pot % new ) allocate ( pair_pot % new_q ( 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_q' , 'pair_pot_allocate' ) allocate ( pair_pot % new_b ( 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_b' , 'pair_pot_allocate' ) allocate ( pair_pot % new_s ( 1 : nspec , 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_s' , 'pair_pot_allocate' ) end if We also need to do the same for cleaning up our potential at the end, in the routine pair_pot_deallocate : if ( allocated ( pair_pot % new_q )) then deallocate ( pair_pot % new_q , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_q in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_b )) then deallocate ( pair_pot % new_b , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_b in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_s )) then deallocate ( pair_pot % new_s , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_s in pair_pot_deallocate' ) end if Initialising variables We need to be able to set the values for our parameters. For this we need to add an initialisation subroutine. The details can be found in the sample file, available on request. For three-body routines it is necessary to set the pair_pot%three_body flag on initialisation, and also to add a species triplet loop. Writing the calculation routine This is the only bit which is down to the the creator to consider how it should be set up. The subroutine should obey the follow: The name of the routine should be pair_pot_ The potential should have a header referencing the origin of the potential and the form of the potential. Two-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , rij , mod_rij_2 , ispec , jspec [, spins ], dfij , de ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. rij is of type real(kind=dp) of dimension(3) and is the vector between the two particles. mod_rij_2 is of type real(kind=dp) and is the distance between the two particles. ispec is of type integer and is the species of atom i. jspec is of type integer and is the species of atom j. spins [optional] is of type real(kind=dp) of dimension(4,2) and is the pair of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3) and is the vector force between the two particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the two particles. To reference two-body terms you should use the following syntax: pair_pot % new_b ( ispec , jspec ) Three-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , dr , mod_dr_2 , rcjk , include_cjk , spec [, spins ], dfij , de , stress ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. dr is of type real(kind=dp) of dimension(3,3) and is the vectors of the triplet of pairs of particles. mod_dr_2 is of type real(kind=dp) of dimension(3) and is the distance between the triplet of particles. rcjk is of type real(kind=dp) of dimension(3,3) and is the absolute positions of the particles in the cell. include_cjk is of type logical of dimension(3) and is whether the magnitude of distances between particles is less than that of the cut-off. spec is of type integer of dimension(3) and is the species of the particles. spins [optional] is of type real(kind=dp) of dimension(4,3) and is the triplet of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3,3) and is the vector force between the triplet of particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the interactions. stress is of type real(kind=dp) of dimension(6) and is the upper triangle of stress contributions of the particles. To reference three-body terms you should use the following syntax: pair_pot % new_s ( spec ( i_atom ), spec ( j_atom ), spec ( k_atom )) Spins If your potential uses spin as part of the force-field these are passed into the calculation routines as a set of 4-vectors (2 for 2-body, 3 for 3-body) where the 4 parameters are the 3 directions and the magnitude. Adding the contribution To actually tell the code to calculate the contribution of your potential to the system, we need to add it to the pair_pot_contribution routine, this has the following syntax for two-body potentials: if ( pot_include ( pair_pot % new )) then call pair_pot_new ( pair_pot , rij , mod_rij_2 , species ( 1 ), species ( 2 ), dfij , de ) e_cont = e_cont + de fij (:) = fij (:) + dfij (:) end if Three-body potentials are currently trickier and must currently be manually inserted into the loop in pair_pot_calc , there are aims to simplify this in future releases. Testing We should now be able to activate your potential by adding NEW=T into the devel code block and can set all the parameters just as for other potentials. To verify that you potential is working as expected, there are several built-in methods to check for developers. The first is the FD_CHECK devel code which enables finite difference evaluation alongside the potential evaluation and dumps the output to a file .fd . It aso prints warnings if the analytic and finite difference derivatives do not match. You should verify that the finite difference evaluated forces are the same as the analytic derivative. The second is the PRINT_POT devel code which evaluates your potential over 1000 evenly spaced points between 0 and your cut-off and dumps the computed forces and energies to a series of files of the form ____.pot these are just 3-column tabular data of the form Distance Energy Force ready to be plotted. Tests should be added to the test suite to compute the value of your new potential at known points.","title":"Adding empirical potentials"},{"location":"developer/adding_pair_pots/#adding-empirical-potentials","text":"If you have access to the source, it is possible to add a new formulation for an empirical potential easily. The idea of the module is that this should be trivial even to a beginner programmer with no expert knowledge of Fortran. A summary of how to do this is in the header of the pair_pot.f90 source, a more in-depth description is below.","title":"Adding Empirical potentials"},{"location":"developer/adding_pair_pots/#setting-up-parameters","text":"First we need to make the pair_pot_type aware of your potential. There are several key things we need to update in order to use our potential. First, we need to update the number of potentials our code is looking for: BEFORE : integer , parameter :: num_pot = 9 AFTER : integer , parameter :: num_pot = 10 Next we need to tell the code what our potential's keyword is and its internal ID. This will be the highest number which isn't occupied. (NOTE: Keywords have to have a length of 4 characters and must be padded with spaces to this length): BEFORE : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' ] AFTER : integer :: lj = 1 , buck = 2 , coul = 3 , dz = 4 , pol = 5 , bb = 6 , bs = 7 , sw = 8 , mors = 9 , new = 10 character ( len = 4 ), dimension ( num_pot ) :: name = & & [ 'LJ ' , 'BUCK' , 'COUL' , 'DZ ' , 'POL ' , 'BB ' , 'BS ' , 'SW ' , 'MORS' , 'NEW ' ] We then need to add the parameters that our potential will use to the pair_pot_type . The style of these parameters should be: The variable name should be the keyword of your potential followed by an underscore, followed by the name or symbol for the parameter. They should be of type real(kind=dp) . They should be allocatable, and of dimensions equivalent to the number of particles involved in the interaction (i.e. 2-body \\Rightarrow{} \\Rightarrow{} dimension(:,:) ; 3-body \\Rightarrow{} \\Rightarrow{} dimension(:,:,:) ). They should have a comment describing the full name and form of your potential. It is also important to note that Fortran is case-insensitive, meaning it does not distinguish between upper and lower cases in variable names. !New example potential of the form b*exp(rij^-qi)*exp(rik^-qi) + (cos(rijk) - cos(s)) real ( kind = dp ), dimension (:), allocatable :: new_q real ( kind = dp ), dimension (:,:), allocatable :: new_b real ( kind = dp ), dimension (:,:,:), allocatable :: new_s We should now go into pair_pot_print and add our potential to the 1- and 2- (and possibly 3-)body sections of the potential printing. This is of the form: 1-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 103 ) pre_str , 'r' , pair_pot % cut_off ( pair_pot % new , 1 , 1 ), 'NEW' write ( unit_out , 103 ) pre_str , 'q' , pair_pot % new_q ( 1 , 1 ), 'NEW' end if 2-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 202 ) pre_str , 'r' , pair_pot_print_combinations ( pair_pot % cut_off ( pair_pot % new , :, :), ispec , jspec ), 'NEW' write ( unit_out , 202 ) pre_str , 'b' , pair_pot_print_combinations ( pair_pot % new_b , ispec , jspec ), 'NEW' end if 3-Body if ( pair_pot % pot_present ( pair_pot % new )) then write ( unit_out , 301 ) pre_str , ispec_name , jspec_name , kspec_name write ( unit_out , 103 ) pre_str , 'S' , pair_pot % new_s ( ispec , jspec , kspec ), 'NEW' end if And with that we should be done with setting up our potential in pair_pot_type , things like cut-off and the activation of the potential are handled automatically based on the potential keyword, although for some specialised potentials advanced rules can be necessary.","title":"Setting up parameters"},{"location":"developer/adding_pair_pots/#allocation-and-deallocation","text":"It is important in Fortran to ensure that our parameter arrays are allocated. We need to go into the routine pair_pot_allocate and add our new parameters to it. For our example potential, the syntax is as follows: if ( pair_pot % pot_present ( pair_pot % new ) allocate ( pair_pot % new_q ( 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_q' , 'pair_pot_allocate' ) allocate ( pair_pot % new_b ( 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_b' , 'pair_pot_allocate' ) allocate ( pair_pot % new_s ( 1 : nspec , 1 : nspec , 1 : nspec ), stat = ierr ) if ( ierr . ne . 0 ) call io_allocate_abort ( 'new_s' , 'pair_pot_allocate' ) end if We also need to do the same for cleaning up our potential at the end, in the routine pair_pot_deallocate : if ( allocated ( pair_pot % new_q )) then deallocate ( pair_pot % new_q , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_q in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_b )) then deallocate ( pair_pot % new_b , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_b in pair_pot_deallocate' ) end if if ( allocated ( pair_pot % new_s )) then deallocate ( pair_pot % new_s , stat = ierr ) if ( ierr . ne . 0 ) call io_abort ( 'Error deallocating new_s in pair_pot_deallocate' ) end if","title":"Allocation and deallocation"},{"location":"developer/adding_pair_pots/#initialising-variables","text":"We need to be able to set the values for our parameters. For this we need to add an initialisation subroutine. The details can be found in the sample file, available on request. For three-body routines it is necessary to set the pair_pot%three_body flag on initialisation, and also to add a species triplet loop.","title":"Initialising variables"},{"location":"developer/adding_pair_pots/#writing-the-calculation-routine","text":"This is the only bit which is down to the the creator to consider how it should be set up. The subroutine should obey the follow: The name of the routine should be pair_pot_ The potential should have a header referencing the origin of the potential and the form of the potential. Two-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , rij , mod_rij_2 , ispec , jspec [, spins ], dfij , de ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. rij is of type real(kind=dp) of dimension(3) and is the vector between the two particles. mod_rij_2 is of type real(kind=dp) and is the distance between the two particles. ispec is of type integer and is the species of atom i. jspec is of type integer and is the species of atom j. spins [optional] is of type real(kind=dp) of dimension(4,2) and is the pair of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3) and is the vector force between the two particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the two particles. To reference two-body terms you should use the following syntax: pair_pot % new_b ( ispec , jspec ) Three-body potentials should obey the following input structure: subroutine pair_pot_new ( pair_pot , dr , mod_dr_2 , rcjk , include_cjk , spec [, spins ], dfij , de , stress ) Where: pair_pot is of type pair_pot_type and contains the initialised parameters of your new potential. dr is of type real(kind=dp) of dimension(3,3) and is the vectors of the triplet of pairs of particles. mod_dr_2 is of type real(kind=dp) of dimension(3) and is the distance between the triplet of particles. rcjk is of type real(kind=dp) of dimension(3,3) and is the absolute positions of the particles in the cell. include_cjk is of type logical of dimension(3) and is whether the magnitude of distances between particles is less than that of the cut-off. spec is of type integer of dimension(3) and is the species of the particles. spins [optional] is of type real(kind=dp) of dimension(4,3) and is the triplet of spin vectors of (x, y, z, magnitude) dfij is of type real(kind=dp) of dimension(3,3) and is the vector force between the triplet of particles. de is of type real(kind=dp) and is the contribution to the total potential energy of the interactions. stress is of type real(kind=dp) of dimension(6) and is the upper triangle of stress contributions of the particles. To reference three-body terms you should use the following syntax: pair_pot % new_s ( spec ( i_atom ), spec ( j_atom ), spec ( k_atom ))","title":"Writing the calculation routine"},{"location":"developer/adding_pair_pots/#spins","text":"If your potential uses spin as part of the force-field these are passed into the calculation routines as a set of 4-vectors (2 for 2-body, 3 for 3-body) where the 4 parameters are the 3 directions and the magnitude.","title":"Spins"},{"location":"developer/adding_pair_pots/#adding-the-contribution","text":"To actually tell the code to calculate the contribution of your potential to the system, we need to add it to the pair_pot_contribution routine, this has the following syntax for two-body potentials: if ( pot_include ( pair_pot % new )) then call pair_pot_new ( pair_pot , rij , mod_rij_2 , species ( 1 ), species ( 2 ), dfij , de ) e_cont = e_cont + de fij (:) = fij (:) + dfij (:) end if Three-body potentials are currently trickier and must currently be manually inserted into the loop in pair_pot_calc , there are aims to simplify this in future releases.","title":"Adding the contribution"},{"location":"developer/adding_pair_pots/#testing","text":"We should now be able to activate your potential by adding NEW=T into the devel code block and can set all the parameters just as for other potentials. To verify that you potential is working as expected, there are several built-in methods to check for developers. The first is the FD_CHECK devel code which enables finite difference evaluation alongside the potential evaluation and dumps the output to a file .fd . It aso prints warnings if the analytic and finite difference derivatives do not match. You should verify that the finite difference evaluated forces are the same as the analytic derivative. The second is the PRINT_POT devel code which evaluates your potential over 1000 evenly spaced points between 0 and your cut-off and dumps the computed forces and energies to a series of files of the form ____.pot these are just 3-column tabular data of the form Distance Energy Force ready to be plotted. Tests should be added to the test suite to compute the value of your new potential at known points.","title":"Testing"},{"location":"developer/adding_testing/","text":"Adding Tests Following the addition of a new feature or bugfix it is essential to add system and unit tests that demonstrate the functionality of said addition. This document describes the process of adding new tests to the system as well as implementing your own testing groups. Warning Before any code is accepted into CASTEP it must have tests to prove its functionality and robustness. testcode CASTEP's test suite is built using the testcode testing platform. This handles all of the generation of benchmarks and comparisons in the test suite. Valid Properties CASTEP's extract_results.pl can extract the following properties from the .castep files: Note Those in code-style are the names for the properties, those without are just divisions used here Energy PS_Energy FreeEnergy SolvationEnergy dEtot/dlogE Spin AbsSpin Force Stress Phonons Phonon-q Phonon Grad_q(f) Freq g(f) ir Raman Born Species Ion Born Permittivity Polarisability Permittivity epsilon(f) NLO_Chi2 Raman Raman_Tr Raman_II depolarisation Electric_constants Compliance_mat Mulliken Populations Species Ion s p d f Total Charge Hirshfeld populations Species Ion Hirshfeld Spin ELF Data elf_fmt gx gy gz ELF(chi) den_fmt gx gy gz density chdiff_fmt gx gy gz diff-den pot_fmt gx gy gz potential Band Structure kx ky kz weight Eigenvalue MD Data MD Labels from the block magres cs_iso cs_aniso cs_eta Cq eta_q hf_iso FC SD PARA DIA TOT TDDFT_Eigenvalues Hugoniostat H-Compression H-Temperature H-Pressure H-Energy EFermi xrd_sf h k l Re(...) , Im(...) from output file The Test folder structure The CASTEP test folder is structured as follows: Test |- CMakeLists.txt |- jobconfig |- userconfig |- README |- List |- Electronic |- Cr-AFM |- Cr_00PBE.uspcc |- Cr_AFM.cell |- Cr_AFM.param |- benchmark.out.castep-23.1.castep-python-1.0.python-3.6.9.inp=Cr_AFM.param |- ELF |- Electrostatics ... |- XC ... The key files in the Test directory are: CMakeLists.txt CMake source file to build test suite in the CMake build system (see: Adding tests to be run ) jobconfig Essential file for testcode which defines the jobs, tolerances and categories of tests. userconfig Essential file for testcode which defines the commands to run tests and where to look for benchmarks. README Brief documentation detailing the purpose of the test suite and how to construct tests. The tests themselves are generally structured in the folder tree by a folder representing the general category of the tests and then a sub-folder for the specific test case. It is, however, possible to have multiple test cases within these sub-folders. The structure is used by testcode to determine which properties to check with which tolerances. Adding Tests Defining new tests What do tests look like? Tests in CASTEP are generally defined via a short CASTEP run (complete with .cell and .param files) which is: Sufficient to demonstrate the functionality in question Short enough that it does not take significant time to run Stable enough that the results do not change significantly from run to run. Note These calculations do not necessarily need to be physcially meaningful and in general should not, due to the time requirements. Adding tests to be run testcode runs tests according to two files contained in the Test directory . userconfig To add tests you should not need to touch userconfig , so we can ignore that here. jobconfig If we are adding a new test folder we need to modify jobconfig to include the new test folder, as well as define tolerances on the various properties we might measure within the tests. The structure of the jobconfig is as follows: # Run all tests on this folder and all subfolders with the given settings. [Electronic/*] run_concurrent = true # (1) tolerance = (0.015, None, 'Spin') # (2) # Override the settings of the general folder for a specific case. [Electronic/Si2-fine-grid] tolerance = (0.0003, None, 'Energy'), (0.0003, None, 'PS_Energy') Enable running tests within this folder in parallel. Set the tolerance for a given property . How to ensure stability CASTEP tests generally want to have a fixed seed using: rand_seed: 1234567890 Note The actual value of the rand_seed doesn't matter, only that it is fixed. The test should also generally be a short run of a small crystal structure to avoid any potential noise accumulating in the answer. The run does not need tight tolerances on E_{\\text{cut}} E_{\\text{cut}} or \\mathbf{k} \\mathbf{k} -point meshes, only sufficient to ensure that the answer produced is not noise itself. Adding Test Groups Adding to jobconfig At the end of the jobconfig file, there is a section called categories which contains the list of categories testcode knows about. The structure is: < category_name > := < path_to_tests > | < other categories > Note The can contain wildcards, or absolute paths Note All paths are relative to the location of jobconfig in CASTEP's case that is the /Test Example format of the categories [categories] spe-simple = Electronic/* bs-simple = Excitations/* phonon-simple = Phonon/* ... simple = spe-simple bs-simple phonon-simple [...] ... Adding to CMake To add the tests to be compatible with the CMake build system you need to modify the CMakeLists.txt at Test/CMakeLists.txt and add the category to the list on line 157, which looks like: foreach ( CASTEP_TEST_CATEGORY \"spe\" \"bs\" \"phonon\" ... ) ADD_CATEGORY_TARGETS ( ${ CASTEP_TEST_CATEGORY } TRUE ) endforeach () Adding to Make To add the tests properly to the GNU make build system ) you need to modify the Makefile at Test/Makefile and add the category in several places. Add it to the list of .PHONY : .PHONY : check check - simple check - spe - simple ... and create an entry in the appropriate lists for each of the five classes of test jobs: check recheck benchmark compare diff to call your tests when the target is called e.g.: check-solvation : exe - exists prepare - clean $( TESTCODE ) $( QUIET_FLAG ) $( PARALLEL ) -e $( CASTEPEXE ) -c solvation-simple Note exe-exists and prepare-clean are to ensure that CASTEP is compiled and that any old test runs are cleared out before starting the tests.","title":"Testing"},{"location":"developer/adding_testing/#adding-tests","text":"Following the addition of a new feature or bugfix it is essential to add system and unit tests that demonstrate the functionality of said addition. This document describes the process of adding new tests to the system as well as implementing your own testing groups. Warning Before any code is accepted into CASTEP it must have tests to prove its functionality and robustness.","title":"Adding Tests"},{"location":"developer/adding_testing/#testcode","text":"CASTEP's test suite is built using the testcode testing platform. This handles all of the generation of benchmarks and comparisons in the test suite.","title":"testcode"},{"location":"developer/adding_testing/#valid-properties","text":"CASTEP's extract_results.pl can extract the following properties from the .castep files: Note Those in code-style are the names for the properties, those without are just divisions used here Energy PS_Energy FreeEnergy SolvationEnergy dEtot/dlogE Spin AbsSpin Force Stress Phonons Phonon-q Phonon Grad_q(f) Freq g(f) ir Raman Born Species Ion Born Permittivity Polarisability Permittivity epsilon(f) NLO_Chi2 Raman Raman_Tr Raman_II depolarisation Electric_constants Compliance_mat Mulliken Populations Species Ion s p d f Total Charge Hirshfeld populations Species Ion Hirshfeld Spin ELF Data elf_fmt gx gy gz ELF(chi) den_fmt gx gy gz density chdiff_fmt gx gy gz diff-den pot_fmt gx gy gz potential Band Structure kx ky kz weight Eigenvalue MD Data MD Labels from the block magres cs_iso cs_aniso cs_eta Cq eta_q hf_iso FC SD PARA DIA TOT TDDFT_Eigenvalues Hugoniostat H-Compression H-Temperature H-Pressure H-Energy EFermi xrd_sf h k l Re(...) , Im(...) from output file","title":"Valid Properties"},{"location":"developer/adding_testing/#the-test-folder-structure","text":"The CASTEP test folder is structured as follows: Test |- CMakeLists.txt |- jobconfig |- userconfig |- README |- List |- Electronic |- Cr-AFM |- Cr_00PBE.uspcc |- Cr_AFM.cell |- Cr_AFM.param |- benchmark.out.castep-23.1.castep-python-1.0.python-3.6.9.inp=Cr_AFM.param |- ELF |- Electrostatics ... |- XC ... The key files in the Test directory are: CMakeLists.txt CMake source file to build test suite in the CMake build system (see: Adding tests to be run ) jobconfig Essential file for testcode which defines the jobs, tolerances and categories of tests. userconfig Essential file for testcode which defines the commands to run tests and where to look for benchmarks. README Brief documentation detailing the purpose of the test suite and how to construct tests. The tests themselves are generally structured in the folder tree by a folder representing the general category of the tests and then a sub-folder for the specific test case. It is, however, possible to have multiple test cases within these sub-folders. The structure is used by testcode to determine which properties to check with which tolerances.","title":"The Test folder structure"},{"location":"developer/adding_testing/#adding-tests_1","text":"","title":"Adding Tests"},{"location":"developer/adding_testing/#defining-new-tests","text":"","title":"Defining new tests"},{"location":"developer/adding_testing/#what-do-tests-look-like","text":"Tests in CASTEP are generally defined via a short CASTEP run (complete with .cell and .param files) which is: Sufficient to demonstrate the functionality in question Short enough that it does not take significant time to run Stable enough that the results do not change significantly from run to run. Note These calculations do not necessarily need to be physcially meaningful and in general should not, due to the time requirements.","title":"What do tests look like?"},{"location":"developer/adding_testing/#adding-tests-to-be-run","text":"testcode runs tests according to two files contained in the Test directory .","title":"Adding tests to be run"},{"location":"developer/adding_testing/#userconfig","text":"To add tests you should not need to touch userconfig , so we can ignore that here.","title":"userconfig"},{"location":"developer/adding_testing/#jobconfig","text":"If we are adding a new test folder we need to modify jobconfig to include the new test folder, as well as define tolerances on the various properties we might measure within the tests. The structure of the jobconfig is as follows: # Run all tests on this folder and all subfolders with the given settings. [Electronic/*] run_concurrent = true # (1) tolerance = (0.015, None, 'Spin') # (2) # Override the settings of the general folder for a specific case. [Electronic/Si2-fine-grid] tolerance = (0.0003, None, 'Energy'), (0.0003, None, 'PS_Energy') Enable running tests within this folder in parallel. Set the tolerance for a given property .","title":"jobconfig"},{"location":"developer/adding_testing/#how-to-ensure-stability","text":"CASTEP tests generally want to have a fixed seed using: rand_seed: 1234567890 Note The actual value of the rand_seed doesn't matter, only that it is fixed. The test should also generally be a short run of a small crystal structure to avoid any potential noise accumulating in the answer. The run does not need tight tolerances on E_{\\text{cut}} E_{\\text{cut}} or \\mathbf{k} \\mathbf{k} -point meshes, only sufficient to ensure that the answer produced is not noise itself.","title":"How to ensure stability"},{"location":"developer/adding_testing/#adding-test-groups","text":"","title":"Adding Test Groups"},{"location":"developer/adding_testing/#adding-to-jobconfig","text":"At the end of the jobconfig file, there is a section called categories which contains the list of categories testcode knows about. The structure is: < category_name > := < path_to_tests > | < other categories > Note The can contain wildcards, or absolute paths Note All paths are relative to the location of jobconfig in CASTEP's case that is the /Test Example format of the categories [categories] spe-simple = Electronic/* bs-simple = Excitations/* phonon-simple = Phonon/* ... simple = spe-simple bs-simple phonon-simple [...] ...","title":"Adding to jobconfig"},{"location":"developer/adding_testing/#adding-to-cmake","text":"To add the tests to be compatible with the CMake build system you need to modify the CMakeLists.txt at Test/CMakeLists.txt and add the category to the list on line 157, which looks like: foreach ( CASTEP_TEST_CATEGORY \"spe\" \"bs\" \"phonon\" ... ) ADD_CATEGORY_TARGETS ( ${ CASTEP_TEST_CATEGORY } TRUE ) endforeach ()","title":"Adding to CMake"},{"location":"developer/adding_testing/#adding-to-make","text":"To add the tests properly to the GNU make build system ) you need to modify the Makefile at Test/Makefile and add the category in several places. Add it to the list of .PHONY : .PHONY : check check - simple check - spe - simple ... and create an entry in the appropriate lists for each of the five classes of test jobs: check recheck benchmark compare diff to call your tests when the target is called e.g.: check-solvation : exe - exists prepare - clean $( TESTCODE ) $( QUIET_FLAG ) $( PARALLEL ) -e $( CASTEPEXE ) -c solvation-simple Note exe-exists and prepare-clean are to ensure that CASTEP is compiled and that any old test runs are cleared out before starting the tests.","title":"Adding to Make"},{"location":"developer/build-system/","text":"The CASTEP Build Sytem Introduction This documentation is intended for developers who intend to add new features/sources to the CASTEP system. A quick-start guide on how to build CASTEP can be found in the CASTEP_ROOT in README.INSTALL for the GNU Make build-system or README.cmake for the new CMake build system. The CASTEP build system is designed to be efficient, but also intuitive. There are two existing build systems, one relying on GNU Make, which is faster to build and intended for rapid development, and one based on CMake which is designed to be more intuitive to those who are used to CMake build systems and for automatically detecting the best options for the average user. CASTEP directory structure When adding new sources to CASTEP it is important to consider the hierarchical directory/module structure of CASTEP. CASTEP sources are currently organised into sub-libraries which each depend on the library above them in the hierarchy. These libraries, in order of hierarchy are: Utility Fundamental OTFG Dispersion Functional There are also Tools which are separately built programs which depend on the CASTEP sub-libraries. GNU Make The GNU make build system is broken down into a hierarchical tree which build up the required rules for compiling CASTEP on as many varied systems as possible while still being isolated and maintable. The hierarchy of these make files is as follows: \u251c `/` \u2514\u2500\u252c\u2500 `Makefile` - Root Makefile \u251c\u2500 `obj/` \u2514\u2500\u2500\u252c\u2500 `include_rules.mk` \u251c\u2500 `include_utility.mk` \u251c\u2500 `include_fundamental.mk` \u251c\u2500 `include_otfg.mk` \u251c\u2500 `include_dispersion.mk` \u251c\u2500 `include_functional.mk` \u251c\u2500 `include_test.mk` \u251c\u2500 `include_tools.mk` \u251c\u2500 `platforms/` \u2514\u2500\u2500\u2500\u2500 Various make rules for different platforms CMake The CMake system is designed to be intuitive for those who are used to CMake build systems while still being familiar to those who are used to the CASTEP GNU Make style syntax. This means that many of the CASTEP CMake variables have names which are chosen to match, or are aliased to, the CASTEP GNU Make variables. This is intended to minimise confusion for people who transition from GNU Make to CMake. The CMake system is also intended to expand the capabilities of CASTEP to be able to compile and run efficiently on Windows systems. Adding New Source Files In order to add new sources to CASTEP, first it is necessary to work out the relevant dependencies and where they fit into the directory structure (i.e. the CASTEP sub-libraries). Adding to GNU Make build-system Following this the source should be added to the relevant obj/include_.mk SRCS_$(D) . This will automatically include your new source in the CASTEP sub-library. Adding to the CMake build-system The next step is to navigate into the sub-library folder which contains your new source and add the source file into the CMakeLists.txt therein. Conditional inclusion If your source file provides functions which should only conditionally be included in CASTEP (e.g. interfaces to external libraries), then it must provide stub functions (generally no-op s returning relevant arguments) in order that the conditional inclusions can be compiled. These are generally saved as source_name.stub.f90 and these must be conditionally included into the compilation. Adding to GNU Make build-system First off, it is important to add a conditional into the relevant obj/include_.mk to include either your stub or your main source into the compilation. obj/include_.mk ifeq (${MY_LIBRARY_VAR},none) SRCS_$(d) := $(SRCS_$(d)) source_name.stub.f90 else SRCS_$(d) := $(SRCS_$(d)) source_name.f90 endif If extra libraries are needed to be conditionally linked these should be added as follows: obj/include_rules.mk ifneq (${MY_LIBRARY_VAR},none) ifneq ($(strip $(MY_LIB_REL_LIB_DIR)), ) CASTEP_LIB_SEARCH_PATH += -L\"../$(MY_LIB_REL_LIB_DIR)\" ifdef SUN CASTEP_LIB_SEARCH_PATH += -R \"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef NAG CASTEP_LIB_SEARCH_PATH += -Wl,-Wl,,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef LINUX CASTEP_LIB_SEARCH_PATH += -Wl,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" endif LIBS += -lmy_extra_lib endif Adding to CMake build-system The process with the CMake is similar, create a variable which selects either your source or stub based on an option. e.g. CASTEP_ROOT/CMakeLists.txt option(WITH_MY_LIB \"my lib's features\") cmake/extralibs.cmake if(WITH_MY_LIB) set(MY_LIB_MOD source_name.f90) else() set(MY_LIB_MOD source_name.stub.f90) endif() SOURCE_DIR/CMakeLists.txt add_castep_lib(NAME sub_lib SRCS ... ${MY_LIB_MOD} ... ) If extra libraries are needed to be conditionally linked these should be added as follows: cmake/extralibs.cmake if(WITH_MY_LIB) find_library(my_extra_lib NAMES my_extra_lib HINTS ${EXTERNAL_MY_LIB} DOC \"Doc\") if (NOT my_extra_lib) message(FATAL_ERROR \"MY_EXTRA_LIB requested, but not found. Set EXTERNAL_MY_LIB to manually specify location of libraries (currently: '${EXTERNAL_MY_LIB}')\") endif() set(MY_EXTRA_LIB ${my_extra_lib}) set(MY_LIB_MOD source_name.f90) else() set(MY_EXTRA_LIB \"\") set(MY_LIB_MOD source_name.stub.f90) endif() ... mark_as_advanced(... my_extra_lib) SOURCE_DIR/CMakeLists.txt target_link_libraries(sub-lib ... ${MY_EXTRA_LIB}) Special Compilation Options If you need to add special per-file compilation options, first you should check that your code is properly standards conforming. Failing that, it is possible to override options by setting them up in each platform, however, this is discouraged unless absolutely necessary. Adding to GNU Make build-system In the GNU make system it is necessary to add the special compilation flags to each relevant platform under the obj/platforms directory. e.g. obj/platforms/.mk .o: private OPT = -O2 Adding to CMake build-system In the CMake build system, flags are set up in the cmake/buildflags_.cmake files. To override flags, the set_special_flags function has been defined, which override flags for a particular build optimisation. set_special_flags(OPT FAST FILES .f90 FLAGS -O2)","title":"Build System"},{"location":"developer/build-system/#the-castep-build-sytem","text":"","title":"The CASTEP Build Sytem"},{"location":"developer/build-system/#introduction","text":"This documentation is intended for developers who intend to add new features/sources to the CASTEP system. A quick-start guide on how to build CASTEP can be found in the CASTEP_ROOT in README.INSTALL for the GNU Make build-system or README.cmake for the new CMake build system. The CASTEP build system is designed to be efficient, but also intuitive. There are two existing build systems, one relying on GNU Make, which is faster to build and intended for rapid development, and one based on CMake which is designed to be more intuitive to those who are used to CMake build systems and for automatically detecting the best options for the average user.","title":"Introduction"},{"location":"developer/build-system/#castep-directory-structure","text":"When adding new sources to CASTEP it is important to consider the hierarchical directory/module structure of CASTEP. CASTEP sources are currently organised into sub-libraries which each depend on the library above them in the hierarchy. These libraries, in order of hierarchy are: Utility Fundamental OTFG Dispersion Functional There are also Tools which are separately built programs which depend on the CASTEP sub-libraries.","title":"CASTEP directory structure"},{"location":"developer/build-system/#gnu-make","text":"The GNU make build system is broken down into a hierarchical tree which build up the required rules for compiling CASTEP on as many varied systems as possible while still being isolated and maintable. The hierarchy of these make files is as follows: \u251c `/` \u2514\u2500\u252c\u2500 `Makefile` - Root Makefile \u251c\u2500 `obj/` \u2514\u2500\u2500\u252c\u2500 `include_rules.mk` \u251c\u2500 `include_utility.mk` \u251c\u2500 `include_fundamental.mk` \u251c\u2500 `include_otfg.mk` \u251c\u2500 `include_dispersion.mk` \u251c\u2500 `include_functional.mk` \u251c\u2500 `include_test.mk` \u251c\u2500 `include_tools.mk` \u251c\u2500 `platforms/` \u2514\u2500\u2500\u2500\u2500 Various make rules for different platforms","title":"GNU Make"},{"location":"developer/build-system/#cmake","text":"The CMake system is designed to be intuitive for those who are used to CMake build systems while still being familiar to those who are used to the CASTEP GNU Make style syntax. This means that many of the CASTEP CMake variables have names which are chosen to match, or are aliased to, the CASTEP GNU Make variables. This is intended to minimise confusion for people who transition from GNU Make to CMake. The CMake system is also intended to expand the capabilities of CASTEP to be able to compile and run efficiently on Windows systems.","title":"CMake"},{"location":"developer/build-system/#adding-new-source-files","text":"In order to add new sources to CASTEP, first it is necessary to work out the relevant dependencies and where they fit into the directory structure (i.e. the CASTEP sub-libraries).","title":"Adding New Source Files"},{"location":"developer/build-system/#adding-to-gnu-make-build-system","text":"Following this the source should be added to the relevant obj/include_.mk SRCS_$(D) . This will automatically include your new source in the CASTEP sub-library.","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-the-cmake-build-system","text":"The next step is to navigate into the sub-library folder which contains your new source and add the source file into the CMakeLists.txt therein.","title":"Adding to the CMake build-system"},{"location":"developer/build-system/#conditional-inclusion","text":"If your source file provides functions which should only conditionally be included in CASTEP (e.g. interfaces to external libraries), then it must provide stub functions (generally no-op s returning relevant arguments) in order that the conditional inclusions can be compiled. These are generally saved as source_name.stub.f90 and these must be conditionally included into the compilation.","title":"Conditional inclusion"},{"location":"developer/build-system/#adding-to-gnu-make-build-system_1","text":"First off, it is important to add a conditional into the relevant obj/include_.mk to include either your stub or your main source into the compilation. obj/include_.mk ifeq (${MY_LIBRARY_VAR},none) SRCS_$(d) := $(SRCS_$(d)) source_name.stub.f90 else SRCS_$(d) := $(SRCS_$(d)) source_name.f90 endif If extra libraries are needed to be conditionally linked these should be added as follows: obj/include_rules.mk ifneq (${MY_LIBRARY_VAR},none) ifneq ($(strip $(MY_LIB_REL_LIB_DIR)), ) CASTEP_LIB_SEARCH_PATH += -L\"../$(MY_LIB_REL_LIB_DIR)\" ifdef SUN CASTEP_LIB_SEARCH_PATH += -R \"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef NAG CASTEP_LIB_SEARCH_PATH += -Wl,-Wl,,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" else ifdef LINUX CASTEP_LIB_SEARCH_PATH += -Wl,-rpath=\"$(abspath ../$(MY_LIB_REL_LIB_DIR))\" endif LIBS += -lmy_extra_lib endif","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-cmake-build-system","text":"The process with the CMake is similar, create a variable which selects either your source or stub based on an option. e.g. CASTEP_ROOT/CMakeLists.txt option(WITH_MY_LIB \"my lib's features\") cmake/extralibs.cmake if(WITH_MY_LIB) set(MY_LIB_MOD source_name.f90) else() set(MY_LIB_MOD source_name.stub.f90) endif() SOURCE_DIR/CMakeLists.txt add_castep_lib(NAME sub_lib SRCS ... ${MY_LIB_MOD} ... ) If extra libraries are needed to be conditionally linked these should be added as follows: cmake/extralibs.cmake if(WITH_MY_LIB) find_library(my_extra_lib NAMES my_extra_lib HINTS ${EXTERNAL_MY_LIB} DOC \"Doc\") if (NOT my_extra_lib) message(FATAL_ERROR \"MY_EXTRA_LIB requested, but not found. Set EXTERNAL_MY_LIB to manually specify location of libraries (currently: '${EXTERNAL_MY_LIB}')\") endif() set(MY_EXTRA_LIB ${my_extra_lib}) set(MY_LIB_MOD source_name.f90) else() set(MY_EXTRA_LIB \"\") set(MY_LIB_MOD source_name.stub.f90) endif() ... mark_as_advanced(... my_extra_lib) SOURCE_DIR/CMakeLists.txt target_link_libraries(sub-lib ... ${MY_EXTRA_LIB})","title":"Adding to CMake build-system"},{"location":"developer/build-system/#special-compilation-options","text":"If you need to add special per-file compilation options, first you should check that your code is properly standards conforming. Failing that, it is possible to override options by setting them up in each platform, however, this is discouraged unless absolutely necessary.","title":"Special Compilation Options"},{"location":"developer/build-system/#adding-to-gnu-make-build-system_2","text":"In the GNU make system it is necessary to add the special compilation flags to each relevant platform under the obj/platforms directory. e.g. obj/platforms/.mk .o: private OPT = -O2","title":"Adding to GNU Make build-system"},{"location":"developer/build-system/#adding-to-cmake-build-system_1","text":"In the CMake build system, flags are set up in the cmake/buildflags_.cmake files. To override flags, the set_special_flags function has been defined, which override flags for a particular build optimisation. set_special_flags(OPT FAST FILES .f90 FLAGS -O2)","title":"Adding to CMake build-system"},{"location":"developer/git_workflow/","text":"Draft bitbucket/git workflow for CASTEP developers: NB: Not a git tutorial! Bitbucket web - create fork (\u201cmyfork\u201d for this example) Make fork visible to CDG (bitbucket group, very least to dominik.jochym@stfc.ac.uk so that the CI works) Clone to local machine git clone git@bitbucket.org:mybitbucket/castep-myfork.git castep-myfork Setup local githook (see readme in .githooks) Configure remote \u201cmyfork\u201d and \u201cupstream\u201d: git remote add upstream git@bitbucket.org:castep/castep.git git remote add myfork git@bitbucket.org:mybitbucket/castep-myfork.git Can verify remotes with git remote -v (useful to have more remote aliases if you want to check out a branch on someone else\u2019s fork) Name branch git branch foo Switch to branch git switch foo (Stage and) Commit changes git commit -m \u201cCool stuff\u201d If planned destination branch (usually default) has changed: Fetch from official git fetch upstream default:default [NB: reference to \u201cupstream\u201d might be different if your remote aliases are configured differently]. This not only performs the fetch but also updates the local \"default\" branch to sync with the upstream. Rebase using destination (default) branch git rebase default . This makes it so that your changes are sitting on top of the latest \u201cofficial\u201d default. If your branch contains many PRs it may be better to \"squash\", using the bitbucket merge option \"squash merge\", or git rebase -i default and then in your editor, leave the first line as 'pick ....' and then change all subsequent lines from 'pick ...' to 'squash ...'. Save the file and then you will get a squashed history for this PR. Fix conflicts if needed git mergetool tool=kdiff3 [kdiff3 is just my personal preference] and then: git rebase --continue (and commit) Push branch to fork ( git push myfork foo ) This is a very good habit to get used to: always specify the remote and branch so you know exactly what you\u2019re trying to push and where! Synchronise your fork\u2019s default branch with upstream: git push myfork default Create pull request (bitbucket web, from fork) \"Delete this branch after merge\" should be checked in most cases. The exception is with long-term development branches and release branches. If another PR is merged first, you have two choices: Do NOT click \u201cSync now\u201d on the PR page as this does a merge and commit, which breaks our --ffonly policy At your local clone, go back to step 9 Similar to step 10, except this is a \u201cforce\u201d push as the rebase has changed the commit history: git push --force myfork foo git push myfork default On the website interface, click \"merge\". Then change the merge strategy to \"Squash\". You will then get an opportunity to edit the commit message. Switch back to the default branch git switch default. Do not do any further work on your foo branch and attempt any merging, or you risk creating a \"spaghetti\" of loops in the commit graph. You may re-use the name of your branch if you delete the old one with git branch -D .","title":"Git workflow"},{"location":"developer/release_procedure/","text":"CASTEP new release procedure Initial setup Open an issue containing this checklist Open bug fix/release branch Cherry pick appropriate bug-fixes from default Update version number in license.F90 Ensure BIOVIA release is tagged Functionality Check OTFG features exposed in cell Check CI Create dedicated pipeline for release branch on ANVIL Run full build tests on Make and CMake Check make dist works -- Including unpacking and building from dist only! Check that cmake -t dist also compiles and includes everything Ensure checkpoints forward & backward compatible Ensure compatibility between Academic and BIOVIA releases Check CASTEP builds and runs on ARCHER2 -- Both GNU and CMake Check GPU build on Tier-1 machines -- Both GNU and CMake Check supported compilers for oldest and latest and update README.install appropriately External Libraries Check linked/included library versions for updates Current libraries: dl_mg simple-dftd3 d4 spglib libxc FoxXML External Tools Checked shipped versions of third-party tools and utilities for updates Current tools: c2x cif2cell optados BoltzTrap SHengBTE emc atat elastic_constants Update emacs_mode keys for most recent keywords Check that version requirement of Python components and utilities are still up to date Documentation Check and update README.install docs Update release notes Update version in Ford Docs Check new parameters (cell and param keywords) New parameters have correct help text New parameters are documented in the manual Licences Update checksums file Upload appropriately to licences.stfc.ac.uk Finalisation Tag final release commit Pre-notify HPC providers of release Notify mailing list of release Update castep.org with latest info Check release branch for build system and documentation updates and back-port to default branch if needed","title":"Release Procedure"},{"location":"developer/release_procedure/#castep-new-release-procedure","text":"","title":"CASTEP new release procedure"},{"location":"developer/release_procedure/#initial-setup","text":"Open an issue containing this checklist Open bug fix/release branch Cherry pick appropriate bug-fixes from default Update version number in license.F90 Ensure BIOVIA release is tagged","title":"Initial setup"},{"location":"developer/release_procedure/#functionality","text":"Check OTFG features exposed in cell Check CI Create dedicated pipeline for release branch on ANVIL Run full build tests on Make and CMake Check make dist works -- Including unpacking and building from dist only! Check that cmake -t dist also compiles and includes everything Ensure checkpoints forward & backward compatible Ensure compatibility between Academic and BIOVIA releases Check CASTEP builds and runs on ARCHER2 -- Both GNU and CMake Check GPU build on Tier-1 machines -- Both GNU and CMake Check supported compilers for oldest and latest and update README.install appropriately","title":"Functionality"},{"location":"developer/release_procedure/#external-libraries","text":"Check linked/included library versions for updates Current libraries: dl_mg simple-dftd3 d4 spglib libxc FoxXML","title":"External Libraries"},{"location":"developer/release_procedure/#external-tools","text":"Checked shipped versions of third-party tools and utilities for updates Current tools: c2x cif2cell optados BoltzTrap SHengBTE emc atat elastic_constants Update emacs_mode keys for most recent keywords Check that version requirement of Python components and utilities are still up to date","title":"External Tools"},{"location":"developer/release_procedure/#documentation","text":"Check and update README.install docs Update release notes Update version in Ford Docs Check new parameters (cell and param keywords) New parameters have correct help text New parameters are documented in the manual","title":"Documentation"},{"location":"developer/release_procedure/#licences","text":"Update checksums file Upload appropriately to licences.stfc.ac.uk","title":"Licences"},{"location":"developer/release_procedure/#finalisation","text":"Tag final release commit Pre-notify HPC providers of release Notify mailing list of release Update castep.org with latest info Check release branch for build system and documentation updates and back-port to default branch if needed","title":"Finalisation"},{"location":"developer/style_guide/","text":"Introduction The CASTEP code has been designed from conception to achieve various goals - including efficiency and maintainability. The following are some simple guidelines on writing code for inclusion within CASTEP. These are intended to enable the writing of correct, efficient code, and to ensure a consistent style for multiple authors throughout the code that is straightforward for others to maintain in the future. Fortran 2003 has been chosen as the language that all the code will be written in, as it has many modern features which enable the writing of clean, modular code without compromising efficiency and portability. In this document, there is a template for writing modules , and for writing subprograms within a module. These templates are designed to enforce good programming practice and documentation of routine function and side-effects. It is important that all routines be written with these templates. The general guidelines about style addressed here, the use of module templates, the completeness of the documentation, etc. all help to make writing new code and maintaining the existing code a simple task. It is also the programmer's responsibility to ensure that each routine is coded as efficiently as possible. Whilst it is tempting to use some of the new built-in features of Fortran 2003, experience has shown that discretion is required in their usage so as not to compromise efficiency. Therefore, guidelines on the use of such features has also been included. CASTEP linter The CASTEP linter is a Python tool which checks your CASTEP build for any issues related to the CASTEP style. It should be used after making any major modifications. Note The linter is also run on the CASTEP CI system and will warn you if any new issues arise from your modifications. Should any new issues be in your PR, it may not be accepted. Using the CASTEP linter The linter is available on PyPI and can be installed on your system using pip : python -m pip install castep-linter Following the install, it should be possible to run the linter by running: castep-lint e.g. castep-lint Source/Functional/pair_pot.f90 For further information, type castep-lint -h It is also possible to use the CASTEP linter in emacs through a flycheck extension . To use this you must install the flycheck package which can be done through the MELPA emacs package repository. Writing to the Specification Document \"It does exactly what it says on the tin\" Obviously, it is of paramount importance to make sure that any routine that you are responsible for does exactly what the specification says that it should do, particularly with regard to exit conditions, side-effects, etc. Routines and variables that are covered by the specification are public whilst other routines and variables are private . The specification says nothing about the r\u00f4le or meaning of private routines. Private routines and variables are only accessible within the module in which they occur. Do not assume anything that is not written in the specification document If the specification does not say that a particular routine will preserve the input values on exit, then you cannot presume that whoever coded it will do likewise! Even if that routine was written by you... Similarly, it may seem obvious that a particular variable has a particular meaning, but if it is not defined in the specification, then it cannot be presumed. Future revisions of the code may change non-specified routines freely. If all code sticks to the specification at all times, then maintaining the code is much simpler. Note that the specification does not say anything about private routines or variables in any module. For this reason, great care must be taken when using such routines. The subprogram template is there to remind you to document all side-effects of each routine! Code robustly for errors That is, the user should never see a Fortran run-time error message - your code should check for possible error conditions, and either correct the error or print a nice, meaningful error message and do a graceful exit via io_abort . Conditions on execution Conditions given in the specification must be true for correct execution of each routine. Obviously, these should be tested for to ensure correctness, but this may introduce a considerable performance penalty, particularly for Utility or Fundamental routines. For this reason, it is recommended to use a single #ifdef debug block at the start of each routine to test these conditions where appropriate and call io_abort as necessary. The code can then be compiled either with or without full error checking as appropriate. Errors and Warnings Use stderr from any node Unlike normal messages, any node can write an error or warning message. Any such message is to be written to stderr from the relevant node. The routine shall then call io_abort to terminate the program neatly. Use iprint consistently Normal output, including warning messages and debugging information, should only by written to stdout by the root node. The level of detail is controlled by the iprint variable: 0 - Minimal output - just the basic parameters controlling the run and the answers! 1 - Default output - breakdown of energies and forces into components, etc. but no debugging output. 2 - Minimal debugging - values of all significant parameters, etc. Not printing all the arrays. 3 - Maximal debugging - the works! Efficiency Issues Libraries The use of BLAS and LAPACK libraries are recommended, as these are freely available libraries and often come in vendor-optimised versions for each platform. For efficiency, it is also recommended that you do not use BLAS \"level 0 routines\" as there are little efficiency gains to be made, and the equivalent fortran is often much neater and easier to read. Fortran array intrinsics Beware the use of fortran array intrinsics - they can be inefficient and may cause memory problems, e.g. result=matmul(a,matmul(b,c)) requires an implicit dynamic memory allocation. Wherever practical use BLAS instead. Some intrinsics may also impede compiler optimisation, particularly on a vector machine. Similarly, do not use functions such as transfer or mold - these can be very inefficient. Passing arrays to subprograms This is a tricky subject, which can easily lead to confusion and inefficient code. The main problem is that there are multiple ways of passing arrays, and these are not in general equivalent! The best practice is to always pass the whole array together with its size, such as: call foo ( int_array , N1 , N2 ) ... subroutine foo ( int_array , N1 , N2 ) implicit none integer , intent ( in ) :: N1 , N2 integer , dimension ( 1 : N1 , 1 : N2 ) :: int_array ... as this does not cause any copying of the array and allows the compiler to do bound-checking etc. The use of assumed-shape arrays , such as int_array(:, :) is less efficient as this has an explicit rank, but an implicit shape. This requires the use of functions such as size(int_array,1) and may prevent certain compiler optimisations. However, it does allow the compiler to do bound-checking. Care must be taken in passing the array though. If an array section is to be passed then it is much better to use assumed-size arrays (i.e. the old fashioned way), that is call foo2 ( int_array ( 1 , N )) ... subroutine foo2 ( int_array ) implicit none integer , dimension ( * ) :: int_array ... than to pass int_array(:, N) and receive int_array(:) as this will create a copy of the array on the stack which will rapidly lead to \"out of memory\" errors. The use of assumed-size arrays, such as int_array(*) is useful if you want to write a general purpose routine that will work with any size and/or rank array. Note however, that it will not in general work with scalars, nor does it allow bounds-checking. However, it does not cause the creation of any copies of the array. Machine-Specific Code Avoid! Write in standard fortran without vendor extensions and without using any system routines wherever possible, for maximum portability. The one exception that is allowed to this is in the Utility modules, where all the low-level input/output and communications are handled. Test thoroughly to prevent Always test your routines on several different platforms and with several different compilers to be sure that you have not inadvertently relied upon some default behaviour of one specific compiler. The CI system will handle compilation for all supported compilers once submitted as a merge request into the Bitbucket repository, but these should be performed beforehand to minimise the effort in bugfixing. File handling One obvious area of machine dependency is that of file handling. For this reason, the io module should be used to handle the opening of all files. The programmer is responsible for reading / writing the data and closing the file. Files are not to be kept open for any longer than strictly necessary. Compiler/preprocessor directives These should be avoided wherever possible as they hinder portability. They should only be used in the Utility modules for machine specific code. All module filenames should be given the extension .f90 , with the exception of Utility modules, where .F90 is permitted, but generally only if preproccesing is used. Fortran90 Features Use of dynamic arrays Each routine is responsible for allocating/using/deallocating its own workspace. We recommend that such allocate / deallocate s only occur once in a routine - never inside a loop as this will produce a significant performance penalty. You must ensure that you always deallocate local work arrays on termination of the routine. Obviously, care needs to be taken if there are multiple exit points from a routine. Pointers Always accept passed arrays in subprograms as arrays and not as pointers. This will force automatic dereferencing of the array and enable better optimisations by the compiler. Flow of control Use of constructs such as select case and do ... end do , with labelling of \"do loops\", etc. is recommended for clarity. Use of cycle and exit is OK - but only use to move a maximum of one level of nesting where possible. Do NOT use goto . Functions A function subprogram should be \"pure\", i.e. generate no side-effects through modification of variables in argument list or module variables through \"use association\". Avoid recursion. Use of use Use modules with an only clause if only a small number of variables required. Put appropriate use statements into each subroutine required, NOT into the module header, in order to keep track of module variable modification. Line numbers Avoid where possible. Line numbers are only to be used for format statements, and end= or err= in file handling. Do not use continue . General features Avoid multiple statement lines unless trivially simple. Modules General All code is to be contained within modules. Usage Each module described in the specification is to be one source file. All routines given in the specification for this module are to be in this file. Auxiliary modules CASTEP also encourages the use of the more recent (Fortran 2008) submodule s. Submodules allow the programmatic subdivision of a module enabling the compiler to precompile interfaces, reduce required compilation if only the submodule has changed and allowing the developer to more effectively control scope of module internals. For clarity, and to keep the module from being excessively long, the module may also use auxiliary modules, which can be in separate files (again with one file per module). Any auxiliary modules must be used in only one specified module, i.e. no auxiliary code reuse in other specified modules as the auxiliary routines are not specified! The naming convention of any auxiliary modules is to be inherited from the specified module to make it clear where the auxiliary routines are to be used, e.g. if the specified module is called me.F90 with routines called me_sub , etc. then an auxiliary module would be me_extra.F90 with routines called me_extra_sub , etc. Note Rather than using full auxilliary modules in modern CASTEP, submodule s are encouraged. Style and Layout Use the module template The module template gives the recommended layout for a module and for a subprogram. This is available in the CASTEP source at Source/template.f90 . In particular, note the layout and contents of the comment header, and the order of declarations. Everything is to be private unless explicitly specified as public! This also makes it simple to check the code against the specification. Layout All code is to use indentation as generated by GNU-Emacs f90-mode. Use any editor you like to create the code, but please ensure that whatever goes into the Bitbucket repository has been passed through Emacs f90-mode indentation at the finished stage. To assist in Emacs usage, the module template contains Emacs directives to set f90-mode, etc. Case Use lower case for keywords and use capitalisation as given in the specification for all routines and variables mentioned therein. For private routines and variables use lower case in general. However, you may use upper case to differentiate words within a name, e.g. userInputData - as long as you are consistent throughout the module. Use upper case, with stripped spaces, for the value of string variables that are passed between routines, e.g. run_type='MOLECULARDYNAMICS' not 'MolecularDynamics ' or 'molecular dynamics' etc. to simplify string comparisons. Names For clarity, don't change variable name on passing to a different routine wherever possible. Avoid short (1 or 2 letter) variable names except for simple loop counters. Use new form end subroutine name etc. not older form end subroutine . Types Do NOT use implicit typing. Similarly, you do not have to stick to the old rules for implicit typing - you can have integer names beginning with \" c \" etc! Do not give type as double precision - use real(kind=dp) instead, as dp is a constant in the Constants module and this will make porting to other architectures (e.g. Cray) much simpler. Remember that all machine-specific code stays in the Utility routines. Similarly, when declaring a constant, use 1.234_dp NOT 1.234d0 . Free format Use free-format f90, with a maximum line length of 132 characters. Spaces Use spaces between keywords e.g. end if not endif . Code cleanly Obviously, to ensure correctness and make it easier for others to maintain the code. If the obvious way to code a routine is inefficient, whilst the efficient way is obscure, then this is allowed as long as the routine is well documented internally, with a discussion as to the design decisions made. Be aware of vectorisation When coding, be aware that the code is almost always executed upon vector architectures. Therefore code with a style that enables good vectorisation - e.g. don't put if statements inside nested loops wherever possible. Documentation Internal Each module, based upon the module template , is to have a header block describing its overall purpose and function. Each routine, written to the template, is to have a header block describing its function, the variables required and how modified, the necessary conditions for correct operation, etc. These comments should be clear and easy to understand. Each routine is also to contain lots of comments within the code. Comments are to be either on the same line(s) as the feature being comment upon, or in a block of lines above the feature. Comment density should be comparable to code density. All comments are to be in English and obey standard rules of English grammar. External A module (or any modifications) is only considered complete when additional documentation has been supplied for inclusion. Documentation must be provided in the appropriate module and function header blocks, explaining the function of the module and each routine, the physics behind the code, the algorithms used, the key variables and data structures, and appropriate references to the literature. Testing Test Program Each module shall be tested for correctness before being added to the Bitbucket repository. To this end a set of tests shall be provided, which must compile and execute correctly in the CI system. The purpose of these tests is to verify the correct operation of every specified routine in the module. CASTEP uses the testcode testing platform which allows automated generation of benchmark data from a set of valid CASTEP input files. Please see Testing for more information on how to do this. Reference data The module test program shall come with both appropriate input datafiles and reference output results. Correct operation of the test shall be verified by comparing the actual output against the reference output results. Module Template General Note particularly the order of declaration, use of implicit none and private , and the standard comment header, for internal documentation. All lines in comment headers are to be 80 characters wide. Not all sections of the header will be relevant to all subprograms and so can be deleted. It is very important that the header is kept up-to-date and as complete as possible. Use of public and private Each module uses an initial private statement to force all entities in the module to be private by default. Then have explicit public statements to expose those datatypes, variables and (overloaded) routine names, as listed in the specification document. This makes it easy to compare the code to the specification document. Template ! -*- mode: F90 ; mode: font-lock ; column-number-mode: true ; vc-back-end: git -*- !=============================================================================! ! D U M M Y ! !=============================================================================! ! Overall explanation of purpose and function of module. ! ! ! !-----------------------------------------------------------------------------! ! Written from \"Module Specification for New Plane Wave Code\", M. Segall, ! ! P. Lindan, M. Probert, C. Pickard, P. Hasnip, S. Clark and M. Payne ! ! Copyright 1999/2000 ! !-----------------------------------------------------------------------------! ! Written by author, version, date ! !-----------------------------------------------------------------------------! ! ! ! ! !=============================================================================! module dummy use constants , only : dp !Minimal useage where practical implicit none !Impose strong typing private !Everything is private ... !---------------------------------------------------------------------------! ! P u b l i c R o u t i n e s ! !---------------------------------------------------------------------------! public :: routine_name ... !... unless exposed here. interface routine_name !Overloaded routines, etc. ... !(specific names are private) end interface !---------------------------------------------------------------------------! ! P u b l i c V a r i a b l e s ! !---------------------------------------------------------------------------! public datatypes ... public variables ... !---------------------------------------------------------------------------! ! P r i v a t e R o u t i n e s ! !---------------------------------------------------------------------------! !---------------------------------------------------------------------------! ! P r i v a t e V a r i a b l e s ! !---------------------------------------------------------------------------! datatypes ... !Private data for all routines variables .. !in this module ... ... contains subroutine public1 ( var1 , var2 ,...) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! !-------------------------------------------------------------------------! ! Arguments: ! ! var1, intent, meaning ! ! ... (in order of call list) ! !-------------------------------------------------------------------------! ! Parent module variables used: ! ! globalvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Modules used: ! ! other_module used, ! ! other_vars, meanings, changes ! ! ... ! !-------------------------------------------------------------------------! ! Key Internal Variables: ! ! intvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Necessary conditions: ! ! ... ! !-------------------------------------------------------------------------! ! Written by author, version, date ! !=========================================================================! use my_module , only : some_other_function use other_module , only : other_var1 implicit none integer , intent ( in ), dimension (:,:) :: var1 !Variables in call order real ( kind = dp ), intent ( in ), parameter :: var2 ... ( other variables in call list ) real ( kind = dp ) :: my_var1 = 2.7182818_dp !base of natural logs complex ( kind = dp ), allocatable , dimension (:) :: my_work1 ... ( other internal variables ) ... ( condition checks ) ... ( actual code ) return end subroutine public1 ... ( other public subroutines ) subroutine private1 (....) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! ! (etc, as for public routines) ! !=========================================================================! .... end subroutine private1 end module dummy","title":"Style Guide"},{"location":"developer/style_guide/#introduction","text":"The CASTEP code has been designed from conception to achieve various goals - including efficiency and maintainability. The following are some simple guidelines on writing code for inclusion within CASTEP. These are intended to enable the writing of correct, efficient code, and to ensure a consistent style for multiple authors throughout the code that is straightforward for others to maintain in the future. Fortran 2003 has been chosen as the language that all the code will be written in, as it has many modern features which enable the writing of clean, modular code without compromising efficiency and portability. In this document, there is a template for writing modules , and for writing subprograms within a module. These templates are designed to enforce good programming practice and documentation of routine function and side-effects. It is important that all routines be written with these templates. The general guidelines about style addressed here, the use of module templates, the completeness of the documentation, etc. all help to make writing new code and maintaining the existing code a simple task. It is also the programmer's responsibility to ensure that each routine is coded as efficiently as possible. Whilst it is tempting to use some of the new built-in features of Fortran 2003, experience has shown that discretion is required in their usage so as not to compromise efficiency. Therefore, guidelines on the use of such features has also been included.","title":"Introduction"},{"location":"developer/style_guide/#castep-linter","text":"The CASTEP linter is a Python tool which checks your CASTEP build for any issues related to the CASTEP style. It should be used after making any major modifications. Note The linter is also run on the CASTEP CI system and will warn you if any new issues arise from your modifications. Should any new issues be in your PR, it may not be accepted.","title":"CASTEP linter"},{"location":"developer/style_guide/#using-the-castep-linter","text":"The linter is available on PyPI and can be installed on your system using pip : python -m pip install castep-linter Following the install, it should be possible to run the linter by running: castep-lint e.g. castep-lint Source/Functional/pair_pot.f90 For further information, type castep-lint -h It is also possible to use the CASTEP linter in emacs through a flycheck extension . To use this you must install the flycheck package which can be done through the MELPA emacs package repository.","title":"Using the CASTEP linter"},{"location":"developer/style_guide/#writing-to-the-specification-document","text":"","title":"Writing to the Specification Document"},{"location":"developer/style_guide/#it-does-exactly-what-it-says-on-the-tin","text":"Obviously, it is of paramount importance to make sure that any routine that you are responsible for does exactly what the specification says that it should do, particularly with regard to exit conditions, side-effects, etc. Routines and variables that are covered by the specification are public whilst other routines and variables are private . The specification says nothing about the r\u00f4le or meaning of private routines. Private routines and variables are only accessible within the module in which they occur.","title":"\"It does exactly what it says on the tin\""},{"location":"developer/style_guide/#do-not-assume-anything-that-is-not-written-in-the-specification-document","text":"If the specification does not say that a particular routine will preserve the input values on exit, then you cannot presume that whoever coded it will do likewise! Even if that routine was written by you... Similarly, it may seem obvious that a particular variable has a particular meaning, but if it is not defined in the specification, then it cannot be presumed. Future revisions of the code may change non-specified routines freely. If all code sticks to the specification at all times, then maintaining the code is much simpler. Note that the specification does not say anything about private routines or variables in any module. For this reason, great care must be taken when using such routines. The subprogram template is there to remind you to document all side-effects of each routine!","title":"Do not assume anything that is not written in the specification document"},{"location":"developer/style_guide/#code-robustly-for-errors","text":"That is, the user should never see a Fortran run-time error message - your code should check for possible error conditions, and either correct the error or print a nice, meaningful error message and do a graceful exit via io_abort .","title":"Code robustly for errors"},{"location":"developer/style_guide/#conditions-on-execution","text":"Conditions given in the specification must be true for correct execution of each routine. Obviously, these should be tested for to ensure correctness, but this may introduce a considerable performance penalty, particularly for Utility or Fundamental routines. For this reason, it is recommended to use a single #ifdef debug block at the start of each routine to test these conditions where appropriate and call io_abort as necessary. The code can then be compiled either with or without full error checking as appropriate.","title":"Conditions on execution"},{"location":"developer/style_guide/#errors-and-warnings","text":"","title":"Errors and Warnings"},{"location":"developer/style_guide/#use-stderr-from-any-node","text":"Unlike normal messages, any node can write an error or warning message. Any such message is to be written to stderr from the relevant node. The routine shall then call io_abort to terminate the program neatly.","title":"Use stderr from any node"},{"location":"developer/style_guide/#use-iprint-consistently","text":"Normal output, including warning messages and debugging information, should only by written to stdout by the root node. The level of detail is controlled by the iprint variable: 0 - Minimal output - just the basic parameters controlling the run and the answers! 1 - Default output - breakdown of energies and forces into components, etc. but no debugging output. 2 - Minimal debugging - values of all significant parameters, etc. Not printing all the arrays. 3 - Maximal debugging - the works!","title":"Use iprint consistently"},{"location":"developer/style_guide/#efficiency-issues","text":"","title":"Efficiency Issues"},{"location":"developer/style_guide/#libraries","text":"The use of BLAS and LAPACK libraries are recommended, as these are freely available libraries and often come in vendor-optimised versions for each platform. For efficiency, it is also recommended that you do not use BLAS \"level 0 routines\" as there are little efficiency gains to be made, and the equivalent fortran is often much neater and easier to read.","title":"Libraries"},{"location":"developer/style_guide/#fortran-array-intrinsics","text":"Beware the use of fortran array intrinsics - they can be inefficient and may cause memory problems, e.g. result=matmul(a,matmul(b,c)) requires an implicit dynamic memory allocation. Wherever practical use BLAS instead. Some intrinsics may also impede compiler optimisation, particularly on a vector machine. Similarly, do not use functions such as transfer or mold - these can be very inefficient.","title":"Fortran array intrinsics"},{"location":"developer/style_guide/#passing-arrays-to-subprograms","text":"This is a tricky subject, which can easily lead to confusion and inefficient code. The main problem is that there are multiple ways of passing arrays, and these are not in general equivalent! The best practice is to always pass the whole array together with its size, such as: call foo ( int_array , N1 , N2 ) ... subroutine foo ( int_array , N1 , N2 ) implicit none integer , intent ( in ) :: N1 , N2 integer , dimension ( 1 : N1 , 1 : N2 ) :: int_array ... as this does not cause any copying of the array and allows the compiler to do bound-checking etc. The use of assumed-shape arrays , such as int_array(:, :) is less efficient as this has an explicit rank, but an implicit shape. This requires the use of functions such as size(int_array,1) and may prevent certain compiler optimisations. However, it does allow the compiler to do bound-checking. Care must be taken in passing the array though. If an array section is to be passed then it is much better to use assumed-size arrays (i.e. the old fashioned way), that is call foo2 ( int_array ( 1 , N )) ... subroutine foo2 ( int_array ) implicit none integer , dimension ( * ) :: int_array ... than to pass int_array(:, N) and receive int_array(:) as this will create a copy of the array on the stack which will rapidly lead to \"out of memory\" errors. The use of assumed-size arrays, such as int_array(*) is useful if you want to write a general purpose routine that will work with any size and/or rank array. Note however, that it will not in general work with scalars, nor does it allow bounds-checking. However, it does not cause the creation of any copies of the array.","title":"Passing arrays to subprograms"},{"location":"developer/style_guide/#machine-specific-code","text":"","title":"Machine-Specific Code"},{"location":"developer/style_guide/#avoid","text":"Write in standard fortran without vendor extensions and without using any system routines wherever possible, for maximum portability. The one exception that is allowed to this is in the Utility modules, where all the low-level input/output and communications are handled.","title":"Avoid!"},{"location":"developer/style_guide/#test-thoroughly-to-prevent","text":"Always test your routines on several different platforms and with several different compilers to be sure that you have not inadvertently relied upon some default behaviour of one specific compiler. The CI system will handle compilation for all supported compilers once submitted as a merge request into the Bitbucket repository, but these should be performed beforehand to minimise the effort in bugfixing.","title":"Test thoroughly to prevent"},{"location":"developer/style_guide/#file-handling","text":"One obvious area of machine dependency is that of file handling. For this reason, the io module should be used to handle the opening of all files. The programmer is responsible for reading / writing the data and closing the file. Files are not to be kept open for any longer than strictly necessary.","title":"File handling"},{"location":"developer/style_guide/#compilerpreprocessor-directives","text":"These should be avoided wherever possible as they hinder portability. They should only be used in the Utility modules for machine specific code. All module filenames should be given the extension .f90 , with the exception of Utility modules, where .F90 is permitted, but generally only if preproccesing is used.","title":"Compiler/preprocessor directives"},{"location":"developer/style_guide/#fortran90-features","text":"","title":"Fortran90 Features"},{"location":"developer/style_guide/#use-of-dynamic-arrays","text":"Each routine is responsible for allocating/using/deallocating its own workspace. We recommend that such allocate / deallocate s only occur once in a routine - never inside a loop as this will produce a significant performance penalty. You must ensure that you always deallocate local work arrays on termination of the routine. Obviously, care needs to be taken if there are multiple exit points from a routine.","title":"Use of dynamic arrays"},{"location":"developer/style_guide/#pointers","text":"Always accept passed arrays in subprograms as arrays and not as pointers. This will force automatic dereferencing of the array and enable better optimisations by the compiler.","title":"Pointers"},{"location":"developer/style_guide/#flow-of-control","text":"Use of constructs such as select case and do ... end do , with labelling of \"do loops\", etc. is recommended for clarity. Use of cycle and exit is OK - but only use to move a maximum of one level of nesting where possible. Do NOT use goto .","title":"Flow of control"},{"location":"developer/style_guide/#functions","text":"A function subprogram should be \"pure\", i.e. generate no side-effects through modification of variables in argument list or module variables through \"use association\". Avoid recursion.","title":"Functions"},{"location":"developer/style_guide/#use-of-use","text":"Use modules with an only clause if only a small number of variables required. Put appropriate use statements into each subroutine required, NOT into the module header, in order to keep track of module variable modification.","title":"Use of use"},{"location":"developer/style_guide/#line-numbers","text":"Avoid where possible. Line numbers are only to be used for format statements, and end= or err= in file handling. Do not use continue .","title":"Line numbers"},{"location":"developer/style_guide/#general-features","text":"Avoid multiple statement lines unless trivially simple.","title":"General features"},{"location":"developer/style_guide/#modules","text":"","title":"Modules"},{"location":"developer/style_guide/#general","text":"All code is to be contained within modules.","title":"General"},{"location":"developer/style_guide/#usage","text":"Each module described in the specification is to be one source file. All routines given in the specification for this module are to be in this file.","title":"Usage"},{"location":"developer/style_guide/#auxiliary-modules","text":"CASTEP also encourages the use of the more recent (Fortran 2008) submodule s. Submodules allow the programmatic subdivision of a module enabling the compiler to precompile interfaces, reduce required compilation if only the submodule has changed and allowing the developer to more effectively control scope of module internals. For clarity, and to keep the module from being excessively long, the module may also use auxiliary modules, which can be in separate files (again with one file per module). Any auxiliary modules must be used in only one specified module, i.e. no auxiliary code reuse in other specified modules as the auxiliary routines are not specified! The naming convention of any auxiliary modules is to be inherited from the specified module to make it clear where the auxiliary routines are to be used, e.g. if the specified module is called me.F90 with routines called me_sub , etc. then an auxiliary module would be me_extra.F90 with routines called me_extra_sub , etc. Note Rather than using full auxilliary modules in modern CASTEP, submodule s are encouraged.","title":"Auxiliary modules"},{"location":"developer/style_guide/#style-and-layout","text":"","title":"Style and Layout"},{"location":"developer/style_guide/#use-the-module-template","text":"The module template gives the recommended layout for a module and for a subprogram. This is available in the CASTEP source at Source/template.f90 . In particular, note the layout and contents of the comment header, and the order of declarations. Everything is to be private unless explicitly specified as public! This also makes it simple to check the code against the specification.","title":"Use the module template"},{"location":"developer/style_guide/#layout","text":"All code is to use indentation as generated by GNU-Emacs f90-mode. Use any editor you like to create the code, but please ensure that whatever goes into the Bitbucket repository has been passed through Emacs f90-mode indentation at the finished stage. To assist in Emacs usage, the module template contains Emacs directives to set f90-mode, etc.","title":"Layout"},{"location":"developer/style_guide/#case","text":"Use lower case for keywords and use capitalisation as given in the specification for all routines and variables mentioned therein. For private routines and variables use lower case in general. However, you may use upper case to differentiate words within a name, e.g. userInputData - as long as you are consistent throughout the module. Use upper case, with stripped spaces, for the value of string variables that are passed between routines, e.g. run_type='MOLECULARDYNAMICS' not 'MolecularDynamics ' or 'molecular dynamics' etc. to simplify string comparisons.","title":"Case"},{"location":"developer/style_guide/#names","text":"For clarity, don't change variable name on passing to a different routine wherever possible. Avoid short (1 or 2 letter) variable names except for simple loop counters. Use new form end subroutine name etc. not older form end subroutine .","title":"Names"},{"location":"developer/style_guide/#types","text":"Do NOT use implicit typing. Similarly, you do not have to stick to the old rules for implicit typing - you can have integer names beginning with \" c \" etc! Do not give type as double precision - use real(kind=dp) instead, as dp is a constant in the Constants module and this will make porting to other architectures (e.g. Cray) much simpler. Remember that all machine-specific code stays in the Utility routines. Similarly, when declaring a constant, use 1.234_dp NOT 1.234d0 .","title":"Types"},{"location":"developer/style_guide/#free-format","text":"Use free-format f90, with a maximum line length of 132 characters.","title":"Free format"},{"location":"developer/style_guide/#spaces","text":"Use spaces between keywords e.g. end if not endif .","title":"Spaces"},{"location":"developer/style_guide/#code-cleanly","text":"Obviously, to ensure correctness and make it easier for others to maintain the code. If the obvious way to code a routine is inefficient, whilst the efficient way is obscure, then this is allowed as long as the routine is well documented internally, with a discussion as to the design decisions made.","title":"Code cleanly"},{"location":"developer/style_guide/#be-aware-of-vectorisation","text":"When coding, be aware that the code is almost always executed upon vector architectures. Therefore code with a style that enables good vectorisation - e.g. don't put if statements inside nested loops wherever possible.","title":"Be aware of vectorisation"},{"location":"developer/style_guide/#documentation","text":"","title":"Documentation"},{"location":"developer/style_guide/#internal","text":"Each module, based upon the module template , is to have a header block describing its overall purpose and function. Each routine, written to the template, is to have a header block describing its function, the variables required and how modified, the necessary conditions for correct operation, etc. These comments should be clear and easy to understand. Each routine is also to contain lots of comments within the code. Comments are to be either on the same line(s) as the feature being comment upon, or in a block of lines above the feature. Comment density should be comparable to code density. All comments are to be in English and obey standard rules of English grammar.","title":"Internal"},{"location":"developer/style_guide/#external","text":"A module (or any modifications) is only considered complete when additional documentation has been supplied for inclusion. Documentation must be provided in the appropriate module and function header blocks, explaining the function of the module and each routine, the physics behind the code, the algorithms used, the key variables and data structures, and appropriate references to the literature.","title":"External"},{"location":"developer/style_guide/#testing","text":"","title":"Testing"},{"location":"developer/style_guide/#test-program","text":"Each module shall be tested for correctness before being added to the Bitbucket repository. To this end a set of tests shall be provided, which must compile and execute correctly in the CI system. The purpose of these tests is to verify the correct operation of every specified routine in the module. CASTEP uses the testcode testing platform which allows automated generation of benchmark data from a set of valid CASTEP input files. Please see Testing for more information on how to do this.","title":"Test Program"},{"location":"developer/style_guide/#reference-data","text":"The module test program shall come with both appropriate input datafiles and reference output results. Correct operation of the test shall be verified by comparing the actual output against the reference output results.","title":"Reference data"},{"location":"developer/style_guide/#module-template","text":"","title":"Module Template"},{"location":"developer/style_guide/#general_1","text":"Note particularly the order of declaration, use of implicit none and private , and the standard comment header, for internal documentation. All lines in comment headers are to be 80 characters wide. Not all sections of the header will be relevant to all subprograms and so can be deleted. It is very important that the header is kept up-to-date and as complete as possible.","title":"General"},{"location":"developer/style_guide/#use-of-public-and-private","text":"Each module uses an initial private statement to force all entities in the module to be private by default. Then have explicit public statements to expose those datatypes, variables and (overloaded) routine names, as listed in the specification document. This makes it easy to compare the code to the specification document.","title":"Use of public and private"},{"location":"developer/style_guide/#template","text":"! -*- mode: F90 ; mode: font-lock ; column-number-mode: true ; vc-back-end: git -*- !=============================================================================! ! D U M M Y ! !=============================================================================! ! Overall explanation of purpose and function of module. ! ! ! !-----------------------------------------------------------------------------! ! Written from \"Module Specification for New Plane Wave Code\", M. Segall, ! ! P. Lindan, M. Probert, C. Pickard, P. Hasnip, S. Clark and M. Payne ! ! Copyright 1999/2000 ! !-----------------------------------------------------------------------------! ! Written by author, version, date ! !-----------------------------------------------------------------------------! ! ! ! ! !=============================================================================! module dummy use constants , only : dp !Minimal useage where practical implicit none !Impose strong typing private !Everything is private ... !---------------------------------------------------------------------------! ! P u b l i c R o u t i n e s ! !---------------------------------------------------------------------------! public :: routine_name ... !... unless exposed here. interface routine_name !Overloaded routines, etc. ... !(specific names are private) end interface !---------------------------------------------------------------------------! ! P u b l i c V a r i a b l e s ! !---------------------------------------------------------------------------! public datatypes ... public variables ... !---------------------------------------------------------------------------! ! P r i v a t e R o u t i n e s ! !---------------------------------------------------------------------------! !---------------------------------------------------------------------------! ! P r i v a t e V a r i a b l e s ! !---------------------------------------------------------------------------! datatypes ... !Private data for all routines variables .. !in this module ... ... contains subroutine public1 ( var1 , var2 ,...) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! !-------------------------------------------------------------------------! ! Arguments: ! ! var1, intent, meaning ! ! ... (in order of call list) ! !-------------------------------------------------------------------------! ! Parent module variables used: ! ! globalvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Modules used: ! ! other_module used, ! ! other_vars, meanings, changes ! ! ... ! !-------------------------------------------------------------------------! ! Key Internal Variables: ! ! intvar1, meaning ! ! ... ! !-------------------------------------------------------------------------! ! Necessary conditions: ! ! ... ! !-------------------------------------------------------------------------! ! Written by author, version, date ! !=========================================================================! use my_module , only : some_other_function use other_module , only : other_var1 implicit none integer , intent ( in ), dimension (:,:) :: var1 !Variables in call order real ( kind = dp ), intent ( in ), parameter :: var2 ... ( other variables in call list ) real ( kind = dp ) :: my_var1 = 2.7182818_dp !base of natural logs complex ( kind = dp ), allocatable , dimension (:) :: my_work1 ... ( other internal variables ) ... ( condition checks ) ... ( actual code ) return end subroutine public1 ... ( other public subroutines ) subroutine private1 (....) !=========================================================================! ! Explanation of purpose of routine ! ! ... ! ! (etc, as for public routines) ! !=========================================================================! .... end subroutine private1 end module dummy","title":"Template"},{"location":"developer/using_devel_codes/","text":"Using Devel Codes This document is intended to describe the use of devel codes for developers to speed up implementation of experimental parameters. What are devel codes Devel codes are handy tools for developers to control features while they are not ready for public release. Devel codes are read from the devel_code block of the .param file. Devel codes are much simpler to use than keywords, however they do not have the rigorous type/value checking or unit conversion that keywords do. Nor are they searchable and do not provide any help. In order to use devel codes you have to explicitly know how to call them, the values they should take and what they do. The devel code block is an arbitrary string which can be used to provide parameters to a function, however, the devel code block also has several useful standard structural elements to make it more useful than just a string one has to parse themselves. Using devel codes Devel code sub-blocks Devel codes are divided into sub-blocks which are usually named related to the module or functions they support. Examples include: MD - Relating to molecular dynamics options FIRE - Relating to the FIRE geometry optimisation method ELECTRONIC - Relating to electronic minimisation However they can be anything the developer wants. Note While in principle block names are general and arbitrary, keeping them related to the module where they are used or their functionality is useful for remembering how to call them. Another use of blocks is to have a block dedicated to a particular algorithm or as a structured block in the style of .cell style blocks (i.e. %block ... %endblock ) ready for integration into the main parameters when the feature is complete. The structure of a sub-block in the .param file (here XYZ ) is as follows: %block devel_code XYZ: param=3 :ENDXYZ %endblock devel_code Extracting devel codes The devel code block is converted upon reading the param file into parameters :: current_params%devel_code . This block can then be parsed using the following functions: io :: io_code_present(code, key, block) Check whether a particular parameter key is present in block block . If block is not given check the top-level devel-code. io :: io_code_block(code, block) Return the entire block block as a character array allowing you to manually process the data. Most useful for situations where the final parameter will be a block of data. io :: io_code_logical(code, key, block) Parse given parameter key in block block as a logical according to list-directed Fortran logical rules. io :: io_code_integer(code, key, block) Parse given parameter key in block block as an integer according to list-directed Fortran integer rules. io :: io_code_real(code, key, block) Parse given parameter key in block block as an real according to list-directed Fortran real rules. io :: io_code_complex(code, key, block) Parse given parameter key in block block as an complex according to list-directed Fortran complex rules. io :: io_code_string(code, key, block) Parse given parameter key in block block as a character string. Example For a devel_code block that looks like: %block devel_code mod_param=17 XYZ: param=3 :ENDXYZ %endblock devel_code The usual procedure for processing a devel code argument is as follows: module my_module ... ! Can read into module parameters if necessary integer :: module_param ... function use_devel_code () ! Ensure the devel_codes are available use parameters , only : current_params ! Ensure we can parse the devel-codes use io , only : io_code_present , io_code_integer ! Have the param available integer :: param ! Check that we're the master process for reading the strings if ( on_root_node ) then ! Check if the devel code has been set if ( io_code_present ( current_params % devel_code , 'param' , 'XYZ' )) & ! Read and parse the parameter for use & param = io_code_integer ( current_params % devel_code , 'param' , 'XYZ' ) !Since it's top-level we parse it without passing the block. if ( io_code_present ( current_params % devel_code , 'mod_param' )) & & module_param = io_code_integer ( current_params % devel_code , 'mod_param' ) endif ! Distribute the parameters to all nodes call comms_gcopy ( param , 1 ) ...","title":"Using Devel Codes"},{"location":"developer/using_devel_codes/#using-devel-codes","text":"This document is intended to describe the use of devel codes for developers to speed up implementation of experimental parameters.","title":"Using Devel Codes"},{"location":"developer/using_devel_codes/#what-are-devel-codes","text":"Devel codes are handy tools for developers to control features while they are not ready for public release. Devel codes are read from the devel_code block of the .param file. Devel codes are much simpler to use than keywords, however they do not have the rigorous type/value checking or unit conversion that keywords do. Nor are they searchable and do not provide any help. In order to use devel codes you have to explicitly know how to call them, the values they should take and what they do. The devel code block is an arbitrary string which can be used to provide parameters to a function, however, the devel code block also has several useful standard structural elements to make it more useful than just a string one has to parse themselves.","title":"What are devel codes"},{"location":"developer/using_devel_codes/#using-devel-codes_1","text":"","title":"Using devel codes"},{"location":"developer/using_devel_codes/#devel-code-sub-blocks","text":"Devel codes are divided into sub-blocks which are usually named related to the module or functions they support. Examples include: MD - Relating to molecular dynamics options FIRE - Relating to the FIRE geometry optimisation method ELECTRONIC - Relating to electronic minimisation However they can be anything the developer wants. Note While in principle block names are general and arbitrary, keeping them related to the module where they are used or their functionality is useful for remembering how to call them. Another use of blocks is to have a block dedicated to a particular algorithm or as a structured block in the style of .cell style blocks (i.e. %block ... %endblock ) ready for integration into the main parameters when the feature is complete. The structure of a sub-block in the .param file (here XYZ ) is as follows: %block devel_code XYZ: param=3 :ENDXYZ %endblock devel_code","title":"Devel code sub-blocks"},{"location":"developer/using_devel_codes/#extracting-devel-codes","text":"The devel code block is converted upon reading the param file into parameters :: current_params%devel_code . This block can then be parsed using the following functions: io :: io_code_present(code, key, block) Check whether a particular parameter key is present in block block . If block is not given check the top-level devel-code. io :: io_code_block(code, block) Return the entire block block as a character array allowing you to manually process the data. Most useful for situations where the final parameter will be a block of data. io :: io_code_logical(code, key, block) Parse given parameter key in block block as a logical according to list-directed Fortran logical rules. io :: io_code_integer(code, key, block) Parse given parameter key in block block as an integer according to list-directed Fortran integer rules. io :: io_code_real(code, key, block) Parse given parameter key in block block as an real according to list-directed Fortran real rules. io :: io_code_complex(code, key, block) Parse given parameter key in block block as an complex according to list-directed Fortran complex rules. io :: io_code_string(code, key, block) Parse given parameter key in block block as a character string.","title":"Extracting devel codes"},{"location":"developer/using_devel_codes/#example","text":"For a devel_code block that looks like: %block devel_code mod_param=17 XYZ: param=3 :ENDXYZ %endblock devel_code The usual procedure for processing a devel code argument is as follows: module my_module ... ! Can read into module parameters if necessary integer :: module_param ... function use_devel_code () ! Ensure the devel_codes are available use parameters , only : current_params ! Ensure we can parse the devel-codes use io , only : io_code_present , io_code_integer ! Have the param available integer :: param ! Check that we're the master process for reading the strings if ( on_root_node ) then ! Check if the devel code has been set if ( io_code_present ( current_params % devel_code , 'param' , 'XYZ' )) & ! Read and parse the parameter for use & param = io_code_integer ( current_params % devel_code , 'param' , 'XYZ' ) !Since it's top-level we parse it without passing the block. if ( io_code_present ( current_params % devel_code , 'mod_param' )) & & module_param = io_code_integer ( current_params % devel_code , 'mod_param' ) endif ! Distribute the parameters to all nodes call comms_gcopy ( param , 1 ) ...","title":"Example"},{"location":"developer/using_trace/","text":"Using the trace module The trace module provides functionality useful to developers for debugging and profiling particular sections of castep. It is common practice to put calls to trace_entry and trace_exit at the beginning and end of function calls in castep, but the reasoning why may be unclear. The primary reason for most users is that when castep performs an io_abort , it first calls into trace on each process to dump the current trace stack to the ..err files. This is the main error message people see when castep fails. This document sets out to explain in more detail, the usage of the trace module and how and why it benefits developers. The trace module Tracing code Trace Blocks The trace module provides a number of functions which are helpful in debugging and profiling code. The key functions in trace for general usage are trace_entry and trace_exit which should be used in all major functions. This makes it so the subprogram is logged in tracing. Note The trace_entry and trace_exit routines do have an associated cost, and therefore for short routines called very frequently (e.g. functions in loops) it can be a bad idea for performance to trace these routines. The syntax for trace_entry is: call trace_entry ( block_name , success [, profile ][, class ]) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. profile - logical, intent(in) - whether to profile this block class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Note trace_entry and trace_exit subroutines can be called around any arbitrary blocks of code. This makes it possible to narrow down failing points, but not only that, they can be used to profile sections of code where performance is falling below expectations. Trace Sections It is possible to mark a section of a code as a sub-element of a trace-block rather than a block in its own right. These can also have extra arguments passed through to log parameters at certain stages. The syntax for trace_section is: call trace_section_entry ( section_name [, variable_name , value ], success [, class ]) Where: section_name - character, intent(in) - is the name of the entry in the trace. variable_name - character, intent(in) - is the logging name to be attached to the section in the trace output value - integer|character, intent(in) - is the current value of the variable to be logged. value can either be an integer or character(len=63) success - integer, intent(out) - is the return status of the function, 0 if successful. class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_section_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Debugging The trace stack is built up from the trace_entry and trace_exit routines which keep track of where the code is currently executing. This is why it is recommended that all major routines (where possible, see note above) begin and end with a trace_entry , trace_exit . Tracing can also be used to dump information to a logging file whenever a trace_entry / trace_exit call is hit. This is done using: call trace_set_debug (. true .) It is then possible to check within a module whether trace debugging is on using: if ( trace_debug_is_on ()) then ... end if Profiling Trace also provides profiling functionality timing the duration between any entry & exit . Timing can be enabled through setting the relevant prof or profclass devel codes to true ( see: below ). It is also possible to enable profiling globally using: class trace_set_profile (. true .) And subsequently disable it in a similar way: class trace_set_profile (. false .) The trace module tracks a number of useful profiling factors including time spent in function, call counts, and time per call. Devel Codes The trace module has several functions which can be enabled by devel codes. Global FULL_TRACE - logical - Enable full profiling for all modules including the trace module itself. TRACE - logical - Enable automated dumping of function calls to the profiling filed PROF block Enables timing for the castep. # Prints profiling information for the whole run # i.e. how long is spent in each subroutine. %block devel_code PROF: * :ENDPROF %endblock devel_code PROFCLASS Block List of \"classes\" to be matched against trace classes (see: trace_entry ), to enable profiling for certain groups of operations. %block devel_code PROFCLASS:FFT ORTHOGONALISATION:ENDPROFCLASS %endblock devel_code will print a table of the total time spent in routines labelled with a particular class. This will produce an output like: Class of operation Time spent FFT 1.41s ORTHOGONALISATION 0.05s Note For PROF::ENDPROF and PROFCLASS::ENDPROFCLASS there must be no whitespace in the devel_code before or after the colon (:) character, i.e PROF:wave:ENDPROF and not PROF: wave :ENDPROF Dumping info It is possible to dump the info in the tracing at any time. In order to get all information including timings, calls, etc. you can call trace_output as follows: call trace_output ( out_unit , success , order ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. order - character, intent(in) - Order in which to dump trace, must be one of: L - Order they were (first) added to trace. T - Descending order of total time spent in function. C - Descending order of number of calls. P - Descenging order of time per call. It is also possible to quickly dump the current trace call stack. This is done as follows: call trace_log_output ( out_unit , success ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. Output format If any of the TRACE , FULL_TRACE or PROF devel_codes are present, or a call is made to trace_output , CASTEP writes a table of calls to each subroutine in (something similar to) the following format: +------------------------------------------------------------ | o-- list of parent routines | / | O->name of subroutine | / | --o-> list of child routines +------------------------------------------------------------ The list of parent routines has information on the number of calls this parent routine calls this current routine. The subroutine of interest has information on how many times in total it was called. The list of child routines has a list of how many times a particular child routine was called from the subroutine of interest. If profiling is on, for all or some of the routines, there is an additional column for number of times the routine was profiled and a total time spent in each routine. Logging Files By default, CASTEP creates ..profile files to log trace information.","title":"Using trace"},{"location":"developer/using_trace/#using-the-trace-module","text":"The trace module provides functionality useful to developers for debugging and profiling particular sections of castep. It is common practice to put calls to trace_entry and trace_exit at the beginning and end of function calls in castep, but the reasoning why may be unclear. The primary reason for most users is that when castep performs an io_abort , it first calls into trace on each process to dump the current trace stack to the ..err files. This is the main error message people see when castep fails. This document sets out to explain in more detail, the usage of the trace module and how and why it benefits developers.","title":"Using the trace module"},{"location":"developer/using_trace/#the-trace-module","text":"","title":"The trace module"},{"location":"developer/using_trace/#tracing-code","text":"","title":"Tracing code"},{"location":"developer/using_trace/#trace-blocks","text":"The trace module provides a number of functions which are helpful in debugging and profiling code. The key functions in trace for general usage are trace_entry and trace_exit which should be used in all major functions. This makes it so the subprogram is logged in tracing. Note The trace_entry and trace_exit routines do have an associated cost, and therefore for short routines called very frequently (e.g. functions in loops) it can be a bad idea for performance to trace these routines. The syntax for trace_entry is: call trace_entry ( block_name , success [, profile ][, class ]) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. profile - logical, intent(in) - whether to profile this block class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful. Note trace_entry and trace_exit subroutines can be called around any arbitrary blocks of code. This makes it possible to narrow down failing points, but not only that, they can be used to profile sections of code where performance is falling below expectations.","title":"Trace Blocks"},{"location":"developer/using_trace/#trace-sections","text":"It is possible to mark a section of a code as a sub-element of a trace-block rather than a block in its own right. These can also have extra arguments passed through to log parameters at certain stages. The syntax for trace_section is: call trace_section_entry ( section_name [, variable_name , value ], success [, class ]) Where: section_name - character, intent(in) - is the name of the entry in the trace. variable_name - character, intent(in) - is the logging name to be attached to the section in the trace output value - integer|character, intent(in) - is the current value of the variable to be logged. value can either be an integer or character(len=63) success - integer, intent(out) - is the return status of the function, 0 if successful. class - character, intent(in) - is the profile class for the purposes of profclass enabling profiling. The syntax for trace_exit is: call trace_section_exit ( block_name , success ) Where: block_name - character, intent(in) - is the name of the entry in the trace. success - integer, intent(out) - is the return status of the function, 0 if successful.","title":"Trace Sections"},{"location":"developer/using_trace/#debugging","text":"The trace stack is built up from the trace_entry and trace_exit routines which keep track of where the code is currently executing. This is why it is recommended that all major routines (where possible, see note above) begin and end with a trace_entry , trace_exit . Tracing can also be used to dump information to a logging file whenever a trace_entry / trace_exit call is hit. This is done using: call trace_set_debug (. true .) It is then possible to check within a module whether trace debugging is on using: if ( trace_debug_is_on ()) then ... end if","title":"Debugging"},{"location":"developer/using_trace/#profiling","text":"Trace also provides profiling functionality timing the duration between any entry & exit . Timing can be enabled through setting the relevant prof or profclass devel codes to true ( see: below ). It is also possible to enable profiling globally using: class trace_set_profile (. true .) And subsequently disable it in a similar way: class trace_set_profile (. false .) The trace module tracks a number of useful profiling factors including time spent in function, call counts, and time per call.","title":"Profiling"},{"location":"developer/using_trace/#devel-codes","text":"The trace module has several functions which can be enabled by devel codes.","title":"Devel Codes"},{"location":"developer/using_trace/#global","text":"FULL_TRACE - logical - Enable full profiling for all modules including the trace module itself. TRACE - logical - Enable automated dumping of function calls to the profiling filed","title":"Global"},{"location":"developer/using_trace/#prof-block","text":"Enables timing for the castep. # Prints profiling information for the whole run # i.e. how long is spent in each subroutine. %block devel_code PROF: * :ENDPROF %endblock devel_code","title":"PROF block"},{"location":"developer/using_trace/#profclass-block","text":"List of \"classes\" to be matched against trace classes (see: trace_entry ), to enable profiling for certain groups of operations. %block devel_code PROFCLASS:FFT ORTHOGONALISATION:ENDPROFCLASS %endblock devel_code will print a table of the total time spent in routines labelled with a particular class. This will produce an output like: Class of operation Time spent FFT 1.41s ORTHOGONALISATION 0.05s Note For PROF::ENDPROF and PROFCLASS::ENDPROFCLASS there must be no whitespace in the devel_code before or after the colon (:) character, i.e PROF:wave:ENDPROF and not PROF: wave :ENDPROF","title":"PROFCLASS Block"},{"location":"developer/using_trace/#dumping-info","text":"It is possible to dump the info in the tracing at any time. In order to get all information including timings, calls, etc. you can call trace_output as follows: call trace_output ( out_unit , success , order ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful. order - character, intent(in) - Order in which to dump trace, must be one of: L - Order they were (first) added to trace. T - Descending order of total time spent in function. C - Descending order of number of calls. P - Descenging order of time per call. It is also possible to quickly dump the current trace call stack. This is done as follows: call trace_log_output ( out_unit , success ) Where: out_unit - integer, intent(in) - Fortran file unit to write to success - integer, intent(out) - is the return status of the function, 0 if successful.","title":"Dumping info"},{"location":"developer/using_trace/#output-format","text":"If any of the TRACE , FULL_TRACE or PROF devel_codes are present, or a call is made to trace_output , CASTEP writes a table of calls to each subroutine in (something similar to) the following format: +------------------------------------------------------------ | o-- list of parent routines | / | O->name of subroutine | / | --o-> list of child routines +------------------------------------------------------------ The list of parent routines has information on the number of calls this parent routine calls this current routine. The subroutine of interest has information on how many times in total it was called. The list of child routines has a list of how many times a particular child routine was called from the subroutine of interest. If profiling is on, for all or some of the routines, there is an additional column for number of times the routine was profiled and a total time spent in each routine.","title":"Output format"},{"location":"developer/using_trace/#logging-files","text":"By default, CASTEP creates ..profile files to log trace information.","title":"Logging Files"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/","text":"Linear expansion DeltaSCF DFT calculations - Constraining projected reference orbitals Basics For molecules adsorbed at surfaces, \\Delta \\Delta SCF calculations become challenging, simply because of the large number of states. Not only is it difficult to identify the correct state, often hybridization spreads adsorbate molecular orbitals across a large number of substrate bands. A more realistic excitation constraint would be to project on a gasphase molecular orbital and subsequently enforce occupation of this state. This idea is referred to as linear expansion \\Delta \\Delta SCF and has first been proposed by Gavnholt et al 1 . The CASTEP implementation is described in Maurer and Reuer (2013) 2 . Herein, we constrain the occupation of a so-called resonance state built from a linear combination of Kohn-Sham states instead of a single KS state. We expand an abitrary reference state |\\phi_c\\rangle |\\phi_c\\rangle in the space of Kohn-Sham states as follows: |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle At the same time we orthogonalize the remaining KS states |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle After an additional orthonormalization of all states we have constructed a resonance state \\tilde{\\psi_c^{\\mathbf{k}}} \\tilde{\\psi_c^{\\mathbf{k}}} and removed all its contributions from all other states. We can now constrain the occupation of this state with the effect of describing an excitation of a specific molecular orbital. This is done in every SCF step until the calculation is converged. For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_overlap_cutoff Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : linear expansion deltascf_overlap_cutoff : 0.01 #band occ spin %block deltascf_constraints 35 1.0000 1 %endblock deltascf_constraints In this example, we take state 35 from wavefunction file .check and enforce an occupation of 1.00 electrons. In this runmode we do not have to pick constraints that yield a net change in charge equal to 0. Charge neutrality will be satisfied by modifying the Fermi level accordingly. However, this is only strictly sensible for metallic systems. Jeppe Gavnholt, Thomas Olsen, Mads Engelund, and Jakob Schi\u00f8tz. \u0394 self-consistent field method to obtain potential energy surfaces of excited molecules on surfaces. Phys. Rev. B , 78:075441, Aug 2008. doi:10.1103/PhysRevB.78.075441 . \u21a9 Reinhard J. Maurer and Karsten Reuter. Excited-state potential-energy surfaces of metal-adsorbed organic molecules from linear expansion \u0394-self-consistent field density-functional theory (\u0394SCF-DFT). The Journal of Chemical Physics , 139(1):014708, 07 2013. doi:10.1063/1.4812398 . \u21a9","title":"Linear expansion DeltaSCF"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/#linear-expansion-deltascf-dft-calculations-constraining-projected-reference-orbitals","text":"","title":"Linear expansion DeltaSCF DFT calculations - Constraining projected reference orbitals"},{"location":"documentation/Delta_SCF/lin_ex_delta_scf/#basics","text":"For molecules adsorbed at surfaces, \\Delta \\Delta SCF calculations become challenging, simply because of the large number of states. Not only is it difficult to identify the correct state, often hybridization spreads adsorbate molecular orbitals across a large number of substrate bands. A more realistic excitation constraint would be to project on a gasphase molecular orbital and subsequently enforce occupation of this state. This idea is referred to as linear expansion \\Delta \\Delta SCF and has first been proposed by Gavnholt et al 1 . The CASTEP implementation is described in Maurer and Reuer (2013) 2 . Herein, we constrain the occupation of a so-called resonance state built from a linear combination of Kohn-Sham states instead of a single KS state. We expand an abitrary reference state |\\phi_c\\rangle |\\phi_c\\rangle in the space of Kohn-Sham states as follows: |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle |\\tilde{\\psi}_c^{\\mathbf{k}}\\rangle = \\sum_i^{\\mathrm{states}} |\\psi_i^{\\mathbf{k}}\\rangle\\langle\\psi_i^{\\mathbf{k}}|\\phi_c^{\\mathbf{k}} \\rangle At the same time we orthogonalize the remaining KS states |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle |\\tilde{\\psi_i^{\\mathbf{k}}}\\rangle = |\\psi_i^{\\mathbf{k}}\\rangle - \\sum_c^{\\mathrm{constr.}}|\\phi_c^{\\mathbf{k}}\\rangle\\langle\\phi_c^{\\mathbf{k}}|\\psi_i^{\\mathbf{k}}\\rangle After an additional orthonormalization of all states we have constructed a resonance state \\tilde{\\psi_c^{\\mathbf{k}}} \\tilde{\\psi_c^{\\mathbf{k}}} and removed all its contributions from all other states. We can now constrain the occupation of this state with the effect of describing an excitation of a specific molecular orbital. This is done in every SCF step until the calculation is converged. For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_overlap_cutoff Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : linear expansion deltascf_overlap_cutoff : 0.01 #band occ spin %block deltascf_constraints 35 1.0000 1 %endblock deltascf_constraints In this example, we take state 35 from wavefunction file .check and enforce an occupation of 1.00 electrons. In this runmode we do not have to pick constraints that yield a net change in charge equal to 0. Charge neutrality will be satisfied by modifying the Fermi level accordingly. However, this is only strictly sensible for metallic systems. Jeppe Gavnholt, Thomas Olsen, Mads Engelund, and Jakob Schi\u00f8tz. \u0394 self-consistent field method to obtain potential energy surfaces of excited molecules on surfaces. Phys. Rev. B , 78:075441, Aug 2008. doi:10.1103/PhysRevB.78.075441 . \u21a9 Reinhard J. Maurer and Karsten Reuter. Excited-state potential-energy surfaces of metal-adsorbed organic molecules from linear expansion \u0394-self-consistent field density-functional theory (\u0394SCF-DFT). The Journal of Chemical Physics , 139(1):014708, 07 2013. doi:10.1063/1.4812398 . \u21a9","title":"Basics"},{"location":"documentation/Delta_SCF/mo_delta_scf/","text":"DFT+U(MO) - Applying potentials to arbitrary orbitals Basics We can employ the molecular orbital projections we have introduced in the le \\Delta \\Delta SCF section to also introduce penalty potentials that shift specific orbitals up or down. This can be used to specify the HOMO-LUMO of an adsorbed molecule or to modify the level alignment with the metal substrate. This constraint potential can be combined with population constraints. For more details and an example application on Porphine molecules adsorbed at coinage metal surfaces, see M\u00fcller et al . (2016) 1 . For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_dftu_checkpoint Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_dftu_checkpoint : .check deltascf_method : DFT+U(MO) #band occ spin +U in eV excite? %block deltascf_constraints 34 0.0000 1 -1.40 Y 35 1.0000 2 0.70 Y %endblock deltascf_constraints In this mode we add a potential to the Hamiltonian for each defined constraint, which has the following form: V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| You can find a detailed description of these potentials in Appendix D of First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches 2 In this example, two +U constraint potentials act on orbital no. 34 of the majority spin channel and orbital no. 35 of the minority spin channel, taken from the deltascf_dftu_checkpoint=.check file. In addition, the occupation of orbital no. 35 taken from file deltascf_checkpoint=.check file is constrained to the occupation 1.000. Excitation constraints on each state can be activated (or not) by adding the final 'Y' or 'N' to the relevant line. Moritz M\u00fcller, Katharina Diller, Reinhard J. Maurer, and Karsten Reuter. Interfacial charge rearrangement and intermolecular interactions: Density-functional theory study of free-base porphine adsorbed on Ag(111) and Cu(111). The Journal of Chemical Physics , 144(2):024701, 01 2016. doi:10.1063/1.4938259 . \u21a9 Reinhard Johann Maurer. First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches . PhD thesis, Technische Universit\u00e4t M\u00fcnchen, 2014. URL: https://mediatum.ub.tum.de/1190934 . \u21a9","title":"MO Delta SCF"},{"location":"documentation/Delta_SCF/mo_delta_scf/#dftumo-applying-potentials-to-arbitrary-orbitals","text":"","title":"DFT+U(MO) - Applying potentials to arbitrary orbitals"},{"location":"documentation/Delta_SCF/mo_delta_scf/#basics","text":"We can employ the molecular orbital projections we have introduced in the le \\Delta \\Delta SCF section to also introduce penalty potentials that shift specific orbitals up or down. This can be used to specify the HOMO-LUMO of an adsorbed molecule or to modify the level alignment with the metal substrate. This constraint potential can be combined with population constraints. For more details and an example application on Porphine molecules adsorbed at coinage metal surfaces, see M\u00fcller et al . (2016) 1 . For a le \\Delta \\Delta SCF calculation, we have to set deltascf_method = linear expansion in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_dftu_checkpoint Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_dftu_checkpoint : .check deltascf_method : DFT+U(MO) #band occ spin +U in eV excite? %block deltascf_constraints 34 0.0000 1 -1.40 Y 35 1.0000 2 0.70 Y %endblock deltascf_constraints In this mode we add a potential to the Hamiltonian for each defined constraint, which has the following form: V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| V_c = \\frac{U}{2} \\cdot|\\phi_c\\rangle\\langle\\phi_c| You can find a detailed description of these potentials in Appendix D of First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches 2 In this example, two +U constraint potentials act on orbital no. 34 of the majority spin channel and orbital no. 35 of the minority spin channel, taken from the deltascf_dftu_checkpoint=.check file. In addition, the occupation of orbital no. 35 taken from file deltascf_checkpoint=.check file is constrained to the occupation 1.000. Excitation constraints on each state can be activated (or not) by adding the final 'Y' or 'N' to the relevant line. Moritz M\u00fcller, Katharina Diller, Reinhard J. Maurer, and Karsten Reuter. Interfacial charge rearrangement and intermolecular interactions: Density-functional theory study of free-base porphine adsorbed on Ag(111) and Cu(111). The Journal of Chemical Physics , 144(2):024701, 01 2016. doi:10.1063/1.4938259 . \u21a9 Reinhard Johann Maurer. First-Principles Description of the Isomerization Dynamics of Surface-Adsorbed Molecular Switches . PhD thesis, Technische Universit\u00e4t M\u00fcnchen, 2014. URL: https://mediatum.ub.tum.de/1190934 . \u21a9","title":"Basics"},{"location":"documentation/Delta_SCF/molpdos/","text":"Molecular Orbital (MO) projected Density-of-States - MolPDOS Basics This mode allows to generate projections and pDOS plots with respect to any molecular orbital (MO). To run it one just has to add calculate_modos=true keyword to .param file. The projection data is produced by CASTEP after the SCF task and is written to files called .modos_state_<#>_<#> , where the two numbers correspond to the number and the spin of the specified reference orbital from the reference checkfile. At the end of the .castep file the projection is commented in the following way: Calculating MODOS weights +-------------------INPUT PARAMETERS-------------------+ Taking band from model N2-base.check MODOS state 1 MODOS band nr. 5 MODOS band has spin 1 MODOS state 2 MODOS band nr. 6 MODOS band has spin 1 |DeltaSCF| Population of state: 5 1 1.000000 |DeltaSCF| Population of state: 6 1 0.000000 Writing file N2-modos.modos_state_5_1 Writing file N2-modos.modos_state_6_1 These files, together with the .bands file can be post-processed with the MolPDOS program with the following command MolPDOS This will write output in the .castep with following header. ############################################# # # # # # MolPDOS -CASTEP Post-processor # # # # by R. J. Maurer # # # # # ############################################# In addition it will write files for the total DOS (Total-DOS.dat), for the two spin channels if the calculation was spin polarized (Total-DOS_spin1.dat, Total-DOS_spin2.dat), and for the MolPDOS ( <#>_spin<#>_1X molpdos_bin_with No real number, default=0.01 molpdos_smearing No real number, default=0.05 molpdos_scaling No real number, default=1.0, scales MolPDOSes no_fermi_shift No no argument, logical, removes fermishift ax is_energy_margin No real in eV default=0.0eV output_filename No Example .molpdos file: molpdos_state : 34 1 molpdos_state : 35 1 molpdos_state : 36 1 molpdos_state : 33 1 molpdos_bin_width : 0.02 molpdos_smearing : 0.05 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat","title":"Molecular Projected DOS"},{"location":"documentation/Delta_SCF/molpdos/#molecular-orbital-mo-projected-density-of-states-molpdos","text":"","title":"Molecular Orbital (MO) projected Density-of-States - MolPDOS"},{"location":"documentation/Delta_SCF/molpdos/#basics","text":"This mode allows to generate projections and pDOS plots with respect to any molecular orbital (MO). To run it one just has to add calculate_modos=true keyword to .param file. The projection data is produced by CASTEP after the SCF task and is written to files called .modos_state_<#>_<#> , where the two numbers correspond to the number and the spin of the specified reference orbital from the reference checkfile. At the end of the .castep file the projection is commented in the following way: Calculating MODOS weights +-------------------INPUT PARAMETERS-------------------+ Taking band from model N2-base.check MODOS state 1 MODOS band nr. 5 MODOS band has spin 1 MODOS state 2 MODOS band nr. 6 MODOS band has spin 1 |DeltaSCF| Population of state: 5 1 1.000000 |DeltaSCF| Population of state: 6 1 0.000000 Writing file N2-modos.modos_state_5_1 Writing file N2-modos.modos_state_6_1 These files, together with the .bands file can be post-processed with the MolPDOS program with the following command MolPDOS This will write output in the .castep with following header. ############################################# # # # # # MolPDOS -CASTEP Post-processor # # # # by R. J. Maurer # # # # # ############################################# In addition it will write files for the total DOS (Total-DOS.dat), for the two spin channels if the calculation was spin polarized (Total-DOS_spin1.dat, Total-DOS_spin2.dat), and for the MolPDOS ( <#>_spin<#>_1X molpdos_bin_with No real number, default=0.01 molpdos_smearing No real number, default=0.05 molpdos_scaling No real number, default=1.0, scales MolPDOSes no_fermi_shift No no argument, logical, removes fermishift ax is_energy_margin No real in eV default=0.0eV output_filename No Example .molpdos file: molpdos_state : 34 1 molpdos_state : 35 1 molpdos_state : 36 1 molpdos_state : 33 1 molpdos_bin_width : 0.02 molpdos_smearing : 0.05 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat","title":"Keywords allowed in .molpdos"},{"location":"documentation/Delta_SCF/overview/","text":"Overview Functionality Calculate \\Delta \\Delta SCF-DFT excitation energies by changing band occupation - the \"simple\" method. Constrain and occupy an orbital of a subsystem or reference system to resemble an electronic excitation via 'linear expansion mode' = le \\Delta \\Delta SCF-DFT Put penalties onto orbitals of a subsystem in a DFT+U fashion (DFT+U(MO)). This can be done by enforcing idempotency (integer occupation) or by constrained DFT Generate a projection of the orbital of a subsystem on the Density-of-States (DOS) There is also a separate post-processing tool (MolPDOS) to generate the corresponding DOS from the projection information Prerequisites The following applies to all modes, except the \\Delta \\Delta SCF-DFT mode. Nonetheless, this runmode requires a good understanding of its limitations. The two systems should not be strongly geometrically or electronically mixed and a separation into general system and subsystem has to still be chemically reasonable. Otherwise this Ansatz breaks down. Ideally the difference can be seen as a weak perturbation. This applies for example for A molecule adsorbed at a metal surface with weak to medium hybridization, e.g. C 6 H 6 \\@Au(111). A particle or molecule inserted into a porous nanostructure. The exact same system in another electronic state, e.g. groundstate vs. first excited state. The wavefunction of the subsystem has to be calculated with exactly the same settings (K-points, spin-polarisation, cutoff, cell size) as the actual system. This introduces some artificial dispersion for gas-phase molecules, but if the cell is sufficiently large the effects should be small. In addition, this might be something desirable, for example when high coverage situations are investigated. At the moment, the excitation constraints only work for metals_method=DM and spin_treatment=scalar or none . Currently, hybrid XC functionals are unsupported. General Use The general use of \\Delta \\Delta SCF always involves the following steps: Define the base system and calculate the self consistent density and wave functions using a task=single point energy . The checkfile generated is then used as the base for the next steps. Define the system you want to study and add something similar to the following to the .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_mode : 1 where is the seedname of the base calculation in step 1. Decide on the type of \\Delta \\Delta SCF calculation. The allowed methods are: deltascf_method : SIMPLE or deltascf_mode : 1 deltascf_method : DFT+U(MO) or deltascf_mode : 2 deltascf_method : LINEAR EXPANSTION or deltascf_mode : 3 For each method, the constraints need to be specified as follows: SIMPLE #band occ spin from_band to_band %block deltascf_constraints 5 0.5000 1 5 5 6 0.5000 1 6 6 %endblock deltascf_constraints DFT+U(MO) #band occ spin U(eV) excite_band %block deltascf_constraints 5 0.5000 1 +0.0 .true. 6 0.5000 1 +0.0 .true. %endblock deltascf_constraints LINEAR EXPANSION #band occ spin %block deltascf_constraints 5 0.5000 1 6 0.5000 1 %endblock deltascf_constraints The \"occ\" column is the constrained occupation required. In this instance, 1 electron is being raised from band 5 to band 6. The occupation is defined such that 0<=occ<=1 so if non-spin polarized calculation then occ=0.5 means 1 electron. You can now run the \\Delta \\Delta SCF calculation as any other CASTEP task. If you wish to, you can analyse the results using the MolPDOS post-processing tool which needs an additional .molpdos input file. Hence use MolPDOS ","title":"Delta SCF Overview"},{"location":"documentation/Delta_SCF/overview/#overview","text":"","title":"Overview"},{"location":"documentation/Delta_SCF/overview/#functionality","text":"Calculate \\Delta \\Delta SCF-DFT excitation energies by changing band occupation - the \"simple\" method. Constrain and occupy an orbital of a subsystem or reference system to resemble an electronic excitation via 'linear expansion mode' = le \\Delta \\Delta SCF-DFT Put penalties onto orbitals of a subsystem in a DFT+U fashion (DFT+U(MO)). This can be done by enforcing idempotency (integer occupation) or by constrained DFT Generate a projection of the orbital of a subsystem on the Density-of-States (DOS) There is also a separate post-processing tool (MolPDOS) to generate the corresponding DOS from the projection information","title":"Functionality"},{"location":"documentation/Delta_SCF/overview/#prerequisites","text":"The following applies to all modes, except the \\Delta \\Delta SCF-DFT mode. Nonetheless, this runmode requires a good understanding of its limitations. The two systems should not be strongly geometrically or electronically mixed and a separation into general system and subsystem has to still be chemically reasonable. Otherwise this Ansatz breaks down. Ideally the difference can be seen as a weak perturbation. This applies for example for A molecule adsorbed at a metal surface with weak to medium hybridization, e.g. C 6 H 6 \\@Au(111). A particle or molecule inserted into a porous nanostructure. The exact same system in another electronic state, e.g. groundstate vs. first excited state. The wavefunction of the subsystem has to be calculated with exactly the same settings (K-points, spin-polarisation, cutoff, cell size) as the actual system. This introduces some artificial dispersion for gas-phase molecules, but if the cell is sufficiently large the effects should be small. In addition, this might be something desirable, for example when high coverage situations are investigated. At the moment, the excitation constraints only work for metals_method=DM and spin_treatment=scalar or none . Currently, hybrid XC functionals are unsupported.","title":"Prerequisites"},{"location":"documentation/Delta_SCF/overview/#general-use","text":"The general use of \\Delta \\Delta SCF always involves the following steps: Define the base system and calculate the self consistent density and wave functions using a task=single point energy . The checkfile generated is then used as the base for the next steps. Define the system you want to study and add something similar to the following to the .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_mode : 1 where is the seedname of the base calculation in step 1. Decide on the type of \\Delta \\Delta SCF calculation. The allowed methods are: deltascf_method : SIMPLE or deltascf_mode : 1 deltascf_method : DFT+U(MO) or deltascf_mode : 2 deltascf_method : LINEAR EXPANSTION or deltascf_mode : 3 For each method, the constraints need to be specified as follows: SIMPLE #band occ spin from_band to_band %block deltascf_constraints 5 0.5000 1 5 5 6 0.5000 1 6 6 %endblock deltascf_constraints DFT+U(MO) #band occ spin U(eV) excite_band %block deltascf_constraints 5 0.5000 1 +0.0 .true. 6 0.5000 1 +0.0 .true. %endblock deltascf_constraints LINEAR EXPANSION #band occ spin %block deltascf_constraints 5 0.5000 1 6 0.5000 1 %endblock deltascf_constraints The \"occ\" column is the constrained occupation required. In this instance, 1 electron is being raised from band 5 to band 6. The occupation is defined such that 0<=occ<=1 so if non-spin polarized calculation then occ=0.5 means 1 electron. You can now run the \\Delta \\Delta SCF calculation as any other CASTEP task. If you wish to, you can analyse the results using the MolPDOS post-processing tool which needs an additional .molpdos input file. Hence use MolPDOS ","title":"General Use"},{"location":"documentation/Delta_SCF/simple_delta_scf/","text":"Conventional Delta-Self-Consistent-Field-DFT Calculations Basics In \\Delta \\Delta SCF-DFT we calculate electronic excited states by assuming a certain non-equilibrium orbital occupation and by self-consistently solving the Kohn-Sham equations with this excited state population. The excitation energy is then simply the energy difference between the ground state KS-DFT calculation and the \\Delta \\Delta SCF-DFT calculation: \\Delta E = E(\\Delta SCF)-E(DFT) \\Delta E = E(\\Delta SCF)-E(DFT) We therefore need to perform two calculations, the ground state DFT calculation and the DeltaSCF calculation. For a more detailed explanation, see Maurer and Reuter (2011) 1 . For this simple \\Delta \\Delta SCF calculation, we have to set deltascf_method = simple in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_smearing Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.0000 1 34 34 35 1.0000 1 35 35 %endblock deltascf_constraints In this example, we enforce an occupation of 0.00 electrons in the electronic state 34, spin channel 1 and an occupation of 1.00 electrons in the electronic state 35, spin channel 1. The last two numbers in each line specify a window of states in which the corresponding state is searched if it changes its position between SCF cycles. In that way we can ensure that we constrain the correct state. deltascf_smearing is a mechanism which relaxes the constraints minimally to facilitate convergence. Sometimes, especially in the case of degenerate states, deltascf_smearing is necessary. Reinhard J. Maurer and Karsten Reuter. Assessing computationally efficient isomerization dynamics: \u0394SCF density-functional theory study of azobenzene molecular switching. The Journal of Chemical Physics , 135(22):224303, 12 2011. doi:10.1063/1.3664305 . \u21a9","title":"Simple Delta SCF"},{"location":"documentation/Delta_SCF/simple_delta_scf/#conventional-delta-self-consistent-field-dft-calculations","text":"","title":"Conventional Delta-Self-Consistent-Field-DFT Calculations"},{"location":"documentation/Delta_SCF/simple_delta_scf/#basics","text":"In \\Delta \\Delta SCF-DFT we calculate electronic excited states by assuming a certain non-equilibrium orbital occupation and by self-consistently solving the Kohn-Sham equations with this excited state population. The excitation energy is then simply the energy difference between the ground state KS-DFT calculation and the \\Delta \\Delta SCF-DFT calculation: \\Delta E = E(\\Delta SCF)-E(DFT) \\Delta E = E(\\Delta SCF)-E(DFT) We therefore need to perform two calculations, the ground state DFT calculation and the DeltaSCF calculation. For a more detailed explanation, see Maurer and Reuter (2011) 1 . For this simple \\Delta \\Delta SCF calculation, we have to set deltascf_method = simple in the .param file. The constraint must also be specifed, as discussed in the overview section. The only additional relevant \\Delta \\Delta SCF keywords is deltascf_smearing Example .param file: reuse : .check calculate_deltascf : true deltascf_checkpoint : .check deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.0000 1 34 34 35 1.0000 1 35 35 %endblock deltascf_constraints In this example, we enforce an occupation of 0.00 electrons in the electronic state 34, spin channel 1 and an occupation of 1.00 electrons in the electronic state 35, spin channel 1. The last two numbers in each line specify a window of states in which the corresponding state is searched if it changes its position between SCF cycles. In that way we can ensure that we constrain the correct state. deltascf_smearing is a mechanism which relaxes the constraints minimally to facilitate convergence. Sometimes, especially in the case of degenerate states, deltascf_smearing is necessary. Reinhard J. Maurer and Karsten Reuter. Assessing computationally efficient isomerization dynamics: \u0394SCF density-functional theory study of azobenzene molecular switching. The Journal of Chemical Physics , 135(22):224303, 12 2011. doi:10.1063/1.3664305 . \u21a9","title":"Basics"},{"location":"documentation/EPR/overview/","text":"In crystalline materials, electron paramagnetic resonance (EPR) can be used to study paramagnetic defects. EPR spectra of spin \u00bd centers have two contributions: the hyperfine tensor {\\bf A} {\\bf A} and the g-tensor {\\bf g} {\\bf g} , which are defined through the following effective Hamiltonian \\begin{equation} H_{eff}=\\frac{\\alpha}{2}{\\bf S}\\cdot{\\bf g}\\cdot{\\bf B} + \\sum_I {\\bf S}\\cdot{\\bf A}_{I}\\cdot{\\bf I}_I \\end{equation} where \\alpha \\alpha is the fine structure constant and the summation I I runs over nuclei. The hyperfine tensor arises from the interaction of the nuclei with the ground-state spin density. This term has been calculated within the planewave-pseudopotential approach; indeed it was for this property that the PAW scheme was first introduced.\\cite{walle93} The g-tensor arises from the interaction of the electronic spin with the external magnetic field. This term plays an somewhat similar role to the shielding in NMR; induced electronic currents in the sample modify the g-tensor from its vacuum value. The GIPAW approach has been used to compute g-tensors in several crystalline materials including defects in \\alpha \\alpha -quartz and zirconia.","title":"EPR Overview"},{"location":"documentation/Geometry_Optimisation/constraints/","text":"Atomic constraints CASTEP can impose various forms of linear or non-linear constraints upon the positions of the atoms. This can be used with all forms of geometry optimization and molecular dynamics. Some simple short cuts exist, such as to keep all the atoms fixed: FIX_ALL_IONS : T or to fix the Centre of Mass: FIX_COM : T It is also possible to specify constraints on individual atoms, using the IONIC_CONSTRAINTS block. The simplest case is to control which atoms remain fixed during a geometry optimisation. e.g. %BLOCK IONIC_CONSTRAINTS fix: C 1 !fix position of atom C 1 %ENDBLOCK IONIC_CONSTRAINTS Some further examples include fix: all !fix all atoms\u2028 fix: C N !fix species C and N\u2028 fix: C 1 !fix position of atom C 1\u2028 fix: C{1,3,5-10} !fix positions of atoms C1, C3, C5,C6,C7,C8,C9,C10\u2028 fix: all unfix: H !fix positions of all atoms except H The last example in particularly useful in the case of molecular crystals, when you might want to allow the H atoms to move but keep all of the heavy atoms in the positions determined by diffraction. To fix the individual Cartesian components of an atom's position use the full syntax of the ionic_constraints block, where each constraint removes one degree of freedom. For example %BLOCK IONIC_CONSTRAINTS 1 W 1 1.0000000000 0.0000000000 0.0000000000 2 W 1 0.0000000000 1.0000000000 0.0000000000 3 W 1 0.0000000000 0.0000000000 1.0000000000 4 W 2 1.0000000000 0.0000000000 0.0000000000 %ENDBLOCK IONIC_CONSTRAINTS The 1 st line says that constraint number 1 is to fix the x coordinate of Tungsten atom 1. The 2 nd line says that constraint number 2 is to fix the y coordinate of Tungsten atom 1. etc. To fix an atom in 3D requires 3 constraints to remove all 3 degrees of freedom. The ionic_constraints block can also be used to impose any arbitary linear constraint, such as to restrict an atom to move in a plane or along a line, or to fix the centre of mass. A constraint may involve more than 1 atom, and hence can span mulitple lines, but each constraint operates on 1 degree of freedom. It cannot be used to fix a bond length - that is a non-linear constraint - see below for more details. The general syntax for constraint i i operating on atom j j of element X at position r^j r^j is %BLOCK IONIC_CONSTRAINTS ... i X j a1 a2 a3 ... %ENDBLOCK IONIC_CONSTRAINTS and the constraint is specfied as \\begin{equation} C^i={\\bf a^i}\\cdot{\\bf r^j} \\end{equation} where C^i C^i is given by the initial conditions. For example to fix the second S atom to move in the plane parallel to y=x y=x use this: %BLOCK IONIC_CONSTRAINTS 1 S 2 -1 1 0 %ENDBLOCK IONIC_CONSTRAINTS Cell Constraints Cell constraints can be used with all forms of geometry optimization and molecular dynamics that allow the cell size/shape to vary. Some simple short cuts exist, such as to keep the unit cell fixed during the optimisation FIX_CELL : T or to fix the volume (but not the shape) of the unit cell FIX_VOL : T It is also possible to apply an arbitary set of constraints to the cell angles and cell lengths using the CELL_CONSTRAINTS block. %BLOCK CELL_CONSTRAINTS a b c alpha beta gamma %ENDBLOCK CELL_CONSTRAINTS Setting an element to zero means to keep it fixed. Two or more elements set to the same positive integer, means that these elements should be kept equal during the geometry optimisation. For example %BLOCK CELL_CONSTRAINTS 0 0 0 4 5 6 %ENDBLOCK CELL_CONSTRAINTS would keep all cell lengths fixed, and allow the three cell angles to vary independently, and %BLOCK CELL_CONSTRAINTS 0 0 0 4 4 6 %ENDBLOCK CELL_CONSTRAINTS would enforce \\alpha=\\beta\\neq\\gamma \\alpha=\\beta\\neq\\gamma and keep the cell lengths fixed. Symmetry The application of symmetry with constraints (for ionic positions and/or cell vectors) needs to be considered carefully. In general, if symmetry is on, then there is no need to add a constraint to explicitly impose a restriction that is implied by the symmetry. If there is a need for an additional restriction, then that can be added on top of the symmetry, but the user needs to be careful that the additional constraint does not conflict with symmetry. If in doubt, turn symmetry off and impose all the desired constraints explicitly. Non-linear Constraints CASTEP can also support non-linear constraints, such as fixed bond length, in both molecular dynamics, and also in geometry optimization if using GEOM_METHOD=DELOCALISED : %BLOCK NONLINEAR_CONSTRAINTS constraint_type atom1 atom2 (atom3 (atom 4)) ... %ENDBLOCK NONLINEAR_CONSTRAINTS where the first element specifies a constraint type (distance, bend angle or torsion angle). Then depending on the type of constraint, either 2, 3 or 4 atoms need to be specified, and the corresponding quantity (distance, bend angle or torsion angle) is held constant at the initial value. As for (linear) ionic constraints, atoms are specified by species and number within that species. In addition, it is necessary to specify which periodic image of the cell the atom is located in (so constraints can straddle a cell boundary). For instance %BLOCK NONLINEAR_CONSTRAINTS distance H 4 0 0 0 O 2 0 1 0 bend H 5 0 0 0 C 1 1 0 1 H 2 0 0 0 torsion H 6 0 0 0 H 3 1 0 0 H 1 0 0 1 H 9 1 1 1 0 %ENDBLOCK NONLINEAR_CONSTRAINTS specifies: the distance between the 4 th hydrogen atom and the 2 nd oxygen atom in the adjacent ( 0 1 0 ) cell the bend angle defined by the 5 th hydrogen atom, the 1 st carbon atom in the ( 1 0 1 ) cell and the 2 nd hydrogen atom the torsion angle defined by 4 hydrogen atoms, etc.","title":"Constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#atomic-constraints","text":"CASTEP can impose various forms of linear or non-linear constraints upon the positions of the atoms. This can be used with all forms of geometry optimization and molecular dynamics. Some simple short cuts exist, such as to keep all the atoms fixed: FIX_ALL_IONS : T or to fix the Centre of Mass: FIX_COM : T It is also possible to specify constraints on individual atoms, using the IONIC_CONSTRAINTS block. The simplest case is to control which atoms remain fixed during a geometry optimisation. e.g. %BLOCK IONIC_CONSTRAINTS fix: C 1 !fix position of atom C 1 %ENDBLOCK IONIC_CONSTRAINTS Some further examples include fix: all !fix all atoms\u2028 fix: C N !fix species C and N\u2028 fix: C 1 !fix position of atom C 1\u2028 fix: C{1,3,5-10} !fix positions of atoms C1, C3, C5,C6,C7,C8,C9,C10\u2028 fix: all unfix: H !fix positions of all atoms except H The last example in particularly useful in the case of molecular crystals, when you might want to allow the H atoms to move but keep all of the heavy atoms in the positions determined by diffraction. To fix the individual Cartesian components of an atom's position use the full syntax of the ionic_constraints block, where each constraint removes one degree of freedom. For example %BLOCK IONIC_CONSTRAINTS 1 W 1 1.0000000000 0.0000000000 0.0000000000 2 W 1 0.0000000000 1.0000000000 0.0000000000 3 W 1 0.0000000000 0.0000000000 1.0000000000 4 W 2 1.0000000000 0.0000000000 0.0000000000 %ENDBLOCK IONIC_CONSTRAINTS The 1 st line says that constraint number 1 is to fix the x coordinate of Tungsten atom 1. The 2 nd line says that constraint number 2 is to fix the y coordinate of Tungsten atom 1. etc. To fix an atom in 3D requires 3 constraints to remove all 3 degrees of freedom. The ionic_constraints block can also be used to impose any arbitary linear constraint, such as to restrict an atom to move in a plane or along a line, or to fix the centre of mass. A constraint may involve more than 1 atom, and hence can span mulitple lines, but each constraint operates on 1 degree of freedom. It cannot be used to fix a bond length - that is a non-linear constraint - see below for more details. The general syntax for constraint i i operating on atom j j of element X at position r^j r^j is %BLOCK IONIC_CONSTRAINTS ... i X j a1 a2 a3 ... %ENDBLOCK IONIC_CONSTRAINTS and the constraint is specfied as \\begin{equation} C^i={\\bf a^i}\\cdot{\\bf r^j} \\end{equation} where C^i C^i is given by the initial conditions. For example to fix the second S atom to move in the plane parallel to y=x y=x use this: %BLOCK IONIC_CONSTRAINTS 1 S 2 -1 1 0 %ENDBLOCK IONIC_CONSTRAINTS","title":"Atomic constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#cell-constraints","text":"Cell constraints can be used with all forms of geometry optimization and molecular dynamics that allow the cell size/shape to vary. Some simple short cuts exist, such as to keep the unit cell fixed during the optimisation FIX_CELL : T or to fix the volume (but not the shape) of the unit cell FIX_VOL : T It is also possible to apply an arbitary set of constraints to the cell angles and cell lengths using the CELL_CONSTRAINTS block. %BLOCK CELL_CONSTRAINTS a b c alpha beta gamma %ENDBLOCK CELL_CONSTRAINTS Setting an element to zero means to keep it fixed. Two or more elements set to the same positive integer, means that these elements should be kept equal during the geometry optimisation. For example %BLOCK CELL_CONSTRAINTS 0 0 0 4 5 6 %ENDBLOCK CELL_CONSTRAINTS would keep all cell lengths fixed, and allow the three cell angles to vary independently, and %BLOCK CELL_CONSTRAINTS 0 0 0 4 4 6 %ENDBLOCK CELL_CONSTRAINTS would enforce \\alpha=\\beta\\neq\\gamma \\alpha=\\beta\\neq\\gamma and keep the cell lengths fixed.","title":"Cell Constraints"},{"location":"documentation/Geometry_Optimisation/constraints/#symmetry","text":"The application of symmetry with constraints (for ionic positions and/or cell vectors) needs to be considered carefully. In general, if symmetry is on, then there is no need to add a constraint to explicitly impose a restriction that is implied by the symmetry. If there is a need for an additional restriction, then that can be added on top of the symmetry, but the user needs to be careful that the additional constraint does not conflict with symmetry. If in doubt, turn symmetry off and impose all the desired constraints explicitly.","title":"Symmetry"},{"location":"documentation/Geometry_Optimisation/constraints/#non-linear-constraints","text":"CASTEP can also support non-linear constraints, such as fixed bond length, in both molecular dynamics, and also in geometry optimization if using GEOM_METHOD=DELOCALISED : %BLOCK NONLINEAR_CONSTRAINTS constraint_type atom1 atom2 (atom3 (atom 4)) ... %ENDBLOCK NONLINEAR_CONSTRAINTS where the first element specifies a constraint type (distance, bend angle or torsion angle). Then depending on the type of constraint, either 2, 3 or 4 atoms need to be specified, and the corresponding quantity (distance, bend angle or torsion angle) is held constant at the initial value. As for (linear) ionic constraints, atoms are specified by species and number within that species. In addition, it is necessary to specify which periodic image of the cell the atom is located in (so constraints can straddle a cell boundary). For instance %BLOCK NONLINEAR_CONSTRAINTS distance H 4 0 0 0 O 2 0 1 0 bend H 5 0 0 0 C 1 1 0 1 H 2 0 0 0 torsion H 6 0 0 0 H 3 1 0 0 H 1 0 0 1 H 9 1 1 1 0 %ENDBLOCK NONLINEAR_CONSTRAINTS specifies: the distance between the 4 th hydrogen atom and the 2 nd oxygen atom in the adjacent ( 0 1 0 ) cell the bend angle defined by the 5 th hydrogen atom, the 1 st carbon atom in the ( 1 0 1 ) cell and the 2 nd hydrogen atom the torsion angle defined by 4 hydrogen atoms, etc.","title":"Non-linear Constraints"},{"location":"documentation/Geometry_Optimisation/files/","text":".geom The .geom file is the primary output file, and contains the unit cell, positions of the atoms and the forces on the atoms for each step of the geometry optimisation. The format of this file is very similar to the .md file. BEGIN header END header 0 F F F F <-- c -1.1089287934762380E+000 -1.1089287934762380E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 0.0000000000000000E+000 0.0000000000000000E+000 0.0000000000000000E+000 <-- R H 2 0.0000000000000000E+000 0.0000000000000000E+000 1.8897261258369291E+000 <-- R H 1 5.2328399876121735E-008 -1.0421543664521416E-007 7.0009877481903737E-002 <-- F H 2 -5.2328399876121735E-008 1.0421543664521414E-007 -7.0009877481903737E-002 <-- F 1 F F F T <-- c -1.1238786617585625E+000 -1.1238786617585625E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 9.4833861449528325E-008 -1.8886784811136898E-007 1.2687770000486739E-001 <-- R H 2 -9.4833861449528339E-008 1.8886784811136895E-007 1.7628484258320618E+000 <-- R H 1 -3.5821658412345467E-009 7.1341230429117867E-009 4.3459352502549203E-002 <-- F H 2 3.5821658412345467E-009 -7.1341230429117867E-009 -4.3459352502549203E-002 <-- F 5 T T T T <-- c -1.1282766172341445E+000 -1.1282766172341445E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 -3.9595146097124387E-007 7.8856409239690845E-007 2.1772199021621047E-001 <-- R H 2 3.9595146097124376E-007 -7.8856409239690845E-007 1.6720041356207189E+000 <-- R H 1 -8.2747158669639466E-009 1.6479675454026804E-008 1.5340573808683700E-006 <-- F H 2 8.2747158669639466E-009 -1.6479675454026804E-008 -1.5340573808683700E-006 <-- F All quantities are reported in atomic units (this cannot be changed by any parameter) <-- c Reports the iteration number and whether the convergence criteria are satisfied. <-- E Energy (total energy, enthalpy) <-- h Unit cell vectors <-- S Stress on unit cell (only reported if the cell is allowed to change) <-- R Cartesian positions of atoms <-- F Force on atoms The '\u2190 c' line also reports the status of 4 convergence flags (either F=false or T=true). These are (in order): dE - has the energy change/atom been below geom_energy_tol for the last geom_convergence_win steps? Fmax - is the largest component of any force below geom_force_tol? dRmax - is the largest change in position for any atom below geom_disp_tol? Smax - is the largest component of the stress tensor below geom_stress_tol?","title":"Files"},{"location":"documentation/Geometry_Optimisation/files/#geom","text":"The .geom file is the primary output file, and contains the unit cell, positions of the atoms and the forces on the atoms for each step of the geometry optimisation. The format of this file is very similar to the .md file. BEGIN header END header 0 F F F F <-- c -1.1089287934762380E+000 -1.1089287934762380E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 0.0000000000000000E+000 0.0000000000000000E+000 0.0000000000000000E+000 <-- R H 2 0.0000000000000000E+000 0.0000000000000000E+000 1.8897261258369291E+000 <-- R H 1 5.2328399876121735E-008 -1.0421543664521416E-007 7.0009877481903737E-002 <-- F H 2 -5.2328399876121735E-008 1.0421543664521414E-007 -7.0009877481903737E-002 <-- F 1 F F F T <-- c -1.1238786617585625E+000 -1.1238786617585625E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 9.4833861449528325E-008 -1.8886784811136898E-007 1.2687770000486739E-001 <-- R H 2 -9.4833861449528339E-008 1.8886784811136895E-007 1.7628484258320618E+000 <-- R H 1 -3.5821658412345467E-009 7.1341230429117867E-009 4.3459352502549203E-002 <-- F H 2 3.5821658412345467E-009 -7.1341230429117867E-009 -4.3459352502549203E-002 <-- F 5 T T T T <-- c -1.1282766172341445E+000 -1.1282766172341445E+000 <-- E 1.1338356755021575E+001 0.0000000000000000E+000 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 1.1338356755021575E+001 0.0000000000000000E+000 <-- h 6.9427411538139708E-016 6.9427411538139708E-016 1.1338356755021575E+001 <-- h H 1 -3.9595146097124387E-007 7.8856409239690845E-007 2.1772199021621047E-001 <-- R H 2 3.9595146097124376E-007 -7.8856409239690845E-007 1.6720041356207189E+000 <-- R H 1 -8.2747158669639466E-009 1.6479675454026804E-008 1.5340573808683700E-006 <-- F H 2 8.2747158669639466E-009 -1.6479675454026804E-008 -1.5340573808683700E-006 <-- F All quantities are reported in atomic units (this cannot be changed by any parameter) <-- c Reports the iteration number and whether the convergence criteria are satisfied. <-- E Energy (total energy, enthalpy) <-- h Unit cell vectors <-- S Stress on unit cell (only reported if the cell is allowed to change) <-- R Cartesian positions of atoms <-- F Force on atoms The '\u2190 c' line also reports the status of 4 convergence flags (either F=false or T=true). These are (in order): dE - has the energy change/atom been below geom_energy_tol for the last geom_convergence_win steps? Fmax - is the largest component of any force below geom_force_tol? dRmax - is the largest change in position for any atom below geom_disp_tol? Smax - is the largest component of the stress tensor below geom_stress_tol?","title":".geom"},{"location":"documentation/Geometry_Optimisation/keywords/","text":"To perform a geometry optimisation set the task parameter task : geomopt The convergence criteria have the following default values, each of which can be set independently. geom_energy_tol : Tolerance on energy change between iterations (default: 2.0e-5 eV) geom_force_tol : Tolerance on maximum force on each atom (default: 0.05 eV/ANG) geom_stress_tol : Tolerance on maximum stress on cell (default: 0.1 GPa) geom_disp_tol : Tolerance on change in atom positions between iterations (default: 0.001: Ang) geom_max_iter : Maximum number of iterations (default: 30) It is possible to change the optimisation method, and to choose a preconditioner. geom_method : LBFGS (default), BFGS, TPSD, DAMPEDMD, FIRE geom_preconditioner : EXP / FF / ID # EXPonential, Force Field, Identity (default) It is useful to set the following two parameters in a geometry optimisation. These will cause CASTEP to write a new cell/cif file with the final optimised coordinates write_cell_structure : T write_cif_structure : T","title":"Keywords"},{"location":"documentation/Geometry_Optimisation/overview/","text":"The essence of the calculation is for the ions and electrons in the supercell to be moved around stepwise until the forces on the atoms and the change in total energy between steps fall below some predefined convergence tolerance. The ionic positions are optimised using quasi-Newton methods. For each configuration of the ionic positions the electronic configuration is optimised using the method of conjugate gradients. The flow of the calculation is thus; Move ions into new positions using geometry optimisation algorithm Find electronic energy and forces for this ionic configuration Compare total energy with previous configurations and check if forces within tolerance limits If structure not optimised start at (1) and generate new set of ionic positions This cycle is performed until the forces fall within the tolerance limit and the energy should then be a local minimum. With periodic boundary conditions (as used by CASTEP) it is also possible to change the size and shape of the cell, in addition to (or instead of) moving the ions. In this case, the stress is calculated in addition to the forces, and this is used to change the cell, until the stress falls within a given tolerance. Finally, when considering the change in the cell, it is also possible to apply an external pressure. Hence it is the enthalpy, which is the appropriate free energy in this scenario, which is minimised instead of the energy. Finite-basis set corrections It should be noted, that with a plane-wave basis set (as used by CASTEP) there is an important side-effect of changing the size and/or shape of the cell - it changes the basis set used for the electronic states. Many DFT programs ignore this effect, which means that if the cell vectors change by more than a few %, the final structure is evaluated with a non-self-consistent basis, with a different cut-off energy to that intended. In CASTEP, there are two choices here: to either keep the cut-off energy constant (which results in the number and meaning of the plane-waves used in the basis changing from step-to-step) or to keep the number of plane-waves constant (which results in a change in the cut-off energy and in the meaning of the plane-waves used from step-to-step). The constant-cutoff/variable-number of plane-waves approach is the CASTEP default as it is the most physically reasonable. The constant number of plane-waves approach means that the quality of the calculation is changing from step-to-step. The effect of changing lattice vectors on the basis set can also be corrected to first-order using the 'finite basis set correction'. This can be calculated by the change in total energy for a small change in the cut-off energy at the start of a calculation, and then used as a correction to the energy and the stress. This is especially important in variable-cell calculations, for which it is activated by default. Advanced settings For geometry optimisation, there are a variety of different algorithms available which can be selected by the geom_method parameter in the param file. The choices are: LBFGS - the low-memory version of BFGS - the default option BFGS - widely-used quasi-Newton minimization TPSD - two-point steepest descent DELOCALIZED - a BFGS-based minimizer using delocalized internal coordinates DMD - optimally damped MD FIRE - fast inertial relaxation engine - a modified MD approach NB These are all 'local optimisations', i.e. the final structure depends upon the initial configuration and is not the global minimum. For those interested in finding the global minimum, then there are associated projects using Genetic Algorithms and AIRSS. The first 3 methods can do variable-cell or fixed-cell optimization, whereas the last 3 are only fixed-cell (for now). LBFGS/BFGS is generally the fastest method, and since v19, LBFGS has supported new preconditioners which should make it generally faster still. TPSD (unlike LBFGS/BFGS) has no built-in history, so should be much slower - however, the CASTEP implementation has a very efficient preconditioner which makes up for this, and the lack of history means that variable-cell optimisation with additional cell constraints is much more efficient than the equivalent calculation in LBFGS/BFGS. The DELOCALIZED minimizer is the only supported method to use delocalized internal coordinates, as opposed to absolute or fractional coordinates, and as such, should be best for optimizing large structures such as molecule-in-a-box with many low-energy soft modes. The two MD-based methods are generally less efficient, but can handle arbitrary constraints well, and have sometimes out-performed other methods for very anisotropic systems, such as molecule-on-a-surface etc.","title":"Overview"},{"location":"documentation/Geometry_Optimisation/overview/#finite-basis-set-corrections","text":"It should be noted, that with a plane-wave basis set (as used by CASTEP) there is an important side-effect of changing the size and/or shape of the cell - it changes the basis set used for the electronic states. Many DFT programs ignore this effect, which means that if the cell vectors change by more than a few %, the final structure is evaluated with a non-self-consistent basis, with a different cut-off energy to that intended. In CASTEP, there are two choices here: to either keep the cut-off energy constant (which results in the number and meaning of the plane-waves used in the basis changing from step-to-step) or to keep the number of plane-waves constant (which results in a change in the cut-off energy and in the meaning of the plane-waves used from step-to-step). The constant-cutoff/variable-number of plane-waves approach is the CASTEP default as it is the most physically reasonable. The constant number of plane-waves approach means that the quality of the calculation is changing from step-to-step. The effect of changing lattice vectors on the basis set can also be corrected to first-order using the 'finite basis set correction'. This can be calculated by the change in total energy for a small change in the cut-off energy at the start of a calculation, and then used as a correction to the energy and the stress. This is especially important in variable-cell calculations, for which it is activated by default.","title":"Finite-basis set corrections"},{"location":"documentation/Geometry_Optimisation/overview/#advanced-settings","text":"For geometry optimisation, there are a variety of different algorithms available which can be selected by the geom_method parameter in the param file. The choices are: LBFGS - the low-memory version of BFGS - the default option BFGS - widely-used quasi-Newton minimization TPSD - two-point steepest descent DELOCALIZED - a BFGS-based minimizer using delocalized internal coordinates DMD - optimally damped MD FIRE - fast inertial relaxation engine - a modified MD approach NB These are all 'local optimisations', i.e. the final structure depends upon the initial configuration and is not the global minimum. For those interested in finding the global minimum, then there are associated projects using Genetic Algorithms and AIRSS. The first 3 methods can do variable-cell or fixed-cell optimization, whereas the last 3 are only fixed-cell (for now). LBFGS/BFGS is generally the fastest method, and since v19, LBFGS has supported new preconditioners which should make it generally faster still. TPSD (unlike LBFGS/BFGS) has no built-in history, so should be much slower - however, the CASTEP implementation has a very efficient preconditioner which makes up for this, and the lack of history means that variable-cell optimisation with additional cell constraints is much more efficient than the equivalent calculation in LBFGS/BFGS. The DELOCALIZED minimizer is the only supported method to use delocalized internal coordinates, as opposed to absolute or fractional coordinates, and as such, should be best for optimizing large structures such as molecule-in-a-box with many low-energy soft modes. The two MD-based methods are generally less efficient, but can handle arbitrary constraints well, and have sometimes out-performed other methods for very anisotropic systems, such as molecule-on-a-surface etc.","title":"Advanced settings"},{"location":"documentation/Geometry_Optimisation/tools/","text":"JMol can read a .geom file and animate the movement of atoms during the optimisation. See tutorials for more examples.","title":"Tools"},{"location":"documentation/Getting_Started/basic_cell_file/","text":"This is a basic overview of the cell file. See the full cell file page for more details. The cell file is one of CASTEP's two main input files. It contains all of the information about the crystal lattice and the atomic positions, as well as additional information such as Brillouin zone sampling ('k-points'), pseudopotentials, and atomic properties. The file itself is a free-format keyword-driven text file, consisting of keywords and blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. Most of the keywords and blocks are optional, but CASTEP requires two block entries: a block to specify the lattice, and another to specify the atomic elements and positions within the cell. Lattice There are two main ways to set the crystal lattice in the cell file. The lattice_abc block specifies the lattice constants in terms of the lengths of the lattice vectors ( \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} ) and angles (alpha, beta and gamma): %block lattice_abc a b c alpha beta gamma %endblock lattice_abc This doesn't specify how the cell is to be oriented in the Cartesian coordinate system, so CASTEP uses the convention that \\mathbf{a} \\mathbf{a} is along the x-axis, and \\mathbf{b} \\mathbf{b} is in the x-y plane. Alternatively, you can specify the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} directly in terms of their Cartesian components, using the lattice_cart block. Note that these are specified as row vectors: %block lattice_cart [unit] a_x a_y a_z b_x b_y b_z c_x c_y c_z %endblock lattice_cart The first line is optional, and specifies a length unit; the default is ang , meaning Angstroms. Atomic positions The positions of the atoms within a cell may be specified in either fractional coordinates (i.e. the coordinates in the basis of the lattice vectors) or Cartesian coordinates: %block positions_frac symbol u v w %endblock positions_frac where symbol is the chemical symbol for the atomic element, and u , v and w are the fractional components of the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} , respectively, such that the Cartesian positions vector of the atom, \\mathbf{r} \\mathbf{r} , is \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} To add a second atom, simply add a second line with the new information, and similarly for additional atoms. An alternative is to specify the atomic coordinates with reference to their absolute Cartesian coordinates: %block positions_abs [unit] symbol x y z %endblock positions_abs where [unit] is an optional length unit (default: ang , meaning Angstroms), symbol is the chemical symbol for the atomic element, and x , y and z are the Cartesian coordinates of the atom, such that the position vector, \\mathbf{r}=(x,y,z) \\mathbf{r}=(x,y,z) . Comments It can be convenient to add comments to a cell file, not only to explain why certain choices were made, but also as a way of disabling input lines without removing them from the file. Both ! and # are accepted as comment characters, and anything to the right of these will be ignored by CASTEP. For example, the cell section # Place a single atom at the origin %block positions_abs bohr C 0.00000000 0.00000000 0.00000000 !Si 0.00000000 0.00000000 0.00000000 %endblock positions_abs has a comment explaining the atomic coordinates, and a single carbon atom at the origin. The second atomic position is commented out, so CASTEP will ignore it.","title":"cell File"},{"location":"documentation/Getting_Started/basic_cell_file/#lattice","text":"There are two main ways to set the crystal lattice in the cell file. The lattice_abc block specifies the lattice constants in terms of the lengths of the lattice vectors ( \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} ) and angles (alpha, beta and gamma): %block lattice_abc a b c alpha beta gamma %endblock lattice_abc This doesn't specify how the cell is to be oriented in the Cartesian coordinate system, so CASTEP uses the convention that \\mathbf{a} \\mathbf{a} is along the x-axis, and \\mathbf{b} \\mathbf{b} is in the x-y plane. Alternatively, you can specify the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} directly in terms of their Cartesian components, using the lattice_cart block. Note that these are specified as row vectors: %block lattice_cart [unit] a_x a_y a_z b_x b_y b_z c_x c_y c_z %endblock lattice_cart The first line is optional, and specifies a length unit; the default is ang , meaning Angstroms.","title":"Lattice"},{"location":"documentation/Getting_Started/basic_cell_file/#atomic-positions","text":"The positions of the atoms within a cell may be specified in either fractional coordinates (i.e. the coordinates in the basis of the lattice vectors) or Cartesian coordinates: %block positions_frac symbol u v w %endblock positions_frac where symbol is the chemical symbol for the atomic element, and u , v and w are the fractional components of the lattice vectors \\mathbf{a} \\mathbf{a} , \\mathbf{b} \\mathbf{b} and \\mathbf{c} \\mathbf{c} , respectively, such that the Cartesian positions vector of the atom, \\mathbf{r} \\mathbf{r} , is \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} \\mathbf{r} = u\\mathbf{a} + v\\mathbf{b} + w\\mathbf{c} To add a second atom, simply add a second line with the new information, and similarly for additional atoms. An alternative is to specify the atomic coordinates with reference to their absolute Cartesian coordinates: %block positions_abs [unit] symbol x y z %endblock positions_abs where [unit] is an optional length unit (default: ang , meaning Angstroms), symbol is the chemical symbol for the atomic element, and x , y and z are the Cartesian coordinates of the atom, such that the position vector, \\mathbf{r}=(x,y,z) \\mathbf{r}=(x,y,z) .","title":"Atomic positions"},{"location":"documentation/Getting_Started/basic_cell_file/#comments","text":"It can be convenient to add comments to a cell file, not only to explain why certain choices were made, but also as a way of disabling input lines without removing them from the file. Both ! and # are accepted as comment characters, and anything to the right of these will be ignored by CASTEP. For example, the cell section # Place a single atom at the origin %block positions_abs bohr C 0.00000000 0.00000000 0.00000000 !Si 0.00000000 0.00000000 0.00000000 %endblock positions_abs has a comment explaining the atomic coordinates, and a single carbon atom at the origin. The second atomic position is commented out, so CASTEP will ignore it.","title":"Comments"},{"location":"documentation/Getting_Started/basic_param_file/","text":"This is a basic overview of the param file. See the full param file page for more details. The param file is one of CASTEP's two main input files. It contains all of the information about the kind of simulation your wish CASTEP to perform, as well as details of how CASTEP should perform them and additional simulations and analyses. The file itself is a free-format keyword-driven text file, consisting largely of single-line keywords, although there are a small number of blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. All of the keywords and blocks are optional, but you will almost always want to change at least some. Task This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file . Cut-off energy The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV. XC functional Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"param File"},{"location":"documentation/Getting_Started/basic_param_file/#task","text":"This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file .","title":"Task"},{"location":"documentation/Getting_Started/basic_param_file/#cut-off-energy","text":"The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV.","title":"Cut-off energy"},{"location":"documentation/Getting_Started/basic_param_file/#xc-functional","text":"Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"XC functional"},{"location":"documentation/Getting_Started/built_in_help/","text":"CASTEP has an in-built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: castep -h To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: castep -h kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. castep -s symmetry Finally, to list all keywords, use: castep -h all To find out which version of CASTEP you have, use: castep -v","title":"Command line help"},{"location":"documentation/Getting_Started/intro/","text":"CASTEP is a software package to calculate the properties of materials. It is based on quantum mechanics, in a form known as density functional theory, and can simulate a wide range of materials proprieties including energetics, structure at the atomic level, vibrational properties, and many experimental characterisation methods, such as infra-red and Raman spectra, NMR, and core-level spectra. This documentation This documentation focuses on using CASTEP at the command-line, as a stand-alone program. You can build two versions of CASTEP: a \"serial\" version called castep.serial , which is primarily designed to run on a single CPU core; or a parallel version called castep.mpi , which uses the message passing interface (MPI) to run on more than one core. Most of this documentation applies equally to both versions, but for simplicity we will focus on the serial version in most of the examples. We will refer to the CASTEP command itself as castep , which you will need to change to castep.serial or castep.mpi , as appropriate. In this documentation, anything in a fixed width font like this is text to type, either on the command-line or in a CASTEP input file. For CASTEP's input files, there is sometimes a choice between different settings, and this will be indicated using the | symbol, meaning \"or\". For example, setting : choice_1|choice_2|choice_3 If some of the entries are optional, they will have square brackets around them [like this] , for example: setting : choice_1|choice_2|choice_3 [unit of choice]","title":"Introduction"},{"location":"documentation/Getting_Started/intro/#this-documentation","text":"This documentation focuses on using CASTEP at the command-line, as a stand-alone program. You can build two versions of CASTEP: a \"serial\" version called castep.serial , which is primarily designed to run on a single CPU core; or a parallel version called castep.mpi , which uses the message passing interface (MPI) to run on more than one core. Most of this documentation applies equally to both versions, but for simplicity we will focus on the serial version in most of the examples. We will refer to the CASTEP command itself as castep , which you will need to change to castep.serial or castep.mpi , as appropriate. In this documentation, anything in a fixed width font like this is text to type, either on the command-line or in a CASTEP input file. For CASTEP's input files, there is sometimes a choice between different settings, and this will be indicated using the | symbol, meaning \"or\". For example, setting : choice_1|choice_2|choice_3 If some of the entries are optional, they will have square brackets around them [like this] , for example: setting : choice_1|choice_2|choice_3 [unit of choice]","title":"This documentation"},{"location":"documentation/Getting_Started/restarting/","text":"Checkpointing and Restarting CASTEP provides a mechanism for saving intermediate and final states of the calculation and for restarting or continuing from a saved state. At the end of every calculation which completes normally, CASTEP writes two files .check and .castep_bin which are binary-format files containing a complete state of the calculation including input parameters, cell variables, electron densities and any results or intermediate quantities whose calculation has completed. All inputs and results reported in the .castep file are saved to the checkpoint: indeed a lost .castep file from a completed calculation may be (mostly) regenerated using a minimal continuation run. .check vs .castep_bin The only difference between .check and .castep_bin is that the .check file contains the converged ground-state wavefunctions but .castep_bin does not, and therefore requires much less disk space to store. This makes it useful for purposes of archiving a calculation. When continuing from a .castep_bin CASTEP will regenerate the ground state wavefunctions non-selfconsistently using the ground-state density from the file. Checkpointing during a calculation An incomplete calculation can be completed in a new run by adding the parameters keyword continuation : default in the .param file and rerunning CASTEP as before with the same command-line argument. This is the usual way of continuing a run interrupted, for example, by the job time limit on a batch scheduling system. To benefit from continuation, a checkpoint file must have been written in the original run. There are three parameters keywords which may be used to do this: num_backup_iter write a checkpoint every (default 5) geometry MD or phonon steps backup_interval write a checkpoint every seconds run_time write a checkpoint and exit at the first opportunity after seconds have elapsed. These may be used to periodically checkpoint many lengthy post-SCF tasks including geometry optimization, MD, phonon calculations, but checkpointing of spectral and magres tasks is not supported via this mechanism. Neither is checkpointing possible within an extremely lengthy SCF calculation, but see the next section for an alternative. Checkpoint files are portable, and independent of data-distribution, so the continuation run may use a different number of parallel nodes, data distribution, OpenMP etc. They are also portable across computers, so a run may be started on one computer and finished on another, which may be helpful to balance use of computer resources. Advanced keywords One additional related parameters keyword which finds occasional use is a simple one-liner stop which can be added to the .param file while a run is in progress. CASTEP rereads the .param file at every checkpoint opportunity and if this is present will perform a graceful exit after writing the checkpoint files. Which periodic and end-of-run checkpoint files are written may be controlled by the parameters keyword write_checkpoint which takes values none : to suppress checkpoints completely minimal writes only .castep_bin all : writes both .check and .castep_bin Continuing from completed calculations The checkpoint/restart mechanism may also be used to \"chain\" runs or initialise a modified run with the results of a previous one. The .param file of the new run should contain continuation : .check Parameters values stored in and read from .check will be used, unless overridden by the new .param file, which therefore needs only a minimal number of entries. The .cell file is usually just copy of the original, but may also be modified if needed. Modifying task is a good way to \"chain\" calculations, for example performing a geometry optimisation followed by a spectral calculation. Info Not all parameter or cell keywords can be overridden upon continuation. castep --help will report whether a variable is modifiable on continuation","title":"Checkpoint and Restart"},{"location":"documentation/Getting_Started/restarting/#checkpointing-and-restarting","text":"CASTEP provides a mechanism for saving intermediate and final states of the calculation and for restarting or continuing from a saved state. At the end of every calculation which completes normally, CASTEP writes two files .check and .castep_bin which are binary-format files containing a complete state of the calculation including input parameters, cell variables, electron densities and any results or intermediate quantities whose calculation has completed. All inputs and results reported in the .castep file are saved to the checkpoint: indeed a lost .castep file from a completed calculation may be (mostly) regenerated using a minimal continuation run. .check vs .castep_bin The only difference between .check and .castep_bin is that the .check file contains the converged ground-state wavefunctions but .castep_bin does not, and therefore requires much less disk space to store. This makes it useful for purposes of archiving a calculation. When continuing from a .castep_bin CASTEP will regenerate the ground state wavefunctions non-selfconsistently using the ground-state density from the file.","title":"Checkpointing and Restarting"},{"location":"documentation/Getting_Started/restarting/#checkpointing-during-a-calculation","text":"An incomplete calculation can be completed in a new run by adding the parameters keyword continuation : default in the .param file and rerunning CASTEP as before with the same command-line argument. This is the usual way of continuing a run interrupted, for example, by the job time limit on a batch scheduling system. To benefit from continuation, a checkpoint file must have been written in the original run. There are three parameters keywords which may be used to do this: num_backup_iter write a checkpoint every (default 5) geometry MD or phonon steps backup_interval write a checkpoint every seconds run_time write a checkpoint and exit at the first opportunity after seconds have elapsed. These may be used to periodically checkpoint many lengthy post-SCF tasks including geometry optimization, MD, phonon calculations, but checkpointing of spectral and magres tasks is not supported via this mechanism. Neither is checkpointing possible within an extremely lengthy SCF calculation, but see the next section for an alternative. Checkpoint files are portable, and independent of data-distribution, so the continuation run may use a different number of parallel nodes, data distribution, OpenMP etc. They are also portable across computers, so a run may be started on one computer and finished on another, which may be helpful to balance use of computer resources. Advanced keywords One additional related parameters keyword which finds occasional use is a simple one-liner stop which can be added to the .param file while a run is in progress. CASTEP rereads the .param file at every checkpoint opportunity and if this is present will perform a graceful exit after writing the checkpoint files. Which periodic and end-of-run checkpoint files are written may be controlled by the parameters keyword write_checkpoint which takes values none : to suppress checkpoints completely minimal writes only .castep_bin all : writes both .check and .castep_bin","title":"Checkpointing during a calculation"},{"location":"documentation/Getting_Started/restarting/#continuing-from-completed-calculations","text":"The checkpoint/restart mechanism may also be used to \"chain\" runs or initialise a modified run with the results of a previous one. The .param file of the new run should contain continuation : .check Parameters values stored in and read from .check will be used, unless overridden by the new .param file, which therefore needs only a minimal number of entries. The .cell file is usually just copy of the original, but may also be modified if needed. Modifying task is a good way to \"chain\" calculations, for example performing a geometry optimisation followed by a spectral calculation. Info Not all parameter or cell keywords can be overridden upon continuation. castep --help will report whether a variable is modifiable on continuation","title":"Continuing from completed calculations"},{"location":"documentation/Getting_Started/running_castep/","text":"CASTEP has two main input files, called the cell file and the param file . The cell file defines the structure of the material (or molecule) you wish to study, and the param file defines the kind of simulation CASTEP should perform. The cell and param files should be named using the same prefix, which CASTEP calls the \"seedname\", with the extensions .cell and .param , respectively. For example, for a calculation called mytest , you need the input files mytest.cell mytest.param and the calculation is run with the command castep mytest The main CASTEP output file will be names using the same seedname and the .castep extension, i.e. in the above example it would be called mytest.castep . If this file already exists, CASTEP will append its output to it. When CASTEP completes successfully, it writes additional files such as the .bib file, which contains references to key papers for the theory and methods CASTEP used. If CASTEP encounters a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error files from each of these cores. They are named using the same seedname, but with the numeric process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them. See the Troubleshooting Guide for details of how to find and fix common problems.","title":"Running CASTEP"},{"location":"documentation/Groundstate/ELF/","text":"ELF - Electron Localization Function The ground state electron density, e.g. from a single point calculation or an MD run, etc. contains much useful information. It can be analysed in different ways, and the Electron Localization Function (ELF) is one such. This idea was originally created by Becke and Edgecombe 1 for the analysis of molecules. The idea was later extended to spin and then to solid state systems by Silvi and Savin 2 . It was later discovered that the theoretical expressions were not strictly positive definite, and so a correlation correction was added by Jarvis and Carter 3 , and it is this final form that has been implemented in CASTEP. ELF theory The ELF is given by \\begin{equation} ELF = \\frac{1}{1+\\left( D/D0 \\right)^2} \\end{equation} \\begin{equation} ELF = \\frac{1}{1+\\left( D/D0 \\right)^2} \\end{equation} and for Hartree-Fock approaches we have \\begin{equation} D = \\frac{\\sum{\\left| \\nabla \\psi \\right|^2}}{2} -\\frac{\\left(\\nabla n\\right)^2}{8*n} \\end{equation} with \\psi \\psi being the wavefunction and n n the electron number density, and \\begin{equation} D0 = 0.3*\\left(3*\\pi^2\\right)^{2/3}*n^{5/3} \\end{equation} \\begin{equation} D0 = 0.3*\\left(3*\\pi^2\\right)^{2/3}*n^{5/3} \\end{equation} with D0 D0 is the probability. Hence ELF measures the excess kinetic energy due to Pauli repulsion, and this definition is bounded 0 1 to get more information on what has been included in the D3 correction. In the current implementation, users cannot supply custom parameters for this correction scheme. SEDC_SCHEME : D3 SEDC_SCHEME : D3-BJ This is the Grimme D3 scheme with Becke-Johnson damping. Note When running a D3-BJ calculation with IPRINT > 1 , you might see Dispersion version: D4 in the .castep output file. Confusingly, this does not mean the Grimme D4 method has been used, it's just an interal CASTEP version label for this correction scheme. Compilation flags: for the D3 correction, CASTEP must be compiled with GRIMMED3 := compile Note that for the D3 correction to work, CASTEP must be compiled with the following flag: # Grimme D3 library support. Options are none or compile GRIMMED3 := compile in the Makefile For CASTEP 20, the D3 library is included in the distribution and the setting the flag above should be sufficient. D4 Generally applicable atomic-charge dependent London dispersion correction, termed DFT+D4. It is available from CASTEP 24.1 onwards via setting SEDC_SCHEME : D4 Note that D4 is made available via using the external dftd4 library. This library is included in the CASTEP 24.1 distribution and should be compiled by default when you build CASTEP. Restrictions: Default D4 parameters are available for the PBE, RPBE, PBESOL, BLYP, PW91 and RSCAN functionals. Exchange-dipole moment (XDM) method A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. Restrictions: Default XDM parameters are available for the following XC functionals: B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN SEDC_SCHEME : XDM For functionals that are not in this list, you need to specify the following additional parameters: Customisation keywords .param file SEDC_A1_XDM Type: Real (float) Level: Expert Description: Customisable A1 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default: 1.0. SEDC_A2_XDM Type: Physical (float) Level: Expert Description: Customisable A2 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SC_XDM Type: Real (float) Level: Expert Description: Customisable SC value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_C9_XDM Type: Logical Level: Basic Description: Specifies whether three-body dispersion coefficients are to be computed in the XDM semi-empirical dispersion/ van der Waals correction scheme. Modifiable: restart and on the fly Allowed values: TRUE or FALSE Default is FALSE Note that if you wish to experiment with these values, for example to test a new functional, then careful further testing is necessary. Other Schemes SEDC_SCHEME : OBS Ortmann, Bechstedt and Schmidt Semiempirical van der Waals correction to the density functional description of solids and molecular structures Customisation keywords .param file \" SEDC_LAMBDA_OBS \" Type: Real (float) Level: Expert Description: Customisable lambda value for damping function in the the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . \" SEDC_N_OBS \" Type: Real (float) Level: Expert Description: Customisable n value for the damping function in the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SCHEME : JCHS Jure\u010dka, \u010cern\u00fd, Hobza and Salahub Customisation keywords .param file SEDC_SR_JCHS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_S6_JCHS Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_JCHS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . Stefan Grimme, Andreas Hansen, Jan Gerit Brandenburg, and Christoph Bannwarth. Dispersion-corrected mean-field electronic structure methods. Chemical Reviews , 116(9):5105\u20135154, 2016. PMID: 27077966. doi:10.1021/acs.chemrev.5b00533 . \u21a9 Kyuho Lee, \u00c9amonn D. Murray, Lingzhu Kong, Bengt I. Lundqvist, and David C. Langreth. Higher-accuracy van der Waals density functional. Phys. Rev. B , 82:081101, Aug 2010. doi:10.1103/PhysRevB.82.081101 . \u21a9 Kristian Berland and Per Hyldgaard. Exchange functional that tests the robustness of the plasmon description of the van der Waals density functional. Phys. Rev. B , 89:035412, Jan 2014. doi:10.1103/PhysRevB.89.035412 . \u21a9 Oleg A. Vydrov and Troy Van Voorhis. Nonlocal van der Waals density functional: The simpler the better. The Journal of Chemical Physics , 133(24):244103, 12 2010. doi:10.1063/1.3521275 . \u21a9 Yan Zhao and Donald G. Truhlar. The M06 suite of density functionals for main group thermochemistry, thermochemical kinetics, noncovalent interactions, excited states, and transition elements: two new functionals and systematic testing of four M06-class functionals and 12 other functionals. Theoretical Chemistry Accounts , 120(1):215\u2013241, May 2008. doi:10.1007/s00214-007-0310-x . \u21a9 Jeffrey A. van Santen and Gino A. DiLabio. Dispersion corrections improve the accuracy of both noncovalent and covalent interactions energies predicted by a density-functional theory approximation. The Journal of Physical Chemistry A , 119(25):6703\u20136713, 2015. PMID: 26030132. doi:10.1021/acs.jpca.5b02809 . \u21a9 Grygoriy A. Dolgonos, Johannes Hoja, and A. Daniel Boese. Revised values for the x23 benchmark set of molecular crystals. Phys. Chem. Chem. Phys. , 21:24333\u201324344, 2019. doi:10.1039/C9CP04488D . \u21a9 Ji\u0159\u00ed Klime\u0161, David R. Bowler, and Angelos Michaelides. Van der Waals density functionals applied to solids. Phys. Rev. B , 83:195131, May 2011. doi:10.1103/PhysRevB.83.195131 . \u21a9 Alexandre Tkatchenko and Matthias Scheffler. Accurate molecular van der Waals interactions from ground-state electron density and free-atom reference data. Phys. Rev. Lett. , 102:073005, Feb 2009. doi:10.1103/PhysRevLett.102.073005 . \u21a9 Victor G. Ruiz, Wei Liu, Egbert Zojer, Matthias Scheffler, and Alexandre Tkatchenko. Density-functional theory with screened van der Waals interactions for the modeling of hybrid inorganic-organic systems. Phys. Rev. Lett. , 108:146103, Apr 2012. doi:10.1103/PhysRevLett.108.146103 . \u21a9 Alexandre Tkatchenko, Robert A. DiStasio, Roberto Car, and Matthias Scheffler. Accurate and efficient method for many-body van der Waals interactions. Phys. Rev. Lett. , 108:236402, Jun 2012. doi:10.1103/PhysRevLett.108.236402 . \u21a9 \u21a9 Alberto Ambrosetti, Anthony M. Reilly, Robert A. DiStasio, Jr., and Alexandre Tkatchenko. Long-range correlation energy calculated from coupled atomic response functions. The Journal of Chemical Physics , 140(18):18A508, 02 2014. doi:10.1063/1.4865104 . \u21a9 Stefan Grimme. Semiempirical GGA-type density functional constructed with a long-range dispersion correction. Journal of Computational Chemistry , 27(15):1787\u20131799, 2006. doi:https://doi.org/10.1002/jcc.20495 . \u21a9 Stefan Grimme, Jens Antony, Stephan Ehrlich, and Helge Krieg. A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu. The Journal of Chemical Physics , 132(15):154104, 04 2010. doi:10.1063/1.3382344 . \u21a9 Stefan Grimme, Stephan Ehrlich, and Lars Goerigk. Effect of the damping function in dispersion corrected density functional theory. Journal of Computational Chemistry , 32(7):1456\u20131465, 2011. arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/jcc.21759 , doi:https://doi.org/10.1002/jcc.21759 . \u21a9 Eike Caldeweyher, Christoph Bannwarth, and Stefan Grimme. Extension of the d3 dispersion coefficient model. The Journal of Chemical Physics , July 2017. URL: http://dx.doi.org/10.1063/1.4993215 , doi:10.1063/1.4993215 . \u21a9 Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph Bannwarth, and Stefan Grimme. A generally applicable atomic-charge dependent london dispersion correction. The Journal of Chemical Physics , April 2019. URL: http://dx.doi.org/10.1063/1.5090222 , doi:10.1063/1.5090222 . \u21a9 Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. Extension and evaluation of the d4 london-dispersion model for periodic systems. Physical Chemistry Chemical Physics , 22(16):8499\u20138512, 2020. URL: http://dx.doi.org/10.1039/D0CP00502A , doi:10.1039/d0cp00502a . \u21a9 F. Ortmann, F. Bechstedt, and W. G. Schmidt. Semiempirical van der Waals correction to the density functional description of solids and molecular structures. Phys. Rev. B , 73:205101, May 2006. doi:10.1103/PhysRevB.73.205101 . \u21a9 Petr Jure\u010dka, Ji\u0159\u00ed \u010cern\u00fd, Pavel Hobza, and Dennis R. Salahub. Density functional theory augmented with an empirical dispersion term. Interaction energies and geometries of 80 noncovalent complexes compared with ab initio quantum mechanics calculations. Journal of Computational Chemistry , 28(2):555\u2013569, 2007. doi:10.1002/jcc.20570 . \u21a9 Axel D. Becke and Erin R. Johnson. A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. The Journal of Chemical Physics , 127(12):124108, 09 2007. doi:10.1063/1.2768530 . \u21a9 Daniel G. A. Smith, Lori A. Burns, Konrad Patkowski, and C. David Sherrill. Revised damping parameters for the d3 dispersion correction to density functional theory. The Journal of Physical Chemistry Letters , 7(12):2197\u20132203, 2016. PMID: 27203625. doi:10.1021/acs.jpclett.6b00780 . \u21a9","title":"Dispersion Corrections"},{"location":"documentation/Groundstate/dftd/#long-range-dispersion-corrections","text":"","title":"Long-range dispersion corrections"},{"location":"documentation/Groundstate/dftd/#background","text":"","title":"Background"},{"location":"documentation/Groundstate/dftd/#why-and-when-are-long-range-dispersion-methods-needed","text":"Van der Waals (vdW) interactions are ubiquitous in nature but aren't accounted for by standard local and semilocal density functional approximations (i.e. LDA or GGAs). In particular, the long-range attractive part of the vdW interaction between system components (London dispersion interaction) is not captured. Including such dispersion effects is essential for accurately describing certain systems, especially for systems that are not bound ionically or covalently, e.g. gas molecules. The use of a dispersion method is strongly recommended when intermolecular interactions are expected to play a key role such as in molecular crystals, stacked 2D materials, and generally any weakly-bound system.","title":"Why and when are long range-dispersion methods needed?"},{"location":"documentation/Groundstate/dftd/#types-of-correction-schemes","text":"There are several families of dispersion methods. A good summary of these can be found in the 2016 review by Grimme et al . 1 We will summarise these categories here and, for those implemented in CASTEP, link to the relevant keywords. Semiempirical/semiclassical treatments Here the dispersion energy is calculated atom-wise (typically pair-wise) and is added to the DFT energy of the underlying functional. Note that a specific damping parameter (and function) is usually used to combine a given underlying functional (e.g. PBE) with a dispersion correction (e.g. D3). This means, for example, that the D3 correction to the PBE functional may be different to the D3 correction to HSE. Methods include: The Tkatchenko\u2212Scheffler scheme ( TS ) The TS-based many-body dispersion scheme ( MBD ) Grimme's D2 and D3 methods The exchange-dipole moment model ( XDM ) Nonlocal density-based treatments (not implemented in CASTEP) Here non-local functionals of the electronic density are constructed. Methods include the van der Waals functionals (e.g. vdW-DF2 2 and vdW-DF-cx 3 ) and Vydrov and Van Voorhis functionals 4 . Effective one-electron potentials (not implemented in CASTEP) Finally, the many-body correlated motion of electrons can be, to some extent, captured empiricially by using effective one-electron potentials. Examples of these include: semi-local functionals such as the Minnesota functionals (e.g. M06 5 ) and external potentials such as the dispersion-corrected atom-centered potentials (e.g. van Santen and DiLabio, 2015 6 ).","title":"Types of correction schemes"},{"location":"documentation/Groundstate/dftd/#general-recommendations","text":"Every application will have its own set of important features and it is not possible to say with certainty which density functional approximation will be the most appropriate. With that said, here are some suggestions for different types of materials: Molecular crystals: D3-BJ/XDM/MBD in combination with GGA or hybrid functionals (Dolgonos et al ., 2019 7 ). Metals: vdW-DFs developed with solid state materials in mind (Klime\u0161 et al ., 2011 8 ). Interactions between molecules and surfaces of metals: vdW-DFs or dispersion methods that include screening, e.g. TSSCS MOFs: dispersion corrected (e.g. TS, D3, etc.) GGAs Layered vdW materials: Beyond pairwise approaches, e.g. D3-BJ* or MBD. ^* ^* See note below for how to include the three-body terms in the CASTEP D3 correction. Again, please do your own testing and consult relevant reviews and benchmarking papers. For the TS, MBD and XDM methods you may get a warning if your unit cell is small (where the lattice constants are comparable to the vdW radii). This has been fixed in academic CASTEP v24.1 for TS and MBD, and in v25 for XDM. If you are using an older version of CASTEP, then you should try to use larger unit cells until your dispersion correction converges. Not all XC_FUNCTIONAL values are supported for all schemes - if in doubt use PBE. The primary 'XC_FUNCTIONAL' for XDM is B86PBE. Each scheme has default parameters defined for a subset of elements (see table below). For other elements you need to define custom parameters using the SEDC_CUSTOM_PARAMS keyword in the .cell file.","title":"General recommendations"},{"location":"documentation/Groundstate/dftd/#using-dispersion-corrections-in-castep","text":"","title":"Using dispersion corrections in CASTEP"},{"location":"documentation/Groundstate/dftd/#param-file-keywords","text":"In the .param file, set: SEDC_APPLY : true turns on dispersion correction. SEDC_SCHEME : The semi-empirical dispersion/van der Waals correction scheme to use. Default is NONE , other possible values listed in the table below. SEDC_SCHEME Available from CASTEP version Compatible XC functionals Elements supported Stresses Phonons ^* ^* TS 9 Predates 2012 PBE, PBE0, PBE1PBE, BLYP, B3LYP, AM0, RPB, PBESOL, PW91 Up to Z=54 with first row Lanthanides Analytic DFPT & FD TSSURF 10 Not sure if working TSSCS 11 Not sure if working Up to Z=54 with first row Lanthanides Analytic MBD (Alias: MBD*) 11 12 2015? Rewritten (and fixed) for CASTEP 18 PBE, PBE0, PBE1PBE, HSE03, HSE06, RSCAN Up to Z=54 with first row Lanthanides Numeric FD G06 (= D2) 13 Predates 2012 PBE, BLYP, BP86, B3LYP, TPSS Up to Z= 54 Analytic DFPT & FD D3 14 CASTEP 20 ( Compilation instructions ) PBE, PBE0, HF Analytic FD D3-BJ 15 CASTEP 20 ( Compilation instructions ) PBE, PBE0, HF Analytic FD D4 16 17 18 CASTEP 24.1 PBE, RPBE, PBESOL, BLYP, PW91, RSCAN Analytic FD OBS 19 Predates 2012 LDA, PW91 Up to Z=57 Analytic DFPT & FD JCHS 20 Predates 2012 PBE, BLYP, B3LYP, TPSS H, C, N, O, F, Cl, Br Analytic DFPT & FD XDM 21 CASTEP 20 B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN Up to Z=102 Analytic FD ^* ^* DFPT: Density functional perturbation theory; FD: finite displacement. All of the above methods support analytic forces.","title":".param file keywords"},{"location":"documentation/Groundstate/dftd/#cell-file-keywords","text":"In the .cell file you can optionally set custom parameters for each species: C6 (eV \u00c5 ^6 ^6 ): Available for TS, MBD*, and Grimme schemes. R0 (\u00c5): Available for TS, MBD*, and Grimme schemes. alpha (\u00c5 ^3 ^3 ): Available for TS, MBD*, and OBS schemes. I (eV): Available for the OBS scheme. Rvdw (\u00c5): Available for the OBS scheme. You set them like this: %BLOCK SEDC_CUSTOM_PARAMS ! example values for test purposes only - don't use these... ! He C6:1.00 R0:2.00 Ne C6:10.00 R0:4.00 %ENDBLOCK SEDC_CUSTOM_PARAMS","title":".cell file keywords"},{"location":"documentation/Groundstate/dftd/#method-details-and-customisation","text":"","title":"Method details and customisation"},{"location":"documentation/Groundstate/dftd/#tkatchenkoscheffler-schemes","text":"A density-dependent, atom pairwise dispersion-correction scheme. SEDC_SCHEME : TS Restrictions: Can only be used with the following XC functionals: PBE, PBE0, PBE1PBE, BLYP, B3LYP, AM0, RPB, PBESOL, PW91 Elements up to Z=54 (Xe) together with first row Lanthanides are supported. SEDC_SCHEME : TSSCS TS with self-consistent screening SEDC_SCHEME : TSSURF Customisation keywords for all TS schemes .param file SEDC_SR_TS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the TS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_TS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the TS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For the TS methods, C6 (eV \u00c5 ^6 ^6 ), R0 (\u00c5) and alpha (\u00c5 ^3 ^3 ) can be customised.","title":"Tkatchenko\u2212Scheffler schemes"},{"location":"documentation/Groundstate/dftd/#many-body-dispersion","text":"Beyond what can be included in simple pairwise dispersion approaches, MBD introduces: (1) many-body energy (Axilrod-Teller and higher-order) and (2) long-range Coulomb response (screening) that serves to modify the polarizabilities of interacting species. SEDC_SCHEME : MBD (Alias: MBD* ) Note that the two aliases MBD and MBD* both refer to the revised version of MBD which employs range-separation (rs) of the self-consistent screening (SCS) of polarizabilities and the calculation of the long-range correlation energy, i.e. the MBD@rs-scs method. Restrictions: Can only be used with the following XC functionals: PBE, PBE0, PBE1PBE, HSE03, HSE06, RSCAN Elements up to Z=54 (Xe) together with first row Lanthanides are supported. Note that in the current implementation, only numeric stresses are available. Customisation keywords for MBD scheme .param file SEDC_SR_TS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the TS and MBD correction schemes. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_TS Type: Real (float) Level: Expert Description: Customisable d value for the damping functionin the TS and MBD correction schemes. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For the MBD method, C6 (eV \u00c5 ^6 ^6 ), R0 (\u00c5) and alpha (\u00c5 ^3 ^3 ) can be customised.","title":"Many-body dispersion"},{"location":"documentation/Groundstate/dftd/#grimme-d-corrections","text":"D2 Note that default D2 parameters are available only for the PBE, BLYP, BP86, B3LYP, TPSS functionals. You can also customise the correction parameters using the following keywords: SEDC_SCHEME : G06 Note This is CASTEP's name for the Grimme D2 correction Customisation keywords G06 .param file SEDC_S6_G06 Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the G06 semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_G06 Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the G06 semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . .cell file SEDC_CUSTOM_PARAMS Type: Block Level: Basic Description: Customized parameters for semi-empirical dispersion corrections. Used to calculate van der Waals forces. Default value for each species is determined by the chosen semiempirical correction scheme. For Grimme's D2 method, C6 (eV \u00c5 ^6 ^6 ) and R0 (\u00c5) can be customised. D3 Grimme's DFT-D3 method. The D3 scheme with Becke-Johnson damping (D3-BJ) is generally more accurate 22 than the 'zero-damping' method (D3). Note that most published results for \"D3\" are actually \"D3-BJ\", and that the original version of D3 is rarely used any more. Restrictions: Default D3 parameters are available for the PBE, PBE0 and HF functionals. By default the three-body term is not included . To include it, set d3_threebody: True within a devel_code block in the .param file. Turn on IPRINT > 1 to get more information on what has been included in the D3 correction. In the current implementation, users cannot supply custom parameters for this correction scheme. SEDC_SCHEME : D3 SEDC_SCHEME : D3-BJ This is the Grimme D3 scheme with Becke-Johnson damping. Note When running a D3-BJ calculation with IPRINT > 1 , you might see Dispersion version: D4 in the .castep output file. Confusingly, this does not mean the Grimme D4 method has been used, it's just an interal CASTEP version label for this correction scheme. Compilation flags: for the D3 correction, CASTEP must be compiled with GRIMMED3 := compile Note that for the D3 correction to work, CASTEP must be compiled with the following flag: # Grimme D3 library support. Options are none or compile GRIMMED3 := compile in the Makefile For CASTEP 20, the D3 library is included in the distribution and the setting the flag above should be sufficient. D4 Generally applicable atomic-charge dependent London dispersion correction, termed DFT+D4. It is available from CASTEP 24.1 onwards via setting SEDC_SCHEME : D4 Note that D4 is made available via using the external dftd4 library. This library is included in the CASTEP 24.1 distribution and should be compiled by default when you build CASTEP. Restrictions: Default D4 parameters are available for the PBE, RPBE, PBESOL, BLYP, PW91 and RSCAN functionals.","title":"Grimme D corrections"},{"location":"documentation/Groundstate/dftd/#exchange-dipole-moment-xdm-method","text":"A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. Restrictions: Default XDM parameters are available for the following XC functionals: B86PBE, PBE, BLYP, PBESOL, PW91, RPBE, WC, RSCAN SEDC_SCHEME : XDM For functionals that are not in this list, you need to specify the following additional parameters: Customisation keywords .param file SEDC_A1_XDM Type: Real (float) Level: Expert Description: Customisable A1 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default: 1.0. SEDC_A2_XDM Type: Physical (float) Level: Expert Description: Customisable A2 value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SC_XDM Type: Real (float) Level: Expert Description: Customisable SC value for the damping function in the XDM semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_C9_XDM Type: Logical Level: Basic Description: Specifies whether three-body dispersion coefficients are to be computed in the XDM semi-empirical dispersion/ van der Waals correction scheme. Modifiable: restart and on the fly Allowed values: TRUE or FALSE Default is FALSE Note that if you wish to experiment with these values, for example to test a new functional, then careful further testing is necessary.","title":"Exchange-dipole moment (XDM) method"},{"location":"documentation/Groundstate/dftd/#other-schemes","text":"SEDC_SCHEME : OBS Ortmann, Bechstedt and Schmidt Semiempirical van der Waals correction to the density functional description of solids and molecular structures Customisation keywords .param file \" SEDC_LAMBDA_OBS \" Type: Real (float) Level: Expert Description: Customisable lambda value for damping function in the the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . \" SEDC_N_OBS \" Type: Real (float) Level: Expert Description: Customisable n value for the damping function in the OBS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_SCHEME : JCHS Jure\u010dka, \u010cern\u00fd, Hobza and Salahub Customisation keywords .param file SEDC_SR_JCHS Type: Real (float) Level: Expert Description: Customisable SR value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_S6_JCHS Type: Real (float) Level: Expert Description: Customisable S6 value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . SEDC_D_JCHS Type: Real (float) Level: Expert Description: Customisable d value for the damping function in the JCHS semi-empirical dispersion/van der Waals correction scheme. Modifiable: restart and on the fly Default is determined by XC_FUNCTIONAL . Stefan Grimme, Andreas Hansen, Jan Gerit Brandenburg, and Christoph Bannwarth. Dispersion-corrected mean-field electronic structure methods. Chemical Reviews , 116(9):5105\u20135154, 2016. PMID: 27077966. doi:10.1021/acs.chemrev.5b00533 . \u21a9 Kyuho Lee, \u00c9amonn D. Murray, Lingzhu Kong, Bengt I. Lundqvist, and David C. Langreth. Higher-accuracy van der Waals density functional. Phys. Rev. B , 82:081101, Aug 2010. doi:10.1103/PhysRevB.82.081101 . \u21a9 Kristian Berland and Per Hyldgaard. Exchange functional that tests the robustness of the plasmon description of the van der Waals density functional. Phys. Rev. B , 89:035412, Jan 2014. doi:10.1103/PhysRevB.89.035412 . \u21a9 Oleg A. Vydrov and Troy Van Voorhis. Nonlocal van der Waals density functional: The simpler the better. The Journal of Chemical Physics , 133(24):244103, 12 2010. doi:10.1063/1.3521275 . \u21a9 Yan Zhao and Donald G. Truhlar. The M06 suite of density functionals for main group thermochemistry, thermochemical kinetics, noncovalent interactions, excited states, and transition elements: two new functionals and systematic testing of four M06-class functionals and 12 other functionals. Theoretical Chemistry Accounts , 120(1):215\u2013241, May 2008. doi:10.1007/s00214-007-0310-x . \u21a9 Jeffrey A. van Santen and Gino A. DiLabio. Dispersion corrections improve the accuracy of both noncovalent and covalent interactions energies predicted by a density-functional theory approximation. The Journal of Physical Chemistry A , 119(25):6703\u20136713, 2015. PMID: 26030132. doi:10.1021/acs.jpca.5b02809 . \u21a9 Grygoriy A. Dolgonos, Johannes Hoja, and A. Daniel Boese. Revised values for the x23 benchmark set of molecular crystals. Phys. Chem. Chem. Phys. , 21:24333\u201324344, 2019. doi:10.1039/C9CP04488D . \u21a9 Ji\u0159\u00ed Klime\u0161, David R. Bowler, and Angelos Michaelides. Van der Waals density functionals applied to solids. Phys. Rev. B , 83:195131, May 2011. doi:10.1103/PhysRevB.83.195131 . \u21a9 Alexandre Tkatchenko and Matthias Scheffler. Accurate molecular van der Waals interactions from ground-state electron density and free-atom reference data. Phys. Rev. Lett. , 102:073005, Feb 2009. doi:10.1103/PhysRevLett.102.073005 . \u21a9 Victor G. Ruiz, Wei Liu, Egbert Zojer, Matthias Scheffler, and Alexandre Tkatchenko. Density-functional theory with screened van der Waals interactions for the modeling of hybrid inorganic-organic systems. Phys. Rev. Lett. , 108:146103, Apr 2012. doi:10.1103/PhysRevLett.108.146103 . \u21a9 Alexandre Tkatchenko, Robert A. DiStasio, Roberto Car, and Matthias Scheffler. Accurate and efficient method for many-body van der Waals interactions. Phys. Rev. Lett. , 108:236402, Jun 2012. doi:10.1103/PhysRevLett.108.236402 . \u21a9 \u21a9 Alberto Ambrosetti, Anthony M. Reilly, Robert A. DiStasio, Jr., and Alexandre Tkatchenko. Long-range correlation energy calculated from coupled atomic response functions. The Journal of Chemical Physics , 140(18):18A508, 02 2014. doi:10.1063/1.4865104 . \u21a9 Stefan Grimme. Semiempirical GGA-type density functional constructed with a long-range dispersion correction. Journal of Computational Chemistry , 27(15):1787\u20131799, 2006. doi:https://doi.org/10.1002/jcc.20495 . \u21a9 Stefan Grimme, Jens Antony, Stephan Ehrlich, and Helge Krieg. A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu. The Journal of Chemical Physics , 132(15):154104, 04 2010. doi:10.1063/1.3382344 . \u21a9 Stefan Grimme, Stephan Ehrlich, and Lars Goerigk. Effect of the damping function in dispersion corrected density functional theory. Journal of Computational Chemistry , 32(7):1456\u20131465, 2011. arXiv:https://onlinelibrary.wiley.com/doi/pdf/10.1002/jcc.21759 , doi:https://doi.org/10.1002/jcc.21759 . \u21a9 Eike Caldeweyher, Christoph Bannwarth, and Stefan Grimme. Extension of the d3 dispersion coefficient model. The Journal of Chemical Physics , July 2017. URL: http://dx.doi.org/10.1063/1.4993215 , doi:10.1063/1.4993215 . \u21a9 Eike Caldeweyher, Sebastian Ehlert, Andreas Hansen, Hagen Neugebauer, Sebastian Spicher, Christoph Bannwarth, and Stefan Grimme. A generally applicable atomic-charge dependent london dispersion correction. The Journal of Chemical Physics , April 2019. URL: http://dx.doi.org/10.1063/1.5090222 , doi:10.1063/1.5090222 . \u21a9 Eike Caldeweyher, Jan-Michael Mewes, Sebastian Ehlert, and Stefan Grimme. Extension and evaluation of the d4 london-dispersion model for periodic systems. Physical Chemistry Chemical Physics , 22(16):8499\u20138512, 2020. URL: http://dx.doi.org/10.1039/D0CP00502A , doi:10.1039/d0cp00502a . \u21a9 F. Ortmann, F. Bechstedt, and W. G. Schmidt. Semiempirical van der Waals correction to the density functional description of solids and molecular structures. Phys. Rev. B , 73:205101, May 2006. doi:10.1103/PhysRevB.73.205101 . \u21a9 Petr Jure\u010dka, Ji\u0159\u00ed \u010cern\u00fd, Pavel Hobza, and Dennis R. Salahub. Density functional theory augmented with an empirical dispersion term. Interaction energies and geometries of 80 noncovalent complexes compared with ab initio quantum mechanics calculations. Journal of Computational Chemistry , 28(2):555\u2013569, 2007. doi:10.1002/jcc.20570 . \u21a9 Axel D. Becke and Erin R. Johnson. A unified density-functional treatment of dynamical, nondynamical, and dispersion correlations. The Journal of Chemical Physics , 127(12):124108, 09 2007. doi:10.1063/1.2768530 . \u21a9 Daniel G. A. Smith, Lori A. Burns, Konrad Patkowski, and C. David Sherrill. Revised damping parameters for the d3 dispersion correction to density functional theory. The Journal of Physical Chemistry Letters , 7(12):2197\u20132203, 2016. PMID: 27203625. doi:10.1021/acs.jpclett.6b00780 . \u21a9","title":"Other Schemes"},{"location":"documentation/Groundstate/intro/","text":"One of the most fundamental tasks for CASTEP is to take a crystal lattice and set of atomic positions, and compute the electronic density and total energy. Once the lattice and atomic positions have been specified, you can tell CASTEP to compute the energy by setting the task keyword in the param file : task : energy Your cell and param files should be named using the same prefix, which CASTEP calls the \"seedname\", and the extensions .cell and .param , respectively. For example, for a calculation called mytest , you need the input files mytest.cell mytest.param and the calculation is run with the command castep mytest CASTEP computes the energy by solving the Kohn-Sham equations iteratively, using the 'self-consistent field' (SCF) method.","title":"Overview"},{"location":"documentation/Groundstate/nlxc/","text":"","title":"Nlxc"},{"location":"documentation/Groundstate/population_analysis/","text":"Population analysis At the end of a single point calculation, the ground state electron density is obtained. The electrons are distributed such that the total energy functional is minimised, meaning that they do not belong to individual atoms anymore. However, it is often useful as well as insightful to partition the total electron density to atomic or bond contributions. While such population analyses have no direct connection to experimental observables, they provide a chemical interpretation of possible charge transfer within the system. There are many flavours of charge partitioning, of which CASTEP can perform the Mulliken population analysis 1 (see also part II 2 , part III 3 and part IV 4 ) and the Hirshfeld definition 5 . Mulliken population analysis The total number of electrons N N of a quantum mechanical system can be found by evaluating the sum \\begin{equation} N = \\sum _ \\mu (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\end{equation} where \\mathbf{P} \\mathbf{P} and \\mathbf{S} \\mathbf{S} are the density and overlap matrices expressed in a suitable basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} , respectively. The overlap matrix elements are obtained as \\begin{equation} S _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} The density matrix results from evaluating the density operator using the basis set \\begin{equation} P _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\hat{P} | \\chi _ \\nu \\rangle \\end{equation} where the single-particle density operator is expressed in terms of the single-particle wavefunctions \\psi _ i \\psi _ i and the corresponding occupancies f _ i f _ i as \\begin{equation} \\hat{P} = \\sum _ i f _ i \\; |\\psi _ i \\rangle \\langle \\psi _ i | \\textrm{,} \\end{equation} therefore \\begin{equation} P _ {\\mu\\nu} = \\sum _ i f _ i \\; \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\psi _ i | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} If the basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} is local (i.e. functions with compact support), individual terms (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} in the total charge expression may be associated with the spatial region corresponding to the individual basis function \\chi _ \\mu \\chi _ \\mu . If these basis functions are centred on atoms, the contributions belonging to a particular atom A A are defined as the charge of A A : \\begin{equation} N _ A = \\sum _ {\\mu \\in A} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\textrm{.} \\end{equation} Conveniently, the off-diagonal elements of \\mathbf{P} \\mathbf{S} \\mathbf{P} \\mathbf{S} are partitioned into bond contributions between atoms A A and B B as \\begin{equation} N _ {AB} = \\sum _ {\\mu \\in A} \\sum _ {\\nu \\in B} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\nu} \\textrm{.} \\end{equation} To assign a charge to an atom, \\begin{equation} q _ A = Z' _ A - N _ A \\end{equation} is calculated, where Z' Z' is the pseudoatom nuclear charge. The CASTEP implementation In CASTEP, the solution of the electronic problem results in a set of Kohn-Sham orbitals \\psi _ i \\psi _ i , which are expressed in terms of plane-wave functions. Plane-waves are non-local, therefore not directly suitable for Mulliken population analysis. In order to obtain a suitable local basis, CASTEP solves the electronic problem of the isolated atom for each atomic specie present in the system, resulting in a set of atomic orbitals \\chi _ \\mu \\chi _ \\mu . Note that for this set of calculations, the same calculation settings (e.g. electronic cutoff and pseudopotentials) are used. With the atomic orbitals determined, the Mulliken population analysis can be performed by calculating the projections \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\chi _ \\mu | \\psi _ i \\rangle . CASTEP keywords The default behaviour is to compute the population analysis on completion of most tasks that determine the ground state electron density. Mulliken population analysis can be turned off by adding POPN_CALCULATE : FALSE to the .param file. The bond population analysis is computed between all atoms which are closer than a spatial cutoff (3 \u212b by default), which may be controlled using the .param keyword POPN_BOND_CUTOFF , for example POPN_BOND_CUTOFF : 4.0 to set the cutoff to 4 \u212b. To control the verbosity of the population analysis output, POPN_WRITE : ENHANCED which is the default setting, writes individual orbital as well as atomic and bond populations; POPN_WRITE : MINIMAL only writes atomic and bond populations; POPN_WRITE : NONE only writes bond populations. The .cell block SPECIES_LCAO_STATES controls the number of atomic orbitals, as specified by their main and angular quantum numbers, used for each atomic specie. By default, all valence states up to the next noble gas configuration are obtained and used in the population analysis, but these can be overridden, for example: %BLOCK SPECIES_LCAO_STATES H 3 %ENDBLOCK SPECIES_LCAO_STATES will use the 1s, 2s and 2p orbitals. Shallow core states, if explicitly treated as valance states, are included. For example, for atoms such as Na, where most pseudopotential definitions include shallow core states, 2s, 2p, 3s and 3p are all used in the population analysis. The Hirshfeld partitioning scheme The Hirshfeld population analysis partitions the total ground state electronic density \\rho(\\mathbf{r}) \\rho(\\mathbf{r}) into atomic densities using \\begin{equation} \\rho _ A(\\mathbf{r}) = w _ A(\\mathbf{r}) \\rho(\\mathbf{r}) \\end{equation} where w _ A(\\mathbf{r}) w _ A(\\mathbf{r}) is the sharing function belonging to atom A A . The sharing function is calculated from the spherically averaged isolated atom densities \\rho^\\textrm{isolated} \\rho^\\textrm{isolated} as \\begin{equation} w _ A(\\mathbf{r}) = \\frac{\\rho^\\textrm{isolated} _ A (\\mathbf{r})}{\\sum _ A \\rho^\\textrm{isolated} _ A (\\mathbf{r})} \\textrm{,} \\end{equation} where each \\rho^\\textrm{isolated} _ A \\rho^\\textrm{isolated} _ A is centred at the position \\mathbf{R} _ A \\mathbf{R} _ A of the nucleus of A A . The electronic charge attributed to atom A A is the integral \\begin{equation} N _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) \\textrm{,} \\end{equation} from which the total charge is obtained as \\begin{equation} q _ A = Z' _ A - N _ A \\textrm{.} \\end{equation} Other quantities, such as the volume of the bonded atom is calculated from the integral \\begin{equation} V _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) |\\mathbf{r} - \\mathbf{R} _ A|^3 \\textrm{,} \\end{equation} which are useful in other methods, such as the many-body and XDM ispersion schemes . The CASTEP implementation Similarly to the Mulliken population analysis, the ground state electron density of isolated atoms of every specie are determined in the post-processing step, using the same pseudopotential and calculation parameters as the main calculation. CASTEP keywords To switch on the Hirshfeld partitioning scheme, add CALCULATE_HIRSHFELD : TRUE to the .param file. This provides a basic analysis of the Hirshfeld charges. More information, such as atomic volumes, can be gained when using IPRINT : 2 or higher. R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. I. The Journal of Chemical Physics , 23(10):1833\u20131840, 10 1955. doi:10.1063/1.1740588 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. II. Overlap Populations, Bond Orders, and Covalent Bond Energies. The Journal of Chemical Physics , 23(10):1841\u20131846, 10 1955. doi:10.1063/1.1740589 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. III. Effects of Hybridization on Overlap and Gross AO Populations. The Journal of Chemical Physics , 23(12):2338\u20132342, 12 1955. doi:10.1063/1.1741876 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. IV. Bonding and Antibonding in LCAO and Valence\u2010Bond Theories. The Journal of Chemical Physics , 23(12):2343\u20132346, 12 1955. doi:10.1063/1.1741877 . \u21a9 F. L. Hirshfeld. Bonded-atom fragments for describing molecular charge densities. Theoretica chimica acta , 44(2):129\u2013138, Jun 1977. doi:10.1007/BF00549096 . \u21a9","title":"Population analysis"},{"location":"documentation/Groundstate/population_analysis/#population-analysis","text":"At the end of a single point calculation, the ground state electron density is obtained. The electrons are distributed such that the total energy functional is minimised, meaning that they do not belong to individual atoms anymore. However, it is often useful as well as insightful to partition the total electron density to atomic or bond contributions. While such population analyses have no direct connection to experimental observables, they provide a chemical interpretation of possible charge transfer within the system. There are many flavours of charge partitioning, of which CASTEP can perform the Mulliken population analysis 1 (see also part II 2 , part III 3 and part IV 4 ) and the Hirshfeld definition 5 .","title":"Population analysis"},{"location":"documentation/Groundstate/population_analysis/#mulliken-population-analysis","text":"The total number of electrons N N of a quantum mechanical system can be found by evaluating the sum \\begin{equation} N = \\sum _ \\mu (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\end{equation} where \\mathbf{P} \\mathbf{P} and \\mathbf{S} \\mathbf{S} are the density and overlap matrices expressed in a suitable basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} , respectively. The overlap matrix elements are obtained as \\begin{equation} S _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} The density matrix results from evaluating the density operator using the basis set \\begin{equation} P _ {\\mu\\nu} = \\langle \\chi _ \\mu | \\hat{P} | \\chi _ \\nu \\rangle \\end{equation} where the single-particle density operator is expressed in terms of the single-particle wavefunctions \\psi _ i \\psi _ i and the corresponding occupancies f _ i f _ i as \\begin{equation} \\hat{P} = \\sum _ i f _ i \\; |\\psi _ i \\rangle \\langle \\psi _ i | \\textrm{,} \\end{equation} therefore \\begin{equation} P _ {\\mu\\nu} = \\sum _ i f _ i \\; \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\psi _ i | \\chi _ \\nu \\rangle \\textrm{.} \\end{equation} If the basis set \\boldsymbol{\\chi} \\boldsymbol{\\chi} is local (i.e. functions with compact support), individual terms (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} in the total charge expression may be associated with the spatial region corresponding to the individual basis function \\chi _ \\mu \\chi _ \\mu . If these basis functions are centred on atoms, the contributions belonging to a particular atom A A are defined as the charge of A A : \\begin{equation} N _ A = \\sum _ {\\mu \\in A} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\mu} \\textrm{.} \\end{equation} Conveniently, the off-diagonal elements of \\mathbf{P} \\mathbf{S} \\mathbf{P} \\mathbf{S} are partitioned into bond contributions between atoms A A and B B as \\begin{equation} N _ {AB} = \\sum _ {\\mu \\in A} \\sum _ {\\nu \\in B} (\\mathbf{P} \\mathbf{S}) _ {\\mu\\nu} \\textrm{.} \\end{equation} To assign a charge to an atom, \\begin{equation} q _ A = Z' _ A - N _ A \\end{equation} is calculated, where Z' Z' is the pseudoatom nuclear charge.","title":"Mulliken population analysis"},{"location":"documentation/Groundstate/population_analysis/#the-castep-implementation","text":"In CASTEP, the solution of the electronic problem results in a set of Kohn-Sham orbitals \\psi _ i \\psi _ i , which are expressed in terms of plane-wave functions. Plane-waves are non-local, therefore not directly suitable for Mulliken population analysis. In order to obtain a suitable local basis, CASTEP solves the electronic problem of the isolated atom for each atomic specie present in the system, resulting in a set of atomic orbitals \\chi _ \\mu \\chi _ \\mu . Note that for this set of calculations, the same calculation settings (e.g. electronic cutoff and pseudopotentials) are used. With the atomic orbitals determined, the Mulliken population analysis can be performed by calculating the projections \\langle \\chi _ \\mu | \\psi _ i \\rangle \\langle \\chi _ \\mu | \\psi _ i \\rangle .","title":"The CASTEP implementation"},{"location":"documentation/Groundstate/population_analysis/#castep-keywords","text":"The default behaviour is to compute the population analysis on completion of most tasks that determine the ground state electron density. Mulliken population analysis can be turned off by adding POPN_CALCULATE : FALSE to the .param file. The bond population analysis is computed between all atoms which are closer than a spatial cutoff (3 \u212b by default), which may be controlled using the .param keyword POPN_BOND_CUTOFF , for example POPN_BOND_CUTOFF : 4.0 to set the cutoff to 4 \u212b. To control the verbosity of the population analysis output, POPN_WRITE : ENHANCED which is the default setting, writes individual orbital as well as atomic and bond populations; POPN_WRITE : MINIMAL only writes atomic and bond populations; POPN_WRITE : NONE only writes bond populations. The .cell block SPECIES_LCAO_STATES controls the number of atomic orbitals, as specified by their main and angular quantum numbers, used for each atomic specie. By default, all valence states up to the next noble gas configuration are obtained and used in the population analysis, but these can be overridden, for example: %BLOCK SPECIES_LCAO_STATES H 3 %ENDBLOCK SPECIES_LCAO_STATES will use the 1s, 2s and 2p orbitals. Shallow core states, if explicitly treated as valance states, are included. For example, for atoms such as Na, where most pseudopotential definitions include shallow core states, 2s, 2p, 3s and 3p are all used in the population analysis.","title":"CASTEP keywords"},{"location":"documentation/Groundstate/population_analysis/#the-hirshfeld-partitioning-scheme","text":"The Hirshfeld population analysis partitions the total ground state electronic density \\rho(\\mathbf{r}) \\rho(\\mathbf{r}) into atomic densities using \\begin{equation} \\rho _ A(\\mathbf{r}) = w _ A(\\mathbf{r}) \\rho(\\mathbf{r}) \\end{equation} where w _ A(\\mathbf{r}) w _ A(\\mathbf{r}) is the sharing function belonging to atom A A . The sharing function is calculated from the spherically averaged isolated atom densities \\rho^\\textrm{isolated} \\rho^\\textrm{isolated} as \\begin{equation} w _ A(\\mathbf{r}) = \\frac{\\rho^\\textrm{isolated} _ A (\\mathbf{r})}{\\sum _ A \\rho^\\textrm{isolated} _ A (\\mathbf{r})} \\textrm{,} \\end{equation} where each \\rho^\\textrm{isolated} _ A \\rho^\\textrm{isolated} _ A is centred at the position \\mathbf{R} _ A \\mathbf{R} _ A of the nucleus of A A . The electronic charge attributed to atom A A is the integral \\begin{equation} N _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) \\textrm{,} \\end{equation} from which the total charge is obtained as \\begin{equation} q _ A = Z' _ A - N _ A \\textrm{.} \\end{equation} Other quantities, such as the volume of the bonded atom is calculated from the integral \\begin{equation} V _ A = \\int \\mathrm{d} \\mathbf{r} \\rho _ A(\\mathbf{r}) |\\mathbf{r} - \\mathbf{R} _ A|^3 \\textrm{,} \\end{equation} which are useful in other methods, such as the many-body and XDM ispersion schemes .","title":"The Hirshfeld partitioning scheme"},{"location":"documentation/Groundstate/population_analysis/#the-castep-implementation_1","text":"Similarly to the Mulliken population analysis, the ground state electron density of isolated atoms of every specie are determined in the post-processing step, using the same pseudopotential and calculation parameters as the main calculation.","title":"The CASTEP implementation"},{"location":"documentation/Groundstate/population_analysis/#castep-keywords_1","text":"To switch on the Hirshfeld partitioning scheme, add CALCULATE_HIRSHFELD : TRUE to the .param file. This provides a basic analysis of the Hirshfeld charges. More information, such as atomic volumes, can be gained when using IPRINT : 2 or higher. R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. I. The Journal of Chemical Physics , 23(10):1833\u20131840, 10 1955. doi:10.1063/1.1740588 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2013MO Molecular Wave Functions. II. Overlap Populations, Bond Orders, and Covalent Bond Energies. The Journal of Chemical Physics , 23(10):1841\u20131846, 10 1955. doi:10.1063/1.1740589 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. III. Effects of Hybridization on Overlap and Gross AO Populations. The Journal of Chemical Physics , 23(12):2338\u20132342, 12 1955. doi:10.1063/1.1741876 . \u21a9 R. S. Mulliken. Electronic Population Analysis on LCAO\u2010MO Molecular Wave Functions. IV. Bonding and Antibonding in LCAO and Valence\u2010Bond Theories. The Journal of Chemical Physics , 23(12):2343\u20132346, 12 1955. doi:10.1063/1.1741877 . \u21a9 F. L. Hirshfeld. Bonded-atom fragments for describing molecular charge densities. Theoretica chimica acta , 44(2):129\u2013138, Jun 1977. doi:10.1007/BF00549096 . \u21a9","title":"CASTEP keywords"},{"location":"documentation/Groundstate/soc/","text":"keywords For a calculation of a non-spin polarised system with spin orbit coupling (e.g. GaAs) the following keywords should be set in the param file spin_treatment : vector spin_orbit_coupling : true spin_polarised : false relativistic_treatment : dirac If the system has a spin density (e.g. a ferromagnet or antiferromagnet) then the following keywords should be set in the para file spin_treatment : vector spin_orbit_coupling : true spin_polarised : true relativistic_treatment : dirac As the spin-orbit coupling is transmitted via the pseudopotential is is necessary to use j-dependent pseudopotentials. These can be read from file (UPF or uspso) or generated on the fly. At the moment the SOC19 set of OTFG norm-conserving potentials are suitable. These can be specified with the following block in the cell file ``` %block species_pot SOC19 %endblock species_pot Limitations","title":"Spin Orbit Coupling"},{"location":"documentation/Groundstate/soc/#keywords","text":"For a calculation of a non-spin polarised system with spin orbit coupling (e.g. GaAs) the following keywords should be set in the param file spin_treatment : vector spin_orbit_coupling : true spin_polarised : false relativistic_treatment : dirac If the system has a spin density (e.g. a ferromagnet or antiferromagnet) then the following keywords should be set in the para file spin_treatment : vector spin_orbit_coupling : true spin_polarised : true relativistic_treatment : dirac As the spin-orbit coupling is transmitted via the pseudopotential is is necessary to use j-dependent pseudopotentials. These can be read from file (UPF or uspso) or generated on the fly. At the moment the SOC19 set of OTFG norm-conserving potentials are suitable. These can be specified with the following block in the cell file ``` %block species_pot SOC19 %endblock species_pot","title":"keywords"},{"location":"documentation/Groundstate/soc/#limitations","text":"","title":"Limitations"},{"location":"documentation/Groundstate/spin_constraints/","text":"Introduction Spin constraints allow you to \u2018fix\u2019 the spins within DFT by adding an energy penalty to states which do not obey the constraint. These change the minimum energy state from being the normal ground state to only those which have the target spin. Theory Energy Penalty Function The easiest constraint is to fix the vector direction of the spin on a target atom. The energy penalty has the form: E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 (eq1), where is the penalty constant, \\mathbf{M}_I \\mathbf{M}_I is the magnetic moment of atom I I , defined by \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r where m(r) m(r) is the magnetization of the electrons at r r , and F_I(r) F_I(r) is a function approximating the electronic density of the atom I I . This integral sums up the total magnetic moments in a region around the atom. Eq (1) goes to zero as \\mathbf{M}_I \\mathbf{M}_I goes to \\mathbf{e}_I \\mathbf{e}_I and it is positive otherwise, so this leaves the target state unchanged and increases the energy of other states. The potential that arises from this can be found by taking the derivative of (1) with respect to the density: V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] This is a local potential that pushes the density towards the constrained state. The strength of this \u201cpush\u201d is changed by the penalty constant . Due to the factor (the spin operator), the potential only has components in the spin space and tries to rotate the direction of spin, but not change the magnitude. Energy Penalty Constant The energy penalty constant ( \\lambda \\lambda ) must be large enough to overcome any natural features of the energy landscape. That is, it must be big enough to make the target minimum be the actual minimum of the system. On the other hand, making this value too big causes the numerics to become difficult to solve. CASTEP is built to solve things that act like physical systems and various parameters have been tuned to make it fast at this. Values that are too big, push the system away from being like a physical system and make it take a very long time to converge. There are a few tricks that we can play to speed this up. The first is to start with a low value of the \\lambda \\lambda and then increase it gradually. We do this by starting with a very low value, waiting until the system is converged, and then checking if the constraints are actually fulfilled (ie \\mathbf{M}_I = \\mathbf{e}_I \\mathbf{M}_I = \\mathbf{e}_I . If not, we double \\lambda \\lambda and converge again. We repeat this until the constraint is obeyed. Using Magnetic Constraints To apply a constraint to an atom, you must specify the spin in the cell file and add the extra tag FIX_SPIN for each atom on which you want to apply a constraint to block positions_frac or positions_abs in cell: %block positions_frac Fe 0.0 0.0 0.0 spin 2 0 0 FIX_SPIN Ni 0.5 0.5 0.5 spin 1 1 0 Mn 0.3 0.4 0.0 %endblock positions_frac This will set the system up with two Fe atoms as follows: Element Initial Spin Spin Constraint Fe 2 0 0 Along 1 0 0 Ni 1 1 0 None Mn None None It will then do the procedure mentioned in the previous section, doubling \\lambda \\lambda to achieve the target constraints. You can only add FIX_SPIN to any atom that you have specified the spin for. Convergence Some of the magnetic states can be difficult to converge, as the penalty potential still does not end up looking like a physical system. This causes the calculation to take a huge number of steps to reach convergence (if it even gets there!) You almost certainly need to decrease the value of spin_mix_amp which has a default of 0.8 but should be much lower (eg 0.5 or even less) for many of these systems. Alternatively, you can use metals_method: EDFT which uses EDFT instead of density mixing and this can improve the convergence.","title":"Spin Constraints"},{"location":"documentation/Groundstate/spin_constraints/#introduction","text":"Spin constraints allow you to \u2018fix\u2019 the spins within DFT by adding an energy penalty to states which do not obey the constraint. These change the minimum energy state from being the normal ground state to only those which have the target spin.","title":"Introduction"},{"location":"documentation/Groundstate/spin_constraints/#theory","text":"","title":"Theory"},{"location":"documentation/Groundstate/spin_constraints/#energy-penalty-function","text":"The easiest constraint is to fix the vector direction of the spin on a target atom. The energy penalty has the form: E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 E_\\text{con} = \\lambda\\left(|\\mathbf{M}_I| - \\mathbf{e}_I \\cdot \\mathbf{M}_I\\right) \\geq 0 (eq1), where is the penalty constant, \\mathbf{M}_I \\mathbf{M}_I is the magnetic moment of atom I I , defined by \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r \\mathbf{M}_I = \\int_\\Omega \\mathbf{m}(\\mathbf{r}) F_I(\\mathbf{r}) d^3r where m(r) m(r) is the magnetization of the electrons at r r , and F_I(r) F_I(r) is a function approximating the electronic density of the atom I I . This integral sums up the total magnetic moments in a region around the atom. Eq (1) goes to zero as \\mathbf{M}_I \\mathbf{M}_I goes to \\mathbf{e}_I \\mathbf{e}_I and it is positive otherwise, so this leaves the target state unchanged and increases the energy of other states. The potential that arises from this can be found by taking the derivative of (1) with respect to the density: V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] V_\\text{con}(\\mathbf{r}) = \\lambda F_I(\\mathbf{r}) \\left[\\left(\\frac{\\mathbf{M}_I}{|\\mathbf{M}_I|} - \\mathbf{e}_I \\right) \\cdot \\sigma\\ \\right] This is a local potential that pushes the density towards the constrained state. The strength of this \u201cpush\u201d is changed by the penalty constant . Due to the factor (the spin operator), the potential only has components in the spin space and tries to rotate the direction of spin, but not change the magnitude.","title":"Energy Penalty Function"},{"location":"documentation/Groundstate/spin_constraints/#energy-penalty-constant","text":"The energy penalty constant ( \\lambda \\lambda ) must be large enough to overcome any natural features of the energy landscape. That is, it must be big enough to make the target minimum be the actual minimum of the system. On the other hand, making this value too big causes the numerics to become difficult to solve. CASTEP is built to solve things that act like physical systems and various parameters have been tuned to make it fast at this. Values that are too big, push the system away from being like a physical system and make it take a very long time to converge. There are a few tricks that we can play to speed this up. The first is to start with a low value of the \\lambda \\lambda and then increase it gradually. We do this by starting with a very low value, waiting until the system is converged, and then checking if the constraints are actually fulfilled (ie \\mathbf{M}_I = \\mathbf{e}_I \\mathbf{M}_I = \\mathbf{e}_I . If not, we double \\lambda \\lambda and converge again. We repeat this until the constraint is obeyed.","title":"Energy Penalty Constant"},{"location":"documentation/Groundstate/spin_constraints/#using-magnetic-constraints","text":"To apply a constraint to an atom, you must specify the spin in the cell file and add the extra tag FIX_SPIN for each atom on which you want to apply a constraint to block positions_frac or positions_abs in cell: %block positions_frac Fe 0.0 0.0 0.0 spin 2 0 0 FIX_SPIN Ni 0.5 0.5 0.5 spin 1 1 0 Mn 0.3 0.4 0.0 %endblock positions_frac This will set the system up with two Fe atoms as follows: Element Initial Spin Spin Constraint Fe 2 0 0 Along 1 0 0 Ni 1 1 0 None Mn None None It will then do the procedure mentioned in the previous section, doubling \\lambda \\lambda to achieve the target constraints. You can only add FIX_SPIN to any atom that you have specified the spin for.","title":"Using Magnetic Constraints"},{"location":"documentation/Groundstate/spin_constraints/#convergence","text":"Some of the magnetic states can be difficult to converge, as the penalty potential still does not end up looking like a physical system. This causes the calculation to take a huge number of steps to reach convergence (if it even gets there!) You almost certainly need to decrease the value of spin_mix_amp which has a default of 0.8 but should be much lower (eg 0.5 or even less) for many of these systems. Alternatively, you can use metals_method: EDFT which uses EDFT instead of density mixing and this can improve the convergence.","title":"Convergence"},{"location":"documentation/Groundstate/xc/","text":"","title":"Xc"},{"location":"documentation/Input_Files/cell_file/","text":"This is a detailed description of options for CASTEP's cell file. See the basic cell file page for an overview. This page has the most frequently-used cell file options, but for a full set use CASTEP's built-in help . There is also a concise table of cell keywords . The cell file is one of CASTEP's two main input files. It contains all of the information about the crystal lattice and the atomic positions, as well as additional information such as Brillouin zone sampling ('k-points'), pseudopotentials, cell symmetry, external pressure, constraints on motion of the atoms or cell, and atomic properties such as the mass of each species. The file itself is a free-format keyword-driven text file, consisting of keywords and blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. Most of the keywords and blocks are optional, but CASTEP requires two block entries: a block to specify the lattice, and another to specify the atomic elements and positions within the cell. At the very least, the cell lattice vectors and ionic positions must be specified. Reasonable defaults are chosen for anything else not specified. For the purposes of the following definitions, all variables represented by R R are defined to be real numbers, those represented by I I are defined to be integers and those represented by C C are characters. Cell Lattice Vectors The cell lattice vectors may be specified in Cartesian coordinates or in terms of the lattice vector magnitudes and the angles between them ( a, b, c, \\alpha, \\beta, \\gamma a, b, c, \\alpha, \\beta, \\gamma ). Only one of LATTICE_CART and LATTICE_ABC may occur in a cell definition file. The definitions of these keywords are as follows: %BLOCK LATTICE_CART [units] a_x a_y a_z b_x b_y b_z c_x c_y c_z %ENDBLOCK LATTICE_CART Here a_x is the x-component of the first lattice vector, \\mathbf{a} \\mathbf{a} , b_y b_y is the y-component of the second lattice vector, \\mathbf{b} \\mathbf{b} , etc. [units] specifies the units in which the lattice vectors are defined. If not present, the default is \u00c5. %BLOCK LATTICE_ABC [units] a b c alpha beta gamma %ENDBLOCK LATTICE_ABC Here a is the value of the lattice constant \\vert\\mathbf{a}\\vert \\vert\\mathbf{a}\\vert , gamma is the value of the cell angle \\gamma \\gamma (in degrees) etc. If the lattice is specified in this manner, the absolute orientation is arbitrary. In this case the orientation is defined by applying the following constraints: \\mathbf{a} \\mathbf{a} lies along the x-axis \\mathbf{b} \\mathbf{b} lies in the xy plane \\mathbf{c} \\mathbf{c} forms a right-handed set with \\mathbf{a} \\mathbf{a} and \\mathbf{b} \\mathbf{b} [units] specifies the units in which the lattice vector magnitudes are defined. If not present, the default is \u00c5. Angles should be specified in degrees. Ionic Positions The ionic positions may be specified in fractional coordinates relative to the lattice vectors of the unit cell, or in absolute coordinates. Only one of POSITIONS_FRAC and POSITIONS_ABS may occur in a cell definition file. %BLOCK POSITIONS_FRAC CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK END POSITIONS_FRAC The first entry on a line is the symbol of the species (chemical element). Alternatively, the atomic number may be given instead, in which case CASTEP will be look up for chemical symbol. A symbol can have a maximum of three characters. The first alphabetical characters identify the element, from which default values for atomic mass etc. The next three entries on a line in POSITIONS_FRAC are real numbers representing the position of the ion in fractions of the unit cell lattice vectors. If the optional flag SPIN is present on a line, this sets the spin polarisation ( N^\\uparrow-N^\\downarrow N^\\uparrow-N^\\downarrow ) of the atom for initialisation of the spin density; for non-collinear spin calculations, the vector spin is specified as three numbers. If this flag is not present a non-spin polarised state will be assumed. %BLOCK POSITIONS_ABS [units] CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK POSITIONS_ABS The first entry on a line is the symbol or atomic number of the ionic species, as for POSITIONS_FRAC . The next three entries are real numbers representing the position of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5. The optional flag SPIN is defined above under POSITIONS_FRAC . Brillouin Zone Sampling (k-points) (N.B. in the following section the keywords with the prefixes KPOINT_ and KPOINTS_ are synonymous. KPOINT_ is the preferred usage.) The k-points at which the Brillouin zone is to be sampled during a self consistent calculation to find the electronic ground state may be defined either by specifying a list of k-points or a Monkhorst-Pack grid in terms of the dimensions of the k-point mesh or a minimum k-point density. The origin of the Monkhorst-Pack grid may be offset by a vector from the origin of the Brillouin zone. If no k-points are specified, the default will be a Monkhorst-Pack grid with a maximum spacing of 0.1\u00c5 ^{-1} ^{-1} and no offset of the origin. The KPOINT_LIST , KPOINT_MP_GRID and KPOINT_MP_SPACING keywords are mutually exclusive. KPOINT_MP_OFFSET may be specified in combination with either KPOINT_MP_GRID or KPOINT_MP_SPACING . %BLOCK KPOINT_LIST \\begin{array}{cccc} R_{1i} R_{1j} R_{1k} R_{1w} R_{2i} R_{2j} R_{2k} R_{2w} ... %ENDBLOCK KPOINT_LIST The first three entries on a line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The final entry on a line is the weight of the k-point relative to the others specified. The sum of the weights must be equal to 1. KPOINT_MP_GRID I_i I_j I_k This specifies the dimensions of the Monkhorst-Pack grid requested in the directions of the reciprocal space lattice vectors. The generated grid will be I_i\\times I_j\\times I_k I_i\\times I_j\\times I_k ; any symmetries generated (or supplied) will be used to reduce this number, when computing the irreducible wedge. KPOINT_MP_SPACING R [units] The single entry is the maximum distance between k-points on the Monkhorst-Pack grid. The dimensions of the grid will be chosen such that the maximum separation of k-points is less than this. [units] specifies the units in which the k-point spacing is defined, although note that the actual units used are 2\\pi 2\\pi units . If not present, the default is ang-1 , such that the spacing is in 2\\pi \u00c5^{-1} 2\\pi \u00c5^{-1} . KPOINT_MP_OFFSET R_i R_j R_k This specifies the offset of the Monkhorst-Pack grid with respect to the origin of the Brillouin zone. The three entries are the offset in fractional coordinates relative to the reciprocal lattice vectors. The k-point set for performing spectral calculations can be specified in the same manner, using version of the keywords above with SPECTRAL_ prepended. The same restrictions regarding mutually exclusive keywords apply. For a non-self-consistent spectral calculation, the k-points may be defined along a path through reciprocal space or a list of k-points. %BLOCK SPECTRAL_KPOINT_PATH R_{1i} R_{1j} R_{1k} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK SPECTRAL_KPOINT_PATH The three numbers on each line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The k-points define a continuous sequence of straight line segments, unless the keyword BREAK appears on a separate line within the sequence of k-points. In this case the continuous path will end at the k-point immediately preceding the BREAK keyword and resume at the k-point immediately following. The path will be open unless the first and last point in the list are identical . The maximum spacing of the points sampled along each line segment is defined by the keyword SPECTRAL_KPOINT_PATH_SPACING (default value 0.1 \\times 2\\pi 0.1 \\times 2\\pi \u00c5 ^{-1} ^{-1} ). If necessary, the actual spacing used may be smaller than this in order to ensure that the length of the line segment is an integer multiple of the spacing between points on that segment. Alternatively, the k-point set for performing a band structure calculation can be specified in the same manner as the main k-point set, using version of the keywords above with BS_ prepended. The same restrictions regarding mutually exclusive keywords apply. In this case, the k-point weight in SPECTRAL_KPOINT_LIST is optional. If omitted, the weights for each k-point are assumed to be equal. For a phonon spectrum calculation, the k-points may be defined along a path through reciprocal space or a list of k-points, in the same manner as for a spectral calculation. The corresponding keywords are identical to those for the band structure specification with the initial SPECTRAL_ replaced by PHONON_ , e.g. PHONON_KPOINT_PATH , PHONON_KPOINT_PATH_SPACING and PHONON_KPOINT_LIST . The same restrictions regarding mutually exclusive keywords apply. The block keyword PHONON_GAMMA_DIRECTIONS specifies the directions in which the gamma point will be approached when calculating the non-analytic terms of the LO/TO splitting. Each line in this block will consist of a 3-vector specifying a direction in the basis of reciprocal lattice vectors. If this keyword is not present, the default will be a single vector determined as follows: If the gamma point is q_i = 0 q_i = 0 and there is a successor kpoint q_{i+1} q_{i+1} in the list, then it is q_{i+1} q_{i+1} . Otherwise if the gamma point is q_i =0 q_i =0 and there is a predecessor kpoint q_{i-1} q_{i-1} in the list then it is q_{i-1} q_{i-1} . Otherwise (i.e. a Gamma point only calculation) the a-axis of the reciprocal cell. For backwards compatibility the keywords beginning BS_ and OPTICS_ are synonyms for SPECTRAL_KPOINT_ and similarly those beginning. Cell Symmetry If no symmetry is specified in the cell definition file, the default is for no symmetry to be applied. SYMMETRY_GENERATE If this keyword is present in the cell, the highest symmetry group that applies to the structure of the cell will be found and the corresponding symmetry operations generated. SYMMETRY_TOL R [units] This parameter is the tolerance within which symmetry will be considered to be satisfied. If an ion is found within this distance of its symmetric position, the symmetry will be considered to be satisfied. [units] specifies the units in which the tolerance is defined. If not present, the default is \u00c5. Alternatively, the symmetry operations may be provided directly in a SYMMETRY_OPS block. The symmetry of the cell is represented as a series of symmetry operations under which the unit cell is invariant. Each operation is represented as a 3\\times 3 3\\times 3 array. %BLOCK SYMMETRY_OPS R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 ... %ENDBLOCK SYMMETRY_OPS Each of the first three lines contains 3 entries representing a row of a 3\\times3 3\\times3 array. These represent one symmetry rotation. The three entries on the following line contain the translation associated with this rotation. Constraints The movement of ions or the unit cell during a relaxation or molecular dynamics run may be constrained. The constraints on the ionic motion may by specified as a set of linear constraints. Each constraint is specified as a series of coefficients a_{ijk} a_{ijk} such that: $$ \\sum_{k=1}^{\\tt N_\\mathrm{species}} \\quad \\sum_{j=1}^{\\mathrm{N_\\mathrm{ions}}(k)} \\quad \\sum_{i=1}^{3} a_{ijk} \\verb#ionic_positions(i,j,k)# = constant $$ where \\mathrm{N_\\mathrm{ions}}(k) \\mathrm{N_\\mathrm{ions}}(k) is the number of ions in species k k . The change in the shape of the unit cell may also be constrained using the keyword CELL_CONSTRAINTS . The special case of constraining the centre of mass of the ions to remain fixed is supported by a logical keyword FIX_COM . Also all ionic positions or cell parameters may be fixed by specifying the keywords FIX_ALL_IONS or FIX_ALL_CELL to be TRUE respectively. If no ionic or cell constraints are specified in the cell definition file, the default is to fix the centre of mass. %BLOCK IONIC_CONSTRAINTS I_1 CCC_{1s} I_{1s} I_{n1} R_{1i} R_{1j} R_{1k} I_2 CCC_{2s} I_{2s} I_{n2} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK IONIC_CONSTRAINTS The first element on each line is an integer specifying the number of the constraint being specified. The second entry is either the symbol or atomic number of the species of the ion to which this constraint applies. The third element is the number of the ion within the species. The ordering of the ions in a species is the order in which they appear in the POSITIONS_FRAC or POSITIONS_ABS block in the cell definition file. The final three numbers are real numbers representing the coefficients of the Cartesian coordinates of the ionic position in the constraint sum. All coefficients in the sum not explicitly specified will be zero. On reading this data, the matrix of ionic constraints will be orthogonalised. %BLOCK CELL_CONSTRAINTS I_a I_b I_c I_alpha I_beta I_gamma %ENDBLOCK CELL_CONSTRAINTS The first three entries relate to the magnitude of the three lattice vectors a,b,c a,b,c and the second set of three entries to the angles \\alpha, \\beta, \\gamma \\alpha, \\beta, \\gamma . If the value of the entry corresponding to a magnitude or angle is zero, this quantity will remain fixed. If two or three entries contain the same integer, the corresponding quantities will be constrained to have the same value. If a positive integer greater than 0 occurs in entries 1 through 3 the same integer cannot occur in entries 4 through 6 as this would imply that a vector length and angle must have the same value. Species Characteristics The mass of a species, the pseudopotential which represents the ion and the size of the LCAO basis set used for population anslsyis may be specified in the cell definition file. %BLOCK SPECIES_MASS [units] CCC_1 I_1 R_1 CCC_2 I_2 R_2 ... %ENDBLOCK SPECIES_MASS [units] specifies the units in which the masses are defined. If not present, the default is atomic mass units. The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the mass of that species. Not all species need appear in the SPECIES_MASS block, any not present will assume the default mass for that species. If the initial alphabetical symbol specified for a species is not a standard element symbol in the periodic table, the mass of the species must be specified. %BLOCK SPECIES_POT CCC_1 I_1 CCC_2 I_2 ... %ENDBLOCK SPECIES_POT The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the filename of the file containing the definition of the pseudopotential representing the ionic species. The file to which this refers may be a definition of the parameters of the pseudopotential which is to be generated at runtime, or an old-style pseudopotential definition containing the data for the pseudopotential. Not all species need appear in the SPECIES_POT block. If a pseudopotential is not specified, the default pseudopotential parameters will be used to generate a pseudopotential for the element specified. If the initial alphabetical characters of a species label is not a standard element symbol in the periodic table, the potential for the species must be specified. The charge on the ion for each species will be derived from the pseudopotential corresponding to that ion. %BLOCK SPECIES_LCAO_STATES CCC_1 I_1 I_{B1} CCC_2 I_2 I_{B2} ... %ENDBLOCK SPECIES_LCAO_STATES The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second number is the number of angular momentum channels to use in the LCAO basis set for the species when performing population analysis. For example, to use the 2s and 2p states for C (The 1s state is a core state) this should be 2. By default, the number of states will be the appropriate number to complete the valence shell to the next noble gas. If shallow core states are excluded from a pseudopotential, the value of SPECIES_LCAO_STATES for that species should be included in the cell file to ensure a meaningful basis set is used. External Pressure An external pressure may be applied to the unit cell by specifying a pressure tensor. %BLOCK EXTERNAL_PRESSURE [units] R_{xx} R_{xy} R_{xz} R_{yy} R_{yz} R_{zz} %ENDBLOCK EXTERNAL_PRESSURE [units] specifies the units in which the pressure is defined. If not present, the default is GPa. Entry R_{xx} R_{xx} is the xx xx -component of the pressure, R_{xy} R_{xy} the xy xy -component etc. The default is to apply no external pressure. Ionic Velocities The initial ionic velocities may be specified in Cartesian coordinates in a cell definition file. %BLOCK IONIC_VELOCITIES [units] CCC_1 V_{1x} V_{1y} V_{1z} CCC_2 V_{2x} V_{2y} V_{2z} ... %ENDBLOCK IONIC_VELOCITIES The first entry on a line is the chemical symbol (or atomic number) of the ionic species. The correct symbol will be looked up for the atomic species if the atomic number is specified. A symbol can have a maximum of three characters. The next three entries are real numbers representing the velocity of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5/ps. If this keyword is not present and a molecular dynamics calculation is performed, the ionic velocities will be randomly initialised with the appropriate temperature.","title":"cell File"},{"location":"documentation/Input_Files/cell_file/#cell-lattice-vectors","text":"The cell lattice vectors may be specified in Cartesian coordinates or in terms of the lattice vector magnitudes and the angles between them ( a, b, c, \\alpha, \\beta, \\gamma a, b, c, \\alpha, \\beta, \\gamma ). Only one of LATTICE_CART and LATTICE_ABC may occur in a cell definition file. The definitions of these keywords are as follows: %BLOCK LATTICE_CART [units] a_x a_y a_z b_x b_y b_z c_x c_y c_z %ENDBLOCK LATTICE_CART Here a_x is the x-component of the first lattice vector, \\mathbf{a} \\mathbf{a} , b_y b_y is the y-component of the second lattice vector, \\mathbf{b} \\mathbf{b} , etc. [units] specifies the units in which the lattice vectors are defined. If not present, the default is \u00c5. %BLOCK LATTICE_ABC [units] a b c alpha beta gamma %ENDBLOCK LATTICE_ABC Here a is the value of the lattice constant \\vert\\mathbf{a}\\vert \\vert\\mathbf{a}\\vert , gamma is the value of the cell angle \\gamma \\gamma (in degrees) etc. If the lattice is specified in this manner, the absolute orientation is arbitrary. In this case the orientation is defined by applying the following constraints: \\mathbf{a} \\mathbf{a} lies along the x-axis \\mathbf{b} \\mathbf{b} lies in the xy plane \\mathbf{c} \\mathbf{c} forms a right-handed set with \\mathbf{a} \\mathbf{a} and \\mathbf{b} \\mathbf{b} [units] specifies the units in which the lattice vector magnitudes are defined. If not present, the default is \u00c5. Angles should be specified in degrees.","title":"Cell Lattice Vectors"},{"location":"documentation/Input_Files/cell_file/#ionic-positions","text":"The ionic positions may be specified in fractional coordinates relative to the lattice vectors of the unit cell, or in absolute coordinates. Only one of POSITIONS_FRAC and POSITIONS_ABS may occur in a cell definition file. %BLOCK POSITIONS_FRAC CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK END POSITIONS_FRAC The first entry on a line is the symbol of the species (chemical element). Alternatively, the atomic number may be given instead, in which case CASTEP will be look up for chemical symbol. A symbol can have a maximum of three characters. The first alphabetical characters identify the element, from which default values for atomic mass etc. The next three entries on a line in POSITIONS_FRAC are real numbers representing the position of the ion in fractions of the unit cell lattice vectors. If the optional flag SPIN is present on a line, this sets the spin polarisation ( N^\\uparrow-N^\\downarrow N^\\uparrow-N^\\downarrow ) of the atom for initialisation of the spin density; for non-collinear spin calculations, the vector spin is specified as three numbers. If this flag is not present a non-spin polarised state will be assumed. %BLOCK POSITIONS_ABS [units] CCC_1 R_{1i} R_{1j} R_{1k} [SPIN=s_1] CCC_2 R_{2i} R_{2j} R_{2k} [SPIN=s_2] ... %ENDBLOCK POSITIONS_ABS The first entry on a line is the symbol or atomic number of the ionic species, as for POSITIONS_FRAC . The next three entries are real numbers representing the position of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5. The optional flag SPIN is defined above under POSITIONS_FRAC .","title":"Ionic Positions"},{"location":"documentation/Input_Files/cell_file/#brillouin-zone-sampling-k-points","text":"(N.B. in the following section the keywords with the prefixes KPOINT_ and KPOINTS_ are synonymous. KPOINT_ is the preferred usage.) The k-points at which the Brillouin zone is to be sampled during a self consistent calculation to find the electronic ground state may be defined either by specifying a list of k-points or a Monkhorst-Pack grid in terms of the dimensions of the k-point mesh or a minimum k-point density. The origin of the Monkhorst-Pack grid may be offset by a vector from the origin of the Brillouin zone. If no k-points are specified, the default will be a Monkhorst-Pack grid with a maximum spacing of 0.1\u00c5 ^{-1} ^{-1} and no offset of the origin. The KPOINT_LIST , KPOINT_MP_GRID and KPOINT_MP_SPACING keywords are mutually exclusive. KPOINT_MP_OFFSET may be specified in combination with either KPOINT_MP_GRID or KPOINT_MP_SPACING . %BLOCK KPOINT_LIST \\begin{array}{cccc} R_{1i} R_{1j} R_{1k} R_{1w} R_{2i} R_{2j} R_{2k} R_{2w} ... %ENDBLOCK KPOINT_LIST The first three entries on a line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The final entry on a line is the weight of the k-point relative to the others specified. The sum of the weights must be equal to 1. KPOINT_MP_GRID I_i I_j I_k This specifies the dimensions of the Monkhorst-Pack grid requested in the directions of the reciprocal space lattice vectors. The generated grid will be I_i\\times I_j\\times I_k I_i\\times I_j\\times I_k ; any symmetries generated (or supplied) will be used to reduce this number, when computing the irreducible wedge. KPOINT_MP_SPACING R [units] The single entry is the maximum distance between k-points on the Monkhorst-Pack grid. The dimensions of the grid will be chosen such that the maximum separation of k-points is less than this. [units] specifies the units in which the k-point spacing is defined, although note that the actual units used are 2\\pi 2\\pi units . If not present, the default is ang-1 , such that the spacing is in 2\\pi \u00c5^{-1} 2\\pi \u00c5^{-1} . KPOINT_MP_OFFSET R_i R_j R_k This specifies the offset of the Monkhorst-Pack grid with respect to the origin of the Brillouin zone. The three entries are the offset in fractional coordinates relative to the reciprocal lattice vectors. The k-point set for performing spectral calculations can be specified in the same manner, using version of the keywords above with SPECTRAL_ prepended. The same restrictions regarding mutually exclusive keywords apply. For a non-self-consistent spectral calculation, the k-points may be defined along a path through reciprocal space or a list of k-points. %BLOCK SPECTRAL_KPOINT_PATH R_{1i} R_{1j} R_{1k} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK SPECTRAL_KPOINT_PATH The three numbers on each line are the fractional positions of the k-point relative to the reciprocal space lattice vectors. The k-points define a continuous sequence of straight line segments, unless the keyword BREAK appears on a separate line within the sequence of k-points. In this case the continuous path will end at the k-point immediately preceding the BREAK keyword and resume at the k-point immediately following. The path will be open unless the first and last point in the list are identical . The maximum spacing of the points sampled along each line segment is defined by the keyword SPECTRAL_KPOINT_PATH_SPACING (default value 0.1 \\times 2\\pi 0.1 \\times 2\\pi \u00c5 ^{-1} ^{-1} ). If necessary, the actual spacing used may be smaller than this in order to ensure that the length of the line segment is an integer multiple of the spacing between points on that segment. Alternatively, the k-point set for performing a band structure calculation can be specified in the same manner as the main k-point set, using version of the keywords above with BS_ prepended. The same restrictions regarding mutually exclusive keywords apply. In this case, the k-point weight in SPECTRAL_KPOINT_LIST is optional. If omitted, the weights for each k-point are assumed to be equal. For a phonon spectrum calculation, the k-points may be defined along a path through reciprocal space or a list of k-points, in the same manner as for a spectral calculation. The corresponding keywords are identical to those for the band structure specification with the initial SPECTRAL_ replaced by PHONON_ , e.g. PHONON_KPOINT_PATH , PHONON_KPOINT_PATH_SPACING and PHONON_KPOINT_LIST . The same restrictions regarding mutually exclusive keywords apply. The block keyword PHONON_GAMMA_DIRECTIONS specifies the directions in which the gamma point will be approached when calculating the non-analytic terms of the LO/TO splitting. Each line in this block will consist of a 3-vector specifying a direction in the basis of reciprocal lattice vectors. If this keyword is not present, the default will be a single vector determined as follows: If the gamma point is q_i = 0 q_i = 0 and there is a successor kpoint q_{i+1} q_{i+1} in the list, then it is q_{i+1} q_{i+1} . Otherwise if the gamma point is q_i =0 q_i =0 and there is a predecessor kpoint q_{i-1} q_{i-1} in the list then it is q_{i-1} q_{i-1} . Otherwise (i.e. a Gamma point only calculation) the a-axis of the reciprocal cell. For backwards compatibility the keywords beginning BS_ and OPTICS_ are synonyms for SPECTRAL_KPOINT_ and similarly those beginning.","title":"Brillouin Zone Sampling (k-points)"},{"location":"documentation/Input_Files/cell_file/#cell-symmetry","text":"If no symmetry is specified in the cell definition file, the default is for no symmetry to be applied. SYMMETRY_GENERATE If this keyword is present in the cell, the highest symmetry group that applies to the structure of the cell will be found and the corresponding symmetry operations generated. SYMMETRY_TOL R [units] This parameter is the tolerance within which symmetry will be considered to be satisfied. If an ion is found within this distance of its symmetric position, the symmetry will be considered to be satisfied. [units] specifies the units in which the tolerance is defined. If not present, the default is \u00c5. Alternatively, the symmetry operations may be provided directly in a SYMMETRY_OPS block. The symmetry of the cell is represented as a series of symmetry operations under which the unit cell is invariant. Each operation is represented as a 3\\times 3 3\\times 3 array. %BLOCK SYMMETRY_OPS R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 R_{11} R_{21} R_{31} R_{12} R_{22} R_{32} R_{13} R_{23} R_{33} T_1 T_2 T_3 ... %ENDBLOCK SYMMETRY_OPS Each of the first three lines contains 3 entries representing a row of a 3\\times3 3\\times3 array. These represent one symmetry rotation. The three entries on the following line contain the translation associated with this rotation.","title":"Cell Symmetry"},{"location":"documentation/Input_Files/cell_file/#constraints","text":"The movement of ions or the unit cell during a relaxation or molecular dynamics run may be constrained. The constraints on the ionic motion may by specified as a set of linear constraints. Each constraint is specified as a series of coefficients a_{ijk} a_{ijk} such that: $$ \\sum_{k=1}^{\\tt N_\\mathrm{species}} \\quad \\sum_{j=1}^{\\mathrm{N_\\mathrm{ions}}(k)} \\quad \\sum_{i=1}^{3} a_{ijk} \\verb#ionic_positions(i,j,k)# = constant $$ where \\mathrm{N_\\mathrm{ions}}(k) \\mathrm{N_\\mathrm{ions}}(k) is the number of ions in species k k . The change in the shape of the unit cell may also be constrained using the keyword CELL_CONSTRAINTS . The special case of constraining the centre of mass of the ions to remain fixed is supported by a logical keyword FIX_COM . Also all ionic positions or cell parameters may be fixed by specifying the keywords FIX_ALL_IONS or FIX_ALL_CELL to be TRUE respectively. If no ionic or cell constraints are specified in the cell definition file, the default is to fix the centre of mass. %BLOCK IONIC_CONSTRAINTS I_1 CCC_{1s} I_{1s} I_{n1} R_{1i} R_{1j} R_{1k} I_2 CCC_{2s} I_{2s} I_{n2} R_{2i} R_{2j} R_{2k} ... %ENDBLOCK IONIC_CONSTRAINTS The first element on each line is an integer specifying the number of the constraint being specified. The second entry is either the symbol or atomic number of the species of the ion to which this constraint applies. The third element is the number of the ion within the species. The ordering of the ions in a species is the order in which they appear in the POSITIONS_FRAC or POSITIONS_ABS block in the cell definition file. The final three numbers are real numbers representing the coefficients of the Cartesian coordinates of the ionic position in the constraint sum. All coefficients in the sum not explicitly specified will be zero. On reading this data, the matrix of ionic constraints will be orthogonalised. %BLOCK CELL_CONSTRAINTS I_a I_b I_c I_alpha I_beta I_gamma %ENDBLOCK CELL_CONSTRAINTS The first three entries relate to the magnitude of the three lattice vectors a,b,c a,b,c and the second set of three entries to the angles \\alpha, \\beta, \\gamma \\alpha, \\beta, \\gamma . If the value of the entry corresponding to a magnitude or angle is zero, this quantity will remain fixed. If two or three entries contain the same integer, the corresponding quantities will be constrained to have the same value. If a positive integer greater than 0 occurs in entries 1 through 3 the same integer cannot occur in entries 4 through 6 as this would imply that a vector length and angle must have the same value.","title":"Constraints"},{"location":"documentation/Input_Files/cell_file/#species-characteristics","text":"The mass of a species, the pseudopotential which represents the ion and the size of the LCAO basis set used for population anslsyis may be specified in the cell definition file. %BLOCK SPECIES_MASS [units] CCC_1 I_1 R_1 CCC_2 I_2 R_2 ... %ENDBLOCK SPECIES_MASS [units] specifies the units in which the masses are defined. If not present, the default is atomic mass units. The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the mass of that species. Not all species need appear in the SPECIES_MASS block, any not present will assume the default mass for that species. If the initial alphabetical symbol specified for a species is not a standard element symbol in the periodic table, the mass of the species must be specified. %BLOCK SPECIES_POT CCC_1 I_1 CCC_2 I_2 ... %ENDBLOCK SPECIES_POT The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second entry on each line is the filename of the file containing the definition of the pseudopotential representing the ionic species. The file to which this refers may be a definition of the parameters of the pseudopotential which is to be generated at runtime, or an old-style pseudopotential definition containing the data for the pseudopotential. Not all species need appear in the SPECIES_POT block. If a pseudopotential is not specified, the default pseudopotential parameters will be used to generate a pseudopotential for the element specified. If the initial alphabetical characters of a species label is not a standard element symbol in the periodic table, the potential for the species must be specified. The charge on the ion for each species will be derived from the pseudopotential corresponding to that ion. %BLOCK SPECIES_LCAO_STATES CCC_1 I_1 I_{B1} CCC_2 I_2 I_{B2} ... %ENDBLOCK SPECIES_LCAO_STATES The first entry on a line is the symbol or atomic number of the species. This must correspond with the species symbol or atomic number of the species in the POSITIONS_FRAC or POSITIONS_ABS block. The second number is the number of angular momentum channels to use in the LCAO basis set for the species when performing population analysis. For example, to use the 2s and 2p states for C (The 1s state is a core state) this should be 2. By default, the number of states will be the appropriate number to complete the valence shell to the next noble gas. If shallow core states are excluded from a pseudopotential, the value of SPECIES_LCAO_STATES for that species should be included in the cell file to ensure a meaningful basis set is used.","title":"Species Characteristics"},{"location":"documentation/Input_Files/cell_file/#external-pressure","text":"An external pressure may be applied to the unit cell by specifying a pressure tensor. %BLOCK EXTERNAL_PRESSURE [units] R_{xx} R_{xy} R_{xz} R_{yy} R_{yz} R_{zz} %ENDBLOCK EXTERNAL_PRESSURE [units] specifies the units in which the pressure is defined. If not present, the default is GPa. Entry R_{xx} R_{xx} is the xx xx -component of the pressure, R_{xy} R_{xy} the xy xy -component etc. The default is to apply no external pressure.","title":"External Pressure"},{"location":"documentation/Input_Files/cell_file/#ionic-velocities","text":"The initial ionic velocities may be specified in Cartesian coordinates in a cell definition file. %BLOCK IONIC_VELOCITIES [units] CCC_1 V_{1x} V_{1y} V_{1z} CCC_2 V_{2x} V_{2y} V_{2z} ... %ENDBLOCK IONIC_VELOCITIES The first entry on a line is the chemical symbol (or atomic number) of the ionic species. The correct symbol will be looked up for the atomic species if the atomic number is specified. A symbol can have a maximum of three characters. The next three entries are real numbers representing the velocity of the ion in Cartesian coordinates. [units] specifies the units in which the positions are defined. If not present, the default is \u00c5/ps. If this keyword is not present and a molecular dynamics calculation is performed, the ionic velocities will be randomly initialised with the appropriate temperature.","title":"Ionic Velocities"},{"location":"documentation/Input_Files/cell_keywords/","text":"This is a concise list of the common keywords for CASTEP's cell input file. The definitions of the keywords are given in more detail in the section on the cell file . Keyword in the cell file Type Default Description LATTICE_CART ^1 ^1 B -- The cell lattice vectors in Cartesian coordinates. LATTICE_ABC ^1 ^1 B -- The cell lattice vectors specified in $ a, b, c, \\alpha, \\beta, \\gamma $ format. POSITIONS_FRAC ^2 ^2 B -- The positions of the ions in fraction coordinates with respect to the lattice vectors. POSITIONS_ABS ^2 ^2 B -- The positions of the ions in absolute coordinates. KPOINT_LIST ^3 ^3 B -- A list of k-points in the Brillouin zone with associated weights. KPOINT_MP_GRID ^3 ^3 W -- The k-points defined as a Monkhorst-Pack grid by specifying the grid dimensions in each direction. KPOINT_MP_SPACING ^3 ^3 P 0.1 \u00c5^{-1} \u00c5^{-1} The k-points as a Monkhorst-Pack grid by specifying the maximum distance between k-points. KPOINT_MP_OFFSET V 0,0,0 The offset of the origin of the Monkhorst-Pack grid in fractional coordinates relative to the reciprocal lattice vectors. SPECTRAL_KPOINT_PATH ^4 ^4 B -- A list of k-points in the Brillouin zone which defines the path along which a band-structure calculation will be performed. SPECTRAL_KPOINT_PATH_SPACING P 0.1 \u00c5^{-1} \u00c5^{-1} Specifies the maximum spacing between k-points along the path for which a band structure calculation will be performed. SPECTRAL_KPOINT_LIST ^4 ^4 B SCF k-points A list of k-points at which a band-structure calculation will be performed. SPECTRAL_KPOINT_MP_GRID ^4 ^4 W -- The k-points for optical matrix element calculations defined as a Monkhorst-Pack grid by specifying the grid dimensions in each direction. SPECTRAL_KPOINT_MP_SPACING ^4 ^4 P 0.1 \u00c5 ^{-1} ^{-1} The k-points for optical matrix element calculations as a Monkhorst-Pack grid by specifying the maximum distance between k-points. SPECTRAL_KPOINT_MP_OFFSET V 0,0,0 The offset of the origin of the Monkhorst-Pack grid for optical matrix element calculations in fractional coordinates relative to the reciprocal lattice vectors. PHONON_KPOINT_PATH ^5 ^5 B -- A list of k-points in the Brillouin zone which defines the path along which a phonon calculation will be performed. PHONON_KPOINT_PATH_SPACING P 0.1 \u00c5 ^{-1} ^{-1} Specifies the maximum spacing between k-points along the path for which a phonon calculation will be performed. PHONON_KPOINT_LIST ^5 ^5 B SCF k-points A list of k-points at which a phonon calculation will be performed. PHONON_GAMMA_DIRECTIONS B See text The directions in which the gamma point will be approached for calculation of the LO/TO splitting. SYMMETRY_GENERATE ^6 ^6 D no symmetry If this is present, the highest symmtery group of the cell will found and the corresponding symmetry operations generated. SYMMETRY_OPS ^6 ^6 B no symmetry The symmetry operations that apply to the cell. SYMMETRY_TOL P 0.01 \u00c5 The tolerance within which symmetry will be enforced. IONIC_CONSTRAINTS B no constraints The constraints on the motion of ions during relaxation or MD. FIX_ALL_IONS L FALSE Constrain all ionic positions to remain fixed. FIX_ALL_CELL L FALSE Constrain all cell parameters to remain fixed. FIX_COM L TRUE Constrain the centre of mass of the ions to remain fixed. CELL_CONSTRAINTS B no constraints The constraints on changes in the cell shape during relaxation or MD. SPECIES_MASS B atomic mass The masses of the ionic species. SPECIES_POT B see text The names of the pseudopotentials associated with each species. SPECIES_LCAO_STATES B see text The number of angular momentum states to use in the LCAO basis set for this species when performing population analysis. EXTERNAL_PRESSURE B no pressure The external pressure tensor. IONIC_VELOCITIES B random The velocities of the ions in Cartesian coordinates. For the argument types, B indicates block data, P means a physical value, L is a logical value, D is a keyword that may simply be defined (present) or not, V is a real vector and W is an integer vector. ^1 ^1 Only one of LATTICE_CART and LATTICE_ABC maybe present in a cell file. ^2 ^2 Only one of POSITIONS_FRAC and POSITIONS_ABS may be present in a cell file. ^3 ^3 Only one of KPOINTS_LIST , KPOINTS_MP_GRID and KPOINTS_MP_SPACING may be present in a cell file. ^4 ^4 Only one of SPECTRAL_KPOINT_PATH , SPECTRAL_KPOINTS_MP_GRID , SPECTRAL_KPOINTS_MP_SPACING and SPECTRAL_KPOINT_LIST may be present in a cell file. ^5 ^5 Only one of PHONON_KPOINT_PATH and PHONON_KPOINT_LIST may be present in a cell file. ^6 ^6 Only one of SYMMETRY_GENERATE and SYMMETRY_OPS may be present in a cell file.","title":"Cell Keywords"},{"location":"documentation/Input_Files/param_file/","text":"This is a detailed description of options for CASTEP's param file. See the basic param file page for an overview. This page has the most frequently-used param file options, but for a full set use CASTEP's built-in help . The param file is one of CASTEP's two main input files. It contains all of the information about the kind of simulation your wish CASTEP to perform, as well as details of how CASTEP should perform them and additional simulations and analyses. The file itself is a free-format keyword-driven text file, consisting largely of single-line keywords, although there are a small number of blocks of information. These may be given in any order, with blocks indicated by the special %block and %endblock markers. All of the keywords and blocks are optional, but you will almost always want to change at least some. Task This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file . Cut-off energy The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV. XC functional Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"param File"},{"location":"documentation/Input_Files/param_file/#task","text":"This keyword controls what CASTEP's simulation task is. The default is task : energy which tells CASTEP to compute the ground state electronic energy and density for the input set of atoms from the cell file .","title":"Task"},{"location":"documentation/Input_Files/param_file/#cut-off-energy","text":"The plane-wave cut-off energy controls how large CASTEP's basis set is for representing the wavefunction. Higher values mean more plane-waves and a better representation of the wavefunction, but this consumes more computer RAM and the calculation will take more time. CASTEP calculations are always a compromise between the accuracy you require, and the computational resources the simulations will use. The cut-off energy you need will also depend on the pseudopotentials you're using in the cell file . You can choose from some preset values using the basis_precision keyword: basis_precision : coarse|medium|fine|precise i.e. you can choose to set basis_precision to coarse , medium , fine or precise . The settings coarse and medium are usually only suitable for quick preliminary investigations, and for research simulations you will usually want to set it to fine or better. For more control over the cut-off energy, the cut_off_energy keyword may be used instead: cut_off_energy : 500 eV Typical cut-off energies are in the range 300 to 1500 eV.","title":"Cut-off energy"},{"location":"documentation/Input_Files/param_file/#xc-functional","text":"Density functional theory is exact in principle, except for the exchange-correlation (XC) functional which must be approximated. There are many different functional forms to approximate this, and in CASTEP you select it with the xc_functional keyword, for example: xc_functional : pbe which selects the PBE functional of Perdew, Burke and Ernzerhof.","title":"XC functional"},{"location":"documentation/Molecular_Dynamics/basics/","text":"Fundamental to MD calculations is the calculation time-step. An appropriate value for the simulation should be specified in the parameters file in the following way. md_delta_t = 2 fs Any valid unit of time can be used when specifying the time-step. The number of time-steps to perform is specified with e.g. md_num_iter = 500 NB This is the number of steps to be calculated in this run. It is NOT the accumulated total number of steps in a series of continuation runs. The \"MD time\" value in the .castep file records the cumulative time. Ensembles The following statistical ensembles can be simulated using CASTEP. NVE In this ensemble the number of atoms (N), the shape and volume (V) of the simulation cell and the energy (E) remain constant. The conserved energy is the Born-Oppenheimer Hamiltonian E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} in atomic units. This ensemble is selected using the command md_ensemble = NVE in the parameters file. The actual value of the conserved energy will be the result of the initial self-consistent DFT calculation plus the kinetic energy of the initial ionic velocities. These ionic velocities are defined in one of three ways. By explicit user definition of ionic velocities in the cell file, e.g. %BLOCK IONIC_VELOCITIES auv H xxxxx yyyyy zzzzz H xxxxx yyyyy zzzzz O xxxxx yyyyy zzzzz %ENDBLOCK IONIC_VELOCITIES using any valid unit of velocity (auv is atomic unit of velocity), etc. By definition of an initial temperature in the parameters file, e.g. md_temperature = 293 K Note that this can be specified using any valid unit of temperature. In this case initial velocities are assigned randomly such that the total linear momentum is zero and the instantaneous temperature matches that specified. The system will reach equilibrium with a somewhat different temperature due to equipartition of kinetic and potential energy. By continuation from an equilibrated run at the desired temperature. This could be a run in any of the other available ensembles. This will also use the cell and ionic positions from the continuation file. See the section on continuation for details. Velocities read from a continuation file will always take precedence. If no continuation file is used, and both md_temperature and an IONIC_VELOCITIES block are specified, the md_temperature keyword will be ignored. By default, pressure is not calculated during an NVE run. To override this use the command calculate_stress = true in the parameters file. NVT This ensemble is selected with md_ensemble = NVT The system will be evolved to a specific temperature defined using the md_temperature keyword as used above. Initial velocities are assigned based on this temperature, read from an IONIC_VELOCITIES block in the cell file, or read from a continuation file in the same way as above. Temperature control can be implemented by one of several methods, all of which have been shown to correctly sample the canonical ensemble. The first of these is the deterministic Nose-Hoover chain method of Tuckerman et al 1 and is selected with md_thermostat = nose-hoover in the parameters file. In the NVT case, a single Nose-Hoover chain is coupled to all particle degrees of freedom. The length of the chain can also be specified, e.g. md_nhc_length = 5 for a chain of five thermostats. In the Nose-Hoover case with a chain of M M thermostats acting of N_{f} N_{f} ionic degrees of freedom, the conserved quantity is the pseudo-Hamiltonian \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} where the Q_{i} Q_{i} are the thermostat fictitious masses assigned automatically from the specified ion relaxation time and \\xi_{i} \\xi_{i} are the thermostat degrees of freedom. This is printed with the label Hamilt Energy: at each time-step. A Nose-Hoover thermostat with no chain (i.e. with M M =1 ) is known to not be ergodic and hence should be avoided. The second method of controlling temperature is through the stochastic Langevin thermostat. md_thermostat = langevin In this case the printed Hamiltonian energy is the value of equation above. This is not conserved by the dynamics, but should exhibit no long term drift from the equilibrium value. Finally, the temperature may be controled via the Hoover-Langevin thermostat. md_thermostat = hoover-langevin which is the fusion of a deterministic Nose-Hoover thermostat acting directly on the physical system, with a Langevin thermostat operating on the Nose-Hoover variables, in order to guarantee ergodicity. With each method, a suitable relaxation time for the thermostatic process should be specified. This can use any supported unit of time, e.g md_ion_t = 2.4 ps for a thermostat relaxation time of 2.4 picoseconds. The Hoover-Langevin thermostat is the LEAST sensitive to the choice of this value. As with the NVE ensemble, pressure is not calculated by default. This is overridden in the same way as the NVE case. NPH In this ensemble the size and (if desired) shape of the simulation cell varies to regulate pressure. No thermostat is applied and hence the enthalpy (H) is conserved. This ensemble is specified with the following: md_ensemble = NPH The external pressure is set in the cell definition file using any valid unit of pressure. The required symmetry of the external pressure tensor implies that only the upper triangular components need be specified, e.g. %block external_pressure GPa 0.5 0.0 0.0 0.5 0.0 0.5 %endblock external_pressure to specify an isotropic external pressure of 0.5 Giga-Pascals. MD can also support non-isotropic pressure if using a variable-shape barostat. Velocities are assigned such that the initial temperature is equal to md_temperature , or are read from the cell definition file/continuation file as in the NVE/NVT cases. Two barostat schemes are available. The first restricts the dynamics of the cell to isotropic expansions and contractions. This follows the method of Andersen 2 and Hoover 3 4 as corrected by Martyna et al. 5 . This is selected using: md_barostat = andersen-hoover In this case the printed Hamiltonian energy is the enthalpy, plus the kinetic energy associated with the cell motion. \\begin{equation} \\label{eq:AndersenNPH} H = \\left<\\Psi|\\hat{H} {e}|\\Psi\\right> + \\frac{1}{2} \\sum {N}\\sum_{j=1} {|\\mathbf{R}}\\frac{Z_{i}Z_{j} {i}-\\mathbf{R} +\\sum_{i=1}}| {N}\\frac{P_{i} /2W \\end{equation } The alternative scheme implements the method of Parrinello and Rahman}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2 6 7 . Both the size and shape of the simulation cell are allowed to vary. The issue of cell rotations is eliminated by the use of a symmetrised pressure tensor. Note that as liquids cannot sustain shear, this method should only be used with solids. It should also be noted that this scheme is based on the modified Parrinello-Rahman method of Martyna, Tobias and Klien 5 . The following line in the parameters file selects this barostat. md_barostat = parrinello-rahman The cell dynamics contain nine degrees of freedom (of which six are independent) leading to a Hamiltonian energy of \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} For both barostats, a relaxation time for the cell motions should be specified with an appropriate unit of time, for example: md_cell_t = 20 ps This time is used to calculate a fictitious mass W W for the cell dynamics and should be large compared to the characteristic time for the ionic dynamics. The NPH equations of motion require that pressure (stress) is calculated at each MD time-step. The value of calculate_stress is therefore irrelevant in this case. A variable cell implies variable reciprocal lattice vectors which has consequences for the plane-wave basis set. As the cell changes, the number of plane waves required to produce the specified cut-off energy changes. The user therefore has two options. The first is to fix the size of the basis set. fixed_npw = true The cut-off energy is now variable as is the quality of the basis set. This option should therefore only be used for calculations in which the volume changes are small and which are over-converged with respect to the number of plane waves. The second option is to allow the basis set to change at each time-step. fixed_npw = false which is the default value. This keeps the cut-off energy approximately constant by adding or subtracting plane waves from the basis set at each time-step. In either case, the effect of Pulay stress is reduced by applying a finite basis set correction to the pressure at each time-step. In the case of a fixed number of plane waves, the constant correction to energy is ignored. With variable number of plane waves the energy correction is no longer constant and is recalculated at each step. NPT The NPT ensemble is specified with the command: md_ensemble = NPT This can use either the Nose-Hoover or Langevin thermostat, and either Andersen-Hoover or Parrinello-Rahman barostat. In all cases, the dynamics can be shown to correctly sample the isothermal-isobaric ensemble 5 All options pertaining to the NPH and NVT ensembles apply. In the case of Langevin dynamics at NPT, the printed Hamiltonian energy is the same as in the NPH ensemble, i.e. that given by the equations above. In the case of Nose-Hoover NPT molecular dynamics, the Hamiltonian energy is given by \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} in the case of isotropic cell dynamics, or \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} in the Parrinello-Rahman case. Note that in each case the motion of the cell degree(s) of freedom couple to a second Nose-Hoover chain. Glenn J. Martyna, Michael L. Klein, and Mark Tuckerman. Nos\u00e9\u2013Hoover chains: The canonical ensemble via continuous dynamics. The Journal of Chemical Physics , 97(4):2635\u20132643, 08 1992. doi:10.1063/1.463940 . \u21a9 Hans C. Andersen. Molecular dynamics simulations at constant pressure and/or temperature. The Journal of Chemical Physics , 72(4):2384\u20132393, 02 1980. doi:10.1063/1.439486 . \u21a9 William G. Hoover. Canonical dynamics: equilibrium phase-space distributions. Phys. Rev. A , 31:1695\u20131697, Mar 1985. doi:10.1103/PhysRevA.31.1695 . \u21a9 William G. Hoover. Constant-pressure equations of motion. Phys. Rev. A , 34:2499\u20132500, Sep 1986. doi:10.1103/PhysRevA.34.2499 . \u21a9 Glenn J. Martyna, Douglas J. Tobias, and Michael L. Klein. Constant pressure molecular dynamics algorithms. The Journal of Chemical Physics , 101(5):4177\u20134189, 09 1994. doi:10.1063/1.467468 . \u21a9 \u21a9 \u21a9 M. Parrinello and A. Rahman. Crystal structure and pair potentials: a molecular-dynamics study. Phys. Rev. Lett. , 45:1196\u20131199, Oct 1980. doi:10.1103/PhysRevLett.45.1196 . \u21a9 M. Parrinello and A. Rahman. Polymorphic transitions in single crystals: A new molecular dynamics method. Journal of Applied Physics , 52(12):7182\u20137190, 12 1981. doi:10.1063/1.328693 . \u21a9","title":"MD Basics"},{"location":"documentation/Molecular_Dynamics/basics/#ensembles","text":"The following statistical ensembles can be simulated using CASTEP.","title":"Ensembles"},{"location":"documentation/Molecular_Dynamics/basics/#nve","text":"In this ensemble the number of atoms (N), the shape and volume (V) of the simulation cell and the energy (E) remain constant. The conserved energy is the Born-Oppenheimer Hamiltonian E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} E = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} in atomic units. This ensemble is selected using the command md_ensemble = NVE in the parameters file. The actual value of the conserved energy will be the result of the initial self-consistent DFT calculation plus the kinetic energy of the initial ionic velocities. These ionic velocities are defined in one of three ways. By explicit user definition of ionic velocities in the cell file, e.g. %BLOCK IONIC_VELOCITIES auv H xxxxx yyyyy zzzzz H xxxxx yyyyy zzzzz O xxxxx yyyyy zzzzz %ENDBLOCK IONIC_VELOCITIES using any valid unit of velocity (auv is atomic unit of velocity), etc. By definition of an initial temperature in the parameters file, e.g. md_temperature = 293 K Note that this can be specified using any valid unit of temperature. In this case initial velocities are assigned randomly such that the total linear momentum is zero and the instantaneous temperature matches that specified. The system will reach equilibrium with a somewhat different temperature due to equipartition of kinetic and potential energy. By continuation from an equilibrated run at the desired temperature. This could be a run in any of the other available ensembles. This will also use the cell and ionic positions from the continuation file. See the section on continuation for details. Velocities read from a continuation file will always take precedence. If no continuation file is used, and both md_temperature and an IONIC_VELOCITIES block are specified, the md_temperature keyword will be ignored. By default, pressure is not calculated during an NVE run. To override this use the command calculate_stress = true in the parameters file.","title":"NVE"},{"location":"documentation/Molecular_Dynamics/basics/#nvt","text":"This ensemble is selected with md_ensemble = NVT The system will be evolved to a specific temperature defined using the md_temperature keyword as used above. Initial velocities are assigned based on this temperature, read from an IONIC_VELOCITIES block in the cell file, or read from a continuation file in the same way as above. Temperature control can be implemented by one of several methods, all of which have been shown to correctly sample the canonical ensemble. The first of these is the deterministic Nose-Hoover chain method of Tuckerman et al 1 and is selected with md_thermostat = nose-hoover in the parameters file. In the NVT case, a single Nose-Hoover chain is coupled to all particle degrees of freedom. The length of the chain can also be specified, e.g. md_nhc_length = 5 for a chain of five thermostats. In the Nose-Hoover case with a chain of M M thermostats acting of N_{f} N_{f} ionic degrees of freedom, the conserved quantity is the pseudo-Hamiltonian \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} \\begin{equation} \\mathcal{H} = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} \\end{equation} where the Q_{i} Q_{i} are the thermostat fictitious masses assigned automatically from the specified ion relaxation time and \\xi_{i} \\xi_{i} are the thermostat degrees of freedom. This is printed with the label Hamilt Energy: at each time-step. A Nose-Hoover thermostat with no chain (i.e. with M M =1 ) is known to not be ergodic and hence should be avoided. The second method of controlling temperature is through the stochastic Langevin thermostat. md_thermostat = langevin In this case the printed Hamiltonian energy is the value of equation above. This is not conserved by the dynamics, but should exhibit no long term drift from the equilibrium value. Finally, the temperature may be controled via the Hoover-Langevin thermostat. md_thermostat = hoover-langevin which is the fusion of a deterministic Nose-Hoover thermostat acting directly on the physical system, with a Langevin thermostat operating on the Nose-Hoover variables, in order to guarantee ergodicity. With each method, a suitable relaxation time for the thermostatic process should be specified. This can use any supported unit of time, e.g md_ion_t = 2.4 ps for a thermostat relaxation time of 2.4 picoseconds. The Hoover-Langevin thermostat is the LEAST sensitive to the choice of this value. As with the NVE ensemble, pressure is not calculated by default. This is overridden in the same way as the NVE case.","title":"NVT"},{"location":"documentation/Molecular_Dynamics/basics/#nph","text":"In this ensemble the size and (if desired) shape of the simulation cell varies to regulate pressure. No thermostat is applied and hence the enthalpy (H) is conserved. This ensemble is specified with the following: md_ensemble = NPH The external pressure is set in the cell definition file using any valid unit of pressure. The required symmetry of the external pressure tensor implies that only the upper triangular components need be specified, e.g. %block external_pressure GPa 0.5 0.0 0.0 0.5 0.0 0.5 %endblock external_pressure to specify an isotropic external pressure of 0.5 Giga-Pascals. MD can also support non-isotropic pressure if using a variable-shape barostat. Velocities are assigned such that the initial temperature is equal to md_temperature , or are read from the cell definition file/continuation file as in the NVE/NVT cases. Two barostat schemes are available. The first restricts the dynamics of the cell to isotropic expansions and contractions. This follows the method of Andersen 2 and Hoover 3 4 as corrected by Martyna et al. 5 . This is selected using: md_barostat = andersen-hoover In this case the printed Hamiltonian energy is the enthalpy, plus the kinetic energy associated with the cell motion. \\begin{equation} \\label{eq:AndersenNPH} H = \\left<\\Psi|\\hat{H} {e}|\\Psi\\right> + \\frac{1}{2} \\sum {N}\\sum_{j=1} {|\\mathbf{R}}\\frac{Z_{i}Z_{j} {i}-\\mathbf{R} +\\sum_{i=1}}| {N}\\frac{P_{i} /2W \\end{equation } The alternative scheme implements the method of Parrinello and Rahman}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2 6 7 . Both the size and shape of the simulation cell are allowed to vary. The issue of cell rotations is eliminated by the use of a symmetrised pressure tensor. Note that as liquids cannot sustain shear, this method should only be used with solids. It should also be noted that this scheme is based on the modified Parrinello-Rahman method of Martyna, Tobias and Klien 5 . The following line in the parameters file selects this barostat. md_barostat = parrinello-rahman The cell dynamics contain nine degrees of freedom (of which six are independent) leading to a Hamiltonian energy of \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} \\begin{equation} \\label{eq:ParRarNPH} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W \\end{equation} For both barostats, a relaxation time for the cell motions should be specified with an appropriate unit of time, for example: md_cell_t = 20 ps This time is used to calculate a fictitious mass W W for the cell dynamics and should be large compared to the characteristic time for the ionic dynamics. The NPH equations of motion require that pressure (stress) is calculated at each MD time-step. The value of calculate_stress is therefore irrelevant in this case. A variable cell implies variable reciprocal lattice vectors which has consequences for the plane-wave basis set. As the cell changes, the number of plane waves required to produce the specified cut-off energy changes. The user therefore has two options. The first is to fix the size of the basis set. fixed_npw = true The cut-off energy is now variable as is the quality of the basis set. This option should therefore only be used for calculations in which the volume changes are small and which are over-converged with respect to the number of plane waves. The second option is to allow the basis set to change at each time-step. fixed_npw = false which is the default value. This keeps the cut-off energy approximately constant by adding or subtracting plane waves from the basis set at each time-step. In either case, the effect of Pulay stress is reduced by applying a finite basis set correction to the pressure at each time-step. In the case of a fixed number of plane waves, the constant correction to energy is ignored. With variable number of plane waves the energy correction is no longer constant and is recalculated at each step.","title":"NPH"},{"location":"documentation/Molecular_Dynamics/basics/#npt","text":"The NPT ensemble is specified with the command: md_ensemble = NPT This can use either the Nose-Hoover or Langevin thermostat, and either Andersen-Hoover or Parrinello-Rahman barostat. In all cases, the dynamics can be shown to correctly sample the isothermal-isobaric ensemble 5 All options pertaining to the NPH and NVT ensembles apply. In the case of Langevin dynamics at NPT, the printed Hamiltonian energy is the same as in the NPH ensemble, i.e. that given by the equations above. In the case of Nose-Hoover NPT molecular dynamics, the Hamiltonian energy is given by \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:HooverNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + p_{\\epsilon}^{2}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + k_{B}T\\sum_{i=1}^{M}\\xi_{bi} \\end{equation} in the case of isotropic cell dynamics, or \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} \\begin{equation} \\label{eq:ParRarNPT} H = \\left<\\Psi|\\hat{H}_{e}|\\Psi\\right> + \\frac{1}{2} \\sum_{i=1}^{N}\\sum_{j=1}^{N}\\frac{Z_{i}Z_{j}} {|\\mathbf{R}_{i}-\\mathbf{R}_{j}|} +\\sum_{i=1}^{N}\\frac{P_{i}^{2}}{2M_{i}} + P_{ext}V + \\mathrm{Tr}[{\\mathbf{p}_{g}\\mathbf{p}_{g}^{T}]}/2W + \\sum_{i=1}^{M}\\frac{p_{\\xi_{i}}^{2}}{2Q_{i}} + N_{f}k_{B}T\\xi_{1} + k_{B}T\\sum_{i=2}^{M}\\xi_{i} + \\sum_{i=1}^{M}\\frac{p_{\\xi_{bi}}^{2}}{2Q_{bi}} + 9k_{B}T\\xi_{b1} + k_{B}T\\sum_{i=2}^{M}\\xi_{bi} \\end{equation} in the Parrinello-Rahman case. Note that in each case the motion of the cell degree(s) of freedom couple to a second Nose-Hoover chain. Glenn J. Martyna, Michael L. Klein, and Mark Tuckerman. Nos\u00e9\u2013Hoover chains: The canonical ensemble via continuous dynamics. The Journal of Chemical Physics , 97(4):2635\u20132643, 08 1992. doi:10.1063/1.463940 . \u21a9 Hans C. Andersen. Molecular dynamics simulations at constant pressure and/or temperature. The Journal of Chemical Physics , 72(4):2384\u20132393, 02 1980. doi:10.1063/1.439486 . \u21a9 William G. Hoover. Canonical dynamics: equilibrium phase-space distributions. Phys. Rev. A , 31:1695\u20131697, Mar 1985. doi:10.1103/PhysRevA.31.1695 . \u21a9 William G. Hoover. Constant-pressure equations of motion. Phys. Rev. A , 34:2499\u20132500, Sep 1986. doi:10.1103/PhysRevA.34.2499 . \u21a9 Glenn J. Martyna, Douglas J. Tobias, and Michael L. Klein. Constant pressure molecular dynamics algorithms. The Journal of Chemical Physics , 101(5):4177\u20134189, 09 1994. doi:10.1063/1.467468 . \u21a9 \u21a9 \u21a9 M. Parrinello and A. Rahman. Crystal structure and pair potentials: a molecular-dynamics study. Phys. Rev. Lett. , 45:1196\u20131199, Oct 1980. doi:10.1103/PhysRevLett.45.1196 . \u21a9 M. Parrinello and A. Rahman. Polymorphic transitions in single crystals: A new molecular dynamics method. Journal of Applied Physics , 52(12):7182\u20137190, 12 1981. doi:10.1063/1.328693 . \u21a9","title":"NPT"},{"location":"documentation/Molecular_Dynamics/files/","text":"Understanding the Output In this chapter we shall briefly describe the output produced during a CASTEP calculation. Only the level of detail printed at iprint = 1 will be discussed. The .castep file Header As well as the usual information printed at the top of the output file, the molecular dynamics data specified in the parameters file is presented. ************************ Molecular Dynamics Parameters ************************ ensemble : NPT variable cell method : fixed basis quality pressure : see below temperature : 293.0 K using : Parrinello-Rahman barostat with characteristic cell time : 26.00 ps using : Langevin thermostat with characteristic ionic time : 16.95 ps time step : 0.2000E-02 ps number of MD steps : 500000 using best-fit first order extrapolation for wavefunctions backup results every : 5 steps MD SCF energy / atom convergence tol. : 0.1000E-04 eV MD SCF convergence tolerance window : 3 cycles ******************************************************************************* This amount of information presented in this section will obviously vary depending on the type of calculation being performed, but should be self-explanatory. Initial cell The information specified in the .cell file is then output. This will include the ionic positions, any user specified velocities if present, the usual pseudo-potential, k-point information, and details of any constraints. The total energy of the initial cell is then minimised, performing a finite basis set correction along the way if appropriate. The message Starting MD is then printed, and the MD calculation proper commences. As the first time-step will require data on forces, stress (for variable cell calculations) and energies, these are evaluated and printed at this point. Forces are output in the following format, using the force unit specified by the user, or the default of eV / Ang. ******************************** Forces ********************************* * * * Cartesian components (eV/A) * * --------------------------------------------------------------------- * * x y z * * * * Si 1 -0.02632 -0.02632 -0.02632 * * Si 2 -0.02653 -0.02617 -0.02617 * * Si 3 -0.02617 -0.02617 -0.02653 * * Si 4 -0.02617 -0.02653 -0.02617 * * Si 5 0.00075 0.05164 0.00075 * * Si 6 0.05204 0.05204 0.05204 * * Si 7 0.05164 0.00075 0.00075 * * Si 8 0.00075 0.00075 0.05164 * * * ************************************************************************* The stress tensor (if calculated) is output in the specified units of pressure, along with the corresponding scalar T=0 T=0 pressure, i.e. one third of the trace of the stress tensor. ***************** Stress Tensor ***************** * * * Cartesian components (GPa) * * --------------------------------------------- * * x y z * * * * x 0.009981 1.140649 1.140649 * * y 1.140649 0.009981 1.140649 * * z 1.140649 1.140649 0.009981 * * * * Pressure: -0.0100 * * * ************************************************* The current time and MD energies are then printed in the user specified energy units. Here potential energy refers to the total configurational energy of electrons plus ions obtained from the DFT calculation. Kinetic energy is the classical kinetic energy of the ions. Total energy refers to the sum of these two energies. The enthalpy and the relevant Hamiltonian energy for the ensemble as quoted in section ensembles is then printed. The temperature is also output at this point. Note that this is the ionic temperature only. If performing a calculation with finite temperature electrons (i.e. EDFT) the electron temperature may not be the same. Finally total pressure, i.e. the trace of the stress tensor plus the kinetic (ideal gas) pressure is printed in the user specified pressure units. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx x MD Data: x x x x time : 0.000000 ps x x x x Potential Energy: -865.882944 eV x x Kinetic Energy: 0.265113 eV x x Total Energy: -865.617832 eV x x Enthalpy: -865.617735 eV x x Hamilt Energy: -865.617735 eV x x x x Temperature: 293.000000 K x x T/=0 Pressure: 0.172231 GPa x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Iteration The MD simulation proper now begins. ================================================================= Starting MD iteration 1 ... ================================================================= Following this message the current cell information on the new configuration is printed and the energy is re-minimised to determine the new forces. The MD step is then performed and the updated forces, stress and energy information is printed in the same manner as above. ----------------------------------------------------------------- ... finished MD iteration 1 ----------------------------------------------------------------- The process repeats until the calculation is killed, or the specified number of MD iterations is completed. The .md file The .md file is provided as a single source for all the dynamical data produced by a CASTEP calculation. In all cases, data is printed in Hartree atomic units. Fortran formating data will be given here for all entries in this file for those who wish to import it into their own analysis codes. The CASTEP default behaviour is to record every single configuration in the .md file. This can therefore grow to quite a large size if doing a long MD run! The only exception to this, is if doing a non-DFT calculation, whereupon a sample of the configurations are written if md_sample_iter >0, otherwise no configurations are written. Note that unlike the .castep file, the .md file from a previous calculation with the same seedname will be overwritten, unless the new calculation is a continuation of the original. Header At the top of every .md file a header is written as below. The total length is four lines including blanks. The comments written are taken from the cell/parameter files. BEGIN header This is 8 atom cubic Si cell END header This is followed by a blank line. There is a single space at the start of each non-blank line. This header is written once only. Time and Energy Data The next entry will be the data for the first MD step. This begins with the current time on the first line, followed by the Total, Hamiltonian, and Kinetic energy on the second line with the label <-- E . 0.00000000E+000 -3.18206146E+001 -3.18108683E+001 9.74270683E-003 <-- E Formatting: format(12x,es18.8e3) format(9x,3(3x,es18.8e3),' <-- E') Thermodynamic Data The current temperature is then printed with the label <-- T . If the output is from a variable cell calculation, or calculate_stress has been explicitly set to true, the pressure is also printed with the label <-- P . 9.27876841E-04 <-- T 5.85402338E-06 <-- P Formatting: format(12x,es18.8,T73, ' <-- T') format(12x,es18.8,T73, ' <-- P') Cell Data For all calculations, the current matrix of cell vectors is printed with the label <-- h Each row gives the three Cartesian components of one of the cell vectors. 1.01599045E+001 0.00000000E+000 0.00000000E+000 <-- h 1.29430839E-017 1.01599045E+001 0.00000000E+000 <-- h 1.29430839E-017 1.29430839E-017 1.01599045E+001 <-- h Formatting: format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') The remaining cell data is only printed for variable cell calculations, regardless of the value of calculate_stress . First the velocity of each cell vector is printed with the label <-- hv . 2.80052926E-008 -1.42751448E-007 -1.35787248E-007 <-- hv -1.42751448E-007 2.76907508E-008 -1.44694219E-007 <-- hv -1.35787248E-007 -1.44694219E-007 2.71532850E-008 <-- hv Formatting: format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') The full pressure tensor (including kinetic contributions) is then printed with the label <-- S in a similar fashion. -6.21684372E-006 3.03062374E-005 3.23291890E-005 <-- S 3.03062374E-005 -6.06171719E-006 3.31426773E-005 <-- S 3.23291890E-005 3.31426773E-005 -5.79666096E-006 <-- S Formatting: format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') Ionic Data Data on the current ionic configuration is then printed. Atoms are identified by their chemical symbol in the first column, and number of the atom within the species in the second. First the position vectors of all ions are printed with the label <-- R . Si 1 1.04834750E-002 1.15560090E-002 7.82230990E-003 <-- R Si 2 -3.20400394E-003 5.07172565E+000 5.10986361E+000 <-- R Si 3 5.07271954E+000 5.11656710E+000 -2.45225140E-003 <-- R Si 4 5.10789066E+000 -2.63240242E-002 5.09753015E+000 <-- R Si 5 7.57309188E+000 2.52845762E+000 7.57612741E+000 <-- R Si 6 2.55271297E+000 2.54057876E+000 2.53924276E+000 <-- R Si 7 2.53422324E+000 7.64091983E+000 7.62428191E+000 <-- R Si 8 7.63167143E+000 7.59610368E+000 2.52717191E+000 <-- R Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- R') Velocities are then printed in a similar fashion. Si 1 5.77278549E-005 7.23673746E-005 4.30349159E-005 <-- V Si 2 -1.72415752E-005 -5.23270551E-005 1.75385181E-004 <-- V Si 3 -4.17085102E-005 2.14539848E-004 -1.78769096E-005 <-- V Si 4 1.58756714E-004 -1.60916056E-004 9.49147966E-005 <-- V Si 5 -2.70431102E-004 -7.18757382E-005 -2.43440176E-004 <-- V Si 6 7.51663795E-005 8.70332331E-008 -8.82271461E-006 <-- V Si 7 -4.19898677E-005 1.31687892E-004 3.60873179E-005 <-- V Si 8 7.97201068E-005 -1.33563298E-004 -7.92824105E-005 <-- V Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- V') Finally forces are printed. Si 1 -4.23569381E-003 2.52214252E-003 -2.46018145E-003 <-- F Si 2 3.06338418E-003 -2.16206923E-003 -5.29928454E-003 <-- F Si 3 7.37259995E-004 -4.73479365E-003 -2.20030945E-003 <-- F Si 4 -6.89050954E-003 -2.25153379E-003 -8.37626756E-003 <-- F Si 5 4.53551291E-003 3.34757083E-003 1.02791157E-002 <-- F Si 6 2.06737343E-003 2.05175887E-003 2.70990363E-003 <-- F Si 7 -1.41457164E-003 -9.15433604E-004 1.54850432E-003 <-- F Si 8 2.13724448E-003 2.14235805E-003 3.79851935E-003 <-- F Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- F') A blank line is then printed, and the process repeats with the data from the next time-step. The .hug file If you are using the Hugoniostat predictor-corrector method to generate a Hugoniot curve, each different state point generated has a different compression etc. This is summarized in the .hug file as follows: 0.990000000000 36.31531287 0.41888602 0.15771481 <-- cTPE 0.943272613764 40.07750465 0.63662992 1.62298398 <-- cTPE 0.865294155381 58.07130958 1.30346964 6.92736406 <-- cTPE The 4 data fields are: c - the ratio of the compressed to original cell vectors T - the temperature (in user units) - calculated as a time average of the instantaneous temperature of the configurations at this compression P - the pressure (in user units) - calculated as a time average E - the energy (in user units) - calculated as a time average","title":"MD Files"},{"location":"documentation/Molecular_Dynamics/files/#understanding-the-output","text":"In this chapter we shall briefly describe the output produced during a CASTEP calculation. Only the level of detail printed at iprint = 1 will be discussed.","title":"Understanding the Output"},{"location":"documentation/Molecular_Dynamics/files/#the-castep-file","text":"","title":"The .castep file"},{"location":"documentation/Molecular_Dynamics/files/#header","text":"As well as the usual information printed at the top of the output file, the molecular dynamics data specified in the parameters file is presented. ************************ Molecular Dynamics Parameters ************************ ensemble : NPT variable cell method : fixed basis quality pressure : see below temperature : 293.0 K using : Parrinello-Rahman barostat with characteristic cell time : 26.00 ps using : Langevin thermostat with characteristic ionic time : 16.95 ps time step : 0.2000E-02 ps number of MD steps : 500000 using best-fit first order extrapolation for wavefunctions backup results every : 5 steps MD SCF energy / atom convergence tol. : 0.1000E-04 eV MD SCF convergence tolerance window : 3 cycles ******************************************************************************* This amount of information presented in this section will obviously vary depending on the type of calculation being performed, but should be self-explanatory.","title":"Header"},{"location":"documentation/Molecular_Dynamics/files/#initial-cell","text":"The information specified in the .cell file is then output. This will include the ionic positions, any user specified velocities if present, the usual pseudo-potential, k-point information, and details of any constraints. The total energy of the initial cell is then minimised, performing a finite basis set correction along the way if appropriate. The message Starting MD is then printed, and the MD calculation proper commences. As the first time-step will require data on forces, stress (for variable cell calculations) and energies, these are evaluated and printed at this point. Forces are output in the following format, using the force unit specified by the user, or the default of eV / Ang. ******************************** Forces ********************************* * * * Cartesian components (eV/A) * * --------------------------------------------------------------------- * * x y z * * * * Si 1 -0.02632 -0.02632 -0.02632 * * Si 2 -0.02653 -0.02617 -0.02617 * * Si 3 -0.02617 -0.02617 -0.02653 * * Si 4 -0.02617 -0.02653 -0.02617 * * Si 5 0.00075 0.05164 0.00075 * * Si 6 0.05204 0.05204 0.05204 * * Si 7 0.05164 0.00075 0.00075 * * Si 8 0.00075 0.00075 0.05164 * * * ************************************************************************* The stress tensor (if calculated) is output in the specified units of pressure, along with the corresponding scalar T=0 T=0 pressure, i.e. one third of the trace of the stress tensor. ***************** Stress Tensor ***************** * * * Cartesian components (GPa) * * --------------------------------------------- * * x y z * * * * x 0.009981 1.140649 1.140649 * * y 1.140649 0.009981 1.140649 * * z 1.140649 1.140649 0.009981 * * * * Pressure: -0.0100 * * * ************************************************* The current time and MD energies are then printed in the user specified energy units. Here potential energy refers to the total configurational energy of electrons plus ions obtained from the DFT calculation. Kinetic energy is the classical kinetic energy of the ions. Total energy refers to the sum of these two energies. The enthalpy and the relevant Hamiltonian energy for the ensemble as quoted in section ensembles is then printed. The temperature is also output at this point. Note that this is the ionic temperature only. If performing a calculation with finite temperature electrons (i.e. EDFT) the electron temperature may not be the same. Finally total pressure, i.e. the trace of the stress tensor plus the kinetic (ideal gas) pressure is printed in the user specified pressure units. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx x MD Data: x x x x time : 0.000000 ps x x x x Potential Energy: -865.882944 eV x x Kinetic Energy: 0.265113 eV x x Total Energy: -865.617832 eV x x Enthalpy: -865.617735 eV x x Hamilt Energy: -865.617735 eV x x x x Temperature: 293.000000 K x x T/=0 Pressure: 0.172231 GPa x xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","title":"Initial cell"},{"location":"documentation/Molecular_Dynamics/files/#iteration","text":"The MD simulation proper now begins. ================================================================= Starting MD iteration 1 ... ================================================================= Following this message the current cell information on the new configuration is printed and the energy is re-minimised to determine the new forces. The MD step is then performed and the updated forces, stress and energy information is printed in the same manner as above. ----------------------------------------------------------------- ... finished MD iteration 1 ----------------------------------------------------------------- The process repeats until the calculation is killed, or the specified number of MD iterations is completed.","title":"Iteration"},{"location":"documentation/Molecular_Dynamics/files/#the-md-file","text":"The .md file is provided as a single source for all the dynamical data produced by a CASTEP calculation. In all cases, data is printed in Hartree atomic units. Fortran formating data will be given here for all entries in this file for those who wish to import it into their own analysis codes. The CASTEP default behaviour is to record every single configuration in the .md file. This can therefore grow to quite a large size if doing a long MD run! The only exception to this, is if doing a non-DFT calculation, whereupon a sample of the configurations are written if md_sample_iter >0, otherwise no configurations are written. Note that unlike the .castep file, the .md file from a previous calculation with the same seedname will be overwritten, unless the new calculation is a continuation of the original.","title":"The .md file"},{"location":"documentation/Molecular_Dynamics/files/#header_1","text":"At the top of every .md file a header is written as below. The total length is four lines including blanks. The comments written are taken from the cell/parameter files. BEGIN header This is 8 atom cubic Si cell END header This is followed by a blank line. There is a single space at the start of each non-blank line. This header is written once only.","title":"Header"},{"location":"documentation/Molecular_Dynamics/files/#time-and-energy-data","text":"The next entry will be the data for the first MD step. This begins with the current time on the first line, followed by the Total, Hamiltonian, and Kinetic energy on the second line with the label <-- E . 0.00000000E+000 -3.18206146E+001 -3.18108683E+001 9.74270683E-003 <-- E Formatting: format(12x,es18.8e3) format(9x,3(3x,es18.8e3),' <-- E')","title":"Time and Energy Data"},{"location":"documentation/Molecular_Dynamics/files/#thermodynamic-data","text":"The current temperature is then printed with the label <-- T . If the output is from a variable cell calculation, or calculate_stress has been explicitly set to true, the pressure is also printed with the label <-- P . 9.27876841E-04 <-- T 5.85402338E-06 <-- P Formatting: format(12x,es18.8,T73, ' <-- T') format(12x,es18.8,T73, ' <-- P')","title":"Thermodynamic Data"},{"location":"documentation/Molecular_Dynamics/files/#cell-data","text":"For all calculations, the current matrix of cell vectors is printed with the label <-- h Each row gives the three Cartesian components of one of the cell vectors. 1.01599045E+001 0.00000000E+000 0.00000000E+000 <-- h 1.29430839E-017 1.01599045E+001 0.00000000E+000 <-- h 1.29430839E-017 1.29430839E-017 1.01599045E+001 <-- h Formatting: format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') format(9x,3(3x,es18.8e3),' <-- h') The remaining cell data is only printed for variable cell calculations, regardless of the value of calculate_stress . First the velocity of each cell vector is printed with the label <-- hv . 2.80052926E-008 -1.42751448E-007 -1.35787248E-007 <-- hv -1.42751448E-007 2.76907508E-008 -1.44694219E-007 <-- hv -1.35787248E-007 -1.44694219E-007 2.71532850E-008 <-- hv Formatting: format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') format(9x,3(3x,es18.8e3),' <-- hv') The full pressure tensor (including kinetic contributions) is then printed with the label <-- S in a similar fashion. -6.21684372E-006 3.03062374E-005 3.23291890E-005 <-- S 3.03062374E-005 -6.06171719E-006 3.31426773E-005 <-- S 3.23291890E-005 3.31426773E-005 -5.79666096E-006 <-- S Formatting: format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S') format(9x,3(3x,es18.8e3),' <-- S')","title":"Cell Data"},{"location":"documentation/Molecular_Dynamics/files/#ionic-data","text":"Data on the current ionic configuration is then printed. Atoms are identified by their chemical symbol in the first column, and number of the atom within the species in the second. First the position vectors of all ions are printed with the label <-- R . Si 1 1.04834750E-002 1.15560090E-002 7.82230990E-003 <-- R Si 2 -3.20400394E-003 5.07172565E+000 5.10986361E+000 <-- R Si 3 5.07271954E+000 5.11656710E+000 -2.45225140E-003 <-- R Si 4 5.10789066E+000 -2.63240242E-002 5.09753015E+000 <-- R Si 5 7.57309188E+000 2.52845762E+000 7.57612741E+000 <-- R Si 6 2.55271297E+000 2.54057876E+000 2.53924276E+000 <-- R Si 7 2.53422324E+000 7.64091983E+000 7.62428191E+000 <-- R Si 8 7.63167143E+000 7.59610368E+000 2.52717191E+000 <-- R Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- R') Velocities are then printed in a similar fashion. Si 1 5.77278549E-005 7.23673746E-005 4.30349159E-005 <-- V Si 2 -1.72415752E-005 -5.23270551E-005 1.75385181E-004 <-- V Si 3 -4.17085102E-005 2.14539848E-004 -1.78769096E-005 <-- V Si 4 1.58756714E-004 -1.60916056E-004 9.49147966E-005 <-- V Si 5 -2.70431102E-004 -7.18757382E-005 -2.43440176E-004 <-- V Si 6 7.51663795E-005 8.70332331E-008 -8.82271461E-006 <-- V Si 7 -4.19898677E-005 1.31687892E-004 3.60873179E-005 <-- V Si 8 7.97201068E-005 -1.33563298E-004 -7.92824105E-005 <-- V Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- V') Finally forces are printed. Si 1 -4.23569381E-003 2.52214252E-003 -2.46018145E-003 <-- F Si 2 3.06338418E-003 -2.16206923E-003 -5.29928454E-003 <-- F Si 3 7.37259995E-004 -4.73479365E-003 -2.20030945E-003 <-- F Si 4 -6.89050954E-003 -2.25153379E-003 -8.37626756E-003 <-- F Si 5 4.53551291E-003 3.34757083E-003 1.02791157E-002 <-- F Si 6 2.06737343E-003 2.05175887E-003 2.70990363E-003 <-- F Si 7 -1.41457164E-003 -9.15433604E-004 1.54850432E-003 <-- F Si 8 2.13724448E-003 2.14235805E-003 3.79851935E-003 <-- F Formatting (for each atom): format(1x,a3,1x,i4,3(3x,es18.8e3),' <-- F') A blank line is then printed, and the process repeats with the data from the next time-step.","title":"Ionic Data"},{"location":"documentation/Molecular_Dynamics/files/#the-hug-file","text":"If you are using the Hugoniostat predictor-corrector method to generate a Hugoniot curve, each different state point generated has a different compression etc. This is summarized in the .hug file as follows: 0.990000000000 36.31531287 0.41888602 0.15771481 <-- cTPE 0.943272613764 40.07750465 0.63662992 1.62298398 <-- cTPE 0.865294155381 58.07130958 1.30346964 6.92736406 <-- cTPE The 4 data fields are: c - the ratio of the compressed to original cell vectors T - the temperature (in user units) - calculated as a time average of the instantaneous temperature of the configurations at this compression P - the pressure (in user units) - calculated as a time average E - the energy (in user units) - calculated as a time average","title":"The .hug file"},{"location":"documentation/Molecular_Dynamics/hugoniostat/","text":"Hugoniostat The Hugoniostat is an approach to simulate shock-waves in DFT through a pseudo-ensemble which drives the temperature and pressure to the point on the Hugoniot line. Two Hugoniotstat methods are implemented. The constant volume Hugoniostat (NVHug) of Maillet et al. 1 and the constant pressure/stress Hugoniostat of Ravelo et al. 2 . The NVHug and NPHug algorithms are a form of pseudo-ensemble which means that the do not strictly conserve a formal quantity, but drive the system into a desired state. The algorithms are implemented as other CASTEP ensembles and use many of the common MD keywords and can function with with any of the standard CASTEP thermostat methods (see basics ). Details of extended Hugoniostat methods can be found in the PhD thesis 3 where the methods were initially implemented in CASTEP. Hugoniot Equation of State The Hugoniot describes the shocked state of the system \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} where subscript 1 1 and 2 2 refer to the states ahead and behind the shock-front, \\rho{} \\rho{} is the mass density of the fluid, u u is the fluid velocity, P P is the pressure and h h is the specific enthalpy (per unit mass). It can also be formulated in terms of the shock speed: \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) where u_{s} u_{s} is the shock speed and e e is the specific internal energy. Using substitutions of the mass conservation & momentum conservation into the energy conservation it is possible to derive the Hugoniot equation: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), which in the per-unit-mass basis gives us: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), NVHug The NVHug method performs a static cell calculation at a compression ratio of md_hug_compression in the direction specified by md_hug_dir (by default ISO tropic). The equations of motion that govern NVHug are (in the Nose-Hoover formulation): \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), where \\chi{} \\chi{} is the heat-flow of the thermostat into the system, \\nu{} \\nu{} is the coupling between the thermostat and the system, C C is a scaling constant in units of energy to conserve system size independence and E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) where t_{0} t_{0} is the time before the system has been compressed (i.e. the equilibrium state), we deem the deviation of our current state from the Hugoniot state the Hugoniot estimator: E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). Example .param task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NVHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 md_hug_compression : 0.7 NPHug The equations of motion that govern the NPHug Hugoniostat (in the Nose-Hoover formulation) are: \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), where \\alpha{} \\alpha{} refers to an element in the direction of a cell-vector \\vec{h} \\vec{h} , \\nu{}_{H} \\nu{}_{H} is the coupling of the thermostat to the system, \\nu{}_{P}{} \\nu{}_{P}{} is the coupling of the barostat piston to the system, \\sigma{} \\sigma{} is the target pressure tensor and P P is the instantaneous total pressure tensor, D D is a scaling constant in units of pressure to conserve system size independence, Ravelo et al . 2 suggest the equilibrium bulk modulus ( B_{0} B_{0} ) . Example .param task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NPHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 .cell ... %block external_pressure GPa 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 10.0 %endblock external_pressure Accelerated Equilibration Due to the nature of plane-wave density functional theory (DFT) calculations and the way in which the forces are calculated, DFT can be very susceptible to rapid changes in structure and can become unstable at extremely high temperatures, and if atoms become close enough the fundamental assumptions of non-polarisability of core electrons becomes invalid in DFT. DFT is also expensive to calculate compared to the empirical force-fields, and so wasting as little calculation as possible is essential. The accelerated equilibration methods exist to make the process of computing shockwaves faster and more robust. Damping Ravelo et al . 2 suggested applying damping to the \"velocity\" of the thermo-/barostats preventing the over-shoot of the ideal Hugeoniot values. This makes the thermostat NVHug formulation: \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, and similarly for the update equation of motion of the NPHug formulation: \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, where \\beta{}_{H} \\beta{}_{H} and \\beta{}_{p} \\beta{}_{p} are user-defined damping coefficients for the heat-flow and barostat piston respectively, chosen to bring about critical damping to the Hugoniot state. Related Keywords beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs Examples %block devel_code md: BETA_T=0.1 BETA_H=0.1 :endmd # Lightly Damped md: BETA_T=0.3 BETA_H=0.3 :endmd # Damped %enblock devel_code Effects of the damping on the Langevin scheme (Eq. 4.2) on a 500- atom Lennard-Jones cell at 60% volume with an overly strong Hugoniostat coupling ( \\nu{}_{H} \\nu{}_{H} ) of 0.1fs^{\u22121} 0.1fs^{\u22121} and a damping factor ( \\beta{}_{H} \\beta{}_{H} ) of (Undamped) 0.0, (Lightly Damped) 0.1, (Damped) 0.3. Quenching Quenching is a more extreme version of damping where upon the \"acceleration\" of the thermo-/barostat changing sign, the \"velocity\" is reset to 0. Because this is not directly coupled to the system this does not damage the internal dynamics of the system and can lead to faster convergence and more stable temperatures. Particularly in the initial phases of NVHug where upon initial compression temperatures and pressures can spike. Quenching only takes place during the equilibration phase as determined by md_eqm_t Related Keywords quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat velocity upon changing direction for rapid equilibration Examples %block devel_code md: QUENCH_T=T :endmd # Quench Thermostat md: QUENCH_P=T :endmd # Quench Barostat %enblock devel_code The effects of quenching on the temperature of a 70% volume 500-atom Lennard-Jones system, unquenched line (black) shows a large tran- sient initially, the quenched lines (blue and green) show the elimination of this transient at the expense of \u201cunphysical\u201d temperature dynamics, which are eliminated when the quenching is turned off (blue) after equilibration. It should be noted that all three converge to the same temperature. Steady compression Steady compression spreads the system compression in NVHug compression over a period of time rather than compressing instantaneously to allow the system to equilibrate more steadily and avoid transient temperature and pressure spikes. This was also proposed in Ravelo et al . 2 as a means of smoothing equilibration. k-points and wavefunction samples are determined from the compressed cell so that the NVHug can be more efficient for the majority of the run. compression_t and compression_rate are two different ways of specifying the same thing either as %/fs or fs/% . When the compression has reached the target compression the compression will stop. For steady compression, it is generally best to compress the system for slightly less time than the equilibration period to ensure that the system is in a valid steady state before measuring data. compression_block gives the system time to equilibrate between compressions by compressing every compression_block steps rather than every step (though the compression at each compression step will be larger s.t. compression_rate and compression_t are preserved). Relevant Keywords compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure. Examples md_eqm_t: 600fs %block devel_code md: compression_t=400 :endmd %enblock devel_code Effect of steady compression on reducing initial transients during equilibration. Predictor-corrector (Experimental) Due to the nature of DFT, where a lot of important properties (e.g. wavefunctions) are tied to the simulation cell, it is generally more efficient to use a fixed-cell calculation in order to reduce the computational expense of recalculating all the properties which are related to the cell. This means that using NVHug is generally more efficient in CASTEP, however, we are usually more interested in sampling particular pressures on the Hugoniot rather than the effect of a given compression. The predictor-corrector attempts to mitigate these issues by using past measures on the Hugoniot curve to automatically trace out the Hugoniot curve up to a given pressure with a series of NVHug simulations. It uses the previous hist_len points to fit a curve and predict what compression would give the target pressure and run it. Tracing out the Hugoniot to target_p in either steps steps or steps of size pstep . E.g. pc: target_p=10 steps=2 :endpc Will target 5 and 10GPa pc: target_p=10 pstep=2 :endpc will target 2, 4, 6, 8 and 10GPa err determines how close the actual pressure must be to the target to be accepted, relative to the actual target. E.g. pc: target_p=10 err=0.1 :endpc Will accept any calculation whose final Hugoniot P P is between 9-11GPa as complete and move to the next target. The reuse keyword causes the P-C to use the final state of the previous step as the initial state of the current. Including temperature/pressure and atomic positions to speed up the equilibration process. max_delta limits the compression step the P-C can take between stages to ensure that initial steps, where estimates are limited by lack of datapoints, in very stiff materials do not result in extreme temperature or pressure jumps where fundamental assumptions of DFT may break down and cause the system to fail. Related Keywords pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's final state as the next steps initial state. max_delta : (Physical) Maximum attempted compression step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep Examples PC: PC=T TARGET_P=1.0 STEPS=2 METHOD='LIN' AV_METHOD='RUNAV' :ENDPC Keywords Summary Param Keywords md_ensemble : Should be set to HUG to use Hugoniostat methods. md_hug_method : (NONE, NVHUG, NPHUG) Hugoniostat method. (default: NONE) md_hug_dir : (XDIR, YDIR, ZDIR, ISO) Hugoniostat compression direction. (default: ISO) md_hug_t : (Physical) Hugoniostat coupling constant. md_hug_compression : (Physical) Hugoniostat compression ratio \\frac{V}{V_{0}} \\frac{V}{V_{0}} . Values from 0.0 to 1.0 (default) Devel Code Parameters MD Block chem_pot : (Physical) Manually specify total chemical potential (scaling factor) in eV Equilibration Acceleration quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat upon changing direction for rapid equilibration eqm_hug_t : (Physical) Hugoniostat coupling during equilibration phase in 1/fs beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure. Running Averages ra_len : (Integer) Number of running average steps to use in calculating final Hugoniot av_method : (CUMAV, RUNAV, DIRCT, FINAL) Method for computing Hugoniot to dump to .hug file. Initial States ma_init_t : (Logical) Use Maillet hugoniostat temperature estimator as initial temperature. init_eta : (Physical) Initial \\eta{} \\eta{} (cell compression velocity) for NPHug in \\tfrac{A}{fs} \\tfrac{A}{fs} . temp_init : (Physical) Initial temperature to be used for each hug stage (overriding md_temperature each stage in P-C) in K K . PC Block pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's temperature as initial temperature rather than md_temperature max_delta : (Physical) Maximum attempted pressure step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep J.-B. Maillet, M. Mareschal, L. Soulard, R. Ravelo, P. S. Lomdahl, T. C. Germann, and B. L. Holian. Uniaxial hugoniostat: a method for atomistic simulations of shocked materials. Phys. Rev. E , 63:016121, Dec 2000. doi:10.1103/PhysRevE.63.016121 . \u21a9 R. Ravelo, B. L. Holian, T. C. Germann, and P. S. Lomdahl. Constant-stress hugoniostat method for following the dynamical evolution of shocked matter. Phys. Rev. B , 70:014103, Jul 2004. doi:10.1103/PhysRevB.70.014103 . \u21a9 \u21a9 \u21a9 \u21a9 Jacob Wilkins. Exploration of approaches to shock-wave simulations . PhD thesis, University of York, July 2019. URL: https://etheses.whiterose.ac.uk/24444/ . \u21a9","title":"Hugoniostat"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#hugoniostat","text":"The Hugoniostat is an approach to simulate shock-waves in DFT through a pseudo-ensemble which drives the temperature and pressure to the point on the Hugoniot line. Two Hugoniotstat methods are implemented. The constant volume Hugoniostat (NVHug) of Maillet et al. 1 and the constant pressure/stress Hugoniostat of Ravelo et al. 2 . The NVHug and NPHug algorithms are a form of pseudo-ensemble which means that the do not strictly conserve a formal quantity, but drive the system into a desired state. The algorithms are implemented as other CASTEP ensembles and use many of the common MD keywords and can function with with any of the standard CASTEP thermostat methods (see basics ). Details of extended Hugoniostat methods can be found in the PhD thesis 3 where the methods were initially implemented in CASTEP.","title":"Hugoniostat"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#hugoniot-equation-of-state","text":"The Hugoniot describes the shocked state of the system \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Mass:} \\qquad{}\\quad{}~~\\,\\rho{}_{1}u_{1} = \\rho{}_{2}u_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Momentum:} \\qquad{} \\rho{}u_{1}^{2} + P_{1} = \\rho{}u_{2}^{2} + P_{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} \\text{Energy:} \\qquad{} h_{1} + \\tfrac{1}{2}u_{1}^{2} = h_{2} + \\tfrac{1}{2}u_{2}^{2} where subscript 1 1 and 2 2 refer to the states ahead and behind the shock-front, \\rho{} \\rho{} is the mass density of the fluid, u u is the fluid velocity, P P is the pressure and h h is the specific enthalpy (per unit mass). It can also be formulated in terms of the shock speed: \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Mass:} \\qquad{}\\rho{}_{1}u_{s} = \\rho{}_{2}(u_{s} - u_{2}) \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Momentum:} \\qquad{} P_{2}-P_{1} = \\rho{}_{2}u_{2}(u_{s}-u_{2}) = \\rho{}_{1}u_{s}u_{2} \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) \\text{Energy:} \\qquad{} P_2\\,u_2 = \\rho{}_{1}u_{s}(\\tfrac{1}{2}u_{2}^{2} + e_{2} - e_{1}) where u_{s} u_{s} is the shock speed and e e is the specific internal energy. Using substitutions of the mass conservation & momentum conservation into the energy conservation it is possible to derive the Hugoniot equation: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(\\rho{}_{1}^{\\text{-}1}-\\rho{}_{2}^{\\text{-}1}), which in the per-unit-mass basis gives us: e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}), e_{2} - e_{1} = \\tfrac{1}{2}(P_{1} + P_{2})(V_{1}-V_{2}),","title":"Hugoniot Equation of State"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#nvhug","text":"The NVHug method performs a static cell calculation at a compression ratio of md_hug_compression in the direction specified by md_hug_dir (by default ISO tropic). The equations of motion that govern NVHug are (in the Nose-Hoover formulation): \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{r}}_{i} = \\frac{\\textbf{p}_{i}}{m_{i}}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\textbf{p}}_{i} = \\textbf{F}_{i} - \\nu{}\\chi{}\\textbf{p}_{i}, \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}}{C}(E(t) - E_{H}(t)), where \\chi{} \\chi{} is the heat-flow of the thermostat into the system, \\nu{} \\nu{} is the coupling between the thermostat and the system, C C is a scaling constant in units of energy to conserve system size independence and E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) E_{H}(t) = E(t_{0}) + \\tfrac{1}{2}(P(t) + P(t_{0})(V(t_{0}) - V(t)) where t_{0} t_{0} is the time before the system has been compressed (i.e. the equilibrium state), we deem the deviation of our current state from the Hugoniot state the Hugoniot estimator: E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)). E(t) - E_{H}(t) = E(t) - E(t_{0}) - \\tfrac{1}{2}(P(t) + P(t_{0}))(V(t_{0}) - V(t)).","title":"NVHug"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#example","text":"","title":"Example"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param","text":"task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NVHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000 md_hug_compression : 0.7","title":".param"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#nphug","text":"The equations of motion that govern the NPHug Hugoniostat (in the Nose-Hoover formulation) are: \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{r}_{\\alpha{}i} = \\frac{p_{\\alpha{}i}}{m_{i}} + \\nu{}_{P}\\eta{}_{\\alpha{}}r_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{p}_{\\alpha{}i} = F_{\\alpha{}i} - (\\nu{}_{p}\\eta{}_{\\alpha{}} - \\nu{}_{H}\\chi{})p_{\\alpha{}i}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{h}_{\\alpha{}\\alpha{}} = \\nu{}_{p}\\eta{}_{\\alpha{}}h_{\\alpha{}\\alpha{}}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}), where \\alpha{} \\alpha{} refers to an element in the direction of a cell-vector \\vec{h} \\vec{h} , \\nu{}_{H} \\nu{}_{H} is the coupling of the thermostat to the system, \\nu{}_{P}{} \\nu{}_{P}{} is the coupling of the barostat piston to the system, \\sigma{} \\sigma{} is the target pressure tensor and P P is the instantaneous total pressure tensor, D D is a scaling constant in units of pressure to conserve system size independence, Ravelo et al . 2 suggest the equilibrium bulk modulus ( B_{0} B_{0} ) .","title":"NPHug"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#example_1","text":"","title":"Example"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param_1","text":"task : molecular dynamics md_ensemble : HUG md_hug_dir : ZDIR md_hug_method : NPHug md_temperature : 70 K md_thermostat : langevin md_hug_t : 10 fs md_ion_t : 50 fs md_delta_t : 1 fs md_eqm_t : 500 fs md_num_iter : 1000","title":".param"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#cell","text":"... %block external_pressure GPa 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 10.0 %endblock external_pressure","title":".cell"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#accelerated-equilibration","text":"Due to the nature of plane-wave density functional theory (DFT) calculations and the way in which the forces are calculated, DFT can be very susceptible to rapid changes in structure and can become unstable at extremely high temperatures, and if atoms become close enough the fundamental assumptions of non-polarisability of core electrons becomes invalid in DFT. DFT is also expensive to calculate compared to the empirical force-fields, and so wasting as little calculation as possible is essential. The accelerated equilibration methods exist to make the process of computing shockwaves faster and more robust.","title":"Accelerated Equilibration"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#damping","text":"Ravelo et al . 2 suggested applying damping to the \"velocity\" of the thermo-/barostats preventing the over-shoot of the ideal Hugeoniot values. This makes the thermostat NVHug formulation: \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, \\dot{\\chi{}} = \\frac{\\nu{}_{H}}{C}(E(t) - E_{H}(t)) - \\beta{}_{H}\\chi{}, and similarly for the update equation of motion of the NPHug formulation: \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, \\dot{\\eta{}}_{\\alpha{}} = \\frac{\\nu{}_{p}}{D}(P_{\\alpha{}\\alpha{}}(t) - \\sigma{}_{\\alpha{}\\alpha{}}) - \\beta{}_{p}\\eta{}, where \\beta{}_{H} \\beta{}_{H} and \\beta{}_{p} \\beta{}_{p} are user-defined damping coefficients for the heat-flow and barostat piston respectively, chosen to bring about critical damping to the Hugoniot state.","title":"Damping"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords","text":"beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples","text":"%block devel_code md: BETA_T=0.1 BETA_H=0.1 :endmd # Lightly Damped md: BETA_T=0.3 BETA_H=0.3 :endmd # Damped %enblock devel_code Effects of the damping on the Langevin scheme (Eq. 4.2) on a 500- atom Lennard-Jones cell at 60% volume with an overly strong Hugoniostat coupling ( \\nu{}_{H} \\nu{}_{H} ) of 0.1fs^{\u22121} 0.1fs^{\u22121} and a damping factor ( \\beta{}_{H} \\beta{}_{H} ) of (Undamped) 0.0, (Lightly Damped) 0.1, (Damped) 0.3.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#quenching","text":"Quenching is a more extreme version of damping where upon the \"acceleration\" of the thermo-/barostat changing sign, the \"velocity\" is reset to 0. Because this is not directly coupled to the system this does not damage the internal dynamics of the system and can lead to faster convergence and more stable temperatures. Particularly in the initial phases of NVHug where upon initial compression temperatures and pressures can spike. Quenching only takes place during the equilibration phase as determined by md_eqm_t","title":"Quenching"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords_1","text":"quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat velocity upon changing direction for rapid equilibration","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_1","text":"%block devel_code md: QUENCH_T=T :endmd # Quench Thermostat md: QUENCH_P=T :endmd # Quench Barostat %enblock devel_code The effects of quenching on the temperature of a 70% volume 500-atom Lennard-Jones system, unquenched line (black) shows a large tran- sient initially, the quenched lines (blue and green) show the elimination of this transient at the expense of \u201cunphysical\u201d temperature dynamics, which are eliminated when the quenching is turned off (blue) after equilibration. It should be noted that all three converge to the same temperature.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#steady-compression","text":"Steady compression spreads the system compression in NVHug compression over a period of time rather than compressing instantaneously to allow the system to equilibrate more steadily and avoid transient temperature and pressure spikes. This was also proposed in Ravelo et al . 2 as a means of smoothing equilibration. k-points and wavefunction samples are determined from the compressed cell so that the NVHug can be more efficient for the majority of the run. compression_t and compression_rate are two different ways of specifying the same thing either as %/fs or fs/% . When the compression has reached the target compression the compression will stop. For steady compression, it is generally best to compress the system for slightly less time than the equilibration period to ensure that the system is in a valid steady state before measuring data. compression_block gives the system time to equilibrate between compressions by compressing every compression_block steps rather than every step (though the compression at each compression step will be larger s.t. compression_rate and compression_t are preserved).","title":"Steady compression"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#relevant-keywords","text":"compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure.","title":"Relevant Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_2","text":"md_eqm_t: 600fs %block devel_code md: compression_t=400 :endmd %enblock devel_code Effect of steady compression on reducing initial transients during equilibration.","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#predictor-corrector-experimental","text":"Due to the nature of DFT, where a lot of important properties (e.g. wavefunctions) are tied to the simulation cell, it is generally more efficient to use a fixed-cell calculation in order to reduce the computational expense of recalculating all the properties which are related to the cell. This means that using NVHug is generally more efficient in CASTEP, however, we are usually more interested in sampling particular pressures on the Hugoniot rather than the effect of a given compression. The predictor-corrector attempts to mitigate these issues by using past measures on the Hugoniot curve to automatically trace out the Hugoniot curve up to a given pressure with a series of NVHug simulations. It uses the previous hist_len points to fit a curve and predict what compression would give the target pressure and run it. Tracing out the Hugoniot to target_p in either steps steps or steps of size pstep . E.g. pc: target_p=10 steps=2 :endpc Will target 5 and 10GPa pc: target_p=10 pstep=2 :endpc will target 2, 4, 6, 8 and 10GPa err determines how close the actual pressure must be to the target to be accepted, relative to the actual target. E.g. pc: target_p=10 err=0.1 :endpc Will accept any calculation whose final Hugoniot P P is between 9-11GPa as complete and move to the next target. The reuse keyword causes the P-C to use the final state of the previous step as the initial state of the current. Including temperature/pressure and atomic positions to speed up the equilibration process. max_delta limits the compression step the P-C can take between stages to ensure that initial steps, where estimates are limited by lack of datapoints, in very stiff materials do not result in extreme temperature or pressure jumps where fundamental assumptions of DFT may break down and cause the system to fail.","title":"Predictor-corrector (Experimental)"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#related-keywords_2","text":"pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's final state as the next steps initial state. max_delta : (Physical) Maximum attempted compression step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep","title":"Related Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#examples_3","text":"PC: PC=T TARGET_P=1.0 STEPS=2 METHOD='LIN' AV_METHOD='RUNAV' :ENDPC","title":"Examples"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#keywords-summary","text":"","title":"Keywords Summary"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#param-keywords","text":"md_ensemble : Should be set to HUG to use Hugoniostat methods. md_hug_method : (NONE, NVHUG, NPHUG) Hugoniostat method. (default: NONE) md_hug_dir : (XDIR, YDIR, ZDIR, ISO) Hugoniostat compression direction. (default: ISO) md_hug_t : (Physical) Hugoniostat coupling constant. md_hug_compression : (Physical) Hugoniostat compression ratio \\frac{V}{V_{0}} \\frac{V}{V_{0}} . Values from 0.0 to 1.0 (default)","title":"Param Keywords"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#devel-code-parameters","text":"","title":"Devel Code Parameters"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#md-block","text":"chem_pot : (Physical) Manually specify total chemical potential (scaling factor) in eV","title":"MD Block"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#equilibration-acceleration","text":"quench_t : (Logical) Quench thermostat velocity upon changing direction for rapid equilibration quench_p : (Logical) Quench barostat upon changing direction for rapid equilibration eqm_hug_t : (Physical) Hugoniostat coupling during equilibration phase in 1/fs beta_t : (Physical) Damping parameter for Hugoniostat temperature coupling in 1/fs beta_h : (Physical) Damping parameter for Hugoniostat pressure coupling in 1/fs compression_t : (Physical) Time over which the compression should take place for pressure ramping in fs fs . compression_rate : (Physical) Rate of decrease of cell volume as \\tfrac{\\%}{fs} \\tfrac{\\%}{fs} . compression_block : (Integer) Number of steps between cell compressions to steadily ramp up pressure.","title":"Equilibration Acceleration"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#running-averages","text":"ra_len : (Integer) Number of running average steps to use in calculating final Hugoniot av_method : (CUMAV, RUNAV, DIRCT, FINAL) Method for computing Hugoniot to dump to .hug file.","title":"Running Averages"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#initial-states","text":"ma_init_t : (Logical) Use Maillet hugoniostat temperature estimator as initial temperature. init_eta : (Physical) Initial \\eta{} \\eta{} (cell compression velocity) for NPHug in \\tfrac{A}{fs} \\tfrac{A}{fs} . temp_init : (Physical) Initial temperature to be used for each hug stage (overriding md_temperature each stage in P-C) in K K .","title":"Initial States"},{"location":"documentation/Molecular_Dynamics/hugoniostat/#pc-block","text":"pc : (Logical) Use predictor-corrector algorithm to attempt to trace the Hugoniot line automatically. reuse : (Logical) Reuse previous compression's temperature as initial temperature rather than md_temperature max_delta : (Physical) Maximum attempted pressure step difference for P-C in GPa err (Physical) Permitted difference between attained and target considered accepted target_p : (Physical) Highest target pressure for P-C to reach in GPa pstep : (Physical) Reach target_p in steps of approximately pstep GPa steps : (Integer) Reach target_p in approximately steps steps method : (LIN, POLY, EXP) Equation form to use for predictor corrector estimation, POLY nomial is recommended. poly_order : (Integer) Polynomial order used in POLY nomial method hist_len : (Integer) Length of history to keep J.-B. Maillet, M. Mareschal, L. Soulard, R. Ravelo, P. S. Lomdahl, T. C. Germann, and B. L. Holian. Uniaxial hugoniostat: a method for atomistic simulations of shocked materials. Phys. Rev. E , 63:016121, Dec 2000. doi:10.1103/PhysRevE.63.016121 . \u21a9 R. Ravelo, B. L. Holian, T. C. Germann, and P. S. Lomdahl. Constant-stress hugoniostat method for following the dynamical evolution of shocked matter. Phys. Rev. B , 70:014103, Jul 2004. doi:10.1103/PhysRevB.70.014103 . \u21a9 \u21a9 \u21a9 \u21a9 Jacob Wilkins. Exploration of approaches to shock-wave simulations . PhD thesis, University of York, July 2019. URL: https://etheses.whiterose.ac.uk/24444/ . \u21a9","title":"PC Block"},{"location":"documentation/Molecular_Dynamics/keywords/","text":"To perform a molecular dynamics calculation set the task parameter task : md To control the length of the dynamics simulation md_num_iter : number of MD steps (default 100) md_delta_t : MD timestep (default 1fs) To control the conditions for the dynamics md_ensemble : Ensemble (NVE, NVT, NPH, NPT, HUG) md_thermostat : Thermostat to use if not a constant energy ensemble. values: NOSE-HOOVER (default), LANGEVIN, HOOVER-LANGEVIN md_barostat : Barostat to use if not a constant volume ensemble. Values: ANDERSEN-HOOVER (default), PARRINELLO-RAHMAN md_temperature : Temperature to use if not a constant energy ensemble For the Hugoniot Thermostat md_hug_method : Hugoniostat method. Values: NONE (default), NVHUG, NPHUG md_hug_dir : Hugoniostat compression direction. Values: XDIR, YDIR, ZDIR, ISO (default) md_hug_t : Hugoniostat coupling constant. md_hug_compression : Hugoniostat compression ratio. Values from 0.0 to 1.0 (default) Path Integral MD (PIMD) MD_USE_PATHINT PIMD on/off MD_NUM_BEADS PIMD number of beads MD_PATHINT_INIT PIMD initialisation method MD_PATHINT_STAGING PIMD staging modes on/off MD_PATHINT_NUM_STAGES PIMD number of stages Advanced settings It is possible to change the tolerances for accepting the SCF groundstate during the molecular dynamics run. The default value are those for a single point energy e.g. the default for md_elec_energy_tol is the value of elec_energy_tol md_elec_energy_tol : MD total energy per atom convergence tolerance md_elec_eigenvalue_tol : MD eigenvalue convergence tolerance md_elec_force_tol : max force per atom convergence tolerance md_elec_convergence_win : MD convergence tolerance window MD_EQM_METHOD MD enhanced equilibration method MD_EQM_ION_T MD equilibration time for ions MD_EQM_CELL_T MD equilibration time for cell MD_EQM_T MD equilibration time MD_ION_T MD characteristic ionic time MD_CELL_T MD characteristic cell time MD_CELL_DAMP_RINGING Damp cell ringing mode MD_USE_PLUMED Use PLUMED metadynamics","title":"MD Keywords"},{"location":"documentation/Molecular_Dynamics/keywords/#path-integral-md-pimd","text":"MD_USE_PATHINT PIMD on/off MD_NUM_BEADS PIMD number of beads MD_PATHINT_INIT PIMD initialisation method MD_PATHINT_STAGING PIMD staging modes on/off MD_PATHINT_NUM_STAGES PIMD number of stages","title":"Path Integral MD (PIMD)"},{"location":"documentation/Molecular_Dynamics/keywords/#advanced-settings","text":"It is possible to change the tolerances for accepting the SCF groundstate during the molecular dynamics run. The default value are those for a single point energy e.g. the default for md_elec_energy_tol is the value of elec_energy_tol md_elec_energy_tol : MD total energy per atom convergence tolerance md_elec_eigenvalue_tol : MD eigenvalue convergence tolerance md_elec_force_tol : max force per atom convergence tolerance md_elec_convergence_win : MD convergence tolerance window MD_EQM_METHOD MD enhanced equilibration method MD_EQM_ION_T MD equilibration time for ions MD_EQM_CELL_T MD equilibration time for cell MD_EQM_T MD equilibration time MD_ION_T MD characteristic ionic time MD_CELL_T MD characteristic cell time MD_CELL_DAMP_RINGING Damp cell ringing mode MD_USE_PLUMED Use PLUMED metadynamics","title":"Advanced settings"},{"location":"documentation/Molecular_Dynamics/overview/","text":"Instead of using the forces to optimise the structure of the system, CASTEP can instead use the forces to accelerate the atoms (and cell-shape) in order to simulate dynamical properties - a method known as \"Molecular Dynamics\" or simply \"MD\". To perform this kind of calculation, set task : MD in your param file. CASTEP has a wide range of Molecular Dynamics (MD) capabilities, and can do equilibrium MD using a variety of ensembles: NVE - the microcanonical ensemble - with fixed number of atoms, volume of cell, and total energy conserved NVT - the canonical ensemble - with constant temperature not constant energy - due to the application of a thermostat NPH - constant external pressure and enthalpy - due to the application of a barostat NPT - constant external pressure and temperature - due to the application of a barostat and a thermostat HUG - the Hugoniostat - a special thermo-barostat algorithm to find states on the Hugoniot curve Of these, NPT is the closest to most real-life experiments. Of the different thermostats, CASTEP supports Nose-Hoover, Nose-Hoover chains, Langevin and Hoover-Langevin. Of the different barostats, CASTEP supports the isotropic Andersen-Hoover barostat, and the anisotropic Parrinello-Rahman barostat. CASTEP also supports the Berendsen thermostat and barostat, as a route to faster equilibration before switching to one of the above thermostats/barostats for production data. As well as generating different classical ensembles, CASTEP can also generate a state on the Hugoniot using the Hugoniostat algorithm. In fact, CASTEP can generate multiple sets of points on the Hugoniot curve in a single calculation. CASTEP can also go beyond the Born-Oppenheimer approximation to do quantum dynamics, using Path Integral Molecular Dynamics (PIMD), in either NVT or NPT ensembles, using the Langevin thermostat. In all MD schemes, CASTEP can support both linear and non-linear constraints on the ionic positions and/or on the cell vectors. The detailed trajectory information is written to a .md file, which is a structured text file (similar to the .geom file), for ease of manipulation and post-calculation analysis.","title":"MD Overview"},{"location":"documentation/Molecular_Dynamics/pimd/","text":"For some systems, with light atoms and/or at low temperatures, the zero-point motion of the atom (rather than the electrons) can become significant. This requires a level of theory beyond the Born-Oppenheimer approximation, which assuming that the nuclei can be treated as classical point charges. One way of doing this, is the Feynman Path Integral approach to quantum mechanics, and using the isomorphism of a ring of classical \"beads and springs\" to represent a quantum particle. This approach is combined with MD to generate an ensemble of configurations, and so the approach is known as Path Integral Molecular Dynamics (PIMD). With this approach, quantum expectation values can be calculated by trajectory averages. Hence classical MD analysis techniques can be used to generate quantum values. Keywords PIMD is a form of MD, and so all the usual MD keywords apply. NB the only supported md_thermostat is Langevin but this works with all values of md_barostat . To activate PIMD, the key variables are: md_use_pathint : true md_num_beads : 2 which turns on PIMD and 2 beads. It is important to note that the number of beads is an extra convergence parameter - the discretized ring becomes a continuous path integral in the limit that the number of beads tends to infinity. In practice, this is usually 2 -- 128 for light atoms (e.g. hydrogen) at temperatures > 10K. For lower temperatures, the number of beads goes up significantly. num_farms : 2 This is an important way to parallelize a PIMD calculation. With task farming, each bead can be assigned to a farm, so the number of farms should be either 1 (no farming) or md_num_beads . Then the PIMD calculation can be run in parallel on num_farms blocks of processors, where the number of processors in each block is determined by the usual CASTEP+DFT parallelization strategies (k-points, g-vectors, bands etc). More advanced keywords are: md_pathint_init : point / Gaussian md_pathint_staging : true This determines how the initial beads positions for a given atom are assigned. 'point' puts all the beads at the same point, whilst 'Gaussian' uses a Gaussian spreading function, which is analyticaly correct for a free particle to estimate the delocalization at the given temperature. The staging mode transformation is a key way to eliminate the natural harmonics in the dynamics of the ring of beads, which would otherwise significantly reduce the time step required, particularly at low temperatures. Output files When doing a PIMD calculation, there is md_num_beads times more information generated! Hence if using farming, then only the centroid position of and velocity etc of each ring of beads (corresponding to the classical position of each atom) is output to the .castep file. The coordinate data for each value of imaginary time (the cyclic index labelling the beads for each atom) is written to individual farmXXX.castep where XXX is the farm number. If not farming, then all this data is written to the single .castep file. The size of each ring for each atom at each real timestep is analysed in terms of the 'radius of gyration' tensor, and the 3 RGY eigenvalues and corresponding eigenvectors are also output to the master .castep file. In addition, there are beadXXX.md files produced, one per imaginary time value (number of beads). These can be used for different MD analysis techniques, and can also be merged using scripts such as pimerge.pl to put all the bead data for each value of real time into the same file, which can be useful for visualization of the bead dynamics. Working with i-pi i-pi is a 3 rd -party python package for doing PIMD. This needs other codes, such as CASTEP, to generate the forces for a given configuration, and can then do different forms of PIMD, including centroid PIMD, which is not natively supported by CASTEP. i-pi communicates to CASTEP via internet sockets. The support for this is built into CASTEP from v22 or later. There is an example of running i-pi with CASTEP in the examples/castep directory, along with a 'run_me' script that launches the i-pi server, creates a set of sub-directories (one per bead), and then launches the separate CASTEP clients. If doing PIMD in this mode, then you do not set PIMD variables in the .param file but rather in an i-pi input.xml file. The CASTEP .param file keywords needed are: task : socketdriver socket_port: 31415 socket_host: localhost where the task tells CASTEP to communicate with i-pi on socket_port (in this case, it is sent the bead coordinates and returns the energy and forces). The socket_host can be localhost, or an internet host, if running on a remote server. For more information, see the i-pi website .","title":"PIMD"},{"location":"documentation/Molecular_Dynamics/pimd/#keywords","text":"PIMD is a form of MD, and so all the usual MD keywords apply. NB the only supported md_thermostat is Langevin but this works with all values of md_barostat . To activate PIMD, the key variables are: md_use_pathint : true md_num_beads : 2 which turns on PIMD and 2 beads. It is important to note that the number of beads is an extra convergence parameter - the discretized ring becomes a continuous path integral in the limit that the number of beads tends to infinity. In practice, this is usually 2 -- 128 for light atoms (e.g. hydrogen) at temperatures > 10K. For lower temperatures, the number of beads goes up significantly. num_farms : 2 This is an important way to parallelize a PIMD calculation. With task farming, each bead can be assigned to a farm, so the number of farms should be either 1 (no farming) or md_num_beads . Then the PIMD calculation can be run in parallel on num_farms blocks of processors, where the number of processors in each block is determined by the usual CASTEP+DFT parallelization strategies (k-points, g-vectors, bands etc). More advanced keywords are: md_pathint_init : point / Gaussian md_pathint_staging : true This determines how the initial beads positions for a given atom are assigned. 'point' puts all the beads at the same point, whilst 'Gaussian' uses a Gaussian spreading function, which is analyticaly correct for a free particle to estimate the delocalization at the given temperature. The staging mode transformation is a key way to eliminate the natural harmonics in the dynamics of the ring of beads, which would otherwise significantly reduce the time step required, particularly at low temperatures.","title":"Keywords"},{"location":"documentation/Molecular_Dynamics/pimd/#output-files","text":"When doing a PIMD calculation, there is md_num_beads times more information generated! Hence if using farming, then only the centroid position of and velocity etc of each ring of beads (corresponding to the classical position of each atom) is output to the .castep file. The coordinate data for each value of imaginary time (the cyclic index labelling the beads for each atom) is written to individual farmXXX.castep where XXX is the farm number. If not farming, then all this data is written to the single .castep file. The size of each ring for each atom at each real timestep is analysed in terms of the 'radius of gyration' tensor, and the 3 RGY eigenvalues and corresponding eigenvectors are also output to the master .castep file. In addition, there are beadXXX.md files produced, one per imaginary time value (number of beads). These can be used for different MD analysis techniques, and can also be merged using scripts such as pimerge.pl to put all the bead data for each value of real time into the same file, which can be useful for visualization of the bead dynamics.","title":"Output files"},{"location":"documentation/Molecular_Dynamics/pimd/#working-with-i-pi","text":"i-pi is a 3 rd -party python package for doing PIMD. This needs other codes, such as CASTEP, to generate the forces for a given configuration, and can then do different forms of PIMD, including centroid PIMD, which is not natively supported by CASTEP. i-pi communicates to CASTEP via internet sockets. The support for this is built into CASTEP from v22 or later. There is an example of running i-pi with CASTEP in the examples/castep directory, along with a 'run_me' script that launches the i-pi server, creates a set of sub-directories (one per bead), and then launches the separate CASTEP clients. If doing PIMD in this mode, then you do not set PIMD variables in the .param file but rather in an i-pi input.xml file. The CASTEP .param file keywords needed are: task : socketdriver socket_port: 31415 socket_host: localhost where the task tells CASTEP to communicate with i-pi on socket_port (in this case, it is sent the bead coordinates and returns the energy and forces). The socket_host can be localhost, or an internet host, if running on a remote server. For more information, see the i-pi website .","title":"Working with i-pi"},{"location":"documentation/Molecular_Dynamics/restarts/","text":"Check-pointing, Continuation and Parameter Changes As with any other calculation in CASTEP, checkpoint files are written at regular intervals. Should the calculation be interrupted for whatever reason, it is possible to continue from the point at which the checkpoint file was last written. Check-pointing is performed by dumping all pertinent data to a .check file. The interval at which this check-pointing occurs can be controlled in two ways. The first option is to specify the number of md steps between checkpoints. num_backup_iter = 5 Alternatively, the wall-clock time (in seconds) between backups can be specified with: backup_interval = 60 Both can be specified but backup_interval will be preferred over num_backup_iter if both are set. To disable either option, set the corresponding parameter to zero. The name of the checkpoint file will be the calculation seed-name followed by \".check\". This can be overridden with: checkpoint = my_md_run.check To continue an MD calculation from a checkpoint file, ensure that the .check file, the .castep file and the .md file from the previous run are present in the current directory. If the seed-name of the new run is the same as for the old, the command continuation = default will suffice. To continue the run from a checkpoint file my_md_run.check use: continuation = my_md_run.check Note the standard CASTEP behaviour is to append new data to the end of existing files (such as .castep and .md) to avoid loosing data from earlier runs. This is not the case for the .check file, which is overwritten with new data. For this reason, the default CASTEP behaviour is to make a backup of the .check file, before over-writing it, so as to minimize the risk of data loss. Changing Parameters on Continuation Check-pointing is particularly useful for MD calculations where we often require many thousands of time-steps to extract useful information. Another important benefit is the ability to halt a calculation, and continue from a checkpoint with a revised set of MD parameters. For example one may wish to alter the target thermostat temperature, or the cell relaxation time without having to restart the run from the unequilibrated configuration. All options described in the above sections can be changed on a restart, i.e. it is possible to change ensemble, thermostat and barostat schemes, relaxation times, time-step, constraints, etc. by specifying new values in the input files for the new run. It is not possible to change the number of atoms/electrons in the cell upon a restart. Care must be taken when changing parameters on a restart. For example a large discontinuous change in the specified temperature or pressure will perturb a system away from equilibrium. In such cases the system should not be sampled until re-equilibrated. Although it is possible to change electronic minimisation schemes/parameters on a restart, this is somewhat unwise for obvious reasons. On-The-Fly Parameter Changes In fact, molecular dynamics parameters can be changed without having to halt the calculation at all! At the end of each MD step, the parameters file is re-read. Any parameters in this file which differ from those currently in use will be updated before the next MD step commences. It is therefore possible to alter the state of a running calculation by simply making changes to the parameters file while the calculation is running. The same considerations/restrictions which apply to changing parameters on a restart apply to these on the fly changes.","title":"MD Restarts"},{"location":"documentation/Molecular_Dynamics/restarts/#check-pointing-continuation-and-parameter-changes","text":"As with any other calculation in CASTEP, checkpoint files are written at regular intervals. Should the calculation be interrupted for whatever reason, it is possible to continue from the point at which the checkpoint file was last written. Check-pointing is performed by dumping all pertinent data to a .check file. The interval at which this check-pointing occurs can be controlled in two ways. The first option is to specify the number of md steps between checkpoints. num_backup_iter = 5 Alternatively, the wall-clock time (in seconds) between backups can be specified with: backup_interval = 60 Both can be specified but backup_interval will be preferred over num_backup_iter if both are set. To disable either option, set the corresponding parameter to zero. The name of the checkpoint file will be the calculation seed-name followed by \".check\". This can be overridden with: checkpoint = my_md_run.check To continue an MD calculation from a checkpoint file, ensure that the .check file, the .castep file and the .md file from the previous run are present in the current directory. If the seed-name of the new run is the same as for the old, the command continuation = default will suffice. To continue the run from a checkpoint file my_md_run.check use: continuation = my_md_run.check Note the standard CASTEP behaviour is to append new data to the end of existing files (such as .castep and .md) to avoid loosing data from earlier runs. This is not the case for the .check file, which is overwritten with new data. For this reason, the default CASTEP behaviour is to make a backup of the .check file, before over-writing it, so as to minimize the risk of data loss.","title":"Check-pointing, Continuation and Parameter Changes"},{"location":"documentation/Molecular_Dynamics/restarts/#changing-parameters-on-continuation","text":"Check-pointing is particularly useful for MD calculations where we often require many thousands of time-steps to extract useful information. Another important benefit is the ability to halt a calculation, and continue from a checkpoint with a revised set of MD parameters. For example one may wish to alter the target thermostat temperature, or the cell relaxation time without having to restart the run from the unequilibrated configuration. All options described in the above sections can be changed on a restart, i.e. it is possible to change ensemble, thermostat and barostat schemes, relaxation times, time-step, constraints, etc. by specifying new values in the input files for the new run. It is not possible to change the number of atoms/electrons in the cell upon a restart. Care must be taken when changing parameters on a restart. For example a large discontinuous change in the specified temperature or pressure will perturb a system away from equilibrium. In such cases the system should not be sampled until re-equilibrated. Although it is possible to change electronic minimisation schemes/parameters on a restart, this is somewhat unwise for obvious reasons.","title":"Changing Parameters on Continuation"},{"location":"documentation/Molecular_Dynamics/restarts/#on-the-fly-parameter-changes","text":"In fact, molecular dynamics parameters can be changed without having to halt the calculation at all! At the end of each MD step, the parameters file is re-read. Any parameters in this file which differ from those currently in use will be updated before the next MD step commences. It is therefore possible to alter the state of a running calculation by simply making changes to the parameters file while the calculation is running. The same considerations/restrictions which apply to changing parameters on a restart apply to these on the fly changes.","title":"On-The-Fly Parameter Changes"},{"location":"documentation/Molecular_Dynamics/tools/","text":"JMol can read a .md file and animate the motion of the atoms. See the tutorials for examples of more tools for MD.","title":"MD Tools"},{"location":"documentation/NMR/NMR_overview/","text":"Diamagnetic Insulators By a diamagnetic insulator we mean a system with an electronic gap between its highest occupied state and lowest unoccupied state, and all of the electronic spins are paired, simple examples are diamond, quartz, glycine\u2026 This class of materials is the most suitable for calculations as the main NMR interactions, magnetic sielding, J-coupling and electric field gradients can all be computed. Magnetic Shielding In a diamagnetic insulator this arises from orbital currents induced by an external magnetic field. This current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , produces a non-uniform induced magnetic field in the material, which is given by the Biot-Savart law as {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. The shielding tensor is defined as the ratio between this induced field, and the external applied field {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. It can thus be seen that the question of computing the shielding tensor is that of computing the induced electronic current. J-coupling The J-coupling is a small perturbation to the electronic ground-state of the system and we can identify it as a derivative of the total energy E, of the system {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} An equivalent expression arises from considering one nuclear spin (L) as perturbation which creates a magnetic field at a second (receiving) nucleus (K) {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. Eqn.~\\ref{eq:J} tells us that the question of computing J is essentially that of computing the magnetic field induced indirectly by a nuclear magnetic moment. When spin-orbit coupling is neglected we can consider the field as arising from two, essentially independent, mechanisms. Firstly, the magnetic moment can interact with electronic charge inducing an orbital current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , which in turn creates a magnetic field at the other nuclei in the system. This mechanism is similar to the case of magnetic shielding in insulators. The second mechanism arises from the interaction of the magnetic moment with the electronic spin, causing an electronic spin polarisation. By working to first order in these quantities we can write the magnetic field at atom {\\rm K} {\\rm K} induced by the magnetic moment of atom {\\rm L} {\\rm L} as {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. Several quantum chemistry packages provide the ability to compute J coupling tensors in molecular systems (see Helgaker et al . 1 } for a review of methods). An approach to compute J tensors within the planewave-pseudopotential approach has recently been developed 2 . EFG For a nucleus with spin > > \u00bd the NMR response will include an interaction between the quadrupole moment of the nucleus, Q, and the electric field gradient (EFG) generated by the surrounding electronic structure. The EFG is a second rank, symmetric, traceless tensor G({\\bf r}) G({\\bf r}) given by G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} where \\alpha,\\beta,\\gamma \\alpha,\\beta,\\gamma denote the Cartesian coordinates x,y,z and E_{\\alpha}({\\bf r}) E_{\\alpha}({\\bf r}) is the local electric field at the position {\\bf r} {\\bf r} , which can be calculated from the charge density n({\\bf r}) n({\\bf r}) : \\begin{equation} E_{\\alpha}({\\bf r})=\\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3} (r_{\\alpha}-r_{\\alpha}'). \\end{equation} The EFG tensor is then equal to \\begin{equation}\\label{eq:efg_rs} G_{\\alpha\\beta}({\\bf r}) = \\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3}\\left[ \\delta_{\\alpha\\beta} -3 \\frac{(r_{\\alpha}-r_{\\alpha}')(r_{\\beta}-r_{\\beta}')}{|{\\bf r}-{\\bf r}'|^2}\\right]. \\end{equation} The computation of electric field gradient tensors is less demanding than either shielding or J-coupling tensors as it requires only knowledge of the electronic ground state. The LAPW approach in its implementation within the Wien series of codes 3 has been widely used and shown to reliably predict Electric Field Gradient (EFG) tensors 4 . The equivalent formalism for the planewave/PAW approach is reported in Profeta et al . 5 . The quadrupolar coupling constant, C _Q _Q and the asymmetry parameter, \\eta_Q \\eta_Q can be obtained from the the diagonalized electric field gradient tensor whose eigenvalues are labelled V _{xx} _{xx} , V _{yy} _{yy} , V _{zz} _{zz} , such that |V_{zz}|>|V_{yy}|>|V_{xx}| |V_{zz}|>|V_{yy}|>|V_{xx}| : \\begin{equation} C_{Q}=\\frac{eV_{zz}Q}{h}, \\end{equation} where h is Planck's constant and \\begin{equation} \\eta_Q=\\frac{V_{xx}-V_{yy}}{V_{zz}}. \\end{equation} Trygve Helgaker, Micha\u0142 Jaszu\u0144ski, and Magdalena Pecul. The quantum-chemical calculation of nmr indirect spin\u2013spin coupling constants. Progress in Nuclear Magnetic Resonance Spectroscopy , 53(4):249\u2013268, 2008. doi:10.1016/j.pnmrs.2008.02.002 . \u21a9 Si\u00e2n A. Joyce, Jonathan R. Yates, Chris J. Pickard, and Francesco Mauri. A first principles theory of nuclear magnetic resonance J-coupling in solid-state systems. The Journal of Chemical Physics , 127(20):204107, 11 2007. doi:10.1063/1.2801984 . \u21a9 P. Blaha, K. Schwarz, P. Sorantin, and S.B. Trickey. Full-potential, linearized augmented plane wave programs for crystalline systems. Computer Physics Communications , 59(2):399\u2013415, 1990. doi:10.1016/0010-4655(90)90187-6 . \u21a9 P. Blaha, P. Sorantin, C. Ambrosch, and K. Schwarz. Calculation of the electric field gradient tensor from energy band structures. Hyperfine Interactions , 51(1):917\u2013923, Jun 1989. doi:10.1007/BF02407802 . \u21a9 Mickael Profeta, Francesco Mauri, and Chris J. Pickard. Accurate first principles prediction of 17O NMR parameters in SiO2: assignment of the zeolite ferrierite spectrum. Journal of the American Chemical Society , 125(2):541\u2013548, 2003. PMID: 12517169. doi:10.1021/ja027124r . \u21a9","title":"NMR Overview"},{"location":"documentation/NMR/NMR_overview/#diamagnetic-insulators","text":"By a diamagnetic insulator we mean a system with an electronic gap between its highest occupied state and lowest unoccupied state, and all of the electronic spins are paired, simple examples are diamond, quartz, glycine\u2026 This class of materials is the most suitable for calculations as the main NMR interactions, magnetic sielding, J-coupling and electric field gradients can all be computed.","title":"Diamagnetic Insulators"},{"location":"documentation/NMR/NMR_overview/#magnetic-shielding","text":"In a diamagnetic insulator this arises from orbital currents induced by an external magnetic field. This current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , produces a non-uniform induced magnetic field in the material, which is given by the Biot-Savart law as {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. {\\bf B}_{\\rm in}({\\bf r}) =\\frac{1}{c}\\int d^3r' {\\bf j}({\\bf r}')\\times \\frac{{\\bf r}-{\\bf r}'}{|{\\bf r}-{\\bf r}'|^3}. The shielding tensor is defined as the ratio between this induced field, and the external applied field {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. {\\bf B}_{\\rm in}({\\bf r})=-{\\vec{\\sigma}}({\\bf r}){\\bf B}_{\\rm ext}. It can thus be seen that the question of computing the shielding tensor is that of computing the induced electronic current.","title":"Magnetic Shielding"},{"location":"documentation/NMR/NMR_overview/#j-coupling","text":"The J-coupling is a small perturbation to the electronic ground-state of the system and we can identify it as a derivative of the total energy E, of the system {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} {\\bf J}_{\\rm KL}= \\frac{\\hbar\\gamma_{\\rm K}\\gamma_{\\rm L}}{2\\pi}\\frac{\\partial^2 E}{\\partial {\\bf m}_{\\rm K} \\partial {\\bf m}_{\\rm L}} An equivalent expression arises from considering one nuclear spin (L) as perturbation which creates a magnetic field at a second (receiving) nucleus (K) {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{2\\pi}{\\hbar\\gamma_{{\\rm K}}\\gamma_{{\\rm L}}}{\\bf J}_{{\\rm KL}} \\cdot {\\bf m}_{{\\rm L}}. Eqn.~\\ref{eq:J} tells us that the question of computing J is essentially that of computing the magnetic field induced indirectly by a nuclear magnetic moment. When spin-orbit coupling is neglected we can consider the field as arising from two, essentially independent, mechanisms. Firstly, the magnetic moment can interact with electronic charge inducing an orbital current {\\bf j}({\\bf r}) {\\bf j}({\\bf r}) , which in turn creates a magnetic field at the other nuclei in the system. This mechanism is similar to the case of magnetic shielding in insulators. The second mechanism arises from the interaction of the magnetic moment with the electronic spin, causing an electronic spin polarisation. By working to first order in these quantities we can write the magnetic field at atom {\\rm K} {\\rm K} induced by the magnetic moment of atom {\\rm L} {\\rm L} as {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} {\\bf B}^{(1)}_{\\rm in}({\\bf R}_{{\\rm K}}) = \\frac{\\mu_{0}}{4\\pi}\\int {\\bf m}^{(1)}({\\bf r})\\cdot \\left[\\frac{3{\\bf r}_{{\\rm K}}{\\bf r}_{{\\rm K}} - |{\\bf r}_{{\\rm K}}|^{2}}{|{\\bf r}_{{\\rm K}}|^{5}}\\right]\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\frac{8\\pi}{3}\\int {\\bf m}^{(1)}({\\bf r}) \\delta({\\bf r}_{{\\rm K}})\\,{\\rm d}^{3}{\\bf r} + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. + \\frac{\\mu_{0}}{4\\pi}\\int {\\bf j}^{(1)}({\\bf r})\\times \\frac{{\\bf r}_{{\\rm K}}}{|{\\bf r}_{{\\rm K}}|^{3}}\\,{\\rm d}^{3}{\\bf r}. Several quantum chemistry packages provide the ability to compute J coupling tensors in molecular systems (see Helgaker et al . 1 } for a review of methods). An approach to compute J tensors within the planewave-pseudopotential approach has recently been developed 2 .","title":"J-coupling"},{"location":"documentation/NMR/NMR_overview/#efg","text":"For a nucleus with spin > > \u00bd the NMR response will include an interaction between the quadrupole moment of the nucleus, Q, and the electric field gradient (EFG) generated by the surrounding electronic structure. The EFG is a second rank, symmetric, traceless tensor G({\\bf r}) G({\\bf r}) given by G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} G_{\\alpha\\beta}({\\bf r}) = \\frac{\\partial E_{\\alpha}({\\bf r})}{\\partial r_{\\beta}} - \\frac{1}{3}\\delta_{\\alpha\\beta}\\sum_{\\gamma}\\frac{\\partial E_{\\gamma}({\\bf r})}{\\partial r_{\\gamma}} where \\alpha,\\beta,\\gamma \\alpha,\\beta,\\gamma denote the Cartesian coordinates x,y,z and E_{\\alpha}({\\bf r}) E_{\\alpha}({\\bf r}) is the local electric field at the position {\\bf r} {\\bf r} , which can be calculated from the charge density n({\\bf r}) n({\\bf r}) : \\begin{equation} E_{\\alpha}({\\bf r})=\\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3} (r_{\\alpha}-r_{\\alpha}'). \\end{equation} The EFG tensor is then equal to \\begin{equation}\\label{eq:efg_rs} G_{\\alpha\\beta}({\\bf r}) = \\int d^3r \\frac{n({\\bf r})}{|{\\bf r}-{\\bf r}'|^3}\\left[ \\delta_{\\alpha\\beta} -3 \\frac{(r_{\\alpha}-r_{\\alpha}')(r_{\\beta}-r_{\\beta}')}{|{\\bf r}-{\\bf r}'|^2}\\right]. \\end{equation} The computation of electric field gradient tensors is less demanding than either shielding or J-coupling tensors as it requires only knowledge of the electronic ground state. The LAPW approach in its implementation within the Wien series of codes 3 has been widely used and shown to reliably predict Electric Field Gradient (EFG) tensors 4 . The equivalent formalism for the planewave/PAW approach is reported in Profeta et al . 5 . The quadrupolar coupling constant, C _Q _Q and the asymmetry parameter, \\eta_Q \\eta_Q can be obtained from the the diagonalized electric field gradient tensor whose eigenvalues are labelled V _{xx} _{xx} , V _{yy} _{yy} , V _{zz} _{zz} , such that |V_{zz}|>|V_{yy}|>|V_{xx}| |V_{zz}|>|V_{yy}|>|V_{xx}| : \\begin{equation} C_{Q}=\\frac{eV_{zz}Q}{h}, \\end{equation} where h is Planck's constant and \\begin{equation} \\eta_Q=\\frac{V_{xx}-V_{yy}}{V_{zz}}. \\end{equation} Trygve Helgaker, Micha\u0142 Jaszu\u0144ski, and Magdalena Pecul. The quantum-chemical calculation of nmr indirect spin\u2013spin coupling constants. Progress in Nuclear Magnetic Resonance Spectroscopy , 53(4):249\u2013268, 2008. doi:10.1016/j.pnmrs.2008.02.002 . \u21a9 Si\u00e2n A. Joyce, Jonathan R. Yates, Chris J. Pickard, and Francesco Mauri. A first principles theory of nuclear magnetic resonance J-coupling in solid-state systems. The Journal of Chemical Physics , 127(20):204107, 11 2007. doi:10.1063/1.2801984 . \u21a9 P. Blaha, K. Schwarz, P. Sorantin, and S.B. Trickey. Full-potential, linearized augmented plane wave programs for crystalline systems. Computer Physics Communications , 59(2):399\u2013415, 1990. doi:10.1016/0010-4655(90)90187-6 . \u21a9 P. Blaha, P. Sorantin, C. Ambrosch, and K. Schwarz. Calculation of the electric field gradient tensor from energy band structures. Hyperfine Interactions , 51(1):917\u2013923, Jun 1989. doi:10.1007/BF02407802 . \u21a9 Mickael Profeta, Francesco Mauri, and Chris J. Pickard. Accurate first principles prediction of 17O NMR parameters in SiO2: assignment of the zeolite ferrierite spectrum. Journal of the American Chemical Society , 125(2):541\u2013548, 2003. PMID: 12517169. doi:10.1021/ja027124r . \u21a9","title":"EFG"},{"location":"documentation/Output_Files/output_files/","text":"CASTEP writes output data in a variety of files. Some of these will be in human readable ASCII format (i.e. plaintext) and can be read with commands such as less or more on linux, or with a simple text editor (textedit, notepad etc). Other files will be in binary format and are designed to be read or processed with an external program. See Tools for software and libraries to read and analyse them. Groundstate .castep ASCII. CASTEP's main outputfile. .bib ASCII. Bibtex file containing citations to the methods CASTEP has used in the calculation. .check Binary. This checkpoint file contains the results of the calculation including the groundstate charge density and wavefunctions. It is typically a very large file. Will be read by CASTEP when performing a continuation calculation. Also read by postprocessing software such as c2x or euphonic. .check_bak Binary. backup of the checkpoint file. .castep_bin Binary. This file is identical to .check except that does not contain the wavefunctions. Therefore it is usually much smaller than the .check file, making it suitable for archiving a calculation. It may also be processed by euphonic, c2x or other software which can read checkpoint file. .cst_esp Binary. The local part of the Kohn-Sham potential (Vloc + Hartree + XC). .usp ASCII. Pseudoptential data, written for each species. See the page on reading usp headers . .uspso ASCII. Pseudoptential data, written for each species. This is the J-dependant version of the .usp . See the page on reading usp headers . .beta Xmgrace (.agr) format. Beta projectors for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .pwave Xmgrace (.agr) format. Pseudo-wavefunctions for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .econv Xmgrace (.agr) format. Isolated atom energy cutoff convergence for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .bands ASCII. Kohn-Sham eigenvalues at the requested k-points. Can be used to plot band structures or density of states. Note that the eigenvalues are given in atomic units (Hartree). .den_fmt ASCII. Charge density. Only written if write_formatted_density : T . .pot_fmt ASCII. Groundstate local potential (Vloc + Hartree + XC) (See .cst_esp ). Only written if write_formatted_potential : T . .chdiff Binary. Difference between the groundstate charge density and a superposition of atomic densities. Only written if calculate_densdiff : T .chdiff_fmt ASCII. same data as .chdiff in human readable format. Only written if calculate_densdiff : T and write_formatted_density : T . .xrd_sf ASCII. X-ray structure factors. See the documentation page . .elf Binary. Result of ELF calculation. .elf_fmt ASCII. Result of ELF calculation.Only written if write_formatted_elf : T . Geometry Optimisation *.geom ASCII. State of the system (coordinates, unit cell etc) at each step of the geometry optimisation. See for specification. Can be used to animate the geometry optimisation and can be read directly by Jmol. Molecular Dynamics *.md ASCII. State of the system (coordinates, unit cell etc) at each step of the molecular dynamics simulation. Same format as the .geom file. See for specification. Can be used to animate the trajectory, and can be read directly by Jmol. *.hug ASCII. Hugoniot data for hugoniostat MD. Spectral .pdos_bin Binary. Matrix elements used for plotting a projected density of states. Used by Optados. .ome_bin Binary. Matrix elements used for calculating optical properties. Used by Optados. .dome_bin Binary. Diagonal elements of the optical matrix elements. Used by Optados to plot densities of states / spectral properties using adaptive smearing. .elnes_bin Binary. Matrix elements used for plotting the core-loss spectrum. Used by Optados. .orbitals Binary. Kohn-Sham states at each kpoints. Used by orbital2bands to make a reorganised .bands file for a cleaner looking bandstructure. Phonon and Efield .phonon ASCII. Phonon eigenvalues and eigenvectors. .phonon_dos ASCII. Phonon branch gradients and density-of-states when param keyword phonon_calculate_dos is true. .efield ASCII. Mode oscillator strengths and frequency-dependent permittivity tensor in the ir band. Electron-Phonon coupling .epme ASCII. Electron-phonon matrix elements. .epme_bin Binary. Electron-phonon matrix elements. Elastic Constants .elastic ASCII. Elastic constants, compliance matrix, Frozen ion constants, Internal Strain and Piezoelectric tensors TDDFT .tddft ASCII. TDDFT state band projection analysis and TDDFT excitation energies. Magres .magres ASCII. Contain the NMR tensors (depending on magres_task shielding, EFG or J). Read by MagresView or the Soprano python libraries. _current.dat ASCII. Written if MAGRES_WRITE_RESPONSE=True . Used to compute NICS (nucleus independent chemical shifts) see https://www.ccpnc.ac.uk/docs/nics . Transition state search .ts ASCII. See the specification in the documentation pages .","title":"Output Files"},{"location":"documentation/Output_Files/output_files/#groundstate","text":".castep ASCII. CASTEP's main outputfile. .bib ASCII. Bibtex file containing citations to the methods CASTEP has used in the calculation. .check Binary. This checkpoint file contains the results of the calculation including the groundstate charge density and wavefunctions. It is typically a very large file. Will be read by CASTEP when performing a continuation calculation. Also read by postprocessing software such as c2x or euphonic. .check_bak Binary. backup of the checkpoint file. .castep_bin Binary. This file is identical to .check except that does not contain the wavefunctions. Therefore it is usually much smaller than the .check file, making it suitable for archiving a calculation. It may also be processed by euphonic, c2x or other software which can read checkpoint file. .cst_esp Binary. The local part of the Kohn-Sham potential (Vloc + Hartree + XC). .usp ASCII. Pseudoptential data, written for each species. See the page on reading usp headers . .uspso ASCII. Pseudoptential data, written for each species. This is the J-dependant version of the .usp . See the page on reading usp headers . .beta Xmgrace (.agr) format. Beta projectors for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .pwave Xmgrace (.agr) format. Pseudo-wavefunctions for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .econv Xmgrace (.agr) format. Isolated atom energy cutoff convergence for each generated pseudopotential. Only written if a test configuration [] is present in the OTF string. .bands ASCII. Kohn-Sham eigenvalues at the requested k-points. Can be used to plot band structures or density of states. Note that the eigenvalues are given in atomic units (Hartree). .den_fmt ASCII. Charge density. Only written if write_formatted_density : T . .pot_fmt ASCII. Groundstate local potential (Vloc + Hartree + XC) (See .cst_esp ). Only written if write_formatted_potential : T . .chdiff Binary. Difference between the groundstate charge density and a superposition of atomic densities. Only written if calculate_densdiff : T .chdiff_fmt ASCII. same data as .chdiff in human readable format. Only written if calculate_densdiff : T and write_formatted_density : T . .xrd_sf ASCII. X-ray structure factors. See the documentation page . .elf Binary. Result of ELF calculation. .elf_fmt ASCII. Result of ELF calculation.Only written if write_formatted_elf : T .","title":"Groundstate"},{"location":"documentation/Output_Files/output_files/#geometry-optimisation","text":"*.geom ASCII. State of the system (coordinates, unit cell etc) at each step of the geometry optimisation. See for specification. Can be used to animate the geometry optimisation and can be read directly by Jmol.","title":"Geometry Optimisation"},{"location":"documentation/Output_Files/output_files/#molecular-dynamics","text":"*.md ASCII. State of the system (coordinates, unit cell etc) at each step of the molecular dynamics simulation. Same format as the .geom file. See for specification. Can be used to animate the trajectory, and can be read directly by Jmol. *.hug ASCII. Hugoniot data for hugoniostat MD.","title":"Molecular Dynamics"},{"location":"documentation/Output_Files/output_files/#spectral","text":".pdos_bin Binary. Matrix elements used for plotting a projected density of states. Used by Optados. .ome_bin Binary. Matrix elements used for calculating optical properties. Used by Optados. .dome_bin Binary. Diagonal elements of the optical matrix elements. Used by Optados to plot densities of states / spectral properties using adaptive smearing. .elnes_bin Binary. Matrix elements used for plotting the core-loss spectrum. Used by Optados. .orbitals Binary. Kohn-Sham states at each kpoints. Used by orbital2bands to make a reorganised .bands file for a cleaner looking bandstructure.","title":"Spectral"},{"location":"documentation/Output_Files/output_files/#phonon-and-efield","text":".phonon ASCII. Phonon eigenvalues and eigenvectors. .phonon_dos ASCII. Phonon branch gradients and density-of-states when param keyword phonon_calculate_dos is true. .efield ASCII. Mode oscillator strengths and frequency-dependent permittivity tensor in the ir band.","title":"Phonon and Efield"},{"location":"documentation/Output_Files/output_files/#electron-phonon-coupling","text":".epme ASCII. Electron-phonon matrix elements. .epme_bin Binary. Electron-phonon matrix elements.","title":"Electron-Phonon coupling"},{"location":"documentation/Output_Files/output_files/#elastic-constants","text":".elastic ASCII. Elastic constants, compliance matrix, Frozen ion constants, Internal Strain and Piezoelectric tensors","title":"Elastic Constants"},{"location":"documentation/Output_Files/output_files/#tddft","text":".tddft ASCII. TDDFT state band projection analysis and TDDFT excitation energies.","title":"TDDFT"},{"location":"documentation/Output_Files/output_files/#magres","text":".magres ASCII. Contain the NMR tensors (depending on magres_task shielding, EFG or J). Read by MagresView or the Soprano python libraries. _current.dat ASCII. Written if MAGRES_WRITE_RESPONSE=True . Used to compute NICS (nucleus independent chemical shifts) see https://www.ccpnc.ac.uk/docs/nics .","title":"Magres"},{"location":"documentation/Output_Files/output_files/#transition-state-search","text":".ts ASCII. See the specification in the documentation pages .","title":"Transition state search"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/","text":"Molecular vibrational calculations CASTEP is primarily a solid state code with periodic boundary conditions, and is not necessarily the first choice for performing vibrational spectroscopy calculations on molecules. Nevertheless it can sometimes be convenient to use it in this mode (for example, if it is desired to compare a molecular crystal with an isolated molecule at exactly the same level of theory). With certain limitations this can be done in CASTEP using the \u201cmolecule in large box\u201d method. The idea is to place the molecule in a vacuum by constructing a large supercell. If the supercell is sufficiently large that the periodic images of the molecule do not interact then the frequencies and eigenvectors in the molecular limit can be recovered. Because the zero charge density in a large volume must still be represented using a plane-wave basis sat, such calculations can become expensive, but it is nevertheless essential to perform careful cell size convergence tests. A molecule in free space possesses rotational as well as translational symmetry, which results in three (or two for a linear molecule) free librational modes of zero frequency. A periodic CASTEP calculation does not possess this symmetry and the librational mode frequencies will have nonzero values, either real and positive or imaginary. If a molecular electric field calculation is desired the parameter efield_ignore_molec_modes may be specified with the keyword value of MOLECULE or LINEAR_MOLECULE . This omits the 6 (or 5) lowest modes from the infra-red polarizability calculation, assuming them to be the librations. As with crystalline systems it is desirable to maximise the use of symmetry by optimally orienting the molecule. In this case an additional criterion applies - the simulation cell vectors should be organised for maximal compatibility with the molecular symmetry. Any incompatible symmetry operations will not be found if using the SYMMETRY_GENERATE keyword. For example a tetrahedral molecule is best modelled in a cubic cell with the 3-fold axes oriented along the cube diagonals. By contrast a hexagonal molecule such as benzene is better modelled using a hexagonal simulation cell with the molecule commensurately oriented. A limitation of this method is that CASTEP implements only the crystallographic point group symmetry operations, and does not include all of the molecular point groups. It is not always possible to take full advantage of molecular symmetry, and 5-fold rotation axes and icosahedral groups can not be represented. In such cases some degeneracies will be lifted and only approximately satisfied, and the group theoretical analysis of the eigenvectors will not be correct for the molecular point group. Finally, it is sometimes desirable to compute the vibrational spectrum of an ion rather than a neutral molecule. This adds a number of complications of different degrees of severity. First is the well-known result that semi-local DFT (LDA and GGA) severely underbinds anions, and the description of the molecular states in some systems may be substantially incorrect. Second, the introduction of a non-zero molecular charge in a periodic cell necessitates the addition of a compensating charge to avoid a divergent Coulomb energy. CASTEP implicitly adds a uniform charge distribution which integrates over the cell to the negative of the sum of ionic and electronic charge in the system. This model while effective, gives rise to additional electrostatic terms which decrease only as 1/L^{3} 1/L^{3} . Consequently it is impossible to completely converge such a calculation with respect to cell size. It is beyond the scope of this document to describe the techniques which may be used to recover the \u201cinfinite\u201d volume limit. The reader is referred to ref ( Leslie and Gillan 1985 ) and the extensive literature which cites this paper for further reading. An example of a successful approach involving an extrapolation of frequencies of a molecular anion to the infinite cell limit is given in Parker et al. ( Parker et al. 2006 ). Isotopic substitution calculations A powerful technique in experimental spectroscopy is isotopic substitution where the sample is modified by the substitution of a common isotope of some element by a heavier or lighter one. This can provide valuable site-specific spectroscopic information, particularly if the substitution can be performed in a site-specific manner. Force constants and dynamical matrices do not depend on nuclear mass, and are therefore one set of computations will suffice irrespective of isotopic substitution. The phonons tool (section [phonons-tool] ) allows recomputation of the frequencies for different isotopic substitutions without recomputing dynamical matrices. The simplest case is complete substitution. The new .cell file should contain a block specifying the new mass, e.g. %block SPECIES_MASS H 2.014101778 %endblock SPECIES_MASS Running the phonon code will compute the vibrational frequencies and eigenvectors for a completely deuterated sample. Slightly more complicated is the case where only one or a few of a number of sites is to be substituted. In that case the above prescription is inadequate as it would change all of the sites containing the species in question. It is therefore necessary to use CASTEP\u2019s sub-species labelling capabilities. For example the original cell containing a methane molecule might contain %block SPECIES_POT C C_00.recpot H H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS The continuation cell for input to phonons should contain %block SPECIES_POT C C_00.recpot H H_04.recpot H:D H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H:D 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS %block SPECIES_MASS H:D 2.014101778 H 1.007825032 C 12.0107 %endblock SPECIES_MASS The new atom label may contain any alphanumeric extension following the colon up to a maximum of 8 characters. This defines a new system with one hydrogen atom of a methane molecule replaced by deuterium. Notice that this has broken the initial symmetry of the cell. The phonons program generates a new system of reduced symmetry with three distinct atom types, and copies the dynamical matrix data from the original methane system from the .check file over to the corresponding atoms in the new system. It then diagonalises the dynamical matrix, applies whatever post-processing is specified and writes the frequencies and eigenvectors as usual. This straightforward approach fails to take into account isotopic shifts in bond lengths and geometry, and is therefore an approximate one. Since isotopic shifts in bond lengths depend in turn on the vibrational frequency, within the quasiharmionic approximation a self-consistent approach under which bond lengths and frequencies are simultaneously adjusted to self-consistency would be required. This would also require new DFPT electronic calculations at each stage and is beyond the scope of this utility. Constrained lattice dynamics It is sometimes desirable to compute the vibrational frequencies of a restricted region of an ab initio model. Consider the case of a molecule adsorbed on a surface. If only the frequencies of the molecular vibrations are needed it would be desirable to compute a subset of the modes were this possible. While it is not practical (as it would require prior knowledge of the eigenvectors of the full calculation), an alternative approach is to apply constraints to certain atoms. CASTEP implements a technique known as constrained lattice dynamics , also known as the partial hessian method. Nominated atoms are assumed to be \u201cfrozen\u201d, and the corresponding entries of the dynamical matrix are set to zero. The model is effectively one whereby the atoms in the region of the system deemed \u201cirrelevant\u201d are assigned a mass of infinity. It is not necessary to perform any computations for perturbation of these atoms, and a considerable saving of computational effort may be achieved. Frozen atoms are specified a CASTEP .cell file using the same syntax as applies to geometry operations. The block %block IONIC_CONSTRAINTS 1 Si 1 1 1 1 2 Si 2 1 1 1 3 C 4 1 1 1 %endblock IONIC_CONSTRAINTS constrains silicon atoms numbered 1-2 and C atom number 4 to be fixed. These do not move during geometry optimisation, and their perturbations are not considered during a lattice dynamics calculation. In fact the constrained lattice dynamics method does not make full use of the generality of CASTEP\u2019s linear constraints block (see for example the tutorial on MD at http://www.castep.org ) but only identifies atoms which are fully constrained not to move. As in the example above, there should be a single line for each atom which creates a uniquely numbered constraint. This should contain a \u201c1\u201d in all of the x, y, z positions. Except in rather specialised geometries the presence of fixed atom constraints is incompatible with most symmetry operations, and therefore symmetry should usually be turned off during a constrained lattice dynamics calculation. There is also an incompatibility with the acoustic sum rule (section [asr] ) as constraining the atoms breaks the translational invariance of the Hamiltonian. Acoustic sum rule correction is therefore disabled automatically if constraints are present.","title":"Advanced-Topics"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#sec:molecules","text":"CASTEP is primarily a solid state code with periodic boundary conditions, and is not necessarily the first choice for performing vibrational spectroscopy calculations on molecules. Nevertheless it can sometimes be convenient to use it in this mode (for example, if it is desired to compare a molecular crystal with an isolated molecule at exactly the same level of theory). With certain limitations this can be done in CASTEP using the \u201cmolecule in large box\u201d method. The idea is to place the molecule in a vacuum by constructing a large supercell. If the supercell is sufficiently large that the periodic images of the molecule do not interact then the frequencies and eigenvectors in the molecular limit can be recovered. Because the zero charge density in a large volume must still be represented using a plane-wave basis sat, such calculations can become expensive, but it is nevertheless essential to perform careful cell size convergence tests. A molecule in free space possesses rotational as well as translational symmetry, which results in three (or two for a linear molecule) free librational modes of zero frequency. A periodic CASTEP calculation does not possess this symmetry and the librational mode frequencies will have nonzero values, either real and positive or imaginary. If a molecular electric field calculation is desired the parameter efield_ignore_molec_modes may be specified with the keyword value of MOLECULE or LINEAR_MOLECULE . This omits the 6 (or 5) lowest modes from the infra-red polarizability calculation, assuming them to be the librations. As with crystalline systems it is desirable to maximise the use of symmetry by optimally orienting the molecule. In this case an additional criterion applies - the simulation cell vectors should be organised for maximal compatibility with the molecular symmetry. Any incompatible symmetry operations will not be found if using the SYMMETRY_GENERATE keyword. For example a tetrahedral molecule is best modelled in a cubic cell with the 3-fold axes oriented along the cube diagonals. By contrast a hexagonal molecule such as benzene is better modelled using a hexagonal simulation cell with the molecule commensurately oriented. A limitation of this method is that CASTEP implements only the crystallographic point group symmetry operations, and does not include all of the molecular point groups. It is not always possible to take full advantage of molecular symmetry, and 5-fold rotation axes and icosahedral groups can not be represented. In such cases some degeneracies will be lifted and only approximately satisfied, and the group theoretical analysis of the eigenvectors will not be correct for the molecular point group. Finally, it is sometimes desirable to compute the vibrational spectrum of an ion rather than a neutral molecule. This adds a number of complications of different degrees of severity. First is the well-known result that semi-local DFT (LDA and GGA) severely underbinds anions, and the description of the molecular states in some systems may be substantially incorrect. Second, the introduction of a non-zero molecular charge in a periodic cell necessitates the addition of a compensating charge to avoid a divergent Coulomb energy. CASTEP implicitly adds a uniform charge distribution which integrates over the cell to the negative of the sum of ionic and electronic charge in the system. This model while effective, gives rise to additional electrostatic terms which decrease only as 1/L^{3} 1/L^{3} . Consequently it is impossible to completely converge such a calculation with respect to cell size. It is beyond the scope of this document to describe the techniques which may be used to recover the \u201cinfinite\u201d volume limit. The reader is referred to ref ( Leslie and Gillan 1985 ) and the extensive literature which cites this paper for further reading. An example of a successful approach involving an extrapolation of frequencies of a molecular anion to the infinite cell limit is given in Parker et al. ( Parker et al. 2006 ).","title":"Molecular vibrational calculations"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#sec:isotopes","text":"A powerful technique in experimental spectroscopy is isotopic substitution where the sample is modified by the substitution of a common isotope of some element by a heavier or lighter one. This can provide valuable site-specific spectroscopic information, particularly if the substitution can be performed in a site-specific manner. Force constants and dynamical matrices do not depend on nuclear mass, and are therefore one set of computations will suffice irrespective of isotopic substitution. The phonons tool (section [phonons-tool] ) allows recomputation of the frequencies for different isotopic substitutions without recomputing dynamical matrices. The simplest case is complete substitution. The new .cell file should contain a block specifying the new mass, e.g. %block SPECIES_MASS H 2.014101778 %endblock SPECIES_MASS Running the phonon code will compute the vibrational frequencies and eigenvectors for a completely deuterated sample. Slightly more complicated is the case where only one or a few of a number of sites is to be substituted. In that case the above prescription is inadequate as it would change all of the sites containing the species in question. It is therefore necessary to use CASTEP\u2019s sub-species labelling capabilities. For example the original cell containing a methane molecule might contain %block SPECIES_POT C C_00.recpot H H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS The continuation cell for input to phonons should contain %block SPECIES_POT C C_00.recpot H H_04.recpot H:D H_04.recpot %endblock SPECIES_POT %block POSITIONS_ABS C 0.0 0.0 0.0 H:D 0.0 0.0 1.09 H 0.9316592 0.0 -0.36333333 H -0.4658296 0.8068405 -0.36333333 H -0.4658296 -0.8068405 -0.36333333 %endblock POSITIONS_ABS %block SPECIES_MASS H:D 2.014101778 H 1.007825032 C 12.0107 %endblock SPECIES_MASS The new atom label may contain any alphanumeric extension following the colon up to a maximum of 8 characters. This defines a new system with one hydrogen atom of a methane molecule replaced by deuterium. Notice that this has broken the initial symmetry of the cell. The phonons program generates a new system of reduced symmetry with three distinct atom types, and copies the dynamical matrix data from the original methane system from the .check file over to the corresponding atoms in the new system. It then diagonalises the dynamical matrix, applies whatever post-processing is specified and writes the frequencies and eigenvectors as usual. This straightforward approach fails to take into account isotopic shifts in bond lengths and geometry, and is therefore an approximate one. Since isotopic shifts in bond lengths depend in turn on the vibrational frequency, within the quasiharmionic approximation a self-consistent approach under which bond lengths and frequencies are simultaneously adjusted to self-consistency would be required. This would also require new DFPT electronic calculations at each stage and is beyond the scope of this utility.","title":"Isotopic substitution calculations"},{"location":"documentation/Phonons/Castep_Phonons/Advanced-Topics/#constrained-lattice-dynamics","text":"It is sometimes desirable to compute the vibrational frequencies of a restricted region of an ab initio model. Consider the case of a molecule adsorbed on a surface. If only the frequencies of the molecular vibrations are needed it would be desirable to compute a subset of the modes were this possible. While it is not practical (as it would require prior knowledge of the eigenvectors of the full calculation), an alternative approach is to apply constraints to certain atoms. CASTEP implements a technique known as constrained lattice dynamics , also known as the partial hessian method. Nominated atoms are assumed to be \u201cfrozen\u201d, and the corresponding entries of the dynamical matrix are set to zero. The model is effectively one whereby the atoms in the region of the system deemed \u201cirrelevant\u201d are assigned a mass of infinity. It is not necessary to perform any computations for perturbation of these atoms, and a considerable saving of computational effort may be achieved. Frozen atoms are specified a CASTEP .cell file using the same syntax as applies to geometry operations. The block %block IONIC_CONSTRAINTS 1 Si 1 1 1 1 2 Si 2 1 1 1 3 C 4 1 1 1 %endblock IONIC_CONSTRAINTS constrains silicon atoms numbered 1-2 and C atom number 4 to be fixed. These do not move during geometry optimisation, and their perturbations are not considered during a lattice dynamics calculation. In fact the constrained lattice dynamics method does not make full use of the generality of CASTEP\u2019s linear constraints block (see for example the tutorial on MD at http://www.castep.org ) but only identifies atoms which are fully constrained not to move. As in the example above, there should be a single line for each atom which creates a uniquely numbered constraint. This should contain a \u201c1\u201d in all of the x, y, z positions. Except in rather specialised geometries the presence of fixed atom constraints is incompatible with most symmetry operations, and therefore symmetry should usually be turned off during a constrained lattice dynamics calculation. There is also an incompatibility with the acoustic sum rule (section [asr] ) as constraining the atoms breaks the translational invariance of the Hamiltonian. Acoustic sum rule correction is therefore disabled automatically if constraints are present.","title":"Constrained lattice dynamics"},{"location":"documentation/Phonons/Castep_Phonons/Bibliography/","text":"Ackland, G J, M C Warren, and S J Clark. 1997. \u201cPractical Methods in Ab Initio Lattice Dynamics.\u201d Journal of Physics: Condensed Matter 9 (37): 7861\u201372. http://stacks.iop.org/0953-8984/9/7861 . Balan, E., A. M. Saitta, F. Mauri, and G. Calas. 2001. \u201cFirst-Principles Modeling of the Infra-Red Spectrum of Kaolinite.\u201d American Mineralogist 86: 1321\u201330. https://doi.org/10.2138/am-2001-11-1201 . Baroni, Stefano, Stefano de Gironcoli, Andrea Dal Corso, and Paolo Giannozzi. 2001. \u201cPhonons and Related Crystal Properties from Density-Functional Perturbation Theory.\u201d Reviews of Modern Physics 73 (2): 515\u201362. https://doi.org/10.1103/RevModPhys.73.515 . Boyd, Robert W. 2003. Nonlinear Optics . San Diego, Calif.: Academic Press. http://www.myilibrary.com?id=105034 . Cheng, Y. Q., and A. J. Ramirez-Cuesta. 2020. \u201cCalculation of the Thermal Neutron Scattering Cross-Section of Solids Using OCLIMAX.\u201d J. Chem. Theory Comput. 16 (8): 5212\u201317. https://doi.org/10.1021/acs.jctc.0c00569 . Dove, Martin T. 1993. Introduction to Lattice Dynamics . Cambridge Topics in Mineral Physics and Chemistry. Cambridge University Press. https://doi.org/10.1017/CBO9780511619885 . Fair, R., A. Jackson, D. Voneshen, D. Jochym, D. Le, K. Refson, and T. Perring. 2022. \u201cEuphonic: Inelastic Neutron Scattering Simulations from Force Constants and Visualization Tools for Phonon Properties.\u201d J Appl Cryst 55 (6): 1689\u20131703. https://doi.org/10.1107/S1600576722009256 . Giannozzi, Paolo, Stefano de Gironcoli, Pasquale Pavone, and Stefano Baroni. 1991. \u201cAb Initio Calculation of Phonon Dispersions in Semiconductors.\u201d Phys. Rev. B 43 (9): 7231\u201342. https://doi.org/10.1103/PhysRevB.43.7231 . Gonze, Xavier. 1997. \u201cFirst-Principles Responses of Solids to Atomic Displacements and Homogeneous Electric Fields: Implementation of a Conjugate-Gradient Algorithm.\u201d Physical Review B 55 (16): 10377\u201354. https://doi.org/10.1103/PhysRevB.55.10337 . Gonze, Xavier, and Changyol Lee. 1997. \u201cDynamical Matrices, Born Effective Charges, Dielectric Permittivity Tensors, and Interatomic Force Constants from Density-Functional Perturbation Theory.\u201d Physical Review B 55 (16): 10355\u201368. https://doi.org/10.1103/PhysRevB.55.10355 . Kendrick, John, and Andrew D. Burnett. 2016. \u201cPDielec: The Calculation of Infrared and Terahertz Absorption for Powdered Crystals.\u201d Journal of Computational Chemistry 37 (16): 1491\u20131504. https://doi.org/10.1002/jcc.24344 . Kunc, K., and Richard M. Martin. 1982. \u201cAb Initio Force Constants of GaAs: A New Approach to Calculation of Phonons and Dielectric Properties.\u201d Phys. Rev. Lett. 48 (6): 406\u20139. https://doi.org/10.1103/PhysRevLett.48.406 . Leslie, M., and M. J. Gillan. 1985. \u201cThe Energy and Elastic Dipole Tensor of Defects in Ionic Crystals Calculated by the Supercell Method.\u201d Journal of Physics: Condensed Matter 18: 973\u201382. https://doi.org/10.1088/0022-3719/18/5/005 . Levine, Zachary H., and Douglas C. Allan. 1989. \u201cLinear Optical Response in Silicon and Germanium Including Self-Energy Effects.\u201d Phys. Rev. Lett. 63 (16): 1719\u201322. https://doi.org/10.1103/PhysRevLett.63.1719 . Lloyd-Williams, Jonathan H., and Bartomeu Monserrat. 2015. \u201cLattice Dynamics and Electron-Phonon Coupling Calculations Using Nondiagonal Supercells.\u201d Physical Review B 92 (18): 184301. https://doi.org/10.1103/PhysRevB.92.184301 . Maradudin, A. A., and G. K. Horton, eds. 1980. Dynamical Properties of Solids . Vol. 1\u20137. Elsevier. https://www.sciencedirect.com/bookseries/dynamical- properties-of-solids . Miwa, Kazutoshi. 2011. \u201cPrediction of Raman Spectra with Ultrasoft Pseudopotentials.\u201d Physical Review B 84 (9): 094304. https://doi.org/10.1103/PhysRevB.84.094304 . Pallikara, Ioanna, Prakriti Kayastha, Jonathan M Skelton, and Lucy D Whalley. 2022. \u201cThe Physical Significance of Imaginary Phonon Modes in Crystals.\u201d Electronic Structure 4 (3): 033002. https://doi.org/10.1088/2516-1075/ac78b3 . Parker, S. F., K. Refson, K. P. J. Williams, D. A. Braden, B. S. Hudson, and K. Yvon. 2006. \u201cSpectroscopic and Ab Initio Characterization of the ReH9(2-) Ion.\u201d Inorg. Chem. 45 (26): 10951\u201357. https://doi.org/10.1021/ic0611894 . Parlinski, K., Z. Q. Li, and Y. Kawazoe. 1997. \u201cFirst-Principles Determination of the Soft Mode in Cubic ZrO2 ZrO2 .\u201d Phys. Rev. Lett. 78 (21): 4063\u201366. https://doi.org/10.1103/PhysRevLett.78.4063 . Pick, R. M. Robert M. R. M. Robert M., Morrel H. Cohen, and Richard M. Martin. 1970. \u201cMicroscopic Theory of Force Constants in the Adiabatic Approximation.\u201d Physical Review B 1 (2): 910\u201320. https://doi.org/10.1103/PhysRevB.1.910 . Pickard, Chris J. 1997. \u201cAb Initio Electron Energy Loss Spectroscopy.\u201d PhD Thesis, University of Cambridge. https://www.tcm.phy.cam.ac.uk/~cjp20/old/thesis.ps.gz . Porezag, Dirk, and Mark R. Pederson. 1996. \u201cInfrared Intensities and Raman-Scattering Activities Within Density-Functional Theory.\u201d Phys. Rev. B 54 (11): 7830\u201336. https://doi.org/10.1103/PhysRevB.54.7830 . Probert, M. I. J., and M. C. Payne. 2003. \u201cImproving the Convergence of Defect Calculations in Supercells: An Ab Initio Study of the Neutral Silicon Vacancy.\u201d Phys. Rev. B 67 (7): 075204. https://doi.org/10.1103/PhysRevB.67.075204 . Ramirez-Cuesta, A. J. 2004. \u201caCLIMAX 4.0.1, the New Version of the Software for Analyzing and Interpreting INS Spectra.\u201d Computer Physics Communications 157 (3): 226\u201338. https://doi.org/10.1016/S0010-4655(03)00520-4 . Refson, Keith, P. R. Tulip, and Stewart J. Clark. 2006. \u201cVariational Density-Functional Perturbation Theory for Dielectrics and Lattice Dynamics.\u201d Physical Review B 73 (15): 155114. https://doi.org/10.1103/PhysRevB.73.155114 . Srivastava, G. P. 2023. The Physics of Phonons (2 nd Edition) . Taylor; Francis. https://doi.org/10.1201/9781003141273 . Yates, Jonathan R, Xinjie Wang, David Vanderbilt, and Ivo Souza. 2007. \u201cSpectral and Fermi Surface Properties from Wannier Interpolation.\u201d Physical Review B 75 (19): 195121. https://doi.org/10.1103/PhysRevB.75.195121 . Ye, Lin-Hui, Bang-Gui Liu, Ding-Sheng Wang, and Rushan Han. 2004. \u201cAb Initio Phonon Dispersions of Single-Wall Carbon Nanotubes.\u201d Phys. Rev. B 69 (23): 235409. https://doi.org/10.1103/PhysRevB.69.235409 .","title":"Bibliography"},{"location":"documentation/Phonons/Castep_Phonons/Dielectric-properties/","text":"Density functional perturbation theory is not limited to atomic displacement perturbations, and may also be used to calculate other response properties with respect to an electric field perturbation of an insulating system 1 . These are the dielectric permittivity \\epsilon_{\\alpha,\\beta}^{\\infty} = \\delta_{\\alpha,\\beta} - \\frac{4 \\pi}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, \\epsilon_{\\alpha,\\beta}^{\\infty} = \\delta_{\\alpha,\\beta} - \\frac{4 \\pi}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, the \u201cmolecular\u201d polarizability \\alpha_{\\alpha,\\beta}^{\\infty} = - \\frac{1}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, \\alpha_{\\alpha,\\beta}^{\\infty} = - \\frac{1}{\\Omega}\\frac{\\partial^2 E}{\\partial \\varepsilon_{\\alpha} \\partial \\varepsilon_{\\beta}} \\;, and the Born effective charges Z^{*}_{\\alpha,\\beta} = \\Omega \\frac{\\partial P_{\\beta}}{\\partial u_{\\kappa,\\alpha}} = \\frac{\\partial F_{\\kappa,\\alpha}}{\\partial \\varepsilon_{\\beta}} = \\frac{\\partial^2 E}{\\partial u_{\\kappa,\\alpha}\\partial \\varepsilon_{\\beta}} Z^{*}_{\\alpha,\\beta} = \\Omega \\frac{\\partial P_{\\beta}}{\\partial u_{\\kappa,\\alpha}} = \\frac{\\partial F_{\\kappa,\\alpha}}{\\partial \\varepsilon_{\\beta}} = \\frac{\\partial^2 E}{\\partial u_{\\kappa,\\alpha}\\partial \\varepsilon_{\\beta}} which play a strong role in lattice dynamics of crystals, and in particular governs the frequency-dependent dielectric response in the infra-red region ( Gonze and Lee 1997 ). An electric field response calculation is selected using the task keyword in the .param file. task : EFIELD which computes the optical frequency dielectric permittivity tensor and the low frequency (ionic lattice) response to a time-varying field in the regime of the phonon modes and the Born charges. Alternatively task : PHONON+EFIELD performs both dielectric and phonon tasks. The low and near-infrared frequency contributions to the permittivity and polarizability and the Born effective charges are printed to the .castep output file. An extract for the same Wurtzite BN calculation as earlier is shown in figure [efield-out] . An additional output file seedname .efield is also written and contains the frequency-dependent permittivity over the entire range, with a spacing determined by parameter efield_freq_spacing , and a Lorentzian broadening governed by a fixed Q Q , efield_oscillator_q . The low-frequency contribution of the phonons to the dielectric polarizability and permittivity is only well-defined when all mode frequencies are real and positive. In the presence of any imaginary mode or one of zero frequency the low-frequency dielectric and polarizability tensors are not calculated and are reported as \u201cinfinity\u201d. By default the three lowest frequency modes are assumed to be acoustic modes and not included in the calculation. To support molecule-in-supercell calculations, the parameter efield_ignore_molec_modes may be set to molecule , which excludes the 6 lowest frequency modes from the dielectric calculation. Allowed values are CRYSTAL , MOLECULE and LINEAR_MOLECULE which ignore 3, 6 and 5 modes respectively. In fact CASTEP usually performs an electric field response calculation even for a task : PHONON calculation because the permittivity tensor and Born charges are required to calculate the LO/TO splitting terms. Conversely a pure task : EFIELD calculation also performs a \\Gamma \\Gamma -point phonon calculation which is needed to compute the ionic contribution to the permittivity and polarizability. Consequently the only real difference between any of the tasks PHONON , EFIELD and PHONON+EFIELD lies in what is printed to the output file as the same computations are performed in each case. Only if one or other of those properties is specifically turned off with one of the parameters phonon_calc_lo_to_splitting : FALSE efield_calc_ion_permittivity : FALSE is a \u201cpure\u201d phonon or E-field calculation ever performed. It is well documented that the LDA tends to overestimate dielectric permittivities - by over 10% in the case of Si or Ge ( Levine and Allan 1989 ). It is possible to include an ad-hoc correction term to model the missing self-energy, by applying the so-called \u201cscissors operator\u201d, which consists of a rigid upshift of all conduction band states. This was incorporated into DFPT electric field response calculations by Gonze and Lee ( Gonze and Lee 1997 ). The parameters keyword excited_state_scissors 1.0 eV is used to model the effect of a 1 eV (in this example) upshift of conduction band states and will include the effects on dielectric permittivity and Born charges (but not phonons). The value to use must be determined from high-level calculations or empirically. =============================================================================== Optical Permittivity (f->infinity) DC Permittivity (f=0) ---------------------------------- --------------------- 4.50788 0.00000 0.00000 6.64363 0.00000 0.00000 0.00000 4.50788 0.00000 0.00000 6.64363 0.00000 0.00000 0.00000 4.63846 0.00000 0.00000 7.15660 =============================================================================== =============================================================================== Polarisabilities (A**3) Optical (f->infinity) Static (f=0) --------------------- ------------- 6.52844 0.00000 0.00000 10.50324 0.00000 0.00000 0.00000 6.52844 0.00000 0.00000 10.50324 0.00000 0.00000 0.00000 6.77146 0.00000 0.00000 11.45793 =============================================================================== =================================================== Born Effective Charges ---------------------- B 1 1.84636 0.00000 0.00000 0.00000 1.84636 0.00000 0.00000 0.00000 1.94523 B 2 1.84636 0.00000 0.00000 0.00000 1.84636 0.00000 0.00000 0.00000 1.94523 N 1 -1.85371 0.00000 0.00000 0.00000 -1.85371 0.00000 0.00000 0.00000 -1.94009 N 2 -1.85371 0.00000 0.00000 0.00000 -1.85371 0.00000 0.00000 0.00000 -1.94009 =================================================== Figure 6 Extract from the .castep output file generated from the hexagonal BN run of figure [example-gamma] , with task : EFIELD . The Born effective charges are laid out with the columns representing the X,Y,Z electric field directions and the rows the X,Y,Z displacement directions. Non-linear optical susceptibility In addition to the linear response properties calculated with task EFIELD or phonon+efield the non-linear dielectric susceptibility may be computed if the parameter efield_calculate_nonlinear : CHI2 is set. The calculation uses the \u201c2n+1 theorem\u201d extension of DFPT ( Baroni et al. 2001 ; Miwa 2011 ) to compute the static response, \\chi^{(2)} \\chi^{(2)} . The results are reported in the .castep file in reduced tensor form as the \u201cd-matrix\u201d ( Boyd 2003 ). See figure [nlo] . This is not activated by default, because it is substantially more expensive than a baseline E-field linear response calculation. (It requires the calculation of three sets of response functions with a full k-point set in P1 symmetry, even for crystals with higher, even cubic symmetry.) =========================================================================== Nonlinear Optical Susceptibility (pm/V) --------------------------------------- 1.13621 -1.13625 0.00001 0.00002 -7.73417 0.00002 0.00002 -0.00003 -0.00008 -7.73421 0.00002 -1.13625 -7.73417 -7.73421 -30.12197 -0.00008 0.00001 0.00002 =========================================================================== Figure 7 Nonlinear optical susceptibility \\chi^{(2)} \\chi^{(2)} expressed as a d-matrix for LiNbO3. Because the response of a metallic system to an applied field is the generation of a current flow, the dielectric permittivity diverges and the Born charges become zero. CASTEP will check that the system has a band gap before proceeding with an E-field response calculation and abort if there is none. \u21a9","title":"Dielectric-properties"},{"location":"documentation/Phonons/Castep_Phonons/Dielectric-properties/#sec:nlo","text":"In addition to the linear response properties calculated with task EFIELD or phonon+efield the non-linear dielectric susceptibility may be computed if the parameter efield_calculate_nonlinear : CHI2 is set. The calculation uses the \u201c2n+1 theorem\u201d extension of DFPT ( Baroni et al. 2001 ; Miwa 2011 ) to compute the static response, \\chi^{(2)} \\chi^{(2)} . The results are reported in the .castep file in reduced tensor form as the \u201cd-matrix\u201d ( Boyd 2003 ). See figure [nlo] . This is not activated by default, because it is substantially more expensive than a baseline E-field linear response calculation. (It requires the calculation of three sets of response functions with a full k-point set in P1 symmetry, even for crystals with higher, even cubic symmetry.) =========================================================================== Nonlinear Optical Susceptibility (pm/V) --------------------------------------- 1.13621 -1.13625 0.00001 0.00002 -7.73417 0.00002 0.00002 -0.00003 -0.00008 -7.73421 0.00002 -1.13625 -7.73417 -7.73421 -30.12197 -0.00008 0.00001 0.00002 =========================================================================== Figure 7 Nonlinear optical susceptibility \\chi^{(2)} \\chi^{(2)} expressed as a d-matrix for LiNbO3. Because the response of a metallic system to an applied field is the generation of a current flow, the dielectric permittivity diverges and the Born charges become zero. CASTEP will check that the system has a band gap before proceeding with an E-field response calculation and abort if there is none. \u21a9","title":"Non-linear optical susceptibility"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/","text":"This guide introduces the concepts, keywords and techniques needed to set up and run CASTEP calculations of lattice dynamics and vibrational spectroscopy. The material covers the various lattice-dynamical and related methods implemented in CASTEP, how to set up a calculation, and presents simple examples of the major types of calculation. It is assumed that the reader is familiar with the general CASTEP input and output files and keywords to the level which may be found at https://castep-docs.github.io/castep-docs/ . It describes how to analyse the results and generate graphical output using the CASTEP tools, but does not cover the modelling of IR, Raman or inelastic neutron or X-ray spectra, which are large subjects and beyond the scope of this document. It does not describe the compilation and installation of CASTEP and its tools, nor does it describe the operational details of invoking and running CASTEP. Computational clusters, HPC computing environments and batch systems vary to a considerable degree, and the reader is referred to their cluster or computer centre documentation. It does discuss general aspects of managing and running large phonon calculations including restarts and parallelism in section [large-calculations] . There are many useful textbooks on the theory of vibrations in crystals, or lattice dynamics as the subject is usually known. A good beginner\u2019s guide is \u201cIntroduction to Lattice Dynamics\u201d by Martin Dove ( Dove 1993 ). More advanced texts are available by Srivistava ( Srivastava 2023 ), Maradudin ( Maradudin and Horton 1980 ) and many others. The following section presents only a brief summary to introduce the notation. Theory of Lattice Dynamics Consider a crystal with a unit cell containing N N atoms, labelled \\kappa \\kappa , and a a labels the primitive cells in the lattice. The crystal is initially in mechanical equilibrium, with Cartesian co-ordinates R_{{\\kappa,\\alpha}} R_{{\\kappa,\\alpha}} , ( \\alpha=1..3 \\alpha=1..3 denotes the Cartesian x x , y y or z z direction). {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} denotes the displacement of an atom from its equilibrium position. Harmonic lattice dynamics is based on a Taylor expansion of total energy about structural equilibrium co-ordinates. E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... where {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} is the vector of atomic displacements from equilibrium and {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} is the matrix of force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. At equilibrium the forces F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} are all zero so the first-order term vanishes. In the Harmonic Approximation the 3 ^{\\text{rd}} ^{\\text{rd}} and higher order terms are neglected 1 . Assume Born von Karman periodic boundary conditions and substitute a plane-wave trial solution {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) with a phonon wavevector {\\mathbf{q}} {\\mathbf{q}} and a polarization vector {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} . This yields an eigenvalue equation {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . The dynamical matrix is defined as {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} where the index a a runs over all lattice images of the primitive cell. That is, the dynamical matrix is the mass-reduced Fourier transform of the force constant matrix. The eigenvalue equation [dmat-eigen] can be solved by standard numerical methods. The eigenvalues, \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 , must be real numbers because {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} is a Hermitian matrix. The vibrational frequencies at each mode \\omega_{m,{\\mathbf{q}}} \\omega_{m,{\\mathbf{q}}} are obtained as the square roots, and consequently are either real and positive (if \\omega_{m,{\\mathbf{q}}}^2 > 0 \\omega_{m,{\\mathbf{q}}}^2 > 0 ) or pure imaginary (if \\omega_{m,{\\mathbf{q}}}^2 < 0 \\omega_{m,{\\mathbf{q}}}^2 < 0 ) The corresponding eigenvectors are the polarization vectors, and describe the pattern of atomic displacements belonging to each mode. The central question of ab-initio lattice dynamics is therefore how to determine the force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} which are the second derivatives of the total energy with respect to two atomic displacements. The first derivatives are the forces, and may be determined straightforwardly using the Hellman\u2013Feynmann Theorem as the derivative of the quantum mechanical energy with respect to an atomic displacement, \\lambda \\lambda \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} If {\\left < \\psi \\right |} {\\left < \\psi \\right |} represents the ground state of {\\hat{H}} {\\hat{H}} then the first two terms vanish because {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 . Differentiating again yields \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. Unlike equation [hellman] the terms involving the derivatives of the wavefunctions do not vanish. This means that it is necessary to somehow compute the electronic response of the system to the displacement of an atom to perform ab-initio lattice dynamics calculations. This may be accomplished either by a finite-displacement method, i.e. performing two calculations which differ by a small displacement of an atomic co-ordinate and evaluating a numerical derivative, or by using perturbation theory to evaluate the response wavefunction {\\frac{d \\psi}{d \\lambda}} {\\frac{d \\psi}{d \\lambda}} . (In Kohn-Sham DFT, as implemented in CASTEP we actually evaluate the first-order response orbitals.) Some general references on ab-initio lattice dynamics methods are chapter 3 of ref ( Srivastava 2023 ) and the review paper by Baroni et al. ( Baroni et al. 2001 ). Prerequisites Geometry Optimisation A successful phonon calculation almost always requires a preceding geometry optimisation (except for small, high symmetry system where all atoms lie on crystallographic high-symmetry positions and the forces are zero by symmetry). It is not necessary to perform a variable-cell optimisation - the lattice dynamics is well defined at any stress or pressure, and phonons in high-pressure or strained systems are frequently of scientific interest. The two most convenient ways of achieving this are to Set up the phonon run as a continuation of the geometry optimisation by setting the parameters keyword continuation : . Add the keyword write_cell_structure : TRUE to the geometry optimization run and modify the resulting -out.cell to use as the input for a new run. The importance of a high-quality structure optimisation can not be overemphasized - the energy expansion in equation [taylor] makes the explicit assumption that the system is in mechanical equilibrium and that all atomic forces are zero. This is sufficiently important that before performing a phonon calculation CASTEP will compute the residual forces to determine if the geometry is converged. If any component of the force exceeds geom_force_tol it will print an error message and abort the run. Should a run fail with this message, it may be because the geometry optimisation run did not in fact succeed, or because some parameter governing the convergence ( e.g. the cutoff energy) differs in the phonon run compared to the geometry optimisation. In that case the correct procedure would be to re-optimise the geometry using the same parameters as needed for the phonon run. Alternatively if the geometry error and size of the force residual are tolerable, then the value of geom_force_tol may be increased in the .param file of the phonon calculation which will allow the run to proceed. How accurate a geometry optimization is needed? Accumulated practical experience suggests that substantially tighter tolerances are needed to generate reasonable quality phonons than are needed for structural or energetics calculations. For many crystalline systems a geometry force convergence tolerance set using parameter geom_force_tol of 0.01 eV/\u00c5 is typically needed. For \u201csoft\u201d materials containing weak bonds such as molecular crystals or in the presence of hydrogen bonds, an even smaller value is frequently necessary. Only careful convergence testing of the geometry and resulting frequencies can determine the value to use. To achieve a high level of force convergence, it is obviously essential that the forces be evaluated to at least the same precision. This will in turn govern the choice of electronic k-point sampling, and probably require a smaller than default SCF convergence tolerance, elec_energy_tol . See section [convergence] for further discussion of geometry optimisation and convergence for phonon calculations. If a lattice dynamics calculation is performed at the configuration which minimises the energy the force constant matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is positive definite, and all of its eigenvalues are positive. Consequently the vibrational frequencies which are the square roots of the eigenvalues are real numbers. 2 If on the other hand the system is not at a minimum energy equilibrium configuration {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is not necessarily positive definite, the eigenvalues \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 may be negative. In that case the frequencies are imaginary and do not correspond to a physical vibrational mode. For convenience CASTEP prints such values using a a minus sign \u201c - - \u201d. These are sometimes loosely referred to as \u201cnegative\u201d frequencies, but bear in mind that this convention really indicates negative eigenvalues and imaginary frequencies. 3 Use of Symmetry CASTEP lattice dynamics uses symmetry to reduce the number of perturbation calculations to the irreducible set, and applies the symmetry transformations to generate the full dynamical matrix. Combined with the usual reduction in k-points in the IBZ, savings in CPU time by use of crystallographic symmetry can easily be a factor of 10 or more. It is therefore important to maximise the symmetry available to the calculation, and to either specify the symmetry operations in the .cell file using the %block SYMMETRY_OPS keyword or generate them using keyword symmetry_generate . CASTEP generates the dynamical matrix using perturbations along Cartesian X, Y and Z directions. To maximise the use of symmetry and minimise the number of perturbations required, the symmetry axes of the crystal or molecule should be aligned along Cartesian X, Y, and Z. If the cell axes are specified using %block LATTICE_ABC , CASTEP attempts to optimally orient the cell in many cases, but if using %block LATTICE_CART it is the responsibility of the user. This is one of the few cases where the absolute orientation makes any difference in a CASTEP calculation. An optimal orientation will use the fewest perturbations and lowest CPU time and will also exhibit best convergence with respect to, for example electronic k-point set. Phonon calculations should normally be set up using the primitive unit cell. As an example the conventional cell of a face-centred-cubic crystal contains four primitive unit cells, and thus four times the number of electrons and four times the volume. It will therefore cost 16 times as much memory and 16 times the compute time to run even the SCF calculation. CASTEP\u2019s symmetry analysis will print a warning to the .castep file if this is detected. A further reason to work with the primitive cell is that CASTEP defines its phonon {\\mathbf{q}} {\\mathbf{q}} -point parameters with respect to the actual simulation cell, and so a naive attempt to specify {\\mathbf{q}} {\\mathbf{q}} -point paths would result in output for a folded Brillouin-Zone, which is unlikely to be what is desired. Most input structure-preparation tools like c2x or cif2cell are capable of conversion between conventional and primitive cells. There is a further consideration related to symmetry; structure, cell and atomic co-ordinates must be specified to a reasonably high accuracy in the input files. CASTEP uses stochastic methods to analyse the effect of symmetry operations on the dynamical matrix, and this analysis can fail to detect symmetries or otherwise misbehave unless symmetry operations, lattice vectors and atomic co-ordinates are consistent to a reasonable degree of precision. It is recommended that symmetry-related lattice vectors and internal co-ordinates are consistent to at least 10 ^{-6} ^{-6} \u00c5\u2006 which can only be achieved if the values in the .cell file are expressed to this number of decimal places. This is particularly significant in the case of trigonal or hexagonal systems specified with %block LATTICE_CART where equality of the a a and b b cell vector lengths is only as precise as the number of significant figures used to represent the components. Two features of CASTEP\u2019s .cell file input may be helpful. First is the ability to input cell vectors and atomic positions using (a limited set of) mathematical syntax. See figure [example-gamma] for an example. Second, if the cell file keyword snap_to_symmetry is present, CASTEP will adjust co-ordinates and vectors to satisfy symmetry to high precision. Alternatively there is a utility program in the academic distribution named symmetry_snap which implements the same functionality. This is invoked simply as symmetry_snap seedname which reads seedname .cell and outputs the symmetrised version to seedname -symm.cell Thus the harmonic approximation is noticeably in error for very asymmetric potentials, which for examplein the worst cases can lead to disagreement with experimental frequencies of up to 5% for the librational modes of small molecular crystals, or OH bonds. It also neglects phonon-phonon interactions and therefore does not predict any intrinsic line broadening. \u21a9 Beware of the tempting but incorrect assumption that a CASTEP geometry optimisation is sufficient to find the true minimum-energy configuration of the atoms. Any such geometry optimization can only yield the minimum subject to the constraints imposed; in most cases by crystallographic symmetry and in all cases by the lattice repeat symmetry of the unit cell. The true system may be able to lower its energy further, but only by breaking the symmetry or lattice constraint. In such cases there will be an imaginary frequencies corresponding to any such possibility. \u21a9 This apparent problem may be turned to a positive advantage. A lattice dynamics calculation can be used as a test whether a purported equilibrium crystal structure really is dynamically stable. The presence of imaginary frequencies anywhere in the Brillouin Zone would indicate that the structure is unstable to a distortion along the corresponding eigenvector. Another occasion would be to investigate a transition state. By definition a transition state geometry is at a stationary saddle point of the energy hypersurface and must therefore exhibit precisely one imaginary frequency. A final example is the case of a system exhibiting a \u201csoft-mode\u201d phase transition where the frequency at the Brillouin-zone boundary decreases to zero, indicating that the crystal could lower its energy by doubling of the corresponding unit cell parameter. It is often useful to explore how the frequency approaches zero as some external variable such as pressure or lattice constant is varied, in order to precisely locate the phase transition. Reference ( Pallikara et al. 2022 ) discusses the physical significance of imaginary phonon modes in some details and with examples. \u21a9","title":"Introduction"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:theory","text":"Consider a crystal with a unit cell containing N N atoms, labelled \\kappa \\kappa , and a a labels the primitive cells in the lattice. The crystal is initially in mechanical equilibrium, with Cartesian co-ordinates R_{{\\kappa,\\alpha}} R_{{\\kappa,\\alpha}} , ( \\alpha=1..3 \\alpha=1..3 denotes the Cartesian x x , y y or z z direction). {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}= x_{{\\kappa,\\alpha,a}} - R_{{\\kappa,\\alpha,a}} denotes the displacement of an atom from its equilibrium position. Harmonic lattice dynamics is based on a Taylor expansion of total energy about structural equilibrium co-ordinates. E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... E = E_0 + \\sum_{{\\kappa,\\alpha,a}} \\frac{\\partial E}{\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}}.{{\\mathbf{u}}_{{\\kappa,\\alpha},a}}+ {\\frac{1}{2}} \\sum_{{\\kappa,\\alpha,a},{\\kappa^\\prime,\\alpha^\\prime},a^\\prime} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}.{\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,a^\\prime)}. {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},a^\\prime}}+ ... where {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} {{\\mathbf{u}}_{{\\kappa,\\alpha},a}} is the vector of atomic displacements from equilibrium and {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} is the matrix of force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}\\equiv {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a,0)}= \\frac{\\partial^2 E}{\\partial {{\\mathbf{u}}_{{\\kappa,\\alpha},a}}\\partial {{\\mathbf{u}}_{{\\kappa^\\prime,\\alpha^\\prime},0}}} \\;. At equilibrium the forces F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} F_{{\\kappa,\\alpha}} = -\\partial E/\\partial{{\\mathbf{u}}_{{\\kappa,\\alpha}}} are all zero so the first-order term vanishes. In the Harmonic Approximation the 3 ^{\\text{rd}} ^{\\text{rd}} and higher order terms are neglected 1 . Assume Born von Karman periodic boundary conditions and substitute a plane-wave trial solution {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) {{\\mathbf{u}}_{{\\kappa,\\alpha}}}= {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp( i {\\mathbf{q}}. {\\mathbf{R}}_{{\\kappa,\\alpha}} - \\omega_{m} t) with a phonon wavevector {\\mathbf{q}} {\\mathbf{q}} and a polarization vector {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} . This yields an eigenvalue equation {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}{\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}= \\omega_{m,{\\mathbf{q}}}^2 {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\; . The dynamical matrix is defined as {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})}= \\frac{1}{\\sqrt{M_\\kappa M_{\\kappa^\\prime}}} \\sum_{a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)} e^{-i \\mathbf{q}.{\\mathbf{r}}_a} where the index a a runs over all lattice images of the primitive cell. That is, the dynamical matrix is the mass-reduced Fourier transform of the force constant matrix. The eigenvalue equation [dmat-eigen] can be solved by standard numerical methods. The eigenvalues, \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 , must be real numbers because {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} is a Hermitian matrix. The vibrational frequencies at each mode \\omega_{m,{\\mathbf{q}}} \\omega_{m,{\\mathbf{q}}} are obtained as the square roots, and consequently are either real and positive (if \\omega_{m,{\\mathbf{q}}}^2 > 0 \\omega_{m,{\\mathbf{q}}}^2 > 0 ) or pure imaginary (if \\omega_{m,{\\mathbf{q}}}^2 < 0 \\omega_{m,{\\mathbf{q}}}^2 < 0 ) The corresponding eigenvectors are the polarization vectors, and describe the pattern of atomic displacements belonging to each mode. The central question of ab-initio lattice dynamics is therefore how to determine the force constants {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} which are the second derivatives of the total energy with respect to two atomic displacements. The first derivatives are the forces, and may be determined straightforwardly using the Hellman\u2013Feynmann Theorem as the derivative of the quantum mechanical energy with respect to an atomic displacement, \\lambda \\lambda \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} \\begin{aligned} E &= {\\left < \\psi \\right |}{\\hat{H}}{\\left | \\psi \\right >}\\qquad \\text{with}\\qquad {\\hat{H}}= \\nabla^2 + V_{\\text{SCF}}\\\\ F &= - \\frac{dE}{d\\lambda} \\\\ &= - {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\hat{H}}{\\left | \\psi \\right >}- {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >} \\; . \\end{aligned} If {\\left < \\psi \\right |} {\\left < \\psi \\right |} represents the ground state of {\\hat{H}} {\\hat{H}} then the first two terms vanish because {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 {\\left < \\psi \\right |}{\\hat{H}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= \\epsilon_n {\\left < \\psi \\right |}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}= 0 . Differentiating again yields \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. \\frac{d^2 E}{d \\lambda^2} = {\\left < {\\frac{d \\psi}{d \\lambda}}\\right |}{\\frac{d V}{d \\lambda}}{\\left | \\psi \\right >}+ {\\left < \\psi \\right |}{\\frac{d V}{d \\lambda}}{\\left | {\\frac{d \\psi}{d \\lambda}}\\right >}- {\\left < \\psi \\right |}{\\frac{d^2 V}{d \\lambda^2}}{\\left | \\psi \\right >}\\;. Unlike equation [hellman] the terms involving the derivatives of the wavefunctions do not vanish. This means that it is necessary to somehow compute the electronic response of the system to the displacement of an atom to perform ab-initio lattice dynamics calculations. This may be accomplished either by a finite-displacement method, i.e. performing two calculations which differ by a small displacement of an atomic co-ordinate and evaluating a numerical derivative, or by using perturbation theory to evaluate the response wavefunction {\\frac{d \\psi}{d \\lambda}} {\\frac{d \\psi}{d \\lambda}} . (In Kohn-Sham DFT, as implemented in CASTEP we actually evaluate the first-order response orbitals.) Some general references on ab-initio lattice dynamics methods are chapter 3 of ref ( Srivastava 2023 ) and the review paper by Baroni et al. ( Baroni et al. 2001 ).","title":"Theory of Lattice Dynamics"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:prerequisites","text":"","title":"Prerequisites"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:geometry","text":"A successful phonon calculation almost always requires a preceding geometry optimisation (except for small, high symmetry system where all atoms lie on crystallographic high-symmetry positions and the forces are zero by symmetry). It is not necessary to perform a variable-cell optimisation - the lattice dynamics is well defined at any stress or pressure, and phonons in high-pressure or strained systems are frequently of scientific interest. The two most convenient ways of achieving this are to Set up the phonon run as a continuation of the geometry optimisation by setting the parameters keyword continuation : . Add the keyword write_cell_structure : TRUE to the geometry optimization run and modify the resulting -out.cell to use as the input for a new run. The importance of a high-quality structure optimisation can not be overemphasized - the energy expansion in equation [taylor] makes the explicit assumption that the system is in mechanical equilibrium and that all atomic forces are zero. This is sufficiently important that before performing a phonon calculation CASTEP will compute the residual forces to determine if the geometry is converged. If any component of the force exceeds geom_force_tol it will print an error message and abort the run. Should a run fail with this message, it may be because the geometry optimisation run did not in fact succeed, or because some parameter governing the convergence ( e.g. the cutoff energy) differs in the phonon run compared to the geometry optimisation. In that case the correct procedure would be to re-optimise the geometry using the same parameters as needed for the phonon run. Alternatively if the geometry error and size of the force residual are tolerable, then the value of geom_force_tol may be increased in the .param file of the phonon calculation which will allow the run to proceed. How accurate a geometry optimization is needed? Accumulated practical experience suggests that substantially tighter tolerances are needed to generate reasonable quality phonons than are needed for structural or energetics calculations. For many crystalline systems a geometry force convergence tolerance set using parameter geom_force_tol of 0.01 eV/\u00c5 is typically needed. For \u201csoft\u201d materials containing weak bonds such as molecular crystals or in the presence of hydrogen bonds, an even smaller value is frequently necessary. Only careful convergence testing of the geometry and resulting frequencies can determine the value to use. To achieve a high level of force convergence, it is obviously essential that the forces be evaluated to at least the same precision. This will in turn govern the choice of electronic k-point sampling, and probably require a smaller than default SCF convergence tolerance, elec_energy_tol . See section [convergence] for further discussion of geometry optimisation and convergence for phonon calculations. If a lattice dynamics calculation is performed at the configuration which minimises the energy the force constant matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is positive definite, and all of its eigenvalues are positive. Consequently the vibrational frequencies which are the square roots of the eigenvalues are real numbers. 2 If on the other hand the system is not at a minimum energy equilibrium configuration {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is not necessarily positive definite, the eigenvalues \\omega_{m,{\\mathbf{q}}}^2 \\omega_{m,{\\mathbf{q}}}^2 may be negative. In that case the frequencies are imaginary and do not correspond to a physical vibrational mode. For convenience CASTEP prints such values using a a minus sign \u201c - - \u201d. These are sometimes loosely referred to as \u201cnegative\u201d frequencies, but bear in mind that this convention really indicates negative eigenvalues and imaginary frequencies. 3","title":"Geometry Optimisation"},{"location":"documentation/Phonons/Castep_Phonons/Introduction/#sec:symmetry","text":"CASTEP lattice dynamics uses symmetry to reduce the number of perturbation calculations to the irreducible set, and applies the symmetry transformations to generate the full dynamical matrix. Combined with the usual reduction in k-points in the IBZ, savings in CPU time by use of crystallographic symmetry can easily be a factor of 10 or more. It is therefore important to maximise the symmetry available to the calculation, and to either specify the symmetry operations in the .cell file using the %block SYMMETRY_OPS keyword or generate them using keyword symmetry_generate . CASTEP generates the dynamical matrix using perturbations along Cartesian X, Y and Z directions. To maximise the use of symmetry and minimise the number of perturbations required, the symmetry axes of the crystal or molecule should be aligned along Cartesian X, Y, and Z. If the cell axes are specified using %block LATTICE_ABC , CASTEP attempts to optimally orient the cell in many cases, but if using %block LATTICE_CART it is the responsibility of the user. This is one of the few cases where the absolute orientation makes any difference in a CASTEP calculation. An optimal orientation will use the fewest perturbations and lowest CPU time and will also exhibit best convergence with respect to, for example electronic k-point set. Phonon calculations should normally be set up using the primitive unit cell. As an example the conventional cell of a face-centred-cubic crystal contains four primitive unit cells, and thus four times the number of electrons and four times the volume. It will therefore cost 16 times as much memory and 16 times the compute time to run even the SCF calculation. CASTEP\u2019s symmetry analysis will print a warning to the .castep file if this is detected. A further reason to work with the primitive cell is that CASTEP defines its phonon {\\mathbf{q}} {\\mathbf{q}} -point parameters with respect to the actual simulation cell, and so a naive attempt to specify {\\mathbf{q}} {\\mathbf{q}} -point paths would result in output for a folded Brillouin-Zone, which is unlikely to be what is desired. Most input structure-preparation tools like c2x or cif2cell are capable of conversion between conventional and primitive cells. There is a further consideration related to symmetry; structure, cell and atomic co-ordinates must be specified to a reasonably high accuracy in the input files. CASTEP uses stochastic methods to analyse the effect of symmetry operations on the dynamical matrix, and this analysis can fail to detect symmetries or otherwise misbehave unless symmetry operations, lattice vectors and atomic co-ordinates are consistent to a reasonable degree of precision. It is recommended that symmetry-related lattice vectors and internal co-ordinates are consistent to at least 10 ^{-6} ^{-6} \u00c5\u2006 which can only be achieved if the values in the .cell file are expressed to this number of decimal places. This is particularly significant in the case of trigonal or hexagonal systems specified with %block LATTICE_CART where equality of the a a and b b cell vector lengths is only as precise as the number of significant figures used to represent the components. Two features of CASTEP\u2019s .cell file input may be helpful. First is the ability to input cell vectors and atomic positions using (a limited set of) mathematical syntax. See figure [example-gamma] for an example. Second, if the cell file keyword snap_to_symmetry is present, CASTEP will adjust co-ordinates and vectors to satisfy symmetry to high precision. Alternatively there is a utility program in the academic distribution named symmetry_snap which implements the same functionality. This is invoked simply as symmetry_snap seedname which reads seedname .cell and outputs the symmetrised version to seedname -symm.cell Thus the harmonic approximation is noticeably in error for very asymmetric potentials, which for examplein the worst cases can lead to disagreement with experimental frequencies of up to 5% for the librational modes of small molecular crystals, or OH bonds. It also neglects phonon-phonon interactions and therefore does not predict any intrinsic line broadening. \u21a9 Beware of the tempting but incorrect assumption that a CASTEP geometry optimisation is sufficient to find the true minimum-energy configuration of the atoms. Any such geometry optimization can only yield the minimum subject to the constraints imposed; in most cases by crystallographic symmetry and in all cases by the lattice repeat symmetry of the unit cell. The true system may be able to lower its energy further, but only by breaking the symmetry or lattice constraint. In such cases there will be an imaginary frequencies corresponding to any such possibility. \u21a9 This apparent problem may be turned to a positive advantage. A lattice dynamics calculation can be used as a test whether a purported equilibrium crystal structure really is dynamically stable. The presence of imaginary frequencies anywhere in the Brillouin Zone would indicate that the structure is unstable to a distortion along the corresponding eigenvector. Another occasion would be to investigate a transition state. By definition a transition state geometry is at a stationary saddle point of the energy hypersurface and must therefore exhibit precisely one imaginary frequency. A final example is the case of a system exhibiting a \u201csoft-mode\u201d phase transition where the frequency at the Brillouin-zone boundary decreases to zero, indicating that the crystal could lower its energy by doubling of the corresponding unit cell parameter. It is often useful to explore how the frequency approaches zero as some external variable such as pressure or lattice constant is varied, in order to precisely locate the phase transition. Reference ( Pallikara et al. 2022 ) discusses the physical significance of imaginary phonon modes in some details and with examples. \u21a9","title":"Use of Symmetry"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/","text":"The cell and param file keywords used specifically for phonon and related calculations are listed here alphabetically with brief descriptions. CELL file keywords PHONON_FINE_KPOINT_LIST List of phonon wavevectors on the fine grid (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer list of points. PHONON_FINE_KPOINT_MP_GRID Fine MP-grid of phonon wavevectors (Integer Vector) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer grid of wavevectors. PHONON_FINE_KPOINT_MP_OFFSET Origin offset of the fine phonon MP grid (Real Vector) The offset of the fine MP grid at which the phonons calculated using DFPT are interpolated. PHONON_FINE_KPOINT_MP_SPACING The spacing of points on the fine MP set for phonons (Physical) This specifies the minimum spacing between points on a Monkhorst-Pack grid that phonons will be interpolated onto from the coarser phonon grid. PHONON_FINE_KPOINT_PATH Path of phonon wavevectors on a fine scale (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer path. PHONON_FINE_KPOINT_PATH_SPACING The fine spacing of points on a path at which phonons are calculated (Physical) The spacing of k-points along a path (specified by PHONON_FINE_KPOINT_PATH ) at which phonons will be interpolated from a coarser grid PHONON_GAMMA_DIRECTIONS Phonon gamma-point LO/TO splitting (Block) This is a list of directions along which {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 will be calculated for the non-analytic LO/TO term in a phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 . Fractional coordinates must be used. Default value: The k-point before gamma in the k-point list, or the one after or (0.1, 0, 0) PHONON_KPOINTS_LIST Alias for PHONON_KPOINT_LIST (Block) Default value: Determined from PHONON_KPOINT_LIST PHONON_KPOINTS_PATH Alias for PHONON_KPOINT_PATH (Block) Default value: Determined from PHONON_KPOINT_PATH PHONON_KPOINTS_PATH_SPACING Alias for PHONON_KPOINT_PATH_SPACING (Physical) Default value: Determined from PHONON_KPOINT_PATH_SPACING PHONON_KPOINT_LIST List of phonon k-points (Block) A list of discrete k-points at which phonon frequencies and eigenvectors will be calculated. Default value: SCF k-points are used if an alternative PHONON_KPOINT_* specifier is not given. PHONON_KPOINT_MP_GRID Phonon wavevector Monkhorst-Pack grid (Integer Vector) The phonon wavevectors defined by a Monkhorst-Pack grid. Symmetry (if specified) will be used to generate the wavevector list and weights. PHONON_KPOINT_MP_OFFSET Phonon wavevector Monkhorst Pack grid offset (Real Vector) The offset of the origin of the Monkhorst-Pack set for phonons in fractional coordinates, or the keyword INCLUDE_GAMMA . Default value: INCLUDE_GAMMA PHONON_KPOINT_MP_SPACING Phonon wavevector Monkhorst-Pack grid density (Physical) The density of wavevectors on a a Monkhorst-Pack grid for phonon calculations. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_KPOINT_PATH Phonon dispersion k-point path (Block) The path continuous through the BZ on which phonon dispersion is calculated. This is specified in fractional coordinates. Default value: None. PHONON_KPOINT_PATH_SPACING Phonon dispersion path spacing (Physical) The maximum spacing between kpoints along the path specified by PHONON_KPOINT_PATH . Units of inverse length must be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_SUPERCELL_MATRIX Supercell matrix for finite difference phonon calculations (Block) The supercelling matrix for force constant matrix calculations. The supercell matrix is specified by a 3x3 integer matrix which gives the supercell used in finite-difference phonon calculations. SUPERCELL_KPOINTS_LIST SCF k-points for FD phonon supercell (Block) A list of k-points in the Brillouin zone (with associated weights) used for BZ integration during a supercell FD phonon calculation. The k-point weights must sum to 1. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING and the crystal symmetry. SUPERCELL_KPOINTS_MP_GRID SCF Monkhorst-Pack grid for FD phonon supercell calculation (Integer Vector) The k-points defined by a Monkhorst-Pack grid when doing a finite displacement phonon calculation. Symmetry (if specified) will be used to generate the k-point list and weights. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING . SUPERCELL_KPOINTS_MP_OFFSET SCF Monkhorst Pack grid offset for a FD phonon supercell calculation (Real Vector) The offset of the origin of the Monkhorst-Pack set in fractional coordinates when performing a finite displacement phonon calculation. Default value: (0, 0, 0). SUPERCELL_KPOINTS_MP_SPACING SCF Monkhorst-Pack grid density for FD phonon supercell calculation (Physical) The k-point density of a Monkhorst-Pack grid for a supercell FD phonon calculation. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PARAM file keywords NUM_BACKUP_ITER md/geom iterations between backups (Integer) Specifies the number of iterations between backups of all data for restarts, for a geometry optimization or molecular dynamics run. Allowed values: (any integer) > > 0 Default value : 5 BACKUP_INTERVAL seconds between backups (Integer) Specifies the interval, in seconds, between backups of all data for restarts, for a geometry optimization/molecular dynamics/phonon run - if less than or equal to zero then no timed backups. Allowed values: (any) Default value : 0 BORN_CHARGE_SUM_RULE enforce Born charge sum rule (Logical) Selects whether to explicitly correct the Born effective charge tensor to enforce the sum rule that effective charges sum to zero. CALCULATE_BORN_CHARGES calculate Born effective charges (Logical) Selects whether to compute Born effective charge tensors as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : TRUE CALCULATE_RAMAN calculate Raman intensities (Logical) Selects whether to compute Raman intensities as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : FALSE EFIELD_CALC_ION_PERMITTIVITY calculate zero-frequency permittivity (Logical) Specifies whether or not to compute the zero-frequency dielectric permittivity based on the ionic response to electric fields. This requires a gamma-point phonon calculation in addition to the EFIELD linear response one. Allowed values: TRUE or FALSE Default value : TRUE EFIELD_CALCULATE_NONLINEAR calculate non-linear optical susceptibility (String) Select which non-linear optical property to calculate during TASK=EFIELD calculation. Allowed values: NONE, CHI2 Default value : NONE EFIELD_CONVERGENCE_WIN convergence tolerance window in EFIELD (Integer) The LR convergence criteria must be met for EFIELD_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 EFIELD_DFPT_METHOD E-field DFPT solver method (String) Selects the solver for E-field density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : ALLBANDS EFIELD_ENERGY_TOL E(2) convergence tolerance in EFIELD (Physical) Tolerance for accepting convergence of the field constants during PHONON calculation. The difference between max and min E(2) values over EFIELD_CONVERGENCE_WIN iterations must be less than this. NB This is an INTENSIVE parameter and has units of volume. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} A ^3 ^3 EFIELD_FREQ_SPACING Spacing of frequencies in permittivity calculation (Physical) Spacing of frequencies in calculation of frequency-dependent permittivity. Allowed values: (any) > > 0.0 Default value : 1.0 cm ^{-1} ^{-1} EFIELD_IGNORE_MOLEC_MODES Ignore lowest modes in permittivity calculation (String) Ignore the lowest lying (3,5,6) modes when computing the ionic contribution to the permittivity and polarizability. Allowed values: CRYSTAL , MOLECULE , LINEAR_MOLECULE Default value : CRYSTAL EFIELD_MAX_CG_STEPS max. number of cg steps in EFIELD (Integer) The maximum number of conjugate gradient steps in EFIELD calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 EFIELD_MAX_CYCLES maximum cycles in EFIELD (Integer) The maximum number of SCF cycles in EFIELD calculation regardless of convergence. Allowed values: (any integer) > > 0 Default value : 50 EFIELD_OSCILLATOR_Q Q-factor for line-shape broadening (Real) Oscillator Q-factor for line-shape broadening in calculation of frequency- dependent permittivity. Allowed values: (any) > > 0.0 Default value : 50.0 EFIELD_UNIT unit of electric field in output (String) Controls the units used for all electric field in output - many different units are supported. Default value : eV/A/E ELEC_METHOD treatment of metals or finite temperature insulator (String) The treatment of metals or finite temperature insulator to be used. An alias for METALS_METHOD . Allowed values: NONE (=ALLBANDS), DM, EDFT Default value : DM EXCITED_STATE_SCISSORS \u201cscissors\u201d operator band-gap correction (Physical) Effectively adds an offset to conduction-band eigenvalues as empirical correction for LDA/GGA underestimation of band-gaps. Allowed values: (any) Default value : 0.0 FIX_OCCUPANCY treat system as an insulator (Logical) Determines if the system is treated as an insulator or a metal. Allowed values: TRUE or FALSE Default value : FALSE GEOM_FORCE_TOL geometry optimization force convergence tolerance (Physical) Tolerance for accepting convergence of the maximum |ionic force| during geometry optimization. Allowed values: (any) > > 0.0 Default value : 0.05 eV/A PHONON_CALCULATE_DOS density of states calculation (Logical) Determines whether or not the phonon density of states will be calculated. Allowed values: TRUE or FALSE Default value : FALSE PHONON_DOS_SPACING density of states calculation (Physical) The resolution at which a phonon density-of-states will be calculated. Allowed values: (any) > 0.0 > 0.0 Default value : 10.0 cm ^{-1} ^{-1} . PHONON_DOS_LIMIT density of states calculation (Logical) The largest phonon to be included in a phonon density-of-states calculation. Allowed values: (any) > > PHONON_DOS_SPACING Default value : 5000.0 cm ^{-1} ^{-1} . PHONON_CALC_LO_TO_SPLITTING gamma-point phonon LO/TO correction (Logical) Selects whether to compute non-analytic contribution to dynamical matrix from long-ranged electric field effects responsible for LO/TO splitting. This requires calculation of the dielectric permittivity by E-field linear-response and the Born effective charges. Allowed values: TRUE or FALSE Default value : TRUE PHONON_CONVERGENCE_WIN convergence tolerance window in LR (Integer) The LR convergence criteria must be met for PHONON_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 PHONON_ENERGY_TOL E(2) convergence tolerance in LR (Physical) Tolerance for accepting convergence of the force constants during PHONON calculation. The difference between max and min E(2) values over PHONON_CONVERGENCE_WIN iterations must be less than this. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} eV/A ^2 ^2 PHONON_FINE_METHOD fine phonon calculation method (String) Selects which calculation method to use for phonon calculation on a fine grid. Allowed values: NONE, SUPERCELL, INTERPOLATE Default value : SUPERCELL if TASK=THERMODYNAMICS else NONE PHONON_FINITE_DISP finite displacement amplitude (Physical) The amplitude of the ionic perturbation to be used in a finite displacement phonon calculation. Allowed values: (any) > > 0.0 Default value : 0.01 a_0 a_0 PHONON_FORCE_CONSTANT_CUTOFF Cutoff for force constant matrix (Physical) The cutoff for the force constant matrix in a phonon calculation on a fine grid with supercell method. Allowed values: (any) \\ge \\ge 0.0 Default value : 0.0 PHONON_FINE_CUTOFF_METHOD Selects which method to use to extract non-periodic force constant matrix from periodic supercell. (String) With the CUMULANT method, all contributions from the periodic supercell are summed with a suitable weighting factor to avoid double counting of image contributions. The SPHERICAL method, uses a minimum image convention with a spherical cutoff given by PHONON_FORCE_CONSTANT_CUTOFF . Allowed values: CUMULANT and SPHERICAL . Default value : CUMULANT . PHONON_FORCE_CONSTANT_CUT_SCALE Scaling factor for aspherical force constant matrix cutoff (Real) The range of force constant terms included is up to s times halfway to the Wigner Seitz cell boundary. This parameter supplies the value of s. Allowed values: 0.0 \\le \\le (any) \\ge \\ge 1.0 Default value : 0.0 PHONON_FORCE_CONSTANT_ELLIPSOID Ellipsoid size for force constant matrix (Real) Alias for PHONON_FORCE_CONSTANT_CUT_SCALE (deprecated). PHONON_MAX_CG_STEPS max. number of cg steps in LR (Integer) The maximum number of conjugate gradient steps in PHONON calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 PHONON_MAX_CYCLES maximum cycles in LR (Integer) The maximum number of SCF cycles in PHONON calculation regardless of convergence. Allowed values: (any integer) \\ge \\ge 0 or if TASK=PHONON etc \\ge \\ge PHONON_CONVERGENCE_WIN Default value : 50 PHONON_METHOD phonon calculation method (String) Selects which calculation method to use for phonons. Allowed values: DFPT, LINEARRESPONSE, FINITEDISPLACEMENT Default value : set by PHONON_FINE_METHOD PHONON_DFPT_METHOD phonon DFPT solver method (String) Selects the solver for phonon density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : DM if FIX_OCCUPANCY : FALSE , otherwise ALLBANDS PHONON_PRECONDITIONER scheme to use in LR (String) The preconditioning scheme used by the CG minimiser in LR. Allowed values: RTPA, TPA, PS, NONE Default value : TPA PHONON_SUM_RULE enforce phonon sum rule (Logical) Selects whether to explicitly correct the dynamical matrix to enforce the acoustic q=0 phonon sum rule, i.e. that 3 modes have zero frequency at q=0. Allowed values: TRUE or FALSE Default value : FALSE PHONON_SUM_RULE_METHOD select method to enforce phonon sum rule (String) Selects a method to use when enforcing acoustic phonon sum rule. Allowed values: NONE : No sum-rule correction will be applied. RECIPROCAL : Correct dynamical matrix D(q) at each q using D(q=0). REALSPACE : Correct the real-space force constant matrix C(R). REAL-RECIP : Correct C(R) in realspace followed by D(q) in reciprocal space. MOLECULAR : Correct D(0) using rotational as well as translational sum-rule. MOLECULAR-1D : Correct D(0) for a linear molecule using rotational as well as translational sum-rule. Default value : RECIPROCAL PHONON_USE_KPOINT_SYMMETRY reduced or full kpoint set in LR (Logical) Selects which k-point set to use For each phonon q-vector in LR: T => use the irreducible k-point set of the (reduced) symmetry, F => use the complete fully symmetric k-point set. Allowed values: TRUE or FALSE Default value : TRUE PHONON_WRITE_FORCE_CONSTANTS Write out real-space force constant matrix (Logical) Selects whether to write out the real-space force constant matrix from a phonon supercell or interpolation calculation (to the .castep file) for the case of PHONON_FINE_METHOD /= NONE. Allowed values: TRUE or FALSE Default value : FALSE PHONON_WRITE_DYNAMICAL Write out reciprocal space dynamical matrix (Logical) Selects whether to write out the reciprocal space dynamical matrices from a phonon calculation (to the .castep file). /= NONE. Allowed values: TRUE or FALSE Default value : FALSE THERMO_T_NPOINTS Number of points in temperature interval (Integer) The number of points in the temperature interval for the thermodynamics calculation. Allowed values: (any integer) \\ge \\ge 1 Default value : 2 if THERMO_T_STOP /= THERMO_T_START or 1 otherwise THERMO_T_SPACING Temperature spacing (Physical) The spacing between temperature values for the thermodynamics calculation. Allowed values: (any) > > (-epsilon) Default value : THERMO_T_STOP - THERMO_T_START THERMO_T_START Starting temperature (Physical) The desired starting temperature for the thermodynamics calculation. Allowed values: (any) > > 0.0 Default value : 298 K THERMO_T_STOP Final temperature (Physical) The desired final temperature for the thermodynamics calculation. Allowed values: (any) \\ge \\ge THERMO_T_START Default value : 298","title":"Keyword-Reference"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/#sec:cellkw","text":"PHONON_FINE_KPOINT_LIST List of phonon wavevectors on the fine grid (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer list of points. PHONON_FINE_KPOINT_MP_GRID Fine MP-grid of phonon wavevectors (Integer Vector) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer grid of wavevectors. PHONON_FINE_KPOINT_MP_OFFSET Origin offset of the fine phonon MP grid (Real Vector) The offset of the fine MP grid at which the phonons calculated using DFPT are interpolated. PHONON_FINE_KPOINT_MP_SPACING The spacing of points on the fine MP set for phonons (Physical) This specifies the minimum spacing between points on a Monkhorst-Pack grid that phonons will be interpolated onto from the coarser phonon grid. PHONON_FINE_KPOINT_PATH Path of phonon wavevectors on a fine scale (Block) Phonon frequencies are calculated on a coarse set of wavevectors using DFPT and interpolated onto this finer path. PHONON_FINE_KPOINT_PATH_SPACING The fine spacing of points on a path at which phonons are calculated (Physical) The spacing of k-points along a path (specified by PHONON_FINE_KPOINT_PATH ) at which phonons will be interpolated from a coarser grid PHONON_GAMMA_DIRECTIONS Phonon gamma-point LO/TO splitting (Block) This is a list of directions along which {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 will be calculated for the non-analytic LO/TO term in a phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 . Fractional coordinates must be used. Default value: The k-point before gamma in the k-point list, or the one after or (0.1, 0, 0) PHONON_KPOINTS_LIST Alias for PHONON_KPOINT_LIST (Block) Default value: Determined from PHONON_KPOINT_LIST PHONON_KPOINTS_PATH Alias for PHONON_KPOINT_PATH (Block) Default value: Determined from PHONON_KPOINT_PATH PHONON_KPOINTS_PATH_SPACING Alias for PHONON_KPOINT_PATH_SPACING (Physical) Default value: Determined from PHONON_KPOINT_PATH_SPACING PHONON_KPOINT_LIST List of phonon k-points (Block) A list of discrete k-points at which phonon frequencies and eigenvectors will be calculated. Default value: SCF k-points are used if an alternative PHONON_KPOINT_* specifier is not given. PHONON_KPOINT_MP_GRID Phonon wavevector Monkhorst-Pack grid (Integer Vector) The phonon wavevectors defined by a Monkhorst-Pack grid. Symmetry (if specified) will be used to generate the wavevector list and weights. PHONON_KPOINT_MP_OFFSET Phonon wavevector Monkhorst Pack grid offset (Real Vector) The offset of the origin of the Monkhorst-Pack set for phonons in fractional coordinates, or the keyword INCLUDE_GAMMA . Default value: INCLUDE_GAMMA PHONON_KPOINT_MP_SPACING Phonon wavevector Monkhorst-Pack grid density (Physical) The density of wavevectors on a a Monkhorst-Pack grid for phonon calculations. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_KPOINT_PATH Phonon dispersion k-point path (Block) The path continuous through the BZ on which phonon dispersion is calculated. This is specified in fractional coordinates. Default value: None. PHONON_KPOINT_PATH_SPACING Phonon dispersion path spacing (Physical) The maximum spacing between kpoints along the path specified by PHONON_KPOINT_PATH . Units of inverse length must be specified. Default value: 0.1 A ^{-1} ^{-1} . PHONON_SUPERCELL_MATRIX Supercell matrix for finite difference phonon calculations (Block) The supercelling matrix for force constant matrix calculations. The supercell matrix is specified by a 3x3 integer matrix which gives the supercell used in finite-difference phonon calculations. SUPERCELL_KPOINTS_LIST SCF k-points for FD phonon supercell (Block) A list of k-points in the Brillouin zone (with associated weights) used for BZ integration during a supercell FD phonon calculation. The k-point weights must sum to 1. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING and the crystal symmetry. SUPERCELL_KPOINTS_MP_GRID SCF Monkhorst-Pack grid for FD phonon supercell calculation (Integer Vector) The k-points defined by a Monkhorst-Pack grid when doing a finite displacement phonon calculation. Symmetry (if specified) will be used to generate the k-point list and weights. Default value: Generated from SUPERCELL_KPOINTS_MP_SPACING . SUPERCELL_KPOINTS_MP_OFFSET SCF Monkhorst Pack grid offset for a FD phonon supercell calculation (Real Vector) The offset of the origin of the Monkhorst-Pack set in fractional coordinates when performing a finite displacement phonon calculation. Default value: (0, 0, 0). SUPERCELL_KPOINTS_MP_SPACING SCF Monkhorst-Pack grid density for FD phonon supercell calculation (Physical) The k-point density of a Monkhorst-Pack grid for a supercell FD phonon calculation. Units of inverse length should be specified. Default value: 0.1 A ^{-1} ^{-1} .","title":"CELL file keywords"},{"location":"documentation/Phonons/Castep_Phonons/Keyword-Reference/#sec:paramkw","text":"NUM_BACKUP_ITER md/geom iterations between backups (Integer) Specifies the number of iterations between backups of all data for restarts, for a geometry optimization or molecular dynamics run. Allowed values: (any integer) > > 0 Default value : 5 BACKUP_INTERVAL seconds between backups (Integer) Specifies the interval, in seconds, between backups of all data for restarts, for a geometry optimization/molecular dynamics/phonon run - if less than or equal to zero then no timed backups. Allowed values: (any) Default value : 0 BORN_CHARGE_SUM_RULE enforce Born charge sum rule (Logical) Selects whether to explicitly correct the Born effective charge tensor to enforce the sum rule that effective charges sum to zero. CALCULATE_BORN_CHARGES calculate Born effective charges (Logical) Selects whether to compute Born effective charge tensors as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : TRUE CALCULATE_RAMAN calculate Raman intensities (Logical) Selects whether to compute Raman intensities as part of a phonon or E-field linear-response calculation. Allowed values: TRUE or FALSE Default value : FALSE EFIELD_CALC_ION_PERMITTIVITY calculate zero-frequency permittivity (Logical) Specifies whether or not to compute the zero-frequency dielectric permittivity based on the ionic response to electric fields. This requires a gamma-point phonon calculation in addition to the EFIELD linear response one. Allowed values: TRUE or FALSE Default value : TRUE EFIELD_CALCULATE_NONLINEAR calculate non-linear optical susceptibility (String) Select which non-linear optical property to calculate during TASK=EFIELD calculation. Allowed values: NONE, CHI2 Default value : NONE EFIELD_CONVERGENCE_WIN convergence tolerance window in EFIELD (Integer) The LR convergence criteria must be met for EFIELD_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 EFIELD_DFPT_METHOD E-field DFPT solver method (String) Selects the solver for E-field density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : ALLBANDS EFIELD_ENERGY_TOL E(2) convergence tolerance in EFIELD (Physical) Tolerance for accepting convergence of the field constants during PHONON calculation. The difference between max and min E(2) values over EFIELD_CONVERGENCE_WIN iterations must be less than this. NB This is an INTENSIVE parameter and has units of volume. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} A ^3 ^3 EFIELD_FREQ_SPACING Spacing of frequencies in permittivity calculation (Physical) Spacing of frequencies in calculation of frequency-dependent permittivity. Allowed values: (any) > > 0.0 Default value : 1.0 cm ^{-1} ^{-1} EFIELD_IGNORE_MOLEC_MODES Ignore lowest modes in permittivity calculation (String) Ignore the lowest lying (3,5,6) modes when computing the ionic contribution to the permittivity and polarizability. Allowed values: CRYSTAL , MOLECULE , LINEAR_MOLECULE Default value : CRYSTAL EFIELD_MAX_CG_STEPS max. number of cg steps in EFIELD (Integer) The maximum number of conjugate gradient steps in EFIELD calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 EFIELD_MAX_CYCLES maximum cycles in EFIELD (Integer) The maximum number of SCF cycles in EFIELD calculation regardless of convergence. Allowed values: (any integer) > > 0 Default value : 50 EFIELD_OSCILLATOR_Q Q-factor for line-shape broadening (Real) Oscillator Q-factor for line-shape broadening in calculation of frequency- dependent permittivity. Allowed values: (any) > > 0.0 Default value : 50.0 EFIELD_UNIT unit of electric field in output (String) Controls the units used for all electric field in output - many different units are supported. Default value : eV/A/E ELEC_METHOD treatment of metals or finite temperature insulator (String) The treatment of metals or finite temperature insulator to be used. An alias for METALS_METHOD . Allowed values: NONE (=ALLBANDS), DM, EDFT Default value : DM EXCITED_STATE_SCISSORS \u201cscissors\u201d operator band-gap correction (Physical) Effectively adds an offset to conduction-band eigenvalues as empirical correction for LDA/GGA underestimation of band-gaps. Allowed values: (any) Default value : 0.0 FIX_OCCUPANCY treat system as an insulator (Logical) Determines if the system is treated as an insulator or a metal. Allowed values: TRUE or FALSE Default value : FALSE GEOM_FORCE_TOL geometry optimization force convergence tolerance (Physical) Tolerance for accepting convergence of the maximum |ionic force| during geometry optimization. Allowed values: (any) > > 0.0 Default value : 0.05 eV/A PHONON_CALCULATE_DOS density of states calculation (Logical) Determines whether or not the phonon density of states will be calculated. Allowed values: TRUE or FALSE Default value : FALSE PHONON_DOS_SPACING density of states calculation (Physical) The resolution at which a phonon density-of-states will be calculated. Allowed values: (any) > 0.0 > 0.0 Default value : 10.0 cm ^{-1} ^{-1} . PHONON_DOS_LIMIT density of states calculation (Logical) The largest phonon to be included in a phonon density-of-states calculation. Allowed values: (any) > > PHONON_DOS_SPACING Default value : 5000.0 cm ^{-1} ^{-1} . PHONON_CALC_LO_TO_SPLITTING gamma-point phonon LO/TO correction (Logical) Selects whether to compute non-analytic contribution to dynamical matrix from long-ranged electric field effects responsible for LO/TO splitting. This requires calculation of the dielectric permittivity by E-field linear-response and the Born effective charges. Allowed values: TRUE or FALSE Default value : TRUE PHONON_CONVERGENCE_WIN convergence tolerance window in LR (Integer) The LR convergence criteria must be met for PHONON_CONVERGENCE_WIN iterations before acceptance. Allowed values: (any integer) \\ge \\ge 2 Default value : 2 PHONON_ENERGY_TOL E(2) convergence tolerance in LR (Physical) Tolerance for accepting convergence of the force constants during PHONON calculation. The difference between max and min E(2) values over PHONON_CONVERGENCE_WIN iterations must be less than this. Allowed values: (any) > > 0.0 Default value : 10^{-5} 10^{-5} eV/A ^2 ^2 PHONON_FINE_METHOD fine phonon calculation method (String) Selects which calculation method to use for phonon calculation on a fine grid. Allowed values: NONE, SUPERCELL, INTERPOLATE Default value : SUPERCELL if TASK=THERMODYNAMICS else NONE PHONON_FINITE_DISP finite displacement amplitude (Physical) The amplitude of the ionic perturbation to be used in a finite displacement phonon calculation. Allowed values: (any) > > 0.0 Default value : 0.01 a_0 a_0 PHONON_FORCE_CONSTANT_CUTOFF Cutoff for force constant matrix (Physical) The cutoff for the force constant matrix in a phonon calculation on a fine grid with supercell method. Allowed values: (any) \\ge \\ge 0.0 Default value : 0.0 PHONON_FINE_CUTOFF_METHOD Selects which method to use to extract non-periodic force constant matrix from periodic supercell. (String) With the CUMULANT method, all contributions from the periodic supercell are summed with a suitable weighting factor to avoid double counting of image contributions. The SPHERICAL method, uses a minimum image convention with a spherical cutoff given by PHONON_FORCE_CONSTANT_CUTOFF . Allowed values: CUMULANT and SPHERICAL . Default value : CUMULANT . PHONON_FORCE_CONSTANT_CUT_SCALE Scaling factor for aspherical force constant matrix cutoff (Real) The range of force constant terms included is up to s times halfway to the Wigner Seitz cell boundary. This parameter supplies the value of s. Allowed values: 0.0 \\le \\le (any) \\ge \\ge 1.0 Default value : 0.0 PHONON_FORCE_CONSTANT_ELLIPSOID Ellipsoid size for force constant matrix (Real) Alias for PHONON_FORCE_CONSTANT_CUT_SCALE (deprecated). PHONON_MAX_CG_STEPS max. number of cg steps in LR (Integer) The maximum number of conjugate gradient steps in PHONON calculation before performing a SD reset. Allowed values: (any integer) \\ge \\ge 0 Default value : 0 PHONON_MAX_CYCLES maximum cycles in LR (Integer) The maximum number of SCF cycles in PHONON calculation regardless of convergence. Allowed values: (any integer) \\ge \\ge 0 or if TASK=PHONON etc \\ge \\ge PHONON_CONVERGENCE_WIN Default value : 50 PHONON_METHOD phonon calculation method (String) Selects which calculation method to use for phonons. Allowed values: DFPT, LINEARRESPONSE, FINITEDISPLACEMENT Default value : set by PHONON_FINE_METHOD PHONON_DFPT_METHOD phonon DFPT solver method (String) Selects the solver for phonon density functional perturbation theory.. Allowed values: ALLBANDS(=VARIATIONAL) or DM(=GREEN) to select Gonze variational or Baroni Green function with DM solver. Default value : DM if FIX_OCCUPANCY : FALSE , otherwise ALLBANDS PHONON_PRECONDITIONER scheme to use in LR (String) The preconditioning scheme used by the CG minimiser in LR. Allowed values: RTPA, TPA, PS, NONE Default value : TPA PHONON_SUM_RULE enforce phonon sum rule (Logical) Selects whether to explicitly correct the dynamical matrix to enforce the acoustic q=0 phonon sum rule, i.e. that 3 modes have zero frequency at q=0. Allowed values: TRUE or FALSE Default value : FALSE PHONON_SUM_RULE_METHOD select method to enforce phonon sum rule (String) Selects a method to use when enforcing acoustic phonon sum rule. Allowed values: NONE : No sum-rule correction will be applied. RECIPROCAL : Correct dynamical matrix D(q) at each q using D(q=0). REALSPACE : Correct the real-space force constant matrix C(R). REAL-RECIP : Correct C(R) in realspace followed by D(q) in reciprocal space. MOLECULAR : Correct D(0) using rotational as well as translational sum-rule. MOLECULAR-1D : Correct D(0) for a linear molecule using rotational as well as translational sum-rule. Default value : RECIPROCAL PHONON_USE_KPOINT_SYMMETRY reduced or full kpoint set in LR (Logical) Selects which k-point set to use For each phonon q-vector in LR: T => use the irreducible k-point set of the (reduced) symmetry, F => use the complete fully symmetric k-point set. Allowed values: TRUE or FALSE Default value : TRUE PHONON_WRITE_FORCE_CONSTANTS Write out real-space force constant matrix (Logical) Selects whether to write out the real-space force constant matrix from a phonon supercell or interpolation calculation (to the .castep file) for the case of PHONON_FINE_METHOD /= NONE. Allowed values: TRUE or FALSE Default value : FALSE PHONON_WRITE_DYNAMICAL Write out reciprocal space dynamical matrix (Logical) Selects whether to write out the reciprocal space dynamical matrices from a phonon calculation (to the .castep file). /= NONE. Allowed values: TRUE or FALSE Default value : FALSE THERMO_T_NPOINTS Number of points in temperature interval (Integer) The number of points in the temperature interval for the thermodynamics calculation. Allowed values: (any integer) \\ge \\ge 1 Default value : 2 if THERMO_T_STOP /= THERMO_T_START or 1 otherwise THERMO_T_SPACING Temperature spacing (Physical) The spacing between temperature values for the thermodynamics calculation. Allowed values: (any) > > (-epsilon) Default value : THERMO_T_STOP - THERMO_T_START THERMO_T_START Starting temperature (Physical) The desired starting temperature for the thermodynamics calculation. Allowed values: (any) > > 0.0 Default value : 298 K THERMO_T_STOP Final temperature (Physical) The desired final temperature for the thermodynamics calculation. Allowed values: (any) \\ge \\ge THERMO_T_START Default value : 298","title":"PARAM file keywords"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/","text":"Several tools and programs are available to help automate post-processing analysis and plotting of the results of phonon calculations. The tools described below are supplied as part of the CASTEP source code distribution Other independently-developed spectroscopy modelling tools may be installed to perform more advanced modelling of, for example inelastic neutron and IR spectra. Two programs dispersion.pl and dos.pl are supplied as part of the CASTEP source distribution to analyse and plot the results. Both of them read the phonon information from the .castep or .phonon files and can generate plots of phonon dispersion curves across the Brillouin Zone, and of phonon densities of states respectively 1 . These programs are written in the PERL language which is almost universally available on modern operating systems. Generation of the plots is handled by either of the xmgrace or gnuplot graphics programs (the perl programs generate an xmgrace script and invoke it automatically). 2 dos.pl The dos.pl program can read any of a .castep , a .phonon , or a .phonon_dos file and generate a phonon density of states plot. Arguments are given in \u201cunix style\u201d following a minus sign (dash). The command dos.pl -xg -w 10 .phonon will generate a phonon density of states using a Gaussian broadening with a FWHM of 10 cm ^{-1} ^{-1} , and invoke xmgrace to generate the plot. If a .phonon file is specified the DOS is constructed as a weighted average over all q-points present in the file. Alternatively an adaptively-weighted dos computed by CASTEP is read from a .phonon_dos file if given as command-line argument. The options -np , -ps , -eps change the default output and write an xmgrace file, a PostScript or Encapsulated PostScript file respectively. These files are written to standard output so use a shell redirect ( > > ) to name your plot file. The option -ir option weights the computed DOS by the computed infra-red intensity in the .castep or .phonon file. This simple algorithm is not a fully realistic model of an infrared powder spectrum, and should be regarded as a simple approximation only. 3 Likewise the -raman option extracts Raman intensities and computes the weighted spectrum. The computed spectrum does include the frequency-dependent and Stokes thermal factors, and is therefore a more realistic model spectrum than in the infrared case. The -lorentz option switches from Gaussian to a Lorentzian broadening and the -temp T option sets the temperature for the Stokes thermal population term in Kelvin. Figure [bn-dos-ir] shows an example derived from the output produced by using dos.pl on the example run of figure [example-gamma-out] . Figure 8 Example output from dos.pl based on the run of figure [example-gamma-out] . Infrared spectrum and DOS curves based on just the TO modes or TO plus LO have been combined into into one plot with a slightly shifted baseline, scaled, and legends added. dispersion.pl The dispersion.pl program can read either a .castep or a .phonon file and generate a dispersion curve plot using xmgrace. Unlike the behaviour of dos.pl there is an important difference between the behaviour when reading these two different output files concerning the detection of branch crossings. A high-quality dispersion plot requires that phonon branches are drawn as continuous lines even when two branches cross in between the computed wavevectors. Dispersion.pl contains an algorithm based on matching of eigenvectors at adjacent points to determine branch connectivity. Only the .phonon file contains eigenvector information, so only in this case is crossing detection enabled. The algorithm can be time consuming and take several minutes to complete in large cases, so patience is sometimes required. The -nj option (\u201cno-join\u201d) disables the crossing detection even when the input file is a .phonon one. The options -np , -ps , -eps behave exactly as for dos.pl . One useful output option is -symmetry which attempts to label the high symmetry points using the conventional Brillouin zone notation of Bradley and Cracknell. The symmetry keywords cubic , fcc , bcc , tetragonal , tetragonal , tetragonal-I , orthorhombic , hexagonal , trigonal , trigonal-h (and minor variants) are understood. Figure [rbbr-dispersion] demonstrates the effect of the flags and the branch joining algorithm. The plots were produced from a Fourier interpolation calculation of fcc RbBr using the commands dispersion.pl -xg -symmetry fcc RbBr.phonon and dispersion.pl -xg -symmetry fcc -nj RbBr.phonon respectively. Figure 9 Phonon dispersion curve plots of RbBr generated using the dispersion.pl script and xmgrace. The Brillouin zone labelling is generated using the -symmetry fcc option. The left-hand plot was generated using the default branch crossing detection algorithm, which was disabled using the -nj option for the right-hand plot. The algorithm has discriminated between modes which do cross and the four genuine avoided crossings in the left-hand plot. mode_follow mode_follow is one of the Fortran tools suite in the CASTEP source, which is compiled using the command make tools . As the name implies its function is to generate new \u201cfrozen phonon\u201d configurations based on perturbation by a mode generated from a previous phonon calculation, which it outputs by writing one or more new .cell files. In fact it has two modes of operation. To generate a sequence of .cell files perturbed by the a frozen phonon at a range of amplitudes, which may be used to explore the energy profile along the mode it is invoked as mode follow -mode mode_num -namp num_amplitudes -amp max_amplitude -qpoint qx qy qz < < seedname > > | < < seedname > > .phonon which reads the .phonon and corresponding .cell files and generates a sequence of N+1 N+1 files seedname - i .cell containing structures perturbed by the selected eigenvector scaled by a non-dimensional amplitude factor f=A i/N, i=0 .. N f=A i/N, i=0 .. N . The arguments are mode_num is the integer index number selecting which mode to use (default 1) qx qy qz is the q-point to extract from the .phonon file (default (0,0,0)) max_amplitude is A A the non-dimensional scale of the eigenvectors used to create the (largest) displacement num_amplitudes is N N , one less than the number of configurations to generate (default 2). seedname is the seed name of a previous, successful phonon run. The file seedname .phonon must exist and be readable. If mode_follow is invoked without the .phonon extension, it will also attempt to read seedname .cell file if it exists and will copy most other cell parameters and settings to its output .cell files. As an alternative to specifying the arguments on the command line mode_follow will also attempt to read them from a file named seedname .mode-param if it exists. This file should contain a Fortran namelist named freeze , whose entries are the identical to the command-line argument names. For example &freeze mode=4 num_amplitudes=5, / To produce a frozen phonon configuration for a nonzero {\\mathbf{q}} {\\mathbf{q}} -vector it is also necessary to generate a supercell which is commensurate with a frozen phonon at wavevector {\\mathbf{q}} {\\mathbf{q}} . This supercell may be specified in the .cell file using the usual phonon_supercell_matrix block, or by the entry SUPERCELL in namelist freeze in the .mode-param file. (There is no corresponding command line argument). For example a .mode-param file requesting a zone-boundary phonon might contain &freeze mode=4 num_amplitudes=5, qpoint=0,0.5,0 supercell=1,0,0,0,2,0,0,0,1 / Mode_follow \u2019s second mode of operation is to generate output files with the structure perturbed by a frozen phonon at the same amplitude but a progressive sequence of phases, which could be used for an animation of the mode. In that case the num_amplitudes argument should be omitted, and the alternative nframes argument given instead (either on the command line or in the .mode-param file). This will generate a sequence of N N frames with phases separated by 2 \\pi/N 2 \\pi/N . Otherwise the arguments and behaviour are identical. One of the scripts in the cteprouts package, e.g. cell2xtl , cell2pdb , cell2xyz may be then be used to convert the .cell files to a form suitable for visualisation. phonons The program phonons , one of the CASTEP tools suite is a general purpose phonon post-processing tool. It can read all of the dynamical matrix or force constant matrix data from a .check or .castep_bin file generated in any phonon calculation and re-generate the final phonon output with changes to one or several \u201cfinalisation\u201d options, without needing to repeat the expensive \u201celectronic\u201d DFPT or supercell parts of a lattice dynamics calculation. For example, an acoustic sum-rule correction may be applied to a calculation where this was not chosen initially. phonons is invoked exactly as is CASTEP and reads a .cell and a .param file exactly as CASTEP does. These may be identical to or near copies of the original calculation, but the .param file must contain the continuation keyword which must point to the .check or .castep_bin file which contains the dynamical matrix data. If the run is successful it will write a log file with the extension .phonon_out and a new .phonon file. In this respect a run of phonons on a continuation deck is very similar to re-running castep on the same deck. However it will not attempt to perform any \u201celectronic\u201d calculation and will ignore any attempt to try. For example, if the parameter elec_energy_tol was changed castep would discard the saved dynamical matrix data and restart from the beginning. phonons will ignore this and process the saved data as a continuation run. This post-processing can be used for a number of tasks, including Turning on or off or modifying an acoustic sum-rule correction by changing the parameters keywords phonon_sum_rule or phonon_sum_rule_method . turning on or off the inclusion of LO/TO splitting terms by changing parameters keyword phonon_calc_lo_to_splitting or changing the set of directions for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 by adding or changing cell %block PHONON_GAMMA_DIRECTIONS . adding or omitting the low-frequency ionic term in an E-field calculation by changing parameter efield_calc_ion_permittivity . Note that an attempt to turn this on will only succeed if there result of a \\Gamma \\Gamma -point phonon calculation is already stored in the .check file. phonons will not attempt the electronic calculation necessary to compute this if it is not. changing the set of fine phonon k-points used as the target of a supercell or interpolation calculation by adding or changing %block PHONON_FINE_KPOINT_LIST , %block PHONON_FINE_KPOINT_PATH , phonon_fine_kpoint_mp_grid or similar in the .cell file. This permits the calculation of both a set of dispersion curves and a DOS from the same electronic run (DFPT/Interpolation or supercell). taking the result of a phonon calculation on a Monkhorst Pack grid of standard (not fine) phonon kpoints and performing Fourier interpolation as a post-processing step. switching interpolation methods between spherical and anisotropic schemes. All of the above could also be performed using castep rather than phonons provided care is taken not to change any parameters which control the properties of the \u201celectronic\u201d part of the calculation. However phonons can also perform some additional processing which castep can not, most notably isotopically substituted lattice dynamics calculations. dispersion.pl and dos.pl are also able perform very similar analysis and plotting of electronic eigenvalues from .castep or .bands files and generate band structure and electronic DOS plots. \u21a9 On linux systems xmgrace can usually be found as a contributed package and installed using the system package manager. Xmgrace is also available for Microsoft Windows systems as part of the \u201ccygwin\u201d suite of programs ( http://www.cygwin.com ) along with shells, the PERL interpreter and an X-windows server (Xmgrace is an X-windows program and requires a running X server to display). \u21a9 A more sophisticated model of infra-red spectra was introduced by Balan and Mauri (( Balan et al. 2001 ; Kendrick and Burnett 2016 ) and subsequent works). Modelling of inelastic neutron spectra is discussed by Fair ( Fair et al. 2022 ), Ramirez-Cuesta ( Ramirez-Cuesta 2004 ; Cheng and Ramirez-Cuesta 2020 ) \u21a9","title":"Plotting-and-analysis-tools"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:dos-pl","text":"The dos.pl program can read any of a .castep , a .phonon , or a .phonon_dos file and generate a phonon density of states plot. Arguments are given in \u201cunix style\u201d following a minus sign (dash). The command dos.pl -xg -w 10 .phonon will generate a phonon density of states using a Gaussian broadening with a FWHM of 10 cm ^{-1} ^{-1} , and invoke xmgrace to generate the plot. If a .phonon file is specified the DOS is constructed as a weighted average over all q-points present in the file. Alternatively an adaptively-weighted dos computed by CASTEP is read from a .phonon_dos file if given as command-line argument. The options -np , -ps , -eps change the default output and write an xmgrace file, a PostScript or Encapsulated PostScript file respectively. These files are written to standard output so use a shell redirect ( > > ) to name your plot file. The option -ir option weights the computed DOS by the computed infra-red intensity in the .castep or .phonon file. This simple algorithm is not a fully realistic model of an infrared powder spectrum, and should be regarded as a simple approximation only. 3 Likewise the -raman option extracts Raman intensities and computes the weighted spectrum. The computed spectrum does include the frequency-dependent and Stokes thermal factors, and is therefore a more realistic model spectrum than in the infrared case. The -lorentz option switches from Gaussian to a Lorentzian broadening and the -temp T option sets the temperature for the Stokes thermal population term in Kelvin. Figure [bn-dos-ir] shows an example derived from the output produced by using dos.pl on the example run of figure [example-gamma-out] . Figure 8 Example output from dos.pl based on the run of figure [example-gamma-out] . Infrared spectrum and DOS curves based on just the TO modes or TO plus LO have been combined into into one plot with a slightly shifted baseline, scaled, and legends added.","title":"dos.pl"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:dispersion-pl","text":"The dispersion.pl program can read either a .castep or a .phonon file and generate a dispersion curve plot using xmgrace. Unlike the behaviour of dos.pl there is an important difference between the behaviour when reading these two different output files concerning the detection of branch crossings. A high-quality dispersion plot requires that phonon branches are drawn as continuous lines even when two branches cross in between the computed wavevectors. Dispersion.pl contains an algorithm based on matching of eigenvectors at adjacent points to determine branch connectivity. Only the .phonon file contains eigenvector information, so only in this case is crossing detection enabled. The algorithm can be time consuming and take several minutes to complete in large cases, so patience is sometimes required. The -nj option (\u201cno-join\u201d) disables the crossing detection even when the input file is a .phonon one. The options -np , -ps , -eps behave exactly as for dos.pl . One useful output option is -symmetry which attempts to label the high symmetry points using the conventional Brillouin zone notation of Bradley and Cracknell. The symmetry keywords cubic , fcc , bcc , tetragonal , tetragonal , tetragonal-I , orthorhombic , hexagonal , trigonal , trigonal-h (and minor variants) are understood. Figure [rbbr-dispersion] demonstrates the effect of the flags and the branch joining algorithm. The plots were produced from a Fourier interpolation calculation of fcc RbBr using the commands dispersion.pl -xg -symmetry fcc RbBr.phonon and dispersion.pl -xg -symmetry fcc -nj RbBr.phonon respectively. Figure 9 Phonon dispersion curve plots of RbBr generated using the dispersion.pl script and xmgrace. The Brillouin zone labelling is generated using the -symmetry fcc option. The left-hand plot was generated using the default branch crossing detection algorithm, which was disabled using the -nj option for the right-hand plot. The algorithm has discriminated between modes which do cross and the four genuine avoided crossings in the left-hand plot.","title":"dispersion.pl"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#mode_follow","text":"mode_follow is one of the Fortran tools suite in the CASTEP source, which is compiled using the command make tools . As the name implies its function is to generate new \u201cfrozen phonon\u201d configurations based on perturbation by a mode generated from a previous phonon calculation, which it outputs by writing one or more new .cell files. In fact it has two modes of operation. To generate a sequence of .cell files perturbed by the a frozen phonon at a range of amplitudes, which may be used to explore the energy profile along the mode it is invoked as mode follow -mode mode_num -namp num_amplitudes -amp max_amplitude -qpoint qx qy qz < < seedname > > | < < seedname > > .phonon which reads the .phonon and corresponding .cell files and generates a sequence of N+1 N+1 files seedname - i .cell containing structures perturbed by the selected eigenvector scaled by a non-dimensional amplitude factor f=A i/N, i=0 .. N f=A i/N, i=0 .. N . The arguments are mode_num is the integer index number selecting which mode to use (default 1) qx qy qz is the q-point to extract from the .phonon file (default (0,0,0)) max_amplitude is A A the non-dimensional scale of the eigenvectors used to create the (largest) displacement num_amplitudes is N N , one less than the number of configurations to generate (default 2). seedname is the seed name of a previous, successful phonon run. The file seedname .phonon must exist and be readable. If mode_follow is invoked without the .phonon extension, it will also attempt to read seedname .cell file if it exists and will copy most other cell parameters and settings to its output .cell files. As an alternative to specifying the arguments on the command line mode_follow will also attempt to read them from a file named seedname .mode-param if it exists. This file should contain a Fortran namelist named freeze , whose entries are the identical to the command-line argument names. For example &freeze mode=4 num_amplitudes=5, / To produce a frozen phonon configuration for a nonzero {\\mathbf{q}} {\\mathbf{q}} -vector it is also necessary to generate a supercell which is commensurate with a frozen phonon at wavevector {\\mathbf{q}} {\\mathbf{q}} . This supercell may be specified in the .cell file using the usual phonon_supercell_matrix block, or by the entry SUPERCELL in namelist freeze in the .mode-param file. (There is no corresponding command line argument). For example a .mode-param file requesting a zone-boundary phonon might contain &freeze mode=4 num_amplitudes=5, qpoint=0,0.5,0 supercell=1,0,0,0,2,0,0,0,1 / Mode_follow \u2019s second mode of operation is to generate output files with the structure perturbed by a frozen phonon at the same amplitude but a progressive sequence of phases, which could be used for an animation of the mode. In that case the num_amplitudes argument should be omitted, and the alternative nframes argument given instead (either on the command line or in the .mode-param file). This will generate a sequence of N N frames with phases separated by 2 \\pi/N 2 \\pi/N . Otherwise the arguments and behaviour are identical. One of the scripts in the cteprouts package, e.g. cell2xtl , cell2pdb , cell2xyz may be then be used to convert the .cell files to a form suitable for visualisation.","title":"mode_follow"},{"location":"documentation/Phonons/Castep_Phonons/Plotting-and-analysis-tools/#sec:phonons-tool","text":"The program phonons , one of the CASTEP tools suite is a general purpose phonon post-processing tool. It can read all of the dynamical matrix or force constant matrix data from a .check or .castep_bin file generated in any phonon calculation and re-generate the final phonon output with changes to one or several \u201cfinalisation\u201d options, without needing to repeat the expensive \u201celectronic\u201d DFPT or supercell parts of a lattice dynamics calculation. For example, an acoustic sum-rule correction may be applied to a calculation where this was not chosen initially. phonons is invoked exactly as is CASTEP and reads a .cell and a .param file exactly as CASTEP does. These may be identical to or near copies of the original calculation, but the .param file must contain the continuation keyword which must point to the .check or .castep_bin file which contains the dynamical matrix data. If the run is successful it will write a log file with the extension .phonon_out and a new .phonon file. In this respect a run of phonons on a continuation deck is very similar to re-running castep on the same deck. However it will not attempt to perform any \u201celectronic\u201d calculation and will ignore any attempt to try. For example, if the parameter elec_energy_tol was changed castep would discard the saved dynamical matrix data and restart from the beginning. phonons will ignore this and process the saved data as a continuation run. This post-processing can be used for a number of tasks, including Turning on or off or modifying an acoustic sum-rule correction by changing the parameters keywords phonon_sum_rule or phonon_sum_rule_method . turning on or off the inclusion of LO/TO splitting terms by changing parameters keyword phonon_calc_lo_to_splitting or changing the set of directions for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 by adding or changing cell %block PHONON_GAMMA_DIRECTIONS . adding or omitting the low-frequency ionic term in an E-field calculation by changing parameter efield_calc_ion_permittivity . Note that an attempt to turn this on will only succeed if there result of a \\Gamma \\Gamma -point phonon calculation is already stored in the .check file. phonons will not attempt the electronic calculation necessary to compute this if it is not. changing the set of fine phonon k-points used as the target of a supercell or interpolation calculation by adding or changing %block PHONON_FINE_KPOINT_LIST , %block PHONON_FINE_KPOINT_PATH , phonon_fine_kpoint_mp_grid or similar in the .cell file. This permits the calculation of both a set of dispersion curves and a DOS from the same electronic run (DFPT/Interpolation or supercell). taking the result of a phonon calculation on a Monkhorst Pack grid of standard (not fine) phonon kpoints and performing Fourier interpolation as a post-processing step. switching interpolation methods between spherical and anisotropic schemes. All of the above could also be performed using castep rather than phonons provided care is taken not to change any parameters which control the properties of the \u201celectronic\u201d part of the calculation. However phonons can also perform some additional processing which castep can not, most notably isotopically substituted lattice dynamics calculations. dispersion.pl and dos.pl are also able perform very similar analysis and plotting of electronic eigenvalues from .castep or .bands files and generate band structure and electronic DOS plots. \u21a9 On linux systems xmgrace can usually be found as a contributed package and installed using the system package manager. Xmgrace is also available for Microsoft Windows systems as part of the \u201ccygwin\u201d suite of programs ( http://www.cygwin.com ) along with shells, the PERL interpreter and an X-windows server (Xmgrace is an X-windows program and requires a running X server to display). \u21a9 A more sophisticated model of infra-red spectra was introduced by Balan and Mauri (( Balan et al. 2001 ; Kendrick and Burnett 2016 ) and subsequent works). Modelling of inelastic neutron spectra is discussed by Fair ( Fair et al. 2022 ), Ramirez-Cuesta ( Ramirez-Cuesta 2004 ; Cheng and Ramirez-Cuesta 2020 ) \u21a9","title":"phonons"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/","text":"Phonon calculations even on small crystalline systems typically require many times the CPU resources of a ground state calculation. DFPT calculations of phonon dispersion compute dynamical matrices at a number of phonon wavevectors, each of which contains calculations of several perturbations. Each perturbation will typically require a large k-point set due to symmetry breaking by the perturbation. If the supercell method is used, converged calculations require a system of a typical size of a few hundred atoms, and many perturbations, although the k-point set used is smaller. Consequently, calculations on systems of scientific interest frequently require departmental, university or national-level supercomputing facilities, usually parallel cluster class machines. Much of the advice for effective use of cluster or supercomputer class resources is the same as for ground-state or other types of CASTEP calculations, but there are a few special considerations for phonon calculations, set out below. Among the particularly relevant general items are the choice of memory/speed tradeoff; usually the best approach is to select the highest speed option opt_strategy_bias : 3 1 which retains wavefunction coefficients in memory rather than paging to disk. For large calculations it is very frequently the case that that the memory requirement (in particular of the wavefunctions) is the most important consideration in choosing a parallel distribution. If a run fails due to exceeding the available memory per node, the processor count requested should be increased to distribute the wavefunction arrays across a larger set of processors, reducing the memory/processor requirement. If increasing the degree of parallel distribution is not possible, opt_strategy_bias can be reduced to 0 2 , which will page wavefunctions to disk. In that case it is vital to ensure that the temporary scratch files are written to high-speed disk (either local or a high-performance filesystem). This is usually controlled by setting the environment variable CASTEP_PAGE_TMPDIR to point to a directory on an appropriate filesystem 3 . Parallel execution CASTEP implements a parallel strategy based on a hierarchical distribution of wavefunction data by k-points, plane-waves, bands and OpenMP across processors 4 . In a phonon calculation this is used to speed up the execution within each perturbation and q-point which are still executed serially in sequence. Normally an efficient distribution is chosen automatically providing that the data_distribution parameter is not changed from the default value MIXED . K-points, plane-wave, band and task farm parallelism are all implemented using the Message-Passing Interface (MPI) system, and CASTEP must usually be launched by starting the executable using the mpiexec or similar commands, viz mpiexec -n 1024 castep.mpi which will start 1024 MPI processes and distribute the calculation across them. By contrast OpenMP parallelism is is activated by setting the environment variable CASTEP_NUM_THREADS : , which may be done before the mpiexec command to activate hybrid MPI+OpenMP mode. k-point and g-vector parallelism To best exploit the k-point component of the parallel distribution, the total number of the processors requested should be a multiple of the number of electronic k-points or have a large common divisor. The parallel distribution is printed to the .castep file, where in this example four k-points are used: Calculation parallelised over 32 nodes. K-points are distributed over 4 groups, each containing 8 nodes. For non-phonon CASTEP calculations it is sufficient to choose a processor count which is a multiple of N_{\\text{k}} N_{\\text{k}} , and that the degree of plane-wave-parallelism is not so large that efficiency is lost. However the choice of processor number in a phonon calculation is severely complicated by the fact that the number of electronic k-points in the irreducible Brillouin Zone changes during the run as the perturbations and phonon q-points have different symmetries. It is not convenient to compute the number for any perturbation individually without a detailed analysis, and some compromise between all of the perturbations should be chosen. To assist in this choice a utility program, phonon_kpoints is provided. This reads the configuration of the proposed calculation from the .cell file and is simply invoked by phonon_kpoints seedname It then determines and prints the k-point counts, and provides a \u201cfigure of merit\u201d for a range of possible processor counts. On most parallel architectures the efficiency of the plane-wave parallelism becomes unacceptable if there are fewer than around 200 plane-waves per node. It is usually possible to choose a processor count which allows a highly parallel run while keeping the number of plane-waves per node considerably higher than this. band parallelism From CASTEP version 24.1 band parallelism is implemented for FD calculations, but not yet DFPT. This may be enabled using a \u201cdevel-code\u201d string in the .param file 5 %block DEVEL_CODE PARALLEL:NBANDS=8:ENDPARALLEL %endblock DEVEL_CODE will attempt to set up 8-way band parallelism in addition to k-point and g-vector. perturbation parallelism From CASTEP release 24.1, a further level of parallelism called task-farming may be used to distribute perturbations across processors. This is set up and run in the same manner as for PIMD or NEB calculations by setting parameters file keyword num_farms : . The value of n n should not be too large, as the performance will be limited by load-balance issues, and in any case never greater than the number of perturbations. This will produce n n output files named _farm00.castep instead of the usual, single .castep file. Of these, _farm001.castep will contain the calculated final frequencies, Born effective charges etc. but a single instance of the .phonon , .efield , .phonon_dos and .check files are written as with other parallel schemes. hybrid OpenMP parallelism In addition to the above-described parallel distribution strategies - all based on MPI parallelism, CASTEP also offers a degree of OpenMP parallelism 6 . This can speed up some operations such as matrix diagonalisations and is activated by setting the environment variable CASTEP_NUM_THREADS : where n n in the range 2-16 is most effective (only a modest speed-up is accessible using OpenMP). However this can give a useful gain in addition to MPI parallelism especially in the case where compute nodes must be underpopulated because of memory requirements. Checkpointing and Restarting Even with a parallel computer, it is frequently the case that a calculation can not be completed in a single run. Many machines have a maximum time limit on a batch queue which may be too short. On desktop machines, run time may be limited by reliability and uptime limitations. CASTEP is capable of periodically writing \u201ccheckpoint\u201d files containing a complete record of the state of the calculation and of restarting and completing a calculation from such a checkpoint file. In particular dynamical matrices from complete q-points, and partial dynamical matrices from each perturbation are saved and can be used in a restart calculation. To enable the writing of periodic checkpoint files, set the parameter backup_interval 3600 which will write a checkpoint file named seedname .check every hour (the time is specified in seconds) or on completion of the next perturbation thereafter. To restart a calculation, set the parameter continuation : default in the .param file before resubmitting the job. This will attempt to read seedname .check and restart the calculation from there. Alternatively the full filename of a checkpoint file may be given as argument to the continuation keyword to read an explicitly named file. At the end of the calculation a checkpoint file seedname .check is always written. As with the intermediate checkpoint files this contains a (now complete) record of the dynamical matrices or force constant matrix resulting from phonon calculation. This may be analysed in a post-processing phase using the phonons utility. equivalent to opt_strategy : SPEED \u21a9 equivalent to opt_strategy : MEMORY \u21a9 If CASTEP_PAGE_TMPDIR is not set, the code falls back to the value of CASTEP_TMPDIR . \u21a9 k-points, plane-waves, bands correspond to indices of the wavefunction data, so parallelism in any of these will distribute the wavefunctions across MPI processes and reduce the memory/process requirement. \u21a9 This activation mechanism will be replaced by a \u201cfirst-class\u201d parameter to set parallelism in future releases of CASTEP. N.B. DEVEL_CODE is the only %block allowed in the .param file. \u21a9 See eCSE report for a description of the implementation and benchmark results \u21a9","title":"Running-Large-Calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#sec:parallelism","text":"CASTEP implements a parallel strategy based on a hierarchical distribution of wavefunction data by k-points, plane-waves, bands and OpenMP across processors 4 . In a phonon calculation this is used to speed up the execution within each perturbation and q-point which are still executed serially in sequence. Normally an efficient distribution is chosen automatically providing that the data_distribution parameter is not changed from the default value MIXED . K-points, plane-wave, band and task farm parallelism are all implemented using the Message-Passing Interface (MPI) system, and CASTEP must usually be launched by starting the executable using the mpiexec or similar commands, viz mpiexec -n 1024 castep.mpi which will start 1024 MPI processes and distribute the calculation across them. By contrast OpenMP parallelism is is activated by setting the environment variable CASTEP_NUM_THREADS : , which may be done before the mpiexec command to activate hybrid MPI+OpenMP mode.","title":"Parallel execution"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#k-point-and-g-vector-parallelism","text":"To best exploit the k-point component of the parallel distribution, the total number of the processors requested should be a multiple of the number of electronic k-points or have a large common divisor. The parallel distribution is printed to the .castep file, where in this example four k-points are used: Calculation parallelised over 32 nodes. K-points are distributed over 4 groups, each containing 8 nodes. For non-phonon CASTEP calculations it is sufficient to choose a processor count which is a multiple of N_{\\text{k}} N_{\\text{k}} , and that the degree of plane-wave-parallelism is not so large that efficiency is lost. However the choice of processor number in a phonon calculation is severely complicated by the fact that the number of electronic k-points in the irreducible Brillouin Zone changes during the run as the perturbations and phonon q-points have different symmetries. It is not convenient to compute the number for any perturbation individually without a detailed analysis, and some compromise between all of the perturbations should be chosen. To assist in this choice a utility program, phonon_kpoints is provided. This reads the configuration of the proposed calculation from the .cell file and is simply invoked by phonon_kpoints seedname It then determines and prints the k-point counts, and provides a \u201cfigure of merit\u201d for a range of possible processor counts. On most parallel architectures the efficiency of the plane-wave parallelism becomes unacceptable if there are fewer than around 200 plane-waves per node. It is usually possible to choose a processor count which allows a highly parallel run while keeping the number of plane-waves per node considerably higher than this.","title":"k-point and g-vector parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#band-parallelism","text":"From CASTEP version 24.1 band parallelism is implemented for FD calculations, but not yet DFPT. This may be enabled using a \u201cdevel-code\u201d string in the .param file 5 %block DEVEL_CODE PARALLEL:NBANDS=8:ENDPARALLEL %endblock DEVEL_CODE will attempt to set up 8-way band parallelism in addition to k-point and g-vector.","title":"band parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#perturbation-parallelism","text":"From CASTEP release 24.1, a further level of parallelism called task-farming may be used to distribute perturbations across processors. This is set up and run in the same manner as for PIMD or NEB calculations by setting parameters file keyword num_farms : . The value of n n should not be too large, as the performance will be limited by load-balance issues, and in any case never greater than the number of perturbations. This will produce n n output files named _farm00.castep instead of the usual, single .castep file. Of these, _farm001.castep will contain the calculated final frequencies, Born effective charges etc. but a single instance of the .phonon , .efield , .phonon_dos and .check files are written as with other parallel schemes.","title":"perturbation parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#hybrid-openmp-parallelism","text":"In addition to the above-described parallel distribution strategies - all based on MPI parallelism, CASTEP also offers a degree of OpenMP parallelism 6 . This can speed up some operations such as matrix diagonalisations and is activated by setting the environment variable CASTEP_NUM_THREADS : where n n in the range 2-16 is most effective (only a modest speed-up is accessible using OpenMP). However this can give a useful gain in addition to MPI parallelism especially in the case where compute nodes must be underpopulated because of memory requirements.","title":"hybrid OpenMP parallelism"},{"location":"documentation/Phonons/Castep_Phonons/Running-Large-Calculations/#sec:checkpointing","text":"Even with a parallel computer, it is frequently the case that a calculation can not be completed in a single run. Many machines have a maximum time limit on a batch queue which may be too short. On desktop machines, run time may be limited by reliability and uptime limitations. CASTEP is capable of periodically writing \u201ccheckpoint\u201d files containing a complete record of the state of the calculation and of restarting and completing a calculation from such a checkpoint file. In particular dynamical matrices from complete q-points, and partial dynamical matrices from each perturbation are saved and can be used in a restart calculation. To enable the writing of periodic checkpoint files, set the parameter backup_interval 3600 which will write a checkpoint file named seedname .check every hour (the time is specified in seconds) or on completion of the next perturbation thereafter. To restart a calculation, set the parameter continuation : default in the .param file before resubmitting the job. This will attempt to read seedname .check and restart the calculation from there. Alternatively the full filename of a checkpoint file may be given as argument to the continuation keyword to read an explicitly named file. At the end of the calculation a checkpoint file seedname .check is always written. As with the intermediate checkpoint files this contains a (now complete) record of the dynamical matrices or force constant matrix resulting from phonon calculation. This may be analysed in a post-processing phase using the phonons utility. equivalent to opt_strategy : SPEED \u21a9 equivalent to opt_strategy : MEMORY \u21a9 If CASTEP_PAGE_TMPDIR is not set, the code falls back to the value of CASTEP_TMPDIR . \u21a9 k-points, plane-waves, bands correspond to indices of the wavefunction data, so parallelism in any of these will distribute the wavefunctions across MPI processes and reduce the memory/process requirement. \u21a9 This activation mechanism will be replaced by a \u201cfirst-class\u201d parameter to set parallelism in future releases of CASTEP. N.B. DEVEL_CODE is the only %block allowed in the .param file. \u21a9 See eCSE report for a description of the implementation and benchmark results \u21a9","title":"Checkpointing and Restarting"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/","text":"CASTEP contains implementations of several methods for computing the electronic response orbitals and the dynamical matrix ( Refson, Tulip, and Clark 2006 ). There are implementation restrictions and the choice of the most suitable one depends on the type of calculation, the Hamiltonian, and the property calculations required. See table [captable] for details. For straightforward semi-local DFT calculations (LDA, PBE etc.) the density-functional perturbation theory method (DFPT) method is preferred (section [dfpt-gamma] ), as this is not only the most efficient, but also allows the calculation of infra red and Raman intensities for modelling of spectra. DFPT is not yet implemented for ultrasoft pseudopotentials, or for Hubbard U or some dispersion-corrected DFT methods (as of release 24.1), and in these cases the finite displacement method should be used (section [fd] ). If a density of states or finely sampled dispersion curve along high symmetry directions is needed, then either the DFPT method with Fourier interpolation (section [ddos] ) is the most suitable or the finite-displacement supercell (section [supercell] ; if ultrasoft pseudopotentials are required). A summary of the recommended approach for various property calculations is given in table [method-selection] . DFPT (Phonon) DFPT (E-field) FD (Phonon) USP \u2718 \u2718 \u2713 NCP \u2713 \u2713 \u2713 LDA, GGA \u2713 \u2713 \u2713 MGGA \u2718 \u2718 \u2713 DFT+U \u2718 \u2718 \u2713 NCM/SOC \u2718 \u2718 \u2713 PBE0, Hybrid XC \u2718 \u2718 \u2713 DFT+D: TS, D2 \u2713 \u2713 \u2713 DFT+D: D3,D4, MBD*,XDM \u2718 \u2713 \u2713 Table 1: CASTEP phonons implementation matrix. In general DFPT is avalable for semilocal DFPT, but not other Hamiltonians. The combination of DFPT and USPs is not implemented. Target Property Preferred method IR spectrum DFPT at q=0 with NCP potentials (section. [dfpt-gamma] ) FD at q=0 with NCP potentials and DFPT e-field (section. [fd] ) FD at q=0 with USP potentials and Berry Phase Z^{*} Z^{*} (section. [berry-fd] ) Raman spectrum DFPT at q=0 with NCP potentials (2n+1 theorem) (section. [raman] ) Born Effective Charges ( Z^{*} Z^{*} ) DFPT E-field using NCP potentials (section. [efield] ) FD at q=0 with USP potentials and Berry Phase Z^{*} Z^{*} (section. [berry-fd] ) Dielectric Permittivity ( \\epsilon_\\infty \\epsilon_\\infty ) DFPT E-field using NCP potentials (section. [efield] ) Nonlinear optical susceptibility ( \\chi^{(2)} \\chi^{(2)} ) DFPT E-field (2n+1 theorem) using NCP potentials (section. [nlo] ) Phonon dispersion or DOS DFPT plus interpolation with NCP potentials (section. [ddos] ) FD plus interpolation using USP or NCP potentials (section. [ndsc] ) FD with supercell using USP or NCP potentials (section. [supercell] ) Vibrational Thermodynamics same as DOS (section. [thermodynamics] ) Table 2: Available and recommended methods for different property calculations. A DFPT phonon calculation at the \\Gamma \\Gamma -point Many of the principles of setting up and running phonon calculations can be illustrated in the simplest case - computing phonon frequencies at the q=(0,0,0) q=(0,0,0) , often referred to as the \\Gamma \\Gamma point. This is a very common calculation, as it forms the basis of modelling of infra-red or Raman spectra and group theoretical analysis and assignment of the modes. Input files The setup for a CASTEP phonon calculation requires a few additional keywords in the seedname .cell file. Like any type of calculation, the unit cell must be specified using either of %block LATTICE_ABC or %block LATTICE_CART , and the atomic co-ordinates using %block POSITIONS_FRAC or %block POSITIONS_ABS . Figure [example-gamma] shows a complete input file for a calculation on boron nitride in the hexagonal Wurtzite structure. The additional keywords. phonon_kpoint_list is used to specify that a single phonon wavevector (0,0,0) is to be computed 1 . More wavevectors could be specified using additional lines in this block. 2 %block LATTICE_ABC 2.536000 2.536000 4.199000 ! a, b, c 90.000000 90.000000 120.000000 ! alpha, beta, gamma %endblock LATTICE_ABC %block POSITIONS_FRAC B 2/3 1/3 0.000000 ! Atom co-ordinates in crystallographic N 2/3 1/3 0.374536 ! fractional system. B 1/3 2/3 0.500000 N 1/3 2/3 0.874536 %endblock POSITIONS_FRAC %block SPECIES_POT B B_00.recpot ! File names of pseudopotential to use for B N N_00.recpot %endblock SPECIES_POT kpoints_mp_spacing 0.07 ! Generate MP grid of electronic k-points. symmetry_generate ! Find symmetry operations of crystal structure %block PHONON_KPOINT_LIST 0.0 0.0 0.0 1.0 ! Wavevector of phonon(s) to compute ( qx qy qz, weight) %endblock PHONON_KPOINT_LIST task : PHONON ! Choose a phonon calculation xc_functional : LDA opt_strategy : SPEED ! Optimise for speed over memory saving cut_off_energy : 700.0 eV ! Plane-wave cutoff for this system elec_method : DM ! Use fast DM solver even for insulating system phonon_sum_rule : TRUE ! Enforce acoustic sum rule on calculated D Figure 1: Annotated example cell and parameter files for BN in the Wurtzite structure. Note that phonon_method defaults to DFPT . Reading the output Figure [example-gamma-out] shows part of the phonon-relevant output extracted from the .castep file obtained by running the input files of the previous section. There are several blocks of output, one per direction chosen for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 in the LO-TO splitting terms. Note that CASTEP has added a calculation without LO-TO splitting (the first block), even though this was not explicitly requested. Within each block frequencies are listed one per line. Also on the line are (a) a label indicating the irreducible representation of the mode from a group theory analysis, (b) the computed absorptivity of the mode in a powder (or otherwise orientationally averaged) infrared experiment, \u00a9 whether the mode is IR active, (d) the Raman activity (if computed) and (e) whether the mode is Raman active. ============================================================================== + Vibrational Frequencies + + ----------------------- + + + + Performing frequency calculation at 1 wavevector (q-pt ) + + ========================================================================== + + + + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 1.0000000000 + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.049170 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1016.312039 a 28.5895083 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1051.124801 b 25.8079204 Y Y + + 12 1123.472590 d 0.0000000 N N + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + Figure 2 Output in the .castep file generated by the preceding input files for wurtzite BN. The columns show the mode frequencies, a letter labelling of the irreducible representation of the mode, the infrared absorptivity and Raman activity, and whether or not the mode is Raman and/or IR active. Not all of these are present in every calculation depending on the use of symmetry and input options. + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 0.0000000000 + + q->0 along ( 0.000000 0.000000 1.000000) + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.037851 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1051.124801 b 25.8079204 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1123.472590 d 0.0000000 N N + + 12 1262.933291 a 28.5895083 Y Y + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + (Due to LO/TO splitting this character table may not contain some symmetry + + operations of the full crystallographic point group. Additional + + representations may be also be present corresponding to split LO modes. + + A conventional analysis can be generated by specifying an additional null + + (all zero) field direction or one along any unique crystallographic axis + + in %BLOCK PHONON_GAMMA_DIRECTIONS in .cell.) + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + ============================================================================== Figure 2 Run output (continued): If the LO-TO-splitting calculation is active the \\Gamma \\Gamma point frequency table is repeated, both without and including the non-analytic contribution which generates the LO/TO splitting in one or more directions (See Gonze and Lee ( Gonze and Lee 1997 )). (The group theory analysis for LO modes is less useful than might be wanted and is likely to be the subject of future developments.) As with other calculations the amount of information written to the .castep file is controlled by the value of the parameter iprint . The levels of output are iprint : 0 Minimal output as in figure [example-gamma-out] . No progress info. iprint : 1 As for iprint : 0 but including a reassuring progress report of q-points and perturbations. iprint : 2 More detailed output including details of k-points and symmetry for each perturbation, cycle-by cycle DFPT minimiser report, printing of dynamical matrices (and force constant matrices). In addition to the user-readable output in the .castep file 3 , every phonon calculation generates an additional output file with the suffix .phonon which is intended for postprocessing analysis by other programs. This includes not only the frequencies but also the eigenvectors {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} resulting from diagonalising the dynamical matrix. These eigenvectors are orthonormal and the relationship between the eigenvectors and atomic displacements is given by u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) where Q_M Q_M is the amplitude of mode m m and the other notation is as set out in the introduction. Raman activity calculations In addition to the infrared absorptivity computed as a default part of a \\Gamma \\Gamma -point phonon calculation, CASTEP is also capable of computing the Raman activity tensors in the case of non-resonant scattering for an insulating system 4 . This calculation uses an extension of DFPT known as the \u201c2n+1 theorem\u201d ( Baroni et al. 2001 ; Miwa 2011 ) which requires substantially more computational effort than a bare phonon calculation and is therefore not enabled by default. To compute Raman activity set calculate_raman : TRUE in the .param file, which calculates and prints the Raman atomic susceptibility tensors and the mode susceptibility tensors to the .castep file. These may be extracted for use when modelling the Raman scattering in a polarised single-crystal geometry. 5 As with the Born effective charges and dynamical matrices, there is a sum rule on the values of the atomic polar tensors, which may not be well satisfied because of numerical approximations. A correction will be applied if parameter raman_sum_rule : TRUE is set. A 3d-average Raman activity (see Porezag and Pedersen ( Porezag and Pederson 1996 )) is computed from the susceptibility tensors and printed as an additional column in the usual frequency output given in figure [example-gamma-out] . This may be used for simple modelling of a powder spectrum, for example using the dos.pl tool (see section [dos-pl] ). Dispersion and density of states Phonons of a nonzero wavevector play an important role in the thermophysical properties of crystalline solids and the physics of many solid-state phase transitions. Proving the mechanical stability of a crystal structure by testing for real frequencies requires a vibrational calculation over the full Brillouin Zone. And dispersion curves and densities of states are frequently required for comparison with inelastic neutron and X-ray scattering experiments. One of the benefits of density functional perturbation theory is that CASTEP can calculate vibrational modes at {\\mathbf{q}}\\ne \\mathbf{0} {\\mathbf{q}}\\ne \\mathbf{0} as easily as at {\\mathbf{q}}= \\mathbf{0} {\\mathbf{q}}= \\mathbf{0} (but at the cost of an increase in CPU time due to the decreased symmetry). It is possible to perform this calculation simply by providing a list of q-points in the .cell file ( using one of the blocks %block PHONON_KPOINT_LIST , or %block PHONON_KPOINT_PATH or keyword phonon_kpoint_mp_grid ). However to generate a reasonable quality dispersion plot or density of states will usually require hundreds or thousands of q-points. The time required by such a calculation would be several hundred times that for a single-point energy and therefore infeasibly large. Fortunately there is a way to achieve the same result at a far smaller computational cost. This method exploits the fact that the interatomic interactions in a solid have a finite range and decay rapidly to zero. Specifically, the elements of the force constant matrix in Eq. [fcmat] decrease as 1 / r^{5} 1 / r^{5} with interatomic distance. Consequently the dynamical matrix defined by Eq. [dmat] and its eigenvalues \\omega^{2}({\\mathbf{q}}) \\omega^{2}({\\mathbf{q}}) are smoothly varying with wavevector {\\mathbf{q}} {\\mathbf{q}} . Fourier interpolation is used to generate dynamical matrices on an arbitrarily fine grid or linear path in reciprocal space from a set of DFPT calculations on a much coarser grid. For a full description of the method see references ( Baroni et al. 2001 ; Giannozzi et al. 1991 ; Gonze and Lee 1997 ). A complication arises in the case of polar solids where the dipole-dipole interaction generated upon displacing an atom leads to a longer ranged force constant matrix which decays only as 1 / r^{3} 1 / r^{3} . CASTEP models this term analytically using Born effective charges and dielectric permittivity calculated using an electric field response DFPT calculation (see section [efield] and Ref. ( Gonze and Lee 1997 )). It is therefore able to perform the Fourier interpolation for only the part of the force constant matrix which varies as 1 / r^{5} 1 / r^{5} , and does not require a finer grid than in the case of non-polar solids. Setting up an interpolation calculation In the .cell file choose the q-points of the coarse grid of points at which to perform DFPT calculations. This may be specified as a %block PHONON_KPOINT_LIST containing the reduced set of points in the irreducible Brillouin Zone, but is is almost always more straightforward to use the alternative keywords phonon_kpoint_mp_grid : p q r phonon_kpoint_mp_offset : INCLUDE_GAMMA to specify the grid parameters and offset 6 . The grid parameters p , q and r should normally be chosen to give a roughly uniform sampling of reciprocal space taking length of the reciprocal lattice vectors into account, and should be compatible with the symmetry of the simulation cell. Alternatively a grid may be specified using the minimum spacing, for example phonon_kpoint_mp_grid_spacing 0.1 1/ang Normally the grid should be chosen to contain the \\Gamma \\Gamma point, which usually gives better convergence properties of the interpolation ( i.e.*convergence at smaller *p,q,r ) than otherwise. This is the opposite behaviour to electronic k-point sampling (see Ref. ( Probert and Payne 2003 )). The special keyword value phonon_kpoint_mp_offset : INCLUDE_GAMMA avoids the need to work out the offset explicitly. The choice of grid parameters p , q and r is governed by three considerations: For a 3-dimensional crystal, p,q,r should obey the crystallographic symmetry , so for a cubic or rhombohedral crystal you should set p = q = r p = q = r . In the case of a uniaxial crystal, such as tetragonal or hexagonal we have p = q \\neq r p = q \\neq r (assuming that c c is the unique axis) and for lower symmetry there is no constraint. The value in any of the directions limits the range of the force constant matrix in much the same way as the supercell multiplier does in a finite-difference/supercell calculation (Section [supercell] ). Exactly how large this should be depends on the nature of the chemical bonding. Ionically bonded systems tend to have fairly short-ranged force-constant matrices and need relatively coarse grids for convergence. For sodium chloride in the rocksalt structure with a primitive lattice parameter 3.75\u00c5 a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 grid is reasonably close to convergence. This corresponds to a truncation of the force constant matrix at a distance of approximately 7 7 \u00c5 ( \\approx p \\times 2 \\pi / a \\approx p \\times 2 \\pi / a ). On the other hand covalent systems tend to have fairly long-ranged force-constant matrices and need finer grids for convergence. Silicon is a good example of this. The primitive lattice parameter is similar to sodium chloride at 3.81 3.81 \u00c5, but the dispersion curve is not fully converged until an 8 \\times 8 \\times 8 8 \\times 8 \\times 8 grid is used. A more detailed examination of this point may be found in reference ( Ackland, Warren, and Clark 1997 ). While there is no essential physics relationship between the grid sizes for phonon {\\mathbf{q}} {\\mathbf{q}} -points and that required for electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling 7 , there is a technical connection resulting from the implementation of density-functional perturbation theory and the requirement to generate and use ground-state Kohn-Sham wavefunctions on grids containing both \\{{\\mathbf{k}}\\} \\{{\\mathbf{k}}\\} and \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} (See ref. ( Gonze 1997 ) for the mathematical details). For best performance and stability of the DFPT calculation the phonon grid parameters should be commensurate with the electronic grid with an exact divisor as the simplest case. For example, in an elemental metal with an hcp structure such as Mg, an electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling of 21 \\times 21 \\times 12 21 \\times 21 \\times 12 and a phonon {\\mathbf{q}} {\\mathbf{q}} -point sampling of 7 \\times 7 \\times 6 7 \\times 7 \\times 6 might be most effective. This is not a hard requirement and CASTEP will attempt to work with whatever grids are specified, but in some cases there may be a performance advantage to rounding up one or other of the grids to meet the commensurability criterion. Additional keywords in the .param file control the interpolation. Most importantly phonon_fine_method : INTERPOLATE instructs CASTEP to perform the Fourier interpolation step following the usual DFPT calculation. The target set of wavevectors for the interpolation is set up using additional keywords or blocks in the .cell file. Either phonon_fine_kpoint_mp_grid p q r phonon_fine_kpoint_mp_offset o _1 _1 o _2 _2 o _3 _3 or phonon_fine_kpoint_mp_spacing 0.03 1/ang . will perform interpolation onto a regular (possibly offset) grid. In fact only the points in the irreducible wedge of the Brillouin Zone are included, and a suitable weight is computed so that the weighted average is identical to a uniform sampling of the BZ. This is the usual method for computing a phonon density of states. If a set of dispersion curves along high symmetry directions is required, an empty cell keyword block %block PHONON_FINE_KPOINT_PATH %endblock PHONON_FINE_KPOINT_PATH will internally generate a list of {\\mathbf{q}} {\\mathbf{q}} -points sampling a default path through the Brillouin-Zone according to the symmetry of the calculation. Alternatively a list of {\\mathbf{q}} {\\mathbf{q}} -points explicitly specifying the vertices of the path may be input as %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 0.5 0.5 0.5 break 0.0 0.0 0.0 0.5 0.5 0.5 ... %endblock PHONON_FINE_KPOINT_PATH which traverses the directions between the vertices specified, except in the presence of the break keyword where the path jumps without including any intermediate points. The fineness of sampling along the path is set by an additional keyword phonon_fine_kpoint_path_spacing : 0.03 1/ang . As a final alternative, a simple list of points can be directly input to model any sampling you choose using %block PHONON_FINE_KPOINT_LIST 0.0 0.0 0.0 0.1 0.2 0.3 ... %endblock PHONON_FINE_KPOINT_LIST This is the approach used for files generated by Accelrys Materials Studio. The same keywords are used in the closely related method of a finite difference calculation; see the example .cell file of figure [al-sc-cell] . Continuation CASTEP stores the results of all phonon calculations - dynamical matrices and force constant matrices - in the binary seedname .check file written at the end of a successful run. This can be used to change some values of parameters relating to interpolation, and to change or indeed replace the entire fine phonon k-point set without any need to repeat the expensive DFPT (or supercell) part of the calculation. In fact a single calculation of the force constant matrix is sufficient to compute a DOS at a variety of sampling densities plus arbitrarily smooth dispersion curves. Setting up a continuation calculation is simple. Just add the continuation keyword in the usual way to a renamed copy of the param file continuation orig-seedname .check and make any changes to the fine phonon k-point sampling parameters in a copy of the seedname .cell file. It is recommended that you work with renamed copies to avoid overwriting the original and valuable seedname .check file. Running CASTEP on the new set of input files is exactly the same as running a new calculation, except that the result will be generated much more quickly. When setting up a continuation run, take care not to change the standard phonon k-point set, the electronic k-point set or any electronic structure parameters such as elec_energy_tol . If a mismatch is detected with the values stored in the checkpoint file, CASTEP will discard the saved dynamical matrix data and restart the full calculation from the beginning. Continuation calculations are also used in conjunction with checkpointing where a partially complete calculation is written to a file, also in .check format and which may be used to restart an interrupted calculation. See section [checkpointing] for a description. Control of interpolation scheme The final representation of the force constant matrix derived from the dynamical matrices is actually a periodic representation and is equivalent to the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a (fictitious) p \\times q \\times r p \\times q \\times r supercell. (See section [supercell] for more explanation.) CASTEP must determine a mapping between elements of the periodic dynamical matrix and aperiodic force constant matrix using a minimum-image convention for ionic site pairs and impose a cutoff scheme in real space to exclude (supercell-) periodic images. In fact CASTEP implements two distinct schemes. The cumulant scheme ( Parlinski, Li, and Kawazoe 1997 ) includes all image force constants with a suitable weighting to avoid multiple counting of images. This is achieved by including image force constants in any direction if they lie within half the distance to the nearest periodic repeat of the fictitious supercell lattice in that direction. If an atom-atom pair vector lies exactly half way to the supercell repeat so that image force constants occur, for example, at both \\mathbf{L} \\mathbf{L} and -\\mathbf{L} -\\mathbf{L} , all images at the same distance are included with a suitable weighting factor to preserve the symmetry of the cumulant force constant matrix. (See Refs. ( Parlinski, Li, and Kawazoe 1997 ) and ( Ye et al. 2004 ) for a more detailed explanation). This scheme is selected by specifying the param file keyword phonon_fine_cutoff_method CUMULANT and is in fact the default method in CASTEP. CASTEP also implements a simple spherical cutoff, controlled by the parameter R_c R_c and specified by parameter phonon_force_constant_cutoff 10.0 ang The value R_c R_c should be chosen to satisfy 2 R_c < min(p L_1,q L_2,r L_3) L 2 R_c < min(p L_1,q L_2,r L_3) L where L_n L_n is the cell edge of the simulation cell and p,q,r p,q,r are the (coarse) grid of phonon wavevectors. It is usually easiest to specify a value of zero, in which case CASTEP chooses the largest allowable value automatically. This scheme is most suitable for bulk materials of cubic symmetry. The spherical scheme is chosen using keyword phonon_fine_cutoff_method SPHERICAL . Within the default method a smaller cutoff volume can be decreased by a radius scaling factor, e.g. phonon_force_constant_cut_scale : 1.0 . This may be useful for testing the effect of long-ranged contributions to the IFC matrix. However any departure of this parameter\u2019s value from 1 does not preserve the superior convergence properties of the cumulant scheme and will in general require a larger supercell than the exact cumulant method. Acoustic Sum Rule correction The vibrational Hamiltonian is invariant to a uniform translation of the system in space. This symmetry is the origin of the well-known result that any crystal has three acoustic vibrational modes at {\\mathbf{q}}=0 {\\mathbf{q}}=0 with a frequency of zero. This leads to the so-called acoustic sum rule (or ASR) ( Ackland, Warren, and Clark 1997 ; Pick, Cohen, and Martin 1970 ) which has mathematical expressions for the force constant and \\Gamma \\Gamma -point dynamical matrices \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} In plane-wave calculations the translational invariance is broken as atoms translate with respect to the fixed FFT grid, so the sum rule is never exactly satisfied. Consequently it is sometimes observed even in an otherwise apparently very well converged calculation that the three acoustic modes at \\Gamma \\Gamma depart significantly from zero frequency. Depending on the XC functional 8 these frequencies may reach or exceed 50 cm ^{\\text{-1}} ^{\\text{-1}} . One solution is simply to increase number of grid points of CASTEP\u2019s \u201cfine\u201d FFT grid used for densities and potentials by increasing fine_grid_scale 9 . (N. B. This is distinct from grid_scale which controls the FFT grid used to represent wavefunctions.) However this can be very costly in computer time and memory. Provided that the amplitude of the symmetry violation is not too large, it is possible to apply a transformation to the computed dynamical or force constant matrix so that it exactly satisfies the ASR. CASTEP implements a scheme which projects out the acoustic mode eigenvectors and adjusts their frequency to zero, while having minimal impact on the optic mode frequencies. This scheme is controlled by parameters (in the .param file) phonon_sum_rule_method : REAL / RECIP / REAL-RECIP / NONE The first of these simply activates or deactivates the correction. The second chooses which of the variants of the ASR in equation [asr] to enforce, the real-space force constant matrix, the reciprocal-space dynamical matrix, or both. ( phonon_sum_rule_method : NONE is a synonym for phonon_sum_rule : FALSE ). The real-space method is only applicable to interpolation or supercell/finite displacement calculations, but the reciprocal-space method can be used for any type of phonon calculation. Both variants change the acoustic mode frequencies away from but near {\\mathbf{q}}=0 {\\mathbf{q}}=0 , the realspace method implicitly, and the reciprocal space method explicitly, by determining the correction to {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} and subtracting it from {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} as suggested by Gonze ( Gonze and Lee 1997 ). This usually results in acoustic mode behaviour which is indistinguishable from a very well converged calculation using a very fine FFT grid 10 . In addition to the sum rule on frequencies there is another for the Born effective charges (see section [efield] ) \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 which is activated by parameter born_charge_sum_rule : TRUE The default behaviour of CASTEP is that neither sum rule is enforced. If this was not requested in the original run, then it may be added in post-processing fashion in a continuation run, as per section [continuation] . Only the raw dynamical and/or force constant matrices are stored in the checkpoint file without the effect of ASR enforcement, which is only applied at the printout stage. Therefore the effect can be turned off, or altered by a post-processing calculation as well as turned on. Density of States The definition of the phonon density of states requires an integration of the calculated frequencies \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} over the Brillouin-Zone g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . A simple computational approximation would be to compute \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} on a regular, discrete grid of {\\mathbf{q}} {\\mathbf{q}} , replace the integral with a sum over the grid and convolute the result with some peak shape function h(\\omega) h(\\omega) such as a Gaussian g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . In the CASTEP toolset, this is implemented by performing a Fourier interpolation calculation onto a suitably fine {\\mathbf{q}} {\\mathbf{q}} -point set, specifying either phonon_fine_kpoint_mp_grid or phonon_fine_kpoint_mp_spacing . The resulting .phonon file may then be analysed using the dos.pl tool (see section [dos-pl] ) which implements equation [broadendos] . However the broadening smooths out any sharp features of the DOS, and fails to reproduce the smoothly-curved or sharply peaked segments typical of theoretical densities-of-states. This is discussed in more detail in references ( Yates et al. 2007 ) and ( Pickard 1997 ). A more faithful rendering may be obtained using the so-called adaptive broadening approach of Yates et. al ( Yates et al. 2007 ) which uses the gradients of the phonon branch dispersion to narrow or widen the broadening for flat or steep branches respectively. It is activated by the parameters keyword phonon_calculate_dos : TRUE which computes an adaptively-broadened DOS during the Fourier interpolation stage of the calculation and writes an output file named .phonon_dos containing the tabulated DOS, plus the per-atomic-species resolved DOS in additional columns. The dos.pl script is able to read and present .phonon_dos files just as with .phonon . The range and resolution may be modified using additional parameters, for example phonon_dos_spacing : 0.01 THz phonon_dos_limit : 10.0 THz Example output for the phonons of diamond is shown in figure [c2-pdos] . Figure 3 Phonon DOS for Diamond, with an 18^3 18^3 fine grid comparing Gaussian broadened (red) vs adaptively broadened (black) methods. Artefactual wiggles are clearly visible in the Gaussian-broadened case, and the height of the sharp peaks is not well reproduced. Finite Displacement In addition to the DFPT method of computing force constants, CASTEP implements schemes based on numerical differentiation of forces when atoms are displaced by a small amount from their equilibrium positions. This method is useful for cases where DFPT has not been implemented, which as of CASTEP release 24.1 includes ultrasoft pseudopotentials, Hubbard U and exact exchange and hybrid functionals, and some of the newer classes of dispersion correction. There are three variants of this scheme. Primitive Cell Finite Displacement The basic finite displacement method is selected by setting parameter phonon_method : FINITEDISPLACEMENT In contrast to DFPT such displacements are necessarily periodic with the simulation cell, and therefore only {\\mathbf{q}}=0 {\\mathbf{q}}=0 phonons are commensurate with this condition. As in the case of DFPT lattice dynamics the phonon wavevectors are specified by %block PHONON_KPOINT_LIST , %block PHONON_KPOINT_PATH or phonon_kpoint_mp_grid in the .cell file but only the \\Gamma \\Gamma point, (0,0,0) (0,0,0) is meaningful. CASTEP will print a warning in the output file and ignore any non-zero value in the list. CASTEP proceeds by shifting each atom by a small amount, then performing a SCF calculation to evaluate the forces on the perturbed configuration. Both positive and negative displacements are performed in each direction so that the corresponding force constants can be evaluated using the accurate \u201ccentral difference\u201d method of numerical differentiation. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. Equation [finite-diff] demonstrates that a single pair of displaced calculation yields an entire row of the dynamical matrix. As with DFPT calculations, only the minimal set of perturbations is performed and the space-group symmetry is used to build the complete dynamical matrix. The SCF calculations on the perturbed configuration are efficient, typically taking only only a few cycles in CASTEP 5.0 or later. This efficiency is achieved by first making a good guess for the electron density of the perturbed system based on the ground state of the unperturbed system, and applying a displacement of an atomic-like density of the pseudo-atom in question. Second, the SCF is started using the Kohn-Sham orbitals of the unperturbed state as the initial guess for the perturbed configuration. To exploit this efficiency it is essential to use the density-mixing (Davidson) minimiser, selected by elec_method : DM in the .param file. (As the all-bands method has no means of initialising the density). The default displacement used is 0.01 0.01 bohr This can be changed if necessary by setting a parameter, phonon_finite_disp : 0.02 ang in the .param file. Except for the differences discussed above, input and output formats are the same as for DFPT calculations. Born Charges, Permittivity and LO/TO splitting with FD FD phonon calculations are useful where atomic-displacement response DFPT is not implemented, notably for ultrasoft pseudopotentials (USPs) and post-DFT exchange and correlation including LDA+U, SOC, hybrid functionals (see table [captable] ). However properties including IR spectral intensity, LO/TO splitting and the effectiveness of Fourier interpolation of dynamical matrices depend on the Born effective charges and dielectric permittivity (see section [efield] ), whose calculation by electric field response DFPT is not implemented. In some cases it may be convenient to read in externally computed or approximate values of Born charges and permittivity to be used to calculate IR spectra, LO/TO splitting etc. For example, a DFT+U, meta-GGA, or hybrid calculation might make use of values calculated using PBE-DFPT and NCPs as a fair approximation, or even computed using a different DFT code. This may be accomplished by specifying the name of an external file containing the values (in this case BORN.DAT ) in the .param file %block DEVEL_CODE PHONON:READ_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE The file should be formatted as for the Phonopy code ( https://phonopy.github.io/phonopy/input-files.html#born-optional ). A file of this format may be written at the end of a DFT, NCP E-field response calculation by %block DEVEL_CODE PHONON:WRITE_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE Born charges from Berry Phase Polarization As of CASTEP release 25.1, it will be possible to calculate Born effective charges (but not dielectric permittivity) using a finite-difference numerical differentiation of the Berry-phase polarization. This is performed as an adjunct to the FD phonon calculation, and will be automatically selected in the case of an FD phonon calculation with USPs. This works for any compatible Hamiltonian, including DFT+U, mGGAs such as rSCAN as well as hybrid XC functionals. Finite Displacement using non-diagonal supercells As with the DFPT method, calculation of phonon dispersion and DOS using the finite displacement method is achieved using Fourier interpolation of dynamical matrixes. First, an approximation of the full force-constant-matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is calculated by explicitly computing a set of {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} with {\\mathbf{q}} {\\mathbf{q}} sampling a coarse grid of {\\mathbf{q}} {\\mathbf{q}} and using the inverse Fourier relation to equation [dmat] . Then equation [dmat] is used to generate the dynamical matrices at all of the (fine) phonon wavevectors required. The key step of computing every {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} on the \u201ccoarse\u201d regular grid is achieved by constructing a list of supercells commensurate with each of the coarse {\\mathbf{q}} {\\mathbf{q}} -points in turn (so that {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi where T_{\\text{SC}} T_{\\text{SC}} is a lattice vector of that supercell). This {\\mathbf{q}} {\\mathbf{q}} maps to a \\Gamma \\Gamma point calculation on the corresponding supercell despite being incommensurate with the primitive cell, and {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} for the primitive cell at {\\mathbf{q}} {\\mathbf{q}} may be extracted using equation [dmat] . It was shown by Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ) that by using so-called non-diagonal supercells such a set need contain only the least common multiple of the coarse grid subdivisions ( p, q, r p, q, r ). Consequently the number of distinct supercell calculations requires is much smaller than the number of {\\mathbf{q}} {\\mathbf{q}} -vectors of the grid, and most importantly increases with the linear dimension of the grid instead of the product. A non-diagonal supercell calculation is selected by setting the parameters phonon_method : FINITEDISPLACEMENT phonon_fine_method : INTERPOLATE , the cell keywords phonon_kpoint_mp_grid : p q r and one of the specifications of phonon_fine_kpoints exactly as in the case of a DFPT calculation. When the phonon calculation begins, CASTEP generates a list of supercells using the algorithm of Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ). For each of these, CASTEP generates the corresponding supercell and performs a finite-displacement phonon calculation. The dynamical matrices {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} are then extracted for each {\\mathbf{q}} {\\mathbf{q}} on the coarse KPOINT grid, and the calculation proceeds exactly as if the DFPT method has been used. The choice of coarse {\\mathbf{q}} {\\mathbf{q}} -point sampling set by phonon_kpoint_mp_grid requires one additional consideration compared to the DFPT case to give best computational performance. The supercell-generation algorithm of Lloyd Williams and Monserrat guarantees that the largest supercell in the generated list contains N_\\text{SC} = \\text{LCM} (p, q, r) N_\\text{SC} = \\text{LCM} (p, q, r) replications of the primitive cell. For example, an 4 \\times 4 \\times 4 4 \\times 4 \\times 4 sampling of a cubic cell gives N_\\text{SC} = 4 N_\\text{SC} = 4 . However a 2 \\times 3 \\times 4 2 \\times 3 \\times 4 sampling of an orthorhombic primitive cell yields N_\\text{SC} = 12 N_\\text{SC} = 12 , the LCM of 4 and 3. In that case it might be more efficient to use a 2 \\times 4 \\times 4 2 \\times 4 \\times 4 sampling which only requires N_\\text{SC} = 8 N_\\text{SC} = 8 for the largest of the generated supercells. As well as the {\\mathbf{q}} {\\mathbf{q}} -point sampling, FD interpolation calculations require one further parameter choice, namely to select the electronic k-point sampling for the supercell calculations. This may most conveniently be set using the cell keyword supercell_kpoint_mp_spacing : 0.1 1/ang . An explicit setting of grid sampling divisions with supercell_kpoint_mp_grid would be inappropriate as the correct choice will be different for each supercell, and unknown until run-time. By default CASTEP chooses a default spacing which is consistent with the primitive cell spacing, in an attempt to achieve a consistent level of convergence across supercells. Apart from the above two considerations, the setting up and execution of the FD interpolation follows exactly the same lines as with DFPT. In particular sum-rule, DOS and thermodynamics calculations and interpolation scheme tweaks apply identically. Legacy Finite Displacement/Supercell The limitation of the primitive-cell finite displacement approach to {\\mathbf{q}}=0 {\\mathbf{q}}=0 may also be overcome by combining the method with the use of a supercell. This method, sometimes known as the \u201cdirect method\u201d ( Kunc and Martin 1982, sec. 19.2 ) relies on the short-ranged decay of the force constant matrix with interatomic distance and makes the assumption that force constants for separations larger than some value, R_c R_c are negligibly small and can be treated as zero. A supercell can be constructed to contain an imaginary sphere of radius R_c R_c beyond which force constants may be neglected. Then the dynamical matrix of a supercell satisfying L > 2 R_{c} L > 2 R_{c} is identical to the force constant matrix , i.e. {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} . Therefore complete knowledge of the force constant matrix to a reasonable approximation may be derived from a single calculation of the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a supercell containing several primitive cells. From this set of force constants the dynamical matrices at any phonon wavevector may be computed using equation [dmat] in exactly the same way as used in an interpolation calculation. Note: This method is mostly superceded by the non-diagonal supercell/finite displacement approach of section [ndsc] . That method gives an equivalent calculation of the force constant matrix, usually with a smaller computational cost, because of its superior scaling with cell size. %block LATTICE_CART 0 2.02475 2.02475 2.02475 0 2.02475 2.02475 2.02475 0 %endblock LATTICE_CART %block POSITIONS_ABS Al 0 0 0 %endblock POSITIONS_ABS %block SPECIES_POT Al Al_00.usp %endblock SPECIES_POT kpoint_mp_grid 14 14 14 supercell_kpoint_mp_grid 2 2 2 symmetry_generate %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 1.0 1.0 1.0 0.5 0.5 0.5 0.5 0.5 0.0 0.5 0.75 0.25 0.5 0.5 0.5 %endblock PHONON_FINE_KPOINT_PATH %block PHONON_SUPERCELL_MATRIX -3 3 3 3 -3 3 3 3 -3 %endblock PHONON_SUPERCELL_MATRIX Figure 4 Example cell file for aluminium supercell phonon calculation. This calculation computes a set of dispersion curves along high-symmetry directions. Note that this calculation is not fully converged with supercell size - there is a noticeable change in frequency on some of the branches on increasing the supercell matrix entries from 3 to 4. task : PHONON phonon_fine_method : SUPERCELL phonon_calc_lo_to_splitting : FALSE phonon_sum_rule : TRUE calculate_born_charges : FALSE phonon_force_constant_ellipsoid : 1.0 cut_off_energy : 150 eV elec_method : DM smearing_width : 0.04 eV nextra_bands : 4 spin_polarized : FALSE opt_strategy : SPEED num_dump_cycles : 0 xc_functional : LDA Figure 5 Example param file for aluminium supercell phonon calculation. It is not strictly necessary to turn off the LO/TO splitting calculation - CASTEP will warn that this is not possible and turn it off anyway. The explicit request for a non-spin polarized calculation is necessary for fcc Al, because CASTEP chooses spin-polarized by default due to the odd number of electrons. In a CASTEP calculation the supercell must be chosen and explicitly specified in the input files. It is defined by a matrix, which multiplies the ordinary simulation cell vectors and is specified as a 3\\times3 3\\times3 matrix in the .cell file of the form %block PHONON_SUPERCELL_MATRIX 4 0 0 0 4 0 0 0 4 %endblock PHONON_SUPERCELL_MATRIX This typical example using a diagonal matrix creates a supercell expanded along each lattice vector a , b and c by factor of 4. The supercell to be used in a phonon calculation needs to be chosen with care. It must be large enough to contain a sphere of radius R_c R_c , the typical range of a force constant matrix. In a simple metal a value of R_c R_c as small as 6\u00c5 may be satisfactory, but more complex and structured systems will need a larger value 11 . In a covalent semiconductor the required R_c R_c may be 10\u00c5 or larger. However a supercell can quickly grow to generate a very large calculation indeed. For example a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 supercell of even a 2 atom primitive cell contains 128 atoms. Consequently it is rarely feasible to use this method on a uniprocessor or desktop computer, and a substantial parallel computer is usually required. The shape of the supercell should usually be as near cubic as possible, irrespective of the shape of the primitive cell, to optimise the supercell size/ R_c R_c ratio. This can be achieved using an off-diagonal supercell matrix, as in the example input files of figure [al-sc-cell] where a cubic supercell containing 108 atoms ( 3 \\times 4 = 12 3 \\times 4 = 12 unit cells) is generated from the rhombohedral primitive cell of aluminium containing a single atom. If the system is highly anisotropic, perhaps a slab model of a surface then a uniform supercell is clearly not appropriate and a suitable supercell must be designed from a consideration of the exact nature of the model. The electronic Brillouin-Zone integrals for the supercell calculation use the special k-points method, which are specified in the . cell file using an separate but analogous set of keywords to those pertaining to the primitive cell sampling. Specifically, %block SUPERCELL_KPOINT_LIST allows an exact specification of k-points and weights supercell_kpoint_mp_grid_spacing d chooses a Monkhorst-Pack grid with the specified spacing. supercell_kpoint_mp_grid p q r (and optionally supercell_kpoint_mp_offset ) allow an exact specification of a Monkhorst-Pack grid. Finally if no supercell kpoint keywords or blocks are given, a grid is chosen to generate a similar sampling density to the primitive cell calculation. Once the force constant matrix has been calculated using the supercell, the remainder of the lattice dynamics proceeds exactly as in the case of a Fourier interpolation calculation. The keywords controlling the interpolation scheme and cutoff radius, the fine phonon kpoint set and the acoustic sum rule enforcement work in exactly the same way. See section [interpolation-setup] for details. Convergence Phonon and dielectric response calculations give rise to a number of issues with convergence, in addition to those encountered in ground-state calculations, and a systematic and step-by-step approach is necessary to achieve well-converged results. CASTEP assists the user by setting default values for many convergence parameters based on the particular task which incorporate the experience of many calculations. Therefore it is a good practice not to specify convergence parameters explicitly unless specific convergence test results are known - otherwise a well-chosen default could be overridden with an untested value. (The example input of figure [example-gamma] contains no phonon-specific convergence parameters.) It was emphasised previously (section [geometry] ) that a well-converged geometry optimisation is a prerequisite for a phonon calculation. In turn this mandates a reasonably high level of convergence of plane-wave cutoff, SCF convergence and electronic k-point sampling. It is typical to run phonon calculations at a basis_precision : FINE level of plane-wave cutoff, (The header of each .usp or .recpot pseudopotential file contains a translation into eV units.) DFPT electric field response calculations can require finer electronic k-point sampling than suffices for a ground state calculation, so the effect of the kpoint_mp_grid on the dielectric permittivity should be tested. Convergence of DFPT solver The second stage of a phonon or E-field calculation is the variational DFPT solver, and there are a number of associated parameters to control the convergence. Parameters phonon_energy_tol 1.0e-5 eV/ang**2 and efield_energy_tol 1.0e-5 ang**3 govern the exit criterion for the DFPT self-consistency loop. The above default values are usually sufficient for frequencies converged to < 1 \\text{cm}^{-1} < 1 \\text{cm}^{-1} and permittivities to two or three decimal places and rarely need to be changed. However the converged results depend not only on the DFPT SCF calculation, but also, and rather strongly on the degree of convergence of the ground state electron density and wavefunctions. These enter the DFPT equations both directly and as a consequence of the orthogonality condition between ground-state and first-order response orbitals ( Refson, Tulip, and Clark 2006 ; Gonze and Lee 1997 ). To generate sufficiently accurate ground-state wavefunctions, the value of elec_energy_tol should be much lower than needed for an SCF or geometry optimuzation calculation. CASTEP sets a default value of roughly phonon_energy_tol squared and it is wise to rely on this and not to set elec_energy_tol explicitly in a phonon calculation. 12 Convergence of finite displacement forces The criteria for choosing the \u201cground-state\u201d convergence parameters for a finite-displacement phonon calculation (in either primitive or supercell mode) are naturally almost identical to those governing DFPT calculations. In this case there is no additional self-consistent electronic calculation; instead there is a sequence of additional ground-state calculations at displaced geometries. Finite-displacement calculations require very well converged forces to be computed in the ground state SCF calculation. This is because the numerical evaluation of the second derivative depends on differences between the (small) forces at perturbed configurations (equation [finite-diff] ). Clearly the numerical derivative has lower relative precision than the argument (the forces), which must therefore be evaluated to a rather high precision. Unlike the ground-state energy , which is variational with respect to the orbitals, the forces are not and the error in the forces is linear in the error in the orbitals. The main parameter governing their accuracy is again elec_energy_tol which is again set by default from the value of phonon_energy_tol ^2 ^2 . It is normally sufficient to use the default value of elec_energy_tol chosen as the default in a phonon calculation. However there is also a way of directly achieving the requested force tolerance, by setting parameter elec_force_tol 1e-3 eV/ang . This is not used by default as it adds some overhead to the SCF calculation resulting in longer run times. However it does guarantee that the forces really are converged to the required accuracy, unlike setting elec_energy_tol . Convergence of Interpolation and Supercell Fourier interpolation and supercell calculations add yet another criterion which must be satisfied to achieve well-converged results - the range of the force-constant matrix in real space. Sections [interpolation-setup] and [supercell] discuss some of the criteria applicable to these types of calculation. Unfortunately convergence testing of the size of the supercell for FD/supercell calculations can be prohibitively expensive as the the volume and number of atoms increase as the cube of the linear dimension under test. Consequently the CPU time will increase with the sixth power or higher! There is no easy solution to this problem and the reader is cautioned not to necessarily take on trust that FD/supercell phonon calculations published in the literature are fully converged! However some progress may be made by performing a calculation using the largest feasible supercell. If phonon_fine_cutoff_method : SPHERICAL is selected, it is then possible to vary the cutoff radius using parameter phonon_force_constant_CUTOFF to lower values than the maximum of half the largest box size. These tests may be performed using the \u201ccontinuation\u201d method (section [continuation] ) or the \u201cphonons\u201d utility (section [phonons-tool] ) without repeating the expensive supercell calculation. Another convergence test is automatically performed if the spherical cutoff method is selected. The frequencies resulting from the interpolation with the spherical cutoff are compared to those from an \u201cexact\u201d interpolation at wavevectors commensurate with the supercell. The results are written to the .castep file. This provides a quantitative measure of the interpolation error. A similar cutoff scaling test might be possible for the phonon_fine_cutoff_method : DEFAULT case, although it is considerably less useful. Parameter phonon_force_constant_cut_scale 0.9 will scale the range of the cutoff by the factor specified. However the default value of 1.0 is \u201cspecial\u201d in including constants separated by exactly half the supercell Wigner Seitz cell. Consequently convergence is not smooth in this parameter and while 0.95 might be underconverged, 1.0 could be very well converged. (This is also the reason for its superior convergence performance over the spherical cutoff scheme.) In general phonon wavevectors {\\mathbf{q}} {\\mathbf{q}} are specified using one of the variants of the phonon_kpoint_* cell keywords for lists, grids or paths. The example given uses a list of length 1 to specify a single point. \u21a9 This example will use the DFPT method which is the default if phonon_method is not present. \u21a9 Further optional output writing to .castep of the dynamical matrixes and force constant matrices is enabled at any iprint level by the parameters phonon_write_dynamical and phonon_write_force_constants respectively. \u21a9 The Placzek theory applies to the case of insulators only, and no general formulation to compute the activity for Raman scattering of conducting systems is available \u21a9 If the parameter raman_method : FINITEDISPLACEMENT is set the calculation uses an older, finite-difference implementation (see section [fd] ) to compute the mode displacement derivatives of the polarizability tensor (section [efield] ) using the approach of Porezag and Pedersen ( Porezag and Pederson 1996 ). The first stage is to perform a full phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 , to determine the mode eigenvectors and identify the Raman-active modes. Then CASTEP loops over the active modes only computing the Raman tensor, activity and depolarization for each. This method is deprecated as obsolete and computationally expensive. \u21a9 The offset may be specified as three fractions of the grid spacing, so 1/2p \\; 1/2q \\; 1/2r 1/2p \\; 1/2q \\; 1/2r shifts the grid exactly half a subdivision in each of the three directions. As of release 24.1 the INCLUDE_GAMMA keyword will automate this calculation and in fact is the default so that omitting phonon_kpoint_mp_offset entirely will do the right thing. \u21a9 The latter is governed by the effective range of electronic interactions which bears no relationship to the elastic range of the atomic displacements as required for the force constants. \u21a9 The effect is usually small for LDA, intermediate for PBE and largest for PW91, as the gradient terms are most sensitive to the ASR violation. \u21a9 (or fine_gmax or fine_cut_off_energy \u21a9 There is one known case where the reciprocal-space ASR correction fails to give the correct behaviour. Two-dimensional planar or layered systems with weak inter-layer bonding such as graphene or graphite exhibit a quadratic behaviour of an acoustic mode near \\Gamma \\Gamma . The reciprocal space scheme fails to reproduce the correct, quadratic behaviour and linearises the dispersion. The realspace method generates correct behaviour in these cases. \u21a9 A non-negligible force constant at longer range may also occur in a metallic system in the presence of a Kohn anomaly. \u21a9 Specifically, the error in the second-order energy or force constants is variational, and therefore depends quadratically on the error in the DFPT first-order response orbitals. However it is non-variational and linear with respect to the error in the ground-state orbitals. The practical consequence is that there is an error in DFPT results which varies as the square root of the ground-state convergence parameter elec_energy_tol which therefore must be very small for good accuracy. A heuristic rule of thumb is that elec_energy_tol \\approx \\approx phonon_energy_tol ^2 ^2 is necessary to converge the second order energy to the value of phonon_energy_tol . \u21a9","title":"Running-phonon-calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:dfpt-gamma","text":"Many of the principles of setting up and running phonon calculations can be illustrated in the simplest case - computing phonon frequencies at the q=(0,0,0) q=(0,0,0) , often referred to as the \\Gamma \\Gamma point. This is a very common calculation, as it forms the basis of modelling of infra-red or Raman spectra and group theoretical analysis and assignment of the modes.","title":"A DFPT phonon calculation at the \\Gamma\\Gamma-point"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:input-basic","text":"The setup for a CASTEP phonon calculation requires a few additional keywords in the seedname .cell file. Like any type of calculation, the unit cell must be specified using either of %block LATTICE_ABC or %block LATTICE_CART , and the atomic co-ordinates using %block POSITIONS_FRAC or %block POSITIONS_ABS . Figure [example-gamma] shows a complete input file for a calculation on boron nitride in the hexagonal Wurtzite structure. The additional keywords. phonon_kpoint_list is used to specify that a single phonon wavevector (0,0,0) is to be computed 1 . More wavevectors could be specified using additional lines in this block. 2 %block LATTICE_ABC 2.536000 2.536000 4.199000 ! a, b, c 90.000000 90.000000 120.000000 ! alpha, beta, gamma %endblock LATTICE_ABC %block POSITIONS_FRAC B 2/3 1/3 0.000000 ! Atom co-ordinates in crystallographic N 2/3 1/3 0.374536 ! fractional system. B 1/3 2/3 0.500000 N 1/3 2/3 0.874536 %endblock POSITIONS_FRAC %block SPECIES_POT B B_00.recpot ! File names of pseudopotential to use for B N N_00.recpot %endblock SPECIES_POT kpoints_mp_spacing 0.07 ! Generate MP grid of electronic k-points. symmetry_generate ! Find symmetry operations of crystal structure %block PHONON_KPOINT_LIST 0.0 0.0 0.0 1.0 ! Wavevector of phonon(s) to compute ( qx qy qz, weight) %endblock PHONON_KPOINT_LIST task : PHONON ! Choose a phonon calculation xc_functional : LDA opt_strategy : SPEED ! Optimise for speed over memory saving cut_off_energy : 700.0 eV ! Plane-wave cutoff for this system elec_method : DM ! Use fast DM solver even for insulating system phonon_sum_rule : TRUE ! Enforce acoustic sum rule on calculated D Figure 1: Annotated example cell and parameter files for BN in the Wurtzite structure. Note that phonon_method defaults to DFPT .","title":"Input files"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:output-gamma","text":"Figure [example-gamma-out] shows part of the phonon-relevant output extracted from the .castep file obtained by running the input files of the previous section. There are several blocks of output, one per direction chosen for {\\mathbf{q}}\\rightarrow 0 {\\mathbf{q}}\\rightarrow 0 in the LO-TO splitting terms. Note that CASTEP has added a calculation without LO-TO splitting (the first block), even though this was not explicitly requested. Within each block frequencies are listed one per line. Also on the line are (a) a label indicating the irreducible representation of the mode from a group theory analysis, (b) the computed absorptivity of the mode in a powder (or otherwise orientationally averaged) infrared experiment, \u00a9 whether the mode is IR active, (d) the Raman activity (if computed) and (e) whether the mode is Raman active. ============================================================================== + Vibrational Frequencies + + ----------------------- + + + + Performing frequency calculation at 1 wavevector (q-pt ) + + ========================================================================== + + + + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 1.0000000000 + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.049170 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1016.312039 a 28.5895083 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1051.124801 b 25.8079204 Y Y + + 12 1123.472590 d 0.0000000 N N + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + Figure 2 Output in the .castep file generated by the preceding input files for wurtzite BN. The columns show the mode frequencies, a letter labelling of the irreducible representation of the mode, the infrared absorptivity and Raman activity, and whether or not the mode is Raman and/or IR active. Not all of these are present in every calculation depending on the use of symmetry and input options. + -------------------------------------------------------------------------- + + q-pt= 1 ( 0.000000 0.000000 0.000000) 0.0000000000 + + q->0 along ( 0.000000 0.000000 1.000000) + + -------------------------------------------------------------------------- + + Acoustic sum rule correction < 8.094974 cm-1 applied + + N Frequency irrep. ir intensity active raman active + + (cm-1) ((D/A)**2/amu) + + + + 1 -0.037851 a 0.0000000 N N + + 2 -0.034768 b 0.0000000 N N + + 3 -0.034768 b 0.0000000 N N + + 4 475.116083 c 0.0000000 N Y + + 5 475.116083 c 0.0000000 N Y + + 6 952.000075 c 0.0000000 N Y + + 7 952.000075 c 0.0000000 N Y + + 8 963.032787 d 0.0000000 N N + + 9 1051.124801 b 25.8079204 Y Y + + 10 1051.124801 b 25.8079204 Y Y + + 11 1123.472590 d 0.0000000 N N + + 12 1262.933291 a 28.5895083 Y Y + + .......................................................................... + + Character table from group theory analysis of eigenvectors + + Point Group = 25, C6v + + (Due to LO/TO splitting this character table may not contain some symmetry + + operations of the full crystallographic point group. Additional + + representations may be also be present corresponding to split LO modes. + + A conventional analysis can be generated by specifying an additional null + + (all zero) field direction or one along any unique crystallographic axis + + in %BLOCK PHONON_GAMMA_DIRECTIONS in .cell.) + + .......................................................................... + + Rep Mul | E 6 3 2 m_v m_v + + | ------------------------ + + a A1 2 | 1 1 1 1 1 1 + + b E1 2 | 2 1 -1 -2 0 0 + + c E2 2 | 2 -1 -1 2 0 0 + + d B1 2 | 1 -1 1 -1 -1 1 + ============================================================================== Figure 2 Run output (continued): If the LO-TO-splitting calculation is active the \\Gamma \\Gamma point frequency table is repeated, both without and including the non-analytic contribution which generates the LO/TO splitting in one or more directions (See Gonze and Lee ( Gonze and Lee 1997 )). (The group theory analysis for LO modes is less useful than might be wanted and is likely to be the subject of future developments.) As with other calculations the amount of information written to the .castep file is controlled by the value of the parameter iprint . The levels of output are iprint : 0 Minimal output as in figure [example-gamma-out] . No progress info. iprint : 1 As for iprint : 0 but including a reassuring progress report of q-points and perturbations. iprint : 2 More detailed output including details of k-points and symmetry for each perturbation, cycle-by cycle DFPT minimiser report, printing of dynamical matrices (and force constant matrices). In addition to the user-readable output in the .castep file 3 , every phonon calculation generates an additional output file with the suffix .phonon which is intended for postprocessing analysis by other programs. This includes not only the frequencies but also the eigenvectors {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}} resulting from diagonalising the dynamical matrix. These eigenvectors are orthonormal and the relationship between the eigenvectors and atomic displacements is given by u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) u_{\\kappa,\\alpha,a} = \\frac{1}{\\sqrt{M_{\\kappa}}} Q_{m} {\\mathbf{\\varepsilon}_{m{\\kappa,\\alpha}{\\mathbf{q}}}}\\exp(i ({\\mathbf{q}}\\cdot {\\mathbf{R}}_{\\kappa,\\alpha}(a) - \\omega_m t)) where Q_M Q_M is the amplitude of mode m m and the other notation is as set out in the introduction.","title":"Reading the output"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:raman","text":"In addition to the infrared absorptivity computed as a default part of a \\Gamma \\Gamma -point phonon calculation, CASTEP is also capable of computing the Raman activity tensors in the case of non-resonant scattering for an insulating system 4 . This calculation uses an extension of DFPT known as the \u201c2n+1 theorem\u201d ( Baroni et al. 2001 ; Miwa 2011 ) which requires substantially more computational effort than a bare phonon calculation and is therefore not enabled by default. To compute Raman activity set calculate_raman : TRUE in the .param file, which calculates and prints the Raman atomic susceptibility tensors and the mode susceptibility tensors to the .castep file. These may be extracted for use when modelling the Raman scattering in a polarised single-crystal geometry. 5 As with the Born effective charges and dynamical matrices, there is a sum rule on the values of the atomic polar tensors, which may not be well satisfied because of numerical approximations. A correction will be applied if parameter raman_sum_rule : TRUE is set. A 3d-average Raman activity (see Porezag and Pedersen ( Porezag and Pederson 1996 )) is computed from the susceptibility tensors and printed as an additional column in the usual frequency output given in figure [example-gamma-out] . This may be used for simple modelling of a powder spectrum, for example using the dos.pl tool (see section [dos-pl] ).","title":"Raman activity calculations"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:ddos","text":"Phonons of a nonzero wavevector play an important role in the thermophysical properties of crystalline solids and the physics of many solid-state phase transitions. Proving the mechanical stability of a crystal structure by testing for real frequencies requires a vibrational calculation over the full Brillouin Zone. And dispersion curves and densities of states are frequently required for comparison with inelastic neutron and X-ray scattering experiments. One of the benefits of density functional perturbation theory is that CASTEP can calculate vibrational modes at {\\mathbf{q}}\\ne \\mathbf{0} {\\mathbf{q}}\\ne \\mathbf{0} as easily as at {\\mathbf{q}}= \\mathbf{0} {\\mathbf{q}}= \\mathbf{0} (but at the cost of an increase in CPU time due to the decreased symmetry). It is possible to perform this calculation simply by providing a list of q-points in the .cell file ( using one of the blocks %block PHONON_KPOINT_LIST , or %block PHONON_KPOINT_PATH or keyword phonon_kpoint_mp_grid ). However to generate a reasonable quality dispersion plot or density of states will usually require hundreds or thousands of q-points. The time required by such a calculation would be several hundred times that for a single-point energy and therefore infeasibly large. Fortunately there is a way to achieve the same result at a far smaller computational cost. This method exploits the fact that the interatomic interactions in a solid have a finite range and decay rapidly to zero. Specifically, the elements of the force constant matrix in Eq. [fcmat] decrease as 1 / r^{5} 1 / r^{5} with interatomic distance. Consequently the dynamical matrix defined by Eq. [dmat] and its eigenvalues \\omega^{2}({\\mathbf{q}}) \\omega^{2}({\\mathbf{q}}) are smoothly varying with wavevector {\\mathbf{q}} {\\mathbf{q}} . Fourier interpolation is used to generate dynamical matrices on an arbitrarily fine grid or linear path in reciprocal space from a set of DFPT calculations on a much coarser grid. For a full description of the method see references ( Baroni et al. 2001 ; Giannozzi et al. 1991 ; Gonze and Lee 1997 ). A complication arises in the case of polar solids where the dipole-dipole interaction generated upon displacing an atom leads to a longer ranged force constant matrix which decays only as 1 / r^{3} 1 / r^{3} . CASTEP models this term analytically using Born effective charges and dielectric permittivity calculated using an electric field response DFPT calculation (see section [efield] and Ref. ( Gonze and Lee 1997 )). It is therefore able to perform the Fourier interpolation for only the part of the force constant matrix which varies as 1 / r^{5} 1 / r^{5} , and does not require a finer grid than in the case of non-polar solids.","title":"Dispersion and density of states"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:interpolation-setup","text":"In the .cell file choose the q-points of the coarse grid of points at which to perform DFPT calculations. This may be specified as a %block PHONON_KPOINT_LIST containing the reduced set of points in the irreducible Brillouin Zone, but is is almost always more straightforward to use the alternative keywords phonon_kpoint_mp_grid : p q r phonon_kpoint_mp_offset : INCLUDE_GAMMA to specify the grid parameters and offset 6 . The grid parameters p , q and r should normally be chosen to give a roughly uniform sampling of reciprocal space taking length of the reciprocal lattice vectors into account, and should be compatible with the symmetry of the simulation cell. Alternatively a grid may be specified using the minimum spacing, for example phonon_kpoint_mp_grid_spacing 0.1 1/ang Normally the grid should be chosen to contain the \\Gamma \\Gamma point, which usually gives better convergence properties of the interpolation ( i.e.*convergence at smaller *p,q,r ) than otherwise. This is the opposite behaviour to electronic k-point sampling (see Ref. ( Probert and Payne 2003 )). The special keyword value phonon_kpoint_mp_offset : INCLUDE_GAMMA avoids the need to work out the offset explicitly. The choice of grid parameters p , q and r is governed by three considerations: For a 3-dimensional crystal, p,q,r should obey the crystallographic symmetry , so for a cubic or rhombohedral crystal you should set p = q = r p = q = r . In the case of a uniaxial crystal, such as tetragonal or hexagonal we have p = q \\neq r p = q \\neq r (assuming that c c is the unique axis) and for lower symmetry there is no constraint. The value in any of the directions limits the range of the force constant matrix in much the same way as the supercell multiplier does in a finite-difference/supercell calculation (Section [supercell] ). Exactly how large this should be depends on the nature of the chemical bonding. Ionically bonded systems tend to have fairly short-ranged force-constant matrices and need relatively coarse grids for convergence. For sodium chloride in the rocksalt structure with a primitive lattice parameter 3.75\u00c5 a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 grid is reasonably close to convergence. This corresponds to a truncation of the force constant matrix at a distance of approximately 7 7 \u00c5 ( \\approx p \\times 2 \\pi / a \\approx p \\times 2 \\pi / a ). On the other hand covalent systems tend to have fairly long-ranged force-constant matrices and need finer grids for convergence. Silicon is a good example of this. The primitive lattice parameter is similar to sodium chloride at 3.81 3.81 \u00c5, but the dispersion curve is not fully converged until an 8 \\times 8 \\times 8 8 \\times 8 \\times 8 grid is used. A more detailed examination of this point may be found in reference ( Ackland, Warren, and Clark 1997 ). While there is no essential physics relationship between the grid sizes for phonon {\\mathbf{q}} {\\mathbf{q}} -points and that required for electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling 7 , there is a technical connection resulting from the implementation of density-functional perturbation theory and the requirement to generate and use ground-state Kohn-Sham wavefunctions on grids containing both \\{{\\mathbf{k}}\\} \\{{\\mathbf{k}}\\} and \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} \\{{\\mathbf{k}}+ {\\mathbf{q}}\\} (See ref. ( Gonze 1997 ) for the mathematical details). For best performance and stability of the DFPT calculation the phonon grid parameters should be commensurate with the electronic grid with an exact divisor as the simplest case. For example, in an elemental metal with an hcp structure such as Mg, an electronic {\\mathbf{k}} {\\mathbf{k}} -point sampling of 21 \\times 21 \\times 12 21 \\times 21 \\times 12 and a phonon {\\mathbf{q}} {\\mathbf{q}} -point sampling of 7 \\times 7 \\times 6 7 \\times 7 \\times 6 might be most effective. This is not a hard requirement and CASTEP will attempt to work with whatever grids are specified, but in some cases there may be a performance advantage to rounding up one or other of the grids to meet the commensurability criterion. Additional keywords in the .param file control the interpolation. Most importantly phonon_fine_method : INTERPOLATE instructs CASTEP to perform the Fourier interpolation step following the usual DFPT calculation. The target set of wavevectors for the interpolation is set up using additional keywords or blocks in the .cell file. Either phonon_fine_kpoint_mp_grid p q r phonon_fine_kpoint_mp_offset o _1 _1 o _2 _2 o _3 _3 or phonon_fine_kpoint_mp_spacing 0.03 1/ang . will perform interpolation onto a regular (possibly offset) grid. In fact only the points in the irreducible wedge of the Brillouin Zone are included, and a suitable weight is computed so that the weighted average is identical to a uniform sampling of the BZ. This is the usual method for computing a phonon density of states. If a set of dispersion curves along high symmetry directions is required, an empty cell keyword block %block PHONON_FINE_KPOINT_PATH %endblock PHONON_FINE_KPOINT_PATH will internally generate a list of {\\mathbf{q}} {\\mathbf{q}} -points sampling a default path through the Brillouin-Zone according to the symmetry of the calculation. Alternatively a list of {\\mathbf{q}} {\\mathbf{q}} -points explicitly specifying the vertices of the path may be input as %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 0.5 0.5 0.5 break 0.0 0.0 0.0 0.5 0.5 0.5 ... %endblock PHONON_FINE_KPOINT_PATH which traverses the directions between the vertices specified, except in the presence of the break keyword where the path jumps without including any intermediate points. The fineness of sampling along the path is set by an additional keyword phonon_fine_kpoint_path_spacing : 0.03 1/ang . As a final alternative, a simple list of points can be directly input to model any sampling you choose using %block PHONON_FINE_KPOINT_LIST 0.0 0.0 0.0 0.1 0.2 0.3 ... %endblock PHONON_FINE_KPOINT_LIST This is the approach used for files generated by Accelrys Materials Studio. The same keywords are used in the closely related method of a finite difference calculation; see the example .cell file of figure [al-sc-cell] .","title":"Setting up an interpolation calculation"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:continuation","text":"CASTEP stores the results of all phonon calculations - dynamical matrices and force constant matrices - in the binary seedname .check file written at the end of a successful run. This can be used to change some values of parameters relating to interpolation, and to change or indeed replace the entire fine phonon k-point set without any need to repeat the expensive DFPT (or supercell) part of the calculation. In fact a single calculation of the force constant matrix is sufficient to compute a DOS at a variety of sampling densities plus arbitrarily smooth dispersion curves. Setting up a continuation calculation is simple. Just add the continuation keyword in the usual way to a renamed copy of the param file continuation orig-seedname .check and make any changes to the fine phonon k-point sampling parameters in a copy of the seedname .cell file. It is recommended that you work with renamed copies to avoid overwriting the original and valuable seedname .check file. Running CASTEP on the new set of input files is exactly the same as running a new calculation, except that the result will be generated much more quickly. When setting up a continuation run, take care not to change the standard phonon k-point set, the electronic k-point set or any electronic structure parameters such as elec_energy_tol . If a mismatch is detected with the values stored in the checkpoint file, CASTEP will discard the saved dynamical matrix data and restart the full calculation from the beginning. Continuation calculations are also used in conjunction with checkpointing where a partially complete calculation is written to a file, also in .check format and which may be used to restart an interrupted calculation. See section [checkpointing] for a description.","title":"Continuation"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:interpolation-control","text":"The final representation of the force constant matrix derived from the dynamical matrices is actually a periodic representation and is equivalent to the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a (fictitious) p \\times q \\times r p \\times q \\times r supercell. (See section [supercell] for more explanation.) CASTEP must determine a mapping between elements of the periodic dynamical matrix and aperiodic force constant matrix using a minimum-image convention for ionic site pairs and impose a cutoff scheme in real space to exclude (supercell-) periodic images. In fact CASTEP implements two distinct schemes. The cumulant scheme ( Parlinski, Li, and Kawazoe 1997 ) includes all image force constants with a suitable weighting to avoid multiple counting of images. This is achieved by including image force constants in any direction if they lie within half the distance to the nearest periodic repeat of the fictitious supercell lattice in that direction. If an atom-atom pair vector lies exactly half way to the supercell repeat so that image force constants occur, for example, at both \\mathbf{L} \\mathbf{L} and -\\mathbf{L} -\\mathbf{L} , all images at the same distance are included with a suitable weighting factor to preserve the symmetry of the cumulant force constant matrix. (See Refs. ( Parlinski, Li, and Kawazoe 1997 ) and ( Ye et al. 2004 ) for a more detailed explanation). This scheme is selected by specifying the param file keyword phonon_fine_cutoff_method CUMULANT and is in fact the default method in CASTEP. CASTEP also implements a simple spherical cutoff, controlled by the parameter R_c R_c and specified by parameter phonon_force_constant_cutoff 10.0 ang The value R_c R_c should be chosen to satisfy 2 R_c < min(p L_1,q L_2,r L_3) L 2 R_c < min(p L_1,q L_2,r L_3) L where L_n L_n is the cell edge of the simulation cell and p,q,r p,q,r are the (coarse) grid of phonon wavevectors. It is usually easiest to specify a value of zero, in which case CASTEP chooses the largest allowable value automatically. This scheme is most suitable for bulk materials of cubic symmetry. The spherical scheme is chosen using keyword phonon_fine_cutoff_method SPHERICAL . Within the default method a smaller cutoff volume can be decreased by a radius scaling factor, e.g. phonon_force_constant_cut_scale : 1.0 . This may be useful for testing the effect of long-ranged contributions to the IFC matrix. However any departure of this parameter\u2019s value from 1 does not preserve the superior convergence properties of the cumulant scheme and will in general require a larger supercell than the exact cumulant method.","title":"Control of interpolation scheme"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:asr","text":"The vibrational Hamiltonian is invariant to a uniform translation of the system in space. This symmetry is the origin of the well-known result that any crystal has three acoustic vibrational modes at {\\mathbf{q}}=0 {\\mathbf{q}}=0 with a frequency of zero. This leads to the so-called acoustic sum rule (or ASR) ( Ackland, Warren, and Clark 1997 ; Pick, Cohen, and Martin 1970 ) which has mathematical expressions for the force constant and \\Gamma \\Gamma -point dynamical matrices \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} \\begin{aligned} \\sum_{\\kappa,a} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(a)}&= 0\\\\ \\sum_{\\kappa} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}&= 0 \\end{aligned} In plane-wave calculations the translational invariance is broken as atoms translate with respect to the fixed FFT grid, so the sum rule is never exactly satisfied. Consequently it is sometimes observed even in an otherwise apparently very well converged calculation that the three acoustic modes at \\Gamma \\Gamma depart significantly from zero frequency. Depending on the XC functional 8 these frequencies may reach or exceed 50 cm ^{\\text{-1}} ^{\\text{-1}} . One solution is simply to increase number of grid points of CASTEP\u2019s \u201cfine\u201d FFT grid used for densities and potentials by increasing fine_grid_scale 9 . (N. B. This is distinct from grid_scale which controls the FFT grid used to represent wavefunctions.) However this can be very costly in computer time and memory. Provided that the amplitude of the symmetry violation is not too large, it is possible to apply a transformation to the computed dynamical or force constant matrix so that it exactly satisfies the ASR. CASTEP implements a scheme which projects out the acoustic mode eigenvectors and adjusts their frequency to zero, while having minimal impact on the optic mode frequencies. This scheme is controlled by parameters (in the .param file) phonon_sum_rule_method : REAL / RECIP / REAL-RECIP / NONE The first of these simply activates or deactivates the correction. The second chooses which of the variants of the ASR in equation [asr] to enforce, the real-space force constant matrix, the reciprocal-space dynamical matrix, or both. ( phonon_sum_rule_method : NONE is a synonym for phonon_sum_rule : FALSE ). The real-space method is only applicable to interpolation or supercell/finite displacement calculations, but the reciprocal-space method can be used for any type of phonon calculation. Both variants change the acoustic mode frequencies away from but near {\\mathbf{q}}=0 {\\mathbf{q}}=0 , the realspace method implicitly, and the reciprocal space method explicitly, by determining the correction to {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)} and subtracting it from {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} as suggested by Gonze ( Gonze and Lee 1997 ). This usually results in acoustic mode behaviour which is indistinguishable from a very well converged calculation using a very fine FFT grid 10 . In addition to the sum rule on frequencies there is another for the Born effective charges (see section [efield] ) \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 \\sum_{\\kappa} {Z^{*}_{\\kappa,\\beta,\\alpha} }= 0 which is activated by parameter born_charge_sum_rule : TRUE The default behaviour of CASTEP is that neither sum rule is enforced. If this was not requested in the original run, then it may be added in post-processing fashion in a continuation run, as per section [continuation] . Only the raw dynamical and/or force constant matrices are stored in the checkpoint file without the effect of ASR enforcement, which is only applied at the printout stage. Therefore the effect can be turned off, or altered by a post-processing calculation as well as turned on.","title":"Acoustic Sum Rule correction"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#density-of-states","text":"The definition of the phonon density of states requires an integration of the calculated frequencies \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} over the Brillouin-Zone g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . g(\\omega) = \\int_{\\text{BZ}}d^3{\\mathbf{q}}\\sum_i \\delta(\\omega - \\omega_{i{\\mathbf{q}}}) . A simple computational approximation would be to compute \\omega_{i{\\mathbf{q}}} \\omega_{i{\\mathbf{q}}} on a regular, discrete grid of {\\mathbf{q}} {\\mathbf{q}} , replace the integral with a sum over the grid and convolute the result with some peak shape function h(\\omega) h(\\omega) such as a Gaussian g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . g(\\omega) \\approx \\int d\\omega^{\\prime} h(\\omega - \\omega^{\\prime}) \\sum_{{\\mathbf{q}}} \\sum_i \\delta(\\omega^{\\prime} - \\omega_{i{\\mathbf{q}}}) . In the CASTEP toolset, this is implemented by performing a Fourier interpolation calculation onto a suitably fine {\\mathbf{q}} {\\mathbf{q}} -point set, specifying either phonon_fine_kpoint_mp_grid or phonon_fine_kpoint_mp_spacing . The resulting .phonon file may then be analysed using the dos.pl tool (see section [dos-pl] ) which implements equation [broadendos] . However the broadening smooths out any sharp features of the DOS, and fails to reproduce the smoothly-curved or sharply peaked segments typical of theoretical densities-of-states. This is discussed in more detail in references ( Yates et al. 2007 ) and ( Pickard 1997 ). A more faithful rendering may be obtained using the so-called adaptive broadening approach of Yates et. al ( Yates et al. 2007 ) which uses the gradients of the phonon branch dispersion to narrow or widen the broadening for flat or steep branches respectively. It is activated by the parameters keyword phonon_calculate_dos : TRUE which computes an adaptively-broadened DOS during the Fourier interpolation stage of the calculation and writes an output file named .phonon_dos containing the tabulated DOS, plus the per-atomic-species resolved DOS in additional columns. The dos.pl script is able to read and present .phonon_dos files just as with .phonon . The range and resolution may be modified using additional parameters, for example phonon_dos_spacing : 0.01 THz phonon_dos_limit : 10.0 THz Example output for the phonons of diamond is shown in figure [c2-pdos] . Figure 3 Phonon DOS for Diamond, with an 18^3 18^3 fine grid comparing Gaussian broadened (red) vs adaptively broadened (black) methods. Artefactual wiggles are clearly visible in the Gaussian-broadened case, and the height of the sharp peaks is not well reproduced.","title":"Density of States"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:fd","text":"In addition to the DFPT method of computing force constants, CASTEP implements schemes based on numerical differentiation of forces when atoms are displaced by a small amount from their equilibrium positions. This method is useful for cases where DFPT has not been implemented, which as of CASTEP release 24.1 includes ultrasoft pseudopotentials, Hubbard U and exact exchange and hybrid functionals, and some of the newer classes of dispersion correction. There are three variants of this scheme.","title":"Finite Displacement"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#primitive-cell-finite-displacement","text":"The basic finite displacement method is selected by setting parameter phonon_method : FINITEDISPLACEMENT In contrast to DFPT such displacements are necessarily periodic with the simulation cell, and therefore only {\\mathbf{q}}=0 {\\mathbf{q}}=0 phonons are commensurate with this condition. As in the case of DFPT lattice dynamics the phonon wavevectors are specified by %block PHONON_KPOINT_LIST , %block PHONON_KPOINT_PATH or phonon_kpoint_mp_grid in the .cell file but only the \\Gamma \\Gamma point, (0,0,0) (0,0,0) is meaningful. CASTEP will print a warning in the output file and ignore any non-zero value in the list. CASTEP proceeds by shifting each atom by a small amount, then performing a SCF calculation to evaluate the forces on the perturbed configuration. Both positive and negative displacements are performed in each direction so that the corresponding force constants can be evaluated using the accurate \u201ccentral difference\u201d method of numerical differentiation. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. \\frac{d^{2} E_{0}}{d u_{\\kappa,\\alpha} d u_{\\kappa^{\\prime},\\alpha^{\\prime}}} = \\frac{d F_{\\kappa,\\alpha}}{d u} \\approx \\frac{F^{+}_{\\kappa,\\alpha} - F^{-}_{\\kappa,\\alpha}}{2 u} \\;. Equation [finite-diff] demonstrates that a single pair of displaced calculation yields an entire row of the dynamical matrix. As with DFPT calculations, only the minimal set of perturbations is performed and the space-group symmetry is used to build the complete dynamical matrix. The SCF calculations on the perturbed configuration are efficient, typically taking only only a few cycles in CASTEP 5.0 or later. This efficiency is achieved by first making a good guess for the electron density of the perturbed system based on the ground state of the unperturbed system, and applying a displacement of an atomic-like density of the pseudo-atom in question. Second, the SCF is started using the Kohn-Sham orbitals of the unperturbed state as the initial guess for the perturbed configuration. To exploit this efficiency it is essential to use the density-mixing (Davidson) minimiser, selected by elec_method : DM in the .param file. (As the all-bands method has no means of initialising the density). The default displacement used is 0.01 0.01 bohr This can be changed if necessary by setting a parameter, phonon_finite_disp : 0.02 ang in the .param file. Except for the differences discussed above, input and output formats are the same as for DFPT calculations.","title":"Primitive Cell Finite Displacement"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#born-charges-permittivity-and-loto-splitting-with-fd","text":"FD phonon calculations are useful where atomic-displacement response DFPT is not implemented, notably for ultrasoft pseudopotentials (USPs) and post-DFT exchange and correlation including LDA+U, SOC, hybrid functionals (see table [captable] ). However properties including IR spectral intensity, LO/TO splitting and the effectiveness of Fourier interpolation of dynamical matrices depend on the Born effective charges and dielectric permittivity (see section [efield] ), whose calculation by electric field response DFPT is not implemented. In some cases it may be convenient to read in externally computed or approximate values of Born charges and permittivity to be used to calculate IR spectra, LO/TO splitting etc. For example, a DFT+U, meta-GGA, or hybrid calculation might make use of values calculated using PBE-DFPT and NCPs as a fair approximation, or even computed using a different DFT code. This may be accomplished by specifying the name of an external file containing the values (in this case BORN.DAT ) in the .param file %block DEVEL_CODE PHONON:READ_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE The file should be formatted as for the Phonopy code ( https://phonopy.github.io/phonopy/input-files.html#born-optional ). A file of this format may be written at the end of a DFT, NCP E-field response calculation by %block DEVEL_CODE PHONON:WRITE_EXTERNAL_BORN=BORN.DAT:ENDPHONON %endblock DEVEL_CODE","title":"Born Charges, Permittivity and LO/TO splitting with FD"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:berry-fd","text":"As of CASTEP release 25.1, it will be possible to calculate Born effective charges (but not dielectric permittivity) using a finite-difference numerical differentiation of the Berry-phase polarization. This is performed as an adjunct to the FD phonon calculation, and will be automatically selected in the case of an FD phonon calculation with USPs. This works for any compatible Hamiltonian, including DFT+U, mGGAs such as rSCAN as well as hybrid XC functionals.","title":"Born charges from Berry Phase Polarization"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:ndsc","text":"As with the DFPT method, calculation of phonon dispersion and DOS using the finite displacement method is achieved using Fourier interpolation of dynamical matrixes. First, an approximation of the full force-constant-matrix {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} is calculated by explicitly computing a set of {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} with {\\mathbf{q}} {\\mathbf{q}} sampling a coarse grid of {\\mathbf{q}} {\\mathbf{q}} and using the inverse Fourier relation to equation [dmat] . Then equation [dmat] is used to generate the dynamical matrices at all of the (fine) phonon wavevectors required. The key step of computing every {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} on the \u201ccoarse\u201d regular grid is achieved by constructing a list of supercells commensurate with each of the coarse {\\mathbf{q}} {\\mathbf{q}} -points in turn (so that {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi {\\mathbf{q}}\\cdot T_{\\text{SC}} = 2 n \\pi where T_{\\text{SC}} T_{\\text{SC}} is a lattice vector of that supercell). This {\\mathbf{q}} {\\mathbf{q}} maps to a \\Gamma \\Gamma point calculation on the corresponding supercell despite being incommensurate with the primitive cell, and {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} for the primitive cell at {\\mathbf{q}} {\\mathbf{q}} may be extracted using equation [dmat] . It was shown by Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ) that by using so-called non-diagonal supercells such a set need contain only the least common multiple of the coarse grid subdivisions ( p, q, r p, q, r ). Consequently the number of distinct supercell calculations requires is much smaller than the number of {\\mathbf{q}} {\\mathbf{q}} -vectors of the grid, and most importantly increases with the linear dimension of the grid instead of the product. A non-diagonal supercell calculation is selected by setting the parameters phonon_method : FINITEDISPLACEMENT phonon_fine_method : INTERPOLATE , the cell keywords phonon_kpoint_mp_grid : p q r and one of the specifications of phonon_fine_kpoints exactly as in the case of a DFPT calculation. When the phonon calculation begins, CASTEP generates a list of supercells using the algorithm of Lloyd-Williams and Monserrat ( Lloyd-Williams and Monserrat 2015 ). For each of these, CASTEP generates the corresponding supercell and performs a finite-displacement phonon calculation. The dynamical matrices {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} {D^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q})} are then extracted for each {\\mathbf{q}} {\\mathbf{q}} on the coarse KPOINT grid, and the calculation proceeds exactly as if the DFPT method has been used. The choice of coarse {\\mathbf{q}} {\\mathbf{q}} -point sampling set by phonon_kpoint_mp_grid requires one additional consideration compared to the DFPT case to give best computational performance. The supercell-generation algorithm of Lloyd Williams and Monserrat guarantees that the largest supercell in the generated list contains N_\\text{SC} = \\text{LCM} (p, q, r) N_\\text{SC} = \\text{LCM} (p, q, r) replications of the primitive cell. For example, an 4 \\times 4 \\times 4 4 \\times 4 \\times 4 sampling of a cubic cell gives N_\\text{SC} = 4 N_\\text{SC} = 4 . However a 2 \\times 3 \\times 4 2 \\times 3 \\times 4 sampling of an orthorhombic primitive cell yields N_\\text{SC} = 12 N_\\text{SC} = 12 , the LCM of 4 and 3. In that case it might be more efficient to use a 2 \\times 4 \\times 4 2 \\times 4 \\times 4 sampling which only requires N_\\text{SC} = 8 N_\\text{SC} = 8 for the largest of the generated supercells. As well as the {\\mathbf{q}} {\\mathbf{q}} -point sampling, FD interpolation calculations require one further parameter choice, namely to select the electronic k-point sampling for the supercell calculations. This may most conveniently be set using the cell keyword supercell_kpoint_mp_spacing : 0.1 1/ang . An explicit setting of grid sampling divisions with supercell_kpoint_mp_grid would be inappropriate as the correct choice will be different for each supercell, and unknown until run-time. By default CASTEP chooses a default spacing which is consistent with the primitive cell spacing, in an attempt to achieve a consistent level of convergence across supercells. Apart from the above two considerations, the setting up and execution of the FD interpolation follows exactly the same lines as with DFPT. In particular sum-rule, DOS and thermodynamics calculations and interpolation scheme tweaks apply identically.","title":"Finite Displacement using non-diagonal supercells"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:supercell","text":"The limitation of the primitive-cell finite displacement approach to {\\mathbf{q}}=0 {\\mathbf{q}}=0 may also be overcome by combining the method with the use of a supercell. This method, sometimes known as the \u201cdirect method\u201d ( Kunc and Martin 1982, sec. 19.2 ) relies on the short-ranged decay of the force constant matrix with interatomic distance and makes the assumption that force constants for separations larger than some value, R_c R_c are negligibly small and can be treated as zero. A supercell can be constructed to contain an imaginary sphere of radius R_c R_c beyond which force constants may be neglected. Then the dynamical matrix of a supercell satisfying L > 2 R_{c} L > 2 R_{c} is identical to the force constant matrix , i.e. {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} {C^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}(\\mathbf{q}=0)}= {\\Phi^{\\kappa,\\kappa^\\prime}_{\\alpha,\\alpha^\\prime}} . Therefore complete knowledge of the force constant matrix to a reasonable approximation may be derived from a single calculation of the {\\mathbf{q}}=0 {\\mathbf{q}}=0 dynamical matrix of a supercell containing several primitive cells. From this set of force constants the dynamical matrices at any phonon wavevector may be computed using equation [dmat] in exactly the same way as used in an interpolation calculation. Note: This method is mostly superceded by the non-diagonal supercell/finite displacement approach of section [ndsc] . That method gives an equivalent calculation of the force constant matrix, usually with a smaller computational cost, because of its superior scaling with cell size. %block LATTICE_CART 0 2.02475 2.02475 2.02475 0 2.02475 2.02475 2.02475 0 %endblock LATTICE_CART %block POSITIONS_ABS Al 0 0 0 %endblock POSITIONS_ABS %block SPECIES_POT Al Al_00.usp %endblock SPECIES_POT kpoint_mp_grid 14 14 14 supercell_kpoint_mp_grid 2 2 2 symmetry_generate %block PHONON_FINE_KPOINT_PATH 0.0 0.0 0.0 0.5 0.5 0.0 1.0 1.0 1.0 0.5 0.5 0.5 0.5 0.5 0.0 0.5 0.75 0.25 0.5 0.5 0.5 %endblock PHONON_FINE_KPOINT_PATH %block PHONON_SUPERCELL_MATRIX -3 3 3 3 -3 3 3 3 -3 %endblock PHONON_SUPERCELL_MATRIX Figure 4 Example cell file for aluminium supercell phonon calculation. This calculation computes a set of dispersion curves along high-symmetry directions. Note that this calculation is not fully converged with supercell size - there is a noticeable change in frequency on some of the branches on increasing the supercell matrix entries from 3 to 4. task : PHONON phonon_fine_method : SUPERCELL phonon_calc_lo_to_splitting : FALSE phonon_sum_rule : TRUE calculate_born_charges : FALSE phonon_force_constant_ellipsoid : 1.0 cut_off_energy : 150 eV elec_method : DM smearing_width : 0.04 eV nextra_bands : 4 spin_polarized : FALSE opt_strategy : SPEED num_dump_cycles : 0 xc_functional : LDA Figure 5 Example param file for aluminium supercell phonon calculation. It is not strictly necessary to turn off the LO/TO splitting calculation - CASTEP will warn that this is not possible and turn it off anyway. The explicit request for a non-spin polarized calculation is necessary for fcc Al, because CASTEP chooses spin-polarized by default due to the odd number of electrons. In a CASTEP calculation the supercell must be chosen and explicitly specified in the input files. It is defined by a matrix, which multiplies the ordinary simulation cell vectors and is specified as a 3\\times3 3\\times3 matrix in the .cell file of the form %block PHONON_SUPERCELL_MATRIX 4 0 0 0 4 0 0 0 4 %endblock PHONON_SUPERCELL_MATRIX This typical example using a diagonal matrix creates a supercell expanded along each lattice vector a , b and c by factor of 4. The supercell to be used in a phonon calculation needs to be chosen with care. It must be large enough to contain a sphere of radius R_c R_c , the typical range of a force constant matrix. In a simple metal a value of R_c R_c as small as 6\u00c5 may be satisfactory, but more complex and structured systems will need a larger value 11 . In a covalent semiconductor the required R_c R_c may be 10\u00c5 or larger. However a supercell can quickly grow to generate a very large calculation indeed. For example a 4 \\times 4 \\times 4 4 \\times 4 \\times 4 supercell of even a 2 atom primitive cell contains 128 atoms. Consequently it is rarely feasible to use this method on a uniprocessor or desktop computer, and a substantial parallel computer is usually required. The shape of the supercell should usually be as near cubic as possible, irrespective of the shape of the primitive cell, to optimise the supercell size/ R_c R_c ratio. This can be achieved using an off-diagonal supercell matrix, as in the example input files of figure [al-sc-cell] where a cubic supercell containing 108 atoms ( 3 \\times 4 = 12 3 \\times 4 = 12 unit cells) is generated from the rhombohedral primitive cell of aluminium containing a single atom. If the system is highly anisotropic, perhaps a slab model of a surface then a uniform supercell is clearly not appropriate and a suitable supercell must be designed from a consideration of the exact nature of the model. The electronic Brillouin-Zone integrals for the supercell calculation use the special k-points method, which are specified in the . cell file using an separate but analogous set of keywords to those pertaining to the primitive cell sampling. Specifically, %block SUPERCELL_KPOINT_LIST allows an exact specification of k-points and weights supercell_kpoint_mp_grid_spacing d chooses a Monkhorst-Pack grid with the specified spacing. supercell_kpoint_mp_grid p q r (and optionally supercell_kpoint_mp_offset ) allow an exact specification of a Monkhorst-Pack grid. Finally if no supercell kpoint keywords or blocks are given, a grid is chosen to generate a similar sampling density to the primitive cell calculation. Once the force constant matrix has been calculated using the supercell, the remainder of the lattice dynamics proceeds exactly as in the case of a Fourier interpolation calculation. The keywords controlling the interpolation scheme and cutoff radius, the fine phonon kpoint set and the acoustic sum rule enforcement work in exactly the same way. See section [interpolation-setup] for details.","title":"Legacy Finite Displacement/Supercell"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#sec:convergence","text":"Phonon and dielectric response calculations give rise to a number of issues with convergence, in addition to those encountered in ground-state calculations, and a systematic and step-by-step approach is necessary to achieve well-converged results. CASTEP assists the user by setting default values for many convergence parameters based on the particular task which incorporate the experience of many calculations. Therefore it is a good practice not to specify convergence parameters explicitly unless specific convergence test results are known - otherwise a well-chosen default could be overridden with an untested value. (The example input of figure [example-gamma] contains no phonon-specific convergence parameters.) It was emphasised previously (section [geometry] ) that a well-converged geometry optimisation is a prerequisite for a phonon calculation. In turn this mandates a reasonably high level of convergence of plane-wave cutoff, SCF convergence and electronic k-point sampling. It is typical to run phonon calculations at a basis_precision : FINE level of plane-wave cutoff, (The header of each .usp or .recpot pseudopotential file contains a translation into eV units.) DFPT electric field response calculations can require finer electronic k-point sampling than suffices for a ground state calculation, so the effect of the kpoint_mp_grid on the dielectric permittivity should be tested.","title":"Convergence"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-dfpt-solver","text":"The second stage of a phonon or E-field calculation is the variational DFPT solver, and there are a number of associated parameters to control the convergence. Parameters phonon_energy_tol 1.0e-5 eV/ang**2 and efield_energy_tol 1.0e-5 ang**3 govern the exit criterion for the DFPT self-consistency loop. The above default values are usually sufficient for frequencies converged to < 1 \\text{cm}^{-1} < 1 \\text{cm}^{-1} and permittivities to two or three decimal places and rarely need to be changed. However the converged results depend not only on the DFPT SCF calculation, but also, and rather strongly on the degree of convergence of the ground state electron density and wavefunctions. These enter the DFPT equations both directly and as a consequence of the orthogonality condition between ground-state and first-order response orbitals ( Refson, Tulip, and Clark 2006 ; Gonze and Lee 1997 ). To generate sufficiently accurate ground-state wavefunctions, the value of elec_energy_tol should be much lower than needed for an SCF or geometry optimuzation calculation. CASTEP sets a default value of roughly phonon_energy_tol squared and it is wise to rely on this and not to set elec_energy_tol explicitly in a phonon calculation. 12","title":"Convergence of DFPT solver"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-finite-displacement-forces","text":"The criteria for choosing the \u201cground-state\u201d convergence parameters for a finite-displacement phonon calculation (in either primitive or supercell mode) are naturally almost identical to those governing DFPT calculations. In this case there is no additional self-consistent electronic calculation; instead there is a sequence of additional ground-state calculations at displaced geometries. Finite-displacement calculations require very well converged forces to be computed in the ground state SCF calculation. This is because the numerical evaluation of the second derivative depends on differences between the (small) forces at perturbed configurations (equation [finite-diff] ). Clearly the numerical derivative has lower relative precision than the argument (the forces), which must therefore be evaluated to a rather high precision. Unlike the ground-state energy , which is variational with respect to the orbitals, the forces are not and the error in the forces is linear in the error in the orbitals. The main parameter governing their accuracy is again elec_energy_tol which is again set by default from the value of phonon_energy_tol ^2 ^2 . It is normally sufficient to use the default value of elec_energy_tol chosen as the default in a phonon calculation. However there is also a way of directly achieving the requested force tolerance, by setting parameter elec_force_tol 1e-3 eV/ang . This is not used by default as it adds some overhead to the SCF calculation resulting in longer run times. However it does guarantee that the forces really are converged to the required accuracy, unlike setting elec_energy_tol .","title":"Convergence of finite displacement forces"},{"location":"documentation/Phonons/Castep_Phonons/Running-phonon-calculations/#convergence-of-interpolation-and-supercell","text":"Fourier interpolation and supercell calculations add yet another criterion which must be satisfied to achieve well-converged results - the range of the force-constant matrix in real space. Sections [interpolation-setup] and [supercell] discuss some of the criteria applicable to these types of calculation. Unfortunately convergence testing of the size of the supercell for FD/supercell calculations can be prohibitively expensive as the the volume and number of atoms increase as the cube of the linear dimension under test. Consequently the CPU time will increase with the sixth power or higher! There is no easy solution to this problem and the reader is cautioned not to necessarily take on trust that FD/supercell phonon calculations published in the literature are fully converged! However some progress may be made by performing a calculation using the largest feasible supercell. If phonon_fine_cutoff_method : SPHERICAL is selected, it is then possible to vary the cutoff radius using parameter phonon_force_constant_CUTOFF to lower values than the maximum of half the largest box size. These tests may be performed using the \u201ccontinuation\u201d method (section [continuation] ) or the \u201cphonons\u201d utility (section [phonons-tool] ) without repeating the expensive supercell calculation. Another convergence test is automatically performed if the spherical cutoff method is selected. The frequencies resulting from the interpolation with the spherical cutoff are compared to those from an \u201cexact\u201d interpolation at wavevectors commensurate with the supercell. The results are written to the .castep file. This provides a quantitative measure of the interpolation error. A similar cutoff scaling test might be possible for the phonon_fine_cutoff_method : DEFAULT case, although it is considerably less useful. Parameter phonon_force_constant_cut_scale 0.9 will scale the range of the cutoff by the factor specified. However the default value of 1.0 is \u201cspecial\u201d in including constants separated by exactly half the supercell Wigner Seitz cell. Consequently convergence is not smooth in this parameter and while 0.95 might be underconverged, 1.0 could be very well converged. (This is also the reason for its superior convergence performance over the spherical cutoff scheme.) In general phonon wavevectors {\\mathbf{q}} {\\mathbf{q}} are specified using one of the variants of the phonon_kpoint_* cell keywords for lists, grids or paths. The example given uses a list of length 1 to specify a single point. \u21a9 This example will use the DFPT method which is the default if phonon_method is not present. \u21a9 Further optional output writing to .castep of the dynamical matrixes and force constant matrices is enabled at any iprint level by the parameters phonon_write_dynamical and phonon_write_force_constants respectively. \u21a9 The Placzek theory applies to the case of insulators only, and no general formulation to compute the activity for Raman scattering of conducting systems is available \u21a9 If the parameter raman_method : FINITEDISPLACEMENT is set the calculation uses an older, finite-difference implementation (see section [fd] ) to compute the mode displacement derivatives of the polarizability tensor (section [efield] ) using the approach of Porezag and Pedersen ( Porezag and Pederson 1996 ). The first stage is to perform a full phonon calculation at {\\mathbf{q}}=0 {\\mathbf{q}}=0 , to determine the mode eigenvectors and identify the Raman-active modes. Then CASTEP loops over the active modes only computing the Raman tensor, activity and depolarization for each. This method is deprecated as obsolete and computationally expensive. \u21a9 The offset may be specified as three fractions of the grid spacing, so 1/2p \\; 1/2q \\; 1/2r 1/2p \\; 1/2q \\; 1/2r shifts the grid exactly half a subdivision in each of the three directions. As of release 24.1 the INCLUDE_GAMMA keyword will automate this calculation and in fact is the default so that omitting phonon_kpoint_mp_offset entirely will do the right thing. \u21a9 The latter is governed by the effective range of electronic interactions which bears no relationship to the elastic range of the atomic displacements as required for the force constants. \u21a9 The effect is usually small for LDA, intermediate for PBE and largest for PW91, as the gradient terms are most sensitive to the ASR violation. \u21a9 (or fine_gmax or fine_cut_off_energy \u21a9 There is one known case where the reciprocal-space ASR correction fails to give the correct behaviour. Two-dimensional planar or layered systems with weak inter-layer bonding such as graphene or graphite exhibit a quadratic behaviour of an acoustic mode near \\Gamma \\Gamma . The reciprocal space scheme fails to reproduce the correct, quadratic behaviour and linearises the dispersion. The realspace method generates correct behaviour in these cases. \u21a9 A non-negligible force constant at longer range may also occur in a metallic system in the presence of a Kohn anomaly. \u21a9 Specifically, the error in the second-order energy or force constants is variational, and therefore depends quadratically on the error in the DFPT first-order response orbitals. However it is non-variational and linear with respect to the error in the ground-state orbitals. The practical consequence is that there is an error in DFPT results which varies as the square root of the ground-state convergence parameter elec_energy_tol which therefore must be very small for good accuracy. A heuristic rule of thumb is that elec_energy_tol \\approx \\approx phonon_energy_tol ^2 ^2 is necessary to converge the second order energy to the value of phonon_energy_tol . \u21a9","title":"Convergence of Interpolation and Supercell"},{"location":"documentation/Phonons/Castep_Phonons/Thermodynamic-properties/","text":"One of the important motivations for lattice dynamical calculations of crystalline solids is that the harmonic approximation gives access to thermodynamic properties including the zero-point energy and the free energy as a function of temperature. CASTEP lattice dynamics calculations can be followed by a thermodynamics calculation to calculate the zero-point energy and temperature dependent free energy, entropy, and specific heat \\begin{aligned} F &= E_{\\text{elec}} + k_{B} T \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ S &= \\frac{1}{2T} \\sum_{{\\mathbf{q}},i} \\hbar \\omega_{{\\mathbf{q}},i} \\coth \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) - k_{B} \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ C_V &= \\sum_{{\\mathbf{q}},i} k_{B} \\left ( \\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right )^2 \\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} /% \\left [\\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} -1 \\right ]^2 . \\end{aligned} \\begin{aligned} F &= E_{\\text{elec}} + k_{B} T \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ S &= \\frac{1}{2T} \\sum_{{\\mathbf{q}},i} \\hbar \\omega_{{\\mathbf{q}},i} \\coth \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) - k_{B} \\sum_{{\\mathbf{q}},i} ln \\left [ 2 \\sinh \\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right ) \\right ],\\\\ C_V &= \\sum_{{\\mathbf{q}},i} k_{B} \\left ( \\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T} \\right )^2 \\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} /% \\left [\\exp{\\left (\\frac{\\hbar \\omega_{{\\mathbf{q}},i}}{ k_{B} T}\\right )} -1 \\right ]^2 . \\end{aligned} The thermodynamics calculation follows a previous phonon calculation. It is selected by setting the parameter task : THERMODYNAMICS This may be used in a continuation run from a previous phonon calculation, where the value of the continuation parameter is the name of the previous .check file. Alternatively it may be configured as a new run from scratch by setting the remainder of the parameters exactly as if this were a phonon task, and the phonon calculation will be performed first. Only the phonons defined on the \u201cfine\u201d set of phonon kpoints will be used to compute the free energy as it is normally expected that a thermodynamics calculation will follow an interpolation or supercell calculation. However provided that the standard and fine sets of phonon k-points are identical, it may also be used following a standard phonon calculation. This task will compute and print the free energy, entropy and specific heat plus the vibrational atomic displacement parameters (\u201cADP\u201ds) in the range of temperatures specified by the parameters thermo_t_start and thermo_t_stop . The number of temperatures is set by one or other of the parameters thermo_t_spacing or thermo_t_npoints . All temperatures are absolute and the default unit is K. The results of the calculation are written to the .castep file. The harmonic approximation free energy is only defined if all frequencies are greater than or equal to zero. Any zero or imaginary frequencies are automatically omitted from the calculation and a warning message is printed. It is the responsibility of the end user to check that the computed free energy is not rendered meaningless by the presence of an imaginary mode.","title":"Thermodynamic-properties"},{"location":"documentation/Phonons/Castep_Phonons/frontmatter/","text":"Copyright \u00a9 Science and Technology Facilities Council, 2009","title":"Phonon and related calculations using CASTEP"},{"location":"documentation/Pseudopotentials/otfg_string/","text":"In addition to Chris' OTFG document, some more description of the OTF string 2|3.1|4.0|2.2|2|3|5|50U3.4:60U3.1:51:52U3.1{6s1.45,5d0.05}(qc=3)[] Quantities in <> are descriptions not literals. All chars outside <> are literal ||||||| :...{}(flags)[] Local cpt : 0,1,2 for s,p,d r_c(loc) : pseudisation radius for local component (atomic units) r_c(nl) : pseudisation radius for nonlocal components (atomic units) (can be overridden as part of projector description) rinner/rcore : Pseudisation radius for augmentation functions and pseudo-core charge COARSE/MEDIUM/FINE : Recommended cutoff energies in atomic units (Hartree) projn : Descriptions of projectors to include, separated by semicolons. Syntax of a projector is in its briefest form where digits and denote the atomic quantum numbers eg 30 for 3s In fact this is equivalent to the expanded form \"UU\" where the projector flags \"UU\" mean include two ultrasoft beta projectors for this channel. The full form is [[]][+/-][@] where anything in brackets [] is optional (here only). can be U - a single ultrasoft projector UU - Two ultrasoft projectors N - a single norm-conserving projector L - use this projector as the local component G - an ultrasoft GIPAW Gamma projector H - an norm-conserving GIPAW Gamma projector P - Dummy: do not make a projector. LG - Make Gammas for local channel (not done by default) - the projector specific pseudisation radius. - the reference energy for the projector. A floating-point value beginning with an explicit '=', '+' or '-' in Hartree. '=E' means absolute energy, '+/-E' is relative to AE eigenvalue. - Add this value to the projector, it shift it in energy. config : Reference configuration used to generate pseudopotential specified in obvious way, eg {3s1,3d0.5}. It is not necessary to explicitly mention all core states - CASTEP figures this out. flags : Options controlling the type of pseudisation applied and parameters. Syntax (flag1,flag2, ) allows multiple, comma separated flags qc= The optmisation parameter - KE for q < qc is minimised in optimised projector scheme. Can also write (qc=3,qc1=3.5) to specify angular momentum channel-specific value of qc. tm Troullier-Martins pseudosation scheme pn polynomial fit pb bessel fit es \"extra soft\" scheme esr=val extra-soft with explicit specification of r_c nonlcc Do not generate of unscreen with a pseudo-core charge. schro Use non-relativistic schroedinger equation for AE calculation (default is scalar relativistic eqn) aug Explicitly turn on augmentation charges scpsp Generate a self-consistent pseudopotential test config : Specify a non-default test configuration eg, [4s1.5,3d0.5].","title":"OTFG string"},{"location":"documentation/Pseudopotentials/overview/","text":"CASTEP has a built-in library of pseudopotentials which is usually updated each release. We refer to CASTEP's build-in pseudopotentials as on-the-fly generated (or OTFG). The default OTFG pseudopotentials are accurate ultrasoft pseudopotentials. These are used if species_pot block is not defined in the cell file - or an empty block is given %block species_pot %endblock species_pot For preliminary investigations and high-throughput calculations you might want to choose the QC5 set of ultrasoftpotentials which are faster, but slightly less accurate than the default set. These are designed to give converged results at 500eV for all elements: %block species_pot QC5 %endblock species_pot For properties that require norm-conserving pseudopotentials, you can select CASTEP's latest OTFG norm-conserving set with the following in the in your .cell file. %block species_pot NCP %endblock species_pot For backwards compatibility you can also select pseudopotentials from earlier versions on the on-the-fly database, e.g. use %block species_pot C17 %endblock species_pot to select the ultrasoft pseudopotentials from CASTEP version 17. You can also specify the pseudopotential on a per-element basis, e.g. %block species_pot Fe C17 O NCP Ba QC5 %endblock species_pot A complete list of the availible OTFG definitions follows: String Description NCP Alias for the most recent set of norm conserving potentials QC5 High through put set (delta=1.7meV, 0.8meV excluding N,O,Cr,Mn) HARD \"Ultimate\" set of HARD pseudopotentials C7 USP definitions as of CASTEP 7.0 (C7) C8 USP definitions as of CASTEP 8.0 (C8) C9 USP definitions as of CASTEP 9.0/16.0 delta=0.5meV NCP9 Set of Norm Conserving pseudopotentials CASTEP 9.0/16.0 (NCP9)(delta=1.1meV) C17 USP definitions, CASTEP 17.0 (C17) NCP17 Set of Norm Conserving pseudopotentials CASTEP 17.0 (NCP17) C18 USP definitions, CASTEP 18.0 (C18) NCP18 Norm Conserving pseudopotentials CASTEP 18.0 (NCP18) C19 USP definitions, CASTEP 19.0 (C19) delta=0.442 meV (default for CASTEPv19 up to and including CASTEPv24) 1 NCP19 Norm Conserving pseudopotentials CASTEP 19.0 (NCP19) delta=1.098 meV C19mk2 USP definitions. Updated Lanthanide and Actinide definitions, but otherwise identical to C19. Default for CASTEPv25 and later 2 Pseudopotential files CASTEP can also read in pseudopotentials from files Format Origin .usp as generated by CASTEP (note both USP and NCP use this format) .uspso as generated by CASTEP, with spin-orbit coupling .recpot as generated by OPIUM (also legacy CASTEP files) .UPF as generated by Quantum Espresso Note that properties using PAW augmentation will not be available when using file based pseudopotentials (OTFG is required) - this includes all NMR/EPR properties and EELS spectra. Kurt Lejaeghere, Gustav Bihlmayer, Torbj\u00f6rn Bj\u00f6rkman, Peter Blaha, Stefan Bl\u00fcgel, Volker Blum, Damien Caliste, Ivano E. Castelli, Stewart J. Clark, Andrea Dal Corso, Stefano de Gironcoli, Thierry Deutsch, John Kay Dewhurst, Igor Di Marco, Claudia Draxl, Marcin Du\u0142ak, Olle Eriksson, Jos\u00e9 A. Flores-Livas, Kevin F. Garrity, Luigi Genovese, Paolo Giannozzi, Matteo Giantomassi, Stefan Goedecker, Xavier Gonze, Oscar Gr\u00e5n\u00e4s, E. K. U. Gross, Andris Gulans, Fran\u00e7ois Gygi, D. R. Hamann, Phil J. Hasnip, N. A. W. Holzwarth, Diana Iu\u015fan, Dominik B. Jochym, Fran\u00e7ois Jollet, Daniel Jones, Georg Kresse, Klaus Koepernik, Emine K\u00fc\u00e7\u00fckbenli, Yaroslav O. Kvashnin, Inka L. M. Locht, Sven Lubeck, Martijn Marsman, Nicola Marzari, Ulrike Nitzsche, Lars Nordstr\u00f6m, Taisuke Ozaki, Lorenzo Paulatto, Chris J. Pickard, Ward Poelmans, Matt I. J. Probert, Keith Refson, Manuel Richter, Gian-Marco Rignanese, Santanu Saha, Matthias Scheffler, Martin Schlipf, Karlheinz Schwarz, Sangeeta Sharma, Francesca Tavazza, Patrik Thunstr\u00f6m, Alexandre Tkatchenko, Marc Torrent, David Vanderbilt, Michiel J. van Setten, Veronique Van Speybroeck, John M. Wills, Jonathan R. Yates, Guo-Xu Zhang, and Stefaan Cottenier. Reproducibility in density functional theory calculations of solids. Science , 351(6280):aad3000, 2016. URL: https://www.science.org/doi/abs/10.1126/science.aad3000 , arXiv:https://www.science.org/doi/pdf/10.1126/science.aad3000 , doi:10.1126/science.aad3000 . \u21a9 Sebastiaan P. Huber, Emanuele Bosoni, Marnik Bercx, Jens Br\u00f6der, Augustin Degomme, Vladimir Dikan, Kristjan Eimre, Espen Flage-Larsen, Alberto Garcia, Luigi Genovese, Dominik Gresch, Conrad Johnston, Guido Petretto, Samuel Ponc\u00e9, Gian-Marco Rignanese, Christopher J. Sewell, Berend Smit, Vasily Tseplyaev, Martin Uhrin, Daniel Wortmann, Aliaksandr V. Yakutovich, Austin Zadoks, Pezhman Zarabadi-Poor, Bonan Zhu, Nicola Marzari, and Giovanni Pizzi. Common workflows for computing material properties using different quantum engines. npj Computational Materials , 7(1):136, Aug 2021. URL: https://doi.org/10.1038/s41524-021-00594-6 , doi:10.1038/s41524-021-00594-6 . \u21a9","title":"Overview"},{"location":"documentation/Pseudopotentials/overview/#pseudopotential-files","text":"CASTEP can also read in pseudopotentials from files Format Origin .usp as generated by CASTEP (note both USP and NCP use this format) .uspso as generated by CASTEP, with spin-orbit coupling .recpot as generated by OPIUM (also legacy CASTEP files) .UPF as generated by Quantum Espresso Note that properties using PAW augmentation will not be available when using file based pseudopotentials (OTFG is required) - this includes all NMR/EPR properties and EELS spectra. Kurt Lejaeghere, Gustav Bihlmayer, Torbj\u00f6rn Bj\u00f6rkman, Peter Blaha, Stefan Bl\u00fcgel, Volker Blum, Damien Caliste, Ivano E. Castelli, Stewart J. Clark, Andrea Dal Corso, Stefano de Gironcoli, Thierry Deutsch, John Kay Dewhurst, Igor Di Marco, Claudia Draxl, Marcin Du\u0142ak, Olle Eriksson, Jos\u00e9 A. Flores-Livas, Kevin F. Garrity, Luigi Genovese, Paolo Giannozzi, Matteo Giantomassi, Stefan Goedecker, Xavier Gonze, Oscar Gr\u00e5n\u00e4s, E. K. U. Gross, Andris Gulans, Fran\u00e7ois Gygi, D. R. Hamann, Phil J. Hasnip, N. A. W. Holzwarth, Diana Iu\u015fan, Dominik B. Jochym, Fran\u00e7ois Jollet, Daniel Jones, Georg Kresse, Klaus Koepernik, Emine K\u00fc\u00e7\u00fckbenli, Yaroslav O. Kvashnin, Inka L. M. Locht, Sven Lubeck, Martijn Marsman, Nicola Marzari, Ulrike Nitzsche, Lars Nordstr\u00f6m, Taisuke Ozaki, Lorenzo Paulatto, Chris J. Pickard, Ward Poelmans, Matt I. J. Probert, Keith Refson, Manuel Richter, Gian-Marco Rignanese, Santanu Saha, Matthias Scheffler, Martin Schlipf, Karlheinz Schwarz, Sangeeta Sharma, Francesca Tavazza, Patrik Thunstr\u00f6m, Alexandre Tkatchenko, Marc Torrent, David Vanderbilt, Michiel J. van Setten, Veronique Van Speybroeck, John M. Wills, Jonathan R. Yates, Guo-Xu Zhang, and Stefaan Cottenier. Reproducibility in density functional theory calculations of solids. Science , 351(6280):aad3000, 2016. URL: https://www.science.org/doi/abs/10.1126/science.aad3000 , arXiv:https://www.science.org/doi/pdf/10.1126/science.aad3000 , doi:10.1126/science.aad3000 . \u21a9 Sebastiaan P. Huber, Emanuele Bosoni, Marnik Bercx, Jens Br\u00f6der, Augustin Degomme, Vladimir Dikan, Kristjan Eimre, Espen Flage-Larsen, Alberto Garcia, Luigi Genovese, Dominik Gresch, Conrad Johnston, Guido Petretto, Samuel Ponc\u00e9, Gian-Marco Rignanese, Christopher J. Sewell, Berend Smit, Vasily Tseplyaev, Martin Uhrin, Daniel Wortmann, Aliaksandr V. Yakutovich, Austin Zadoks, Pezhman Zarabadi-Poor, Bonan Zhu, Nicola Marzari, and Giovanni Pizzi. Common workflows for computing material properties using different quantum engines. npj Computational Materials , 7(1):136, Aug 2021. URL: https://doi.org/10.1038/s41524-021-00594-6 , doi:10.1038/s41524-021-00594-6 . \u21a9","title":"Pseudopotential files"},{"location":"documentation/Pseudopotentials/reading_headers/","text":"At the start of a calculation CASTEP will generate the require pseudopotentials. A report is written into the start of the .castep file. This page explains what information is contained within this header. Carbon - Ultrasoft ============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.395 qc 0 | | 2 0 0.250 1.395 qc 0 | | 3 1 -0.194 1.395 qc 0 | | 4 1 0.250 1.395 qc 0 | | loc 2 0.000 1.395 pn 0 | | | | Augmentation charge Rinner = 0.983 | | Partial core correction Rc = 0.983 | ------------------------------------------------------------ | \"2|1.4|10|12|13|20:21(qc=7)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ All quantities are given in atomic units - so energies in Hartree (1Ha =26.4eV) and lengths in Bohr (1 bohr = 0.88Ang) Element: This is just the symbol for the element Ionic Charge: Sum of nuclear charge and the core electrons (C Z=6 core=1s2 gives ionic charge as +6-2=+4) Level of theory: The Exchange-Correlation potential used. Atomic-solver: Koelling-Harmon is the default atomic solver. Reference electronic structure. This section describes the valence states included in the calculation. For Carbon these are the 2s and 2p states. Their occupations and energies are given. Pseudopotential Definition (Advanced) The definitions of each of the non-local projector (aka beta projectors) is given here. Beta - the number of the projector l - angular momentum quantum number e - energy of the corresponding orbital Rc - Cutoff (matching) radius for the orbital scheme - pseudization scheme (qc = qc tuned) norm - 1=norm-conserving 0-ultrasoft (norm not conserved) This is a standard Ultrasoft pseudopotential with two beta projectors per angular momentum channel. One projector is from an orbital at the eigen-energy (i.e. -0.505Ha for 2s) while the second projector corresponds to a non-bound orbital at an energy of 0.25Ha. The final line gives the choice of local potential. In this case the local potential is constructed from a l=2 state with the same cutoff radius as for the local projectors. Augmentation charge Rinner . This is specific to the Ultrasoft scheme - and describes the radius outside which the augmentation charge matches the all-electron charge. Partial core correction . As the exchange correlation energy is a non-linear function of charge there is an error introduced if we compute the xc energy of the valence and core electron separately. We therefore include the core charge in the calculation of the xc energy. The core charge is challenging to represent on a grid - and so a pseudized core charge is used. Rc is the cut-off for this pseudized core charge. Carbon - Normconserving ============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.201 qc 1 | | loc 1 -0.194 1.201 qc 1 | | | | No charge augmentation | | Partial core correction Rc = 0.839 | ------------------------------------------------------------ | \"1|1.2|17|20|23|20N:21L(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ Note that the Reference Electronic Structure section is identical to the ultrasoft potential above. This relates to the all-electron atom and is unaffected by the details of the pseudopotential. From the pseudopotential definition we see there is one beta projector for l=0 (s) and the local potential is set to be l=1 (p). For norm-conserving potentials it is common to only need one projector per angular momentum chanel, and for one of the occupied channels to be represented by the local potential. There is no charge augmentation (this is only needed for ultrasofts) however, a non-linear core correction is used. Uranium - J-dependent ============================================================ | Pseudopotential Report - Date of generation 4-07-2020 | ------------------------------------------------------------ | Element: U Ionic charge: 14.00 Level of theory: LDA | | Atomic Solver: Dirac (FR) | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 6s1/2 2.000 -1.748 | | 6p1/2 2.000 -1.101 | | 6p3/2 4.000 -0.776 | | 7s1/2 2.000 -0.161 | | 5f5/2 1.286 -0.147 | | 5f7/2 1.714 -0.116 | | 6d3/2 0.400 -0.103 | | 6d5/2 0.600 -0.085 | | | | Pseudopotential Definition | | Beta l 2j e Rc scheme norm | | 1 0 1 -1.748 2.106 qc 1 | | 2 0 1 -0.161 2.106 qc 1 | | 3 1 3 -0.776 2.106 qc 1 | | 4 1 1 -1.101 2.106 qc 1 | | 5 2 5 -0.085 2.106 qc 1 | | 6 2 3 -0.103 2.106 qc 1 | | 7 3 7 -0.116 2.106 qc 1 | | 8 3 5 -0.147 2.106 qc 1 | | loc 4 0 0.000 2.106 pn 0 | | | | No charge augmentation | | Partial core correction Rc = 1.472 | ------------------------------------------------------------ | \"4|2.1|17|19|22|60N:70N:61N:62N:53N(qc=6,q3=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ This pseudopotential is calculated by using a Dirac equation solver including the spin-orbit interaction (FR=fully relativistic). It is a norm-conserving potential. There are 14 electrons included in the valence (6s2,7s2,6p6,6d1,5f3). Because of the spin orbit splitting states with different j quantum numbers have different energies. States with l>0 are split into j=l+1/2 j=l+1/2 and j=l-1/2 j=l-1/2 (e.g. the 6p states are split into 6p\u00bd and 6p3/2, the 5f into 5f5/2 5f7/2).","title":"Headers"},{"location":"documentation/Pseudopotentials/reading_headers/#carbon-ultrasoft","text":"============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.395 qc 0 | | 2 0 0.250 1.395 qc 0 | | 3 1 -0.194 1.395 qc 0 | | 4 1 0.250 1.395 qc 0 | | loc 2 0.000 1.395 pn 0 | | | | Augmentation charge Rinner = 0.983 | | Partial core correction Rc = 0.983 | ------------------------------------------------------------ | \"2|1.4|10|12|13|20:21(qc=7)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ All quantities are given in atomic units - so energies in Hartree (1Ha =26.4eV) and lengths in Bohr (1 bohr = 0.88Ang) Element: This is just the symbol for the element Ionic Charge: Sum of nuclear charge and the core electrons (C Z=6 core=1s2 gives ionic charge as +6-2=+4) Level of theory: The Exchange-Correlation potential used. Atomic-solver: Koelling-Harmon is the default atomic solver.","title":"Carbon - Ultrasoft"},{"location":"documentation/Pseudopotentials/reading_headers/#reference-electronic-structure","text":"This section describes the valence states included in the calculation. For Carbon these are the 2s and 2p states. Their occupations and energies are given.","title":"Reference electronic structure."},{"location":"documentation/Pseudopotentials/reading_headers/#pseudopotential-definition-advanced","text":"The definitions of each of the non-local projector (aka beta projectors) is given here. Beta - the number of the projector l - angular momentum quantum number e - energy of the corresponding orbital Rc - Cutoff (matching) radius for the orbital scheme - pseudization scheme (qc = qc tuned) norm - 1=norm-conserving 0-ultrasoft (norm not conserved) This is a standard Ultrasoft pseudopotential with two beta projectors per angular momentum channel. One projector is from an orbital at the eigen-energy (i.e. -0.505Ha for 2s) while the second projector corresponds to a non-bound orbital at an energy of 0.25Ha. The final line gives the choice of local potential. In this case the local potential is constructed from a l=2 state with the same cutoff radius as for the local projectors. Augmentation charge Rinner . This is specific to the Ultrasoft scheme - and describes the radius outside which the augmentation charge matches the all-electron charge. Partial core correction . As the exchange correlation energy is a non-linear function of charge there is an error introduced if we compute the xc energy of the valence and core electron separately. We therefore include the core charge in the calculation of the xc energy. The core charge is challenging to represent on a grid - and so a pseudized core charge is used. Rc is the cut-off for this pseudized core charge.","title":"Pseudopotential Definition (Advanced)"},{"location":"documentation/Pseudopotentials/reading_headers/#carbon-normconserving","text":"============================================================ | Pseudopotential Report - Date of generation 8-07-2020 | ------------------------------------------------------------ | Element: C Ionic charge: 4.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.505 | | 2p 2.000 -0.194 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.505 1.201 qc 1 | | loc 1 -0.194 1.201 qc 1 | | | | No charge augmentation | | Partial core correction Rc = 0.839 | ------------------------------------------------------------ | \"1|1.2|17|20|23|20N:21L(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ Note that the Reference Electronic Structure section is identical to the ultrasoft potential above. This relates to the all-electron atom and is unaffected by the details of the pseudopotential. From the pseudopotential definition we see there is one beta projector for l=0 (s) and the local potential is set to be l=1 (p). For norm-conserving potentials it is common to only need one projector per angular momentum chanel, and for one of the occupied channels to be represented by the local potential. There is no charge augmentation (this is only needed for ultrasofts) however, a non-linear core correction is used.","title":"Carbon - Normconserving"},{"location":"documentation/Pseudopotentials/reading_headers/#uranium-j-dependent","text":"============================================================ | Pseudopotential Report - Date of generation 4-07-2020 | ------------------------------------------------------------ | Element: U Ionic charge: 14.00 Level of theory: LDA | | Atomic Solver: Dirac (FR) | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 6s1/2 2.000 -1.748 | | 6p1/2 2.000 -1.101 | | 6p3/2 4.000 -0.776 | | 7s1/2 2.000 -0.161 | | 5f5/2 1.286 -0.147 | | 5f7/2 1.714 -0.116 | | 6d3/2 0.400 -0.103 | | 6d5/2 0.600 -0.085 | | | | Pseudopotential Definition | | Beta l 2j e Rc scheme norm | | 1 0 1 -1.748 2.106 qc 1 | | 2 0 1 -0.161 2.106 qc 1 | | 3 1 3 -0.776 2.106 qc 1 | | 4 1 1 -1.101 2.106 qc 1 | | 5 2 5 -0.085 2.106 qc 1 | | 6 2 3 -0.103 2.106 qc 1 | | 7 3 7 -0.116 2.106 qc 1 | | 8 3 5 -0.147 2.106 qc 1 | | loc 4 0 0.000 2.106 pn 0 | | | | No charge augmentation | | Partial core correction Rc = 1.472 | ------------------------------------------------------------ | \"4|2.1|17|19|22|60N:70N:61N:62N:53N(qc=6,q3=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ This pseudopotential is calculated by using a Dirac equation solver including the spin-orbit interaction (FR=fully relativistic). It is a norm-conserving potential. There are 14 electrons included in the valence (6s2,7s2,6p6,6d1,5f3). Because of the spin orbit splitting states with different j quantum numbers have different energies. States with l>0 are split into j=l+1/2 j=l+1/2 and j=l-1/2 j=l-1/2 (e.g. the 6p states are split into 6p\u00bd and 6p3/2, the 5f into 5f5/2 5f7/2).","title":"Uranium - J-dependent"},{"location":"documentation/Pseudopotentials/theory/","text":"The electrons in an atom can be divided into two types --- core electrons and valence electrons. The core electrons are tightly bound to the nucleus, while the valence electrons are more extended. A working definition for core electrons is that they are the ones which play no part in the interactions between atoms, while the valence electrons dictate most of the properties of the material. It is common to make the frozen core approximation; the core electrons are constrained not to differ from their free atomic nature when placed in the solid state environment. This reduces the number of electronic degrees of freedom in an all-electron calculation. It is a very good approximation. A different, but physically related, approach is taken in the pseudopotential approximation. Since, in an all-electron calculation, the valence electron wavefunctions must be orthogonal to the core wavefunctions they necessarily have strong oscillations in the region near the nucleus (see the all-electron wavefunction in Figure~\\ref{fig:wvfn}). Given that a planewave basis set is to be used to describe the wavefunctions, these strong oscillations are undesirable --- requiring many plane waves for an accurate description. Further, these oscillations are of very little consequence for the electronic structure in the solid, since they occur close to the nucleus. In the pseudopotential approach only the valence electrons are explicitly considered, the effects of the core electrons being integrated within a new ionic potential. The valence wavefunctions need no longer be orthogonal to the core states, and so the orthogonality oscillations disappear; hence far fewer plane waves are required to describe the valence wavefunctions. Numerous schemes to produce optimally soft pseudopotentials have been developed. Common choices are the norm-conserving potentials due to Troullier and Martins 1 and Vanderbilt's ultrasoft scheme 2 . N. Troullier and Jos\u00e9 Lu\u00eds Martins. Efficient pseudopotentials for plane-wave calculations. Phys. Rev. B , 43:1993\u20132006, Jan 1991. doi:10.1103/PhysRevB.43.1993 . \u21a9 David Vanderbilt. Soft self-consistent pseudopotentials in a generalized eigenvalue formalism. Phys. Rev. B , 41:7892\u20137895, Apr 1990. doi:10.1103/PhysRevB.41.7892 . \u21a9","title":"Theory"},{"location":"documentation/Spectral/keywords/","text":"SPECTRAL_TASK - determines what will be calculated. All tasks will compute the eigenenergies (aka bands). The list of tasks, and the extra properties calculated are as follows: bandstructure dos band gradients optics optical matrix elements pdos atomic projections coreloss dipole matrix elements with core states Most spectral calculations will involve the calculation of unoccupied states. One of the following parameters should be set to determine the number of states calculated. SPECTRAL_NEXTRA_BANDS number of extra spectral bands SPECTRAL_PERC_EXTRA_BANDS percentage of extra spectral bands SPECTRAL_NBANDS number of bands/k-point in spectral calc It is possible to use a different exchange-correlation functional to the one used for the groundstate. An example might be when a semi-local functional (such as PBE) is used for the groundstate, and a more expensive non-local functional (e.g. PBE0) is used for the spectral calculation. This is an approximation and should be done with cuation. To set the xc functional use one of the two keywords. SPECTRAL_XC_FUNCTIONAL spectral exchange-correlation functional SPECTRAL_XC_DEFINITION spectral exchange-correlation functional To change the convergence tolerance for the eigenvalues set SPECTRAL_EIGENVALUE_TOL ! default: 10E-6 eV SPECTRAL_MAX_ITER maximum iterations in spectral calculation SPECTRAL_MAX_STEPS_PER_ITER maximum steps per iter in spectral calculation","title":"Keywords"},{"location":"documentation/Spectral/overview/","text":"`","title":"Overview"},{"location":"documentation/Spectral/restarts/","text":"Spectral calculations do not write a check file - however, they can write backups to enable restarting an unfinished calculation. The limitation is that a parallel calculation must be restarted on the same number of processors. #Sample param file cut_off_energy : 550 eV fix_occupancy : true task : spectral spectral_task : coreloss %block devel_code SPECTRAL_RESTART %endblock devel_code backup_interval 1800 ! time in seconds The devel_code keyword SPECTRAL_RESTART triggers both the writing an reading of Spectral backup files. backup_interval determines the time between writing backups. Backup will slow down the calculation as they require disk access (which is always slow). If you expect a job to run for several hours backing up every 30min is a reasonable compromise. After completing each k-point the CASTEP will check to see if time since the last backup is greater than backup_interval - is it is a backup will be written - if not CASTEP carries on with the next k-point. Note that a backup is always written (if backup_interval>0) after the final kpoint. This is useful insurance in case there is any problem when CASTEP writes the final output files. Here is an example .castep file with backup ===================================================================== + + + Calculation of Spectral Properties + + + + Calculation re-parallelised over 2 processes. + + Data distributed by G-vector(1-way), k-point(2-way), band(1-way) + + Data distributed by k-point(2-way) + + + ===================================================================== Starting k-point: 1 of 5 on this process |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC Starting k-point: 5 of 5 on this process |<-- SPEC Starting k-point: 1 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC We see that backups were written every three k-points. The last backup was done after the 1 st k-point for spin 2. As this calculation was run on two processors, we find two backup files have been created -rw-r--r-- 1 317700 18 Jul 10:53 Si2-core.0001.spec -rw-r--r-- 1 317700 18 Jul 10:53 Si2-core.0002.spec To restart, keep everything the same but add to the param file continuation : xxx.check Where xxx.check is the name of the check file containing the ground-state density etc. This will have been written during the first run - and xxx will be replaced with whatever is the seedname of your run. We now re-run the calculation. CASTEP will read the ground-state from the check file (so there should be no electronic minimisation) Restarting spectral calculation from restart file |<-- SPEC Starting k-point: 2 of 5 on this process |<-- SPEC Starting k-point: 3 of 5 on this process |<-- SPEC Starting k-point: 4 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Starting k-point: 5 of 5 on this process |<-- SPEC Check-pointing spectral run |<-- SPEC Total time to compute matrix elements 3500.45 sec |<\u2014- SPEC So the calculation did restart from the 2 nd k-point on spin 2.","title":"Restarts"},{"location":"documentation/TDDFT/overview/","text":"","title":"TDDFT Overview"},{"location":"documentation/Tools/tools/","text":"This page lists various analysis codes (some supplied with the CASTEP distribution as well as other third-party codes) which interoperate with CASTEP. Some of these programs require additional interface codes/scripts to take CASTEP output as their input, etc. Pre-processing Tools c2x (also bundled with the CASTEP distribution) reads and converts a selection of crystal structure file formats including .cif which relate to DFT and perform structure manipulations. It can rotate cells, make supercells, add vacuum space, create slabs and nanotubes. Cif2Cell is a tool to generate the geometrical setup for various electronic structure codes from a CIF (Crystallographic Information Framework) file. Also supports supercell generation and formats for visualisation tools. SeeK-path is a k-path finder that provides band paths compatible with space group symmetry, and an interactive 3D visualiser. Convergence Testing castepconv CASTEPconv (also bundled with the CASTEP distribution) automates convergence testing of plane-wave cutoff, k-point density and fine grid scale. Based on a proforma input, it prepares the files, analyses the output and generates summary data files. A standalone version is shipped with CASTEP source. Later versions depend upon ASE and can be downloaded from github ( https://github.com/CCP-NC/castepconv ) and can also generate plots. General Postprocessing castep-outputs is a Python package to read and parse all of the output files of CASTEP into a standard form. This is the recommended CASTEP output parser interface. A simple CLI tool is provided to dump a .json file, but its main use is intended as a library to be called from future analysis codes. This is the recommended interface for developers of Python analysis tools. Currently this reads and parses all CASTEP text-format files but not the binary ones. castepxbin is a collection of readers for CASTEP binary output files .check , .castep_bin , .orbitals etc. c2x (also bundled with the CASTEP distribution) can read CASTEP binary output files .check , .castep_bin , .orbitals and extract cell geometry data, electron densities , wavefunctions and prepare for visualization and further analysis. It can interpolate densities via a combination of trilinear and Fourier interpolation, integrate densities and calculate their dipole moments, and analyse bands for inversion symmetry. It can be used to produce output formats compatible with XCrysDen, VESTA, VMD and Jmol amongst others, and can also produce 1D data in a format suitable for gnuplot. Spectroscopy Modelling Tools dispersion.pl and dos.pl (part of CASTEP distribution) are tools for producing band-structure and density of states plots from a CASTEP .bands file. They also support creating phonon dispersion and DOS plots. Dispersion.pl will perform simple modelling of a powder Raman spectrum for a specified laser frequency and temperature. OptaDOS is a code for calculating optical, core-level excitation spectra along with full, partial and joint electronic density of states (DOS). SUMO is a suite of tools for electronic band structure and phonon dispersion analysis and plotting. PDielec calculates model powder infra-red spectra including optical cavity effects from CASTEP (and other) phonon calculations. orbitals2bands (part of CASTEP distribution) Reads a CASTEP .orbitals file from a spectral/bandstructure calculation, analyses the band crossings and generates a .bands file with reordered eigenvalues for producing a bandstructure plot with crossings taken into account. bs_sc2pc (part of CASTEP distribution) is a band structure unfolding tool for CASTEP. It implements the effective band structure method described by Popescu and Zunger http://dx.doi.org/10.1103/PhysRevB.85.085201|10.1103/PhysRevB.85.085201 , and is distributed as part of the CASTEP academic distribution. Peter Brommer and David Quigley (2014) \"Automated effective band structures for defective and mismatched supercells.\" J. Phys.: Condens. Matter 26 485501. http://dx.doi.org/10.1088/0953-8984/26/48/485501|10.1088/0953-8984/26/48/485501 . band_up is another program for performing band unfolding calculations on defective supercells. easyunfold is yet another band unfolding tool, with CASTEP support. PhononUnfolding is a program for unfolding of phonon dispersions. mode_follow (part of CASTEP distribution) reads a .phonon output file and generates a sequence of .cell input files for single-point energy calculations to compute the energy profile along a mode for plotting and to analyse for anharmonicity or double-well depth. molpdos (part of CASTEP distribution) calculates DOS, and DOS projected onto molecular states, as part of a Delta SCF calculation. Abins is a plugin for Mantid which allows scientists to compare experimental and theoretical inelastic neutron scattering spectra. AbINS uses the phonon data calculated by DFT programs, such as CASTEP, to generate an INS spectra of a powder sample, which makes it easier to establish a connection between theory and experiments. Euphonic is a library and front-end for calculating the inelastic neutron scattering spectral function in 4-D ( Q , \\omega \\omega ) space to compare with data from a in a single-crystal time-of-flight INS spectrometer. OCLIMAX is a free program for simulation of inelastic neutron scattering using vibrational frequencies and polarization vectors as input. It can perform simulations on both powder and single crystal samples, and the input phonon data can be obtained from first-principles or empirical calculations. phonopy is an open source package for phonon calculations at harmonic and quasi-harmonic levels. phono3py calculates phonon-phonon interaction and related properties using the supercell approach. These properties include the lattice thermal conductivity, joint density of states and the phonon lifetimes. Visualisation CrystalMaker is a visualisation suite for designing and investigating crystal and molecular structures. It also provides support for modelling and animation of atomistic and electronic properties. JMOL is an open-source browser-based HTML5 viewer and stand-alone Java viewer for chemical structures in 3D with features for molecules, crystals, materials, and biomolecules. It is able to read CASTEP .cell , .castep , .den_fmt , . elf-fmt , .geom , .md , .phonon and more, with rendering of crystal structure, densities, ELF etc. and animation of optimization or MD trajectories and phonon vibrations. MagresView is a tool for visualization and processing of computed solid-state NMR parameters. OVITO is a scientific visualization and analysis software for atomistic and particle simulation data. VESTA is a 3D visualization program for structural models, volumetric data such as electron/nuclear densities, and crystal morphologies. XCrysDen is a crystalline and molecular structure visualisation program aiming at display of isosurfaces and contours, which can be superimposed on crystalline structures and interactively rotated and manipulated. ( .c2x can convert CASTEP output to the .xsf format, and other converters are supplied as part of the CASTEP distribution) castep2fs is a CASTEP utility for taking a CASTEP output and producing publication quality Fermi Surfaces and related quantities. castep2cube (Part of CASTEP distribution) reads .check or .castep_bin output files and converts the electron density to Gaussian .cube format which many other visualisation tools can read. Databases, Big Data and Workflow NOMAD supports CASTEP and its users. The service includes uploading, downloading, sharing, assigning DOIs, and more. Storing is guaranteed for at least 10 years, a requirement set by several funding agencies. The NOMAD Repository is also the only repository in Computational Materials Science that is recommended by NATURE Scientific Data. The repository currently contains over 10 8 entries - see the archive for the latest data. aiida-castep Interface to AiiDA workflow infrastructure. Soprano is a Python library meant to help crystallographers with the search and classification of new crystal forms for a given material. It provides a number of classes and functions to handle large amounts of candidate structures, compare them, sort them and cluster them. Structure Prediction CASTEP_GA (part of CASTEP distribution) is a crystal structure prediction tool based upon a modified Genetic Algorithm (GA) for periodic systems. It can handle 3D bulk materials, and also 2D surface reconstructions/interfaces and 1D edges of nanoribbons etc. It has a population of parent crystals, that are mutated and bred to make candidate children, that are then fed to CASTEP for (local) structure optimization. It is also possible to add structures that are randomly generated according to a random space group. After a number of generations, a candidate global minimum enthalpy structure can emerge. The functionality has also been extended to a MOGA (Multi-Objective GA) so that a Pareto front of optimal structures is generated, with minimum enthalpy on one axis, and a user defined property on the other. Example scripts that can be used to generate this property value are included in the distribution. Finally, recent work has been on the CHGA (Convex Hull GA) approach, wherein the stoichiometry is optimized as well, resulting in the generation of a multi-dimensional convex hull. More detailed documentation is included in the 'ReadMe' directory. AIRSS (''Ab initio Random Structure Searching'') is a very simple, yet powerful and highly parallel, approach to structure prediction. It generates random sensible structures and relaxes them to nearby minima. The sensible random structures are constructed so that they have reasonable densities, and atomic separations. Additionally they may embody crystallographic, chemical or prior experimental/computational knowledge. Beyond these explicit constraints the emphasis is on a broad, uniform, sampling of structure space. It is tightly integrated with CASTEP and has been used in a number of landmark studies to find novel phases of materials. Calypso (''Crystal structure AnaLYsis by Particle Swarm Optimization'') is an efficient structure prediction code. The approach requires only chemical compositions for a given compound to predict stable or metastable structures at given external conditions and can be used to predict/determine the crystal structure and design multi-functional materials. USPEX (''Universal Structure Predictor: Evolutionary Xtallography'') is a method developed by the Oganov laboratory for crystal structure prediction. It can very efficiently handle molecular crystals (including those with flexible and very complex molecules) and can predict stable chemical compositions and corresponding crystal structures, given just the names of the chemical elements. In addition to this fully non-empirical search, USPEX allows one to predict also a large set of robust metastable structures and perform several types of simulations using various degrees of prior knowledge. XtalOPT is a free and truly open source evolutionary algorithm designed for a priori crystal structure prediction implemented as an extension to the Avogadro molecular editor. MD analysis geom2xyz.pl , geom2xsf , geom2dcd (part of CASTEP distribution) are filters to convert CASTEP .geom and .md output files to other trajectory formats and may be used to interface with a number of other analysis codes. md_to_phonon (part of CASTEP distribution) is a simple python tool for reading a CASTEP trajectory file and performing various phonon-based analyses, including mass-weighted velocity autocorrelation function (VACF) vs frequency (which is close to the experimental VDOS). It can also project out a particular eigenmode and eigenvector from a user specified peak in the VACF and write as a single-mode CASTEP phonon file for visualization by other tools, e.g. JMol. MDANSE (''Molecular Dynamics Analysis for Neutron Scattering Experiments'') is a python application designed for computing properties that can be directly compared with neutron scattering experiments such as the coherent and incoherent intermediate scattering functions and their Fourier transforms, the elastic incoherent structure factor, the static coherent structure factor or the radial distribution function. LiquidLib is a \"comprehensive toolbox for analyzing classical and ab initio molecular dynamics simulations of liquids and liquid-like matter with applications to neutron scattering experiments\". potfit attempts to fit a model forcefield to a data set provided. There is a python converter tool in the CASTEP distribution for reading a CASTEP trajectory file and generating an atomic configuration file to be used as input for the potfit code. MDTEP is a simple code for analysing MD trajectories and calculating thermodynamic properties such as the heat capacity and the velocity autocorrelation function. Machine-Learned Potentials QUIP is is a collection of software tools to carry out molecular dynamics simulations. It implements a variety of interatomic potentials and tight binding quantum mechanics. See https://pubs.aip.org/aip/jcp/article/159/4/044803/2904492/Machine-learned-acceleration-for-molecular . Transport ShengBTE is a software package for solving the Boltzmann Transport Equation for phonons. Its main purpose is to compute the lattice contribution to the thermal conductivity of bulk crystalline solids, but nanowires can also be treated under a hypothesis of diffusive boundary conditions. AlmaBTA extends the ShengBTE approach currently employed for homogeneous bulk materials, into the mesoscale, to fully describe thermal transport from the electronic ab initio level, through the atomistic one, all the way into the mesoscopic structure level. BoltzTraP is a program for calculating the semi-classic transport coefficients. BoltzTrap2 is a modern implementation of the smoothed Fourier interpolation algorithm for electronic bands that formed the base of the original and widely used BoltzTraP code. One of the most typical uses of BoltzTraP is the calculation of thermoelectric transport coefficients as functions of temperature and chemical potential in the rigid-band picture. However, many other features are available, including 3D plots of Fermi surfaces based on the reconstructed bands. EMC (''Effective Mass Calculator'') implements calculation of the effective masses at the bands extrema using finite difference method. There are two versions of the program: written in FORTRAN and Python. Miscellaneous ASE is a set of tools and Python modules for setting up, manipulating, running, visualizing and analyzing atomistic simulations. The code is freely available under the GNU LGPL license. It can interface with many different electronic structure codes. Bader is a tool to perform Bader charge analysis on a charge density grid. Typically in molecular systems, the charge density reaches a minimum between atoms and this is a natural place to separate atoms from each other. Besides being an intuitive scheme for visualizing atoms in molecules, Bader's definition is often useful for charge analysis. For example, the charge enclosed within the Bader volume is a good approximation to the total electronic charge of an atom. ATAT (Alloy Theoretic Automated Toolkit) is a collection of alloy theory tools developed by Axel van de Walle. CASINO is a computer program system for performing quantum Monte Carlo (QMC) electronic structure calculations that has been developed by members of the Theory of Condensed Matter group in the Cambridge University physics department, and their collaborators, over more than 20 years. It is capable of calculating incredibly accurate solutions to the Schr\u00f6dinger equation of quantum mechanics for realistic systems built from atoms. An interface castep2casino is supplied with the CASTEP distribution. Emacs mode (part of CASTEP distribution) is an emacs major mode for CASTEP input files with datatype based syntax highlighting and inbuilt help functionality. i-PI is a package for performing molecular dynamics and path-integral MD via a unix socket driver interface. More details elsewhere in this site. Commercial Codes BIOVIA Materials Studio is a suite of graphical tools and codes for quantum and classical simulation of materials, and is how CASTEP is distributed commercially.","title":"Other Codes and Tools"},{"location":"documentation/Tools/tools/#pre-processing-tools","text":"c2x (also bundled with the CASTEP distribution) reads and converts a selection of crystal structure file formats including .cif which relate to DFT and perform structure manipulations. It can rotate cells, make supercells, add vacuum space, create slabs and nanotubes. Cif2Cell is a tool to generate the geometrical setup for various electronic structure codes from a CIF (Crystallographic Information Framework) file. Also supports supercell generation and formats for visualisation tools. SeeK-path is a k-path finder that provides band paths compatible with space group symmetry, and an interactive 3D visualiser.","title":"Pre-processing Tools"},{"location":"documentation/Tools/tools/#convergence-testing","text":"castepconv CASTEPconv (also bundled with the CASTEP distribution) automates convergence testing of plane-wave cutoff, k-point density and fine grid scale. Based on a proforma input, it prepares the files, analyses the output and generates summary data files. A standalone version is shipped with CASTEP source. Later versions depend upon ASE and can be downloaded from github ( https://github.com/CCP-NC/castepconv ) and can also generate plots.","title":"Convergence Testing"},{"location":"documentation/Tools/tools/#general-postprocessing","text":"castep-outputs is a Python package to read and parse all of the output files of CASTEP into a standard form. This is the recommended CASTEP output parser interface. A simple CLI tool is provided to dump a .json file, but its main use is intended as a library to be called from future analysis codes. This is the recommended interface for developers of Python analysis tools. Currently this reads and parses all CASTEP text-format files but not the binary ones. castepxbin is a collection of readers for CASTEP binary output files .check , .castep_bin , .orbitals etc. c2x (also bundled with the CASTEP distribution) can read CASTEP binary output files .check , .castep_bin , .orbitals and extract cell geometry data, electron densities , wavefunctions and prepare for visualization and further analysis. It can interpolate densities via a combination of trilinear and Fourier interpolation, integrate densities and calculate their dipole moments, and analyse bands for inversion symmetry. It can be used to produce output formats compatible with XCrysDen, VESTA, VMD and Jmol amongst others, and can also produce 1D data in a format suitable for gnuplot.","title":"General Postprocessing"},{"location":"documentation/Tools/tools/#spectroscopy-modelling-tools","text":"dispersion.pl and dos.pl (part of CASTEP distribution) are tools for producing band-structure and density of states plots from a CASTEP .bands file. They also support creating phonon dispersion and DOS plots. Dispersion.pl will perform simple modelling of a powder Raman spectrum for a specified laser frequency and temperature. OptaDOS is a code for calculating optical, core-level excitation spectra along with full, partial and joint electronic density of states (DOS). SUMO is a suite of tools for electronic band structure and phonon dispersion analysis and plotting. PDielec calculates model powder infra-red spectra including optical cavity effects from CASTEP (and other) phonon calculations. orbitals2bands (part of CASTEP distribution) Reads a CASTEP .orbitals file from a spectral/bandstructure calculation, analyses the band crossings and generates a .bands file with reordered eigenvalues for producing a bandstructure plot with crossings taken into account. bs_sc2pc (part of CASTEP distribution) is a band structure unfolding tool for CASTEP. It implements the effective band structure method described by Popescu and Zunger http://dx.doi.org/10.1103/PhysRevB.85.085201|10.1103/PhysRevB.85.085201 , and is distributed as part of the CASTEP academic distribution. Peter Brommer and David Quigley (2014) \"Automated effective band structures for defective and mismatched supercells.\" J. Phys.: Condens. Matter 26 485501. http://dx.doi.org/10.1088/0953-8984/26/48/485501|10.1088/0953-8984/26/48/485501 . band_up is another program for performing band unfolding calculations on defective supercells. easyunfold is yet another band unfolding tool, with CASTEP support. PhononUnfolding is a program for unfolding of phonon dispersions. mode_follow (part of CASTEP distribution) reads a .phonon output file and generates a sequence of .cell input files for single-point energy calculations to compute the energy profile along a mode for plotting and to analyse for anharmonicity or double-well depth. molpdos (part of CASTEP distribution) calculates DOS, and DOS projected onto molecular states, as part of a Delta SCF calculation. Abins is a plugin for Mantid which allows scientists to compare experimental and theoretical inelastic neutron scattering spectra. AbINS uses the phonon data calculated by DFT programs, such as CASTEP, to generate an INS spectra of a powder sample, which makes it easier to establish a connection between theory and experiments. Euphonic is a library and front-end for calculating the inelastic neutron scattering spectral function in 4-D ( Q , \\omega \\omega ) space to compare with data from a in a single-crystal time-of-flight INS spectrometer. OCLIMAX is a free program for simulation of inelastic neutron scattering using vibrational frequencies and polarization vectors as input. It can perform simulations on both powder and single crystal samples, and the input phonon data can be obtained from first-principles or empirical calculations. phonopy is an open source package for phonon calculations at harmonic and quasi-harmonic levels. phono3py calculates phonon-phonon interaction and related properties using the supercell approach. These properties include the lattice thermal conductivity, joint density of states and the phonon lifetimes.","title":"Spectroscopy Modelling Tools"},{"location":"documentation/Tools/tools/#visualisation","text":"CrystalMaker is a visualisation suite for designing and investigating crystal and molecular structures. It also provides support for modelling and animation of atomistic and electronic properties. JMOL is an open-source browser-based HTML5 viewer and stand-alone Java viewer for chemical structures in 3D with features for molecules, crystals, materials, and biomolecules. It is able to read CASTEP .cell , .castep , .den_fmt , . elf-fmt , .geom , .md , .phonon and more, with rendering of crystal structure, densities, ELF etc. and animation of optimization or MD trajectories and phonon vibrations. MagresView is a tool for visualization and processing of computed solid-state NMR parameters. OVITO is a scientific visualization and analysis software for atomistic and particle simulation data. VESTA is a 3D visualization program for structural models, volumetric data such as electron/nuclear densities, and crystal morphologies. XCrysDen is a crystalline and molecular structure visualisation program aiming at display of isosurfaces and contours, which can be superimposed on crystalline structures and interactively rotated and manipulated. ( .c2x can convert CASTEP output to the .xsf format, and other converters are supplied as part of the CASTEP distribution) castep2fs is a CASTEP utility for taking a CASTEP output and producing publication quality Fermi Surfaces and related quantities. castep2cube (Part of CASTEP distribution) reads .check or .castep_bin output files and converts the electron density to Gaussian .cube format which many other visualisation tools can read.","title":"Visualisation"},{"location":"documentation/Tools/tools/#databases-big-data-and-workflow","text":"NOMAD supports CASTEP and its users. The service includes uploading, downloading, sharing, assigning DOIs, and more. Storing is guaranteed for at least 10 years, a requirement set by several funding agencies. The NOMAD Repository is also the only repository in Computational Materials Science that is recommended by NATURE Scientific Data. The repository currently contains over 10 8 entries - see the archive for the latest data. aiida-castep Interface to AiiDA workflow infrastructure. Soprano is a Python library meant to help crystallographers with the search and classification of new crystal forms for a given material. It provides a number of classes and functions to handle large amounts of candidate structures, compare them, sort them and cluster them.","title":"Databases, Big Data and Workflow"},{"location":"documentation/Tools/tools/#structure-prediction","text":"CASTEP_GA (part of CASTEP distribution) is a crystal structure prediction tool based upon a modified Genetic Algorithm (GA) for periodic systems. It can handle 3D bulk materials, and also 2D surface reconstructions/interfaces and 1D edges of nanoribbons etc. It has a population of parent crystals, that are mutated and bred to make candidate children, that are then fed to CASTEP for (local) structure optimization. It is also possible to add structures that are randomly generated according to a random space group. After a number of generations, a candidate global minimum enthalpy structure can emerge. The functionality has also been extended to a MOGA (Multi-Objective GA) so that a Pareto front of optimal structures is generated, with minimum enthalpy on one axis, and a user defined property on the other. Example scripts that can be used to generate this property value are included in the distribution. Finally, recent work has been on the CHGA (Convex Hull GA) approach, wherein the stoichiometry is optimized as well, resulting in the generation of a multi-dimensional convex hull. More detailed documentation is included in the 'ReadMe' directory. AIRSS (''Ab initio Random Structure Searching'') is a very simple, yet powerful and highly parallel, approach to structure prediction. It generates random sensible structures and relaxes them to nearby minima. The sensible random structures are constructed so that they have reasonable densities, and atomic separations. Additionally they may embody crystallographic, chemical or prior experimental/computational knowledge. Beyond these explicit constraints the emphasis is on a broad, uniform, sampling of structure space. It is tightly integrated with CASTEP and has been used in a number of landmark studies to find novel phases of materials. Calypso (''Crystal structure AnaLYsis by Particle Swarm Optimization'') is an efficient structure prediction code. The approach requires only chemical compositions for a given compound to predict stable or metastable structures at given external conditions and can be used to predict/determine the crystal structure and design multi-functional materials. USPEX (''Universal Structure Predictor: Evolutionary Xtallography'') is a method developed by the Oganov laboratory for crystal structure prediction. It can very efficiently handle molecular crystals (including those with flexible and very complex molecules) and can predict stable chemical compositions and corresponding crystal structures, given just the names of the chemical elements. In addition to this fully non-empirical search, USPEX allows one to predict also a large set of robust metastable structures and perform several types of simulations using various degrees of prior knowledge. XtalOPT is a free and truly open source evolutionary algorithm designed for a priori crystal structure prediction implemented as an extension to the Avogadro molecular editor.","title":"Structure Prediction"},{"location":"documentation/Tools/tools/#md-analysis","text":"geom2xyz.pl , geom2xsf , geom2dcd (part of CASTEP distribution) are filters to convert CASTEP .geom and .md output files to other trajectory formats and may be used to interface with a number of other analysis codes. md_to_phonon (part of CASTEP distribution) is a simple python tool for reading a CASTEP trajectory file and performing various phonon-based analyses, including mass-weighted velocity autocorrelation function (VACF) vs frequency (which is close to the experimental VDOS). It can also project out a particular eigenmode and eigenvector from a user specified peak in the VACF and write as a single-mode CASTEP phonon file for visualization by other tools, e.g. JMol. MDANSE (''Molecular Dynamics Analysis for Neutron Scattering Experiments'') is a python application designed for computing properties that can be directly compared with neutron scattering experiments such as the coherent and incoherent intermediate scattering functions and their Fourier transforms, the elastic incoherent structure factor, the static coherent structure factor or the radial distribution function. LiquidLib is a \"comprehensive toolbox for analyzing classical and ab initio molecular dynamics simulations of liquids and liquid-like matter with applications to neutron scattering experiments\". potfit attempts to fit a model forcefield to a data set provided. There is a python converter tool in the CASTEP distribution for reading a CASTEP trajectory file and generating an atomic configuration file to be used as input for the potfit code. MDTEP is a simple code for analysing MD trajectories and calculating thermodynamic properties such as the heat capacity and the velocity autocorrelation function.","title":"MD analysis"},{"location":"documentation/Tools/tools/#machine-learned-potentials","text":"QUIP is is a collection of software tools to carry out molecular dynamics simulations. It implements a variety of interatomic potentials and tight binding quantum mechanics. See https://pubs.aip.org/aip/jcp/article/159/4/044803/2904492/Machine-learned-acceleration-for-molecular .","title":"Machine-Learned Potentials"},{"location":"documentation/Tools/tools/#transport","text":"ShengBTE is a software package for solving the Boltzmann Transport Equation for phonons. Its main purpose is to compute the lattice contribution to the thermal conductivity of bulk crystalline solids, but nanowires can also be treated under a hypothesis of diffusive boundary conditions. AlmaBTA extends the ShengBTE approach currently employed for homogeneous bulk materials, into the mesoscale, to fully describe thermal transport from the electronic ab initio level, through the atomistic one, all the way into the mesoscopic structure level. BoltzTraP is a program for calculating the semi-classic transport coefficients. BoltzTrap2 is a modern implementation of the smoothed Fourier interpolation algorithm for electronic bands that formed the base of the original and widely used BoltzTraP code. One of the most typical uses of BoltzTraP is the calculation of thermoelectric transport coefficients as functions of temperature and chemical potential in the rigid-band picture. However, many other features are available, including 3D plots of Fermi surfaces based on the reconstructed bands. EMC (''Effective Mass Calculator'') implements calculation of the effective masses at the bands extrema using finite difference method. There are two versions of the program: written in FORTRAN and Python.","title":"Transport"},{"location":"documentation/Tools/tools/#miscellaneous","text":"ASE is a set of tools and Python modules for setting up, manipulating, running, visualizing and analyzing atomistic simulations. The code is freely available under the GNU LGPL license. It can interface with many different electronic structure codes. Bader is a tool to perform Bader charge analysis on a charge density grid. Typically in molecular systems, the charge density reaches a minimum between atoms and this is a natural place to separate atoms from each other. Besides being an intuitive scheme for visualizing atoms in molecules, Bader's definition is often useful for charge analysis. For example, the charge enclosed within the Bader volume is a good approximation to the total electronic charge of an atom. ATAT (Alloy Theoretic Automated Toolkit) is a collection of alloy theory tools developed by Axel van de Walle. CASINO is a computer program system for performing quantum Monte Carlo (QMC) electronic structure calculations that has been developed by members of the Theory of Condensed Matter group in the Cambridge University physics department, and their collaborators, over more than 20 years. It is capable of calculating incredibly accurate solutions to the Schr\u00f6dinger equation of quantum mechanics for realistic systems built from atoms. An interface castep2casino is supplied with the CASTEP distribution. Emacs mode (part of CASTEP distribution) is an emacs major mode for CASTEP input files with datatype based syntax highlighting and inbuilt help functionality. i-PI is a package for performing molecular dynamics and path-integral MD via a unix socket driver interface. More details elsewhere in this site.","title":"Miscellaneous"},{"location":"documentation/Tools/tools/#commercial-codes","text":"BIOVIA Materials Studio is a suite of graphical tools and codes for quantum and classical simulation of materials, and is how CASTEP is distributed commercially.","title":"Commercial Codes"},{"location":"documentation/Transition_State_Search/neb/","text":"Note The NEB functionality in CASTEP was overhauled in version 22, with more efficient algorithms available. In order to use this new functionality, make sure you're **using CASTEP 22 or later**. Background and theory The nudged elastic band method is a widely-used method for finding a minimum energy pathway between two structures. You can use the method to estimate the barrier for the system to transition between the two structures. In our NEB implementation the update rule for atomic position is given by: x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] where x^{k}_n x^{k}_n are the positions of image n n at iteration k k . \\alpha^k \\alpha^k is the step size, which can either be fixed or chosen in an adaptive manner, \\nabla^\\perp V(x^{k}_n) \\nabla^\\perp V(x^{k}_n) is the gradient of the total energy, projected to remove the component along the reaction path, and \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') is the NEB spring force. As a consequence of the projection step, the NEB forces do not have a corresponding energy functional and hence linesearch is not possible, making quasi-Newton searches such as (L)BFGS inapplicable. Standard approaches are either to use simple gradient-only based methods or to add a maximum step size constraint in place of the linesearch. Both of these can exhibit slow convergence; a solution is instead to choose the step size adaptively using a custom time-stepping algorithm. A promising solution to this problem is the ODE12r adaptive scheme 1 , which combines two distinct step selection criteria: one based on minimising the change in the residual force from one step to the next as is typically done to control error in adaptive ODE solvers, and a second based on minimising the residual itself. The key idea is that adaptive ODE step selection should be used in the pre-asymptotic regime, while minimising the residual is suitable in the asymptotic regime. We have implemented three optimisation schemes for NEB paths, with the approach to be used controlled by the TSSEARCH_NEB_METHOD parameter: (i) the two point steepest descent scheme of Barzilai and Borwein 2 ; (ii) the fast inertial relaxation engine ( FIRE 3 ) and (iii) the ODE12R 1 scheme discussed above. In all three cases, convergence is controlled by the existing TSSEARCH_FORCE_TOL parameter. To better fit user intuition, the default value of this parameter is now equal to the force tolerance used during geometry optimisation, GEOM_FORCE_TOL . We also provide three alternative algorithms to compute the tangents (x^{k}_n)' (x^{k}_n)' and curvatures (x^{k}_n)'' (x^{k}_n)'' at each image along the path, controlled by the TSSEARCH_NEB_TANGENT_MODE parameter. The three approaches are based on bisection, the improved tangent scheme of FIRE 3 , and cubic spline interpolation as used in ODE12R 1 . The latter was found to be the most robust so has been made the default. Keywords As with other functionality in CASTEP, you can use the built-in help tool to find information on NEB-related keywords. For example, you could run: castep -s tssearch The relevant .param keywords are summarised in the table below: Parameter Default Level Notes TASK SINGLEPOINT Basic Set to TRANSITIONSTATESEARCH to perform a transition state calculation. TSSEARCH_METHOD LSTQST Basic The search method used to locate transition states. Must be set to NEB to perform a NEB calculation. Previous default retained for backwards compatibility. Modifiable: restart only. Allowed values: LSTQST , NEB Default value : LSTQST TSSEARCH_FORCE_TOL Same as GEOM_FORCE_TOL Basic Tolerance for accepting convergence of the maximum |ionic force| during QST search. Modifiable: restart and on the fly TSSEARCH_MAX_PATH_POINTS 20 Intermediate The maximum number of path points for NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_METHOD ODE12R 1 Intermediate Method used to optimize the NEB shape. Modifiable: restart and on the fly. Allowed values: GRAD_BB 2 , FIRE 3 , ODE12R 1 TSSEARCH_NEB_TANGENT_MODE SPLINE Basic Method used to calculate the tangents of the NEB. Modifiable: restart and on the fly. Allowed values: NONE , BISECT , HIGH_E , SPLINE TSSEARCH_NEB_SPRING_CONSTANT 0.1 eV/ang2 Basic Spring constant used between the images in NEB search. Modifiable: restart and on the fly. Allowed values: (any) > 0.0 TSSEARCH_NEB_CLIMBING FALSE Basic If TRUE then the central bead in NEB search climbs up the potential and TSSEARCH_MAX_PATH_POINTS must be odd (may be increased by +1). If FALSE then the central bead in NEB search slides down the potential. Modifiable: restart only. Allowed values: TRUE or FALSE. Default value: FALSE TSSEARCH_NEB_MAX_ITER 20 Intermediate The maximum number of steps during NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_NORMED FALSE if TSSEARCH_NEB_TANGENT_MODE = SPLINE , TRUE otherwise Expert If TRUE then the spring forces applied along the tangents in the NEB are normed to the displacement between beads. If FALSE then the spring forces are projected along the tangents in the NEB and may result in null forces if displacements are orthogonal to the NEB tangents. Modifiable: restart only. Allowed values: TRUE or FALSE As a minimum, you need to specify TASK: TRANSITIONSTATESEARCH and TSSEARCH_METHOD: NEB in the .param file and specify the product (final) ionic positions (using e.g. the POSITIONS_ABS_PRODUCT block) and a transition state guess configuration (using e.g. the POSITIONS_ABS_INTERMEDIATE block) in the .cell file, in addition to the normal POSITIONS_ABS block. CASTEP will then linearly interpolate from the initial to intermediate and from the intermediate to product configurations to begin the NEB calculation. However, it's advisable to also: change the number of images used ( TSSEARCH_MAX_PATH_POINTS ), decide on whether you want the climbing image method ( TSSEARCH_NEB_CLIMBING ), and think about the relevant force criterion to be used ( TSSEARCH_FORCE_TOL ). For a practical guide on how to use the NEB method in CASTEP, see the tutorial . Output files In addition to information in the .castep file, a .ts file will be generated during a transition state search calculation. Below is the start of a typical .ts file, with annotations explaing what each line means (you can see these by clicking on the ( ) symbols). Note Like `.geom` and `.md` files, `.ts` files use atomic units (Ha for energies, Bohr for distances and Bohr/Ha for forces etc.). TSTYPE TSConfirmation # (1)! REA 1 0.00000000E+000 # (2)! -1.19447739E+001 -1.19447739E+001 <-- E #(3)! 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h #(4)! 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61419707E+000 8.39780193E+000 5.86117838E+000 <-- R #(5)! H 2 8.15635294E+000 5.72185774E+000 5.85777350E+000 <-- R H 3 5.06964224E+000 5.72278559E+000 5.86095165E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 8.47021636E-007 3.11793289E-005 2.28609226E-005 <-- F #(6)! H 2 1.38512779E-006 -2.45087447E-005 -4.65186359E-005 <-- F H 3 -4.12781162E-005 -4.76763241E-006 1.75643331E-005 <-- F N 1 3.90459667E-005 -1.90295182E-006 6.09338019E-006 <-- F PRO 1 1.00000000E+000 #(7)! -1.19447351E+001 -1.19447351E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61608080E+000 8.39796599E+000 7.36585209E+000 <-- R H 2 8.15724653E+000 5.72090835E+000 7.36726384E+000 <-- R H 3 5.07119891E+000 5.72404366E+000 7.37171850E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 6.09749957E-005 4.97392811E-005 -4.85624696E-005 <-- F H 2 6.57602570E-005 -1.92918456E-005 -3.12188543E-005 <-- F H 3 -5.16484028E-005 2.80445001E-005 5.83274956E-005 <-- F N 1 -7.50868499E-005 -5.84919355E-005 2.14538282E-005 <-- F TST 1 1.25000056E-001 #(8)! -1.19415297E+001 -1.19415297E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61443264E+000 8.39782206E+000 6.04926187E+000 <-- R H 2 8.15646486E+000 5.72173929E+000 6.04646018E+000 <-- R H 3 5.06983587E+000 5.72294304E+000 6.04979810E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 -9.19085803E-006 2.32501273E-002 -1.04092397E-002 <-- F H 2 2.02903385E-002 -1.17660606E-002 -1.06346944E-002 <-- F H 3 -2.03961322E-002 -1.17795791E-002 -1.05604406E-002 <-- F N 1 1.14984498E-004 2.95512341E-004 3.16043747E-002 <-- F This is a comment line stating what type of calculation was carried out. This is the initial (i.e. the REA ctant) configuration. The integer indicates it is the configuration for the first NEB iteration. As the REActant (and PROduct) configurations are the same for every NEB iteration, they are only printed out once. The float at the end of the line is a measure of where the configuration lies between 0 (reactant) and 1 (product). <-- E is the total energy and enthalpy of the system, in atomic units. <-- h is the unit cell matrix (atomic units). <-- R are the atomic coordinates (Cartesian), in atomic units. <-- F are the forces (atomic units). This is the end-point (or PRO duct) configuration for the first iteration. As this is the same for every NEB iteration, it is only printed out once. This is the first of the transition state configurations (NEB images) for iteration 1 of the NEB. For example, if you have 7 images, then there will be 7 blocks that start with TST 1 . Stela Makri, Christoph Ortner, and James R. Kermode. A preconditioning scheme for minimum energy path finding methods. The Journal of Chemical Physics , 150(9):094109, 03 2019. doi:10.1063/1.5064465 . \u21a9 \u21a9 \u21a9 \u21a9 \u21a9 Jonathan Barzilai and Jonathan M. Borwein. Two-Point Step Size Gradient Methods. IMA Journal of Numerical Analysis , 8(1):141\u2013148, 01 1988. doi:10.1093/imanum/8.1.141 . \u21a9 \u21a9 Erik Bitzek, Pekka Koskinen, Franz G\u00e4hler, Michael Moseler, and Peter Gumbsch. Structural relaxation made simple. Phys. Rev. Lett. , 97:170201, Oct 2006. doi:10.1103/PhysRevLett.97.170201 . \u21a9 \u21a9 \u21a9","title":"Nudged Elastic Band"},{"location":"documentation/Transition_State_Search/neb/#background-and-theory","text":"The nudged elastic band method is a widely-used method for finding a minimum energy pathway between two structures. You can use the method to estimate the barrier for the system to transition between the two structures. In our NEB implementation the update rule for atomic position is given by: x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] x^{k+1}_{n} = x^{k}_n + \\alpha^k [-\\nabla^\\perp V(x^{k}_n) + \\mathbf{\\eta}^{k}_n] where x^{k}_n x^{k}_n are the positions of image n n at iteration k k . \\alpha^k \\alpha^k is the step size, which can either be fixed or chosen in an adaptive manner, \\nabla^\\perp V(x^{k}_n) \\nabla^\\perp V(x^{k}_n) is the gradient of the total energy, projected to remove the component along the reaction path, and \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') \\mathbf{\\eta}^{k}_n = \\mathbf{\\eta}((x^{k}_n)',(x^{k}_n)'') is the NEB spring force. As a consequence of the projection step, the NEB forces do not have a corresponding energy functional and hence linesearch is not possible, making quasi-Newton searches such as (L)BFGS inapplicable. Standard approaches are either to use simple gradient-only based methods or to add a maximum step size constraint in place of the linesearch. Both of these can exhibit slow convergence; a solution is instead to choose the step size adaptively using a custom time-stepping algorithm. A promising solution to this problem is the ODE12r adaptive scheme 1 , which combines two distinct step selection criteria: one based on minimising the change in the residual force from one step to the next as is typically done to control error in adaptive ODE solvers, and a second based on minimising the residual itself. The key idea is that adaptive ODE step selection should be used in the pre-asymptotic regime, while minimising the residual is suitable in the asymptotic regime. We have implemented three optimisation schemes for NEB paths, with the approach to be used controlled by the TSSEARCH_NEB_METHOD parameter: (i) the two point steepest descent scheme of Barzilai and Borwein 2 ; (ii) the fast inertial relaxation engine ( FIRE 3 ) and (iii) the ODE12R 1 scheme discussed above. In all three cases, convergence is controlled by the existing TSSEARCH_FORCE_TOL parameter. To better fit user intuition, the default value of this parameter is now equal to the force tolerance used during geometry optimisation, GEOM_FORCE_TOL . We also provide three alternative algorithms to compute the tangents (x^{k}_n)' (x^{k}_n)' and curvatures (x^{k}_n)'' (x^{k}_n)'' at each image along the path, controlled by the TSSEARCH_NEB_TANGENT_MODE parameter. The three approaches are based on bisection, the improved tangent scheme of FIRE 3 , and cubic spline interpolation as used in ODE12R 1 . The latter was found to be the most robust so has been made the default.","title":"Background and theory"},{"location":"documentation/Transition_State_Search/neb/#keywords","text":"As with other functionality in CASTEP, you can use the built-in help tool to find information on NEB-related keywords. For example, you could run: castep -s tssearch The relevant .param keywords are summarised in the table below: Parameter Default Level Notes TASK SINGLEPOINT Basic Set to TRANSITIONSTATESEARCH to perform a transition state calculation. TSSEARCH_METHOD LSTQST Basic The search method used to locate transition states. Must be set to NEB to perform a NEB calculation. Previous default retained for backwards compatibility. Modifiable: restart only. Allowed values: LSTQST , NEB Default value : LSTQST TSSEARCH_FORCE_TOL Same as GEOM_FORCE_TOL Basic Tolerance for accepting convergence of the maximum |ionic force| during QST search. Modifiable: restart and on the fly TSSEARCH_MAX_PATH_POINTS 20 Intermediate The maximum number of path points for NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_METHOD ODE12R 1 Intermediate Method used to optimize the NEB shape. Modifiable: restart and on the fly. Allowed values: GRAD_BB 2 , FIRE 3 , ODE12R 1 TSSEARCH_NEB_TANGENT_MODE SPLINE Basic Method used to calculate the tangents of the NEB. Modifiable: restart and on the fly. Allowed values: NONE , BISECT , HIGH_E , SPLINE TSSEARCH_NEB_SPRING_CONSTANT 0.1 eV/ang2 Basic Spring constant used between the images in NEB search. Modifiable: restart and on the fly. Allowed values: (any) > 0.0 TSSEARCH_NEB_CLIMBING FALSE Basic If TRUE then the central bead in NEB search climbs up the potential and TSSEARCH_MAX_PATH_POINTS must be odd (may be increased by +1). If FALSE then the central bead in NEB search slides down the potential. Modifiable: restart only. Allowed values: TRUE or FALSE. Default value: FALSE TSSEARCH_NEB_MAX_ITER 20 Intermediate The maximum number of steps during NEB search. Modifiable: restart and on the fly. Allowed values: (any integer) > 0 TSSEARCH_NEB_NORMED FALSE if TSSEARCH_NEB_TANGENT_MODE = SPLINE , TRUE otherwise Expert If TRUE then the spring forces applied along the tangents in the NEB are normed to the displacement between beads. If FALSE then the spring forces are projected along the tangents in the NEB and may result in null forces if displacements are orthogonal to the NEB tangents. Modifiable: restart only. Allowed values: TRUE or FALSE As a minimum, you need to specify TASK: TRANSITIONSTATESEARCH and TSSEARCH_METHOD: NEB in the .param file and specify the product (final) ionic positions (using e.g. the POSITIONS_ABS_PRODUCT block) and a transition state guess configuration (using e.g. the POSITIONS_ABS_INTERMEDIATE block) in the .cell file, in addition to the normal POSITIONS_ABS block. CASTEP will then linearly interpolate from the initial to intermediate and from the intermediate to product configurations to begin the NEB calculation. However, it's advisable to also: change the number of images used ( TSSEARCH_MAX_PATH_POINTS ), decide on whether you want the climbing image method ( TSSEARCH_NEB_CLIMBING ), and think about the relevant force criterion to be used ( TSSEARCH_FORCE_TOL ). For a practical guide on how to use the NEB method in CASTEP, see the tutorial .","title":"Keywords"},{"location":"documentation/Transition_State_Search/neb/#output-files","text":"In addition to information in the .castep file, a .ts file will be generated during a transition state search calculation. Below is the start of a typical .ts file, with annotations explaing what each line means (you can see these by clicking on the ( ) symbols). Note Like `.geom` and `.md` files, `.ts` files use atomic units (Ha for energies, Bohr for distances and Bohr/Ha for forces etc.). TSTYPE TSConfirmation # (1)! REA 1 0.00000000E+000 # (2)! -1.19447739E+001 -1.19447739E+001 <-- E #(3)! 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h #(4)! 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61419707E+000 8.39780193E+000 5.86117838E+000 <-- R #(5)! H 2 8.15635294E+000 5.72185774E+000 5.85777350E+000 <-- R H 3 5.06964224E+000 5.72278559E+000 5.86095165E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 8.47021636E-007 3.11793289E-005 2.28609226E-005 <-- F #(6)! H 2 1.38512779E-006 -2.45087447E-005 -4.65186359E-005 <-- F H 3 -4.12781162E-005 -4.76763241E-006 1.75643331E-005 <-- F N 1 3.90459667E-005 -1.90295182E-006 6.09338019E-006 <-- F PRO 1 1.00000000E+000 #(7)! -1.19447351E+001 -1.19447351E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61608080E+000 8.39796599E+000 7.36585209E+000 <-- R H 2 8.15724653E+000 5.72090835E+000 7.36726384E+000 <-- R H 3 5.07119891E+000 5.72404366E+000 7.37171850E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 6.09749957E-005 4.97392811E-005 -4.85624696E-005 <-- F H 2 6.57602570E-005 -1.92918456E-005 -3.12188543E-005 <-- F H 3 -5.16484028E-005 2.80445001E-005 5.83274956E-005 <-- F N 1 -7.50868499E-005 -5.84919355E-005 2.14538282E-005 <-- F TST 1 1.25000056E-001 #(8)! -1.19415297E+001 -1.19415297E+001 <-- E 1.32280829E+001 0.00000000E+000 0.00000000E+000 <-- h 8.09986468E-016 1.32280829E+001 0.00000000E+000 <-- h 8.09986468E-016 8.09986468E-016 1.32280829E+001 <-- h H 1 6.61443264E+000 8.39782206E+000 6.04926187E+000 <-- R H 2 8.15646486E+000 5.72173929E+000 6.04646018E+000 <-- R H 3 5.06983587E+000 5.72294304E+000 6.04979810E+000 <-- R N 1 6.61404144E+000 6.61404144E+000 6.61404144E+000 <-- R H 1 -9.19085803E-006 2.32501273E-002 -1.04092397E-002 <-- F H 2 2.02903385E-002 -1.17660606E-002 -1.06346944E-002 <-- F H 3 -2.03961322E-002 -1.17795791E-002 -1.05604406E-002 <-- F N 1 1.14984498E-004 2.95512341E-004 3.16043747E-002 <-- F This is a comment line stating what type of calculation was carried out. This is the initial (i.e. the REA ctant) configuration. The integer indicates it is the configuration for the first NEB iteration. As the REActant (and PROduct) configurations are the same for every NEB iteration, they are only printed out once. The float at the end of the line is a measure of where the configuration lies between 0 (reactant) and 1 (product). <-- E is the total energy and enthalpy of the system, in atomic units. <-- h is the unit cell matrix (atomic units). <-- R are the atomic coordinates (Cartesian), in atomic units. <-- F are the forces (atomic units). This is the end-point (or PRO duct) configuration for the first iteration. As this is the same for every NEB iteration, it is only printed out once. This is the first of the transition state configurations (NEB images) for iteration 1 of the NEB. For example, if you have 7 images, then there will be 7 blocks that start with TST 1 . Stela Makri, Christoph Ortner, and James R. Kermode. A preconditioning scheme for minimum energy path finding methods. The Journal of Chemical Physics , 150(9):094109, 03 2019. doi:10.1063/1.5064465 . \u21a9 \u21a9 \u21a9 \u21a9 \u21a9 Jonathan Barzilai and Jonathan M. Borwein. Two-Point Step Size Gradient Methods. IMA Journal of Numerical Analysis , 8(1):141\u2013148, 01 1988. doi:10.1093/imanum/8.1.141 . \u21a9 \u21a9 Erik Bitzek, Pekka Koskinen, Franz G\u00e4hler, Michael Moseler, and Peter Gumbsch. Structural relaxation made simple. Phys. Rev. Lett. , 97:170201, Oct 2006. doi:10.1103/PhysRevLett.97.170201 . \u21a9 \u21a9 \u21a9","title":"Output files"},{"location":"documentation/Troubleshooting/linux_path/","text":"Command not found When you type castep , Linux doesn't know where that command is, so it looks in the places where programs are usually put (often /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin ; \"bin\" here is short for \"binary\"). Unless CASTEP is there, it will tell you that it can't find it. Notice in particular that the directory you're in when you type the command is not in Linux's list of usual places to look, which is especially confusing when you first encounter it! Telling Linux where to find CASTEP There are several ways to fix this. If you're on a shared machine, it is usually best to make a subdirectory in your home directory, perhaps called \"bin\": mkdir ~/bin and put CASTEP in there (along with any other programs you compile yourself), e.g. cp ~/CASTEP-22.1/obj/linux_x86_64_gfortran--serial/castep.serial ~/bin This still won't mean that Linux will find CASTEP, because this is also not a place it will look for programs. The places Linux looks in are stored in a special Linux environment variable called the \"path\", and the final step is to add the new directory to this \"path\". Exactly how you do this depends on what kind of command-line interpreter (called a \"shell\") you're using in Linux, but there are only really two main kinds: bash and csh. Type export PATH=${PATH}:~/bin if you're using bash, or setenv PATH ${PATH}:~/bin if you're using csh. These commands tell Linux to look in all the places it's looking in already, and also \"~/bin\". If you don't know which shell you're using, try typing: echo $SHELL and see what it says. If it says something like \"/bin/bash\" then you're using bash, if it's \"/bin/csh\" or \"/bin/tcsh\" then it's csh (or close enough). If it gives something else, just try the line starting \"export\" and if it gives an error, try the \"setenv\" one instead. Now try typing \"castep.serial\" and you should see this: Usage: castep : Run files .cell [and .param] \" [-d|--dryrun] : Perform a dryrun calculation on files .cell \" [-s|--search] : print list of keywords with match in description \" [-v|--version] : print version information \" [-h|--help] : describe specific keyword in <>.cell or <>.param \" \" all : print list of all keywords \" \" basic : print list of basic-level keywords \" \" inter : print list of intermediate-level keywords \" \" expert : print list of expert-level keywords \" \" dummy : print list of dummy keywords Automatically adding to your PATH The changes so far will be lost when you exit the command-line. We need to make sure that your directory is added to the PATH variable every time you log in or open a new terminal. If you're using bash, edit the file ~/.bashrc with a text editor (e.g. gedit), go to the end, and add the line to set the PATH: export PATH=${PATH}:~/bin Note that the file is in your home directory (\"~/\"), and the name starts with a dot (\".\" a full stop). Save and exit, and it should all be set up for you. If you're using csh, edit the file \"~/.cshrc\" instead, and add the appropriate line to set the PATH: setenv PATH ${PATH}:~/bin Save and exit, and it should all be set up for you.","title":"Linux help"},{"location":"documentation/Troubleshooting/linux_path/#command-not-found","text":"When you type castep , Linux doesn't know where that command is, so it looks in the places where programs are usually put (often /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin and /usr/local/sbin ; \"bin\" here is short for \"binary\"). Unless CASTEP is there, it will tell you that it can't find it. Notice in particular that the directory you're in when you type the command is not in Linux's list of usual places to look, which is especially confusing when you first encounter it!","title":"Command not found"},{"location":"documentation/Troubleshooting/linux_path/#telling-linux-where-to-find-castep","text":"There are several ways to fix this. If you're on a shared machine, it is usually best to make a subdirectory in your home directory, perhaps called \"bin\": mkdir ~/bin and put CASTEP in there (along with any other programs you compile yourself), e.g. cp ~/CASTEP-22.1/obj/linux_x86_64_gfortran--serial/castep.serial ~/bin This still won't mean that Linux will find CASTEP, because this is also not a place it will look for programs. The places Linux looks in are stored in a special Linux environment variable called the \"path\", and the final step is to add the new directory to this \"path\". Exactly how you do this depends on what kind of command-line interpreter (called a \"shell\") you're using in Linux, but there are only really two main kinds: bash and csh. Type export PATH=${PATH}:~/bin if you're using bash, or setenv PATH ${PATH}:~/bin if you're using csh. These commands tell Linux to look in all the places it's looking in already, and also \"~/bin\". If you don't know which shell you're using, try typing: echo $SHELL and see what it says. If it says something like \"/bin/bash\" then you're using bash, if it's \"/bin/csh\" or \"/bin/tcsh\" then it's csh (or close enough). If it gives something else, just try the line starting \"export\" and if it gives an error, try the \"setenv\" one instead. Now try typing \"castep.serial\" and you should see this: Usage: castep : Run files .cell [and .param] \" [-d|--dryrun] : Perform a dryrun calculation on files .cell \" [-s|--search] : print list of keywords with match in description \" [-v|--version] : print version information \" [-h|--help] : describe specific keyword in <>.cell or <>.param \" \" all : print list of all keywords \" \" basic : print list of basic-level keywords \" \" inter : print list of intermediate-level keywords \" \" expert : print list of expert-level keywords \" \" dummy : print list of dummy keywords","title":"Telling Linux where to find CASTEP"},{"location":"documentation/Troubleshooting/linux_path/#automatically-adding-to-your-path","text":"The changes so far will be lost when you exit the command-line. We need to make sure that your directory is added to the PATH variable every time you log in or open a new terminal. If you're using bash, edit the file ~/.bashrc with a text editor (e.g. gedit), go to the end, and add the line to set the PATH: export PATH=${PATH}:~/bin Note that the file is in your home directory (\"~/\"), and the name starts with a dot (\".\" a full stop). Save and exit, and it should all be set up for you. If you're using csh, edit the file \"~/.cshrc\" instead, and add the appropriate line to set the PATH: setenv PATH ${PATH}:~/bin Save and exit, and it should all be set up for you.","title":"Automatically adding to your PATH"},{"location":"documentation/Troubleshooting/troubleshooting/","text":"CASTEP fails to start Command not found If you see a message like this on the command-line when you run CASTEP: castep mytest castep: command not found then your computer has not located the CASTEP program. Check that: you've used the correct CASTEP name ( castep.serial or castep.mpi ) the CASTEP program is somewhere your computer expects programs to be See here for details of where Linux looks for programs, and how to change it. CASTEP aborts a calculation If CASTEP detects a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error messages from each of these cores. They are named using the same seedname, but with the process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them. Failed to converge","title":"Common errors"},{"location":"documentation/Troubleshooting/troubleshooting/#castep-fails-to-start","text":"","title":"CASTEP fails to start"},{"location":"documentation/Troubleshooting/troubleshooting/#command-not-found","text":"If you see a message like this on the command-line when you run CASTEP: castep mytest castep: command not found then your computer has not located the CASTEP program. Check that: you've used the correct CASTEP name ( castep.serial or castep.mpi ) the CASTEP program is somewhere your computer expects programs to be See here for details of where Linux looks for programs, and how to change it.","title":"Command not found"},{"location":"documentation/Troubleshooting/troubleshooting/#castep-aborts-a-calculation","text":"If CASTEP detects a serious problem, it will stop and write an error message to a .err file. If you are using the parallel version of CASTEP on many cores, you may see error messages from each of these cores. They are named using the same seedname, but with the process ID added, e.g. if CASTEP is run on 2 cores and a serious problem occurs, you might see the files mytest.0001.err mytest.0002.err These files contain useful information about what went wrong, so it is always worth looking at them.","title":"CASTEP aborts a calculation"},{"location":"documentation/Troubleshooting/troubleshooting/#failed-to-converge","text":"","title":"Failed to converge"},{"location":"documentation/XC/XC/","text":"The exchange and correlation functional used for calculations in CASTEP can be specified in one of two main ways. xc_functional The most straightforward is with the .param file keyword xc_functional . For example to use the PBE functional in the .param file simply use xc_functional : PBE There are a number of standard functionals that can be used in CASTEP with the xc_functional keyword: Local density approximation: LDA LDA-X LDA-C Generalised gradient approximations (GGA): PW91 PBE PBEsol RPBE WC BLYP B86PBE PBE_X PBE_C PBEsol_X PBEsol_C B88_X LYP_C Hybrid (non-local) functionals: HF SHF-LDA PBE0 B3LYP HSE03 HSE06 SPBE0 Meta-GGA functionals: RSCAN MS2 xc_definition The keyword xc_definition in the .param file (used instead of xc_functional) is used when you want to modify the standard behaviour of hybrid functionals, or if you want to construct your own hybrid functionals. The simplest use of xc_definition is to replicate that of xc_functional , for example %block xc_definition PBE 1.0 %endblock xc_definition is the same as xc_functional : PBE The \"1.0\" is what weighted fraction of the functional you want, so in this case 1.0 (i.e. 100% PBE). Recall that hybrids are (usually) a mixture of pure (or screened) non-local Hartree-Fock exchange, some local exchange and local correlation. So you could, for example, build a functional that could be 20% Hartree Fock, 80% LDA exchange and 100% LDA correlation. You can run a CASTEP calculation with this using %block xc_definition HF 0.2 LDA-X 0.8 LDA-C 1.0 %endblock xc_definition Examples: 1. B3LYP Firstly you cansimply use xc_functional : B3LYP , however B3LYP is a hybrid functional consisting of a mixture of Hartree-Fock, LDA and B88 exchange, LYP and LDA correlation. This functional can be specified component by component: %block xc_definition LDA-X 0.08 B88_X 0.72 LYP_C 0.81 LDA-C 0.19 HF 0.20 %endblock xc_definition Using the full specification in xc_definition makes it straightforward to adjust the various component weightings to your own specification. There are other adjustments that can be made within the functional. For example the popular functional HSE06 contains a screened Hartree-Fock component, with a mixture of other local functionals. It can be specified component by component as %block xc_definition SHF 0.25 PBE 1.0 PBE_X_SR -0.25 NLXC_SCREENING_LENGTH 0.11 NLXC_SCREENING_FUNCTION ERRORFUNCTION %endblock xc_definition In this case we have 25% screened Hartree-Fock offsetting -25% screened PBE exchange (and 100% PBE correlation within PBE). The default HF screening is exponential, but this can be changed to an error function as shown in the block. Also the strength of the screening can be altered by the NLXC_SCREENING_LENGTH parameter (natural units). 2. Hybrid functionals are expensive calculations, much(!) more computationally intensive than (semi-)local functionals. They are often used because they are able to give much better electronic band gaps. If we do LDA and SHF-LDA band structure for silicon we can use the cell file %block lattice_cart 2.7 2.7 0.0 2.7 0.0 2.7 0.0 2.7 2.7 %endblock lattice_cart %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac symmetry_generate %block spectral_kpoint_path W G X W L G %endblock spectral_kpoint_path %block species_pot NCP %endblock species_pot and then the .param file for LDA task : spectral spectral_task : BandStructure xc_functional : lda and for screened exchange, task : spectral spectral_task : BandStructure xc_functional : shf-lda If we then plot these two band structures together, the difference in results can be seen, the band gap opens from the LDA value of around 0.5eV to a more realistic 1.","title":"Controlling XC"},{"location":"documentation/XC/XCoverview/","text":"There are many sources of description of the role of exchange and correlation within density functional theory, https://en.wikipedia.org/wiki/Density_functional_theory Here we will look at how to give both a basic control over the XC functional that your calculation will use and well as giving finer control over functionals that have free parameters.","title":"Overview"},{"location":"documentation/XC/libXC/","text":"There are many (many!) XC functionals (of varying quality and applicability). LIBXC ( https://www.tddft.org/programs/libxc/ ) is a maintained library of functionals that is upgraded regularly. The list of functionals available in LIBXC is at https://www.tddft.org/programs/libxc/functionals/ . CASTEP interfaces to this library which can be used instead of CASTEP's in-built library of XC functionals. Prepend the string LIBXC_ to CASTEP's functional name in the parameter keyword xc_functional to use LIBXC. For example: xc_functional : PBE for CASTEP's in-built PBE functional xc_functional : LIBXC_PBE for the LIBXC version of the PBE functional In the LIBXC library there are many functionals, covering LDAs, GGAs, Meta-GGAs, Hybrids, etc. Most of these are separated into exchange and correlation contributions. To use these functionals, build your own combination using CASTEP's xc_definition keyword in the .param file. Firstly at https://www.tddft.org/programs/libxc/functionals/ find the exchange and correlation functionals that you require, note the name LIBXC calls is and then prepend the string LIBXC_ to them. For example to construct Perdew and Zunger's LDA, LDA exchange is called LDA_X and correlation is called LDA_C_PZ. In the .param file use %block xc_definition LIBXC_LDA_X 1.0 LIBXC_LDA_C_PZ 1.0 %endblock xc_definition The \"1.0\" after each is the fraction of how much of each you require to use, in this case 100% of each. Example, construct the PBE functional from LIBXC: In LIBXC, PBE exchange is called GGA_X_PBE and its correlation is called GGA_C_PBE. Prepend with LIBXC_ and construct xc_definition : %block xc_definition LIBXC_GGA_X_PBE 1.0 LIBXC_GGA_C_PBE 1.0 %endblock xc_definition There are a few functional in LIBXC that have combined exchange and correlation parts, so this can be listed in xc_definition on its own. For example the HCTH93 XC functional is called GGA_XC_HCTH_93 in LIBXC hence it can be used in CASTEP with %block xc_definition LIBXC_GGA_XC_HCTH_93 1.0 %endblock xc_definition LIBXC can also be used to construct hybrid (non-local) functionals that contain (screened) Hartree-Fock components. Note that LIBXC does not contain the non-local part of such functionals, just the local part. Construct the functional using CASTEP's non-local functionality. For example, the PBE0 functional is called HYB_GGA_XC_PBE0 in LIBXC, so to construct this use %block xc_definition LIBXC_HYB_GGA_XC_PBE0 1.0 HF 0.25 %endblock xc_definition Note here you need to know (ie. read the HYB_GGA_XC_PBE0 reference given in https://www.tddft.org/programs/libxc/functionals/ ) what fraction of local exchange is in the functional and so infer what the fraction of non-local exchange is required (here 0.25). If you want to vary the fraction of non-local exchange then you need to balance this with offsetting it with the correct fraction of local exchange. For this construct the whole functional yourself. For example PBE0 is 0.25HF + 0.75PBE_X + 1.0PBE_C. Varying the HF component in PBE0 can be done with %block xc_definition HF 0.20 LIBXC_GGA_PBE_X 0.80 LIBXC_GGA_PBE_C_1.0 %endblock xc_definition where here it's set to 20% non-local and 80% local exchange, with 100% PBE correlation. Meta-GGAs are also supported. For example the RSCAN functional can be used with %block xc_definition LIBXC_MGGA_X_RSCAN 1.0 LIBXC_MGGA_C_RSCAN 1.0 %endblock xc_definition (although RSCAN is also natively supported in CASTEP with xc_functional : RSCAN ). The xc_definition keyword in the .param file will allow you to mix and match any of the hundreds of functionals in LIBXC https://www.tddft.org/programs/libxc/functionals/ . DO SO WITH EXTREME CAUTION!","title":"libXC"},{"location":"documentation/XRD/overview/","text":"X-ray Structure Factors Basic Theory The X-ray structure factor (SF) intensities can be measured by diffraction experiments involving either X-rays, \\gamma \\gamma -rays or electron beams. It is directly related to the electron density within the unit cell of a material, n(\\mathbf{r}) n(\\mathbf{r}) , by a Fourier transformation 1 : F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, where \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* is the scattering vector corresponding to the (hkl) (hkl) plane, with \\mathbf{a}^*, \\mathbf{b}^* \\mathbf{a}^*, \\mathbf{b}^* and \\mathbf{c}^* \\mathbf{c}^* being the reciprocal lattice vectors of the conventional unit cell. Computation of the SF is difficult within plane-wave pseudopotential DFT codes since the total \"all-electron'' electron density is not normally directly computed and the FFT grids used to house the pseudised valence electron density do not have enough spatial resolution to capture the rapid oscillations near the atomic cores of the total electron density, requiring large plane-wave energy cutoffs in the order of several thousands of eV. Within CASTEP, we have developed an efficient and accurate approach towards calculating these SFs without having to move to large FFT grids or plane-wave energy cutoffs. Details of this implementation can be found in the paper (CITE PAPER WHEN PUBLISHED) but the key observation that has enabled this development is that the electron density can be separated into atom-centred contributions which can be treated on separate radial grids. The resulting structure factor has the form 2 : F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), where f_j(\\mathbf{H}) f_j(\\mathbf{H}) is an effective atomic scattering factor of atom j j within the unit cell, defined to be the Fourier transform of its effective atomic density \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) : f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. Incorporating Thermal Effects Within experiments, thermal vibrations (i.e. phonons) can modify the (time-averaged) electron density and, hence, SFs. Making the approximation that the electron density assigned to each atom \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) directly follows its nuclear motion perfectly, the structure factors can incorporate these thermal vibration effects by including an atomic temperature factor T(\\mathbf{H}) T(\\mathbf{H}) : F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). Taking the vibrations of an atom to follow that of a harmonic oscillator, the temperature factor can be shown to be of the form: T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), where \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle are the averaged, squared, thermal displacements of the atom. For the case where the vibrations are isotropic, this equation reduces to: T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), where B is termed the Debye-Waller factor. Keywords Currently, to enable CASTEP (versions 21 and beyond) to calculate X-ray SFs, the desired SFs must be placed between CALCULATE_XRD_SF: and :ENDCALCULATE_XRD_SF within the devel_code block of the seed.param file. For example, the (111) (111) and (200) (200) and (220) (220) SFs can be calculated by appending the following code to the end of the seed.param file: %block devel_code CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, if no structure factors are listed, as in: %block devel_code CALCULATE_XRD_SF: :ENDCALCULATE_XRD_SF %endblock devel_code then the SFs on the entire FFT grid will be written out. Thermal effects can also be incoporated by placing the desired atomic Debye-Waller (DW) factors between DW_FACTOR: and :ENDDW_FACTOR within the devel_code block of the seed.param file. For isotropic DW factors, the value of the DW factor can be written next to the corresponding atomic symbol as below: %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, the entire anisotropic displacement tensor of each atomic species may be specified as follows: %block devel_code DW_FACTOR: Mg 0.305 0.000 0.000 0.000 0.305 0.000 0.000 0.000 0.305 O 0.340 0.000 0.000 0.000 0.340 0.000 0.000 0.000 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Note Structure factor calculations are a post-processing calculation, so they can be restarted from a previous DFT calculation's .check file by using the CONTINUATION parameter in CASTEP. Output Files The resulting structure factors that have been calculated will be outputted into a file named seed.xrd_sf . For the following inputs: ! MgO.param xc_functional : PBE %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 0 0 2 0 2 2 :ENDCALCULATE_XRD_SF %endblock devel_code ! MgO.cell %BLOCK LATTICE_CART ang 4.2112 0.0 0.0 0.0 4.2112 0.0 0.0 0.0 4.2112 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Mg 0.00 0.00 0.00 Mg 0.50 0.50 0.00 Mg 0.50 0.00 0.50 Mg 0.00 0.50 0.50 O 0.00 0.50 0.00 O 0.50 0.00 0.00 O 0.00 0.00 0.50 O 0.50 0.50 0.50 %ENDBLOCK POSITIONS_FRAC kpoint_mp_grid 8 8 8 SYMMETRY_GENERATE We get a resulting seed.xrd_sf file with the output: h k l Re(F_PAW) Im(F_PAW) Re(F_IAM) Im(F_IAM) Re(F_PP) Im(F_PP) Re(F_core) Im(F_core) Re(F_soft) Im(F_soft) Re(F_aug) Im(F_aug) 1 1 1 11.115757 -0.000000 12.492143 -0.000000 10.926445 -0.000000 0.085890 -0.000000 -9.892234 0.000000 20.922101 -0.000000 0 0 2 52.877502 0.000000 51.830521 -0.000000 52.626486 0.000000 15.464656 -0.000000 15.585172 -0.000000 21.827675 0.000000 0 2 2 41.051122 0.000000 40.948429 -0.000000 40.609195 0.000000 14.950468 -0.000000 7.954567 -0.000000 18.146087 0.000000 After the header, the structure factors are listed along each row based on the order in which they have been listed in the seed.param file. Across the columns along each row, the h, k,l h, k,l vectors are first listed before the real and imaginary components of the SF are listed under Re(F_PAW) and Im(F_PAW) respectively. Several other (less accurate) SFs that are commonly found in literature as well as charge contributions to F_PAW are also listed in columns further to the right, as described below: Label Description F_PAW DFT structure factor with all-electron augmentation charge F_IAM Indepedent atom model structure factor; electron densit formed from superposition of atomic electron densities obtained by numerically solving the Koelling-Harmon equation F_PP DFT structure factor with pseudised (inaccurate) augmentation charge F_core Structure factor contribution to F_PAW due to the (frozen) core electrons F_soft Structure factor contribution to F_PAW due to the soft valence charge (where augmentation charge contribute is removed) F_aug Structure factor contribution due to the all-electron valence augmentation charge Philip Coppens. X-ray charge densities and chemical bonding . Volume 4. International Union of Crystallography, 1997. \u21a9 U. Shmueli and Internationale Union f\u00fcr Kristallographie, editors. International Tables for Crystallography . Volume B: Reciprocal Space. Kluwer Acad. Publ, Dordrecht, 2. edition, 2001. \u21a9","title":"XRD"},{"location":"documentation/XRD/overview/#x-ray-structure-factors","text":"","title":"X-ray Structure Factors"},{"location":"documentation/XRD/overview/#basic-theory","text":"The X-ray structure factor (SF) intensities can be measured by diffraction experiments involving either X-rays, \\gamma \\gamma -rays or electron beams. It is directly related to the electron density within the unit cell of a material, n(\\mathbf{r}) n(\\mathbf{r}) , by a Fourier transformation 1 : F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, F(\\mathbf{H}) = \\mathcal{F}[n(\\mathbf{r})] = \\int_\\textrm{unit cell} n(\\mathbf{r})\\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}\\mathbf{r}, where \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* \\mathbf{H} = h \\mathbf{a}^* + k \\mathbf{b}^* + l\\mathbf{c}^* is the scattering vector corresponding to the (hkl) (hkl) plane, with \\mathbf{a}^*, \\mathbf{b}^* \\mathbf{a}^*, \\mathbf{b}^* and \\mathbf{c}^* \\mathbf{c}^* being the reciprocal lattice vectors of the conventional unit cell. Computation of the SF is difficult within plane-wave pseudopotential DFT codes since the total \"all-electron'' electron density is not normally directly computed and the FFT grids used to house the pseudised valence electron density do not have enough spatial resolution to capture the rapid oscillations near the atomic cores of the total electron density, requiring large plane-wave energy cutoffs in the order of several thousands of eV. Within CASTEP, we have developed an efficient and accurate approach towards calculating these SFs without having to move to large FFT grids or plane-wave energy cutoffs. Details of this implementation can be found in the paper (CITE PAPER WHEN PUBLISHED) but the key observation that has enabled this development is that the electron density can be separated into atom-centred contributions which can be treated on separate radial grids. The resulting structure factor has the form 2 : F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), F(\\mathbf{H}) = \\sum_{j} f_{j} (\\mathbf{H}) \\exp(i 2\\pi \\mathbf{H} \\cdot \\mathbf{r}_{j}), where f_j(\\mathbf{H}) f_j(\\mathbf{H}) is an effective atomic scattering factor of atom j j within the unit cell, defined to be the Fourier transform of its effective atomic density \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) : f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}. f_j (\\mathbf{H}) = \\int \\rho_j (\\mathbf{r}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}) \\mathrm{d}{\\mathbf{r}}.","title":"Basic Theory"},{"location":"documentation/XRD/overview/#incorporating-thermal-effects","text":"Within experiments, thermal vibrations (i.e. phonons) can modify the (time-averaged) electron density and, hence, SFs. Making the approximation that the electron density assigned to each atom \\rho_j(\\mathbf{r}) \\rho_j(\\mathbf{r}) directly follows its nuclear motion perfectly, the structure factors can incorporate these thermal vibration effects by including an atomic temperature factor T(\\mathbf{H}) T(\\mathbf{H}) : F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). F(\\mathbf{H}) = \\sum_j T_j(\\mathbf{H}) f_j (\\mathbf{H}) \\exp(i 2 \\pi \\mathbf{H} \\cdot \\mathbf{r}_j). Taking the vibrations of an atom to follow that of a harmonic oscillator, the temperature factor can be shown to be of the form: T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{1}{4} \\mathbf{H}^\\mathbf{T} \\mathbf{B} \\mathbf{H} \\right), where \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\mathbf{B}^{jk} = 8 \\pi^2 \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle \\langle u^j u^k \\rangle are the averaged, squared, thermal displacements of the atom. For the case where the vibrations are isotropic, this equation reduces to: T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), T(\\mathbf{H}) = \\exp \\left(-\\frac{B |\\mathbf{H}|^2}{4} \\right), where B is termed the Debye-Waller factor.","title":"Incorporating Thermal Effects"},{"location":"documentation/XRD/overview/#keywords","text":"Currently, to enable CASTEP (versions 21 and beyond) to calculate X-ray SFs, the desired SFs must be placed between CALCULATE_XRD_SF: and :ENDCALCULATE_XRD_SF within the devel_code block of the seed.param file. For example, the (111) (111) and (200) (200) and (220) (220) SFs can be calculated by appending the following code to the end of the seed.param file: %block devel_code CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, if no structure factors are listed, as in: %block devel_code CALCULATE_XRD_SF: :ENDCALCULATE_XRD_SF %endblock devel_code then the SFs on the entire FFT grid will be written out. Thermal effects can also be incoporated by placing the desired atomic Debye-Waller (DW) factors between DW_FACTOR: and :ENDDW_FACTOR within the devel_code block of the seed.param file. For isotropic DW factors, the value of the DW factor can be written next to the corresponding atomic symbol as below: %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Alternatively, the entire anisotropic displacement tensor of each atomic species may be specified as follows: %block devel_code DW_FACTOR: Mg 0.305 0.000 0.000 0.000 0.305 0.000 0.000 0.000 0.305 O 0.340 0.000 0.000 0.000 0.340 0.000 0.000 0.000 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 2 0 0 2 2 0 :ENDCALCULATE_XRD_SF %endblock devel_code Note Structure factor calculations are a post-processing calculation, so they can be restarted from a previous DFT calculation's .check file by using the CONTINUATION parameter in CASTEP.","title":"Keywords"},{"location":"documentation/XRD/overview/#output-files","text":"The resulting structure factors that have been calculated will be outputted into a file named seed.xrd_sf . For the following inputs: ! MgO.param xc_functional : PBE %block devel_code DW_FACTOR: Mg 0.305 O 0.340 :ENDDW_FACTOR CALCULATE_XRD_SF: 1 1 1 0 0 2 0 2 2 :ENDCALCULATE_XRD_SF %endblock devel_code ! MgO.cell %BLOCK LATTICE_CART ang 4.2112 0.0 0.0 0.0 4.2112 0.0 0.0 0.0 4.2112 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Mg 0.00 0.00 0.00 Mg 0.50 0.50 0.00 Mg 0.50 0.00 0.50 Mg 0.00 0.50 0.50 O 0.00 0.50 0.00 O 0.50 0.00 0.00 O 0.00 0.00 0.50 O 0.50 0.50 0.50 %ENDBLOCK POSITIONS_FRAC kpoint_mp_grid 8 8 8 SYMMETRY_GENERATE We get a resulting seed.xrd_sf file with the output: h k l Re(F_PAW) Im(F_PAW) Re(F_IAM) Im(F_IAM) Re(F_PP) Im(F_PP) Re(F_core) Im(F_core) Re(F_soft) Im(F_soft) Re(F_aug) Im(F_aug) 1 1 1 11.115757 -0.000000 12.492143 -0.000000 10.926445 -0.000000 0.085890 -0.000000 -9.892234 0.000000 20.922101 -0.000000 0 0 2 52.877502 0.000000 51.830521 -0.000000 52.626486 0.000000 15.464656 -0.000000 15.585172 -0.000000 21.827675 0.000000 0 2 2 41.051122 0.000000 40.948429 -0.000000 40.609195 0.000000 14.950468 -0.000000 7.954567 -0.000000 18.146087 0.000000 After the header, the structure factors are listed along each row based on the order in which they have been listed in the seed.param file. Across the columns along each row, the h, k,l h, k,l vectors are first listed before the real and imaginary components of the SF are listed under Re(F_PAW) and Im(F_PAW) respectively. Several other (less accurate) SFs that are commonly found in literature as well as charge contributions to F_PAW are also listed in columns further to the right, as described below: Label Description F_PAW DFT structure factor with all-electron augmentation charge F_IAM Indepedent atom model structure factor; electron densit formed from superposition of atomic electron densities obtained by numerically solving the Koelling-Harmon equation F_PP DFT structure factor with pseudised (inaccurate) augmentation charge F_core Structure factor contribution to F_PAW due to the (frozen) core electrons F_soft Structure factor contribution to F_PAW due to the soft valence charge (where augmentation charge contribute is removed) F_aug Structure factor contribution due to the all-electron valence augmentation charge Philip Coppens. X-ray charge densities and chemical bonding . Volume 4. International Union of Crystallography, 1997. \u21a9 U. Shmueli and Internationale Union f\u00fcr Kristallographie, editors. International Tables for Crystallography . Volume B: Reciprocal Space. Kluwer Acad. Publ, Dordrecht, 2. edition, 2001. \u21a9","title":"Output Files"},{"location":"tutorials/Bands_and_DOS/magnetic/","text":"Iron ! Fe.cell %BLOCK LATTICE_CART -1.433199999999999 1.433200000000001 1.433200000000001 1.433200000000001 -1.433200000000000 1.433200000000000 1.433200000000000 1.433200000000000 -1.433200000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Fe 0.0000000000000000 0.0000000000000000 0.0000000000000000 %ENDBLOCK POSITIONS_FRAC symmetry_generate ! Kpoint grid for the Groundstate (SCF) calculation kpoint_mp_grid 8 8 8 ! kpoint path through the Brillouin Zone for the Bandstructure %BLOCK spectral_KPOINT_PATH 0.0 0.0 0.0 !G 0.5 0.5 0.5 !H 0.5 0.0 0.0 !N 0.0 0.0 0.0 !G 0.75 0.25 -0.25 !P 0.5 0.0 0.0 !N %ENDBLOCK spectral_KPOINT_PATH In the param file we set spin_polarised true in order to allow the up and down spin electrons to take different configurations. It is important to start the calculation with an initial spin density using e.g. spin: 1 . The value of the initial spin should not affect the final answer - a non-zero value is just needed to break the symmetry between the spin channels. ! Fe.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! grid_scale 2.0 ! opt_strategy speed ! Choose algorithms for best speed spin 1 ! Set the spin in the original cell to 1. spin_polarised true ! Run a spin polarised calculation spectral_nbands 6 ! number of bands to compute during the BS run At the end of the calculation the net spin of the unit cell is reported in the castep file e.g. Integrated Spin Density = 2.15322 hbar/2 Note The band structure has similarities with that of Copper - and other 3d elements - with flat 3d bands and dispersive s bands. We colour code the bands according to their spin chactacter (red=up, blue=down). We can see that there is an almost constant exchange splitting of 1.5eV between the up and down 3d bands. The splitting between the s-like bands is much smaller. More up states lie below the fermi energy than down states - hence the net spin of the unit cell. FeO FeO is an anti-ferromagnetic oxide. We set up the calculation with initial spins on the two Fe atoms pointing in opposite directions. ! FeO.cell %BLOCK LATTICE_CART 1.768531594289456 0.000000000000001 5.002162732258922 -0.884265797144728 1.531593288050063 5.002162732258921 -0.884265797144728 -1.531593288050063 5.002162732258922 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC O 0.75 0.750 -1.250 O -0.75 -0.750 1.250 Fe 0.00 0.000 -0.000 spin=-4.0 Fe 1.50 -0.500 -0.500 spin=4.0 %ENDBLOCK POSITIONS_FRAC kpoints_mp_grid: 6 6 6 symmetry_generate %block spectral_kpoint_path 0.500 0.500 0.000 0.000 0.000 0.000 0.500 0.500 0.500 0.000 0.500 0.000 0.000 0.000 0.000 %endblock spectral_kpoint_path ! FeO.param task : spectral ! The TASK keyword instructs CASTEP what to do xc_functional : PBE ! Which exchange-correlation functional to use. cutoff_energy 600 eV opt_strategy speed ! Choose algorithms for speed. nextra_bands : 6 spin_polarized : true A PBE calculation incorrectly finds FeO to be a metal (bandstructure on left below). Add the following to the cell file to run a PBE+U calculation %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u FeO band structure with PBE (left) and with PBE+U (right) Note Adding a Hubbard U term to the calculation opens the band gap and FeO is (correctly) predicted to be an antiferromangetic insulator.","title":"Magnetic Materials"},{"location":"tutorials/Bands_and_DOS/magnetic/#iron","text":"! Fe.cell %BLOCK LATTICE_CART -1.433199999999999 1.433200000000001 1.433200000000001 1.433200000000001 -1.433200000000000 1.433200000000000 1.433200000000000 1.433200000000000 -1.433200000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Fe 0.0000000000000000 0.0000000000000000 0.0000000000000000 %ENDBLOCK POSITIONS_FRAC symmetry_generate ! Kpoint grid for the Groundstate (SCF) calculation kpoint_mp_grid 8 8 8 ! kpoint path through the Brillouin Zone for the Bandstructure %BLOCK spectral_KPOINT_PATH 0.0 0.0 0.0 !G 0.5 0.5 0.5 !H 0.5 0.0 0.0 !N 0.0 0.0 0.0 !G 0.75 0.25 -0.25 !P 0.5 0.0 0.0 !N %ENDBLOCK spectral_KPOINT_PATH In the param file we set spin_polarised true in order to allow the up and down spin electrons to take different configurations. It is important to start the calculation with an initial spin density using e.g. spin: 1 . The value of the initial spin should not affect the final answer - a non-zero value is just needed to break the symmetry between the spin channels. ! Fe.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! grid_scale 2.0 ! opt_strategy speed ! Choose algorithms for best speed spin 1 ! Set the spin in the original cell to 1. spin_polarised true ! Run a spin polarised calculation spectral_nbands 6 ! number of bands to compute during the BS run At the end of the calculation the net spin of the unit cell is reported in the castep file e.g. Integrated Spin Density = 2.15322 hbar/2 Note The band structure has similarities with that of Copper - and other 3d elements - with flat 3d bands and dispersive s bands. We colour code the bands according to their spin chactacter (red=up, blue=down). We can see that there is an almost constant exchange splitting of 1.5eV between the up and down 3d bands. The splitting between the s-like bands is much smaller. More up states lie below the fermi energy than down states - hence the net spin of the unit cell.","title":"Iron"},{"location":"tutorials/Bands_and_DOS/magnetic/#feo","text":"FeO is an anti-ferromagnetic oxide. We set up the calculation with initial spins on the two Fe atoms pointing in opposite directions. ! FeO.cell %BLOCK LATTICE_CART 1.768531594289456 0.000000000000001 5.002162732258922 -0.884265797144728 1.531593288050063 5.002162732258921 -0.884265797144728 -1.531593288050063 5.002162732258922 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC O 0.75 0.750 -1.250 O -0.75 -0.750 1.250 Fe 0.00 0.000 -0.000 spin=-4.0 Fe 1.50 -0.500 -0.500 spin=4.0 %ENDBLOCK POSITIONS_FRAC kpoints_mp_grid: 6 6 6 symmetry_generate %block spectral_kpoint_path 0.500 0.500 0.000 0.000 0.000 0.000 0.500 0.500 0.500 0.000 0.500 0.000 0.000 0.000 0.000 %endblock spectral_kpoint_path ! FeO.param task : spectral ! The TASK keyword instructs CASTEP what to do xc_functional : PBE ! Which exchange-correlation functional to use. cutoff_energy 600 eV opt_strategy speed ! Choose algorithms for speed. nextra_bands : 6 spin_polarized : true A PBE calculation incorrectly finds FeO to be a metal (bandstructure on left below). Add the following to the cell file to run a PBE+U calculation %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u FeO band structure with PBE (left) and with PBE+U (right) Note Adding a Hubbard U term to the calculation opens the band gap and FeO is (correctly) predicted to be an antiferromangetic insulator.","title":"FeO"},{"location":"tutorials/Bands_and_DOS/metals/","text":"Here we use CASTEP to calculate the bandstructure of two typical metals. The cell and param files are very similar to the semiconductor examples - the one difference is that we use a finer sampling of the Brillouin Zone with the keyword kpoint_mp_grid . A finer sampling is needed to correctly represent the change in occupancy at the Fermi energy. Aluminium ! Al.cell %BLOCK LATTICE_ABC 2.86 2.86 2.86 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Al 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Al.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Aluminium is a metal - there is no gap energy between the occupied and unoccupied states. The bands are close to parabolic (this is particularly noticeable around Gamma) - the electronic structure of aluminium closely follows a nearly-free electron model. Copper ! Cu.cell %BLOCK LATTICE_ABC 2.55 2.55 2.55 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Cu 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Cu.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed at expense of memory. spectral_nbands 8 ! Note Copper is a metal - there is no gap energy between the occupied and unoccupied states. The bandstructure of copper is typical for a transition metal - we have highly dispersive parabolic bands corresponding to the s electrons, these are crossed by 5 quite flat bands corresponding to more localised 3d electrons. In copper the 3d states are filled, and we see the flat bands lie below the Fermi level.","title":"Metals"},{"location":"tutorials/Bands_and_DOS/metals/#aluminium","text":"! Al.cell %BLOCK LATTICE_ABC 2.86 2.86 2.86 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Al 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Al.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Aluminium is a metal - there is no gap energy between the occupied and unoccupied states. The bands are close to parabolic (this is particularly noticeable around Gamma) - the electronic structure of aluminium closely follows a nearly-free electron model.","title":"Aluminium"},{"location":"tutorials/Bands_and_DOS/metals/#copper","text":"! Cu.cell %BLOCK LATTICE_ABC 2.55 2.55 2.55 60 60 60 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS Cu 0 0 0 %ENDBLOCK POSITIONS_ABS kpoint_mp_grid 12 12 12 %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path symmetry_generate ! Cu.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed at expense of memory. spectral_nbands 8 ! Note Copper is a metal - there is no gap energy between the occupied and unoccupied states. The bandstructure of copper is typical for a transition metal - we have highly dispersive parabolic bands corresponding to the s electrons, these are crossed by 5 quite flat bands corresponding to more localised 3d electrons. In copper the 3d states are filled, and we see the flat bands lie below the Fermi level.","title":"Copper"},{"location":"tutorials/Bands_and_DOS/semiconductors/","text":"In this tutorial we will show you the cell and param files needed to plot bandstructures and density of states plots for various semiconductors. For the commands needed to make the plots refer to earlier tutorials. Silicon ! Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path ! Si.cell task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Silicon is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is indirect as the valence band maximum is as Gamma, but the conduction band minimum lies between Gamma and X. Gallium Arsenide The cell file is almost identical to the silicon example above, except that the unitc cell length is slighly larger, and we have replaced one Si atom with Ga, and the other Si with As. ! GaAs.cell %block lattice_abc 4 4 4 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Ga 0.00 0.00 0.00 As 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path The param file is unchanged from the Silicon example ! GaAs.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note GaAs is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is direct both the valence band maximum and conduction band minimum are at Gamma. Compared with Silicon we see that the original bandstructure contains low lying flat bands at around -32eV and -12eV. This is because both the Ga and As pseudopotentials include semi-core states in the valence. The red states are the As 3d and the green are the Ga 3d.","title":"Semiconductors"},{"location":"tutorials/Bands_and_DOS/semiconductors/#silicon","text":"! Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path ! Si.cell task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note Silicon is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is indirect as the valence band maximum is as Gamma, but the conduction band minimum lies between Gamma and X.","title":"Silicon"},{"location":"tutorials/Bands_and_DOS/semiconductors/#gallium-arsenide","text":"The cell file is almost identical to the silicon example above, except that the unitc cell length is slighly larger, and we have replaced one Si atom with Ga, and the other Si with As. ! GaAs.cell %block lattice_abc 4 4 4 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Ga 0.00 0.00 0.00 As 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path The param file is unchanged from the Silicon example ! GaAs.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed Note GaAs is a semiconductor with a small gap between the occupied (blue) and unoccupied states (brown). The gap is direct both the valence band maximum and conduction band minimum are at Gamma. Compared with Silicon we see that the original bandstructure contains low lying flat bands at around -32eV and -12eV. This is because both the Ga and As pseudopotentials include semi-core states in the valence. The red states are the As 3d and the green are the Ga 3d.","title":"Gallium Arsenide"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/","text":"In this tutorial we will walk through plotting a bandstructure and density of states using the perl utilities supplied with CASTEP. We will use Xmgace for plotting - however, the scripts also support gnuplot. Bandstructure Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dispersion.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dispersion.pl -h' castep si-bands dispersion.pl -sym fcc -xg si-bands.bands You should get a plot Density of States Here is a cell file. It is the same as a bandstructure cell file except we have replaced the path through the Brillioun zone with a regular grid of k-points. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a uniform sampling of the Brillouin Zone ! spectral_kpoint_mp_grid 17 17 17 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task dos ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dos.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dos.pl -h' castep si-dos dos.pl -xg si-dos.bands -w 0.3 You should get a plot like Note The procedure above is inefficient as we computed the groundstate of the system twice, once when computing the bandstructure and again when computing the dos. To avoid this we could put the following line in the si-dos.param file continuation: si-bands.check . This will restart the calculation of the dos using the previously computed groundstate.","title":"Plotting - CASTEP tools"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/#bandstructure","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a path through the Brillouin Zone to compute the band structure. ! %block spectral_kpoint_path 0.5 0.25 0.75 ! W 0.5 0.5 0.5 ! L 0.0 0.0 0.0 ! Gamma 0.5 0.0 0.5 ! X 0.5 0.25 0.75 ! W 0.375 0.375 0.75 ! K %endblock spectral_kpoint_path Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-bands.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task bandstructure ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dispersion.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dispersion.pl -h' castep si-bands dispersion.pl -sym fcc -xg si-bands.bands You should get a plot","title":"Bandstructure"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_perl/#density-of-states","text":"Here is a cell file. It is the same as a bandstructure cell file except we have replaced the path through the Brillioun zone with a regular grid of k-points. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 ! Specify a uniform sampling of the Brillouin Zone ! spectral_kpoint_mp_grid 17 17 17 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file si-dos.param task spectral ! The TASK keyword instructs CASTEP what to do spectral_task dos ! xc_functional LDA ! Which exchange-correlation functional to use. cut_off_energy 500 eV ! opt_strategy speed ! Choose algorithms for best speed We can then run castep and use the tool dos.pl to plot a bandstructure with Xmgrace. To see all of the functionality run 'dos.pl -h' castep si-dos dos.pl -xg si-dos.bands -w 0.3 You should get a plot like Note The procedure above is inefficient as we computed the groundstate of the system twice, once when computing the bandstructure and again when computing the dos. To avoid this we could put the following line in the si-dos.param file continuation: si-bands.check . This will restart the calculation of the dos using the previously computed groundstate.","title":"Density of States"},{"location":"tutorials/Bands_and_DOS/Plotting/plotting_sumo/","text":"This is stub for https://github.com/ajjackson/castep-sumo-tutorial/blob/master/castep-sumo.org","title":"Plotting - SUMO"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/","text":"Density of States In this tutorial, we will go through a simple example of using Optados to calculate the electronic density of states (DoS) of crystalline silicon in a 2 atom cell. We will then examine how Optados' adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. ODO Output Firstly, we will run the calculation and examine the Optados output file Si.odo . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 together with the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE SPIN_POLARIZED : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 The first 2 lines are what determine that we will be doing a DoS calculation. Run castep as usual, and then run optados on Si with the Optados input file Si.odi TASK : dos EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default One interesting thing to note here is the line efermi : optados - this sets the internal value of the Fermi level to the one it has derived from the DoS. This is important for subsequent calculations. Other valid options are: file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues insulator , where optados uses a value calculated from assuming the system is non-metallic A custom value you may want to use This generates 3 files: Si.odo - Optados general output file. Si.adaptive.dat - The adaptive broadened DOS raw output data. Si.adaptive.agr - The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Let's have a look at the file Si.odo Towards the top of the data output, we have a table looking like this: ``` +--------------- Fermi Energy Analysis ---------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99964 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99964 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 4.4479 eV <- EfA | +-----------------------------------------------------------------+ ``` It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. Optados now performs some analysis of the DOS at the Fermi level, +----------------------- DOS at Fermi Energy Analysis -----------------------+ | Fermi energy used : 4.4479 eV | | From Adaptive broadening | | Spin Component : 1 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | | Spin Component : 2 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | +----------------------------------------------------------------------------+ From this we may assume that there is a band gap. A bit further down, Optados then calculates the band energy from the DOS is has calculated. +--------------------------- Band Energy Analysis ---------------------------+ | Band energy (Adaptive broadening) : -6.3472 eV <- BEA | | Band energy (From CASTEP) : -6.3471 eV <- BEC | +----------------------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Other Output Files Finally, Optados shifts the Fermi level to 0 eV for the output files - let's have a look at the other 2 files generated. The DoS is written to Si2.adaptive.dat . This contains 5 columns - the 1 st is the energy, the 2 nd is the up-spin DoS, the 3 rd is the down-spin DoS, the 4 th is the up-spin integrated DoS, and the 5 th is the down-spin integrated DoS. If instead SPIN_POLARIZED : FALSE were set in the param file, there would only be 3 columns: energy, DoS and integrated DoS. This file can be plotted by your preferred graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace - to get a plot all you have to run is: $ xmgrace Si2.adaptive.agr The graph should look a bit like this: What is important to mention is that this agr file only contains the data for DoS, not integrated DoS. If you want to plot all the data, including up and down integrated DoS, run xmgrace -batch other_data.bat on the batch file other_data.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Up DOS\" BLOCK XY \"1:3\" S1 LEGEND \"Down DOS\" BLOCK XY \"1:4\" S2 LEGEND \"Up IntDos\" BLOCK XY \"1:5\" S3 LEGEND \"Down IntDos\" This should give a graph that looks like: Band Gap Analysis Let's go back to looking at the odo output file. Because COMPUTE_BAND_GAP : TRUE is set by default, the band gap analysis section should already be present. The results are a table that looks like: +----------------------------- Bandgap Analysis -----------------------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6724150536 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000 | | and CBM kpoint: -0.45000 -0.45000 -0.05000 | | ==> Indirect Gap | +----------------------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5639496096 eV <- OBg | | Spin : 2 : 2.5639441673 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +----------------------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8132681742 eV <- ABg | | Spin : 2 : 3.8132658290 eV <- ABg | | Weighted Average : 3.8132670016 eV <- wAB | +----------------------------------------------------------------------------+ Optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Broadening We will now compare the different forms of broadening. This can be done quickly by changing the first in Si.odi to task : compare_dos and re-running Optados. This gives us 4 new output files - Si_linear.dat and Si_fixed.dat , plus their accompanying agr files. Let's compare them by running xmgrace -batch compare.bat on the batch file compare.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Adaptive DOS\" READ BLOCK \"Si.linear.dat\" BLOCK XY \"1:2\" S1 LEGEND \"Linear DOS\" READ BLOCK \"Si.fixed.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Fixed DOS\" WORLD XMIN 0 WORLD XMAX 5 Note We're looking at a small region, between 0 and 5 eV, so it is easier to see the differences The graph should look like this: To further improve the appearance of the graph, you can lower DOS_SPACING and tinker with the value of ADAPTIVE_SMEARING in the odi file.","title":"OptaDOS - DOS"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#density-of-states","text":"In this tutorial, we will go through a simple example of using Optados to calculate the electronic density of states (DoS) of crystalline silicon in a 2 atom cell. We will then examine how Optados' adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure.","title":"Density of States"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#odo-output","text":"Firstly, we will run the calculation and examine the Optados output file Si.odo . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 together with the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE SPIN_POLARIZED : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 The first 2 lines are what determine that we will be doing a DoS calculation. Run castep as usual, and then run optados on Si with the Optados input file Si.odi TASK : dos EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default One interesting thing to note here is the line efermi : optados - this sets the internal value of the Fermi level to the one it has derived from the DoS. This is important for subsequent calculations. Other valid options are: file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues insulator , where optados uses a value calculated from assuming the system is non-metallic A custom value you may want to use This generates 3 files: Si.odo - Optados general output file. Si.adaptive.dat - The adaptive broadened DOS raw output data. Si.adaptive.agr - The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Let's have a look at the file Si.odo Towards the top of the data output, we have a table looking like this: ``` +--------------- Fermi Energy Analysis ---------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99964 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99964 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 4.4479 eV <- EfA | +-----------------------------------------------------------------+ ``` It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. Optados now performs some analysis of the DOS at the Fermi level, +----------------------- DOS at Fermi Energy Analysis -----------------------+ | Fermi energy used : 4.4479 eV | | From Adaptive broadening | | Spin Component : 1 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | | Spin Component : 2 DOS at Fermi Energy : 0.0010 eln/cell <- DEA | +----------------------------------------------------------------------------+ From this we may assume that there is a band gap. A bit further down, Optados then calculates the band energy from the DOS is has calculated. +--------------------------- Band Energy Analysis ---------------------------+ | Band energy (Adaptive broadening) : -6.3472 eV <- BEA | | Band energy (From CASTEP) : -6.3471 eV <- BEC | +----------------------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer.","title":"ODO Output"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#other-output-files","text":"Finally, Optados shifts the Fermi level to 0 eV for the output files - let's have a look at the other 2 files generated. The DoS is written to Si2.adaptive.dat . This contains 5 columns - the 1 st is the energy, the 2 nd is the up-spin DoS, the 3 rd is the down-spin DoS, the 4 th is the up-spin integrated DoS, and the 5 th is the down-spin integrated DoS. If instead SPIN_POLARIZED : FALSE were set in the param file, there would only be 3 columns: energy, DoS and integrated DoS. This file can be plotted by your preferred graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace - to get a plot all you have to run is: $ xmgrace Si2.adaptive.agr The graph should look a bit like this: What is important to mention is that this agr file only contains the data for DoS, not integrated DoS. If you want to plot all the data, including up and down integrated DoS, run xmgrace -batch other_data.bat on the batch file other_data.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Up DOS\" BLOCK XY \"1:3\" S1 LEGEND \"Down DOS\" BLOCK XY \"1:4\" S2 LEGEND \"Up IntDos\" BLOCK XY \"1:5\" S3 LEGEND \"Down IntDos\" This should give a graph that looks like:","title":"Other Output Files"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#band-gap-analysis","text":"Let's go back to looking at the odo output file. Because COMPUTE_BAND_GAP : TRUE is set by default, the band gap analysis section should already be present. The results are a table that looks like: +----------------------------- Bandgap Analysis -----------------------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6724150536 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000 | | and CBM kpoint: -0.45000 -0.45000 -0.05000 | | ==> Indirect Gap | +----------------------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5639496096 eV <- OBg | | Spin : 2 : 2.5639441673 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +----------------------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8132681742 eV <- ABg | | Spin : 2 : 3.8132658290 eV <- ABg | | Weighted Average : 3.8132670016 eV <- wAB | +----------------------------------------------------------------------------+ Optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap.","title":"Band Gap Analysis"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/DOS/#broadening","text":"We will now compare the different forms of broadening. This can be done quickly by changing the first in Si.odi to task : compare_dos and re-running Optados. This gives us 4 new output files - Si_linear.dat and Si_fixed.dat , plus their accompanying agr files. Let's compare them by running xmgrace -batch compare.bat on the batch file compare.bat READ BLOCK \"Si.adaptive.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Adaptive DOS\" READ BLOCK \"Si.linear.dat\" BLOCK XY \"1:2\" S1 LEGEND \"Linear DOS\" READ BLOCK \"Si.fixed.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Fixed DOS\" WORLD XMIN 0 WORLD XMAX 5 Note We're looking at a small region, between 0 and 5 eV, so it is easier to see the differences The graph should look like this: To further improve the appearance of the graph, you can lower DOS_SPACING and tinker with the value of ADAPTIVE_SMEARING in the odi file.","title":"Broadening"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/pDOS/","text":"Projected Density of States In this tutorial, we will using Optados to calculate the electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. It may be helpful to have gone through the previous tutorial on calculating the DoS . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 12 12 12 and the param file Si.param TASK : SPECTRAL %BLOCK devel_code spectral: check_output: true :endspectral %ENDBLOCK devel_code SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 Run castep. Then, run Optados with the Optados input file Si.odi TASK : pdos PDOS : angular EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default Note the line TASK : pdos - this is what allows us to calculate the PDoS. We have chosen to decompose the DOS into angular momentum channels with the line PDOS : angular , and as in the previous example , we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by Castep. The output can be found in Si2.pdos.dat - it contains the header below to tell us what each column represnts. ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ This shows that there are four projectors described below - each one corresponding to a column in the actual data. The 1 st contains the s-channels of both silicon atoms, the 2 nd the p-channels etc. The values correspond to the sums of the values of both Si atoms. You can change which projectors you will gain by changing the line PDOS : ANGULAR . Changing the value to SPECIES_ANG will give you only the first 2 projectors. SPECIES will yield the sum of all the orbitals and atoms. SITES will give you 1 projector of the sum of all orbitals of Si atom 1, and 1 of atom 2 (note that they're identical). You can also make custom projectors - write down the element, number and orbital in brackets, with columns separating adjacent projectors if you want multiple. For example, Si1(s):Si2(p) will give you 1 column of the PDoS of the s orbital on silicon atom 1, and a column of the p orbital on silicon atom 2. Note Using custom projectors won't save the data in Si.pdos.dat , but a file named based on the projectors chosen - in the example above, it'd be saved in Si.pdos.proj-0001-0002.dat . The output is easily plotted by using xmgrace on the dat file. To plot multiple bits of data, it is easiest to use a batch file - this is the plot of the s and p channels: We can run xmgrace -batch pdos_plot.bat on the batch file pdos_plot.bat READ BLOCK \"Si.pdos.dat\" BLOCK XY \"1:2\" S0 LEGEND \"s-channel\" BLOCK XY \"1:3\" S1 LEGEND \"p-channel\" to get the following output:","title":"OptaDOS - pDOS"},{"location":"tutorials/Bands_and_DOS/Plotting/Optados/pDOS/#projected-density-of-states","text":"In this tutorial, we will using Optados to calculate the electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. It may be helpful to have gone through the previous tutorial on calculating the DoS . We will use the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 12 12 12 and the param file Si.param TASK : SPECTRAL %BLOCK devel_code spectral: check_output: true :endspectral %ENDBLOCK devel_code SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 IPRINT : 1 Run castep. Then, run Optados with the Optados input file Si.odi TASK : pdos PDOS : angular EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default DOS_PER_VOLUME : false # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default Note the line TASK : pdos - this is what allows us to calculate the PDoS. We have chosen to decompose the DOS into angular momentum channels with the line PDOS : angular , and as in the previous example , we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by Castep. The output can be found in Si2.pdos.dat - it contains the header below to tell us what each column represnts. ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ This shows that there are four projectors described below - each one corresponding to a column in the actual data. The 1 st contains the s-channels of both silicon atoms, the 2 nd the p-channels etc. The values correspond to the sums of the values of both Si atoms. You can change which projectors you will gain by changing the line PDOS : ANGULAR . Changing the value to SPECIES_ANG will give you only the first 2 projectors. SPECIES will yield the sum of all the orbitals and atoms. SITES will give you 1 projector of the sum of all orbitals of Si atom 1, and 1 of atom 2 (note that they're identical). You can also make custom projectors - write down the element, number and orbital in brackets, with columns separating adjacent projectors if you want multiple. For example, Si1(s):Si2(p) will give you 1 column of the PDoS of the s orbital on silicon atom 1, and a column of the p orbital on silicon atom 2. Note Using custom projectors won't save the data in Si.pdos.dat , but a file named based on the projectors chosen - in the example above, it'd be saved in Si.pdos.proj-0001-0002.dat . The output is easily plotted by using xmgrace on the dat file. To plot multiple bits of data, it is easiest to use a batch file - this is the plot of the s and p channels: We can run xmgrace -batch pdos_plot.bat on the batch file pdos_plot.bat READ BLOCK \"Si.pdos.dat\" BLOCK XY \"1:2\" S0 LEGEND \"s-channel\" BLOCK XY \"1:3\" S1 LEGEND \"p-channel\" to get the following output:","title":"Projected Density of States"},{"location":"tutorials/Bonding_and_Charge/ELF/","text":"ELF (Electron Localization Function) measures how \"local\" electrons are - the higher the value, the more likely electrons are to make opposite-spin pairs and generally be more \"fixed\" in place. We will use it to examine ionic and covalent bonding, and then use it to examine lone pairs (and hydrogen bonding) in HF, H 2 O and NH 3 molecules. A lot of the steps on examining the data are the same as in Plotting Charge Density - if you prefer, you may use that (and its accompanying video tutorial ), though the cells and planes used are slightly different. For visualising the results, this tutorial will use Vesta , but feel free to use another software if you prefer. NaCl We will start by looking at how electrons in an NaCl crystal behave - to illustrate what ELF exactly does and doesn't do, we will compare it to the results of a standard population analysis. For both calculations we will use the cell file NaCl.cell %block lattice_cart 5.693 0.000 0.000 0.000 5.693 0.000 0.000 0.000 5.693 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 Na 0.0 0.5 0.5 Na 0.5 0.0 0.5 Na 0.5 0.5 0.0 Cl 0.5 0.5 0.5 Cl 0.5 0.0 0.0 Cl 0.0 0.5 0.0 Cl 0.0 0.0 0.5 %endblock positions_frac and the param file NaCl.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false WRITE_FORMATTED_DENSITY : TRUE CALCULATE_ELF : TRUE WRITE_FORMATTED_ELF : TRUE Running castep will yield 2 files of interest: NaCl.elf_fmt and NaCl.den_fmt . We will want to compare the 2 outputs, so: Make 2 copies of the cell file by copying NaCl.cell to NaCl_elf.cell and NaCl_den.cell . 2. Copy NaCl.elf_fmt to NaCl_elf.charg_frm Copy NaCl.den_fmt to NaCl_den.charg_frm . In both .charg_frm files remove the header. Following this, they should look like: 1 1 1 0.000000 2 1 1 0.000000 3 1 1 0.000000 4 1 1 0.000000 5 1 1 0.000000 Now we will be able to visualise the results. Note If you wish to move the files around, make sure that the .charg_frm file is located in the same directory as its respective cell file - for example, NaCl_elf.charg_frm should be with NaCl_elf.cell . We will first look at the density output. Open it in Vesta, and, at the top-bar, go to Utilities -> 2D Data Display . It should open a window which looks like: There, click Slice - this will open another window You should keep the hkl (lattice Miller indices) as 001 , but make a 2x2 supercell and change x(min) , y(min) and z(min) to -1 . Click Ok and you should get an output which looks like: This is what we'd expect of a the charge density in an ionic crystal: a regular pattern where a region with a low relative electron density (the cation) is adjacent to one with a high electron density (the anion). Now let's follow the exact same procedure, except this time with NaCl_elf for the ELF result. This is the outcome: This is rather interesting: though the electron density around the Na + cation is very low, the electrons are much more localised around it - the opposite is true for Cl - : the ELF is high where density is low and vice versa. While both, in the simplest model, have full outer shells and thus should both be highly localised (in fact they are both localised, Na + just moreso), Cl - simply has larger orbitals and has a full valence shell (rather than core), leading to lower localisation. This helps illustrate the key difference between ELF and population analysis: ELF is purely a measure of how localised the electrons are in space, and doesn't always correspond to a higher density. Covalent bonding - Si We will now use ELF to demonstrate covalent bonding in diamond-silicon. We will use the cell file Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac Run castep with an identical param file (you may remove WRITE_FORMATTED_DENSITY : TRUE if not you're not interested in the charge density). Follow the exact same procedure as above (though again you can ignore anything to do with the charge density). After opening it in Vesta, rather than taking a slice, click Edit -> Lattice planes , which will open the window below: Click New and use the 100 plane as before. Then click Ok . Create a supercell. This time click Boundary... on the left side of the main window. Make a 2x2 supercell as before. Rotate the cell around until you see what's happening. You should see something like: You can uncheck Show models to see it better without the atoms This tells us a rather interesting story - the atoms are highly localised along the covalent Si-Si bonds, but relatively delocalised near the atoms themselves. They are especially delocalised in regions where is no bonding or atoms. If you wish to also examine and compare the charge density, this is covered in another tutorial HF Now that we have a good understand of what ELF actually does, let's use it for a more interesting purpose: to demonstrate lone pairs and hydrogen bonding. Lone pairs are by their nature highly localised, pairing up with each other and being held largely in place by strong repulsions to any negative charges (including other lone pairs) and strong attractions to positive ones (such as adjacent dipoles - this leads to hydrogen bonding) For HF we will use the cell file: HF.cell %block lattice_abc 6 6 6 90 90 90 %endblock lattice_abc %block positions_abs H 3 3 3 F 3.92 3 3 %endblock positions_abs kpoints_mp_grid 4 4 4 and again the same param file. Following the exact same steps as with NaCl, slicing the (010) plane (with the distance from the origin, set in the same slice window, set as 0.5d - 0.5 * the size of the side lengths) we get an output looking like: This gives us an interesting picture: the small regions of high electron locality look like what we'd expect of lone pairs. The fluorine has 3 around it (as expected), yet the hydrogen also has 1. Considering that this will be interacting with adjacent cells, which is inevitable given that this is calculated with periodic boundaries, this is a good indication that it has formed a hydrogen bond. Water and ammonia The procedure for H 2 O and NH 3 is almost identical. We use exactly the same param file as above, and perform the same procedures following the elf_fmt output. The cell files we use are: H2O.cell %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs O 2.5 2.5 2.5 H 2.5 1.95 3.29 H 2.5 1.95 1.72 %endblock positions_abs for water and NH3.cell %BLOCK LATTICE_ABC 8 8 8 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS N 4 4 4 H 4 4 5 H 4.95 4 3.67 H 3.53 3.18 3.67 %ENDBLOCK POSITIONS_ABS For ammonia. From then, we again go to 2D display data and Slice... . This is where the procedure might be a bit different: by shift clicking on all the atoms in H 2 O (and the atoms within the plane you wish to look at in NH 3 ) and clicking Calculate the best plane for the selected atoms it'll give us the plane that we may be most interested in. In the case of water it is a simple (100), but for NH 3 you may wish to play around with it by selecting different combinations - alternatively manually choose a plane in which you are interested. Note In VESTA, plane selection may work a bit differently from how you'd expect. In this example, since you're cutting through the middle you'd normally call it a (200) plane. However, here it is considered a (100) plane 2.5 \\mathring{\\text{A}} \\mathring{\\text{A}} (or 0.5d - since the unit cell lengths are 5 \\mathring{\\text{A}} \\mathring{\\text{A}} ) from the origin The result for water in the (100) plane should look like: Alternatively, to better see which bonds/atoms are corresponding to the regions of high/low electron locality, use the Lattice planes method so you can see the cell along with the ELF map. You can again Calculate the best plane for the selected atoms like we did for ammonia with slicing. Feel free to also select different planes and look at how it looks in them. Note Don't forget you can turn off Show isosurfaces and Show sections under Volumetric data - if you're going to be looking at the cell itself this may obscure what you're trying to look at Lastly, let's take a quick look at the NH 3 result. Selecting the best plane containing 2 hydrogens and a nitrogen should give a result looking like: Here we see evidence of lone pairs on both of the hydrogens in the plane (as both can form hydrogen bonds - and so can the third if you look at that one). This is rather unexpected - in the classical view, NH 3 has a nitrogen with 1 lone pair that simply forms a single hydrogen bond with a hydrogen in an adjacent NH 3 . However, because every hydrogen is capable of forming a hydrogen bond, ELF registers them as having regions of high locality near them. The same applies to nitrogen - though it should classically only have 1 pair near it, it is seen as having 2 as it is capable of making 2 hydrogen bonds in that plane. Warning The results will likely look different depending on which 2 hydrogens you pick along with the nitrogen. This can be mostly explained due to how adjacent ammonia molecules are aligned relative to it, which is defined by the cell.","title":"ELF"},{"location":"tutorials/Bonding_and_Charge/ELF/#nacl","text":"We will start by looking at how electrons in an NaCl crystal behave - to illustrate what ELF exactly does and doesn't do, we will compare it to the results of a standard population analysis. For both calculations we will use the cell file NaCl.cell %block lattice_cart 5.693 0.000 0.000 0.000 5.693 0.000 0.000 0.000 5.693 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 Na 0.0 0.5 0.5 Na 0.5 0.0 0.5 Na 0.5 0.5 0.0 Cl 0.5 0.5 0.5 Cl 0.5 0.0 0.0 Cl 0.0 0.5 0.0 Cl 0.0 0.0 0.5 %endblock positions_frac and the param file NaCl.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false WRITE_FORMATTED_DENSITY : TRUE CALCULATE_ELF : TRUE WRITE_FORMATTED_ELF : TRUE Running castep will yield 2 files of interest: NaCl.elf_fmt and NaCl.den_fmt . We will want to compare the 2 outputs, so: Make 2 copies of the cell file by copying NaCl.cell to NaCl_elf.cell and NaCl_den.cell . 2. Copy NaCl.elf_fmt to NaCl_elf.charg_frm Copy NaCl.den_fmt to NaCl_den.charg_frm . In both .charg_frm files remove the header. Following this, they should look like: 1 1 1 0.000000 2 1 1 0.000000 3 1 1 0.000000 4 1 1 0.000000 5 1 1 0.000000 Now we will be able to visualise the results. Note If you wish to move the files around, make sure that the .charg_frm file is located in the same directory as its respective cell file - for example, NaCl_elf.charg_frm should be with NaCl_elf.cell . We will first look at the density output. Open it in Vesta, and, at the top-bar, go to Utilities -> 2D Data Display . It should open a window which looks like: There, click Slice - this will open another window You should keep the hkl (lattice Miller indices) as 001 , but make a 2x2 supercell and change x(min) , y(min) and z(min) to -1 . Click Ok and you should get an output which looks like: This is what we'd expect of a the charge density in an ionic crystal: a regular pattern where a region with a low relative electron density (the cation) is adjacent to one with a high electron density (the anion). Now let's follow the exact same procedure, except this time with NaCl_elf for the ELF result. This is the outcome: This is rather interesting: though the electron density around the Na + cation is very low, the electrons are much more localised around it - the opposite is true for Cl - : the ELF is high where density is low and vice versa. While both, in the simplest model, have full outer shells and thus should both be highly localised (in fact they are both localised, Na + just moreso), Cl - simply has larger orbitals and has a full valence shell (rather than core), leading to lower localisation. This helps illustrate the key difference between ELF and population analysis: ELF is purely a measure of how localised the electrons are in space, and doesn't always correspond to a higher density.","title":"NaCl"},{"location":"tutorials/Bonding_and_Charge/ELF/#covalent-bonding-si","text":"We will now use ELF to demonstrate covalent bonding in diamond-silicon. We will use the cell file Si.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac Run castep with an identical param file (you may remove WRITE_FORMATTED_DENSITY : TRUE if not you're not interested in the charge density). Follow the exact same procedure as above (though again you can ignore anything to do with the charge density). After opening it in Vesta, rather than taking a slice, click Edit -> Lattice planes , which will open the window below: Click New and use the 100 plane as before. Then click Ok . Create a supercell. This time click Boundary... on the left side of the main window. Make a 2x2 supercell as before. Rotate the cell around until you see what's happening. You should see something like: You can uncheck Show models to see it better without the atoms This tells us a rather interesting story - the atoms are highly localised along the covalent Si-Si bonds, but relatively delocalised near the atoms themselves. They are especially delocalised in regions where is no bonding or atoms. If you wish to also examine and compare the charge density, this is covered in another tutorial","title":"Covalent bonding - Si"},{"location":"tutorials/Bonding_and_Charge/ELF/#hf","text":"Now that we have a good understand of what ELF actually does, let's use it for a more interesting purpose: to demonstrate lone pairs and hydrogen bonding. Lone pairs are by their nature highly localised, pairing up with each other and being held largely in place by strong repulsions to any negative charges (including other lone pairs) and strong attractions to positive ones (such as adjacent dipoles - this leads to hydrogen bonding) For HF we will use the cell file: HF.cell %block lattice_abc 6 6 6 90 90 90 %endblock lattice_abc %block positions_abs H 3 3 3 F 3.92 3 3 %endblock positions_abs kpoints_mp_grid 4 4 4 and again the same param file. Following the exact same steps as with NaCl, slicing the (010) plane (with the distance from the origin, set in the same slice window, set as 0.5d - 0.5 * the size of the side lengths) we get an output looking like: This gives us an interesting picture: the small regions of high electron locality look like what we'd expect of lone pairs. The fluorine has 3 around it (as expected), yet the hydrogen also has 1. Considering that this will be interacting with adjacent cells, which is inevitable given that this is calculated with periodic boundaries, this is a good indication that it has formed a hydrogen bond.","title":"HF"},{"location":"tutorials/Bonding_and_Charge/ELF/#water-and-ammonia","text":"The procedure for H 2 O and NH 3 is almost identical. We use exactly the same param file as above, and perform the same procedures following the elf_fmt output. The cell files we use are: H2O.cell %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs O 2.5 2.5 2.5 H 2.5 1.95 3.29 H 2.5 1.95 1.72 %endblock positions_abs for water and NH3.cell %BLOCK LATTICE_ABC 8 8 8 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS N 4 4 4 H 4 4 5 H 4.95 4 3.67 H 3.53 3.18 3.67 %ENDBLOCK POSITIONS_ABS For ammonia. From then, we again go to 2D display data and Slice... . This is where the procedure might be a bit different: by shift clicking on all the atoms in H 2 O (and the atoms within the plane you wish to look at in NH 3 ) and clicking Calculate the best plane for the selected atoms it'll give us the plane that we may be most interested in. In the case of water it is a simple (100), but for NH 3 you may wish to play around with it by selecting different combinations - alternatively manually choose a plane in which you are interested. Note In VESTA, plane selection may work a bit differently from how you'd expect. In this example, since you're cutting through the middle you'd normally call it a (200) plane. However, here it is considered a (100) plane 2.5 \\mathring{\\text{A}} \\mathring{\\text{A}} (or 0.5d - since the unit cell lengths are 5 \\mathring{\\text{A}} \\mathring{\\text{A}} ) from the origin The result for water in the (100) plane should look like: Alternatively, to better see which bonds/atoms are corresponding to the regions of high/low electron locality, use the Lattice planes method so you can see the cell along with the ELF map. You can again Calculate the best plane for the selected atoms like we did for ammonia with slicing. Feel free to also select different planes and look at how it looks in them. Note Don't forget you can turn off Show isosurfaces and Show sections under Volumetric data - if you're going to be looking at the cell itself this may obscure what you're trying to look at Lastly, let's take a quick look at the NH 3 result. Selecting the best plane containing 2 hydrogens and a nitrogen should give a result looking like: Here we see evidence of lone pairs on both of the hydrogens in the plane (as both can form hydrogen bonds - and so can the third if you look at that one). This is rather unexpected - in the classical view, NH 3 has a nitrogen with 1 lone pair that simply forms a single hydrogen bond with a hydrogen in an adjacent NH 3 . However, because every hydrogen is capable of forming a hydrogen bond, ELF registers them as having regions of high locality near them. The same applies to nitrogen - though it should classically only have 1 pair near it, it is seen as having 2 as it is capable of making 2 hydrogen bonds in that plane. Warning The results will likely look different depending on which 2 hydrogens you pick along with the nitrogen. This can be mostly explained due to how adjacent ammonia molecules are aligned relative to it, which is defined by the cell.","title":"Water and ammonia"},{"location":"tutorials/Bonding_and_Charge/charge_density/","text":"In this tutorial we will walk through plotting a charge density with Vesta https://jp-minerals.org/vesta/en/ Silicon Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 1500 eV #this next line causes the charge to be written in a den_fmt file write_formatted_density : T spin_polarised : false The cutoff energy is somewhat higher than needed for a converged total energy - but it helps when making a smoother looking charge density plot. Run castep. You will see a file called silicon.den_fmt this contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called silicon.charg_frm cp silicon.den_fmt silicon.charg_frm Now edit the file silicon.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open silicon.charg_frm with Vesta. Note that Vesta needs both the cell and charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process at https://youtu.be/_c2Hk4jxmm4 An alternative way to plot charge densities (and much more besides) is c2x https://www.c2x.org.uk","title":"Plotting Charge Density"},{"location":"tutorials/Bonding_and_Charge/charge_density/#silicon","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 1500 eV #this next line causes the charge to be written in a den_fmt file write_formatted_density : T spin_polarised : false The cutoff energy is somewhat higher than needed for a converged total energy - but it helps when making a smoother looking charge density plot. Run castep. You will see a file called silicon.den_fmt this contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called silicon.charg_frm cp silicon.den_fmt silicon.charg_frm Now edit the file silicon.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open silicon.charg_frm with Vesta. Note that Vesta needs both the cell and charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process at https://youtu.be/_c2Hk4jxmm4 An alternative way to plot charge densities (and much more besides) is c2x https://www.c2x.org.uk","title":"Silicon"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/","text":"By default castep will calculate the Mulliken Population analysis at the end of every calculation (the keyword popn_calculate is set to true by default). Silicon Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false Run castep. Toward the end of the file silicon.castep you will find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Si 1 1.356 2.644 0.000 0.000 4.000 0.000 Si 2 1.356 2.644 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== Si 1 -- Si 2 2.99 2.32702 ====================================================================== The atoms are not charged overall, and there is a large bond population. This is all indicative of a strong covalent bond. Comparing to Other Diamond Structures To understand the results of this further, we will compare them to 2 other diamond structures - GaAs and diamond (as in carbon-diamond). For both of these cases, we will use an identical .param file (just rename them to diamond.param and GaAs.param ). The cell files will be slightly different - for diamond we will change the lattice_abc block lattice dimensions with 2.52 \\mathring{\\text{A}} \\mathring{\\text{A}} (rather than 3.8 \\mathring{\\text{A}} \\mathring{\\text{A}} - the structure is the same but the cell size is different). Naturally the Si 's in the positions_frac block need to be replaced with C 's Towards the end of diamond.castep we find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== C 1 1.076 2.924 0.000 0.000 4.000 0.000 C 2 1.076 2.924 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== C 1 -- C 2 3.00 1.54318 ====================================================================== The results are rather similar but there are a couple of interesting things to note: The ratio of the populations in s and p orbitals is closer to 1:3, which is expected for sp 3 hybridization - this indicates that the bonds are much more perfectly hybridized, meaning it's more overlapped: this indicates stronger bonding, as well as showing that silicon is a semimetal The population of electrons in the bonds is the same (indicating that the same type of bonding is present), but the bond length is smaller - again indicating more overlap and thus stronger bonding. Now we will compare it with GaAs. The same procedure is used, except the lattice length is now 3.93 \\mathring{\\text{A}} \\mathring{\\text{A}} and the atoms in positions_frac should be Ga and As (it doesn't matter which one goes in which position/line). We get an output looking like this: Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Ga 1 1.180 1.743 9.994 0.000 12.917 0.083 As 1 1.488 3.595 10.000 0.000 15.083 -0.083 ========================================================================== Bond Population Length (A) ====================================================================== Ga 1 -- As 1 0.34 2.44652 ====================================================================== Despite having the same structure, the results are very different now: Unlike before, the Ga and As ions have charges on them - this is indicative of ionic/polar character There is now a much smaller population in the Ga-As bond. This indicates less covalent character Especially in the case of Ga, the s:p shell ratio is far off from 1:3 - this again indicates that the bonding is not like in the cases above Diatomic molecules Next we will examine a few diatomic molecules - HF, HCl and HBr. Here is the HF.cell file %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs H 2 2 2 F 2.91 2 2 %endblock positions_abs Since we are just trying to look at a single diatomic molecule, the cell is defined rather simply - an arbitrarily large cube for the cell (making it too large would make the calculation take longer, but make it too small and it'll simulate a loose crystal rather than a disperse molecule), 1 atom placed about in the middle, and the 2 nd atom placed a bond length away from it - in this case F is 0.91 \\mathring{\\text{A}} \\mathring{\\text{A}} to the right of the H . The bond lengths can be found on a database , or you may perform a geometry optimisation to find it yourself if you wish. Using a param file identical to before and running castep yields this towards the end of HF.castep Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.309 0.000 0.000 0.000 0.309 0.691 F 1 1.960 5.731 0.000 0.000 7.691 -0.691 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- F 1 0.34 0.91000 ====================================================================== There are a couple of interesting things to note: Like GaAs (and unlike Si and diamond), there are 2 opposite charges on both atoms. However, the charge is significantly larger, indicating that the molecule is highly polar/ionic. The population of the H-F bond is rather low - this indicates that the molecule has little covalent character We will now compare HF to very similar molecules - HCl and HBr - keeping the trend of hydrogen bonded to a group 7 element. The param files are completely identical and in the cell files the bond lengths used are 1.275 \\mathring{\\text{A}} \\mathring{\\text{A}} for HCl and 1.44 \\mathring{\\text{A}} \\mathring{\\text{A}} for HBr. HCl has the result Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.620 0.000 0.000 0.000 0.620 0.380 Cl 1 1.936 5.443 0.000 0.000 7.379 -0.379 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Cl 1 0.56 1.27500 ====================================================================== While HBr has Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.824 0.000 0.000 0.000 0.824 0.176 Br 1 1.908 5.267 0.000 0.000 7.176 -0.176 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Br 1 0.53 1.44000 ====================================================================== The most significant thing this shows us is that the charges on both atoms decrease as you go down group 7. This successfully demonstrates something we already know: as you go down group 7, the electronegativity decreases. The same principle can be applied to estimate relative electronegativities of different atoms.","title":"Population Analysis"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#silicon","text":"Here is a cell file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.cell %block lattice_abc 3.8 3.8 3.8 60 60 60 %endblock lattice_abc ! ! Atomic co-ordinates for each species. ! These are in fractional co-ordinates wrt to the cell. ! %block positions_frac Si 0.00 0.00 0.00 Si 0.25 0.25 0.25 %endblock positions_frac ! ! Analyse structure to determine symmetry ! symmetry_generate ! ! Specify M-P grid dimensions for electron wavevectors (K-points) ! kpoint_mp_grid 4 4 4 Here is a param file. You can use the icon in the top right of the box to copy and paste the text. Save it in a file silicon.param xc_functional : LDA cutoff_energy : 500 eV spin_polarised : false Run castep. Toward the end of the file silicon.castep you will find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Si 1 1.356 2.644 0.000 0.000 4.000 0.000 Si 2 1.356 2.644 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== Si 1 -- Si 2 2.99 2.32702 ====================================================================== The atoms are not charged overall, and there is a large bond population. This is all indicative of a strong covalent bond.","title":"Silicon"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#comparing-to-other-diamond-structures","text":"To understand the results of this further, we will compare them to 2 other diamond structures - GaAs and diamond (as in carbon-diamond). For both of these cases, we will use an identical .param file (just rename them to diamond.param and GaAs.param ). The cell files will be slightly different - for diamond we will change the lattice_abc block lattice dimensions with 2.52 \\mathring{\\text{A}} \\mathring{\\text{A}} (rather than 3.8 \\mathring{\\text{A}} \\mathring{\\text{A}} - the structure is the same but the cell size is different). Naturally the Si 's in the positions_frac block need to be replaced with C 's Towards the end of diamond.castep we find Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== C 1 1.076 2.924 0.000 0.000 4.000 0.000 C 2 1.076 2.924 0.000 0.000 4.000 0.000 ========================================================================== Bond Population Length (A) ====================================================================== C 1 -- C 2 3.00 1.54318 ====================================================================== The results are rather similar but there are a couple of interesting things to note: The ratio of the populations in s and p orbitals is closer to 1:3, which is expected for sp 3 hybridization - this indicates that the bonds are much more perfectly hybridized, meaning it's more overlapped: this indicates stronger bonding, as well as showing that silicon is a semimetal The population of electrons in the bonds is the same (indicating that the same type of bonding is present), but the bond length is smaller - again indicating more overlap and thus stronger bonding. Now we will compare it with GaAs. The same procedure is used, except the lattice length is now 3.93 \\mathring{\\text{A}} \\mathring{\\text{A}} and the atoms in positions_frac should be Ga and As (it doesn't matter which one goes in which position/line). We get an output looking like this: Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== Ga 1 1.180 1.743 9.994 0.000 12.917 0.083 As 1 1.488 3.595 10.000 0.000 15.083 -0.083 ========================================================================== Bond Population Length (A) ====================================================================== Ga 1 -- As 1 0.34 2.44652 ====================================================================== Despite having the same structure, the results are very different now: Unlike before, the Ga and As ions have charges on them - this is indicative of ionic/polar character There is now a much smaller population in the Ga-As bond. This indicates less covalent character Especially in the case of Ga, the s:p shell ratio is far off from 1:3 - this again indicates that the bonding is not like in the cases above","title":"Comparing to Other Diamond Structures"},{"location":"tutorials/Bonding_and_Charge/mulliken_population/#diatomic-molecules","text":"Next we will examine a few diatomic molecules - HF, HCl and HBr. Here is the HF.cell file %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc %block positions_abs H 2 2 2 F 2.91 2 2 %endblock positions_abs Since we are just trying to look at a single diatomic molecule, the cell is defined rather simply - an arbitrarily large cube for the cell (making it too large would make the calculation take longer, but make it too small and it'll simulate a loose crystal rather than a disperse molecule), 1 atom placed about in the middle, and the 2 nd atom placed a bond length away from it - in this case F is 0.91 \\mathring{\\text{A}} \\mathring{\\text{A}} to the right of the H . The bond lengths can be found on a database , or you may perform a geometry optimisation to find it yourself if you wish. Using a param file identical to before and running castep yields this towards the end of HF.castep Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.309 0.000 0.000 0.000 0.309 0.691 F 1 1.960 5.731 0.000 0.000 7.691 -0.691 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- F 1 0.34 0.91000 ====================================================================== There are a couple of interesting things to note: Like GaAs (and unlike Si and diamond), there are 2 opposite charges on both atoms. However, the charge is significantly larger, indicating that the molecule is highly polar/ionic. The population of the H-F bond is rather low - this indicates that the molecule has little covalent character We will now compare HF to very similar molecules - HCl and HBr - keeping the trend of hydrogen bonded to a group 7 element. The param files are completely identical and in the cell files the bond lengths used are 1.275 \\mathring{\\text{A}} \\mathring{\\text{A}} for HCl and 1.44 \\mathring{\\text{A}} \\mathring{\\text{A}} for HBr. HCl has the result Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.620 0.000 0.000 0.000 0.620 0.380 Cl 1 1.936 5.443 0.000 0.000 7.379 -0.379 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Cl 1 0.56 1.27500 ====================================================================== While HBr has Atomic Populations (Mulliken) ----------------------------- Species Ion s p d f Total Charge (e) ========================================================================== H 1 0.824 0.000 0.000 0.000 0.824 0.176 Br 1 1.908 5.267 0.000 0.000 7.176 -0.176 ========================================================================== Bond Population Length (A) ====================================================================== H 1 -- Br 1 0.53 1.44000 ====================================================================== The most significant thing this shows us is that the charges on both atoms decrease as you go down group 7. This successfully demonstrates something we already know: as you go down group 7, the electronegativity decreases. The same principle can be applied to estimate relative electronegativities of different atoms.","title":"Diatomic molecules"},{"location":"tutorials/Coreloss/Coreloss/","text":"Coreloss Calculation of core-loss spectra for cBN Core-loss calculations effectively calculate the probability of an electron being excited from a core state into the conduction band. This is useful for calculating the core-loss (ionisation edge) peaks - by performing these calculations, you can get a simulation of what you would see in an experimental EELS or XANES spectrum. In this tutorial, we will look at the results of such a calculation on cubic boron nitride (cBN), looking at the boron K-edge. In the end, we will compare it to the spectrum in the EELS Database . We will use the cell file cbn.cell %block lattice_abc 2.5 2.5 2.5 60 60 60 %endblock lattice_abc %block positions_frac B 0.00 0.00 0.00 N 0.25 0.25 0.25 %endblock positions_frac kpoints_mp_grid 10 10 10 spectral_kpoint_mp_grid 12 12 12 with the param file cbn.param task: spectral spectral_task: coreloss xc_functional: LDA opt_strategy: speed Note that a larger number of spectral k-point than standard one is usually required, and, to test if it is converged, you'd have to look at the whole spectrum (rather than examining a single value/result as in some other convergence tests). It is also important that you do not have SYMMETRY_GENERATE on for coreloss calculations. After running Castep, run Optados with the Optados input file cbn.odi TASK : core DOS_SPACING : 0.01 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default CORE_GEOM : polycrystalline # Default CORE_LAI_BROADENING : false # Default true LAI_GAUSSIAN_WIDTH : 1.0 The line TASK : core is what determines that a core-loss calculation will be performed. CORE_GEOM : polycrystalline could also be replaced by core_geom : polarized , in which case you'd also have to add a line specifying the direction - for example, CORE_QDIR : 1 1 1 would simulate the results of an electron (or X-ray) beam going through a single crystal in the [1 1 1] direction. In this tutorial, we will be looking at the polycrystalline case, where it effectively uses the average of all directions. Running Optados should generate 2 files of interest: cbn_B1K1_core_edge.dat and cbn_N1K1_core_edge.dat - these are the results of the core-loss calculations. We will focus on the first dat file - let's look at the boron part specifically. The file starts off like -15.720790912312673 0.0000000000000000 -15.710790160394351 0.0000000000000000 -15.700789408476030 0.0000000000000000 The 1 st column is the energy and the 2 nd is the (smeared) core-loss for that energy. Let's try plotting the dat file with xmgrace - the graph should look like Let's now add some experimental broadening to the results, in order to more accurately simulate experiment. You can do so by re-running Optados (no need to re-run Castep) with CORE_LAI_BROADENING set to true and the lines LAI_GAUSSIAN_WIDTH : 1.8 LAI_LORENTZIAN_WIDTH : 0.1 LAI_LORENTZIAN_SCALE : 0.1 added to the odi file. Gaussian broadening is to simulate the instrument used, and is the same for the whole spectrum, while Lorentzian is to simulate the lifetime effects of the experiment, and is energy-dependent. A Gaussian width of 1.8 is used because we are going to compare it to the spectrum in the EELS Database , and that experiment had a resolution of 1.8eV. A Lorentzian can be used to account for the energy broadening due to the lifetime of the initial and final states. The width depends on the element and edge you are examining, and the value used is recommended here (boron is not there, but 0.1 is recommended for carbon, which is close). A Lorentzian scale of 0.1 is a general and commonly-used value. Re-running it now yields 3 columns in the dat file - it now starts like -15.720790912312673 0.0000000000000000 4.6792920824784473E-005 -15.710790160394351 0.0000000000000000 4.7285842629847867E-005 The 1 st and 2 nd columns are the same, and the 3 rd column is the lifetime and instrumentation (LAI) broadened core-loss results. To plot this with xmgrace, it is easiest to run xmgrace -batch plot.bat on the batch file plot.bat READ BLOCK \"cbn_B1K1_core_edge.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Unbroadened\" BLOCK XY \"1:3\" S1 LEGEND \"Broadened\" WORLD XMIN 0 This gives the graph below Including a core-hole The above was effectively calculating the probability of an electron being able to be excited into the conduction band, corresponding to that same energy being lost from an X-ray/electron and thus XANES/EELs data. However, when calculating that, it was not accounting for the fact that there'd be a core-hole as a result (which naturally will affect energy, DOS and thus probability of occurring): that must be factored in for more realistic results. This is done rather simply by specifying the missing electron when describing the potential in the cell file. If you look at the cbn.castep file generated earlier, you may see that the pseudopotential report contains the line \"2|1.2|12|14|16|20:21(qc=8)\" This tells us what kind of pseudopotential is used for the boron. To specify that there is a 1s electron missing, all you have to do is add {1s1.00} at the end: with only 1 electron in the 1s shell, there is a core electron missing: a core hole. Go into cbn.cell , and add the lines %block species_pot B 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot to calculate the core edge data factoring in the missing 1s electron. Note Your potential may be different, depending on your version of Castep etc. - but don't worry, as the procedure is the same. Also add the line CHARGE : +1 to the cbn.param file - this must be done to maintain charge neutrality. Next, re-run Castep. Let's have a quick look at the pseudopotential report of boron in cbn.castep ============================================================ | Pseudopotential Report - Date of generation 29-07-2024 | ------------------------------------------------------------ | Element: B Ionic charge: 4.00 Level of theory: LDA | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.865 | | 2p 1.000 -0.654 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.865 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.654 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8){1s1.00}\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ You should notice that the energies in the 2s and 2p orbitals are lower, the beta values are all different, and, most importantly, that the pseudopotential used is the one we manually wrote in: the one with only 1 electron in the 1s shell. Now, re-run Optados. This create the same files as before. Again, let's focus on the boron result. The output file cbn_B1K1_core_edge.dat now starts like: -16.879627404257498 0.0000000000000000 4.3418325679994708E-005 -16.869627177952179 0.0000000000000000 4.3433042280034070E-005 The columns represent the same information as before. Plotting it with the same batch file yields us this graph: Supercell The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. To do this, we will create a 2x2x2 supercell - the larger the supercell the better the simulation (as this reduces the core-hole interaction effect more), but the calculation time also shoots up significantly. There are multiple ways of doing this, but this tutorial will cover how it can be done using Vesta . First, upload the cell file we used to Vesta. From the top of the toolbar, go into Edit -> Edit Data -> Unit cell... . This should open up the window below Click Transform... . This opens up a new window To create the 2x2x2 supercell, the transformation matrix is rather simple: make the diagonal values 2 like in the figure above (so it becomes 2x larger in all directions) and click Ok . Select Search atoms in the new unit-cell and add them as new sites in the next pop-up window. Now that the supercell has been generated, we must save it and turn it into a cell file. Click File -> Export Data and save it as cbn.cif file (saving it as a cell file is not an option). We can use cif2cell cbn.cif to get information on how to make the new cell. In the end, we change cbn.cell to: cbn.cell %block lattice_abc 5 5 5 60 60 60 %endblock lattice_abc %block positions_frac B:exi 0.0000000 0.0000000 0.0000000 B 0.0000000 0.0000000 0.5000000 B 0.0000000 0.5000000 0.0000000 B 0.0000000 0.5000000 0.5000000 B 0.5000000 0.0000000 0.0000000 B 0.5000000 0.0000000 0.5000000 B 0.5000000 0.5000000 0.0000000 B 0.5000000 0.5000000 0.5000000 N 0.1250000 0.1250000 0.1250000 N 0.1250000 0.1250000 0.6250000 N 0.1250000 0.6250000 0.1250000 N 0.1250000 0.6250000 0.6250000 N 0.6250000 0.1250000 0.1250000 N 0.6250000 0.1250000 0.6250000 N 0.6250000 0.6250000 0.1250000 N 0.6250000 0.6250000 0.6250000 %endblock positions_frac kpoints_mp_grid 5 5 5 %block species_pot B:exi 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot spectral_kpoint_mp_grid 6 6 6 With double the size of the supercell, you may also halve the kpoints: this allows it to be calculated faster without losing accuracy. However, it will still take significantly longer to calculate. Specifying 1 of the boron atoms to be called B:exi and making changing the potential block to only affect that means that we simulate only 1 of the boron atoms losing that electron - by doing this we prevent the interaction problem mentioned above. In the param file, also add the line NEXTRA_BANDS : 100 This makes Castep perform the calculation for higher-energy bands, and is necessary to prevent too sudden of a drop in the core-loss values towards the higher energies (you may notice that in the above figures the value drops towards 0 after the peaks, but tends towards a finite non-zero value in experiment). Re-run Castep and Optados. There will now be 16 output files, rather than just 2 - there is a core edge output for every atom - cbn_ B 1 K1 B:exi_core_edge.dat is the core edge result for the boron with the missing 1s electron. The spaces in the file name can be a bit awkward so let's rename it to cbn_BExi.dat . Let's plot it the same as we have before We can see the resemblance to the database spectrum. Comparison to Experiment To get a good comparison to experiment, we will plot the results from the database and our calculation together on the same graph. You may already notice that, though the shape is similar, the x and y-axis values are very different. The y-axis corresponds to intensity (while in our calculation it is more akin to a probability), so we will scale that by just multiplying by a flat value. The x-axis needs to be adjusted by simply adding a fixed value. We can adjust our results with a simple Python script. with open ( 'cbn_BExi.dat' , 'r' ) as infile , open ( 'cbn_BExi_ss.dat' , 'w' ) as outfile : for line in infile : columns = line . split () col1 = float ( columns [ 0 ]) + 180 col2 = float ( columns [ 2 ]) * 1000000 outfile . write ( f \" { col1 } { col2 } \\n \" ) Now let's plot our Castep and the experimental results together by xmgrace with the batch file READ BLOCK \"cbn_BExi_ss.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Castep\" READ BLOCK \"Dspec.60967.1.msa\" BLOCK XY \"1:2\" S1 LEGEND \"EELS Database\" The output should look like this: They are reasonably similar, but the Optados calculation retains the problem of dropping off faster towards higher energies.","title":"Coreloss"},{"location":"tutorials/Coreloss/Coreloss/#coreloss","text":"","title":"Coreloss"},{"location":"tutorials/Coreloss/Coreloss/#calculation-of-core-loss-spectra-for-cbn","text":"Core-loss calculations effectively calculate the probability of an electron being excited from a core state into the conduction band. This is useful for calculating the core-loss (ionisation edge) peaks - by performing these calculations, you can get a simulation of what you would see in an experimental EELS or XANES spectrum. In this tutorial, we will look at the results of such a calculation on cubic boron nitride (cBN), looking at the boron K-edge. In the end, we will compare it to the spectrum in the EELS Database . We will use the cell file cbn.cell %block lattice_abc 2.5 2.5 2.5 60 60 60 %endblock lattice_abc %block positions_frac B 0.00 0.00 0.00 N 0.25 0.25 0.25 %endblock positions_frac kpoints_mp_grid 10 10 10 spectral_kpoint_mp_grid 12 12 12 with the param file cbn.param task: spectral spectral_task: coreloss xc_functional: LDA opt_strategy: speed Note that a larger number of spectral k-point than standard one is usually required, and, to test if it is converged, you'd have to look at the whole spectrum (rather than examining a single value/result as in some other convergence tests). It is also important that you do not have SYMMETRY_GENERATE on for coreloss calculations. After running Castep, run Optados with the Optados input file cbn.odi TASK : core DOS_SPACING : 0.01 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default CORE_GEOM : polycrystalline # Default CORE_LAI_BROADENING : false # Default true LAI_GAUSSIAN_WIDTH : 1.0 The line TASK : core is what determines that a core-loss calculation will be performed. CORE_GEOM : polycrystalline could also be replaced by core_geom : polarized , in which case you'd also have to add a line specifying the direction - for example, CORE_QDIR : 1 1 1 would simulate the results of an electron (or X-ray) beam going through a single crystal in the [1 1 1] direction. In this tutorial, we will be looking at the polycrystalline case, where it effectively uses the average of all directions. Running Optados should generate 2 files of interest: cbn_B1K1_core_edge.dat and cbn_N1K1_core_edge.dat - these are the results of the core-loss calculations. We will focus on the first dat file - let's look at the boron part specifically. The file starts off like -15.720790912312673 0.0000000000000000 -15.710790160394351 0.0000000000000000 -15.700789408476030 0.0000000000000000 The 1 st column is the energy and the 2 nd is the (smeared) core-loss for that energy. Let's try plotting the dat file with xmgrace - the graph should look like Let's now add some experimental broadening to the results, in order to more accurately simulate experiment. You can do so by re-running Optados (no need to re-run Castep) with CORE_LAI_BROADENING set to true and the lines LAI_GAUSSIAN_WIDTH : 1.8 LAI_LORENTZIAN_WIDTH : 0.1 LAI_LORENTZIAN_SCALE : 0.1 added to the odi file. Gaussian broadening is to simulate the instrument used, and is the same for the whole spectrum, while Lorentzian is to simulate the lifetime effects of the experiment, and is energy-dependent. A Gaussian width of 1.8 is used because we are going to compare it to the spectrum in the EELS Database , and that experiment had a resolution of 1.8eV. A Lorentzian can be used to account for the energy broadening due to the lifetime of the initial and final states. The width depends on the element and edge you are examining, and the value used is recommended here (boron is not there, but 0.1 is recommended for carbon, which is close). A Lorentzian scale of 0.1 is a general and commonly-used value. Re-running it now yields 3 columns in the dat file - it now starts like -15.720790912312673 0.0000000000000000 4.6792920824784473E-005 -15.710790160394351 0.0000000000000000 4.7285842629847867E-005 The 1 st and 2 nd columns are the same, and the 3 rd column is the lifetime and instrumentation (LAI) broadened core-loss results. To plot this with xmgrace, it is easiest to run xmgrace -batch plot.bat on the batch file plot.bat READ BLOCK \"cbn_B1K1_core_edge.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Unbroadened\" BLOCK XY \"1:3\" S1 LEGEND \"Broadened\" WORLD XMIN 0 This gives the graph below","title":"Calculation of core-loss spectra for cBN"},{"location":"tutorials/Coreloss/Coreloss/#including-a-core-hole","text":"The above was effectively calculating the probability of an electron being able to be excited into the conduction band, corresponding to that same energy being lost from an X-ray/electron and thus XANES/EELs data. However, when calculating that, it was not accounting for the fact that there'd be a core-hole as a result (which naturally will affect energy, DOS and thus probability of occurring): that must be factored in for more realistic results. This is done rather simply by specifying the missing electron when describing the potential in the cell file. If you look at the cbn.castep file generated earlier, you may see that the pseudopotential report contains the line \"2|1.2|12|14|16|20:21(qc=8)\" This tells us what kind of pseudopotential is used for the boron. To specify that there is a 1s electron missing, all you have to do is add {1s1.00} at the end: with only 1 electron in the 1s shell, there is a core electron missing: a core hole. Go into cbn.cell , and add the lines %block species_pot B 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot to calculate the core edge data factoring in the missing 1s electron. Note Your potential may be different, depending on your version of Castep etc. - but don't worry, as the procedure is the same. Also add the line CHARGE : +1 to the cbn.param file - this must be done to maintain charge neutrality. Next, re-run Castep. Let's have a quick look at the pseudopotential report of boron in cbn.castep ============================================================ | Pseudopotential Report - Date of generation 29-07-2024 | ------------------------------------------------------------ | Element: B Ionic charge: 4.00 Level of theory: LDA | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.865 | | 2p 1.000 -0.654 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.865 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.654 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8){1s1.00}\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ You should notice that the energies in the 2s and 2p orbitals are lower, the beta values are all different, and, most importantly, that the pseudopotential used is the one we manually wrote in: the one with only 1 electron in the 1s shell. Now, re-run Optados. This create the same files as before. Again, let's focus on the boron result. The output file cbn_B1K1_core_edge.dat now starts like: -16.879627404257498 0.0000000000000000 4.3418325679994708E-005 -16.869627177952179 0.0000000000000000 4.3433042280034070E-005 The columns represent the same information as before. Plotting it with the same batch file yields us this graph:","title":"Including a core-hole"},{"location":"tutorials/Coreloss/Coreloss/#supercell","text":"The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. To do this, we will create a 2x2x2 supercell - the larger the supercell the better the simulation (as this reduces the core-hole interaction effect more), but the calculation time also shoots up significantly. There are multiple ways of doing this, but this tutorial will cover how it can be done using Vesta . First, upload the cell file we used to Vesta. From the top of the toolbar, go into Edit -> Edit Data -> Unit cell... . This should open up the window below Click Transform... . This opens up a new window To create the 2x2x2 supercell, the transformation matrix is rather simple: make the diagonal values 2 like in the figure above (so it becomes 2x larger in all directions) and click Ok . Select Search atoms in the new unit-cell and add them as new sites in the next pop-up window. Now that the supercell has been generated, we must save it and turn it into a cell file. Click File -> Export Data and save it as cbn.cif file (saving it as a cell file is not an option). We can use cif2cell cbn.cif to get information on how to make the new cell. In the end, we change cbn.cell to: cbn.cell %block lattice_abc 5 5 5 60 60 60 %endblock lattice_abc %block positions_frac B:exi 0.0000000 0.0000000 0.0000000 B 0.0000000 0.0000000 0.5000000 B 0.0000000 0.5000000 0.0000000 B 0.0000000 0.5000000 0.5000000 B 0.5000000 0.0000000 0.0000000 B 0.5000000 0.0000000 0.5000000 B 0.5000000 0.5000000 0.0000000 B 0.5000000 0.5000000 0.5000000 N 0.1250000 0.1250000 0.1250000 N 0.1250000 0.1250000 0.6250000 N 0.1250000 0.6250000 0.1250000 N 0.1250000 0.6250000 0.6250000 N 0.6250000 0.1250000 0.1250000 N 0.6250000 0.1250000 0.6250000 N 0.6250000 0.6250000 0.1250000 N 0.6250000 0.6250000 0.6250000 %endblock positions_frac kpoints_mp_grid 5 5 5 %block species_pot B:exi 2|1.2|12|14|16|20:21(qc=8){1s1.00} %endblock species_pot spectral_kpoint_mp_grid 6 6 6 With double the size of the supercell, you may also halve the kpoints: this allows it to be calculated faster without losing accuracy. However, it will still take significantly longer to calculate. Specifying 1 of the boron atoms to be called B:exi and making changing the potential block to only affect that means that we simulate only 1 of the boron atoms losing that electron - by doing this we prevent the interaction problem mentioned above. In the param file, also add the line NEXTRA_BANDS : 100 This makes Castep perform the calculation for higher-energy bands, and is necessary to prevent too sudden of a drop in the core-loss values towards the higher energies (you may notice that in the above figures the value drops towards 0 after the peaks, but tends towards a finite non-zero value in experiment). Re-run Castep and Optados. There will now be 16 output files, rather than just 2 - there is a core edge output for every atom - cbn_ B 1 K1 B:exi_core_edge.dat is the core edge result for the boron with the missing 1s electron. The spaces in the file name can be a bit awkward so let's rename it to cbn_BExi.dat . Let's plot it the same as we have before We can see the resemblance to the database spectrum.","title":"Supercell"},{"location":"tutorials/Coreloss/Coreloss/#comparison-to-experiment","text":"To get a good comparison to experiment, we will plot the results from the database and our calculation together on the same graph. You may already notice that, though the shape is similar, the x and y-axis values are very different. The y-axis corresponds to intensity (while in our calculation it is more akin to a probability), so we will scale that by just multiplying by a flat value. The x-axis needs to be adjusted by simply adding a fixed value. We can adjust our results with a simple Python script. with open ( 'cbn_BExi.dat' , 'r' ) as infile , open ( 'cbn_BExi_ss.dat' , 'w' ) as outfile : for line in infile : columns = line . split () col1 = float ( columns [ 0 ]) + 180 col2 = float ( columns [ 2 ]) * 1000000 outfile . write ( f \" { col1 } { col2 } \\n \" ) Now let's plot our Castep and the experimental results together by xmgrace with the batch file READ BLOCK \"cbn_BExi_ss.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Castep\" READ BLOCK \"Dspec.60967.1.msa\" BLOCK XY \"1:2\" S1 LEGEND \"EELS Database\" The output should look like this: They are reasonably similar, but the Optados calculation retains the problem of dropping off faster towards higher energies.","title":"Comparison to Experiment"},{"location":"tutorials/Delta_SCF/lin_ex_delta_scf/","text":"Electronic excitations of NO on Ni(001) ATTENTION: These calculations are done using standard on-the-fly pseudopotentials from CASTEP-6.0.1 For this example we calculate a charge neutral HOMO->LUMO excitation and a charge transfer excitation between a nickel substrate and a NO molecule In the following, the required input files are: no-on-ni001.param, no-on-ni001.cell, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param #reuse: default calculate_deltascf : true deltascf_method : linear expansion deltascf_checkpoint : gasphase.check #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay mix_history_length : 7 nextra_bands : 50 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.15 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE The workflow is as follows: Calculate reference states (gasphase.check). These can be ground state Kohn-Sham states or themselves excited KS states Calculate the ground state of NO on Ni(001) Final energy, E = -7867.950085034 eV Calculate the leDeltaSCF excitation We calculate a charge transfer from the molecule to the surface by removing an electron from the HOMO in the majority spin channel #band occ spin %block deltascf_constraints 5 0.0000 1 %endblock deltascf_constraints WARNING A sufficient number of virtual states in the calculation, controlled by the keyword nextra_states, is very important. The more virtual states are used explicitly, the more complete is the projection onto the space of KS states. Sometimes states are almost degenerate and we also need to constrain the occupation of the other state to ensure that the population doesn\\'t just switch between the two. In some cases, convergence can be very slow and a large number of SCF steps is necessary. The resulting excitation energy is 0.46 eV. Final energy, E = -7867.487338823 eV We can calculate an intramolecular triplet excitation from HOMO to LUMO with the following constraint sequence in \\.deltascf. This excites 1 electron from the HOMO in the majority spin channel to the LUMO in the minority spin channel. #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints The resulting excitation energy is 9.17 eV. Final energy, E = -7858.779610351 eV","title":"Linear expansion DeltaSCF"},{"location":"tutorials/Delta_SCF/lin_ex_delta_scf/#electronic-excitations-of-no-on-ni001","text":"ATTENTION: These calculations are done using standard on-the-fly pseudopotentials from CASTEP-6.0.1 For this example we calculate a charge neutral HOMO->LUMO excitation and a charge transfer excitation between a nickel substrate and a NO molecule In the following, the required input files are: no-on-ni001.param, no-on-ni001.cell, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param #reuse: default calculate_deltascf : true deltascf_method : linear expansion deltascf_checkpoint : gasphase.check #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay mix_history_length : 7 nextra_bands : 50 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.15 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE The workflow is as follows: Calculate reference states (gasphase.check). These can be ground state Kohn-Sham states or themselves excited KS states Calculate the ground state of NO on Ni(001) Final energy, E = -7867.950085034 eV Calculate the leDeltaSCF excitation We calculate a charge transfer from the molecule to the surface by removing an electron from the HOMO in the majority spin channel #band occ spin %block deltascf_constraints 5 0.0000 1 %endblock deltascf_constraints WARNING A sufficient number of virtual states in the calculation, controlled by the keyword nextra_states, is very important. The more virtual states are used explicitly, the more complete is the projection onto the space of KS states. Sometimes states are almost degenerate and we also need to constrain the occupation of the other state to ensure that the population doesn\\'t just switch between the two. In some cases, convergence can be very slow and a large number of SCF steps is necessary. The resulting excitation energy is 0.46 eV. Final energy, E = -7867.487338823 eV We can calculate an intramolecular triplet excitation from HOMO to LUMO with the following constraint sequence in \\.deltascf. This excites 1 electron from the HOMO in the majority spin channel to the LUMO in the minority spin channel. #band occ spin %block deltascf_constraints 5 0.0000 1 6 1.0000 2 %endblock deltascf_constraints The resulting excitation energy is 9.17 eV. Final energy, E = -7858.779610351 eV","title":"Electronic excitations of NO on Ni(001)"},{"location":"tutorials/Delta_SCF/molpdos/","text":"NO molecule on Ni(001) For this example we calculate the projected MOs of a NO molecule on a Ni(001) slab. In the following the required input files are: no-on-ni001.param, no-on-ni001.cell, no-on-ni001.molpdos, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param calculate_modos : true deltascf_checkpoint : gasphase task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 no-on-ni001.molpdos molpdos_state : 4 1 molpdos_state : 5 1 molpdos_state : 6 1 molpdos_state : 4 2 molpdos_state : 5 2 molpdos_state : 6 2 molpdos_bin_width : 0.01 molpdos_smearing : 0.10 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE After generating gasphase.check by running CASTEP on the gasphase.param and gasphase.cell files, we execute CASTEP and post-process with MolPDOS. This will write x-y data files for the Total DOS, the separate spin channels, and the MolPDOS peaks. The following image shows the Total DOS and the two spin channels. The next picture shows the frontier orbitals of spin channel 1 projected on the total DOS. Especially the LUMO shows strong hybridization with the Nickel d-bands and also is partially occupied. The left scale refers to the total DOS, whereas the right y-scale shows the peak height of the projected MOs. GOOD TO KNOW If you ever forget the correct input for .molpdos, just run the MolPDOS tool without seed. The printed information is all you need!","title":"Molecular Projected DOS"},{"location":"tutorials/Delta_SCF/molpdos/#no-molecule-on-ni001","text":"For this example we calculate the projected MOs of a NO molecule on a Ni(001) slab. In the following the required input files are: no-on-ni001.param, no-on-ni001.cell, no-on-ni001.molpdos, gasphase.cell, gasphase.param, gasphase.check no-on-ni001.param calculate_modos : true deltascf_checkpoint : gasphase task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE no-on-ni001.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS Ni 1.762000 0.000000 1.762000 Ni 0.000000 1.762000 1.762000 Ni 0.000000 0.000000 3.524000 Ni 1.762000 1.762000 3.524000 Ni 1.762000 0.000000 5.286000 Ni 0.000000 1.762000 5.286000 N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS %BLOCK IONIC_CONSTRAINTS 1 Ni 1 1 0 0 2 Ni 1 0 1 0 3 Ni 1 0 0 1 4 Ni 2 1 0 0 5 Ni 2 0 1 0 6 Ni 2 0 0 1 7 Ni 3 1 0 0 8 Ni 3 0 1 0 9 Ni 3 0 0 1 10 Ni 4 1 0 0 11 Ni 4 0 1 0 12 Ni 4 0 0 1 13 Ni 5 1 0 0 14 Ni 5 0 1 0 15 Ni 5 0 0 1 16 Ni 6 1 0 0 17 Ni 6 0 1 0 18 Ni 6 0 0 1 %ENDBLOCK IONIC_CONSTRAINTS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 no-on-ni001.molpdos molpdos_state : 4 1 molpdos_state : 5 1 molpdos_state : 6 1 molpdos_state : 4 2 molpdos_state : 5 2 molpdos_state : 6 2 molpdos_bin_width : 0.01 molpdos_smearing : 0.10 molpdos_scaling : 1.00 axis_energy_margin : 2.00 output_filename : MolPDOS.dat gasphase.cell %BLOCK LATTICE_CART 3.5240000000 0.0000000000 0.0000000000 0.0000000000 3.5240000000 0.0000000000 0.0000000000 0.0000000000 23.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS N 1.7620 0.0000 7.0196 O 1.7620 -0.0000 8.1902 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 2 2 1 KPOINTS_MP_OFFSET : 0.25 0.25 0.25 gasphase.param task: SinglePoint spin_polarized : True cut_off_energy : 400.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : RPBE After generating gasphase.check by running CASTEP on the gasphase.param and gasphase.cell files, we execute CASTEP and post-process with MolPDOS. This will write x-y data files for the Total DOS, the separate spin channels, and the MolPDOS peaks. The following image shows the Total DOS and the two spin channels. The next picture shows the frontier orbitals of spin channel 1 projected on the total DOS. Especially the LUMO shows strong hybridization with the Nickel d-bands and also is partially occupied. The left scale refers to the total DOS, whereas the right y-scale shows the peak height of the projected MOs. GOOD TO KNOW If you ever forget the correct input for .molpdos, just run the MolPDOS tool without seed. The printed information is all you need!","title":"NO molecule on Ni(001)"},{"location":"tutorials/Delta_SCF/simple_delta_scf/","text":"Electronic excitations of the Azobenzene molecule In this example we calculate the first two electronic excited states of E-Azobenzene in a supercell. The required files are azo.cell and azo.param: azo.param task: SinglePoint reuse: default calculate_deltascf : true deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints spin_polarized : False cut_off_energy : 350.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : PBE azo.cell %BLOCK LATTICE_CART 10.0000000 0.0000000000 0.0000000000 0.0000000000 20.0000000 0.0000000000 0.0000000000 0.0000000000 10.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS C -6.72081 -1.66625 0.00000 C -6.64967 -0.26964 0.00000 C -5.40647 0.36858 -0.00000 C -4.23175 -0.38857 -0.00000 C -4.29745 -1.78579 -0.00000 C -5.54882 -2.43430 -0.00000 H -7.68820 -2.15296 0.00000 H -7.55879 0.31772 0.00000 H -5.35348 1.44963 -0.00000 H -3.26966 0.10734 -0.00000 H -3.37789 -2.35693 -0.00000 N -5.65342 -3.85046 -0.00000 N -4.64259 -4.58194 -0.00000 C -4.75058 -5.99808 -0.00000 C -6.00434 -6.64214 -0.00000 C -6.07567 -8.03881 -0.00000 C -4.90409 -8.80053 -0.00000 C -3.65828 -8.16721 -0.00000 C -3.58139 -6.77065 -0.00000 H -2.61200 -6.28795 -0.00000 H -6.92178 -6.06761 -0.00000 H -7.03986 -8.53061 -0.00000 H -4.96168 -9.88134 -0.00000 H -2.75170 -8.75849 -0.00000 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 1 1 1 We start by calculating the total DFT ground state energy as Final energy, E = -2597.665647686 eV Now we reuse the calculated wavefunctions and switch to the DeltaSCF calculation (param file above) There are 68 valence electrons. Therefore, for this non-spin-polarized system the HOMO orbital is orbital no. 34. The LUMO is orbital no. 35. The first two excited states of azobenzene are known to be S1(n->pi*) and S2(pi->pi*) transitions between the HOMO and LUMO and the HOMO-1 and the LUMO. The corresponding constraint sequence in azo.deltascf for the S1 excitation is #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints WARNING When running non-spin-polarized calculations, orbital occupations range from 0 to 1. !!When running a spin-polarized calculation, they also range from 0 to 1, although they contain 0 to 2 electrons. In this (non-spin-polarized) case, if we want to transfer an electron from the HOMO(34) to LUMO(35) we need to enforce the occupation of both to be 0.50. Feel free to increase the print level with iprint to study the output in more detail. The corresponding total energy is Final energy, E = -2595.702720896 eV This corresponds to an S1 excitation energy of 1.96 eV. The constraint sequence for an S2 excitation is #band occ spin from_band to_band %block deltascf_constraints 33 0.5000 1 33 33 35 0.5000 1 35 35 %endblock deltascf_constraints The resulting final energy is Final energy, E = -2594.762182241 eV The corresponding S2 excitation energy is 2.90 eV.","title":"Simple Delta SCF"},{"location":"tutorials/Delta_SCF/simple_delta_scf/#electronic-excitations-of-the-azobenzene-molecule","text":"In this example we calculate the first two electronic excited states of E-Azobenzene in a supercell. The required files are azo.cell and azo.param: azo.param task: SinglePoint reuse: default calculate_deltascf : true deltascf_method : simple deltascf_smearing : 0.01 #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints spin_polarized : False cut_off_energy : 350.0 elec_energy_tol : 1e-07 fix_occupancy : False iprint : 1 max_scf_cycles : 200 metals_method : dm mixing_scheme : Pulay nextra_bands : 10 num_dump_cycles : 0 opt_strategy_bias : 3 smearing_scheme : Gaussian smearing_width : 0.1 xc_functional : PBE azo.cell %BLOCK LATTICE_CART 10.0000000 0.0000000000 0.0000000000 0.0000000000 20.0000000 0.0000000000 0.0000000000 0.0000000000 10.0000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_ABS C -6.72081 -1.66625 0.00000 C -6.64967 -0.26964 0.00000 C -5.40647 0.36858 -0.00000 C -4.23175 -0.38857 -0.00000 C -4.29745 -1.78579 -0.00000 C -5.54882 -2.43430 -0.00000 H -7.68820 -2.15296 0.00000 H -7.55879 0.31772 0.00000 H -5.35348 1.44963 -0.00000 H -3.26966 0.10734 -0.00000 H -3.37789 -2.35693 -0.00000 N -5.65342 -3.85046 -0.00000 N -4.64259 -4.58194 -0.00000 C -4.75058 -5.99808 -0.00000 C -6.00434 -6.64214 -0.00000 C -6.07567 -8.03881 -0.00000 C -4.90409 -8.80053 -0.00000 C -3.65828 -8.16721 -0.00000 C -3.58139 -6.77065 -0.00000 H -2.61200 -6.28795 -0.00000 H -6.92178 -6.06761 -0.00000 H -7.03986 -8.53061 -0.00000 H -4.96168 -9.88134 -0.00000 H -2.75170 -8.75849 -0.00000 %ENDBLOCK POSITIONS_ABS FIX_ALL_CELL : True KPOINTS_MP_GRID : 1 1 1 We start by calculating the total DFT ground state energy as Final energy, E = -2597.665647686 eV Now we reuse the calculated wavefunctions and switch to the DeltaSCF calculation (param file above) There are 68 valence electrons. Therefore, for this non-spin-polarized system the HOMO orbital is orbital no. 34. The LUMO is orbital no. 35. The first two excited states of azobenzene are known to be S1(n->pi*) and S2(pi->pi*) transitions between the HOMO and LUMO and the HOMO-1 and the LUMO. The corresponding constraint sequence in azo.deltascf for the S1 excitation is #band occ spin from_band to_band %block deltascf_constraints 34 0.5000 1 34 34 35 0.5000 1 35 35 %endblock deltascf_constraints WARNING When running non-spin-polarized calculations, orbital occupations range from 0 to 1. !!When running a spin-polarized calculation, they also range from 0 to 1, although they contain 0 to 2 electrons. In this (non-spin-polarized) case, if we want to transfer an electron from the HOMO(34) to LUMO(35) we need to enforce the occupation of both to be 0.50. Feel free to increase the print level with iprint to study the output in more detail. The corresponding total energy is Final energy, E = -2595.702720896 eV This corresponds to an S1 excitation energy of 1.96 eV. The constraint sequence for an S2 excitation is #band occ spin from_band to_band %block deltascf_constraints 33 0.5000 1 33 33 35 0.5000 1 35 35 %endblock deltascf_constraints The resulting final energy is Final energy, E = -2594.762182241 eV The corresponding S2 excitation energy is 2.90 eV.","title":"Electronic excitations of the Azobenzene molecule"},{"location":"tutorials/GA/Introduction/","text":"Introduction In this tutorial we will look at exactly what castep GA is doing when it is used, examining what the input files do what the output files tell us. We will go through a silicon example to do so - starting from a heavily distorted diamond cell and ending in a diamond structure. Input Files We will use the cell file Si.cell %block LATTICE_ABC ang 5.4 5.4 5.4 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.2 0.01 0.04 Si 0.21 0.29 0.30 Si 0.59 0.43 0.03 Si 0.9 0.81 0.30 Si 0.53 0.03 0.58 Si 0.72 0.21 0.79 Si 0.04 0.45 0.4 Si 0.28 0.85 0.69 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang Note that this is just a heavily distorted version of a ideal diamond silicon cell - LATTICE_ABC defines its cubic structure with the lattice parameter that is expected, while the fractional positions of all the Si's are slightly moved from where they'd be expected for diamond - for example the first line Si 0.2 0.01 0.04 is only a bit off from where it'd be in a perfect diamond, which is Si 0 0 0 In a normal castep GA run the positions of all the Si's, and even the starting unit cell, is completely arbitrary, and in most cases it should have little impact on the run. However, in this case we are trying to get it to get to diamond quickly, so that it is easier to analyse what is going on. For the param file we will use task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 6 # Max number of generations to run for ga_mutate_amp = 0.05 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.1 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 129189 # Random seed for replicability # continuation = Si.xyz ################################################################# # CASTEP Geomtery Optimisation Parameters # # These will be used for each cells geom opt/fitenss evaluation # ################################################################# comment = Si_Convex_hull #rand_seed = 100003 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=11 RSC=T RSN=1 CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code There is a lot more to discuss here. For more information on all the key words look at the documentation (ADD LINK LATER). However, let's look at the key information here: ga_max_gens defines the number of generations it will run for. 6 is a very low amount, but it does the job here ga_mutate_amp describes how severe the mutations are. Again, this is using a low number because we're starting not too far off the final result ga_mutate_rate tells you the probability of different parts of the cell mutating - 0.1 is a fairly ordinary value to use A key line for this tutorial is rand_seed = 129189 This means that you may be able to replicate similar results, though that isn't guranteed [[CHECK IF EVEN TRUE]] Running We can now run castep GA on the Si. This should take about 3 minutes to run, but look at what is happening as it is running - you can use tail -f Si.castep to keep track of how the castep output file is being generated. Also, refresh your directory regularly to see what's being generated. The first files to be generated will have the same format as Si.gen_000_mem_001.cell and Si.gen_000_mem_001.param - this is the 1 st member of the 0 th generation, which is generated randomly using the Si.cell as well as the mutation values specified in the Si.param file Note I will refer to future files as being .file_ending in the interest of brevity, specifying details where necessary You should get a total of 12 members like that, up to mem_012 . As it's running, the 0 th generation will start to get .geom and -out.cell outputs for each member. These are obtained as fast geometry optimisations (ADD LINK) are performed on the randomly generated cells. After the last member finishes its geometry optimisation, the next generation is generated: you'll get .cell and .param files. This is the point where the castep output file gets interesting. You have a table that starts like GA: gen # 1 parent # 1 enthalpy = -3.940733E+000 eV/atom un-scaled fitness = 0.684242 conv = T member error = F seed = Si.gen_000_mem_001 vol/ion = 19.4307 A**3/atom GA: gen # 1 parent # 2 enthalpy = -4.070795E+000 eV/atom un-scaled fitness = 0.791433 conv = T member error = F seed = Si.gen_000_mem_002 vol/ion = 20.4806 A**3/atom and ends with GA: gen # 1 child # 11 enthalpy = -4.200422E+000 eV/atom un-scaled fitness = 0.868980 conv = T member error = F seed = Si.gen_001_mem_011 vol/ion = 20.7893 A**3/atom GA: gen # 1 child # 12 enthalpy = -3.296903E+000 eV/atom un-scaled fitness = 0.119203 conv = T member error = F seed = Si.gen_001_mem_012 vol/ion = 28.3264 A**3/atom The parent rows all using generation 0 members as the seed, and giving them an un-scaled fitness . What this means is that all the geometry-optimised cells from generation 0 have their enthalpy and similarity checked - the lower the enthalpy the fitter it is considered, as that is desirable to get the best structure. However, a structure that is similar to another parent will be penalised to encourage diversity. Those parents then breed together to form the children, which are then mutated and geometry optimised like before. The probability of a parent breeding is based on its fitness evaluation - in the example above, parent 2 is more likely to breed than parent 1 (ADD LINK TO ROULETTE RANDOMNESS) You may find the ancestry of each individual child by looking for parts of the castep file such as GA: Member filename Si.gen_002_mem_011 GA: Parent 1 generation 0 and member 9 GA: Parent 2 generation 1 and member 9 Here you see that generation 2 member 11 was made by using the parents generation 0 member 9 and generation 1 member 9. After the children are generated and geometry optimised, they are treated exactly the same as the parents and every member has their fitness (re)evaluated - the enthalpy is already calculated but similarities must be penalised. This leads to a very similar table labelled GA: updated fitnesses with weighted fitness function For generation 2 the table starts with GA: gen # 2 parent # 1 enthalpy = -4.225502E+000 eV/atom un-scaled fitness = 0.866683 conv = T member error = F seed = Si.gen_001_mem_006 vol/ion = 19.0994 A**3/atom GA: gen # 2 parent # 2 enthalpy = -4.200403E+000 eV/atom un-scaled fitness = 0.839781 conv = T member error = F seed = Si.gen_000_mem_009 vol/ion = 20.7940 A**3/atom Here you'll notice that there are parents from both generation 0 (2 nd line) and generation (1 st ) - based on their fitness, 12 got eliminated while the other 12 stayed to become parents in the next generation. The same exact procedure repeats - parents breed (with fitter ones doing moreso), children mutate and optimise, the parents and children are compared together as equal members and the best ones move on to become parents of the next generation. This is done until generation 6. The best structure Finding the best structure found is fairly simple - if using Linux you may use the command grep 'child' Si.castep | sort -k10,10n | head -20 In my case I got generation 6 member 7 to be the lowest enthalpy. Running c2x --int -e=0.1-0.0001 Si.gen_006_mem_007-out.cell tells me that it is Fd-3m - diamond (though the lower tolerance structure is R-3m - this was a very short run so it hasn't got the perfect structure still, but it is close). The 'family tree' of that cell looks like this: Let's go through the steps above to see what happened in this specific case - The 0 th generation was randomly generated. In this case, members 2, 5, 9, 10 and 12 ended up being ancestors of the final structure Members 2 and 5 bred to generate 1,4 (which mutated). The same happened for member 9 Generation 2 member 11 was created using 0, 9 and 1,9. This means that out of the 24 potential parents from generation 1 (12 parents and 12 children generated from said parents), both of them were fit enough to become parents for generation 2. Generation 3 member 4 was created by breeding 2,11 and 1,4. This means that 1,4 survived the fitness tests of generations 1 (where it was made as a child) and 2, where it competed with other parents and their children alike. In generations 4, 5 and 6, no ancestors were generated. Looking forward, that means that 1,4 and 2,11 either didn't breed at all (the parent combinations are ROULETTE RANDOM) or whatever child they made didn't have a mutation favourable enough to be the lowest enthalpy structure. Finally, in generation 6, 3,4 bred with 2,11 (its own parent - again after the children are generated they are all treated as equal parent candidates) to generate 6,7. Please note that in actual runs the family tree will most likely be significantly more complicated - as noted before, both cell and param files were geared towards getting a good structure in few generations and modest mutations. Even with such files it is highly chance-based whether you will get such a result. This was just a simple demonstration.","title":"Introduction"},{"location":"tutorials/GA/Introduction/#introduction","text":"In this tutorial we will look at exactly what castep GA is doing when it is used, examining what the input files do what the output files tell us. We will go through a silicon example to do so - starting from a heavily distorted diamond cell and ending in a diamond structure.","title":"Introduction"},{"location":"tutorials/GA/Introduction/#input-files","text":"We will use the cell file Si.cell %block LATTICE_ABC ang 5.4 5.4 5.4 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.2 0.01 0.04 Si 0.21 0.29 0.30 Si 0.59 0.43 0.03 Si 0.9 0.81 0.30 Si 0.53 0.03 0.58 Si 0.72 0.21 0.79 Si 0.04 0.45 0.4 Si 0.28 0.85 0.69 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang Note that this is just a heavily distorted version of a ideal diamond silicon cell - LATTICE_ABC defines its cubic structure with the lattice parameter that is expected, while the fractional positions of all the Si's are slightly moved from where they'd be expected for diamond - for example the first line Si 0.2 0.01 0.04 is only a bit off from where it'd be in a perfect diamond, which is Si 0 0 0 In a normal castep GA run the positions of all the Si's, and even the starting unit cell, is completely arbitrary, and in most cases it should have little impact on the run. However, in this case we are trying to get it to get to diamond quickly, so that it is easier to analyse what is going on. For the param file we will use task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 6 # Max number of generations to run for ga_mutate_amp = 0.05 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.1 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 129189 # Random seed for replicability # continuation = Si.xyz ################################################################# # CASTEP Geomtery Optimisation Parameters # # These will be used for each cells geom opt/fitenss evaluation # ################################################################# comment = Si_Convex_hull #rand_seed = 100003 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=11 RSC=T RSN=1 CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code There is a lot more to discuss here. For more information on all the key words look at the documentation (ADD LINK LATER). However, let's look at the key information here: ga_max_gens defines the number of generations it will run for. 6 is a very low amount, but it does the job here ga_mutate_amp describes how severe the mutations are. Again, this is using a low number because we're starting not too far off the final result ga_mutate_rate tells you the probability of different parts of the cell mutating - 0.1 is a fairly ordinary value to use A key line for this tutorial is rand_seed = 129189 This means that you may be able to replicate similar results, though that isn't guranteed [[CHECK IF EVEN TRUE]]","title":"Input Files"},{"location":"tutorials/GA/Introduction/#running","text":"We can now run castep GA on the Si. This should take about 3 minutes to run, but look at what is happening as it is running - you can use tail -f Si.castep to keep track of how the castep output file is being generated. Also, refresh your directory regularly to see what's being generated. The first files to be generated will have the same format as Si.gen_000_mem_001.cell and Si.gen_000_mem_001.param - this is the 1 st member of the 0 th generation, which is generated randomly using the Si.cell as well as the mutation values specified in the Si.param file Note I will refer to future files as being .file_ending in the interest of brevity, specifying details where necessary You should get a total of 12 members like that, up to mem_012 . As it's running, the 0 th generation will start to get .geom and -out.cell outputs for each member. These are obtained as fast geometry optimisations (ADD LINK) are performed on the randomly generated cells. After the last member finishes its geometry optimisation, the next generation is generated: you'll get .cell and .param files. This is the point where the castep output file gets interesting. You have a table that starts like GA: gen # 1 parent # 1 enthalpy = -3.940733E+000 eV/atom un-scaled fitness = 0.684242 conv = T member error = F seed = Si.gen_000_mem_001 vol/ion = 19.4307 A**3/atom GA: gen # 1 parent # 2 enthalpy = -4.070795E+000 eV/atom un-scaled fitness = 0.791433 conv = T member error = F seed = Si.gen_000_mem_002 vol/ion = 20.4806 A**3/atom and ends with GA: gen # 1 child # 11 enthalpy = -4.200422E+000 eV/atom un-scaled fitness = 0.868980 conv = T member error = F seed = Si.gen_001_mem_011 vol/ion = 20.7893 A**3/atom GA: gen # 1 child # 12 enthalpy = -3.296903E+000 eV/atom un-scaled fitness = 0.119203 conv = T member error = F seed = Si.gen_001_mem_012 vol/ion = 28.3264 A**3/atom The parent rows all using generation 0 members as the seed, and giving them an un-scaled fitness . What this means is that all the geometry-optimised cells from generation 0 have their enthalpy and similarity checked - the lower the enthalpy the fitter it is considered, as that is desirable to get the best structure. However, a structure that is similar to another parent will be penalised to encourage diversity. Those parents then breed together to form the children, which are then mutated and geometry optimised like before. The probability of a parent breeding is based on its fitness evaluation - in the example above, parent 2 is more likely to breed than parent 1 (ADD LINK TO ROULETTE RANDOMNESS) You may find the ancestry of each individual child by looking for parts of the castep file such as GA: Member filename Si.gen_002_mem_011 GA: Parent 1 generation 0 and member 9 GA: Parent 2 generation 1 and member 9 Here you see that generation 2 member 11 was made by using the parents generation 0 member 9 and generation 1 member 9. After the children are generated and geometry optimised, they are treated exactly the same as the parents and every member has their fitness (re)evaluated - the enthalpy is already calculated but similarities must be penalised. This leads to a very similar table labelled GA: updated fitnesses with weighted fitness function For generation 2 the table starts with GA: gen # 2 parent # 1 enthalpy = -4.225502E+000 eV/atom un-scaled fitness = 0.866683 conv = T member error = F seed = Si.gen_001_mem_006 vol/ion = 19.0994 A**3/atom GA: gen # 2 parent # 2 enthalpy = -4.200403E+000 eV/atom un-scaled fitness = 0.839781 conv = T member error = F seed = Si.gen_000_mem_009 vol/ion = 20.7940 A**3/atom Here you'll notice that there are parents from both generation 0 (2 nd line) and generation (1 st ) - based on their fitness, 12 got eliminated while the other 12 stayed to become parents in the next generation. The same exact procedure repeats - parents breed (with fitter ones doing moreso), children mutate and optimise, the parents and children are compared together as equal members and the best ones move on to become parents of the next generation. This is done until generation 6.","title":"Running"},{"location":"tutorials/GA/Introduction/#the-best-structure","text":"Finding the best structure found is fairly simple - if using Linux you may use the command grep 'child' Si.castep | sort -k10,10n | head -20 In my case I got generation 6 member 7 to be the lowest enthalpy. Running c2x --int -e=0.1-0.0001 Si.gen_006_mem_007-out.cell tells me that it is Fd-3m - diamond (though the lower tolerance structure is R-3m - this was a very short run so it hasn't got the perfect structure still, but it is close). The 'family tree' of that cell looks like this: Let's go through the steps above to see what happened in this specific case - The 0 th generation was randomly generated. In this case, members 2, 5, 9, 10 and 12 ended up being ancestors of the final structure Members 2 and 5 bred to generate 1,4 (which mutated). The same happened for member 9 Generation 2 member 11 was created using 0, 9 and 1,9. This means that out of the 24 potential parents from generation 1 (12 parents and 12 children generated from said parents), both of them were fit enough to become parents for generation 2. Generation 3 member 4 was created by breeding 2,11 and 1,4. This means that 1,4 survived the fitness tests of generations 1 (where it was made as a child) and 2, where it competed with other parents and their children alike. In generations 4, 5 and 6, no ancestors were generated. Looking forward, that means that 1,4 and 2,11 either didn't breed at all (the parent combinations are ROULETTE RANDOM) or whatever child they made didn't have a mutation favourable enough to be the lowest enthalpy structure. Finally, in generation 6, 3,4 bred with 2,11 (its own parent - again after the children are generated they are all treated as equal parent candidates) to generate 6,7. Please note that in actual runs the family tree will most likely be significantly more complicated - as noted before, both cell and param files were geared towards getting a good structure in few generations and modest mutations. Even with such files it is highly chance-based whether you will get such a result. This was just a simple demonstration.","title":"The best structure"},{"location":"tutorials/GA/Silicon/","text":"Castep GA for silicon Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA! Input Files We will use the cell file Si.cell %block LATTICE_ABC ang 3.8 3.8 3.8 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.203 0.617 0.209 Si 0.844 0.442 0.350 Si 0.964 0.379 0.096 Si 0.762 0.524 0.941 Si 0.544 0.605 0.781 Si 0.238 0.597 0.531 Si 0.728 0.914 0.742 Si 0.209 0.929 0.435 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang The definition of the lattice and positions of the atoms is fairly inconsequential to the result you will get: in the 0 th generation it gets effectively randomised. The only thing that matters is the amount of Si atoms defined in the POSITIONS_FRAC block - here it is 8 so future structures will also have 8 atoms. Another thing worth noting is the QC5 potential being used - it is used due to its speed, which is essential considering how many calculations will be done. For the param file we will use Si.param task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 12 # Max number of generations to run for ga_mutate_amp = 1.00 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.15 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 101213 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=12 RSC=F CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code It is important to understand what is going on in this file. The line task = genetic algor is what tells is to actually run GA. The GA parameters tell the GA how to run- unlike in the previous tutorial (ADD LINK), all of these values are reasonable (the mutation amplitude and rate shouldn't be far off those values in most cases). As you can see, we will have 12 parents in each generation (meaning 12 cells will be chosen to breed), and it will run for 12 generations. ga_fixed_N is what ensures that there are fixed 8 ions in the cell (the more information is fixed, the faster it'll get a decent result as it'll have fewer things to try). There are numerous lines that speed up the GA - with how many calculations are being performed, this is essential to be feasible. op_strategy = SPEED and geom_max_iter = 211 help ensure that the geometry optimisations (of which there are 12 per generation - so 144 in total for this first run!) are fast but reasonably accurate. AS=T and MS=3 allow asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. The devel_code block is a bit more complex. The fact that pair potentials are used are defined in both the GA sub-block and GEOM sub-block, again necessary for speed. The CMD sub-block is there so that geometry optimisations are performed on all members: what happens is cell files are generated (initially randomly and in the 1 st generation onwards by breeding + mutation), as well as respective param files that tell them to geometry optimise, for each member, and then they are run. A very important thing to note are the lines NUM_CHILDREN = 12 RSC = F This is highly atypical and would not be used in most actual calculations: instead, it would look like this NUM_CHILDREN=11 RSC=T RSN=1 With the general rule that NUM_CHILREN + RSN = ga_pop_size (defined earlier). What that does is, in every generation, it creates 1 child as a random high-symmetry structure (with the other 11, NUM_CHILDREN , being bred). The reason this is not used here is because Silicon is a very simple example: it is likely to simply randomly guess that it's diamond, meaning the actual GA was inconsequential and the result is uninteresting. Note Though not a gurantee, using an identical RAND_SEED makes it likely that you'll get identical results to this tutorial, so you can follow along more easily Running and Output Now we can run castep GA on Si. You may use tail -f Si.castep If you wish to see what's going on in the castep file as it runs (it's explained in more detail in the previous tutorial ADD LINK). Once it is done running, we will use the scripts get_data.sh and plot_results.py - first run ./get_data.sh to get the output file out.put . Run the python script to see that data visually in all_gens.png . The graph should look like this Each dot in this graph is a member, showing the spread of enthalpy against their volume per ion. The lowest enthalpy member (in this generation generation 6, member 9) is highlighted - this is is currently considered the most stable structure found. You can also find the lowest enthalpy structure by running grep 'child' Si.castep | sort -k10,10n | head -20 This gives the 10 lowest enthalpy members (each one repeats twice - don't worry about that). The output looks a bit like GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom un-scaled fitness = 0.880788 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom updated fitness = 0.452993 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom un-scaled fitness = 0.828518 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom updated fitness = 0.456619 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom un-scaled fitness = 0.835359 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom updated fitness = 0.432991 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom un-scaled fitness = 0.835345 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom updated fitness = 0.432963 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom un-scaled fitness = 0.801207 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom updated fitness = 0.420408 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom un-scaled fitness = 0.865596 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom updated fitness = 0.444351 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom This further confirms that 6,9 is the most stable member. Now we will examine the structure of it. Running c2x on it via c2x --int -e=0.1-0.0001 Si.gen_006_mem_009 tells us its approximation of the structure of it. In my case it gives the output Tol=0.1 International symmetry is P6_3/mmc Tol=0.00316 International symmetry is C2/m From this we can immediately tell that the result is imperfect: the actual structure should be diamond (Fd-3m). Do not worry, however, as looking at a 2x2 supercell in VESTA one can see the resemblance to what we'd expect: This is promising - though it started off by generating random structures, it has already arrived at one resembling diamond. Let's see if more generations will improve the results. Change the initial param file to have ga_max_gens = 18 and add the line continuation = Si.xyz This tells it to continue to run, up to 18 generations, using the previous results as its history. Running castep GA on Si again will make it run as before. After it's done running, if you wish to save the previous graph, simply rename it. Then run the bash, and then python, script again to get a new all_gens.png for the continued, longer run. The new image will have more points on the graph, as more members have been examined, and (hopefully) a new minimum enthalpy member. Running the same grep command will give this in the top 4 GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom This is rather interesting: even after 6 * 12 = 72 new members have been generated, the original minimum is still the 2 nd lowest enthalpy: it certainly is a good structure. However, 16,7 is now considered the best: let's look at how it improved. Running c2x on it tells me this Tol=0.1 International symmetry is Fd-3m Tol=0.0001 International symmetry is P-1 According to c2x it is now more similar to diamond (though if you're being very strict with it it, is not - it is still imperfect, though closer). Looking at it on VESTA (again a 2x2 supercell) tells us a similar story As expected of GA, it has managed to improve the structure through multiple generations. If you wish, you could continue to run it for more generations by keeping the continuation line and increasing ga_max_gens more - in fact, if using a different seed or if your environment processed said seed differently, you may have to - 6 more generations aren't guranteed to find a new lowest enthalpy structure!","title":"Silicon"},{"location":"tutorials/GA/Silicon/#castep-ga-for-silicon","text":"Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA!","title":"Castep GA for silicon"},{"location":"tutorials/GA/Silicon/#input-files","text":"We will use the cell file Si.cell %block LATTICE_ABC ang 3.8 3.8 3.8 90 90 90 %endblock LATTICE_ABC %block POSITIONS_FRAC Si 0.203 0.617 0.209 Si 0.844 0.442 0.350 Si 0.964 0.379 0.096 Si 0.762 0.524 0.941 Si 0.544 0.605 0.781 Si 0.238 0.597 0.531 Si 0.728 0.914 0.742 Si 0.209 0.929 0.435 %endblock POSITIONS_FRAC %BLOCK SPECIES_POT QC5 %ENDBLOCK SPECIES_POT symmetry_generate symmetry_tol : 0.05 ang The definition of the lattice and positions of the atoms is fairly inconsequential to the result you will get: in the 0 th generation it gets effectively randomised. The only thing that matters is the amount of Si atoms defined in the POSITIONS_FRAC block - here it is 8 so future structures will also have 8 atoms. Another thing worth noting is the QC5 potential being used - it is used due to its speed, which is essential considering how many calculations will be done. For the param file we will use Si.param task = genetic algor # Run the GA ga_pop_size = 12 # Parent population size ga_max_gens = 12 # Max number of generations to run for ga_mutate_amp = 1.00 # Mutation amplitude (in Angstrom) ga_mutate_rate = 0.15 # Probability of mutation to occur ga_fixed_N = true # Fix number of ions in each member based on input cell rand_seed = 101213 # Random seed for replicability opt_strategy = SPEED # Run quick geom_max_iter = 211 # Can have a large max iter as using pair potentials # Don't write most output files for each population member write_checkpoint = NONE write_bib = FALSE write_cst_esp = FALSE write_bands = FALSE write_cell_structure = TRUE ###################################### # Any extra devel code options # # & required GA specific devel flags # ###################################### %block devel_code # Command used to call castep for each population member # If not given this defaults to castep.serial CMD: castep.serial :ENDCMD GA: PP=T # Using a pair potential IPM=M # Randomly mutated initial population CW=24 # Num gens for convergence NI=F # No niching FW=0.5 # Fitness weighting # Asynchronous running options # Required for asynchronous running, without this all geom opts will be run # one after another AS=T # Run geometry optimisations asynchronously MS=3 # Run 3 geometry optimisations at once # Random symmetry children NUM_CHILDREN=12 RSC=F CORE_RADII_LAMBDA=0.8 # Core radii 0.8 pseudopotenital radii SCALE_IGNORE_CONV=T # Ignore convergence in fitness calcualtion :ENDGA # Use pair potentials in geometry optimisations and perform a final snap to symmetry GEOM: PP=T SNAP=T :ENDGEOM # Use the Stillinger-Weber pair potential PP=T PP: SW=T :ENDPP %endblock devel_code It is important to understand what is going on in this file. The line task = genetic algor is what tells is to actually run GA. The GA parameters tell the GA how to run- unlike in the previous tutorial (ADD LINK), all of these values are reasonable (the mutation amplitude and rate shouldn't be far off those values in most cases). As you can see, we will have 12 parents in each generation (meaning 12 cells will be chosen to breed), and it will run for 12 generations. ga_fixed_N is what ensures that there are fixed 8 ions in the cell (the more information is fixed, the faster it'll get a decent result as it'll have fewer things to try). There are numerous lines that speed up the GA - with how many calculations are being performed, this is essential to be feasible. op_strategy = SPEED and geom_max_iter = 211 help ensure that the geometry optimisations (of which there are 12 per generation - so 144 in total for this first run!) are fast but reasonably accurate. AS=T and MS=3 allow asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. The devel_code block is a bit more complex. The fact that pair potentials are used are defined in both the GA sub-block and GEOM sub-block, again necessary for speed. The CMD sub-block is there so that geometry optimisations are performed on all members: what happens is cell files are generated (initially randomly and in the 1 st generation onwards by breeding + mutation), as well as respective param files that tell them to geometry optimise, for each member, and then they are run. A very important thing to note are the lines NUM_CHILDREN = 12 RSC = F This is highly atypical and would not be used in most actual calculations: instead, it would look like this NUM_CHILDREN=11 RSC=T RSN=1 With the general rule that NUM_CHILREN + RSN = ga_pop_size (defined earlier). What that does is, in every generation, it creates 1 child as a random high-symmetry structure (with the other 11, NUM_CHILDREN , being bred). The reason this is not used here is because Silicon is a very simple example: it is likely to simply randomly guess that it's diamond, meaning the actual GA was inconsequential and the result is uninteresting. Note Though not a gurantee, using an identical RAND_SEED makes it likely that you'll get identical results to this tutorial, so you can follow along more easily","title":"Input Files"},{"location":"tutorials/GA/Silicon/#running-and-output","text":"Now we can run castep GA on Si. You may use tail -f Si.castep If you wish to see what's going on in the castep file as it runs (it's explained in more detail in the previous tutorial ADD LINK). Once it is done running, we will use the scripts get_data.sh and plot_results.py - first run ./get_data.sh to get the output file out.put . Run the python script to see that data visually in all_gens.png . The graph should look like this Each dot in this graph is a member, showing the spread of enthalpy against their volume per ion. The lowest enthalpy member (in this generation generation 6, member 9) is highlighted - this is is currently considered the most stable structure found. You can also find the lowest enthalpy structure by running grep 'child' Si.castep | sort -k10,10n | head -20 This gives the 10 lowest enthalpy members (each one repeats twice - don't worry about that). The output looks a bit like GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom un-scaled fitness = 0.880788 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 12 child # 8 enthalpy = -4.336381E+000 eV/atom updated fitness = 0.452993 conv = T member error = F seed = Si.gen_012_mem_008 vol/ion = 20.0241 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 5 child # 9 enthalpy = -4.336369E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_005_mem_009 vol/ion = 20.0230 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom un-scaled fitness = 0.828518 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 11 child # 6 enthalpy = -4.258665E+000 eV/atom updated fitness = 0.456619 conv = T member error = F seed = Si.gen_011_mem_006 vol/ion = 19.7822 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 4 child # 10 enthalpy = -4.241488E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_004_mem_010 vol/ion = 18.2369 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 1 child # 8 enthalpy = -4.240423E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_001_mem_008 vol/ion = 18.2175 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom un-scaled fitness = 0.835359 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 3 enthalpy = -4.240415E+000 eV/atom updated fitness = 0.432991 conv = T member error = F seed = Si.gen_009_mem_003 vol/ion = 18.2164 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom un-scaled fitness = 0.835345 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 9 child # 5 enthalpy = -4.240388E+000 eV/atom updated fitness = 0.432963 conv = T member error = F seed = Si.gen_009_mem_005 vol/ion = 18.2140 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom un-scaled fitness = 0.801207 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 11 child # 10 enthalpy = -4.225493E+000 eV/atom updated fitness = 0.420408 conv = T member error = F seed = Si.gen_011_mem_010 vol/ion = 19.0956 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom un-scaled fitness = 0.865596 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom GA: gen # 1 child # 9 enthalpy = -4.225480E+000 eV/atom updated fitness = 0.444351 conv = T member error = F seed = Si.gen_001_mem_009 vol/ion = 19.0992 A**3/atom This further confirms that 6,9 is the most stable member. Now we will examine the structure of it. Running c2x on it via c2x --int -e=0.1-0.0001 Si.gen_006_mem_009 tells us its approximation of the structure of it. In my case it gives the output Tol=0.1 International symmetry is P6_3/mmc Tol=0.00316 International symmetry is C2/m From this we can immediately tell that the result is imperfect: the actual structure should be diamond (Fd-3m). Do not worry, however, as looking at a 2x2 supercell in VESTA one can see the resemblance to what we'd expect: This is promising - though it started off by generating random structures, it has already arrived at one resembling diamond. Let's see if more generations will improve the results. Change the initial param file to have ga_max_gens = 18 and add the line continuation = Si.xyz This tells it to continue to run, up to 18 generations, using the previous results as its history. Running castep GA on Si again will make it run as before. After it's done running, if you wish to save the previous graph, simply rename it. Then run the bash, and then python, script again to get a new all_gens.png for the continued, longer run. The new image will have more points on the graph, as more members have been examined, and (hopefully) a new minimum enthalpy member. Running the same grep command will give this in the top 4 GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 16 child # 7 enthalpy = -4.336404E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_016_mem_007 vol/ion = 20.0237 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom un-scaled fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom GA: gen # 6 child # 9 enthalpy = -4.336393E+000 eV/atom updated fitness = 0.880797 conv = T member error = F seed = Si.gen_006_mem_009 vol/ion = 20.0224 A**3/atom This is rather interesting: even after 6 * 12 = 72 new members have been generated, the original minimum is still the 2 nd lowest enthalpy: it certainly is a good structure. However, 16,7 is now considered the best: let's look at how it improved. Running c2x on it tells me this Tol=0.1 International symmetry is Fd-3m Tol=0.0001 International symmetry is P-1 According to c2x it is now more similar to diamond (though if you're being very strict with it it, is not - it is still imperfect, though closer). Looking at it on VESTA (again a 2x2 supercell) tells us a similar story As expected of GA, it has managed to improve the structure through multiple generations. If you wish, you could continue to run it for more generations by keeping the continuation line and increasing ga_max_gens more - in fact, if using a different seed or if your environment processed said seed differently, you may have to - 6 more generations aren't guranteed to find a new lowest enthalpy structure!","title":"Running and Output"},{"location":"tutorials/NEB/neb_tutorial/","text":"Nudged elastic band tutorial Overview and background The nudged elastic band (NEB) approach is a widely-used method for finding a minimum energy pathway between two configurations of atoms. You can use the method to estimate the barrier for the system to transition between the two structures. The technique starts with two fixed end points which are fully relaxed (local) minima: the initial and final configurations. It then connects these end points with a series of \"images\" via fictitious springs that \"pull\" the structures taut over one or more intermediate transition states. In this tutorial, we will use the well-known example of an ammonia molecule's pyramidal inversion We will cover: How to set up the initial, final (and intermediate) structures How to actually run the NEB calculation efficiently How to analyse the results Other tips and tricks Files You can find all the files needed for this tutorial here: neb_tutorial.tar.gz Setting up the structures Setting up the initial and final states These are the local minima structures you want to find the barrier between. They can be equivalent structures, e.g. differing by a symmetry operation, such reflection through a mirror plane, or they can be configurations with different energies (in which case your forward and reverse barriers will not be the same!). Two crucial conditions must be met before running the NEB calculation : The end point structures must be fully relaxed (geometry optimised) before you start the NEB. Note that both the initial relaxations and the actual NEB calculation must use consistent parameters (e.g. basis set, pseudopotentials, k-points, XC functional etc.). The atoms must be in the correct order. A common mistake is to use a software tool to generate the final state from the initial state and end up with atoms that don't match the initial atom order. Atoms then \"pass through each other\" when CASTEP interpolates between the two structures, causing the calculation to blow up. Always check that the atoms connect up in the way you expect. Note that, for CASTEP, only the atom order within a given species matters, not the order of the species themselves. In this example, we make sure that the H atoms are in the same order in the initial, final and intermediate structures and we can have the N coordinate either before or after the H atom coordinates. The initial state is specified in the same way as a normal .cell file, e.g.: %BLOCK positions_frac H 0.500011764912384 0.634846485697942 0.443086003907125 H 0.616593728396204 0.432553816946042 0.442828605918639 H 0.383248448613152 0.432623959245757 0.443068863520867 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac The final state is specified using a similar block in the same .cell file but with _product appended to the name of the block, e.g.: %BLOCK positions_frac_product H 0.500154169007758 0.634858887961251 0.556834437330747 H 0.616661280589956 0.432482046338754 0.556941161085851 H 0.383366127862304 0.432719065607707 0.557277918851780 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac_product Setting up the transition state guess CASTEP requires you to provide one intermediate structure between the initial and final configurations in order to get the NEB on the right track. The intermediate configuration is added using, e.g.: %BLOCK POSITIONS_ABS_INTERMEDIATE ang N 3.500000 3.500000 3.500000 H 3.500000 4.443968 3.500000 H 4.316393 3.027626 3.500000 H 2.683149 3.028701 3.501215 %ENDBLOCK POSITIONS_ABS_INTERMEDIATE CASTEP will linearly interpolate from the initial to intermediate and the intermediate to final structures provided to generate the rest of the path, depending on the number of images you have chosen. In many cases, a suitable transition state guess structure is simply the halfway point between the initial and final structures (a linear interpolation between the coordinates). However, if your minimum energy pathway contains e.g. a rotation of a (group of) atom(s) around a bond or something similar, then the linear path between initial and final configurations may be a bad starting guess/non-physical structure. For example, if your end points correspond to a C2 rotation, then a linearly interpolated intermediate structure would not be a physical one. It's important to visualise or otherwise check all of your structures before running a calculation. Intermediate structures can also be chosen in such a way as to bias your results to one pathway over another. How many images do I need? It depends... It's usually preferable to start with a small number of images and increase the number if you need to. Starting small can quickly give you a rough sense of the energy landscape and that will determine the actual number of images needed. In addition, if you start with too many images then you might never get close to the converged TS because the optimisation takes too long. If you instead start with a small number and get a reasonable TS structure, you can then use that as your initial intermediate structure in a restarted calculation with more images. Using many (i.e. > 15) will result in slow convergence, but may lead to a more accurate minimum energy pathway for complex barriers. If you do find a particularly complex pathway, however, you might be better off splitting the work up into more than one NEB calculation, each with fewer images. Just remember to always fully relax the end points (even if the end point is a meta-stable local minimum)! Using too few (i.e. < 5) might fail to find the minimum energy pathway if the energy landscape is complex. The TS guess structure that you specify in the .cell file will be assigned to the middle image, with the other images being initially linearly interpolated between the initial, TS guess and final structures. If you choose an even number of images, the 'middle' one is taken to be the one to the right of the centre. e.g. for 6 images, the TS guess will be assigned to image 4. This will make your initial NEB asymmetric in the sense that there will be more images to the left of the TS guess than to the right. If the TS guess is estimated to be in the geometric centre of the minimum energy pathway, then it's probably best to use an odd number of images. As the minimum energy pathway is very simple in this example, we can actually get away with just one image. However, we'll use 7 images here to illustrate the process. As an exercise, you can try running the same calculation with tssearch_max_path_points: 1, 2, 3, 4, 5 images and note how the results change. Some questions to help answer how many images you need: How complex is the landscape between the initial and final state? For example, if you expect more than one maximum between the end points, you probably need more images than for the single peak example we look at here. Note The number of images is the number of structures between the end points. The total number of structures in the path (i.e. including the end points) is therefore the number of images + 2. Constraints We can often dramatically improve the efficiency of the transition state search by imposing constraints on the atomic positions, although this must be done with care so as not to introduce artifacts. For example, when looking at NEB barriers for adsorbates on a surface slab, we can usefully constrain the bottom slab layers, but probably want the top layer(s) unconstrained. In the ammonia case, we can constrain the N atom position without affecting the physical set up by adding the block: %BLOCK IONIC_CONSTRAINTS fix: N %ENDBLOCK IONIC_CONSTRAINTS to the nh3.cell file. You should then see something like: --- Initialising NEB constraints --- Fixed 3 degrees of freedom in the .castep output file. Do I need climbing NEB? The climbing NEB method modifies the force on the highest-energy image such that it tries to climb up the barrier. This is very useful to get an accurate estimate of the transition state configuration and barrier since you ensure that one image sits exactly at the saddle point of the minimum energy pathway. However, care must be taken when exploring more complex pathways (i.e. with multiple maxima) since it might become ambiguous as to which image should be the one to \"climb\". In our example the path is quite straightforward and will not make a large difference whether we use the climbing or regular NEB method. We can set: TSSEARCH_NEB_CLIMBING: TRUE in the .param file. Though it's not necessary in this case, we will use it here to illustrate the process. To illustrate a case in which climbing NEB is more important, consider briefly another example: that of the HCN - HNC isomerisation. In this case, the minimum energy pathway is not a simple linear interpolation between the initial and final states and the minimum energy pathway is not symmetric. The climbing NEB method is very important to get an accurate estimate of the barrier and transition state structure. In Fig 1., we compare the regular and climbing NEB methods using 7 images. While we can find similar barrier heights using both methods if we use a suitable interpolation scheme for the regular NEB, the regular NEB does not find the correct transition state structure. The climbing NEB, on the other hand, finds the correct transition state structure and barrier height. Fig1. Comparison of the regular NEB (left) and the climbing NEB (right) methods for the case of an HCN - HNC isomerisation. The red circle markers indicate the highest-energy structure in each case. The initial, transition state and final configurations are shown for the climbing NEB, with white, blue and brown spheres representing H, N and C respectively. Note that these are not converged calculations, but are simply provided as a simple comparison of the NEB methods. Note The climbing image method in CASTEP requires an odd number total number of images. Therefore, if you choose an even number of images in your .param file, CASTEP will automatically add one more image. Running the NEB Parallelisation Because the NEB calculation essentially involves N independent CASTEP calculations (where N is the number of images), we can make very efficient use of high-performance computers. This is done via \"task farming\", running the calculations for the N images independently. For example, if one CASTEP calculation fits on one node, and you have 7 images, then you could run on a total of 7 nodes by setting the keyword: NUM_FARMS: 7 in the .param file. A good rule of thumb is to aim for NUM_FARMS = number of NEB images. That way each 'farm' is responsible for one NEB image. Since each farm will effectively run a series of single-point calculations on each NEB image they are responsible for, the compute resources of that farm should be appropriately sized for such calculations. Too small and you could get an out-of-memory error, too large and you might end up over-parallelising, leading to reduced overall performance. i.e. you should aim to run on a total of NUM_FARMS times as many cores as you would use for a single-point calculation on one of the structures. This also assumes that your available compute resources can be neatly split into NUM_FARMS . The easy case is when each farm can run on a single node; i.e. NUM_FARMS = number of NEB images = number of nodes. Note that the total number of cores available must be divisible by NUM_FARMS . If you choose NUM_FARMS < number of images, each of the images will run sequentially on one farm as soon as that farm becomes available. If the number of images is not a multiple of NUM_FARMS , some farms will end up being responsible for more images than others, leading poor overall efficiency. If you choose NUM_FARMS > number of images, then some farms will be left with nothing to do, resulting in poor overall efficiency. Setting NUM_FARMS = 1 is equivalent to not setting NUM_FARMS . You will notice that if you enable task farming, the seedname.castep output file will look relatively empty, as most output is split into the different task farm .castep files. The first indexed one contains the most important information (for example, the \"Max NEB force\") and will be called e.g. seedname_farm001.castep . Is the calculation converging? You can monitor the convergence by searching for \"Max NEB force\" within the .castep output file. Common convergence issues include: Not having consistent atom order in the initial and final structures, i.e. non-physical initial path. This is one of the more common reasons for failed calculation. It's always important to visualise the initial and final structures and check that the atoms connect up in the way you expect. Too many (or too few) images. Too many images can lead to slow convergence, too few can lead to the calculation failing to find the minimum energy pathway. Initial or final state (endpoints) not being fully relaxed structures Restarting / Continuing Sometimes the calculation will run out of time/number of iterations before the NEB calculation is finished. You will probably see a \"Failed to converge\" message in the .castep output in that case; always read through your output files! If you re-run the calculation without changing anything, it will simply start from the beginning again -- probably not what you want! In order restart the NEB from the last checkpointed state, you need to explicitly set the name of the .check file you want to continue from in your .param file. In our example that would be: continuation: nh3.check In the .castep output you would then see: Coordinates of NEB images loaded from checkpoint file . Warning Unlike other CASTEP tasks, setting continuation: default does not seem to work for continuing/restarting NEB calculations! You must explicitly set the name of checkpoint file. Analysis Once you have a converged NEB, the provided Python utility readTS can be used to parse and analyse the NEB. To add the readTS module to your PYTHONPATH, you can find a setup.py script in the castep/Utilities/readts directory of your CASTEP source directory. Running python setup.py should install the module to your path. You can also manually add it by inserting the following line into your ~/.bashrc or equivalent and restarting the terminal: export PYTHONPATH = \"/path/to/castep/Utilities/readts: $PYTHONPATH \" (changing the /path/to/castep/ bit to wherever CASTEP is on your machine). You can then extract the NEB path using something like this python code: ## get this by adding castep/Utilities/readts to your PYTHONPATH from readts import TSFile from ase.neb import NEBTools def get_images ( tsfile ): ''' Function to extract the final NEB images from a tsfile object Args: tsfile (TSFile): tsfile object Returns: images (list): list of ASE atoms objects ''' diam_tst = tsfile . blocks [ 'TST' ] diam_i = tsfile . blocks [ 'REA' ][ 1 ][ 0 ] diam_f = tsfile . blocks [ 'PRO' ][ 1 ][ 0 ] nbeads = len ( diam_tst [ 1 ]) max_idx = diam_tst . last_index images = [ diam_i . atoms ] images += [ diam_tst [ max_idx ][ i ] . atoms for i in range ( 0 , nbeads , 1 )] images . append ( diam_f . atoms ) return images def plot_band ( images , filename = 'neb.png' ): nt = NEBTools ( images ) energies = nt . get_barrier () print ( f 'Barrier height: { energies [ 0 ] : 16.5f } eV' ) print ( f 'E_final - E_initial: { energies [ 1 ] : 16.5f } eV' ) nebplot = nt . plot_band () nebplot . savefig ( filename ) if __name__ == '__main__' : import sys seedname = sys . argv [ 1 ] path = './' tolerant = False if len ( sys . argv ) > 2 : tolerant = bool ( sys . argv [ 2 ]) tsfile = TSFile ( seedname , path = path , tolerant = tolerant ) images = get_images ( tsfile ) plot_band ( images ) # we can use ASE to write out the structure # in whatever format we want print ( 'Image \\t\\t Energy (eV)' ) for i , atoms in enumerate ( images ): print ( f ' { i : 03d } \\t { atoms . get_potential_energy () : 16.5f } eV' ) ## this format includes the energy of the image atoms . write ( f 'image- { i : 03d } .xyz' ) ## We can also use the ASE GUI to ## view the images and analyse the NEB path. ## Select Tools -> NEB Plot # from ase.visualize import view # view(images) If we save this script as analysis.py and run it in the directory containing both the nh3.cell and nh3.ts files like this: python analysis.py nh3 we will get an .xyz file for each structure in the optimised NEB path and the energy of each image. We will also get the barrier estimate and a NEB plot showing the barrier. The ASE GUI can also be used to plot the NEB band (uncomment the last two lines in the above script and Select Tools \u2192 NEB Plot from the GUI). The ASE-generated plot looks like this: The green lines show the tangents at those points; these can be useful indicators of convergence. The barrier we obtained is about 0.23 eV, which compares well with the value of 0.25 eV (24.2 kJ/mol) from Wikipedia . We might also notice the slight difference in energy between the two end-points of the path (about 1 meV). These should be identical, so any difference can be used as a very rough guide for the amount of numerical noise in the geometry optimisations. If equivalent structures (the end-points in this example) were found to have very different energies, you would need to go back and tighten up your convergence criteria or force/energy tolerances in the initial geometry optimisations and re-run the NEB calculation with these tightened parameters. Using our favourite visualisation software (here we used the ASE POV-Ray interface ), we can then look at how the structure evolves along the minimum energy pathway found via the NEB. Zero point energy corrections All of the above calculations were done while treating the nuclei as classical particles. In many cases, particularly when lighter atoms are involved, the energy barrier estimates would need to be corrected for quantum-nuclear effects. The simplest approach to accounting for the true quantum nature of nuclei is to compute the vibrational frequencies of the nuclei within the harmonic approximation. You need would need to do this for the reactant and transition state configurations and use, for example, equation 2 from [J. Chem. Phys. 124, 044706 (2006)](http://theory.cm.utexas.edu/henkelman/pubs/henkelman06_044706.pdf) to obtain the Harmonic quantum correction to the barrier.","title":"Nudged elastic band"},{"location":"tutorials/NEB/neb_tutorial/#nudged-elastic-band-tutorial","text":"","title":"Nudged elastic band tutorial"},{"location":"tutorials/NEB/neb_tutorial/#overview-and-background","text":"The nudged elastic band (NEB) approach is a widely-used method for finding a minimum energy pathway between two configurations of atoms. You can use the method to estimate the barrier for the system to transition between the two structures. The technique starts with two fixed end points which are fully relaxed (local) minima: the initial and final configurations. It then connects these end points with a series of \"images\" via fictitious springs that \"pull\" the structures taut over one or more intermediate transition states. In this tutorial, we will use the well-known example of an ammonia molecule's pyramidal inversion We will cover: How to set up the initial, final (and intermediate) structures How to actually run the NEB calculation efficiently How to analyse the results Other tips and tricks","title":"Overview and background"},{"location":"tutorials/NEB/neb_tutorial/#files","text":"You can find all the files needed for this tutorial here: neb_tutorial.tar.gz","title":"Files"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-structures","text":"","title":"Setting up the structures"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-initial-and-final-states","text":"These are the local minima structures you want to find the barrier between. They can be equivalent structures, e.g. differing by a symmetry operation, such reflection through a mirror plane, or they can be configurations with different energies (in which case your forward and reverse barriers will not be the same!). Two crucial conditions must be met before running the NEB calculation : The end point structures must be fully relaxed (geometry optimised) before you start the NEB. Note that both the initial relaxations and the actual NEB calculation must use consistent parameters (e.g. basis set, pseudopotentials, k-points, XC functional etc.). The atoms must be in the correct order. A common mistake is to use a software tool to generate the final state from the initial state and end up with atoms that don't match the initial atom order. Atoms then \"pass through each other\" when CASTEP interpolates between the two structures, causing the calculation to blow up. Always check that the atoms connect up in the way you expect. Note that, for CASTEP, only the atom order within a given species matters, not the order of the species themselves. In this example, we make sure that the H atoms are in the same order in the initial, final and intermediate structures and we can have the N coordinate either before or after the H atom coordinates. The initial state is specified in the same way as a normal .cell file, e.g.: %BLOCK positions_frac H 0.500011764912384 0.634846485697942 0.443086003907125 H 0.616593728396204 0.432553816946042 0.442828605918639 H 0.383248448613152 0.432623959245757 0.443068863520867 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac The final state is specified using a similar block in the same .cell file but with _product appended to the name of the block, e.g.: %BLOCK positions_frac_product H 0.500154169007758 0.634858887961251 0.556834437330747 H 0.616661280589956 0.432482046338754 0.556941161085851 H 0.383366127862304 0.432719065607707 0.557277918851780 N 0.500000000000000 0.500000000000000 0.500000000000000 %ENDBLOCK positions_frac_product","title":"Setting up the initial and final states"},{"location":"tutorials/NEB/neb_tutorial/#setting-up-the-transition-state-guess","text":"CASTEP requires you to provide one intermediate structure between the initial and final configurations in order to get the NEB on the right track. The intermediate configuration is added using, e.g.: %BLOCK POSITIONS_ABS_INTERMEDIATE ang N 3.500000 3.500000 3.500000 H 3.500000 4.443968 3.500000 H 4.316393 3.027626 3.500000 H 2.683149 3.028701 3.501215 %ENDBLOCK POSITIONS_ABS_INTERMEDIATE CASTEP will linearly interpolate from the initial to intermediate and the intermediate to final structures provided to generate the rest of the path, depending on the number of images you have chosen. In many cases, a suitable transition state guess structure is simply the halfway point between the initial and final structures (a linear interpolation between the coordinates). However, if your minimum energy pathway contains e.g. a rotation of a (group of) atom(s) around a bond or something similar, then the linear path between initial and final configurations may be a bad starting guess/non-physical structure. For example, if your end points correspond to a C2 rotation, then a linearly interpolated intermediate structure would not be a physical one. It's important to visualise or otherwise check all of your structures before running a calculation. Intermediate structures can also be chosen in such a way as to bias your results to one pathway over another.","title":"Setting up the transition state guess"},{"location":"tutorials/NEB/neb_tutorial/#how-many-images-do-i-need","text":"It depends... It's usually preferable to start with a small number of images and increase the number if you need to. Starting small can quickly give you a rough sense of the energy landscape and that will determine the actual number of images needed. In addition, if you start with too many images then you might never get close to the converged TS because the optimisation takes too long. If you instead start with a small number and get a reasonable TS structure, you can then use that as your initial intermediate structure in a restarted calculation with more images. Using many (i.e. > 15) will result in slow convergence, but may lead to a more accurate minimum energy pathway for complex barriers. If you do find a particularly complex pathway, however, you might be better off splitting the work up into more than one NEB calculation, each with fewer images. Just remember to always fully relax the end points (even if the end point is a meta-stable local minimum)! Using too few (i.e. < 5) might fail to find the minimum energy pathway if the energy landscape is complex. The TS guess structure that you specify in the .cell file will be assigned to the middle image, with the other images being initially linearly interpolated between the initial, TS guess and final structures. If you choose an even number of images, the 'middle' one is taken to be the one to the right of the centre. e.g. for 6 images, the TS guess will be assigned to image 4. This will make your initial NEB asymmetric in the sense that there will be more images to the left of the TS guess than to the right. If the TS guess is estimated to be in the geometric centre of the minimum energy pathway, then it's probably best to use an odd number of images. As the minimum energy pathway is very simple in this example, we can actually get away with just one image. However, we'll use 7 images here to illustrate the process. As an exercise, you can try running the same calculation with tssearch_max_path_points: 1, 2, 3, 4, 5 images and note how the results change. Some questions to help answer how many images you need: How complex is the landscape between the initial and final state? For example, if you expect more than one maximum between the end points, you probably need more images than for the single peak example we look at here. Note The number of images is the number of structures between the end points. The total number of structures in the path (i.e. including the end points) is therefore the number of images + 2.","title":"How many images do I need?"},{"location":"tutorials/NEB/neb_tutorial/#constraints","text":"We can often dramatically improve the efficiency of the transition state search by imposing constraints on the atomic positions, although this must be done with care so as not to introduce artifacts. For example, when looking at NEB barriers for adsorbates on a surface slab, we can usefully constrain the bottom slab layers, but probably want the top layer(s) unconstrained. In the ammonia case, we can constrain the N atom position without affecting the physical set up by adding the block: %BLOCK IONIC_CONSTRAINTS fix: N %ENDBLOCK IONIC_CONSTRAINTS to the nh3.cell file. You should then see something like: --- Initialising NEB constraints --- Fixed 3 degrees of freedom in the .castep output file.","title":"Constraints"},{"location":"tutorials/NEB/neb_tutorial/#do-i-need-climbing-neb","text":"The climbing NEB method modifies the force on the highest-energy image such that it tries to climb up the barrier. This is very useful to get an accurate estimate of the transition state configuration and barrier since you ensure that one image sits exactly at the saddle point of the minimum energy pathway. However, care must be taken when exploring more complex pathways (i.e. with multiple maxima) since it might become ambiguous as to which image should be the one to \"climb\". In our example the path is quite straightforward and will not make a large difference whether we use the climbing or regular NEB method. We can set: TSSEARCH_NEB_CLIMBING: TRUE in the .param file. Though it's not necessary in this case, we will use it here to illustrate the process. To illustrate a case in which climbing NEB is more important, consider briefly another example: that of the HCN - HNC isomerisation. In this case, the minimum energy pathway is not a simple linear interpolation between the initial and final states and the minimum energy pathway is not symmetric. The climbing NEB method is very important to get an accurate estimate of the barrier and transition state structure. In Fig 1., we compare the regular and climbing NEB methods using 7 images. While we can find similar barrier heights using both methods if we use a suitable interpolation scheme for the regular NEB, the regular NEB does not find the correct transition state structure. The climbing NEB, on the other hand, finds the correct transition state structure and barrier height. Fig1. Comparison of the regular NEB (left) and the climbing NEB (right) methods for the case of an HCN - HNC isomerisation. The red circle markers indicate the highest-energy structure in each case. The initial, transition state and final configurations are shown for the climbing NEB, with white, blue and brown spheres representing H, N and C respectively. Note that these are not converged calculations, but are simply provided as a simple comparison of the NEB methods. Note The climbing image method in CASTEP requires an odd number total number of images. Therefore, if you choose an even number of images in your .param file, CASTEP will automatically add one more image.","title":"Do I need climbing NEB?"},{"location":"tutorials/NEB/neb_tutorial/#running-the-neb","text":"","title":"Running the NEB"},{"location":"tutorials/NEB/neb_tutorial/#parallelisation","text":"Because the NEB calculation essentially involves N independent CASTEP calculations (where N is the number of images), we can make very efficient use of high-performance computers. This is done via \"task farming\", running the calculations for the N images independently. For example, if one CASTEP calculation fits on one node, and you have 7 images, then you could run on a total of 7 nodes by setting the keyword: NUM_FARMS: 7 in the .param file. A good rule of thumb is to aim for NUM_FARMS = number of NEB images. That way each 'farm' is responsible for one NEB image. Since each farm will effectively run a series of single-point calculations on each NEB image they are responsible for, the compute resources of that farm should be appropriately sized for such calculations. Too small and you could get an out-of-memory error, too large and you might end up over-parallelising, leading to reduced overall performance. i.e. you should aim to run on a total of NUM_FARMS times as many cores as you would use for a single-point calculation on one of the structures. This also assumes that your available compute resources can be neatly split into NUM_FARMS . The easy case is when each farm can run on a single node; i.e. NUM_FARMS = number of NEB images = number of nodes. Note that the total number of cores available must be divisible by NUM_FARMS . If you choose NUM_FARMS < number of images, each of the images will run sequentially on one farm as soon as that farm becomes available. If the number of images is not a multiple of NUM_FARMS , some farms will end up being responsible for more images than others, leading poor overall efficiency. If you choose NUM_FARMS > number of images, then some farms will be left with nothing to do, resulting in poor overall efficiency. Setting NUM_FARMS = 1 is equivalent to not setting NUM_FARMS . You will notice that if you enable task farming, the seedname.castep output file will look relatively empty, as most output is split into the different task farm .castep files. The first indexed one contains the most important information (for example, the \"Max NEB force\") and will be called e.g. seedname_farm001.castep .","title":"Parallelisation"},{"location":"tutorials/NEB/neb_tutorial/#is-the-calculation-converging","text":"You can monitor the convergence by searching for \"Max NEB force\" within the .castep output file. Common convergence issues include: Not having consistent atom order in the initial and final structures, i.e. non-physical initial path. This is one of the more common reasons for failed calculation. It's always important to visualise the initial and final structures and check that the atoms connect up in the way you expect. Too many (or too few) images. Too many images can lead to slow convergence, too few can lead to the calculation failing to find the minimum energy pathway. Initial or final state (endpoints) not being fully relaxed structures","title":"Is the calculation converging?"},{"location":"tutorials/NEB/neb_tutorial/#restarting-continuing","text":"Sometimes the calculation will run out of time/number of iterations before the NEB calculation is finished. You will probably see a \"Failed to converge\" message in the .castep output in that case; always read through your output files! If you re-run the calculation without changing anything, it will simply start from the beginning again -- probably not what you want! In order restart the NEB from the last checkpointed state, you need to explicitly set the name of the .check file you want to continue from in your .param file. In our example that would be: continuation: nh3.check In the .castep output you would then see: Coordinates of NEB images loaded from checkpoint file . Warning Unlike other CASTEP tasks, setting continuation: default does not seem to work for continuing/restarting NEB calculations! You must explicitly set the name of checkpoint file.","title":"Restarting / Continuing"},{"location":"tutorials/NEB/neb_tutorial/#analysis","text":"Once you have a converged NEB, the provided Python utility readTS can be used to parse and analyse the NEB. To add the readTS module to your PYTHONPATH, you can find a setup.py script in the castep/Utilities/readts directory of your CASTEP source directory. Running python setup.py should install the module to your path. You can also manually add it by inserting the following line into your ~/.bashrc or equivalent and restarting the terminal: export PYTHONPATH = \"/path/to/castep/Utilities/readts: $PYTHONPATH \" (changing the /path/to/castep/ bit to wherever CASTEP is on your machine). You can then extract the NEB path using something like this python code: ## get this by adding castep/Utilities/readts to your PYTHONPATH from readts import TSFile from ase.neb import NEBTools def get_images ( tsfile ): ''' Function to extract the final NEB images from a tsfile object Args: tsfile (TSFile): tsfile object Returns: images (list): list of ASE atoms objects ''' diam_tst = tsfile . blocks [ 'TST' ] diam_i = tsfile . blocks [ 'REA' ][ 1 ][ 0 ] diam_f = tsfile . blocks [ 'PRO' ][ 1 ][ 0 ] nbeads = len ( diam_tst [ 1 ]) max_idx = diam_tst . last_index images = [ diam_i . atoms ] images += [ diam_tst [ max_idx ][ i ] . atoms for i in range ( 0 , nbeads , 1 )] images . append ( diam_f . atoms ) return images def plot_band ( images , filename = 'neb.png' ): nt = NEBTools ( images ) energies = nt . get_barrier () print ( f 'Barrier height: { energies [ 0 ] : 16.5f } eV' ) print ( f 'E_final - E_initial: { energies [ 1 ] : 16.5f } eV' ) nebplot = nt . plot_band () nebplot . savefig ( filename ) if __name__ == '__main__' : import sys seedname = sys . argv [ 1 ] path = './' tolerant = False if len ( sys . argv ) > 2 : tolerant = bool ( sys . argv [ 2 ]) tsfile = TSFile ( seedname , path = path , tolerant = tolerant ) images = get_images ( tsfile ) plot_band ( images ) # we can use ASE to write out the structure # in whatever format we want print ( 'Image \\t\\t Energy (eV)' ) for i , atoms in enumerate ( images ): print ( f ' { i : 03d } \\t { atoms . get_potential_energy () : 16.5f } eV' ) ## this format includes the energy of the image atoms . write ( f 'image- { i : 03d } .xyz' ) ## We can also use the ASE GUI to ## view the images and analyse the NEB path. ## Select Tools -> NEB Plot # from ase.visualize import view # view(images) If we save this script as analysis.py and run it in the directory containing both the nh3.cell and nh3.ts files like this: python analysis.py nh3 we will get an .xyz file for each structure in the optimised NEB path and the energy of each image. We will also get the barrier estimate and a NEB plot showing the barrier. The ASE GUI can also be used to plot the NEB band (uncomment the last two lines in the above script and Select Tools \u2192 NEB Plot from the GUI). The ASE-generated plot looks like this: The green lines show the tangents at those points; these can be useful indicators of convergence. The barrier we obtained is about 0.23 eV, which compares well with the value of 0.25 eV (24.2 kJ/mol) from Wikipedia . We might also notice the slight difference in energy between the two end-points of the path (about 1 meV). These should be identical, so any difference can be used as a very rough guide for the amount of numerical noise in the geometry optimisations. If equivalent structures (the end-points in this example) were found to have very different energies, you would need to go back and tighten up your convergence criteria or force/energy tolerances in the initial geometry optimisations and re-run the NEB calculation with these tightened parameters. Using our favourite visualisation software (here we used the ASE POV-Ray interface ), we can then look at how the structure evolves along the minimum energy pathway found via the NEB. Zero point energy corrections All of the above calculations were done while treating the nuclei as classical particles. In many cases, particularly when lighter atoms are involved, the energy barrier estimates would need to be corrected for quantum-nuclear effects. The simplest approach to accounting for the true quantum nature of nuclei is to compute the vibrational frequencies of the nuclei within the harmonic approximation. You need would need to do this for the reactant and transition state configurations and use, for example, equation 2 from [J. Chem. Phys. 124, 044706 (2006)](http://theory.cm.utexas.edu/henkelman/pubs/henkelman06_044706.pdf) to obtain the Harmonic quantum correction to the barrier.","title":"Analysis"},{"location":"tutorials/NMR/Example_1_-Ethanol/","text":"Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig1.). In this tutorial, we will try to reproduce this result. Getting outputs This tutorial will go through the calculations for ethanol, using these 2 files: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strategy = speed task = magres cutoff_energy = 300 eV Look at the cell and param files. Note that the only special part of the ethanol.param file is task = magres Run a standard castep calculation for ethanol. Look at the ethanol.castep output file. Towards the end, you should be able to find the isotropic chemical shielding, anisotropy, and asymmetry in a table like this: ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | H 1 29.45 8.84 0.14 | | H 2 30.10 8.07 0.20 | | H 3 29.94 7.12 0.06 | | H 4 26.83 8.02 0.95 | | H 5 27.24 -7.07 0.90 | | H 6 31.93 13.99 0.46 | | C 1 157.27 33.77 0.70 | | C 2 110.73 69.91 0.42 | | O 1 268.63 -50.78 0.96 | ==================================================================== Here we are only interested in the isotropic values for the hydrogen atoms You may also find this information (as well as extra detail) in the file ethanol.magres , which contains tables such as ============ Atom: H 1 ============ H 1 Coordinates 3.981 4.178 3.295 A TOTAL Shielding Tensor 30.1276 1.2172 3.7366 1.9301 27.4802 2.4707 4.0710 2.2023 30.7511 H 1 Eigenvalue sigma_xx 26.1030 (ppm) H 1 Eigenvector sigma_xx 0.3550 0.6810 -0.6405 H 1 Eigenvalue sigma_yy 26.9119 (ppm) H 1 Eigenvector sigma_yy 0.6932 -0.6514 -0.3085 H 1 Eigenvalue sigma_zz 35.3439 (ppm) H 1 Eigenvector sigma_zz 0.6273 0.3345 0.7033 H 1 Isotropic: 29.4529 (ppm) H 1 Anisotropy: 8.8365 (ppm) H 1 Asymmetry: 0.1373 for each atom. You can see here that it also gives the same information - the isotropic value for atom 1 is the same. You may note that the isotropic value is the average of the diagonal values in the total shielding tensor. You might wish to open the ethanol.magres with MagresView . Analysis Next we identify which (hydrogen) ion corresponds to which part of the molecule - in the case of ethanol, we find out which ones correspond to CH 3 CH 2 and OH. This can be done by uploading the cell file to VESTA or MagresView and clicking each atom. Here you can see that one of the CH 3 hydrogens is atom 3. If you do the same for all of them, you should find that atoms 1, 2 and 3 are the CH 3 hydrogens, 4 and 5 are the CH 2 hydrogens and 6 is the OH hydrogen. It is important to check if the results are converged. Running a convergence test plot ranging the cut_off_energy = 200 eV from 200 to 1600eV gives the plot Here a cut off energy of 600 eV is reasonable - it's still relatively fast and should be fairly well-converged. 800eV is better converged. The cut off is quite high due to the presence of oxygen. Next we will look at the converged isotropic hydrogen shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Then we can average the CH 3 and CH 2 chemical shieldings. For example, the shieldings of the CH 2 hydrogens (atoms 4 and 5) are found in the ethanol.castep file (shown above) to be 26.83ppm and 27.24ppm: the average CH 2 shielding is 27.04ppm. CH 3 , meanwhile, has an average of 29.83ppm. Lastly, the single OH hydrogen has a value of 31.93ppm. We now have 3 unique chemical shieldings (though in your case the values will likely slightly differ) We now need to convert the chemical shieldings \\sigma_{iso} \\sigma_{iso} ; to chemical shifts \\delta_{iso} \\delta_{iso} on the experimental scale. We use the relation: \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma . A suitable \\sigma_{ref} \\sigma_{ref} for 1 H is 30.97ppm. Fig2. 1 H NMR spectrum of liquid ethanol Fig2. shows a modern high-resolution 1 H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1 H magnetic moments. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm - in this tutorial the shifts were found to be 1.14ppm (the CH 3 shielding), 3.94ppm (CH 2 ) and -0.96ppm (OH). The OH hydrogen clearly has a very different result while the other 2 roughly agree. The OH hydrogen shift is very sensitive to hydrogen bonding. It is has a very different value in as isolated molecule (as per our calculation) compared to liquid ethanol. The experimental value in a non-polar solvent should be closer to our isolated molecule - but note that the measurement is sensitive to even small traces of absorbed water, which will affect the OH shift.","title":"Example 1 - Ethanol"},{"location":"tutorials/NMR/Example_1_-Ethanol/#getting-outputs","text":"This tutorial will go through the calculations for ethanol, using these 2 files: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strategy = speed task = magres cutoff_energy = 300 eV Look at the cell and param files. Note that the only special part of the ethanol.param file is task = magres Run a standard castep calculation for ethanol. Look at the ethanol.castep output file. Towards the end, you should be able to find the isotropic chemical shielding, anisotropy, and asymmetry in a table like this: ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | H 1 29.45 8.84 0.14 | | H 2 30.10 8.07 0.20 | | H 3 29.94 7.12 0.06 | | H 4 26.83 8.02 0.95 | | H 5 27.24 -7.07 0.90 | | H 6 31.93 13.99 0.46 | | C 1 157.27 33.77 0.70 | | C 2 110.73 69.91 0.42 | | O 1 268.63 -50.78 0.96 | ==================================================================== Here we are only interested in the isotropic values for the hydrogen atoms You may also find this information (as well as extra detail) in the file ethanol.magres , which contains tables such as ============ Atom: H 1 ============ H 1 Coordinates 3.981 4.178 3.295 A TOTAL Shielding Tensor 30.1276 1.2172 3.7366 1.9301 27.4802 2.4707 4.0710 2.2023 30.7511 H 1 Eigenvalue sigma_xx 26.1030 (ppm) H 1 Eigenvector sigma_xx 0.3550 0.6810 -0.6405 H 1 Eigenvalue sigma_yy 26.9119 (ppm) H 1 Eigenvector sigma_yy 0.6932 -0.6514 -0.3085 H 1 Eigenvalue sigma_zz 35.3439 (ppm) H 1 Eigenvector sigma_zz 0.6273 0.3345 0.7033 H 1 Isotropic: 29.4529 (ppm) H 1 Anisotropy: 8.8365 (ppm) H 1 Asymmetry: 0.1373 for each atom. You can see here that it also gives the same information - the isotropic value for atom 1 is the same. You may note that the isotropic value is the average of the diagonal values in the total shielding tensor. You might wish to open the ethanol.magres with MagresView .","title":"Getting outputs"},{"location":"tutorials/NMR/Example_1_-Ethanol/#analysis","text":"Next we identify which (hydrogen) ion corresponds to which part of the molecule - in the case of ethanol, we find out which ones correspond to CH 3 CH 2 and OH. This can be done by uploading the cell file to VESTA or MagresView and clicking each atom. Here you can see that one of the CH 3 hydrogens is atom 3. If you do the same for all of them, you should find that atoms 1, 2 and 3 are the CH 3 hydrogens, 4 and 5 are the CH 2 hydrogens and 6 is the OH hydrogen. It is important to check if the results are converged. Running a convergence test plot ranging the cut_off_energy = 200 eV from 200 to 1600eV gives the plot Here a cut off energy of 600 eV is reasonable - it's still relatively fast and should be fairly well-converged. 800eV is better converged. The cut off is quite high due to the presence of oxygen. Next we will look at the converged isotropic hydrogen shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Then we can average the CH 3 and CH 2 chemical shieldings. For example, the shieldings of the CH 2 hydrogens (atoms 4 and 5) are found in the ethanol.castep file (shown above) to be 26.83ppm and 27.24ppm: the average CH 2 shielding is 27.04ppm. CH 3 , meanwhile, has an average of 29.83ppm. Lastly, the single OH hydrogen has a value of 31.93ppm. We now have 3 unique chemical shieldings (though in your case the values will likely slightly differ) We now need to convert the chemical shieldings \\sigma_{iso} \\sigma_{iso} ; to chemical shifts \\delta_{iso} \\delta_{iso} on the experimental scale. We use the relation: \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma . A suitable \\sigma_{ref} \\sigma_{ref} for 1 H is 30.97ppm. Fig2. 1 H NMR spectrum of liquid ethanol Fig2. shows a modern high-resolution 1 H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1 H magnetic moments. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm - in this tutorial the shifts were found to be 1.14ppm (the CH 3 shielding), 3.94ppm (CH 2 ) and -0.96ppm (OH). The OH hydrogen clearly has a very different result while the other 2 roughly agree. The OH hydrogen shift is very sensitive to hydrogen bonding. It is has a very different value in as isolated molecule (as per our calculation) compared to liquid ethanol. The experimental value in a non-polar solvent should be closer to our isolated molecule - but note that the measurement is sensitive to even small traces of absorbed water, which will affect the OH shift.","title":"Analysis"},{"location":"tutorials/NMR/Example_2_-Diamond/","text":"Here we will look more into convergence of chemical shielding calculations, examining what happens as we change the sampling of the Birllouin zone (BZ). We will examine diamond for this purpose. Varying k-point grid size We will use the cell and param files below for our calculations: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry Running castep on these files will lead to the diamond.castep output file which will contain the table ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | C 1 164.79 -0.00 N/A | | C 2 164.79 -0.00 N/A | ==================================================================== Note We have already done a convergence test of the cut-off energy, which is specified in that file, in example 1 What we are going to be looking at is isometric shielding tensor of carbon (with both atoms being identical). While there is nothing particularly special in diamond.param , we have specified the k-points in the diamond.cell file using the keyword kpoints_mp_grid 4 4 4 We will test the convergence of the chemical shielding with varying k-point mesh grid sizes. To do so, we will run castep for a range of k-point meshes (2, 4, 6, 8, 10), and then make a convergence plot of k-point mesh size against of the chemical shielding of carbon. The convergence plot should look like this: We can see from this that it converges at a k-point grid size of 4, and the converged value is around 160ppm. Single k-point test The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point, reducing computational cost and increasing speed considerably. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). First, we delete the line kpoints_mp_grid x x x Then we specify the kpoint we are examining in the diamond.cell file using %BLOCK KPOINTS_LIST 0 0 0 1.0 %ENDBLOCK KPOINTS_LIST to check (0,0,0) - in this case it resulted in an isometric chemical shielding of about 5798.71ppm (though, as in previous and future cases, the exact values you get may be slightly different) Similarly, we can change that block to %BLOCK KPOINTS_LIST 0.5 0.5 0.5 1.0 %ENDBLOCK KPOINTS_LIST to check (\u00bd,\u00bd,\u00bd), which led to 303.21ppm. Lastly,we replace that block with %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1 %ENDBLOCK KPOINTS_LIST to check (\u00bc,\u00bc,\u00bc) - this gave a value of 164.79ppm, which is by far the closest to the converged value (around 160ppm, as found by the convergence graph above). as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells","title":"Example 2 - Diamond"},{"location":"tutorials/NMR/Example_2_-Diamond/#varying-k-point-grid-size","text":"We will use the cell and param files below for our calculations: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry Running castep on these files will lead to the diamond.castep output file which will contain the table ==================================================================== | Chemical Shielding Tensor | |------------------------------------------------------------------| | Nucleus Shielding tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym | | C 1 164.79 -0.00 N/A | | C 2 164.79 -0.00 N/A | ==================================================================== Note We have already done a convergence test of the cut-off energy, which is specified in that file, in example 1 What we are going to be looking at is isometric shielding tensor of carbon (with both atoms being identical). While there is nothing particularly special in diamond.param , we have specified the k-points in the diamond.cell file using the keyword kpoints_mp_grid 4 4 4 We will test the convergence of the chemical shielding with varying k-point mesh grid sizes. To do so, we will run castep for a range of k-point meshes (2, 4, 6, 8, 10), and then make a convergence plot of k-point mesh size against of the chemical shielding of carbon. The convergence plot should look like this: We can see from this that it converges at a k-point grid size of 4, and the converged value is around 160ppm.","title":"Varying k-point grid size"},{"location":"tutorials/NMR/Example_2_-Diamond/#single-k-point-test","text":"The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point, reducing computational cost and increasing speed considerably. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). First, we delete the line kpoints_mp_grid x x x Then we specify the kpoint we are examining in the diamond.cell file using %BLOCK KPOINTS_LIST 0 0 0 1.0 %ENDBLOCK KPOINTS_LIST to check (0,0,0) - in this case it resulted in an isometric chemical shielding of about 5798.71ppm (though, as in previous and future cases, the exact values you get may be slightly different) Similarly, we can change that block to %BLOCK KPOINTS_LIST 0.5 0.5 0.5 1.0 %ENDBLOCK KPOINTS_LIST to check (\u00bd,\u00bd,\u00bd), which led to 303.21ppm. Lastly,we replace that block with %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1 %ENDBLOCK KPOINTS_LIST to check (\u00bc,\u00bc,\u00bc) - this gave a value of 164.79ppm, which is by far the closest to the converged value (around 160ppm, as found by the convergence graph above). as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells","title":"Single k-point test"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/","text":"Examples 3 - Alanine and Silicates We now look at some more realistic and complex structures - the amino acid alanine and 2 different silicates: cristoballite and qartz. These are fairly large crystals - to get them to complete in a short time we will run them on a cluster. Use the following number of CPUs: analine - 4 cristoballite - 6 quartz - 13 (these numbers are chosen to give efficient k-point scaling) We will also perform EFG calculations for the above structures and examine the respective data. Oxygen-17 NMR Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure. Alanine Examining input and output We will use the cell file alanine.cell Note Don't worry about how long/complex it is - it is no different from any other cell file - it just simply defines a large cell and param file alanine.param fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr cut_off_energy = 35 ry xc_functional : PBE Note that the only difference to the previous files is the line magres_task = nmr This leads to EFG calculations being performed. alanine.param](alanine/alanine.param) You may also want to view the file alanine.pdb in Materials Studio or another software - this allows better examination of features like hydrogen bonding. This is the original file downloaded from the Cambridge Crystallographic Database (and was used to obtain the alanine.cell file). The cell structure was obtained experimentally by neutron diffraction. We will now run castep. The alanine.castep output file should contain the table This is much like our previous results , except there are now 2 more columns - C_Q C_Q and Eta Eta - these are both there because an EFG calculation was now performed. This result is not fully converged (we will not be testing this in this tutorial, but feel free to check), but the relative shift between some of the sites is converged (again you may verify that if inclined). Analysing and comparing to experiment We will now compare these results with experiment. The figure below is an experimental 17 O NMR spectrum of L-alanine. It shows 2 peaks, which are very broad due to the quadripolar coupling, and overlap. Fig3. Solid-State 17 O NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) The experimental parameters are given in Table 1 below. \\delta \\delta (A)- \\delta \\delta (B) (ppm) 23.5 C_Q C_Q (A) (MHz) 7.86 \\eta_Q \\eta_Q (A) 0.28 C_Q C_Q (B) (MHz) 6.53 \\eta_Q \\eta_Q (B) 0.70 Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labelled A and B. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_{Q} C_{Q} , and EFG asymmetry \\eta_Q \\eta_Q . From this, we will try to find what A and B are. To do so, we will look at the alanine.castep tensor table . By a quick glance at the table, we see that the the chemical shift of hydrogen ranges from 20-30ppm, carbon around 0, 124 or 159ppm, nitrogen 194ppm and oxygen 48 or 63ppm. Because of this we can tell that the 2 resonances are going to belong to carbon and oxygen: to get a chemical shift difference of 23.5ppm, oxygen's 48ppm and a hydrogen (ideally of 24.5ppm) are the only option of coming close to that value. We see in the oxygen portion of the table =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 48.29 352.85 0.51 7.125E+00 0.25 | | O 2 62.86 255.66 0.71 5.794E+00 0.64 | | O 3 48.29 352.85 0.51 7.125E+00 0.25 | | O 4 62.86 255.66 0.71 5.794E+00 0.64 | | O 5 48.29 352.85 0.51 7.125E+00 0.25 | | O 6 62.86 255.66 0.71 5.794E+00 0.64 | | O 7 48.29 352.85 0.51 7.125E+00 0.25 | | O 8 62.86 255.66 0.71 5.794E+00 0.64 | =============================================================================== that the chemical shift alternates consistently between 48.29 and 62.86. To examine why this is the case we may look at the alanine.cell file in Vesta (or the alanine.pdb file in Materials Studio, or any other option of your choice that shows hydrogen bonding). Similarly to example 1 , we will examine which atoms correspond to which environment. The cell and a purposely highlighted atom are shown below. The oxygens are the red atoms. We see here that there are effectively 2 types of oxygen here - ones with hydrogen bonding (dashed lines joining to a hydrogen (grey atom)) and ones without. Here atom 52 (oxygen ion 8 in the table ; it starts at 44 as there are 44 atoms before it) is selected: this has a chemical shielding value of 62.86ppm, as seen above. When clicking any oxygen with 2 hydrogen bonds it corresponds to an atom number that has a shielding tensor of 62.86ppm, while all the ones with 1 hydrogen bond have a value of 48.29ppm. For this exercise, we have now identified that resonance A comes from a single-hydrogen-bonded oxygen. There are a lot more hydrogens and thus it is harder to find which specific one A is referring to. Because \\delta \\delta (A) - \\delta \\delta (B) = 23.5ppm, we know that the chemical shielding should have a value of around 48.29 - 23.5 = 24.79ppm 48.29 - 23.5 = 24.79ppm From the table, we see that the closest value is 24.01ppm, corresponding to atoms 1, 8, 15 and 22. By clicking on hydrogens until one of those is found, we find that all 3 of those hydrogens are bonded to a nitrogen that is also bonded to 2 other hydrogens and a carbon. It is different from the other 2 hydrogens because the oxygen it is hydrogen-bonded to has no other hydrogen bonds: A and B are hydrogen-bonded to each other. These results are confirmed by the other values provided in the table. To confirm A being oxygen 1 (or 3 or 5... - all the values are identical), C_Q C_Q in the table is 7.125MHz compared to the expected 7.86MHz, and \\eta_Q \\eta_Q is 0.25 compared to the expected 0.28 - the results are very similar. However, this is not the case for hydrogen - a C_Q C_Q of 6.53MHz and an \\eta_Q \\eta_Q of 0.7 are expected, but the castep results are 0.21MHz and 0.06 respectively. In fact, the only ion that comes close to matching the C_Q C_Q eta_Q eta_Q expectation is the other (even-numbered) oxygen type: the oxygen that the hydrogen of interest (1, 8 and 15) is hydrogen-bonded to. Silicates - Quartz and Cristoballite As an extra example, we will now perform similar calculations and corresponding analysis with 2 forms of silicate - cristoballite and quartz. Naturally, we wiil do the castep calculations separately Input and output files For quartz we will use the cell file quartz.cell And the param file quartz.param cut_off_energy = 40 ry xc_functional : PBE fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr elec_energy_tol = 1.0e-12 ry The param file is identical to the alanine one above. For cristoballite we will use the cell file crist.cell And exactly the same param file as above (just named crist.param instead) We then run castep on both crystal structures as usual, getting the output files quartz.castep and crist.castep . Within those files, we will have the same types of tables as above: For quartz: =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 234.54 68.31 0.12 -5.085E+00 0.20 | | O 2 234.54 68.30 0.12 -5.086E+00 0.20 | | O 3 234.54 68.30 0.12 -5.086E+00 0.20 | | O 4 234.54 68.30 0.12 -5.086E+00 0.20 | | O 5 234.54 68.30 0.12 -5.086E+00 0.20 | | O 6 234.54 68.31 0.12 -5.085E+00 0.20 | | Si 1 435.01 -5.44 0.82 2.067E+01 0.72 | | Si 2 435.01 -5.45 0.81 2.067E+01 0.72 | | Si 3 435.01 -5.44 0.82 2.067E+01 0.72 | =============================================================================== and for cristoballite =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 239.47 79.97 0.08 -5.055E+00 0.14 | | O 2 239.47 79.97 0.08 -5.055E+00 0.14 | | O 3 239.47 79.97 0.08 -5.055E+00 0.14 | | O 4 239.47 79.97 0.08 -5.055E+00 0.14 | | O 5 239.47 79.97 0.08 -5.055E+00 0.14 | | O 6 239.47 79.97 0.08 -5.055E+00 0.14 | | O 7 239.47 79.97 0.08 -5.055E+00 0.14 | | O 8 239.47 79.97 0.08 -5.055E+00 0.14 | | Si 1 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 2 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 3 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 4 437.12 -9.36 0.61 -1.077E+01 0.88 | =============================================================================== Analysing and comparing to experiment Like with alanine, we will compare it to an experimental 17 O NMR parameter table - this is shown below as Table 2 \\delta \\delta (ppm) C_Q C_Q (MHz) \\eta_Q \\eta_Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19 Table 2: Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_Q C_Q , and EFG asymmetry \\eta_Q \\eta_Q . This example is much more straightforward - all the atoms of a certain element are identical. We are given that a suitable \\sigma_{ref} \\sigma_{ref} (for oxygen) is 263ppm. Using the equation \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma - used before in Example 1 - we are able to convert the isometric chemical shielding tensor into a relative chemical shift: O in quartz has a shift of 28.46ppm and in cristoballite it has a shift of 23.53ppm","title":"Examples 3 - Alanine and Silicates"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#examples-3-alanine-and-silicates","text":"We now look at some more realistic and complex structures - the amino acid alanine and 2 different silicates: cristoballite and qartz. These are fairly large crystals - to get them to complete in a short time we will run them on a cluster. Use the following number of CPUs: analine - 4 cristoballite - 6 quartz - 13 (these numbers are chosen to give efficient k-point scaling) We will also perform EFG calculations for the above structures and examine the respective data.","title":"Examples 3 - Alanine and Silicates"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#oxygen-17-nmr","text":"Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure.","title":"Oxygen-17 NMR"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#alanine","text":"","title":"Alanine"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#examining-input-and-output","text":"We will use the cell file alanine.cell Note Don't worry about how long/complex it is - it is no different from any other cell file - it just simply defines a large cell and param file alanine.param fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr cut_off_energy = 35 ry xc_functional : PBE Note that the only difference to the previous files is the line magres_task = nmr This leads to EFG calculations being performed. alanine.param](alanine/alanine.param) You may also want to view the file alanine.pdb in Materials Studio or another software - this allows better examination of features like hydrogen bonding. This is the original file downloaded from the Cambridge Crystallographic Database (and was used to obtain the alanine.cell file). The cell structure was obtained experimentally by neutron diffraction. We will now run castep. The alanine.castep output file should contain the table This is much like our previous results , except there are now 2 more columns - C_Q C_Q and Eta Eta - these are both there because an EFG calculation was now performed. This result is not fully converged (we will not be testing this in this tutorial, but feel free to check), but the relative shift between some of the sites is converged (again you may verify that if inclined).","title":"Examining input and output"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#analysing-and-comparing-to-experiment","text":"We will now compare these results with experiment. The figure below is an experimental 17 O NMR spectrum of L-alanine. It shows 2 peaks, which are very broad due to the quadripolar coupling, and overlap. Fig3. Solid-State 17 O NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) The experimental parameters are given in Table 1 below. \\delta \\delta (A)- \\delta \\delta (B) (ppm) 23.5 C_Q C_Q (A) (MHz) 7.86 \\eta_Q \\eta_Q (A) 0.28 C_Q C_Q (B) (MHz) 6.53 \\eta_Q \\eta_Q (B) 0.70 Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labelled A and B. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_{Q} C_{Q} , and EFG asymmetry \\eta_Q \\eta_Q . From this, we will try to find what A and B are. To do so, we will look at the alanine.castep tensor table . By a quick glance at the table, we see that the the chemical shift of hydrogen ranges from 20-30ppm, carbon around 0, 124 or 159ppm, nitrogen 194ppm and oxygen 48 or 63ppm. Because of this we can tell that the 2 resonances are going to belong to carbon and oxygen: to get a chemical shift difference of 23.5ppm, oxygen's 48ppm and a hydrogen (ideally of 24.5ppm) are the only option of coming close to that value. We see in the oxygen portion of the table =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 48.29 352.85 0.51 7.125E+00 0.25 | | O 2 62.86 255.66 0.71 5.794E+00 0.64 | | O 3 48.29 352.85 0.51 7.125E+00 0.25 | | O 4 62.86 255.66 0.71 5.794E+00 0.64 | | O 5 48.29 352.85 0.51 7.125E+00 0.25 | | O 6 62.86 255.66 0.71 5.794E+00 0.64 | | O 7 48.29 352.85 0.51 7.125E+00 0.25 | | O 8 62.86 255.66 0.71 5.794E+00 0.64 | =============================================================================== that the chemical shift alternates consistently between 48.29 and 62.86. To examine why this is the case we may look at the alanine.cell file in Vesta (or the alanine.pdb file in Materials Studio, or any other option of your choice that shows hydrogen bonding). Similarly to example 1 , we will examine which atoms correspond to which environment. The cell and a purposely highlighted atom are shown below. The oxygens are the red atoms. We see here that there are effectively 2 types of oxygen here - ones with hydrogen bonding (dashed lines joining to a hydrogen (grey atom)) and ones without. Here atom 52 (oxygen ion 8 in the table ; it starts at 44 as there are 44 atoms before it) is selected: this has a chemical shielding value of 62.86ppm, as seen above. When clicking any oxygen with 2 hydrogen bonds it corresponds to an atom number that has a shielding tensor of 62.86ppm, while all the ones with 1 hydrogen bond have a value of 48.29ppm. For this exercise, we have now identified that resonance A comes from a single-hydrogen-bonded oxygen. There are a lot more hydrogens and thus it is harder to find which specific one A is referring to. Because \\delta \\delta (A) - \\delta \\delta (B) = 23.5ppm, we know that the chemical shielding should have a value of around 48.29 - 23.5 = 24.79ppm 48.29 - 23.5 = 24.79ppm From the table, we see that the closest value is 24.01ppm, corresponding to atoms 1, 8, 15 and 22. By clicking on hydrogens until one of those is found, we find that all 3 of those hydrogens are bonded to a nitrogen that is also bonded to 2 other hydrogens and a carbon. It is different from the other 2 hydrogens because the oxygen it is hydrogen-bonded to has no other hydrogen bonds: A and B are hydrogen-bonded to each other. These results are confirmed by the other values provided in the table. To confirm A being oxygen 1 (or 3 or 5... - all the values are identical), C_Q C_Q in the table is 7.125MHz compared to the expected 7.86MHz, and \\eta_Q \\eta_Q is 0.25 compared to the expected 0.28 - the results are very similar. However, this is not the case for hydrogen - a C_Q C_Q of 6.53MHz and an \\eta_Q \\eta_Q of 0.7 are expected, but the castep results are 0.21MHz and 0.06 respectively. In fact, the only ion that comes close to matching the C_Q C_Q eta_Q eta_Q expectation is the other (even-numbered) oxygen type: the oxygen that the hydrogen of interest (1, 8 and 15) is hydrogen-bonded to.","title":"Analysing and comparing to experiment"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#silicates-quartz-and-cristoballite","text":"As an extra example, we will now perform similar calculations and corresponding analysis with 2 forms of silicate - cristoballite and quartz. Naturally, we wiil do the castep calculations separately","title":"Silicates - Quartz and Cristoballite"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#input-and-output-files","text":"For quartz we will use the cell file quartz.cell And the param file quartz.param cut_off_energy = 40 ry xc_functional : PBE fix_occupancy = true opt_strategy : speed task = magres magres_task = nmr elec_energy_tol = 1.0e-12 ry The param file is identical to the alanine one above. For cristoballite we will use the cell file crist.cell And exactly the same param file as above (just named crist.param instead) We then run castep on both crystal structures as usual, getting the output files quartz.castep and crist.castep . Within those files, we will have the same types of tables as above: For quartz: =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 234.54 68.31 0.12 -5.085E+00 0.20 | | O 2 234.54 68.30 0.12 -5.086E+00 0.20 | | O 3 234.54 68.30 0.12 -5.086E+00 0.20 | | O 4 234.54 68.30 0.12 -5.086E+00 0.20 | | O 5 234.54 68.30 0.12 -5.086E+00 0.20 | | O 6 234.54 68.31 0.12 -5.085E+00 0.20 | | Si 1 435.01 -5.44 0.82 2.067E+01 0.72 | | Si 2 435.01 -5.45 0.81 2.067E+01 0.72 | | Si 3 435.01 -5.44 0.82 2.067E+01 0.72 | =============================================================================== and for cristoballite =============================================================================== | Chemical Shielding and Electric Field Gradient Tensors | |-----------------------------------------------------------------------------| | Nucleus Shielding tensor EFG Tensor | | Species Ion Iso(ppm) Aniso(ppm) Asym Cq(MHz) Eta | | O 1 239.47 79.97 0.08 -5.055E+00 0.14 | | O 2 239.47 79.97 0.08 -5.055E+00 0.14 | | O 3 239.47 79.97 0.08 -5.055E+00 0.14 | | O 4 239.47 79.97 0.08 -5.055E+00 0.14 | | O 5 239.47 79.97 0.08 -5.055E+00 0.14 | | O 6 239.47 79.97 0.08 -5.055E+00 0.14 | | O 7 239.47 79.97 0.08 -5.055E+00 0.14 | | O 8 239.47 79.97 0.08 -5.055E+00 0.14 | | Si 1 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 2 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 3 437.12 -9.36 0.61 -1.077E+01 0.88 | | Si 4 437.12 -9.36 0.61 -1.077E+01 0.88 | ===============================================================================","title":"Input and output files"},{"location":"tutorials/NMR/Examples_3_-Alanine_and_Silicates/#analysing-and-comparing-to-experiment_1","text":"Like with alanine, we will compare it to an experimental 17 O NMR parameter table - this is shown below as Table 2 \\delta \\delta (ppm) C_Q C_Q (MHz) \\eta_Q \\eta_Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19 Table 2: Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \\delta \\delta , quadrupolar coupling C_Q C_Q , and EFG asymmetry \\eta_Q \\eta_Q . This example is much more straightforward - all the atoms of a certain element are identical. We are given that a suitable \\sigma_{ref} \\sigma_{ref} (for oxygen) is 263ppm. Using the equation \\delta_{iso} \\delta_{iso} = \\sigma_{iso} \\sigma_{iso} - \\sigma \\sigma - used before in Example 1 - we are able to convert the isometric chemical shielding tensor into a relative chemical shift: O in quartz has a shift of 28.46ppm and in cristoballite it has a shift of 23.53ppm","title":"Analysing and comparing to experiment"},{"location":"tutorials/Optics/JDOS/","text":"JDOS The JDOS (Joint Density of States) is effectively the density of states for an energy range which is equal to the difference between conduction and valence bands - this leads to being able to calculate the probability of an excitation occurring for a given photon energy. One can intuitively understand how this leads to the calculation of optical properties: photons that have energies that correspond to gaps between conduction and valence bands will interact with the material and give rise to its optical properties. In this tutorial, we will calculate the JDOS for silicon, and then relate that to the imaginary and real part of the dielectric function. JDOS Calculation Let's start by actually getting the JDOS results. Run Castep on the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 and param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 Afterwards, run Optados with the Optados input file Si.odi TASK : jdos JDOS_MAX_ENERGY : 30 JDOS_SPACING : 0.01 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default The line TASK : jdos is what tells it to calculate the JDOS in which we are interested. This will generate the file Si.jadaptive.dat (as well as the accompanying agr file). The dat file data table should start like this 0.0000000000000E+00 0.3375085335870E-14 0.1000333444481E-01 0.3869643667676E-14 The 1 st column is the energy, and the 2 nd is the JDOS. The agr file allows us to make a nice plot with xmgrace (though of course you could plot the results with your software of choice) - let's run xmgrace Si.jadaptive.agr The result should look like this: Imaginary Dielectric Now that we have the results, let's examine how they are used to get the dielectric function. You may immediately notice that the shape of the graph above is completely different from either component of the dielectric function. We will need to process the results for them to be meaningful. We will start processing the data by using the Python script energies = [] imaginaries = [] input_file = 'Si.jadaptive.dat' output_file = 'imaginary.dat' new_lines = [] with open ( input_file , 'r' ) as infile : for line in infile : if \"#\" in line : continue parts = line . split () if len ( parts ) == 2 : energy = float ( parts [ 0 ]) jdos = float ( parts [ 1 ]) energies . append ( energy ) if jdos == 0.0 or energy == 0 : eps2 = 0 else : eps2 = ( jdos / energy ** 2 ) imaginaries . append ( eps2 ) new_line = f \" { energy } { jdos } { test } \\n \" new_lines . append ( new_line ) with open ( output_file , 'w' ) as outfile : outfile . writelines ( new_lines ) This creates a new file imaginary.dat that contains the energy, JDOS and our first approximation of the imaginary dielectric function in the 3 rd column. This is approximated by the relationship \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} which was implemented in the line eps2 = ( jdos / energy ** 2 ) We can plot this dat file by using xmgrace on the batch script plot.bat READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" to get just the imaginary output. The graph should look like this: We're starting to see a bit of a resemblance to the imaginary component of the imaginary dielectric function, but it still clearly has room for improvement - the calculation is performed by multiplying what we found by a matrix element, which in this case we are assuming to be constant with energy - which is not the case in reality. We can improve the approximation by using the relationship \\epsilon_2 \\propto \\frac{1}{m^*} \\epsilon_2 \\propto \\frac{1}{m^*} This is a hard thing to implement properly; the effective mass is very difficult to get, depends on position in k-space etc. However, we can simply this with the approximation that, near the band edges, the effective mass is directly proportional to the energy. Note This does have some mathematical merit - if you wish to see where this comes from, have a look at this paper Let's change the line where eps2 is calculated in the Python script to eps2 = ( dos / energy ** 3 ) Re-running the same procedure now yields the graph: At a glance, you can see that it levels off much more quickly - just as it happens in the more-properly calculated dielectric function. To confirm that the results are reasonable, let's plot this together with the results from an actual Optados optics calculation. You can see how to obtain this data at the start of the optics tutorial , or you can download the relevant dat file here . Because we have gotten the results using simple proportionality relations, we'll have to scale the results to make them match experiment - adjust the Python script by changing the eps2 calculation line to eps2 = (dos/energy**3) * 650 650 was found by trial and error to give a reasonable match - again this is simply estimating the constant of proportionality that has been ignored throughout this approximation. You can use the batch file READ BLOCK \"Si_epsilon.dat\" BLOCK XY \"1:3\" S0 LEGEND \"Optics Calculated\" READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" S1 LEGEND \"JDOS Approximated\" to plot it with xmgrace. You can see that they are fairly similar in the graph produced: Real Dielectric We have seen how the JDOS is used to calculate the imaginary dielectric function, and now we will look at how the real component is calculated. The real component is actually calculated only using the imaginary component, using the Kramers-Kroniger relations - and we will demonstrate that. The equation we will use is \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' We'll ignore the constants of proportionality again and just adjust the results. Adding this block of code to the previous Python script import numpy as np energies_arr = np . array ( energies ) eps2_arr = np . array ( imaginaries ) def kramers (): eps1_arr = [] for i , e in enumerate ( energies_arr ): real = 0 sub = ( energies_arr ** 2 ) - ( e ** 2 ) sub [ i ] = np . inf integrand = ( energies_arr * eps2_arr ) / sub real = 1 + 0.6 ( np . trapz ( integrand , energies_arr )) eps1_arr . append ( real ) return eps1_arr eps1_arr = kramers () data = np . column_stack (( energies_arr , eps2_arr , eps1_arr )) np . savetxt ( \"both.dat\" , data ) The implementation is fairly straightforward: for every energy: the integral as in the equation is simply performed for every energy. While adding 1 to the integral is specified in the equation, again the constant of proportionality was found by trial and error until it was a decent fit (and the imaginary part was already scaled the same way). The data is then saved in both.dat with the 1 st column being energy, the 2 nd imaginary dielectric and the 3 rd real dielectric. Let's now compare the imaginary components using xmgrace. Adjust the batch file appropriately, and you should get a graph that looks like: Now we have demonstrated how both parts of the dielectric are related to the JDOS. Sampling Parameters We will now have a look at the effect of increasing and decreasing the JDOS_MAX_ENERGY and JDOS_SPACING parameters. JDOS_MAX_ENERGY determines the highest energy band that is examined, while JDOS_SPACING determines how frequently the results are sampled. We will perform exactly the same procedure as above (including calculating the real and imaginary dielectric - this is the crucial part). It is recommended that you do these calculations in new directories to make it easier to compare results. Maximum Energy Let's first look at increasing and decreasing the maximum energy. We'll start off by increasing it to 100eV. Run the full procedure as above (ending up with both.dat in the new directory), except with the odi file having the line JDOS_MAX_ENERGY : 100 instead of 30. In this case, it is most useful to compare with the result we got from the 30eV maximum energy - plot them both on the same graph. This is what was obtained using an appropriate batch file: We see that the overlap is virtually perfect: sampling beyond 30eV does not improve any results. This indicates that all contributing bands have an energy of 30eV or lower. Let's now try lowering the maximum energy. If we try 20eV and plotting it together with the 30eV result the same way we see this: Now the overlap is no longer perfect: especially towards the end, the real part is becoming increasingly different. Feel free to try different lower energies - you should notice that the lower the maximum energy, the more different the real part becomes, while the imaginary component is unchanging. The example below is for very low 5eV: This shows us that the imaginary component is calculated independently for each energy, but, because the real component is calculated by integrating over all energies, the imaginary component becomes increasingly incorrect as the integral becomes performed not over the full relevant range. Spacing Now let's try decreasing and increasing the rate of sampling by changing the JDOS_SPACING parameter. We will compare it to the standard 0.01eV results we calculated before. First, let's try lowering it - be warned that making it too low will make the python script used to get the real component run extremely slowly; the integral becomes too demanding with too many points. JDOS_SPACING : 0.0005 was used in for the result below: We see here that the results are virtually the same for low and high frequencies, and even the middle part is mostly the same, except for a very narrow range of energies - precisely where the most extreme jumps are occurring. Having a larger sampling failed to capture the largest increases, and increasing the sampling rate meant that they are now seen. Since the other parts of the dielectric function doesn't have such extreme changes, nothing was missed by a slightly higher sampling spacing. Let's now have a look at what happens when we increase the spacing. The result is about what you'd expect: the graph simply loses some of the detail, as seen below. The graph is smoothened out, and, if you were to increase the spacing further, increasing amounts of detail would be lost. Though both results are affected, the real component is more affected: due to it being calculated by integrating the imaginary part, it is much more sensitive to any kind of change in sampling.","title":"JDOS"},{"location":"tutorials/Optics/JDOS/#jdos","text":"The JDOS (Joint Density of States) is effectively the density of states for an energy range which is equal to the difference between conduction and valence bands - this leads to being able to calculate the probability of an excitation occurring for a given photon energy. One can intuitively understand how this leads to the calculation of optical properties: photons that have energies that correspond to gaps between conduction and valence bands will interact with the material and give rise to its optical properties. In this tutorial, we will calculate the JDOS for silicon, and then relate that to the imaginary and real part of the dielectric function.","title":"JDOS"},{"location":"tutorials/Optics/JDOS/#jdos-calculation","text":"Let's start by actually getting the JDOS results. Run Castep on the cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 10 10 10 and param file Si.param TASK : SPECTRAL SPECTRAL_TASK : DOS PDOS_CALCULATE_WEIGHTS : TRUE CUT_OFF_ENERGY : 200 Afterwards, run Optados with the Optados input file Si.odi TASK : jdos JDOS_MAX_ENERGY : 30 JDOS_SPACING : 0.01 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default FIXED_SMEARING : 0.3 # Default SET_EFERMI_ZERO : true # Default NUMERICAL_INTDOS : false # Default FINITE_BIN_CORRECTION : true # Default The line TASK : jdos is what tells it to calculate the JDOS in which we are interested. This will generate the file Si.jadaptive.dat (as well as the accompanying agr file). The dat file data table should start like this 0.0000000000000E+00 0.3375085335870E-14 0.1000333444481E-01 0.3869643667676E-14 The 1 st column is the energy, and the 2 nd is the JDOS. The agr file allows us to make a nice plot with xmgrace (though of course you could plot the results with your software of choice) - let's run xmgrace Si.jadaptive.agr The result should look like this:","title":"JDOS Calculation"},{"location":"tutorials/Optics/JDOS/#imaginary-dielectric","text":"Now that we have the results, let's examine how they are used to get the dielectric function. You may immediately notice that the shape of the graph above is completely different from either component of the dielectric function. We will need to process the results for them to be meaningful. We will start processing the data by using the Python script energies = [] imaginaries = [] input_file = 'Si.jadaptive.dat' output_file = 'imaginary.dat' new_lines = [] with open ( input_file , 'r' ) as infile : for line in infile : if \"#\" in line : continue parts = line . split () if len ( parts ) == 2 : energy = float ( parts [ 0 ]) jdos = float ( parts [ 1 ]) energies . append ( energy ) if jdos == 0.0 or energy == 0 : eps2 = 0 else : eps2 = ( jdos / energy ** 2 ) imaginaries . append ( eps2 ) new_line = f \" { energy } { jdos } { test } \\n \" new_lines . append ( new_line ) with open ( output_file , 'w' ) as outfile : outfile . writelines ( new_lines ) This creates a new file imaginary.dat that contains the energy, JDOS and our first approximation of the imaginary dielectric function in the 3 rd column. This is approximated by the relationship \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} \\epsilon_2 \\propto \\frac{\\text{JDOS}}{\\omega^2} which was implemented in the line eps2 = ( jdos / energy ** 2 ) We can plot this dat file by using xmgrace on the batch script plot.bat READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" to get just the imaginary output. The graph should look like this: We're starting to see a bit of a resemblance to the imaginary component of the imaginary dielectric function, but it still clearly has room for improvement - the calculation is performed by multiplying what we found by a matrix element, which in this case we are assuming to be constant with energy - which is not the case in reality. We can improve the approximation by using the relationship \\epsilon_2 \\propto \\frac{1}{m^*} \\epsilon_2 \\propto \\frac{1}{m^*} This is a hard thing to implement properly; the effective mass is very difficult to get, depends on position in k-space etc. However, we can simply this with the approximation that, near the band edges, the effective mass is directly proportional to the energy. Note This does have some mathematical merit - if you wish to see where this comes from, have a look at this paper Let's change the line where eps2 is calculated in the Python script to eps2 = ( dos / energy ** 3 ) Re-running the same procedure now yields the graph: At a glance, you can see that it levels off much more quickly - just as it happens in the more-properly calculated dielectric function. To confirm that the results are reasonable, let's plot this together with the results from an actual Optados optics calculation. You can see how to obtain this data at the start of the optics tutorial , or you can download the relevant dat file here . Because we have gotten the results using simple proportionality relations, we'll have to scale the results to make them match experiment - adjust the Python script by changing the eps2 calculation line to eps2 = (dos/energy**3) * 650 650 was found by trial and error to give a reasonable match - again this is simply estimating the constant of proportionality that has been ignored throughout this approximation. You can use the batch file READ BLOCK \"Si_epsilon.dat\" BLOCK XY \"1:3\" S0 LEGEND \"Optics Calculated\" READ BLOCK \"imaginary.dat\" BLOCK XY \"1:3\" S1 LEGEND \"JDOS Approximated\" to plot it with xmgrace. You can see that they are fairly similar in the graph produced:","title":"Imaginary Dielectric"},{"location":"tutorials/Optics/JDOS/#real-dielectric","text":"We have seen how the JDOS is used to calculate the imaginary dielectric function, and now we will look at how the real component is calculated. The real component is actually calculated only using the imaginary component, using the Kramers-Kroniger relations - and we will demonstrate that. The equation we will use is \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' \\epsilon_1(\\omega) = 1 + \\frac{2}{\\pi} \\mathcal{P} \\int_{0}^{\\infty} \\frac{\\omega' \\epsilon_2(\\omega')}{\\omega'^2 - \\omega^2} \\, d\\omega' We'll ignore the constants of proportionality again and just adjust the results. Adding this block of code to the previous Python script import numpy as np energies_arr = np . array ( energies ) eps2_arr = np . array ( imaginaries ) def kramers (): eps1_arr = [] for i , e in enumerate ( energies_arr ): real = 0 sub = ( energies_arr ** 2 ) - ( e ** 2 ) sub [ i ] = np . inf integrand = ( energies_arr * eps2_arr ) / sub real = 1 + 0.6 ( np . trapz ( integrand , energies_arr )) eps1_arr . append ( real ) return eps1_arr eps1_arr = kramers () data = np . column_stack (( energies_arr , eps2_arr , eps1_arr )) np . savetxt ( \"both.dat\" , data ) The implementation is fairly straightforward: for every energy: the integral as in the equation is simply performed for every energy. While adding 1 to the integral is specified in the equation, again the constant of proportionality was found by trial and error until it was a decent fit (and the imaginary part was already scaled the same way). The data is then saved in both.dat with the 1 st column being energy, the 2 nd imaginary dielectric and the 3 rd real dielectric. Let's now compare the imaginary components using xmgrace. Adjust the batch file appropriately, and you should get a graph that looks like: Now we have demonstrated how both parts of the dielectric are related to the JDOS.","title":"Real Dielectric"},{"location":"tutorials/Optics/JDOS/#sampling-parameters","text":"We will now have a look at the effect of increasing and decreasing the JDOS_MAX_ENERGY and JDOS_SPACING parameters. JDOS_MAX_ENERGY determines the highest energy band that is examined, while JDOS_SPACING determines how frequently the results are sampled. We will perform exactly the same procedure as above (including calculating the real and imaginary dielectric - this is the crucial part). It is recommended that you do these calculations in new directories to make it easier to compare results.","title":"Sampling Parameters"},{"location":"tutorials/Optics/JDOS/#maximum-energy","text":"Let's first look at increasing and decreasing the maximum energy. We'll start off by increasing it to 100eV. Run the full procedure as above (ending up with both.dat in the new directory), except with the odi file having the line JDOS_MAX_ENERGY : 100 instead of 30. In this case, it is most useful to compare with the result we got from the 30eV maximum energy - plot them both on the same graph. This is what was obtained using an appropriate batch file: We see that the overlap is virtually perfect: sampling beyond 30eV does not improve any results. This indicates that all contributing bands have an energy of 30eV or lower. Let's now try lowering the maximum energy. If we try 20eV and plotting it together with the 30eV result the same way we see this: Now the overlap is no longer perfect: especially towards the end, the real part is becoming increasingly different. Feel free to try different lower energies - you should notice that the lower the maximum energy, the more different the real part becomes, while the imaginary component is unchanging. The example below is for very low 5eV: This shows us that the imaginary component is calculated independently for each energy, but, because the real component is calculated by integrating over all energies, the imaginary component becomes increasingly incorrect as the integral becomes performed not over the full relevant range.","title":"Maximum Energy"},{"location":"tutorials/Optics/JDOS/#spacing","text":"Now let's try decreasing and increasing the rate of sampling by changing the JDOS_SPACING parameter. We will compare it to the standard 0.01eV results we calculated before. First, let's try lowering it - be warned that making it too low will make the python script used to get the real component run extremely slowly; the integral becomes too demanding with too many points. JDOS_SPACING : 0.0005 was used in for the result below: We see here that the results are virtually the same for low and high frequencies, and even the middle part is mostly the same, except for a very narrow range of energies - precisely where the most extreme jumps are occurring. Having a larger sampling failed to capture the largest increases, and increasing the sampling rate meant that they are now seen. Since the other parts of the dielectric function doesn't have such extreme changes, nothing was missed by a slightly higher sampling spacing. Let's now have a look at what happens when we increase the spacing. The result is about what you'd expect: the graph simply loses some of the detail, as seen below. The graph is smoothened out, and, if you were to increase the spacing further, increasing amounts of detail would be lost. Though both results are affected, the real component is more affected: due to it being calculated by integrating the imaginary part, it is much more sensitive to any kind of change in sampling.","title":"Spacing"},{"location":"tutorials/Optics/Optics/","text":"Optics In this tutorial, we will use Optados to examine the optical properties of silicon and aluminium. Silicon Properties For Silicon, we will use the input cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 and the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 IPRINT : 2 Run Castep as usual. When it is done, run Optados on Si with the Optados input file Si.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : polycrystalline # Default OPTICS_LOSSFN_BROADENING : 0.0 After running Optados, we get several output .dat and .agr files. We will now examine them. Epsilon.dat First let's look at the file containing the (polycrystalline) dielectric function - Si_epsilon.dat . The contents of the file look like 0.0000000000000000 14.107263205387552 0.0000000000000000 1.0003334444814937E-002 14.107363765236455 0.0000000000000000 2.0006668889629875E-002 14.107665455817445 0.0000000000000000 3.0010003334444812E-002 14.108168310237140 0.0000000000000000 The 1 st column corresponds to the energy (of the photon interacting with it), the 2 nd is the real component of the dielectric function, and the 3 rd is the imaginary component. The header also contains the results of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') # Result of sum rule: Neff(E) = 7.0939380864459736 Where N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Let's plot it using xmgrace. Although you could plot the dat file (after configuring a bit to get it to plot everything properly), but luckily Optados has also generated an equivalent agr file that contains the same data, but also formats the xmgrace graph nicely. So let's use xmgrace Si_epsilon.agr and get an output looking like This is a very neat result: it looks just like what you'd expect from the Debye equations This file gives us all the data necessary for the calculation of any optical property of the cell examined. As we will see in the remainder of the tutorial, it is the basis of the generation of all the other files. Absorption Next let's look at the absorption data. The dat file is very similar, this time with 2 columns: the 1 st is the energy of the photon, and the 2 nd is the absorption coefficient. It doesn't look particularly different, but if you wish to check, the data table should start like 0.0000000000000000 0.0000000000000000 1.0020040080160320E-002 0.0000000000000000 You can plot it with xmgrace the same way as before (again the agr file is prepared by Optados). It should look like this Let's examine how this is calculated. The absorption coefficient is calculated as \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} Where \\omega \\omega is the energy divided by \\hbar \\hbar , \\kappa \\kappa is the imaginary refractive index and c c is the speed of light. \\kappa \\kappa can be easily obtained from the real and imaginary dielectric functions, knowing that the complex refractive index is the square root of the complex dielectric function - this leads to the equation \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} To check that this is really what's going on in the absorption calculation, we can use the Python script import numpy as np c = 3e8 hbar = 6.582119569e-16 def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar kappa = np . sqrt ( 0.5 * ( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c return alpha data = np . loadtxt ( 'Si2_OPTICS_epsilon.dat' ) energy = data [:, 0 ] epsilon_1 = data [:, 1 ] epsilon_2 = data [:, 2 ] result = calculate_property_coefficient ( energy , epsilon_1 , epsilon_2 ) output_data = np . column_stack (( energy , result )) np . savetxt ( 'predicted_abs.dat' , output_data , fmt = ' %e ' , delimiter = ' ' ) If plot this together with Si_absorption.dat , you should get an identical result to above . For the next properties we will calculate, we will also see where they come from using an almost identical Python script: simply change the calculate_property function. Refractive Index Next we will look at the (real and imaginary) refractive index. This data is found in the Si_refractive_index.dat (and .agr ) files. The file is similar to the previous, this time having 3 columns again - the 1 st is energy, the 2 nd is the real refractive index and the 3 rd is the imaginary refractive index. We have already looked at how to calculate the imaginary refractive index above (multiply it by some constants and you have the absorption coefficient). The calculation of the real refractive index is very similar, instead becoming n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} and the accompanying Python script to verify if this is right is also very similar: the function becomes def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar # Convert energy (eV) to angular frequency (rad/s) kappa = np . sqrt ( 0.5 * ( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c # Absorption coefficient (1/m) return alpha If you're not interested in the Python output, just plot the Si_refractive_index.agr file using xmgrace, but if you wish to plot them together it is easiest to use xmgrace -batch double.bat on the batch file double.bat READ BLOCK \"predicted_refractive_indices.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Predicted real\" BLOCK XY \"1:3\" S1 LEGEND \"Predicted imaginary\" READ BLOCK \"Si2_OPTICS_refractive_index.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Optados real\" BLOCK XY \"1:3\" S3 LEGEND \"Optados imaginary\" LEGEND 0.9, 0.9 This gives a graph that looks like this: Once again, the values derived from the dielectric function dataset are identical, so they overlap - confirming for us how the properties are calculated. You may note that the imaginary refractive index's shape is identical to that of the absorption - as we've seen, it's just that multiplied by a constant. Reflectivity Next we will look at the reflectivity. This can be found in Si_reflection.dat (and .agr again). The 1 st column represents the energy, as usual, while the 2 nd is the corresponding reflection coefficient. The reflectivity is calculated using the Fresnel equations , using normal incidence and assuming the incoming light ray is coming out of air/vacuum (real and imaginary refractive index n 1 and n 2 of the first medium = 1). The imaginary component was also neglected. Under these conditions, the equation for reflectivity becomes R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 Where \\tilde{n} \\tilde{n} is the complex refractive index (real + imaginary part). We can implement this in the Python script more easily by separating it into functions to find the refractive indices (like we did before ), and then use that to find the reflectivity. def calculate_refractive_indices ( epsilon_1 , epsilon_2 ): n = np . sqrt (( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) kappa = np . sqrt (( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) return n , kappa def calculate_property ( n , kappa ): n_complex = n + 1 j * kappa reflectivity = np . abs (( n_complex - 1 ) / ( n_complex + 1 )) ** 2 return reflectivity Once again, we plot the output file of the script along with the .dat file and see that they're identical: If you are interested, you could change the Fresnel equation used and appropriately adjust the script to include the imaginary part, see how it behaves coming from a different medium, different angle etc. - there is a lot you could look at in terms of reflectivity. Conductivity Next we will look the optical conductivity of silicon in Si_conductivity.dat . The 1 st column is the energy, while the 2 nd and 3 rd columns are the real and imaginary parts of conductivity, both in the SI units Siemens per meter. The complex optical conductivity can be found by approximating in the high frequency limit and rearranging the equation to: \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) where \\sigma_1 \\sigma_1 is the real part and \\sigma_2 \\sigma_2 is the imaginary. As usual \\epsilon_1 \\epsilon_1 corresponds to the real dielectric and \\epsilon_2 \\epsilon_2 to the imaginary. In this calculation, \\epsilon_\\infty \\epsilon_\\infty is approximated as 1. This can be implemented in our Python script as def calculate_conductivity ( epsilon_1 , epsilon_2 , energy ): omega = energy / hbar sigma_1 = epsilon_0 * omega * epsilon_2 sigma_2 = - epsilon_0 * omega * ( epsilon_1 - epsilon_inf ) return sigma_1 , sigma_2 As in previous cases, make sure all constants are defined and any file/variable names adjusted as you implement it. Since there are 3 columns, it is easier to plot them together - we can simply repurpose our previous batch file - just make sure to change file names as appropriate. The output should look like: Loss Function Lastly, we will examine the loss function in Si_loss_fn.dat . The 1 st column is the energy, while the 2 nd is the loss function for that energy. The header of the file shows the results of the two sum rules associated with the loss function: \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} The loss function itself is calculated rather simply from the dielectric: it is simply the imaginary component of the inverse of the complex dielectric: \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) This leads to \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} Let's implement this into our Python script by changing the function to def calculate_property ( epsilon_1 , epsilon_2 ): loss_function = epsilon_2 / ( epsilon_1 ** 2 + epsilon_2 ** 2 ) return loss_function Plotting it together with Si_loss_fn.dat on xmgrace gives us the graph Changing Parameters Now that we know what Optados optics does and how it works, let's try changing some parameters in the Optados input file Si.odi , and re-running Optados, to see what effects it has. JDOS Parameters First let's have a look at the effect of changing the line JDOS_MAX_ENERGY : 30 . We'll set it to 10 and 100 and plot Si_epsilon.agr using xmgrace. Doing it for 10 gives the graph while 100 gives us You can also compare with the result for 30 . What you should notice is that all the plots are the same - what this does is change the maximum energy it calculates the optical properties up to. The graphs aren't particularly interesting (you could do a higher max energy calculation and just set WORLD XMAX 10 to see it up to 10eV for example), but it does affect the results of the sum rules - which are in headers and thus not seen in graphs. Let's try seeing the results for JDOS_MAX_ENERGY : 2, 5, 10, 30 and 100. In Si_epsilon.dat the sum rule results for the different max energies should be around as follows: JDOS Max E Sum Rule Result 2 1.58E-6 5 4.40 10 6.42 30 7.09 100 7.11 This tells us that at 2eV barely any electrons contribute to the absorption process, at 5eV over half do, and beyond that slowly increasing amounts do. Most electrons seem to act for energies between 2 and 30eV. Meanwhile, the results of the 1 st and 2 nd sum rules in Si_loss_fn look rather different: JDOS Max E Sum Rule 1 Sum Rule 2 2 1.58E-6 2.18E-5 5 4.25E-3 1.54E-2 10 7.07E-2 7.58E-2 30 7.08 1.46 100 7.10 1.46 Here the 1 st rule seems to shoot up much more drastically and in a different region (between 10 and 30eV), while the 2 nd tends towards a different value, and again shoots up faster and in the same region. Now we'll take a look at the effects of changing the JDOS_SPACING value. Let's change JDOS_SPACING : 0.01 to 1 and 0.001. We'll do this for JDOS_MAX_ENERGY : 30 . For 1 the graph looks like while for 0.001 it looks like As we see here, changing JDOS_SPACING simply affects the frequency of the sampling: the smaller the value, the smaller the energy intervals at which it examines the dielectric function and thus the smoother the curve. You may note that the graphs look the same as the when we first did it with the default 0.01 above - 0.01 is sufficient, and increasing the sampling frequency gives us virtually the same results but slower. This is reflected in the sum rule calculations - the higher the spacing, the more rough of an estimate they are, and that typically leads to them being larger, with it not getting much more accurate being 0.01. JDOS Spacing Epsilon Sum Loss Sum 1 Loss Sum 2 0.001 6.73 6.72 1.50 0.01 6.74 6.73 1.50 1 8.28 7.22 1.39 Loss Function Broadening Additional broadening can be included in the calculation of the loss function. This is done by setting the keyword optics_lossfn_broadening in the odi file to a non-zero value. To have a look at what it does, let's set optics_lossfn_broadening : 1 and rerun Optados. The only files that are different are the Si_loss_fn.dat and .agr files - they now contain a 3 rd column. The 1 st is still energy, the 2 nd is the unbroadened spectrum (the same result as when we did it above ), and the 3 rd is the broadened spectrum. Plotting thr agr file using xmgrace gives us this graph: Broadening it has effectively \"smoothed out\" the curve, and the agr file has the unbroadened results for comparison.","title":"Optics"},{"location":"tutorials/Optics/Optics/#optics","text":"In this tutorial, we will use Optados to examine the optical properties of silicon and aluminium.","title":"Optics"},{"location":"tutorials/Optics/Optics/#silicon-properties","text":"For Silicon, we will use the input cell file Si.cell %BLOCK LATTICE_CART 2.73 2.73 0.00 2.73 0.00 2.73 0.00 2.73 2.73 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Si 0.0 0.0 0.0 Si 0.25 0.25 0.25 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 and the param file Si.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 IPRINT : 2 Run Castep as usual. When it is done, run Optados on Si with the Optados input file Si.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : polycrystalline # Default OPTICS_LOSSFN_BROADENING : 0.0 After running Optados, we get several output .dat and .agr files. We will now examine them.","title":"Silicon Properties"},{"location":"tutorials/Optics/Optics/#epsilondat","text":"First let's look at the file containing the (polycrystalline) dielectric function - Si_epsilon.dat . The contents of the file look like 0.0000000000000000 14.107263205387552 0.0000000000000000 1.0003334444814937E-002 14.107363765236455 0.0000000000000000 2.0006668889629875E-002 14.107665455817445 0.0000000000000000 3.0010003334444812E-002 14.108168310237140 0.0000000000000000 The 1 st column corresponds to the energy (of the photon interacting with it), the 2 nd is the real component of the dielectric function, and the 3 rd is the imaginary component. The header also contains the results of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') # Result of sum rule: Neff(E) = 7.0939380864459736 Where N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Let's plot it using xmgrace. Although you could plot the dat file (after configuring a bit to get it to plot everything properly), but luckily Optados has also generated an equivalent agr file that contains the same data, but also formats the xmgrace graph nicely. So let's use xmgrace Si_epsilon.agr and get an output looking like This is a very neat result: it looks just like what you'd expect from the Debye equations This file gives us all the data necessary for the calculation of any optical property of the cell examined. As we will see in the remainder of the tutorial, it is the basis of the generation of all the other files.","title":"Epsilon.dat"},{"location":"tutorials/Optics/Optics/#absorption","text":"Next let's look at the absorption data. The dat file is very similar, this time with 2 columns: the 1 st is the energy of the photon, and the 2 nd is the absorption coefficient. It doesn't look particularly different, but if you wish to check, the data table should start like 0.0000000000000000 0.0000000000000000 1.0020040080160320E-002 0.0000000000000000 You can plot it with xmgrace the same way as before (again the agr file is prepared by Optados). It should look like this Let's examine how this is calculated. The absorption coefficient is calculated as \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} \\alpha(\\omega) = \\frac{2 \\omega \\kappa(\\omega)}{c} Where \\omega \\omega is the energy divided by \\hbar \\hbar , \\kappa \\kappa is the imaginary refractive index and c c is the speed of light. \\kappa \\kappa can be easily obtained from the real and imaginary dielectric functions, knowing that the complex refractive index is the square root of the complex dielectric function - this leads to the equation \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} \\kappa(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} - \\epsilon_1(\\omega) \\right]} To check that this is really what's going on in the absorption calculation, we can use the Python script import numpy as np c = 3e8 hbar = 6.582119569e-16 def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar kappa = np . sqrt ( 0.5 * ( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c return alpha data = np . loadtxt ( 'Si2_OPTICS_epsilon.dat' ) energy = data [:, 0 ] epsilon_1 = data [:, 1 ] epsilon_2 = data [:, 2 ] result = calculate_property_coefficient ( energy , epsilon_1 , epsilon_2 ) output_data = np . column_stack (( energy , result )) np . savetxt ( 'predicted_abs.dat' , output_data , fmt = ' %e ' , delimiter = ' ' ) If plot this together with Si_absorption.dat , you should get an identical result to above . For the next properties we will calculate, we will also see where they come from using an almost identical Python script: simply change the calculate_property function.","title":"Absorption"},{"location":"tutorials/Optics/Optics/#refractive-index","text":"Next we will look at the (real and imaginary) refractive index. This data is found in the Si_refractive_index.dat (and .agr ) files. The file is similar to the previous, this time having 3 columns again - the 1 st is energy, the 2 nd is the real refractive index and the 3 rd is the imaginary refractive index. We have already looked at how to calculate the imaginary refractive index above (multiply it by some constants and you have the absorption coefficient). The calculation of the real refractive index is very similar, instead becoming n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} n(\\omega) = \\sqrt{\\frac{1}{2} \\left[ \\sqrt{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} + \\epsilon_1(\\omega) \\right]} and the accompanying Python script to verify if this is right is also very similar: the function becomes def calculate_property ( energy , epsilon_1 , epsilon_2 ): omega = energy / hbar # Convert energy (eV) to angular frequency (rad/s) kappa = np . sqrt ( 0.5 * ( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 ))) alpha = ( 2 * omega * kappa ) / c # Absorption coefficient (1/m) return alpha If you're not interested in the Python output, just plot the Si_refractive_index.agr file using xmgrace, but if you wish to plot them together it is easiest to use xmgrace -batch double.bat on the batch file double.bat READ BLOCK \"predicted_refractive_indices.dat\" BLOCK XY \"1:2\" S0 LEGEND \"Predicted real\" BLOCK XY \"1:3\" S1 LEGEND \"Predicted imaginary\" READ BLOCK \"Si2_OPTICS_refractive_index.dat\" BLOCK XY \"1:2\" S2 LEGEND \"Optados real\" BLOCK XY \"1:3\" S3 LEGEND \"Optados imaginary\" LEGEND 0.9, 0.9 This gives a graph that looks like this: Once again, the values derived from the dielectric function dataset are identical, so they overlap - confirming for us how the properties are calculated. You may note that the imaginary refractive index's shape is identical to that of the absorption - as we've seen, it's just that multiplied by a constant.","title":"Refractive Index"},{"location":"tutorials/Optics/Optics/#reflectivity","text":"Next we will look at the reflectivity. This can be found in Si_reflection.dat (and .agr again). The 1 st column represents the energy, as usual, while the 2 nd is the corresponding reflection coefficient. The reflectivity is calculated using the Fresnel equations , using normal incidence and assuming the incoming light ray is coming out of air/vacuum (real and imaginary refractive index n 1 and n 2 of the first medium = 1). The imaginary component was also neglected. Under these conditions, the equation for reflectivity becomes R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 R = \\left( \\frac{\\tilde{n} - 1}{\\tilde{n} + 1} \\right)^2 Where \\tilde{n} \\tilde{n} is the complex refractive index (real + imaginary part). We can implement this in the Python script more easily by separating it into functions to find the refractive indices (like we did before ), and then use that to find the reflectivity. def calculate_refractive_indices ( epsilon_1 , epsilon_2 ): n = np . sqrt (( epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) kappa = np . sqrt (( - epsilon_1 + np . sqrt ( epsilon_1 ** 2 + epsilon_2 ** 2 )) / 2 ) return n , kappa def calculate_property ( n , kappa ): n_complex = n + 1 j * kappa reflectivity = np . abs (( n_complex - 1 ) / ( n_complex + 1 )) ** 2 return reflectivity Once again, we plot the output file of the script along with the .dat file and see that they're identical: If you are interested, you could change the Fresnel equation used and appropriately adjust the script to include the imaginary part, see how it behaves coming from a different medium, different angle etc. - there is a lot you could look at in terms of reflectivity.","title":"Reflectivity"},{"location":"tutorials/Optics/Optics/#conductivity","text":"Next we will look the optical conductivity of silicon in Si_conductivity.dat . The 1 st column is the energy, while the 2 nd and 3 rd columns are the real and imaginary parts of conductivity, both in the SI units Siemens per meter. The complex optical conductivity can be found by approximating in the high frequency limit and rearranging the equation to: \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_1(\\omega) = \\epsilon_0 \\omega \\epsilon_2(\\omega) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) \\sigma_2(\\omega) = -\\epsilon_0 \\omega (\\epsilon_1(\\omega) - \\epsilon_\\infty) where \\sigma_1 \\sigma_1 is the real part and \\sigma_2 \\sigma_2 is the imaginary. As usual \\epsilon_1 \\epsilon_1 corresponds to the real dielectric and \\epsilon_2 \\epsilon_2 to the imaginary. In this calculation, \\epsilon_\\infty \\epsilon_\\infty is approximated as 1. This can be implemented in our Python script as def calculate_conductivity ( epsilon_1 , epsilon_2 , energy ): omega = energy / hbar sigma_1 = epsilon_0 * omega * epsilon_2 sigma_2 = - epsilon_0 * omega * ( epsilon_1 - epsilon_inf ) return sigma_1 , sigma_2 As in previous cases, make sure all constants are defined and any file/variable names adjusted as you implement it. Since there are 3 columns, it is easier to plot them together - we can simply repurpose our previous batch file - just make sure to change file names as appropriate. The output should look like:","title":"Conductivity"},{"location":"tutorials/Optics/Optics/#loss-function","text":"Lastly, we will examine the loss function in Si_loss_fn.dat . The 1 st column is the energy, while the 2 nd is the loss function for that energy. The header of the file shows the results of the two sum rules associated with the loss function: \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} The loss function itself is calculated rather simply from the dielectric: it is simply the imaginary component of the inverse of the complex dielectric: \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) \\text{Loss}(\\omega) = \\text{Im}\\left(\\frac{1}{\\epsilon(\\omega)}\\right) This leads to \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} \\text{Loss}(\\omega) = \\frac{\\epsilon_2(\\omega)}{\\epsilon_1(\\omega)^2 + \\epsilon_2(\\omega)^2} Let's implement this into our Python script by changing the function to def calculate_property ( epsilon_1 , epsilon_2 ): loss_function = epsilon_2 / ( epsilon_1 ** 2 + epsilon_2 ** 2 ) return loss_function Plotting it together with Si_loss_fn.dat on xmgrace gives us the graph","title":"Loss Function"},{"location":"tutorials/Optics/Optics/#changing-parameters","text":"Now that we know what Optados optics does and how it works, let's try changing some parameters in the Optados input file Si.odi , and re-running Optados, to see what effects it has.","title":"Changing Parameters"},{"location":"tutorials/Optics/Optics/#jdos-parameters","text":"First let's have a look at the effect of changing the line JDOS_MAX_ENERGY : 30 . We'll set it to 10 and 100 and plot Si_epsilon.agr using xmgrace. Doing it for 10 gives the graph while 100 gives us You can also compare with the result for 30 . What you should notice is that all the plots are the same - what this does is change the maximum energy it calculates the optical properties up to. The graphs aren't particularly interesting (you could do a higher max energy calculation and just set WORLD XMAX 10 to see it up to 10eV for example), but it does affect the results of the sum rules - which are in headers and thus not seen in graphs. Let's try seeing the results for JDOS_MAX_ENERGY : 2, 5, 10, 30 and 100. In Si_epsilon.dat the sum rule results for the different max energies should be around as follows: JDOS Max E Sum Rule Result 2 1.58E-6 5 4.40 10 6.42 30 7.09 100 7.11 This tells us that at 2eV barely any electrons contribute to the absorption process, at 5eV over half do, and beyond that slowly increasing amounts do. Most electrons seem to act for energies between 2 and 30eV. Meanwhile, the results of the 1 st and 2 nd sum rules in Si_loss_fn look rather different: JDOS Max E Sum Rule 1 Sum Rule 2 2 1.58E-6 2.18E-5 5 4.25E-3 1.54E-2 10 7.07E-2 7.58E-2 30 7.08 1.46 100 7.10 1.46 Here the 1 st rule seems to shoot up much more drastically and in a different region (between 10 and 30eV), while the 2 nd tends towards a different value, and again shoots up faster and in the same region. Now we'll take a look at the effects of changing the JDOS_SPACING value. Let's change JDOS_SPACING : 0.01 to 1 and 0.001. We'll do this for JDOS_MAX_ENERGY : 30 . For 1 the graph looks like while for 0.001 it looks like As we see here, changing JDOS_SPACING simply affects the frequency of the sampling: the smaller the value, the smaller the energy intervals at which it examines the dielectric function and thus the smoother the curve. You may note that the graphs look the same as the when we first did it with the default 0.01 above - 0.01 is sufficient, and increasing the sampling frequency gives us virtually the same results but slower. This is reflected in the sum rule calculations - the higher the spacing, the more rough of an estimate they are, and that typically leads to them being larger, with it not getting much more accurate being 0.01. JDOS Spacing Epsilon Sum Loss Sum 1 Loss Sum 2 0.001 6.73 6.72 1.50 0.01 6.74 6.73 1.50 1 8.28 7.22 1.39","title":"JDOS Parameters"},{"location":"tutorials/Optics/Optics/#loss-function-broadening","text":"Additional broadening can be included in the calculation of the loss function. This is done by setting the keyword optics_lossfn_broadening in the odi file to a non-zero value. To have a look at what it does, let's set optics_lossfn_broadening : 1 and rerun Optados. The only files that are different are the Si_loss_fn.dat and .agr files - they now contain a 3 rd column. The 1 st is still energy, the 2 nd is the unbroadened spectrum (the same result as when we did it above ), and the 3 rd is the broadened spectrum. Plotting thr agr file using xmgrace gives us this graph: Broadening it has effectively \"smoothed out\" the curve, and the agr file has the unbroadened results for comparison.","title":"Loss Function Broadening"},{"location":"tutorials/Optics/Optics_aluminium/","text":"Optics - Aluminium In this tutorial, we will have brief look at how to calculate the optical properties of metals, looking at aluminium in particular, and how the results are different from a standard Optados optics calculation. It is highly recommended that you first go through the previous tutorial , where we go more into depth on it - this tutorial is mostly just highlighting how it is slightly different for metals. We will use the cell file Al.cell %BLOCK LATTICE_CART 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Al 0.0000000000000000 0.0000000000000000 0.0000000000000000 Al 0.5000000000000000 0.5000000000000000 0.0000000000000000 Al 0.5000000000000000 0.0000000000000000 0.5000000000000000 Al 0.0000000000000000 0.5000000000000000 0.5000000000000000 %ENDBLOCK POSITIONS_FRAC KPOINTS_MP_GRID 15 15 15 SPECTRAL_KPOINTS_MP_GRID 15 15 15 SYMMETRY_GENERATE and param file Al.param TASK : SPECTRAL SPECTRAL_TASK : optics NEXTRA_BANDS : 10 Run Castep as usual. Then run Optados with the Optados input file Al.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 OPTICS_INTRABAND : true EFERMI : optados DOS_SPACING : 0.1 ADAPTIVE_SMEARING : 0.8 BROADENING : adaptive # Default OPTICS_GEOM : polycrystalline # Default There is 1 key difference to before: it contains the line OPTICS_INTRABAND : true . This is to include the intraband contribution, which is necessary for metals. We're starting with the high spacing so we get few results (measuring only at 3 energies) - this makes it easier to have a quick look at what's going on. We will use those results for the remainder of the tutorial. Dielectric Dat File The file Al_epsilon.dat contains the following data: 0.0000000000000000 2.1445746376579851 0.0000000000000000 15.000000000000000 1.1673581523361172 1.6007294583641971 30.000000000000000 0.66031465886470098 0.39432835642313052 0.0000000000000000 -32490.319172606654 NaN 15.000000000000000 0.37438389209757406 2.7452531094084771E-003 30.000000000000000 0.84359371433743857 3.4316159432482577E-004 0.0000000000000000 -32489.174597968995 NaN 15.000000000000000 0.54174204443369112 1.6034747114736059 30.000000000000000 0.50390837320213944 0.39467151801745531 You can see here that there are 3 columns like before (energy, real and imaginary dielectric), but there's 3 separate sets of them, separated by a double space. The 1 st set corresponds to the interband contribution, the 2 nd to the intraband, and the 3 rd to the total. Though normally it'd be easiest to visualise this data by plotting the agr file on xmgrace, this would only give the interband term - if you're interested in other information you will have to use the .dat file. You may choose to use/plot this data in your preferred method, but this tutorial will give you the necessary files to plot it using xmgrace. Firstly, we will create a new file called Al_epsilon_sep.dat file that turns separates the data into columns - we can do that with this Python script . The output file looks like 0.0000000000000000 2.1445746376579851 0.0000000000000000 -32490.3191726066543197 0.0000000000000000 -32489.1745979689949309 0.0000000000000000 15.0000000000000000 1.1673581523361172 1.6007294583641971 0.3743838920975741 0.0027452531094085 0.5417420444336911 1.6034747114736059 30.0000000000000000 0.6603146588647010 0.3943283564231305 0.8435937143374386 0.0003431615943248 0.5039083732021394 0.3946715180174553 It's exactly the same data except all the data is in separate columns now: 1 is still energy, 2 is interband real, 3 is interband imaginary, 4 is intraband real, 5 is intraband imaginary, 6 is total real and 7 is total imaginary dielectric. Now let's make a graph of more useful data: rerun Optados with JDOS_SPACING : 0.01 set instead (to get more data for more meaningful graphs), and rerun the Python script. You could plot it with xmgrace (and using any accompanying batch files as you wish), but it is more convenient to plot it using plotly (and Bokeh to add a bit more functionality) - this is because the values vary greatly. To replicate this, you may use this Python script to use plotly to get a basic output, and to get 1 with a bit of extra functionality (such as being able to manually select the range of values to look at) use this script . Make sure you have all the required libraries installed if doing this: pandas and plotly are required for the 1 st , and Bokeh is also required for the 2 nd . The 1 st generates an output HTML file called interactive_graph.html and the 2 nd generates interactive_graph_extra.html . The latter is embedded here for your convenience: document.addEventListener(\"DOMContentLoaded\", function() { var basePath = window.location.origin; var iframe = document.getElementById(\"embed_link\"); iframe.src = basePath + \"/tutorials/Optics/interactive_graph_extra.html\"; }); Alternatively download the data and HTML file and view it on your browser - or just view that HTML link on a new tab. As loaded, the graph doesn't look great: because the values become extremely high towards 0eV, it just looks like 2 straight lines followed by 0. In the HTML, let's set the y min to -10 and y max to 10. Now we can make some general observations. At very low energies, the total dielectric (both real and imaginary) shoot up/down to extremely large values - it seems to settle down around 2eV The imaginary components tend towards 0, while the real parts tend towards a non-zero finite value Try setting x min to 2 (and y min to -50 - just to get no cut-offs): you'll see that the lines are fairly straightforward beyond 2eV. So let's try examine in more detail what is happening between 0 and 2eV. Feel free to drag and (box)-zoom with the widgets provided in the HTML to look at different sections of the graph. Try looking at the region where energy (x) is between 1.3 and 1.6 - you should see that there is a distinct discontinuity there - while the intraband imaginary term remains close to 0, the interband jumps up (up to around 700) and then goes down - the total is the same. The real part also follows the of shape of the interband contribution, being adjusted slightly by a barely-changing intraband term. Try having a look at other regions in the 0-2eV range to see what else you can find. Other files Running Optados generates the same files as without its contribution, except some of the files are slightly different different. For example, the file Al_epsilon.agr only contains the interband term - it only has 2 columns. Similarly to Al_epsilon.dat , Al_loss_fn.dat contains the interband, intraband and total loss function (though this time the components aren't separated by a double space - you'd have to adjust the Python script used before). Unlike epsilon , the Al_loss_fn.agr file contains all the terms - you can plot all the loss function data easily using xmgrace Al_loss_fn.agr The graph should look a bit like For the loss function, you could also include optics_lossfn_broadening : x where x is the value of broadening you wish to use: this will generate a 4 th column containing the broadened total loss function (again well-included in the agr file) If you change the Optados input file to find the tensor properties - which can be done by changing the line OPTICS_GEOM : POLYCRYSTALLINE to OPTICS_GEOM : TENSOR in Al.odi - you'll also get all the contributions in the outputted Al_epsilon.dat file - so you have 3 parts of 6 components, leading to 18 bits of data in total. Only the dielectric dat output is created.","title":"Optics - Aluminium"},{"location":"tutorials/Optics/Optics_aluminium/#optics-aluminium","text":"In this tutorial, we will have brief look at how to calculate the optical properties of metals, looking at aluminium in particular, and how the results are different from a standard Optados optics calculation. It is highly recommended that you first go through the previous tutorial , where we go more into depth on it - this tutorial is mostly just highlighting how it is slightly different for metals. We will use the cell file Al.cell %BLOCK LATTICE_CART 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 0.000000000000000 0.000000000000000 0.000000000000000 4.050000000000000 %ENDBLOCK LATTICE_CART %BLOCK POSITIONS_FRAC Al 0.0000000000000000 0.0000000000000000 0.0000000000000000 Al 0.5000000000000000 0.5000000000000000 0.0000000000000000 Al 0.5000000000000000 0.0000000000000000 0.5000000000000000 Al 0.0000000000000000 0.5000000000000000 0.5000000000000000 %ENDBLOCK POSITIONS_FRAC KPOINTS_MP_GRID 15 15 15 SPECTRAL_KPOINTS_MP_GRID 15 15 15 SYMMETRY_GENERATE and param file Al.param TASK : SPECTRAL SPECTRAL_TASK : optics NEXTRA_BANDS : 10 Run Castep as usual. Then run Optados with the Optados input file Al.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 30 OPTICS_INTRABAND : true EFERMI : optados DOS_SPACING : 0.1 ADAPTIVE_SMEARING : 0.8 BROADENING : adaptive # Default OPTICS_GEOM : polycrystalline # Default There is 1 key difference to before: it contains the line OPTICS_INTRABAND : true . This is to include the intraband contribution, which is necessary for metals. We're starting with the high spacing so we get few results (measuring only at 3 energies) - this makes it easier to have a quick look at what's going on. We will use those results for the remainder of the tutorial.","title":"Optics - Aluminium"},{"location":"tutorials/Optics/Optics_aluminium/#dielectric-dat-file","text":"The file Al_epsilon.dat contains the following data: 0.0000000000000000 2.1445746376579851 0.0000000000000000 15.000000000000000 1.1673581523361172 1.6007294583641971 30.000000000000000 0.66031465886470098 0.39432835642313052 0.0000000000000000 -32490.319172606654 NaN 15.000000000000000 0.37438389209757406 2.7452531094084771E-003 30.000000000000000 0.84359371433743857 3.4316159432482577E-004 0.0000000000000000 -32489.174597968995 NaN 15.000000000000000 0.54174204443369112 1.6034747114736059 30.000000000000000 0.50390837320213944 0.39467151801745531 You can see here that there are 3 columns like before (energy, real and imaginary dielectric), but there's 3 separate sets of them, separated by a double space. The 1 st set corresponds to the interband contribution, the 2 nd to the intraband, and the 3 rd to the total. Though normally it'd be easiest to visualise this data by plotting the agr file on xmgrace, this would only give the interband term - if you're interested in other information you will have to use the .dat file. You may choose to use/plot this data in your preferred method, but this tutorial will give you the necessary files to plot it using xmgrace. Firstly, we will create a new file called Al_epsilon_sep.dat file that turns separates the data into columns - we can do that with this Python script . The output file looks like 0.0000000000000000 2.1445746376579851 0.0000000000000000 -32490.3191726066543197 0.0000000000000000 -32489.1745979689949309 0.0000000000000000 15.0000000000000000 1.1673581523361172 1.6007294583641971 0.3743838920975741 0.0027452531094085 0.5417420444336911 1.6034747114736059 30.0000000000000000 0.6603146588647010 0.3943283564231305 0.8435937143374386 0.0003431615943248 0.5039083732021394 0.3946715180174553 It's exactly the same data except all the data is in separate columns now: 1 is still energy, 2 is interband real, 3 is interband imaginary, 4 is intraband real, 5 is intraband imaginary, 6 is total real and 7 is total imaginary dielectric. Now let's make a graph of more useful data: rerun Optados with JDOS_SPACING : 0.01 set instead (to get more data for more meaningful graphs), and rerun the Python script. You could plot it with xmgrace (and using any accompanying batch files as you wish), but it is more convenient to plot it using plotly (and Bokeh to add a bit more functionality) - this is because the values vary greatly. To replicate this, you may use this Python script to use plotly to get a basic output, and to get 1 with a bit of extra functionality (such as being able to manually select the range of values to look at) use this script . Make sure you have all the required libraries installed if doing this: pandas and plotly are required for the 1 st , and Bokeh is also required for the 2 nd . The 1 st generates an output HTML file called interactive_graph.html and the 2 nd generates interactive_graph_extra.html . The latter is embedded here for your convenience: document.addEventListener(\"DOMContentLoaded\", function() { var basePath = window.location.origin; var iframe = document.getElementById(\"embed_link\"); iframe.src = basePath + \"/tutorials/Optics/interactive_graph_extra.html\"; }); Alternatively download the data and HTML file and view it on your browser - or just view that HTML link on a new tab. As loaded, the graph doesn't look great: because the values become extremely high towards 0eV, it just looks like 2 straight lines followed by 0. In the HTML, let's set the y min to -10 and y max to 10. Now we can make some general observations. At very low energies, the total dielectric (both real and imaginary) shoot up/down to extremely large values - it seems to settle down around 2eV The imaginary components tend towards 0, while the real parts tend towards a non-zero finite value Try setting x min to 2 (and y min to -50 - just to get no cut-offs): you'll see that the lines are fairly straightforward beyond 2eV. So let's try examine in more detail what is happening between 0 and 2eV. Feel free to drag and (box)-zoom with the widgets provided in the HTML to look at different sections of the graph. Try looking at the region where energy (x) is between 1.3 and 1.6 - you should see that there is a distinct discontinuity there - while the intraband imaginary term remains close to 0, the interband jumps up (up to around 700) and then goes down - the total is the same. The real part also follows the of shape of the interband contribution, being adjusted slightly by a barely-changing intraband term. Try having a look at other regions in the 0-2eV range to see what else you can find.","title":"Dielectric Dat File"},{"location":"tutorials/Optics/Optics_aluminium/#other-files","text":"Running Optados generates the same files as without its contribution, except some of the files are slightly different different. For example, the file Al_epsilon.agr only contains the interband term - it only has 2 columns. Similarly to Al_epsilon.dat , Al_loss_fn.dat contains the interband, intraband and total loss function (though this time the components aren't separated by a double space - you'd have to adjust the Python script used before). Unlike epsilon , the Al_loss_fn.agr file contains all the terms - you can plot all the loss function data easily using xmgrace Al_loss_fn.agr The graph should look a bit like For the loss function, you could also include optics_lossfn_broadening : x where x is the value of broadening you wish to use: this will generate a 4 th column containing the broadened total loss function (again well-included in the agr file) If you change the Optados input file to find the tensor properties - which can be done by changing the line OPTICS_GEOM : POLYCRYSTALLINE to OPTICS_GEOM : TENSOR in Al.odi - you'll also get all the contributions in the outputted Al_epsilon.dat file - so you have 3 parts of 6 components, leading to 18 bits of data in total. Only the dielectric dat output is created.","title":"Other files"},{"location":"tutorials/Optics/Optics_ani/","text":"Optics Optados is capable of getting numerous optical properties of different structures, all of which depend on the wavelength (energy) of light interacting with it. In this tutorial, we will perform an Optados optics calculation on rutile (TiO 2 ) - a birefringent crystal with anisotropic optical properties, examining its single-crystal and polycrystalline (isotropic) properties. Throughout this tutorial, we will be using xmgrace to plot everything, but feel free to use your preferred software. We will use the cell file rut.cell %BLOCK LATTICE_ABC 4.6257000 4.6257000 2.9806000 90.0000000 90.0000000 90.0000000 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_FRAC Ti 0.0000000 0.0000000 0.0000000 O 0.2821000 0.2821000 0.0000000 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 This cell file was obtained using cif2cell using the structure with the COD ID 1010942, found on the Crystallography Open Database We will first run a castep calculation using the above cell with the param file rut.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 Once that is done, we can perform the optical Optados calculations. Demonstrating Birefringence We will begin by examining the dielectric tensor. We will do this by using the Opdatos input file rut.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 60 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : tensor # Default OPTICS_LOSSFN_BROADENING : 0.0 # Default The line TASK : optics is key here, as that is what tells us to perform an optical calculation. The other crucial line is OPTICS_GEOM : tensor - this tells it to calculate the full dielectric tensor of rutile. This produces 2 output files: rut.odo and rut_epsilon.dat - we are interested in the latter. The output file starts off looking like # Component 1 0.0000000000000000 10.985963719914423 0.0000000000000000 1.0001666944490749E-002 10.986133776534746 4.5560614006426980E-003 2.0003333888981498E-002 10.990669467897412 5.9329124271557589E-003 The 1 st column corresponds to energy (in eV), the 2 nd is the real part of the dielectric constant and the 3 rd is the imaginary part. The file contains 6 components, each having their own table. This is bothersome to plot, so let's use a Python script to separate it into its components separate.py input_file = 'rut_epsilon.dat' def write_to_file ( component , lines ): file_name = \"rut_tens\" + str ( component ) + \".dat\" with open ( file_name , \"w\" ) as f : f . writelines ( lines ) with open ( \"rut_tens.dat\" , \"r\" ) as f : lines = f . readlines ()[:: - 1 ] component_lines = [] component = 6 for line in lines : component_lines . append ( line ) if \"Componen\" in line : write_to_file ( component , component_lines ) component -= 1 component_lines = [] Note It is recommended to copy and do this is in a separate directory - we will be comparing this output to subsequent calculations. In future instructions this will be in the directory \"tensors\" We now have 6 files for each component of the 3x3 tensor (keep in mind that it is symmetric ie. \\epsilon_{xy} \\epsilon_{xy} = \\epsilon_{yx} \\epsilon_{yx} ). rut_tens1.dat corresponds to \\epsilon_{xx} \\epsilon_{xx} , 2 and 3 and to yy and zz, while 4, 5 and 6 correspond to xy, xz and yz. Now that we have all the components, let's start actually looking at the results. First, let's plot the real parts of \\epsilon_{xx} \\epsilon_{xx} and \\epsilon_{yy} \\epsilon_{yy} on the same graph. We can do this by using the batch file plot_12_together.bat READ BLOCK \"rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"rut_tens2.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real YY component\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" and plotting it with xmgrace via xmgrace -batch plot_12_together.bat This gives us a graph looking like this: There is only 1 line visible - they (almost) perfectly overlap, meaning that \\epsilon_{xx} \\epsilon_{xx} = \\epsilon_{yy} \\epsilon_{yy} . Now let's try comparing \\epsilon_{xx} \\epsilon_{xx} with \\epsilon_{zz} \\epsilon_{zz} - all you have to do is make the 2 nd block rut_tens3.dat (and change the legend appropriately). This is a rather interesting result: this seems that the dielectric function in different directions is different - the material is optically anisotropic. Since it is identical in 2 directions, it would be considered birefringent. Examining Dielectric Tensor So now that we have the dielectric function tensor, let's examine how this corresponds to its (anisotropic) optical properties We will run Optados again (no need to rerun Castep), changing the line OPTICS_GEOM : tensor in the rut.odi file to the lines OPTICS_GEOM : polarised # Default OPTICS_QDIR : 1 0 0 Let's compare the dielectric function output with the \\epsilon_{xx} \\epsilon_{xx} output we got from the tensor. Run xmgrace rut_epsilon.dat tensors/rut_tens1.dat We will get the same graph as the 1 st one . This is no surprise at all: if light is polarised in the xx direction, it'll effectively feel the \\epsilon_{xx} \\epsilon_{xx} dielectric function. Let's try a more interesting example - change the direction line to OPTICS_QDIR : 1 1 1 Now the result shouldn't align with anything. To demonstrate that let's compare it to \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{zz} \\epsilon_{zz} and \\epsilon_{xy} \\epsilon_{xy} , all on the same graph - luckily xmgrace makes it very easy to plot them together. We'll modify the batch file to include all of them - compare.bat READ BLOCK \"tensors/rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"tensors/rut_tens3.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real ZZ component\" READ BLOCK \"tensors/rut_tens4.dat\" BLOCK xy \"1:2\" S2 LEGEND \"Real XY component\" READ BLOCK \"rut_epsilon.dat\" BLOCK xy \"1:2\" S3 LEGEND \"1 1 1 result\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" WORLD XMAX 5 We have also made the graph smaller (only goes up to 5eV) in the last line to make it easier to see overlaps (or lack of them). This is the kind of output we get: You can try comparing it to any other value, but you'll find it's completely different. So how is this related to the tensor? Considering the properties of tensors in general, we know that the value from a tensor in any direction is given by the equation \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} Where \\epsilon' \\epsilon' is the dielectric constant in the direction of \\hat{\\mathbf{n}} \\hat{\\mathbf{n}} , and \\mathbf{\\epsilon} \\mathbf{\\epsilon} is the dielectric matrix. Note In this tutorial, a symbol being bold and underlined (like \\underline{\\mathbf{\\epsilon}} \\underline{\\mathbf{\\epsilon}} ) shows that it's a matrix, while being just bold (like \\mathbf{n} \\mathbf{n} ) shows that it's a vector. Let's quickly work through what we'd expect in the (111) direction and compare that with what we get from Optados. To get $$ \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} $$ we do \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} Then to get the final result we do \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) $$ = \\frac{1}{3} \\bigg ( \\epsilon_{xx} + \\epsilon_{yy} + \\epsilon_{zz} + 2(\\epsilon_{xy} + \\epsilon_{yz} + \\epsilon_{zx}) \\bigg ) $$ Let's check if this is true using our separated dielectric function tensor files. We will get a function that is equal to the above equation using a Python script, and plot it on the same graph as the case polarised in the (111) direction. You may use the script get_in_direction.py import numpy as np eps = { key : np . loadtxt ( f \"rut_tens { i } .dat\" ) for i , key in enumerate (( 'xx' , 'yy' , 'zz' , 'xy' , 'xz' , 'yz' ))} eps_vals = { key : val [:, 1 ] for key , val in eps . items ()} energies = eps [ 'xx' ][:, 0 ] eps_111_values = ( sum ( eps [ ind ] for ind in ( 'xx' , 'yy' , 'zz' )) + 2 * sum ( eps [ ind ] for ind in ( 'xy' , 'xz' , 'yz' )) / 3 output_data = np . column_stack (( energies , eps_111_values )) output_filename = \"rut_111_out.dat\" np . savetxt ( output_filename , output_data , fmt = ' % .16e ' , header = \"Energy (eV) Effective Epsilon_111\" ) This gives the output of the above equation acting on the dielectric function tensor we calculate, stored in rut_111.dat . Now let's see if the 2 results agree: let's try xmgrace rut_epsilon.dat tensors/rut_111_out.dat Using rut_epsilon.dat from our last Optados calculation . We should see that the lines almost perfectly overlap: Now we properly understand what is going on when choosing a certain polarisation direction, and what the dielectric function tensor truly means. Isotropic Dielectric Function There is another case to have a look at: what is the dielectric function when the material is polycrystalline, and thus behaves isotropically? Optados can easily find this by changing the keyword in the rut.odi file to OPTICS_GEOM : tensor and removing the OPTICS_QDIR line (as the direction no longer matters). If you wish to verify how this is being calculated, use the same Python script as above but change the calculation eps_111_values = ( eps [ 'xx' ] + eps [ 'yy' ] + eps [ 'zz' ] + 2 * eps [ 'xy' ] + 2 * eps [ 'xz' ] + 2 * eps [ 'yz' ]) / 3 to for i in range ( len ( energies )): tensor = np . array ([ [ eps [ 'xx' ][ i ], eps [ 'xy' ][ i ], eps [ 'xz' ][ i ]], [ eps [ 'xy' ][ i ], eps [ 'yy' ][ i ], eps [ 'yz' ][ i ]], [ eps [ 'xz' ][ i ], eps [ 'yz' ][ i ], eps [ 'zz' ][ i ]] ]) eigenvalues = np . linalg . eigvals ( tensor ) iso_value = np . mean ( eigenvalues ) iso_values . append ( eps_111_value ) and change variable, output file name etc. as appropraite output_data = np . column_stack (( energies , iso_values )) output_filename = \"rut_111_eigen.dat\" This gives us the average of the eigenvalues of the dielectric matrix for every enegy, giving us the isotropic value. Let's plot them together to see if they're identical: xmgrace rut_epsilon.dat tensors/rut_111_eigen.dat We get a graph looking like this: As expected, the 2 lines overlap: this demonstrates that the polycrystalline calculation is effectively the \"average\" of the dielectric tensor in all directions, which is what we'd expect for a polycrystalline sample, where we can assume that all directions are equally likely.","title":"Optical Anisotropy"},{"location":"tutorials/Optics/Optics_ani/#optics","text":"Optados is capable of getting numerous optical properties of different structures, all of which depend on the wavelength (energy) of light interacting with it. In this tutorial, we will perform an Optados optics calculation on rutile (TiO 2 ) - a birefringent crystal with anisotropic optical properties, examining its single-crystal and polycrystalline (isotropic) properties. Throughout this tutorial, we will be using xmgrace to plot everything, but feel free to use your preferred software. We will use the cell file rut.cell %BLOCK LATTICE_ABC 4.6257000 4.6257000 2.9806000 90.0000000 90.0000000 90.0000000 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_FRAC Ti 0.0000000 0.0000000 0.0000000 O 0.2821000 0.2821000 0.0000000 %ENDBLOCK POSITIONS_FRAC SYMMETRY_GENERATE KPOINTS_MP_GRID 10 10 10 SPECTRAL_KPOINTS_MP_GRID 14 14 14 This cell file was obtained using cif2cell using the structure with the COD ID 1010942, found on the Crystallography Open Database We will first run a castep calculation using the above cell with the param file rut.param TASK : SPECTRAL SPECTRAL_TASK : OPTICS CUT_OFF_ENERGY : 200 Once that is done, we can perform the optical Optados calculations.","title":"Optics"},{"location":"tutorials/Optics/Optics_ani/#demonstrating-birefringence","text":"We will begin by examining the dielectric tensor. We will do this by using the Opdatos input file rut.odi TASK : optics JDOS_SPACING : 0.01 JDOS_MAX_ENERGY : 60 EFERMI : optados DOS_SPACING : 0.1 BROADENING : adaptive # Default ADAPTIVE_SMEARING : 0.4 # Default OPTICS_GEOM : tensor # Default OPTICS_LOSSFN_BROADENING : 0.0 # Default The line TASK : optics is key here, as that is what tells us to perform an optical calculation. The other crucial line is OPTICS_GEOM : tensor - this tells it to calculate the full dielectric tensor of rutile. This produces 2 output files: rut.odo and rut_epsilon.dat - we are interested in the latter. The output file starts off looking like # Component 1 0.0000000000000000 10.985963719914423 0.0000000000000000 1.0001666944490749E-002 10.986133776534746 4.5560614006426980E-003 2.0003333888981498E-002 10.990669467897412 5.9329124271557589E-003 The 1 st column corresponds to energy (in eV), the 2 nd is the real part of the dielectric constant and the 3 rd is the imaginary part. The file contains 6 components, each having their own table. This is bothersome to plot, so let's use a Python script to separate it into its components separate.py input_file = 'rut_epsilon.dat' def write_to_file ( component , lines ): file_name = \"rut_tens\" + str ( component ) + \".dat\" with open ( file_name , \"w\" ) as f : f . writelines ( lines ) with open ( \"rut_tens.dat\" , \"r\" ) as f : lines = f . readlines ()[:: - 1 ] component_lines = [] component = 6 for line in lines : component_lines . append ( line ) if \"Componen\" in line : write_to_file ( component , component_lines ) component -= 1 component_lines = [] Note It is recommended to copy and do this is in a separate directory - we will be comparing this output to subsequent calculations. In future instructions this will be in the directory \"tensors\" We now have 6 files for each component of the 3x3 tensor (keep in mind that it is symmetric ie. \\epsilon_{xy} \\epsilon_{xy} = \\epsilon_{yx} \\epsilon_{yx} ). rut_tens1.dat corresponds to \\epsilon_{xx} \\epsilon_{xx} , 2 and 3 and to yy and zz, while 4, 5 and 6 correspond to xy, xz and yz. Now that we have all the components, let's start actually looking at the results. First, let's plot the real parts of \\epsilon_{xx} \\epsilon_{xx} and \\epsilon_{yy} \\epsilon_{yy} on the same graph. We can do this by using the batch file plot_12_together.bat READ BLOCK \"rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"rut_tens2.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real YY component\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" and plotting it with xmgrace via xmgrace -batch plot_12_together.bat This gives us a graph looking like this: There is only 1 line visible - they (almost) perfectly overlap, meaning that \\epsilon_{xx} \\epsilon_{xx} = \\epsilon_{yy} \\epsilon_{yy} . Now let's try comparing \\epsilon_{xx} \\epsilon_{xx} with \\epsilon_{zz} \\epsilon_{zz} - all you have to do is make the 2 nd block rut_tens3.dat (and change the legend appropriately). This is a rather interesting result: this seems that the dielectric function in different directions is different - the material is optically anisotropic. Since it is identical in 2 directions, it would be considered birefringent.","title":"Demonstrating Birefringence"},{"location":"tutorials/Optics/Optics_ani/#examining-dielectric-tensor","text":"So now that we have the dielectric function tensor, let's examine how this corresponds to its (anisotropic) optical properties We will run Optados again (no need to rerun Castep), changing the line OPTICS_GEOM : tensor in the rut.odi file to the lines OPTICS_GEOM : polarised # Default OPTICS_QDIR : 1 0 0 Let's compare the dielectric function output with the \\epsilon_{xx} \\epsilon_{xx} output we got from the tensor. Run xmgrace rut_epsilon.dat tensors/rut_tens1.dat We will get the same graph as the 1 st one . This is no surprise at all: if light is polarised in the xx direction, it'll effectively feel the \\epsilon_{xx} \\epsilon_{xx} dielectric function. Let's try a more interesting example - change the direction line to OPTICS_QDIR : 1 1 1 Now the result shouldn't align with anything. To demonstrate that let's compare it to \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{zz} \\epsilon_{zz} and \\epsilon_{xy} \\epsilon_{xy} , all on the same graph - luckily xmgrace makes it very easy to plot them together. We'll modify the batch file to include all of them - compare.bat READ BLOCK \"tensors/rut_tens1.dat\" BLOCK xy \"1:2\" S0 LEGEND \"Real XX component\" READ BLOCK \"tensors/rut_tens3.dat\" BLOCK xy \"1:2\" S1 LEGEND \"Real ZZ component\" READ BLOCK \"tensors/rut_tens4.dat\" BLOCK xy \"1:2\" S2 LEGEND \"Real XY component\" READ BLOCK \"rut_epsilon.dat\" BLOCK xy \"1:2\" S3 LEGEND \"1 1 1 result\" XAXIS LABEL \"Energy (eV)\" YAXIS LABEL \"Dielectric constant\" WORLD XMAX 5 We have also made the graph smaller (only goes up to 5eV) in the last line to make it easier to see overlaps (or lack of them). This is the kind of output we get: You can try comparing it to any other value, but you'll find it's completely different. So how is this related to the tensor? Considering the properties of tensors in general, we know that the value from a tensor in any direction is given by the equation \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} \\epsilon' = \\hat{\\mathbf{n}}^T \\cdot \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} Where \\epsilon' \\epsilon' is the dielectric constant in the direction of \\hat{\\mathbf{n}} \\hat{\\mathbf{n}} , and \\mathbf{\\epsilon} \\mathbf{\\epsilon} is the dielectric matrix. Note In this tutorial, a symbol being bold and underlined (like \\underline{\\mathbf{\\epsilon}} \\underline{\\mathbf{\\epsilon}} ) shows that it's a matrix, while being just bold (like \\mathbf{n} \\mathbf{n} ) shows that it's a vector. Let's quickly work through what we'd expect in the (111) direction and compare that with what we get from Optados. To get $$ \\underline{\\mathbf{\\epsilon}} \\hat{\\mathbf{n}} $$ we do \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\begin{pmatrix} \\epsilon_{xx} & \\epsilon_{xy} & \\epsilon_{xz} \\\\ \\epsilon_{yx} & \\epsilon_{yy} & \\epsilon_{yz} \\\\ \\epsilon_{zx} & \\epsilon_{zy} & \\epsilon_{zz} \\end{pmatrix} \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 \\\\ 1 \\\\ 1 \\end{pmatrix} = \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} Then to get the final result we do \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) \\frac{1}{\\sqrt3} \\begin{pmatrix} \\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz} \\\\ \\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz} \\\\ \\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz} \\end{pmatrix} \\cdot \\frac{1}{\\sqrt3} \\begin{pmatrix} 1 & 1 & 1 \\end{pmatrix} = \\frac{1}{3} \\bigg((\\epsilon_{xx} + \\epsilon_{xy} + \\epsilon_{xz}) + (\\epsilon_{yx} + \\epsilon_{yy} + \\epsilon_{yz}) + (\\epsilon_{zx} + \\epsilon_{zy} + \\epsilon_{zz}) \\bigg) $$ = \\frac{1}{3} \\bigg ( \\epsilon_{xx} + \\epsilon_{yy} + \\epsilon_{zz} + 2(\\epsilon_{xy} + \\epsilon_{yz} + \\epsilon_{zx}) \\bigg ) $$ Let's check if this is true using our separated dielectric function tensor files. We will get a function that is equal to the above equation using a Python script, and plot it on the same graph as the case polarised in the (111) direction. You may use the script get_in_direction.py import numpy as np eps = { key : np . loadtxt ( f \"rut_tens { i } .dat\" ) for i , key in enumerate (( 'xx' , 'yy' , 'zz' , 'xy' , 'xz' , 'yz' ))} eps_vals = { key : val [:, 1 ] for key , val in eps . items ()} energies = eps [ 'xx' ][:, 0 ] eps_111_values = ( sum ( eps [ ind ] for ind in ( 'xx' , 'yy' , 'zz' )) + 2 * sum ( eps [ ind ] for ind in ( 'xy' , 'xz' , 'yz' )) / 3 output_data = np . column_stack (( energies , eps_111_values )) output_filename = \"rut_111_out.dat\" np . savetxt ( output_filename , output_data , fmt = ' % .16e ' , header = \"Energy (eV) Effective Epsilon_111\" ) This gives the output of the above equation acting on the dielectric function tensor we calculate, stored in rut_111.dat . Now let's see if the 2 results agree: let's try xmgrace rut_epsilon.dat tensors/rut_111_out.dat Using rut_epsilon.dat from our last Optados calculation . We should see that the lines almost perfectly overlap: Now we properly understand what is going on when choosing a certain polarisation direction, and what the dielectric function tensor truly means.","title":"Examining Dielectric Tensor"},{"location":"tutorials/Optics/Optics_ani/#isotropic-dielectric-function","text":"There is another case to have a look at: what is the dielectric function when the material is polycrystalline, and thus behaves isotropically? Optados can easily find this by changing the keyword in the rut.odi file to OPTICS_GEOM : tensor and removing the OPTICS_QDIR line (as the direction no longer matters). If you wish to verify how this is being calculated, use the same Python script as above but change the calculation eps_111_values = ( eps [ 'xx' ] + eps [ 'yy' ] + eps [ 'zz' ] + 2 * eps [ 'xy' ] + 2 * eps [ 'xz' ] + 2 * eps [ 'yz' ]) / 3 to for i in range ( len ( energies )): tensor = np . array ([ [ eps [ 'xx' ][ i ], eps [ 'xy' ][ i ], eps [ 'xz' ][ i ]], [ eps [ 'xy' ][ i ], eps [ 'yy' ][ i ], eps [ 'yz' ][ i ]], [ eps [ 'xz' ][ i ], eps [ 'yz' ][ i ], eps [ 'zz' ][ i ]] ]) eigenvalues = np . linalg . eigvals ( tensor ) iso_value = np . mean ( eigenvalues ) iso_values . append ( eps_111_value ) and change variable, output file name etc. as appropraite output_data = np . column_stack (( energies , iso_values )) output_filename = \"rut_111_eigen.dat\" This gives us the average of the eigenvalues of the dielectric matrix for every enegy, giving us the isotropic value. Let's plot them together to see if they're identical: xmgrace rut_epsilon.dat tensors/rut_111_eigen.dat We get a graph looking like this: As expected, the 2 lines overlap: this demonstrates that the polycrystalline calculation is effectively the \"average\" of the dielectric tensor in all directions, which is what we'd expect for a polycrystalline sample, where we can assume that all directions are equally likely.","title":"Isotropic Dielectric Function"},{"location":"tutorials/Tools/elastic_constants/","text":"Andrew Walker (building on work by Dan Wilson) provides some python scripts for calculating elastic constants using CASTEP, available from https://github.com/andreww/elastic-constants . The tool comes in two parts - first is generate_strain.py, this takes the results of a successful variable cell geometry optimisation and creates a set of input files to be run through CASTEP. The second part is elastics.py, which takes the CASTEP results and constructs the matrix of elastic constants, Young's modulus, Poisson's ratios and bulk and shear moduli. Usage information for each script can be obtained by using the --help option. For this exercise we will use rutile - titanium dioxide. Below are example .cell and .param files to start from. It is assumed that the scripts generate_strain.py and elastics.py are in your PATH and that python is installed. #TiO2.cell %BLOCK lattice_cart 4.594 0.000 0.000 0.000 4.594 0.000 0.000 0.000 2.959 %ENDBLOCK lattice_cart %BLOCK positions_frac Ti 0.000 0.000 0.000 Ti 0.500 0.500 0.500 O 0.305 0.305 0.000 O -0.305 -0.305 0.000 O 0.805 0.195 0.500 O -0.805 -0.195 0.500 %ENDBLOCK positions_frac symmetry_generate kpoint_mp_grid 3 3 3 #TiO2.param task : geometryoptimisation cutoff_energy : 700 eV xc_functional : PBE max_scf_cycles : 100 calculate_stress : true opt_strategy : speed num_dump_cycles : 0 Task 1: Perform a variable cell geometry optimisation and make sure to include calculate_stress : true in your param file. Test the kinetic energy cut-off and k-point grid such that the stress is converged to within the default geom_stress_tol value. (Hint: Use CASTEP's built-in help utility to find the default.) Task 2: Use the generate_strain.py script to generate a set of .cell files deformed according to the appropriate strain pattern. The command generate_strain.py TiO2 should be sufficient. You should now have twelve (in this case) sets of input files - individual .cell files and corresponding .param , symbolically linked to the original TiO2.param file. Notice that the new .cell files all have the FIX_ALL_CELL true option set. Task 3: Run CASTEP on each of the 12 sets of input files. Note that the cell distortions can break the symmetry of the crystal, hence changing the number of k-points in the symmetry reduced sample. The -dryrun option of CASTEP can be used to do a quick check for how many k-points are required. This can help when selecting how many cores to run the calculation on if you are running CASTEP in parallel. Task 4: Run the elastics.py script to obtain the elastic constants. The command elastics.py TiO2 will print the results to the terminal. The --latex option generates a LaTeX formatted summary of the results and the --graphics option produces a graphical representation of the stress-strain fits in a .png file. Task 5: Investigate how the results and their errors change with smaller values of the elec_energy_tol parameter. Also investigate the effect of changing the --strain option to generate_strain.py . Move any old *cij*.castep files to another directory - the elastics.py script only checks the first set of data in a concatenated .castep file.","title":"Elastic Constants"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/","text":"Interlayer binding energy of graphite Here we'll explore the van der Waals interaction that holds sheets of graphene together to form graphite. We will see how a standard semi-local density functional approximation fails to predict the correct interlayer binding energy in graphite and how we can do better using semi-empirical dispersion corrections in CASTEP. For this tutorial we will use the CASTEP-ASE interface to setup and run many short calculations and analyse the results, though you can of course adapt the content here to use a scripting language of your choice. I have broken up the parts of the script to add clarification in places, but you can download the jupyter notebook with all the cells here . We start by importing several python libraries. For more information on using the atomic simulation environment (ASE) with CASTEP, see the documentation here . # ASE version 3.23 from ase.io import read , write from ase.calculators.castep import Castep from ase.io.castep import read_seed from ase.visualize import view # pandas version 1.3.4 import pandas as pd # castep.mpi on path already, version 24.1 castep_cmd = 'mpirun -n 4 castep.mpi' # plotting from matplotlib import pyplot as plt % matplotlib inline # Python version: 3.9.5 The CASTEP-ASE interface returns the 'Final energy' from the .castep file, though for this tutorial we will actually want the dispersion-corrected energy. The function below reads the .castep file and extracts the dispersion-corrected final energy. def extract_dispersion_corrected_energy ( file_path ): \"\"\" Extracts the dispersion corrected final energy from a .castep file. Parameters: file_path (str): Path to the .castep file. Returns: float: The extracted energy value in eV. \"\"\" energy = None with open ( file_path , 'r' ) as file : lines = file . readlines () # Iterate over the lines in reverse order to find the last occurrence for line in reversed ( lines ): if \"Dispersion corrected final energy\" in line : energy = float ( line . split ()[ - 2 ]) break if energy is None : raise ValueError ( \"Energy not found in the file.\" ) return energy For this tutorial I will use CASTEP version 24.1. See here for a list of the different dispersion correction schemes and which version of CASTEP they are available from. Separation of layers: setup and run the calculations The script below loops over several different dispersion corrections schemes and, for each one, calculates the total energy of a 4-atom graphite cell at several different values of the c lattice constant. This effectively increases the interlayer spacing between the sheets of graphene. By separating them far enough apart, we can estimate the interlayer binding energy predicted by each method. The script took about 10 minutes to run using 4 cores on a relatively powerful laptop. You can decrease the k-point sampling or basis set precision, or loop over fewer methods or c parameters in order to speed things up. # run in this directory directory = 'separate-layers-tutorial/' # k-point grid -- not converged! kpts = [ 13 , 13 , 5 ] # xc functional to use xc = 'PBE' # range of unit c parameters in Angstroms (interlayer spacings are half these!) crange = [ 4 , 5 , 6 , 6.25 , 6.5 , 6.75 , 7 , 7.25 , 7.5 , 8.5 , 10 , 14 , 16 ] #SEDC correction schemes to try: schemes = [ '' , 'G06' , 'D3' , 'D3-BJ' , 'D4' , 'TS' , 'MBD' , 'XDM' ] # pandas dataframe to store the results df = pd . DataFrame ({ 'crange' : crange }) # loop over the different correction schemes for sedc_scheme in schemes : print ( ' \\n ' , 50 * '=' ) print ( f ' { xc } + { sedc_scheme } \\n ' ) # list to temporarily hold the total energy for each calculation energies = [] # loop over c parameters: for c in crange : label = f ' { xc } - { sedc_scheme } - { c : 3.2f } ' try : graphite = read_seed ( directory + label ) except : # if the calculation doesn't already exist, we set it up and # run it # read in cif file (taken from here: https://materialsproject.org/materials/mp-48 ) graphite = read ( 'C_mp-48_primitive.cif' ) # For CASTEP < 24.1 we might need a supercell to get more accurate results # for TS, MBD and XDM schemes that rely on Hirshfeld charges. # graphite = graphite * (3,3,1) # scale c parameter to new value cellpar = graphite . cell . cellpar () cellpar [ 2 ] = c graphite . set_cell ( cellpar , scale_atoms = True ) # set up castep calculator calc = Castep ( kpts = kpts , label = label , castep_command = castep_cmd , directory = directory , _rename_existing_dir = False , # allows us to write all these calculations to the same directory... ) calc . param . xc_functional = xc calc . param . basis_precision = 'precise' # switch to something cheaper (e.g. FINE) to speed things up for this example.. calc . param . write_checkpoint = 'None' # don't need the checkpoint files now calc . param . write_cst_esp = False # don't need the electrostatic potential file now calc . param . write_bands = False # don't need the bands file now calc . cell . symmetry_generate = True # use symmetry to speed up the calculation calc . cell . snap_to_symmetry = True # enforce symmetry # Switch on the SEDC flags if sedc_scheme != '' : calc . param . sedc_apply = True calc . param . sedc_scheme = sedc_scheme # For the XDM scheme we need to set this manually # otherwise the calculation crashes... if sedc_scheme == 'XDM' : calc . param . SEDC_SC_XDM = 1.0 graphite . calc = calc e = graphite . get_potential_energy () # If a SEDC scheme is used, # we need to extract the dispersion corrected energy if sedc_scheme != '' : e = extract_dispersion_corrected_energy ( directory + label + '.castep' ) energies . append ( e ) print ( f ' { c : 8.3f } A \\t { e : 12.8f } eV' ) # save the energy wrt to furthest energy: energies = [ e - energies [ - 1 ] for e in energies ] df [ f ' { xc } - { sedc_scheme } ' ] = energies # Save to a .csv file: df . to_csv ( 'graphite_layer_separation.csv' ) The .param files generated look something like this: WRITE_CST_ESP: FALSE WRITE_BANDS: FALSE WRITE_CHECKPOINT: None XC_FUNCTIONAL: PBE SEDC_APPLY: TRUE SEDC_SCHEME: D3 # or TS or D3-BJ etc. BASIS_PRECISION: precise The task defaults to SINGLEPOINT (which is what we want in this case). The .cell files simply have the crystal structure in which the cell is scaled in the c direction. Read in and analyse the results We can now read in and analyse the results from the previous step. Reading the data into a pandas dataframe object is convenient. df = pd . read_csv ( './graphite_layer_separation.csv' ) # scale by 1000 / 4 to get the energies per atom and in units of meV dfdiff = ( df . iloc [:, 1 :]) * 1000 / 4 # energy per atom in meV # the c parmeter is 2x the interlayer spacing, d dfdiff [ 'c/2' ] = df [ 'crange' ] / 2 styles = [ f ' { m } -' for m in [ \"o\" , \"v\" , \"^\" , \"s\" , \"H\" , \"+\" , \"x\" , \"D\" ]] # compared to this reference (and many others!) https://doi.org/10.1039/C3RA47187J ax = dfdiff . plot ( x = 'c/2' , y = [ 'PBE-' , 'PBE-G06' , 'PBE-D3' , 'PBE-D3-BJ' , 'D4' , 'PBE-TS' , 'PBE-MBD' , 'PBE-XDM' ], ylabel = 'energy/atom (meV)' , ylim = ( - 100 , 80 ), xlabel = r 'interlayer spacing d ( = c/2) (${\\AA}$)' , figsize = ( 16 , 10 ), style = styles , ) ax . axhline ( 0 , color = '0.3' ) ax . axvline ( 3.355 , ls = '--' , color = '0.4' ) # Experimental binding energies reported shown in the figure are 31 \u00b1 2, 43, 52 \u00b1 5 and 35 (+15 to \u201310) meV per atom ax . axhspan ( ymin =- 57 , ymax =- 25 , color = '0.8' , alpha = 0.5 ) ax . set_title ( 'graphite interlayer binding energy' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.pdf' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.png' , dpi = 300 ) which produces the following figure: Fig1. Graphite interlayer binding energy using the PBE XC functional with various dispersion corrections. The dashed vertical line is the experimental interlayer spacing and the shaded grey region is the range of experimentally obtained interlayer binding energies. Please note that these are not fully converged calculations and so do not represent the actual performance of these methods but is simply a guide for how to use them with CASTEP. We can see that the plain PBE functional severely underestimates the binding energy of graphite and that many of the dispersion-corrected results are in much better agreement. The TS scheme strongly overbinds graphite, but has been found to be accurate for other types of systems. Testing such methods carefully is always required when you encounter a new system. Further suggestions For the D3 and D3-BJ methods, try to switch on the three-body interaction term by setting: %BLOCK devel_code d3_threebody TRUE %ENDBLOCK devel_code in the .param file. What effect does this have on the interlayer binding energy in graphite? (You may also want to set IPRINT = 2 to see more information about the dispersion correction parameters.) Compare to other XC functionals with and without the dispersion corrections (though note that of the corrections are only parameterised for a few functionals .) For CASTEP < 24.1 we get a warning for the TS, MBD and XDM schemes about the unit cell being too small for accurate corrections. If you get this warning, try repeating the above calculations for these three methods using a larger supercell to see what the effect is and what sized supercell you would need to converge the dispersion correction.","title":"Dispersion corrections"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#interlayer-binding-energy-of-graphite","text":"Here we'll explore the van der Waals interaction that holds sheets of graphene together to form graphite. We will see how a standard semi-local density functional approximation fails to predict the correct interlayer binding energy in graphite and how we can do better using semi-empirical dispersion corrections in CASTEP. For this tutorial we will use the CASTEP-ASE interface to setup and run many short calculations and analyse the results, though you can of course adapt the content here to use a scripting language of your choice. I have broken up the parts of the script to add clarification in places, but you can download the jupyter notebook with all the cells here . We start by importing several python libraries. For more information on using the atomic simulation environment (ASE) with CASTEP, see the documentation here . # ASE version 3.23 from ase.io import read , write from ase.calculators.castep import Castep from ase.io.castep import read_seed from ase.visualize import view # pandas version 1.3.4 import pandas as pd # castep.mpi on path already, version 24.1 castep_cmd = 'mpirun -n 4 castep.mpi' # plotting from matplotlib import pyplot as plt % matplotlib inline # Python version: 3.9.5 The CASTEP-ASE interface returns the 'Final energy' from the .castep file, though for this tutorial we will actually want the dispersion-corrected energy. The function below reads the .castep file and extracts the dispersion-corrected final energy. def extract_dispersion_corrected_energy ( file_path ): \"\"\" Extracts the dispersion corrected final energy from a .castep file. Parameters: file_path (str): Path to the .castep file. Returns: float: The extracted energy value in eV. \"\"\" energy = None with open ( file_path , 'r' ) as file : lines = file . readlines () # Iterate over the lines in reverse order to find the last occurrence for line in reversed ( lines ): if \"Dispersion corrected final energy\" in line : energy = float ( line . split ()[ - 2 ]) break if energy is None : raise ValueError ( \"Energy not found in the file.\" ) return energy For this tutorial I will use CASTEP version 24.1. See here for a list of the different dispersion correction schemes and which version of CASTEP they are available from.","title":"Interlayer binding energy of graphite"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#separation-of-layers-setup-and-run-the-calculations","text":"The script below loops over several different dispersion corrections schemes and, for each one, calculates the total energy of a 4-atom graphite cell at several different values of the c lattice constant. This effectively increases the interlayer spacing between the sheets of graphene. By separating them far enough apart, we can estimate the interlayer binding energy predicted by each method. The script took about 10 minutes to run using 4 cores on a relatively powerful laptop. You can decrease the k-point sampling or basis set precision, or loop over fewer methods or c parameters in order to speed things up. # run in this directory directory = 'separate-layers-tutorial/' # k-point grid -- not converged! kpts = [ 13 , 13 , 5 ] # xc functional to use xc = 'PBE' # range of unit c parameters in Angstroms (interlayer spacings are half these!) crange = [ 4 , 5 , 6 , 6.25 , 6.5 , 6.75 , 7 , 7.25 , 7.5 , 8.5 , 10 , 14 , 16 ] #SEDC correction schemes to try: schemes = [ '' , 'G06' , 'D3' , 'D3-BJ' , 'D4' , 'TS' , 'MBD' , 'XDM' ] # pandas dataframe to store the results df = pd . DataFrame ({ 'crange' : crange }) # loop over the different correction schemes for sedc_scheme in schemes : print ( ' \\n ' , 50 * '=' ) print ( f ' { xc } + { sedc_scheme } \\n ' ) # list to temporarily hold the total energy for each calculation energies = [] # loop over c parameters: for c in crange : label = f ' { xc } - { sedc_scheme } - { c : 3.2f } ' try : graphite = read_seed ( directory + label ) except : # if the calculation doesn't already exist, we set it up and # run it # read in cif file (taken from here: https://materialsproject.org/materials/mp-48 ) graphite = read ( 'C_mp-48_primitive.cif' ) # For CASTEP < 24.1 we might need a supercell to get more accurate results # for TS, MBD and XDM schemes that rely on Hirshfeld charges. # graphite = graphite * (3,3,1) # scale c parameter to new value cellpar = graphite . cell . cellpar () cellpar [ 2 ] = c graphite . set_cell ( cellpar , scale_atoms = True ) # set up castep calculator calc = Castep ( kpts = kpts , label = label , castep_command = castep_cmd , directory = directory , _rename_existing_dir = False , # allows us to write all these calculations to the same directory... ) calc . param . xc_functional = xc calc . param . basis_precision = 'precise' # switch to something cheaper (e.g. FINE) to speed things up for this example.. calc . param . write_checkpoint = 'None' # don't need the checkpoint files now calc . param . write_cst_esp = False # don't need the electrostatic potential file now calc . param . write_bands = False # don't need the bands file now calc . cell . symmetry_generate = True # use symmetry to speed up the calculation calc . cell . snap_to_symmetry = True # enforce symmetry # Switch on the SEDC flags if sedc_scheme != '' : calc . param . sedc_apply = True calc . param . sedc_scheme = sedc_scheme # For the XDM scheme we need to set this manually # otherwise the calculation crashes... if sedc_scheme == 'XDM' : calc . param . SEDC_SC_XDM = 1.0 graphite . calc = calc e = graphite . get_potential_energy () # If a SEDC scheme is used, # we need to extract the dispersion corrected energy if sedc_scheme != '' : e = extract_dispersion_corrected_energy ( directory + label + '.castep' ) energies . append ( e ) print ( f ' { c : 8.3f } A \\t { e : 12.8f } eV' ) # save the energy wrt to furthest energy: energies = [ e - energies [ - 1 ] for e in energies ] df [ f ' { xc } - { sedc_scheme } ' ] = energies # Save to a .csv file: df . to_csv ( 'graphite_layer_separation.csv' ) The .param files generated look something like this: WRITE_CST_ESP: FALSE WRITE_BANDS: FALSE WRITE_CHECKPOINT: None XC_FUNCTIONAL: PBE SEDC_APPLY: TRUE SEDC_SCHEME: D3 # or TS or D3-BJ etc. BASIS_PRECISION: precise The task defaults to SINGLEPOINT (which is what we want in this case). The .cell files simply have the crystal structure in which the cell is scaled in the c direction.","title":"Separation of layers: setup and run the calculations"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#read-in-and-analyse-the-results","text":"We can now read in and analyse the results from the previous step. Reading the data into a pandas dataframe object is convenient. df = pd . read_csv ( './graphite_layer_separation.csv' ) # scale by 1000 / 4 to get the energies per atom and in units of meV dfdiff = ( df . iloc [:, 1 :]) * 1000 / 4 # energy per atom in meV # the c parmeter is 2x the interlayer spacing, d dfdiff [ 'c/2' ] = df [ 'crange' ] / 2 styles = [ f ' { m } -' for m in [ \"o\" , \"v\" , \"^\" , \"s\" , \"H\" , \"+\" , \"x\" , \"D\" ]] # compared to this reference (and many others!) https://doi.org/10.1039/C3RA47187J ax = dfdiff . plot ( x = 'c/2' , y = [ 'PBE-' , 'PBE-G06' , 'PBE-D3' , 'PBE-D3-BJ' , 'D4' , 'PBE-TS' , 'PBE-MBD' , 'PBE-XDM' ], ylabel = 'energy/atom (meV)' , ylim = ( - 100 , 80 ), xlabel = r 'interlayer spacing d ( = c/2) (${\\AA}$)' , figsize = ( 16 , 10 ), style = styles , ) ax . axhline ( 0 , color = '0.3' ) ax . axvline ( 3.355 , ls = '--' , color = '0.4' ) # Experimental binding energies reported shown in the figure are 31 \u00b1 2, 43, 52 \u00b1 5 and 35 (+15 to \u201310) meV per atom ax . axhspan ( ymin =- 57 , ymax =- 25 , color = '0.8' , alpha = 0.5 ) ax . set_title ( 'graphite interlayer binding energy' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.pdf' ) plt . savefig ( 'graphite-interlayer-binding-castep-dispersions.png' , dpi = 300 ) which produces the following figure: Fig1. Graphite interlayer binding energy using the PBE XC functional with various dispersion corrections. The dashed vertical line is the experimental interlayer spacing and the shaded grey region is the range of experimentally obtained interlayer binding energies. Please note that these are not fully converged calculations and so do not represent the actual performance of these methods but is simply a guide for how to use them with CASTEP. We can see that the plain PBE functional severely underestimates the binding energy of graphite and that many of the dispersion-corrected results are in much better agreement. The TS scheme strongly overbinds graphite, but has been found to be accurate for other types of systems. Testing such methods carefully is always required when you encounter a new system.","title":"Read in and analyse the results"},{"location":"tutorials/dispersion_corrections/castep-ase-dispersion-tutorial/#further-suggestions","text":"For the D3 and D3-BJ methods, try to switch on the three-body interaction term by setting: %BLOCK devel_code d3_threebody TRUE %ENDBLOCK devel_code in the .param file. What effect does this have on the interlayer binding energy in graphite? (You may also want to set IPRINT = 2 to see more information about the dispersion correction parameters.) Compare to other XC functionals with and without the dispersion corrections (though note that of the corrections are only parameterised for a few functionals .) For CASTEP < 24.1 we get a warning for the TS, MBD and XDM schemes about the unit cell being too small for accurate corrections. If you get this warning, try repeating the above calculations for these three methods using a larger supercell to see what the effect is and what sized supercell you would need to converge the dispersion correction.","title":"Further suggestions"},{"location":"workshop/00_starting/","text":"Getting Started Settting up the Virtual Workspace Signing up to the STFC Training Workspace Open a browser and navigate to the link you have been emailed - the one that contains training.analysis.stfc.ac.uk. This should prompt you for some information and it will then send your account for authorisation. Once the account is authorised, you will recieve and email with a link to login. Creating the CASTEP Workspace You should recieve an email with a link that you can use to connect to the STFC system. Save this email as you will use it to login during the training. Select New Workspace and then select CASTEP TRAINING WORKSHOP 2024 and click create workspace. This will generate you a virtual desktop on the STFC cloud service with access to CASTEP. Connecting to and using the virual desktop Mouse over the workspace and you should be presented with buttons to launch the workspace in either a new tab or new window. This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several other useful tools available. Uploading and downloading files from your laptop To upload or download any files from your laptop to the VM, navigate to https://training.analysis.stfc.ac.uk/data/ , click on Data (left hand menu) and then select Home - that's your home directory where you can upload files to. Copying and pasting from your laptop To enable copying and pasting between your laptop and the VM, hover your mouse at the top of the virtual desktop and click on Copy & Paste to enable this. Loading CASTEP Click the applications button in the bottom left and select software -> CASTEP. This will launch a terminal with shortcuts for running CASTEP. Accessing the CASTEP help system To search the castep help system for keywords containing castep: castep-serial castep.serial -s lattice To view detailed information on a particular keyword: castep-serial castep.serial -h lattice_abc Running CASTEP To run castep in serial with Si2 as the seedname, type castep-serial castep.serial Si2 To run castep in parallel using 16 core (the maximum for these virutal machines) with same Si2 seedname, type castep-mpi mpirun -n 16 castep.mpi Si2 Note that the castep-serial and castep-mpi parts that the start of the above lines are particular to these virtual machines for the tutorial. Running castep on your own machines would typically involve either castep.serial Si2 for the serial version or mpirun -n 4 castep.mpi Si2 for the parallel version. Tutorial files The files needed for these tutorials can be found by navigating from Applications -> Data -> Course Materials (that will open up a file browser in the right place). They can also be accessed via the command line from this location: /course_materials/ . Copy the files to somewhere in your home directory before trying to run CASTEP (you can't run CASTEP in the /course_materials directory. You can do that either using the graphical file browser or using the command line. For example: Make a folder called Si2 in your home directory: mkdir ~/Si2 Then copy in the corresponding tutorial file: cp /course_materials/Si2.tar.gz ~/Si2/ Summary of useful commands mv - rename (or move) a file eg. mv oldfile newfile cp - copy a file eg. cp original copy pwd - print current (working) directory mkdir - make a new directory (aka folder) nano - a file editor eg. nano filename . Note you can use this to edit an existing file, or to create a new file. eg nano mynewfile will create a new file called mynewfile ls - list files in the current directory ls -l - list files - but give more details than plain ls exit - to close the terminal when you are finished cp fred/* jim/ - copy all the files in the folder fred into the folder jim cp -r alice bob - copy recursively alice to bob . You need this if you want to copy whole folders. cp ../myfile ./ - copy the file myfile in the folder below to the current folder cp ~/myfile ./ - copy the file myfile in your home folder to the current folder castep-mpi mpirun -np 8 castep.mpi diamond - submits a castep job with diamond.cell and diamond.param as inputs onto 8 cores with a time limit of 1 hour c2x This is a handy free program written by Michael Rutter (TCM group Cambridge). It can convert castep.cell and castep.check files into various formats eg .cell , .pdb . (and many other things!) castep-serial c2x -h - list all the options castep-serial c2x --pdbn castep.cell castep.pdb castep-serial c2x --pdbn castep.check castep.pdb castep-serial c2x --cell castep.check new.cell (useful at the end of geometry optimisation)","title":" 0 Logging on"},{"location":"workshop/00_starting/#getting-started","text":"","title":"Getting Started"},{"location":"workshop/00_starting/#settting-up-the-virtual-workspace","text":"","title":"Settting up the Virtual Workspace"},{"location":"workshop/00_starting/#signing-up-to-the-stfc-training-workspace","text":"Open a browser and navigate to the link you have been emailed - the one that contains training.analysis.stfc.ac.uk. This should prompt you for some information and it will then send your account for authorisation. Once the account is authorised, you will recieve and email with a link to login.","title":"Signing up to the STFC Training Workspace"},{"location":"workshop/00_starting/#creating-the-castep-workspace","text":"You should recieve an email with a link that you can use to connect to the STFC system. Save this email as you will use it to login during the training. Select New Workspace and then select CASTEP TRAINING WORKSHOP 2024 and click create workspace. This will generate you a virtual desktop on the STFC cloud service with access to CASTEP.","title":"Creating the CASTEP Workspace"},{"location":"workshop/00_starting/#connecting-to-and-using-the-virual-desktop","text":"Mouse over the workspace and you should be presented with buttons to launch the workspace in either a new tab or new window. This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several other useful tools available.","title":"Connecting to and using the virual desktop"},{"location":"workshop/00_starting/#uploading-and-downloading-files-from-your-laptop","text":"To upload or download any files from your laptop to the VM, navigate to https://training.analysis.stfc.ac.uk/data/ , click on Data (left hand menu) and then select Home - that's your home directory where you can upload files to.","title":"Uploading and downloading files from your laptop"},{"location":"workshop/00_starting/#copying-and-pasting-from-your-laptop","text":"To enable copying and pasting between your laptop and the VM, hover your mouse at the top of the virtual desktop and click on Copy & Paste to enable this.","title":"Copying and pasting from your laptop"},{"location":"workshop/00_starting/#loading-castep","text":"Click the applications button in the bottom left and select software -> CASTEP. This will launch a terminal with shortcuts for running CASTEP.","title":"Loading CASTEP"},{"location":"workshop/00_starting/#accessing-the-castep-help-system","text":"To search the castep help system for keywords containing castep: castep-serial castep.serial -s lattice To view detailed information on a particular keyword: castep-serial castep.serial -h lattice_abc","title":"Accessing the CASTEP help system"},{"location":"workshop/00_starting/#running-castep","text":"To run castep in serial with Si2 as the seedname, type castep-serial castep.serial Si2 To run castep in parallel using 16 core (the maximum for these virutal machines) with same Si2 seedname, type castep-mpi mpirun -n 16 castep.mpi Si2 Note that the castep-serial and castep-mpi parts that the start of the above lines are particular to these virtual machines for the tutorial. Running castep on your own machines would typically involve either castep.serial Si2 for the serial version or mpirun -n 4 castep.mpi Si2 for the parallel version.","title":"Running CASTEP"},{"location":"workshop/00_starting/#tutorial-files","text":"The files needed for these tutorials can be found by navigating from Applications -> Data -> Course Materials (that will open up a file browser in the right place). They can also be accessed via the command line from this location: /course_materials/ . Copy the files to somewhere in your home directory before trying to run CASTEP (you can't run CASTEP in the /course_materials directory. You can do that either using the graphical file browser or using the command line. For example: Make a folder called Si2 in your home directory: mkdir ~/Si2 Then copy in the corresponding tutorial file: cp /course_materials/Si2.tar.gz ~/Si2/","title":"Tutorial files"},{"location":"workshop/00_starting/#summary-of-useful-commands","text":"mv - rename (or move) a file eg. mv oldfile newfile cp - copy a file eg. cp original copy pwd - print current (working) directory mkdir - make a new directory (aka folder) nano - a file editor eg. nano filename . Note you can use this to edit an existing file, or to create a new file. eg nano mynewfile will create a new file called mynewfile ls - list files in the current directory ls -l - list files - but give more details than plain ls exit - to close the terminal when you are finished cp fred/* jim/ - copy all the files in the folder fred into the folder jim cp -r alice bob - copy recursively alice to bob . You need this if you want to copy whole folders. cp ../myfile ./ - copy the file myfile in the folder below to the current folder cp ~/myfile ./ - copy the file myfile in your home folder to the current folder castep-mpi mpirun -np 8 castep.mpi diamond - submits a castep job with diamond.cell and diamond.param as inputs onto 8 cores with a time limit of 1 hour","title":"Summary of useful commands"},{"location":"workshop/00_starting/#c2x","text":"This is a handy free program written by Michael Rutter (TCM group Cambridge). It can convert castep.cell and castep.check files into various formats eg .cell , .pdb . (and many other things!) castep-serial c2x -h - list all the options castep-serial c2x --pdbn castep.cell castep.pdb castep-serial c2x --pdbn castep.check castep.pdb castep-serial c2x --cell castep.check new.cell (useful at the end of geometry optimisation)","title":"c2x"},{"location":"workshop/01_bonding/","text":"Learning Objectives Introduction to CASTEP input and output files. Running on the Arcus machine at Oxford University. Introduction The aim of this exercise is to familiarise you with CASTEP input and output files and running the code, some associated utilities and conversion programs. You will run some simple and small CASTEP calculations on canonical examples of covalently and ionically bonded materials - silicon and sodium chloride - and use the results to study the bonding from an electronic structure perspective. While performing the exercises try to think about the reasons for each step, and about how to interpret the results. The point of the exercise is not merely to reach the end but to learn the path. The exercise below contains a number of questions. Please take note when a question is asked of you, and think about the answer. Feel free to discuss the answer with one of the demonstrators after you have thought about it for a while. The secondary aim of this exercise is to learn to run programs on Oxford University's Arcus cluster. This is a powerful parallel computer. (Although the runs in this first exercise should take only seconds on a desktop.) For information about how to login to and use this cluster please refer to the instructions provided. ` Where To Find Help If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep --help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep --help kpoints_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep --search symmetry Finally, to list all keywords, use: $ castep --search all Note that the long-form arguments --help and --search can optionally be replaced with -h and -s , respectively. Example 1 - Silicon Download the files to arcus $ wget http://www.castep.org/files/Si2.tgz Unzip and untar them, then move into the new directory $ gunzip Si2.tgz $ tar -xvf Si2.tar $ cd Si2 Examine the CASTEP input files Si2.cell and Si2.param using your favourite text editor (e.g. nano ). The Si_00.usp file is a pseudopotential file, you do not need to understand it at the moment. $ nano Si2.cell $ nano Si2.param It is useful to view the structure before submitting your calculation using CASTEP. Copy the Si2.cell to your local machine using the sftp window (left) in mobaXterm. Cell Structure Visualisation Jmol To open the Si2.cell file using Jmol : Open Jmol (You will need to copy it from the h: drive to your desktop. Then double click jmol.jar ) then use File => Open and navigate to your Si2.cell file. Alternatively, you can drag and drop the Si2.cell file into the Jmol window, and Jmol will open it. It can be helpful to view multiple repeat units of your unit cell. The easiest way to do this in Jmol is to open a console window, click File => Console and type: $ load \"\" { 2 2 2 } to show a 2x2x2 supercell. Check the geometry of the input file is what you expect it to be before moving onto the next step. Vesta To open the Si2.cell file using VESTA : Open VESTA (You will need to copy it from the h: drive to your desktop. Then double click VESTA.exe ) then use File => Open and navigate to your Si2.cell file. You cannot drag and drop into VESTA. If you wish to create a supercell as above, use Objects => Boundary . Then edit the maximum and/or minimum values of x, y, and z in order to change your boundaries. Setting x(max) , y(max) , and z(max) to 2 will create the 2 by 2 by 2 supercell as above. Check the geometry of the input file is as expected before moving on to the next step. Now run CASTEP on Arcus using the 2-atom input files. $ castep.mpi Si2 This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Find the section of the file which monitors the SCF loop and the approach to convergence. How many SCF iterations did it need? Copy the output files Si2.castep and Si2.den_fmt to the local machine using sftp . Visualisation of the charge density Jmol Jmol can also be used to view the isodensity map, open the .castep file by dragging and dropping the Si2.castep file into the Jmol window. Open the Jmol console (File => Console) and type the following commands: $ load \"\" { 2 2 2 } $ isosurface rho cutoff 14 \"Si2.den_fmt\" lattice { 2 2 2 } Note: you can use the cd command within Jmol to navigate to the folder with your .castep files. Jmol uses forward slash for paths to files on windows and linux based machines. This Si2.den_fmt file is a formatted file produced by CASTEP that contains the value of the electron density on a grid of points. This isosurface command in Jmol plots an isodensity surface over your atomic positions. Vesta You will see a file called Si2.den_fmt which contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called Si2.charg_frm cp Si2.den_fmt Si2.charg_frm Now edit the file Si2.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open Si2.charg_frm with Vesta. Note that Vesta needs both the .cell and .charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process here . An alternative way to plot charge densities (and much more besides) is c2x . Answer the following questions: Can you explain what you see as you vary the isosurface value? Can you see any features which might be characteristic of a covalently-bonded crystal. Do you notice anything strange about the electron density close to the Si nucleus? Can you explain this as a consequence of the particular kind of electronic structure calculation you have just performed? Repeat steps 1-8 using input files for sodium chloride and aluminium. $ wget http://www.castep.org/files/Al.tgz $ wget http://www.castep.org/files/NaCl.tgz Think about the following questions: Note what similarities and differences you find compared to silicon? Does this help explain the difference in bond chemistry between silicon, sodium chloride and aluminium? Does this help explain why there are many reasonable classical potential functions for NaCl to be found in the simulation literature, but that finding good potentials for silicon is a very tough challenge? What about aluminium, can you find good potentials for aluminium?","title":" 1 Bonding "},{"location":"workshop/01_bonding/#learning-objectives","text":"Introduction to CASTEP input and output files. Running on the Arcus machine at Oxford University.","title":"Learning Objectives"},{"location":"workshop/01_bonding/#introduction","text":"The aim of this exercise is to familiarise you with CASTEP input and output files and running the code, some associated utilities and conversion programs. You will run some simple and small CASTEP calculations on canonical examples of covalently and ionically bonded materials - silicon and sodium chloride - and use the results to study the bonding from an electronic structure perspective. While performing the exercises try to think about the reasons for each step, and about how to interpret the results. The point of the exercise is not merely to reach the end but to learn the path. The exercise below contains a number of questions. Please take note when a question is asked of you, and think about the answer. Feel free to discuss the answer with one of the demonstrators after you have thought about it for a while. The secondary aim of this exercise is to learn to run programs on Oxford University's Arcus cluster. This is a powerful parallel computer. (Although the runs in this first exercise should take only seconds on a desktop.) For information about how to login to and use this cluster please refer to the instructions provided. `","title":"Introduction"},{"location":"workshop/01_bonding/#where-to-find-help","text":"If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep --help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep --help kpoints_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep --search symmetry Finally, to list all keywords, use: $ castep --search all Note that the long-form arguments --help and --search can optionally be replaced with -h and -s , respectively.","title":"Where To Find Help"},{"location":"workshop/01_bonding/#example-1-silicon","text":"Download the files to arcus $ wget http://www.castep.org/files/Si2.tgz Unzip and untar them, then move into the new directory $ gunzip Si2.tgz $ tar -xvf Si2.tar $ cd Si2 Examine the CASTEP input files Si2.cell and Si2.param using your favourite text editor (e.g. nano ). The Si_00.usp file is a pseudopotential file, you do not need to understand it at the moment. $ nano Si2.cell $ nano Si2.param It is useful to view the structure before submitting your calculation using CASTEP. Copy the Si2.cell to your local machine using the sftp window (left) in mobaXterm. Cell Structure Visualisation","title":"Example 1 - Silicon"},{"location":"workshop/01_bonding/#jmol","text":"To open the Si2.cell file using Jmol : Open Jmol (You will need to copy it from the h: drive to your desktop. Then double click jmol.jar ) then use File => Open and navigate to your Si2.cell file. Alternatively, you can drag and drop the Si2.cell file into the Jmol window, and Jmol will open it. It can be helpful to view multiple repeat units of your unit cell. The easiest way to do this in Jmol is to open a console window, click File => Console and type: $ load \"\" { 2 2 2 } to show a 2x2x2 supercell. Check the geometry of the input file is what you expect it to be before moving onto the next step.","title":"Jmol"},{"location":"workshop/01_bonding/#vesta","text":"To open the Si2.cell file using VESTA : Open VESTA (You will need to copy it from the h: drive to your desktop. Then double click VESTA.exe ) then use File => Open and navigate to your Si2.cell file. You cannot drag and drop into VESTA. If you wish to create a supercell as above, use Objects => Boundary . Then edit the maximum and/or minimum values of x, y, and z in order to change your boundaries. Setting x(max) , y(max) , and z(max) to 2 will create the 2 by 2 by 2 supercell as above. Check the geometry of the input file is as expected before moving on to the next step. Now run CASTEP on Arcus using the 2-atom input files. $ castep.mpi Si2 This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Find the section of the file which monitors the SCF loop and the approach to convergence. How many SCF iterations did it need? Copy the output files Si2.castep and Si2.den_fmt to the local machine using sftp . Visualisation of the charge density","title":"Vesta"},{"location":"workshop/01_bonding/#jmol_1","text":"Jmol can also be used to view the isodensity map, open the .castep file by dragging and dropping the Si2.castep file into the Jmol window. Open the Jmol console (File => Console) and type the following commands: $ load \"\" { 2 2 2 } $ isosurface rho cutoff 14 \"Si2.den_fmt\" lattice { 2 2 2 } Note: you can use the cd command within Jmol to navigate to the folder with your .castep files. Jmol uses forward slash for paths to files on windows and linux based machines. This Si2.den_fmt file is a formatted file produced by CASTEP that contains the value of the electron density on a grid of points. This isosurface command in Jmol plots an isodensity surface over your atomic positions.","title":"Jmol"},{"location":"workshop/01_bonding/#vesta_1","text":"You will see a file called Si2.den_fmt which contains the charge density in a formatted (i.e. a human readable, ASCII file). We need to change this file into a format Vesta can read. Copy it to a file called Si2.charg_frm cp Si2.den_fmt Si2.charg_frm Now edit the file Si2.charg_frm with a text editor to remove the first 11 lines. The file should now begin with 1 1 1 and a number. You can now open Si2.charg_frm with Vesta. Note that Vesta needs both the .cell and .charge_frm files to make a plot. If you are working on a remote machine you will need to copy both of these back to your local machine to view with Vesta. You can find a walkthrough video of this process here . An alternative way to plot charge densities (and much more besides) is c2x .","title":"Vesta"},{"location":"workshop/01_bonding/#answer-the-following-questions","text":"Can you explain what you see as you vary the isosurface value? Can you see any features which might be characteristic of a covalently-bonded crystal. Do you notice anything strange about the electron density close to the Si nucleus? Can you explain this as a consequence of the particular kind of electronic structure calculation you have just performed? Repeat steps 1-8 using input files for sodium chloride and aluminium. $ wget http://www.castep.org/files/Al.tgz $ wget http://www.castep.org/files/NaCl.tgz","title":"Answer the following questions:"},{"location":"workshop/01_bonding/#think-about-the-following-questions","text":"Note what similarities and differences you find compared to silicon? Does this help explain the difference in bond chemistry between silicon, sodium chloride and aluminium? Does this help explain why there are many reasonable classical potential functions for NaCl to be found in the simulation literature, but that finding good potentials for silicon is a very tough challenge? What about aluminium, can you find good potentials for aluminium?","title":"Think about the following questions:"},{"location":"workshop/02_bands_dos/","text":"Learning Objectives Gain awareness and familiarity with the tools available to produce band structure and density of states plots with CASTEP. Investigate how band structures differ for metallic and semiconductor systems differ. Running spin polarised calculations in CASTEP. Note This tutorial we will be running on Arcus, you should be able to complete this tutorial without copying files backwards and forwards; however if you wish to visualise your system (e.g. using VESTA) then you will need to copy files to your local machine to do so. If you don't remember how to do this, remind yourself by referring to Tutorial 0 and Tutorial 1 Xterminals, Plotting and other computational hassle To save some effort transferring files backwards and forwards to and from Arcus we are going to use Arcus to plot the band structure and DOS and send the image to your monitor. Introduction The aim of this tutorial is to enable you to compute band structures using CASTEP and introduce you to a few of the tools which allow you to visualise the band structure and density of electronic states computed using CASTEP. The band structure of metals and semiconductors will be plotted so that you can look at the differences between different types of systems. First you will look at the CASTEP input files (.cell and .param) used to produce band structure information. Next you will use the perl script dispersion.pl which can be used to take CASTEP output and plot band structure diagrams. Then you will use orbitals2bands. A tool which provides more information about the orbitals that contribute to different bands in your band structure diagram. Finally you will look at the band structure of iron, to show how magnetic systems can be studied using CASTEP, you will also plot the density of states of iron using dos.pl. You will need: In addition to CASTEP and the suite of tools it comes with you will need: Grace - A 2D plotting program. Perl - a scripting language. These are available on the Arcus cluster. Example files: Download the input files wget http://www.castep.org/files/bandstructure.tgz Then untar and unzip it using: gunzip bandstructure.tgz tar -xvf bandstructure.tar Example 1 - Graphite. Move into the graphite directory, look at the CASTEP .cell and .param files and notice the differences from the previous single point energy runs. To the .param file the task (which lets CASTEP know what you want it to do) needs to be changed to: task : bandstructure The .cell file requires a path through the Brillouin Zone along which you want the bandstructure to be plotted: %BLOCK BS_KPOINT_PATH 0.0000 0.00000 0.00000 ! G 0.0000 0.00000 0.50000 ! A -0.3333 0.66667 0.50000 ! H -0.3333 0.66667 0.00000 ! K 0.0000 0.00000 0.00000 ! G 0.0000 0.50000 0.00000 ! M 0.0000 0.50000 0.50000 ! L -0.3333 0.66667 0.50000 ! H %ENDBLOCK BS_KPOINT_PATH Run CASTEP using: $ mpirun -np 16 castep.mpi graphite Once the CASTEP calculation has finished a graphite.bands file will be present in the directory. A band structure plot can be viewed by using the dispersion.pl tool. $ dispersion.pl -xg -bs -symmetry hexagonal graphite.bands The -xg option tells dispersion.pl that you are using grace to plot the band structure, the -bs option tells the script that you want to plot using CASTEP output files, the -symmetry hexagonal option labels the high symmetry points on the bands structure plot. When you view this band structure plot you will notice the bands are coloured from lowest to highest energy. Using information about the wavefunction CASTEP can improve this band structure plot, so bands are coloured due to the orbitals that contribute. The orbitals2bands tool can be used to alter the Si.bands file represent the orbitals that contribute to the bands. This tool can be run in the same directory that you ran CASTEP in. The program orbitals2bands overwrites your Si.bands file, so it's best to copy it to another file to preserve it $ cp graphite.bands graphite.bands.orig $ mpirun -np 16 orbitals2bands graphite Example 2 - Silicon and Aluminium. Very similar to example 1, but this time comparing a semiconductor and a metal, both with FCC crystal structures. Go into the silicon and aluminium directories and compute the band structures as above. The dispersion symmetry option needs to be told that these are FCC materials, not hexagonal. Compare the band structure of the Silicon and Aluminium crystals. What are the main similarities and differences? Can you explain this using your knowledge of the bonding in these materials? Example 3 - Iron In the iron directory there is a set of input files for iron. As iron is a magnetic system you need to instruct CASTEP that it is spin polarised. You also need to set up the calculation with the total spin set to a non-zero value, in order to find the magnetic ground state. (If you're interested you could try removing the spin : 1 line from the Fe.param file and see what happens). You set the spin in the .param file: spin : 1 spin_polarised : true The path through the Brillouin Zone is found in the Fe.cell file. Run the iron computation using CASTEP and plot the band structure for iron using dispersion.pl . You might find the -mono option to dispersion.pl to be useful - it colours the bands by spin channel. Iron's Density of States To plot the density of states of iron, we need to run CASTEP again, instead of computing the band structure along a high symmetry line, we compute it on a grid. To your Fe.cell file, remove the bs_kpoint_path block and replace it with: BS_KPOINT_MP_GRID 12 12 12 Run CASTEP using these new input files then use the dos.pl plotting script dos.pl -xg -bs -w 0.2 Fe.bands Can you relate the features in the DOS to those in the Bandstructure? You might find the -mirror option useful. The -w option sets the Gaussian broadening in eV. Try smaller (0.05) and larger (0.5) values - explain what you see. DOS for the other crystals in this tutorial can be computed in a similar way. Further work a) Compute the band-structure of hexagonal monolayer boron nitride. What is the key difference to graphene? b) MoS2 has attracted much recent interest. What is its structure? Can you make a cell file for this (if not ask). What about its band structure - metal or insulator, direct vs indirect gap.","title":" 2 Bandstructure and DOS"},{"location":"workshop/02_bands_dos/#learning-objectives","text":"Gain awareness and familiarity with the tools available to produce band structure and density of states plots with CASTEP. Investigate how band structures differ for metallic and semiconductor systems differ. Running spin polarised calculations in CASTEP.","title":"Learning Objectives"},{"location":"workshop/02_bands_dos/#note","text":"This tutorial we will be running on Arcus, you should be able to complete this tutorial without copying files backwards and forwards; however if you wish to visualise your system (e.g. using VESTA) then you will need to copy files to your local machine to do so. If you don't remember how to do this, remind yourself by referring to Tutorial 0 and Tutorial 1","title":"Note"},{"location":"workshop/02_bands_dos/#xterminals-plotting-and-other-computational-hassle","text":"To save some effort transferring files backwards and forwards to and from Arcus we are going to use Arcus to plot the band structure and DOS and send the image to your monitor.","title":"Xterminals, Plotting and other computational hassle"},{"location":"workshop/02_bands_dos/#introduction","text":"The aim of this tutorial is to enable you to compute band structures using CASTEP and introduce you to a few of the tools which allow you to visualise the band structure and density of electronic states computed using CASTEP. The band structure of metals and semiconductors will be plotted so that you can look at the differences between different types of systems. First you will look at the CASTEP input files (.cell and .param) used to produce band structure information. Next you will use the perl script dispersion.pl which can be used to take CASTEP output and plot band structure diagrams. Then you will use orbitals2bands. A tool which provides more information about the orbitals that contribute to different bands in your band structure diagram. Finally you will look at the band structure of iron, to show how magnetic systems can be studied using CASTEP, you will also plot the density of states of iron using dos.pl.","title":"Introduction"},{"location":"workshop/02_bands_dos/#you-will-need","text":"In addition to CASTEP and the suite of tools it comes with you will need: Grace - A 2D plotting program. Perl - a scripting language. These are available on the Arcus cluster.","title":"You will need:"},{"location":"workshop/02_bands_dos/#example-files","text":"Download the input files wget http://www.castep.org/files/bandstructure.tgz Then untar and unzip it using: gunzip bandstructure.tgz tar -xvf bandstructure.tar","title":"Example files:"},{"location":"workshop/02_bands_dos/#example-1-graphite","text":"Move into the graphite directory, look at the CASTEP .cell and .param files and notice the differences from the previous single point energy runs. To the .param file the task (which lets CASTEP know what you want it to do) needs to be changed to: task : bandstructure The .cell file requires a path through the Brillouin Zone along which you want the bandstructure to be plotted: %BLOCK BS_KPOINT_PATH 0.0000 0.00000 0.00000 ! G 0.0000 0.00000 0.50000 ! A -0.3333 0.66667 0.50000 ! H -0.3333 0.66667 0.00000 ! K 0.0000 0.00000 0.00000 ! G 0.0000 0.50000 0.00000 ! M 0.0000 0.50000 0.50000 ! L -0.3333 0.66667 0.50000 ! H %ENDBLOCK BS_KPOINT_PATH Run CASTEP using: $ mpirun -np 16 castep.mpi graphite Once the CASTEP calculation has finished a graphite.bands file will be present in the directory. A band structure plot can be viewed by using the dispersion.pl tool. $ dispersion.pl -xg -bs -symmetry hexagonal graphite.bands The -xg option tells dispersion.pl that you are using grace to plot the band structure, the -bs option tells the script that you want to plot using CASTEP output files, the -symmetry hexagonal option labels the high symmetry points on the bands structure plot. When you view this band structure plot you will notice the bands are coloured from lowest to highest energy. Using information about the wavefunction CASTEP can improve this band structure plot, so bands are coloured due to the orbitals that contribute. The orbitals2bands tool can be used to alter the Si.bands file represent the orbitals that contribute to the bands. This tool can be run in the same directory that you ran CASTEP in. The program orbitals2bands overwrites your Si.bands file, so it's best to copy it to another file to preserve it $ cp graphite.bands graphite.bands.orig $ mpirun -np 16 orbitals2bands graphite","title":"Example 1 - Graphite."},{"location":"workshop/02_bands_dos/#example-2-silicon-and-aluminium","text":"Very similar to example 1, but this time comparing a semiconductor and a metal, both with FCC crystal structures. Go into the silicon and aluminium directories and compute the band structures as above. The dispersion symmetry option needs to be told that these are FCC materials, not hexagonal. Compare the band structure of the Silicon and Aluminium crystals. What are the main similarities and differences? Can you explain this using your knowledge of the bonding in these materials?","title":"Example 2 - Silicon and Aluminium."},{"location":"workshop/02_bands_dos/#example-3-iron","text":"In the iron directory there is a set of input files for iron. As iron is a magnetic system you need to instruct CASTEP that it is spin polarised. You also need to set up the calculation with the total spin set to a non-zero value, in order to find the magnetic ground state. (If you're interested you could try removing the spin : 1 line from the Fe.param file and see what happens). You set the spin in the .param file: spin : 1 spin_polarised : true The path through the Brillouin Zone is found in the Fe.cell file. Run the iron computation using CASTEP and plot the band structure for iron using dispersion.pl . You might find the -mono option to dispersion.pl to be useful - it colours the bands by spin channel.","title":"Example 3 - Iron"},{"location":"workshop/02_bands_dos/#irons-density-of-states","text":"To plot the density of states of iron, we need to run CASTEP again, instead of computing the band structure along a high symmetry line, we compute it on a grid. To your Fe.cell file, remove the bs_kpoint_path block and replace it with: BS_KPOINT_MP_GRID 12 12 12 Run CASTEP using these new input files then use the dos.pl plotting script dos.pl -xg -bs -w 0.2 Fe.bands Can you relate the features in the DOS to those in the Bandstructure? You might find the -mirror option useful. The -w option sets the Gaussian broadening in eV. Try smaller (0.05) and larger (0.5) values - explain what you see. DOS for the other crystals in this tutorial can be computed in a similar way.","title":"Iron's Density of States"},{"location":"workshop/02_bands_dos/#further-work","text":"a) Compute the band-structure of hexagonal monolayer boron nitride. What is the key difference to graphene? b) MoS2 has attracted much recent interest. What is its structure? Can you make a cell file for this (if not ask). What about its band structure - metal or insulator, direct vs indirect gap.","title":"Further work"},{"location":"workshop/03_geometry/","text":"Geometry Optimisation Exercise 1 - Dihydrogen dimer In this tutorial we will model the bond length of a H2 molecule. This will give you the opportunity to get used to geometry optimisations and gain familiarity Remember you can use castep --help to assist you with finding the appropriate input parameters. Create a new file, H2.cell using your favourite text editor, e.g. nano H2.cell Start by creating a lattice block in your cell file. %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc or %block lattice_cart 5 0 0 0 5 0 0 0 5 %endblock lattice_cart Will produce a cube 5 Angstroms long on each side. NOTE: ONLY USE ONE OF THESE TWO FORMATS Q: Is this a big enough box to represent a molecule? (Recall Periodic Boundary Conditions) A: You may wish to test this by changing the size of the box. Add atoms into our cell. This can be done either relative to the lattice vectors using %block positions_frac H 0.5 0.5 0.5 H 0.5 0.5 0.2 %endblock positions_frac or relative to the origin of the cell file %block positions_abs H 3 3 3 H 3 3 4 %endblock positions_abs Q: If you are varying the size of your unit cell for tests, which one will be more convenient? Add final components to unit cell fix_all_cell: true kpoint_mp_grid: 1 1 1 Q: Why do we only want to use a single k-point? Q: Why do we want to fix the lattice parameters rather than letting them relax? Now close H2.cell and create a H2.param file. In H2.param add Task: GeometryOptimisation XC_Functional: LDA Cut_Off_Energy: 300 If you want to get Castep to automatically print out the final structure, you can also add write_cell_structure: true You can now use mpirun (or your submission script!) to submit your geometry optimisation! Results Analysis Scroll down through the file. Check to see how the forces and bond-length varies over iterations. For advanced bash users, try grep \"F|max\" H2.castep to extract this from the file. You may also want to visualise the H2.cell and (if you told castep to print it) the H2-out.cell files as in previous tutorials Finally, consider watching the optimisation by drag-and-dropping the H2.geom file into Jmol (VESTA will not animate it) The experimental H2 bond length is about 0.74 Angstroms. How does your result compare? Extension A may give some insight into this! Extensions You may wish to split these between groups and discuss the results A. Functional Choice So far you've used the local density approximation (LDA) for the exchange-correlation functional in this exercise. Repeat your calculation with the PBE exchange-correlation functional (a popular GGA): xc_functional : PBE You may also want to consider a hybrid functional such as HSE06 or the meta-GGA RSCAN B. More Precise Structural Optimisations You may wish to have more precise structure for certain calculations such as NMR or Phonons . These may be controlled in the .param file with geom_force_tol: 0.05 eV/ang geom_energy_tol: 2e-5 eV geom_stress_tol: 0.1 GPa geom_disp_tol: 0.001 ang These are the default values; what happens to your final values when you alter them? Hint: You have fixed the lattice - what will stress do? C. Wavefunction Convergence If you have a bad wavefunction you will get bad forces. To demonstrate this try adding elec_energy_tol: 0.1 This overwrites the default of 0.00001 ev and will make the SCF convergence very fast. What does this do to the geometry optimisation? NOTE: This is not something you want to do in practice! Hopefully working through this example will demonstrate why. Exercise 2 Run a geometry optimisation on silicon. You can use a silicon input file from one of the previous tutorials as a starting point for your input files. Set CASTEP's parameters to perform a geometry optimisation using a 160 eV plane-wave cut-off energy and an 8x8x8 Monkhorst-Pack k-point grid: In Si2.param : task : geometry optimisation cut_off_energy : 160 eV In Si2.cell : kpoints_MP_grid 8 8 8 Because you're going to change the lattice vectors, CASTEP will do a finite basis-set correction (FBSC); this will calculate and print out dEtotal/dlog(Ecut) \u2013 anything more than 0.1 eV/atom is big and a sign of incomplete convergence. Q: What is the final lattice parameter? Do convergence tests (cut_off_energy, kpoints etc). The experimental lattice constant is 3.84 Angstrom - how does your value compare? What is the difference in your results between calculations using an LDA and a PBE exchange-correlation functional? Exercise 3 - Graphene It can be useful to know how to construct a monolayer material, such as graphene. This requires the use of cell constraints so that we force a large distance between periodic images (and we don't have the system collapse to form graphite!) In your .cell file: %block cell_constraints 1 1 0 3 4 5 %endblock cell_constraints Will force the a and b lattice parameters to be the same (though free to vary jointly), fix the c lattice vector, and let all angles relax independently. This is similar to the %block lattice_abc structure you saw earlier. For the mathematically minded, this is taking the limit that the interlayer spacing, controlled by the out-of-plane lattice vector, goes to infinity! Practically, we cannot actually set the lattice parameter to infinity - try varying it and seeing how it converges with distance.","title":" 3 Geometry Optimisation"},{"location":"workshop/03_geometry/#geometry-optimisation","text":"","title":"Geometry Optimisation"},{"location":"workshop/03_geometry/#exercise-1-dihydrogen-dimer","text":"In this tutorial we will model the bond length of a H2 molecule. This will give you the opportunity to get used to geometry optimisations and gain familiarity Remember you can use castep --help to assist you with finding the appropriate input parameters. Create a new file, H2.cell using your favourite text editor, e.g. nano H2.cell Start by creating a lattice block in your cell file. %block lattice_abc 5 5 5 90 90 90 %endblock lattice_abc or %block lattice_cart 5 0 0 0 5 0 0 0 5 %endblock lattice_cart Will produce a cube 5 Angstroms long on each side. NOTE: ONLY USE ONE OF THESE TWO FORMATS Q: Is this a big enough box to represent a molecule? (Recall Periodic Boundary Conditions) A: You may wish to test this by changing the size of the box. Add atoms into our cell. This can be done either relative to the lattice vectors using %block positions_frac H 0.5 0.5 0.5 H 0.5 0.5 0.2 %endblock positions_frac or relative to the origin of the cell file %block positions_abs H 3 3 3 H 3 3 4 %endblock positions_abs Q: If you are varying the size of your unit cell for tests, which one will be more convenient? Add final components to unit cell fix_all_cell: true kpoint_mp_grid: 1 1 1 Q: Why do we only want to use a single k-point? Q: Why do we want to fix the lattice parameters rather than letting them relax? Now close H2.cell and create a H2.param file. In H2.param add Task: GeometryOptimisation XC_Functional: LDA Cut_Off_Energy: 300 If you want to get Castep to automatically print out the final structure, you can also add write_cell_structure: true You can now use mpirun (or your submission script!) to submit your geometry optimisation! Results Analysis Scroll down through the file. Check to see how the forces and bond-length varies over iterations. For advanced bash users, try grep \"F|max\" H2.castep to extract this from the file. You may also want to visualise the H2.cell and (if you told castep to print it) the H2-out.cell files as in previous tutorials Finally, consider watching the optimisation by drag-and-dropping the H2.geom file into Jmol (VESTA will not animate it) The experimental H2 bond length is about 0.74 Angstroms. How does your result compare? Extension A may give some insight into this!","title":"Exercise 1 - Dihydrogen dimer"},{"location":"workshop/03_geometry/#extensions","text":"You may wish to split these between groups and discuss the results","title":"Extensions"},{"location":"workshop/03_geometry/#a-functional-choice","text":"So far you've used the local density approximation (LDA) for the exchange-correlation functional in this exercise. Repeat your calculation with the PBE exchange-correlation functional (a popular GGA): xc_functional : PBE You may also want to consider a hybrid functional such as HSE06 or the meta-GGA RSCAN","title":"A. Functional Choice"},{"location":"workshop/03_geometry/#b-more-precise-structural-optimisations","text":"You may wish to have more precise structure for certain calculations such as NMR or Phonons . These may be controlled in the .param file with geom_force_tol: 0.05 eV/ang geom_energy_tol: 2e-5 eV geom_stress_tol: 0.1 GPa geom_disp_tol: 0.001 ang These are the default values; what happens to your final values when you alter them? Hint: You have fixed the lattice - what will stress do?","title":"B. More Precise Structural Optimisations"},{"location":"workshop/03_geometry/#c-wavefunction-convergence","text":"If you have a bad wavefunction you will get bad forces. To demonstrate this try adding elec_energy_tol: 0.1 This overwrites the default of 0.00001 ev and will make the SCF convergence very fast. What does this do to the geometry optimisation? NOTE: This is not something you want to do in practice! Hopefully working through this example will demonstrate why.","title":"C. Wavefunction Convergence"},{"location":"workshop/03_geometry/#exercise-2","text":"Run a geometry optimisation on silicon. You can use a silicon input file from one of the previous tutorials as a starting point for your input files. Set CASTEP's parameters to perform a geometry optimisation using a 160 eV plane-wave cut-off energy and an 8x8x8 Monkhorst-Pack k-point grid: In Si2.param : task : geometry optimisation cut_off_energy : 160 eV In Si2.cell : kpoints_MP_grid 8 8 8 Because you're going to change the lattice vectors, CASTEP will do a finite basis-set correction (FBSC); this will calculate and print out dEtotal/dlog(Ecut) \u2013 anything more than 0.1 eV/atom is big and a sign of incomplete convergence. Q: What is the final lattice parameter? Do convergence tests (cut_off_energy, kpoints etc). The experimental lattice constant is 3.84 Angstrom - how does your value compare? What is the difference in your results between calculations using an LDA and a PBE exchange-correlation functional?","title":"Exercise 2"},{"location":"workshop/03_geometry/#exercise-3-graphene","text":"It can be useful to know how to construct a monolayer material, such as graphene. This requires the use of cell constraints so that we force a large distance between periodic images (and we don't have the system collapse to form graphite!) In your .cell file: %block cell_constraints 1 1 0 3 4 5 %endblock cell_constraints Will force the a and b lattice parameters to be the same (though free to vary jointly), fix the c lattice vector, and let all angles relax independently. This is similar to the %block lattice_abc structure you saw earlier. For the mathematically minded, this is taking the limit that the interlayer spacing, controlled by the out-of-plane lattice vector, goes to infinity! Practically, we cannot actually set the lattice parameter to infinity - try varying it and seeing how it converges with distance.","title":"Exercise 3 - Graphene"},{"location":"workshop/04_nmr_shiedling_efg/","text":"4 NMR shielding and EFG Part 1 We start running castep calculations by looking at two small systems, and examining the issue of \"convergence\". Start by copying the input files into your home directory i.e. wget http://www.tcm.phy.cam.ac.uk/castep/oxford/workshop_nmr_intro.tgz unpack it tar -zxvf workshop_nmr_intro.tgz Example 1 - Ethanol CH 3 CH 2 OH Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig 1). We will try to reproduce this result. FILES: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strate.g.y : speed task = magres cut_off_energy = 20 ry OBJECTIVES: Examine the convergence of the chemical shieldings with planewave cutoff Compare to experiment. INSTRUCTIONS: Look at the cell and param file. Note that the only special keyword is task = magres Run castep. mpirun -np 16 castep.mpi ethanol Look at the output file. At the end the isotropic chemical shielding, anisotropy, and asymmetry are reported (here we are only interested in the isotropic value.) This information, plus the full tensors is also given in the file ethanol.magres You might wish to transfer the *.magres file back to your desktop to visualise with MagresView . Examine the effect of increasing the cutoff energy (say 20-50 Ryd in steps of 10 Ryd). It always helps to plot a graph of the convergence (e.g. with gnuplot or xmgrace on the cluster - or with excel on the pc) Find the \"converged\" hydrogen (or proton in NMR language) shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Average the CH 3 and CH 2 chemical shieldings. This will give you 3 unique chemical shieldings. We now need to convert the chemical shieldings \u03c3 iso to chemical shifts \u03b4 iso on the experimental scale. We use the relation: \u03b4 iso =\u03c3 ref -\u03c3 A suitable \u03c3 ref for 1H is 30.97ppm. Fig2. 1H NMR spectrum of liquid ethanol Fig. 2 shows a modern high-resolution 1H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1H magnetic moments - but let's ignore that for now. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm. You should find that your computed values agree for two sites. Do you know why the other site has such a large disagreement with experiment? Example 2 - Diamond FILES: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate * diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry OBJECTIVES: Examine the convergence of the chemical shielding as the sampling of the electronic Brillouin zone (BZ) is increased. INSTRUCTIONS: Look at the files diamond.cell and diamond.param We have specified the kpoints in the cell file using the keyword kpoints_mp_grid 4 4 4 Run CASTEP for a range of kpoint meshes (say 2,4,6,8,10) Examine (plot?) the convergence of the chemical shielding. The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). Specify the kpoint in the cell file using %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST Which gives a result closest to the converged answer? (as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells) Part 2 We now look at some more realistic examples. Oxygen-17 Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure. Example 3 - Alanine, a simple amino acid FILES: alanine.cell alanine.param alanine.pdb OBJECTIVES: Compute the chemical shift and Electric field gradient for alanine Assign the 17 NMR spectrum Fig3. Solid-State O17 NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) INSTRUCTIONS: Look at the cell and param files. The geometry for alanine was obtained by neutron diffraction and was downloaded from the Cambridge Crystallographic database. View the original pdb file note the hydrogen bonding Run the example - the calculation is not fully converged. However, the relative shift between the two sites is fairly converged. The experimental 17 O NMR spectrum shows two peaks (Fig 3 (b)) - they are very broad due to the quadrupolar coupling, and overlap. The experimental parameters are given in Table 1. Assign the two resonances A and B. Do all three computed parameters support this assignment? Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labeled A and B. Isotropic chemical shift \u03b4, quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4(A)-\u03b4 (B) (ppm) 23.5 C Q (A) (MHz) 7.86 \u03b7 Q (A) 0.28 C Q (B) (MHz) 6.53 \u03b7 Q (B) 0.70 Example 4 - Silicates Quartz and Cristoballite FILES: quartz.cell quartz.param crist.cell crist.param OBJECTIVES: Compute the chemical shift and Electric field gradient for two silicates. Assign the 17 O NMR spectrum INSTRUCTIONS: The 17 O parameters for two silicates are reported in Table 2. From the values you compute can you tell which one is quartz? (a suitable \u03c3 ref is 263ppm) Table 2 : Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \u03b4 , quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4 (ppm) C Q (MHz) \u03b7 Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19","title":" 5 NMR Shielding"},{"location":"workshop/04_nmr_shiedling_efg/#4-nmr-shielding-and-efg","text":"","title":"4 NMR shielding and EFG"},{"location":"workshop/04_nmr_shiedling_efg/#part-1","text":"We start running castep calculations by looking at two small systems, and examining the issue of \"convergence\". Start by copying the input files into your home directory i.e. wget http://www.tcm.phy.cam.ac.uk/castep/oxford/workshop_nmr_intro.tgz unpack it tar -zxvf workshop_nmr_intro.tgz","title":"Part 1"},{"location":"workshop/04_nmr_shiedling_efg/#example-1-ethanol-ch3ch2oh","text":"Fig1. Proton spectrum of ethanol The discovery that one could actually see chemical shifts in hydrogen spectra was made in 1951 at Stanford University by Packard, Arnold, Dharmatti (shown in Fig 1). We will try to reproduce this result. FILES: ethanol.cell %BLOCK LATTICE_ABC 6 6 6 90 90 90 %ENDBLOCK LATTICE_ABC %BLOCK POSITIONS_ABS H 3.980599 4.178342 3.295079 H 5.033394 3.43043 4.504759 H 5.71907 4.552257 3.315353 H 3.720235 5.329505 5.509909 H 4.412171 6.433572 4.317001 H 5.911611 5.032284 6.242202 C 4.84694 4.350631 3.941136 C 4.603025 5.518738 4.882532 O 5.746254 5.812705 5.6871 %ENDBLOCK POSITIONS_ABS %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST ethanol.param xcfunctional = PBE fix_occupancy = true opt_strate.g.y : speed task = magres cut_off_energy = 20 ry OBJECTIVES: Examine the convergence of the chemical shieldings with planewave cutoff Compare to experiment. INSTRUCTIONS: Look at the cell and param file. Note that the only special keyword is task = magres Run castep. mpirun -np 16 castep.mpi ethanol Look at the output file. At the end the isotropic chemical shielding, anisotropy, and asymmetry are reported (here we are only interested in the isotropic value.) This information, plus the full tensors is also given in the file ethanol.magres You might wish to transfer the *.magres file back to your desktop to visualise with MagresView . Examine the effect of increasing the cutoff energy (say 20-50 Ryd in steps of 10 Ryd). It always helps to plot a graph of the convergence (e.g. with gnuplot or xmgrace on the cluster - or with excel on the pc) Find the \"converged\" hydrogen (or proton in NMR language) shieldings. We will compare them to experiment. The three methyl (CH 3 ) protons undergo fast exchange; they \"rotate\" faster than the nuclear magnetic moment processes. The magnetic moment will therefore \"see\" an average chemical shielding. The same is true of the CH 2 protons. Average the CH 3 and CH 2 chemical shieldings. This will give you 3 unique chemical shieldings. We now need to convert the chemical shieldings \u03c3 iso to chemical shifts \u03b4 iso on the experimental scale. We use the relation: \u03b4 iso =\u03c3 ref -\u03c3 A suitable \u03c3 ref for 1H is 30.97ppm. Fig2. 1H NMR spectrum of liquid ethanol Fig. 2 shows a modern high-resolution 1H spectrum for liquid ethanol. Note that the peaks are split due to J-coupling - the interaction of the 1H magnetic moments - but let's ignore that for now. The three peaks are roughly at 1.2ppm, 3.7ppm and 5ppm. You should find that your computed values agree for two sites. Do you know why the other site has such a large disagreement with experiment?","title":"Example 1 - Ethanol CH3CH2OH"},{"location":"workshop/04_nmr_shiedling_efg/#example-2-diamond","text":"FILES: diamond.cell %block LATTICE_CART 0 1.7 1.7 1.7 0 1.7 1.7 1.7 0 %endblock LATTICE_CART %block POSITIONS_FRAC C 0.000000 0.000000 0.000000 C 0.250000 0.250000 0.250000 %endblock POSITIONS_FRAC kpoints_mp_grid 4 4 4 symmetry_generate * diamond.param comment = nmr testing iprint = 1 xcfunctional = LDA task : magres fix_occupancy = true opt_strategy : speed cut_off_energy = 30 Ry OBJECTIVES: Examine the convergence of the chemical shielding as the sampling of the electronic Brillouin zone (BZ) is increased. INSTRUCTIONS: Look at the files diamond.cell and diamond.param We have specified the kpoints in the cell file using the keyword kpoints_mp_grid 4 4 4 Run CASTEP for a range of kpoint meshes (say 2,4,6,8,10) Examine (plot?) the convergence of the chemical shielding. The computational cost scales linearly with the number of kpoints (i.e. the number of points in the irreducible Brillouin Zone). For a large unit cell (i.e. a small BZ) it may be possible to get converged results using a single k-point. But which kpoint should we choose? For diamond we will look at 3 different k-points (0,0,0), (\u00bd,\u00bd,\u00bd) (\u00bc,\u00bc,\u00bc). Specify the kpoint in the cell file using %BLOCK KPOINTS_LIST 0.25 0.25 0.25 1.0 %ENDBLOCK KPOINTS_LIST Which gives a result closest to the converged answer? (as the diamond unit cell is rather small the 1 kpoint answer is not too close to converged. However, the observation holds true for all orthorhombic cells)","title":"Example 2 - Diamond"},{"location":"workshop/04_nmr_shiedling_efg/#part-2","text":"We now look at some more realistic examples. Oxygen-17 Oxygen is a component of many geological materials. Oxygen is also important element in organic and biological molecules since it is often intimately involved in hydrogen bonding. Solid State 17 O NMR should be a uniquely valuable probe as the chemical shift range of 17 O covers almost 1000 ppm in organic molecules. Furthermore 17 O has spin I = 5/2 and hence a net quadrupole moment. As a consequence of this the solid state NMR spectrum is strongly affected by the electric field gradient at the nucleus. Because the isotopic abundance of 17 O is very low (0.037%) and the NMR linewidths due to the electric field gradient relatively large, only limited Solid State NMR data is available. This is particularly true for organic materials. First principles calculations of 17 O NMR parameters have played a vital role in assigning experimental spectra, and developing empirical rules between NMR parameters and local atomic structure.","title":"Part 2"},{"location":"workshop/04_nmr_shiedling_efg/#example-3-alanine-a-simple-amino-acid","text":"FILES: alanine.cell alanine.param alanine.pdb OBJECTIVES: Compute the chemical shift and Electric field gradient for alanine Assign the 17 NMR spectrum Fig3. Solid-State O17 NMR spectrum of L-alanine. (b) is from MAS (magicangle- spinning) (c) is from DOR (double-orientation rotation) INSTRUCTIONS: Look at the cell and param files. The geometry for alanine was obtained by neutron diffraction and was downloaded from the Cambridge Crystallographic database. View the original pdb file note the hydrogen bonding Run the example - the calculation is not fully converged. However, the relative shift between the two sites is fairly converged. The experimental 17 O NMR spectrum shows two peaks (Fig 3 (b)) - they are very broad due to the quadrupolar coupling, and overlap. The experimental parameters are given in Table 1. Assign the two resonances A and B. Do all three computed parameters support this assignment? Table 1: Experimental 17 O NMR parameters for alanine. The two resonances are labeled A and B. Isotropic chemical shift \u03b4, quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4(A)-\u03b4 (B) (ppm) 23.5 C Q (A) (MHz) 7.86 \u03b7 Q (A) 0.28 C Q (B) (MHz) 6.53 \u03b7 Q (B) 0.70","title":"Example 3 - Alanine, a simple amino acid"},{"location":"workshop/04_nmr_shiedling_efg/#example-4-silicates-quartz-and-cristoballite","text":"FILES: quartz.cell quartz.param crist.cell crist.param OBJECTIVES: Compute the chemical shift and Electric field gradient for two silicates. Assign the 17 O NMR spectrum INSTRUCTIONS: The 17 O parameters for two silicates are reported in Table 2. From the values you compute can you tell which one is quartz? (a suitable \u03c3 ref is 263ppm) Table 2 : Experimental 17 O NMR parameters for two silicates. Isotropic chemical shift \u03b4 , quadrupolar coupling C Q , and EFG asymmetry \u03b7 Q . \u03b4 (ppm) C Q (MHz) \u03b7 Q Material A 37.2 5.21 0.13 Material B 40.8 5.19 0.19","title":"Example 4 - Silicates Quartz and Cristoballite"},{"location":"workshop/05_phonon/","text":"Phonons and Spectroscopy Tutorial The aims of this tutorial session is to introduce you to running larger-scale CASTEP jobs on supercomputer clusters, editing of input files for and setup of CASTEP jobs, and analysis of the results using standalone tools. To achieve results without waiting too long for jobs to complete the initial runs will be small ones, but the aim by the end of this afternoon should be to set up larger and more significant runs. Today's session will entirely comprise insulators or semiconductors. You may need to consult the CASTEP phonon users guide, which may be accessed here The practical will be conducted using the arc service. Make a directory called (e.g.) Phonons and copy the files h-BN.cell and h-BN.param into the new folder. A. \\Gamma \\Gamma -Point phonon in h-BN The first exercise will take you through the construction of a \\Gamma \\Gamma point phonon calculation and the generation of a simple model infrared spectrum of a semiconductor. It will also introduce you to the use of some additional analysis and visualisation tools. BN is one of a family of Nitride semiconductors, which occurs in cubic zincblende (c-BN), hexagonal wurtzite (h-BN) and graphite-like hexagonal (h-BN) polymorphs. We will calculate the phonons, infrared spectrum and Raman spectrum of h-BN. Phonon Calculation Set-up Your starting point will be the structure which is provided in the .cell file. The Phonons Manual contains a very similar example for the Wurtzite-structure polymorph of BN. Edit the .cell file using one of the text editors installed on the system (e.g. nano ). Uncomment the species_pot block and change it to read %block species_pot NCP %endblock species_pot to select norm-conserving pseudopotentials. Choose the k-point set to use \u2013 remove any block KPOINT_LIST and replace with the line kpoint_mp_grid 7 7 4 and one to specify a gamma-point phonon wavevector phonon_kpoint_mp_grid 1 1 1 Have a look in the .param file, look up the meaning of any keywords you don\u2019t know (you can use castep.serial -h ). Test your configuration using castep.serial \u2013dryrun h-BN This tells CASTEP to read the intput files and summaries the calculation in the .castep file, but does not run the electronic structure calculation. It is very useful to check syntax before submitting to a batch queue (and finding out later you\u2019d made a spelling mistake!). Check to see if any .err files are produced and fix issues, if any. If / when no errors are returned, congratulations. You have set up the input files, and you can delete the dryrun .castep file. Once you have in place the .cell and .param files you are ready to submit the CASTEP job. This is done using our general script: mpirun -n 4 castep.mpi h-BN which requests a 16-core parallel run. Use the qstat command to monitor the progress of your calculation. When it has finished, you can examine the output file h-BN.castep and find the frequencies. What you see is explained further in the Phonons user guide linked above. There is also a machine-readable file h-BN.phonon which contains the frequencies and also the eigenvectors which we will analyse. Analysis of h-BN phonon output. We will use Castep\u2019s tools to visualise the modes using the free Jmol visualiser. Use secure file transfer to copy the .phonon file back to the PC where Jmol is installed. Start Jmol and bring up a console window from the right-mouse menu. To use the full power of the command-line and find the files it is most convenient to set Jmol's current directory to the location of your working directory containing your output files. (It is possible and simpler to drag and drop the .phonon file onto Jmol window, but you need the power of the command line to display additional periodic repeats.) cd --- report the current directory cd .. or cd -- navigate up/down the directory tree. Then type the Jmol command to load your .castep file load h-BN.phonon {3 3 2} PACKED Note that while you can read in the .phonon file from Jmol's File menu, you need the additional opitions of the command line to display additional periodic repeats. You can then use the Tools-Vibrate menu to turn on mode animation, and navigate the modes. Can you see from the mode eigenvectors which modes are IR-active and which are Raman active? Do you agree with the IR and Raman activity printed in the .castep file? Generation of IR spectrum The easiest way to generate a simple model IR spectrum is to use Castep\u2019s dos.pl tool. To run this in the most effective way and automatically display a plot, you will need to be running an X windows server on the PC. In that case the command dos.pl -ir -xg h-BN.phonon will generate a plot script and use the xmgrace plotting program to display it. You can create a gnuplot script instead of xmgrace by changing the -xg flag to -gp . Alternatively you can generate a GNUPLOT script without plotting by dos.pl -ir -gp -np h-BN.phonon > h-BN-phonon.plt You can then copy the h-BN-phonon.plt back to the PC and read this into GNUPLOT. Generation of Raman spectrum The calculation of a raman intensities is fairly expensive compared to infrared matrix elements and it is therefore not turned on by default however the .param file turned this on: CALCULATE_RAMAN : TRUE RAMAN_METHOD : DFPT You can use the -raman flag of dos.pl to generate and plot a Raman spectrum. B. Molecular modes in benzene The next part of this practical is to compute the modes and spectrum of a molecule and compare the result with a calculation of a molecular crystal. Our example is benzene First run the isolated molecule calculation. Using the supplied PDB format file and using the pdb2cell utility, generate a .cell file for a single molecule calculation. There are a few other considerations to take into account for an isolated molecule calculation. The size of the simulation cell governs the interactions between periodic copies of the molecule and should be large enough that these are negligible. The shape of the simulation cell governs the crystallographic point groups allowed in the handling of the symmetry. It should be chosen to be commensurate (as far as possible) with the molecular point group to maximise the use of symmetry. In the case of benzene it should obviously be hexagonal, here we use a box 8A by 8A by 4A. Recall that there is no electronic dispersion for a molecule, so only a single electronic k-point is needed. The general rule is that all \u201cmolecule in a box\u201d calculations should use the G point only as Castep uses special performance optimisations in this case. Use the norm-conserving pseudopotentials ( NCP in the species_pot block) For simplicity use the local density approximation, LDA . In benzene not all atoms are on special symmetry sites so you should first perform a geometry optimisation, keeping the unit cell fixed (see fix_all_cell keyword in Castep\u2019s help). Then set up a follow-on calculation to compute the Gamma point phonons using the continuation keyword in the .param file. The Phonons User Guide linked above should help you fill in the details, but please ask if you are stuck. Check the phonon frequencies. How many zero frequency modes are there? What frequencies do you get? Can you explain? Benzene Phase III: The next stage is to compute the \\Gamma \\Gamma point phonon modes of the molecular crystal of benzene in the high pressure polymorph, Phase III. You are supplied with a .pdb file. You should use a 2x2x2 grid of electronic k-points, as dispersion is non-zero in this molecular crystal. Make sure that symmetry is detected and enabled using symmetry_generate in the .cell file. Also check that the unit cell parameters are fixed to optimise the geometry and NCP pseudopotentials are used. Use the same .param file as for the molecular case to ensure the settings are the same. Similar to the molecular case run a geometry optimisation followed by a phonon calculation. Once these calculations have completed you should generate a phonon DOS and IR spectra as in the previous practical and compare the molecule with the molecular crystal. You can also use Jmol to identify the modes. Are all your frequencies positive? If not, can you suggest why not? C. Phonon dispersion using interpolation in NaH From \\Gamma \\Gamma point only calculations we now explore the whole of the Brillouin zone of phonon wavevectors. Our example is the rocksalt-structured hydride, NaH which should run quickly enough to return results in a few minutes. Based on previous exercises, lectures and the user manual, you should be able to set up and run a DFPT phonon dispersion calculation and display a well converged set of dispersion curves. A starting point for your .cell file is: %block lattice_cart 2.0 2.0 0.0 2.0 0.0 2.0 0.0 2.0 2.0 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 H 0.5 0.5 0.5 %endblock positions_frac Symmetry_generate This contains the primitive fcc unit cell of the B1 rocksalt structure with the Na ion at (0,0,0) and the H ion at (\u00bd,\u00bd,\u00bd). This is a high-symmetry structure so it is important to instruct CASTEP to generate and use the full symmetry set. Also use norm-conserving pseudopotentials. A suitable list of points for the fine q-point path for an FCC crystal is: %block phonon_fine_kpoint_path 0.0 0.0 0.0 ! Gamma 0.5 0.5 0.0 ! X (along Delta 1.0 1.0 1.0 ! Gamma (Sigma ) 0.5 0.5 0.5 ! L (Delta) 0.5 0.75 0.25 ! W (Q) 0.5 0.5 0.0 ! X (Z) %endblock phonon_fine_kpoint_path Although you can now start the phonon calculation, knowing the accuracy of the result (error bounds) is good science. You should perform a k-point convergence test. For a phonon calculation, convergence of the forces is an appropriate test criterion. Since all of the ions are on symmetry positions the forces are zero by symmetry. Try to think of a way around this obstacle. And adopt a suitable compromise between accuracy and run-time. C.II Phonon DOS using interpolation The task here is to use the NaH example to compute and display not a dispersion curve but a density of states. This will exploit CASTEPs interpolation functionality, and you will be able to compute a good DOS without the need the repeat the expensive electronic structure calculation. To do this you will need to set up a calculation neatly identical to your previous one but with two differences. The calculation should be set up as a continuation. If your previous run wrote a .check file named NaH.check for example, then the param file should contain the line continuation : NaH.check Instead of a %block phonon_fine_kpoint_list in the .cell file, you can specify a grid phonon_fine_kpoint_mp_grid 16 16 16 You can run CASTEP on just 1-4 processors for this You can try this several times with different fine q-point grids. This will produce a .castep and .phonon file as before. You may analyse the .phonon file and generate a DOS using the dos.pl script dos.pl -xg NaH-dos.phonon (again, an X server running on the PC will be needed for grace to display; MobaXterm should have this enabled by default) .","title":" 6 Phonons"},{"location":"workshop/05_phonon/#phonons-and-spectroscopy-tutorial","text":"The aims of this tutorial session is to introduce you to running larger-scale CASTEP jobs on supercomputer clusters, editing of input files for and setup of CASTEP jobs, and analysis of the results using standalone tools. To achieve results without waiting too long for jobs to complete the initial runs will be small ones, but the aim by the end of this afternoon should be to set up larger and more significant runs. Today's session will entirely comprise insulators or semiconductors. You may need to consult the CASTEP phonon users guide, which may be accessed here The practical will be conducted using the arc service. Make a directory called (e.g.) Phonons and copy the files h-BN.cell and h-BN.param into the new folder.","title":"Phonons and Spectroscopy Tutorial"},{"location":"workshop/05_phonon/#a-gammagamma-point-phonon-in-h-bn","text":"The first exercise will take you through the construction of a \\Gamma \\Gamma point phonon calculation and the generation of a simple model infrared spectrum of a semiconductor. It will also introduce you to the use of some additional analysis and visualisation tools. BN is one of a family of Nitride semiconductors, which occurs in cubic zincblende (c-BN), hexagonal wurtzite (h-BN) and graphite-like hexagonal (h-BN) polymorphs. We will calculate the phonons, infrared spectrum and Raman spectrum of h-BN. Phonon Calculation Set-up Your starting point will be the structure which is provided in the .cell file. The Phonons Manual contains a very similar example for the Wurtzite-structure polymorph of BN. Edit the .cell file using one of the text editors installed on the system (e.g. nano ). Uncomment the species_pot block and change it to read %block species_pot NCP %endblock species_pot to select norm-conserving pseudopotentials. Choose the k-point set to use \u2013 remove any block KPOINT_LIST and replace with the line kpoint_mp_grid 7 7 4 and one to specify a gamma-point phonon wavevector phonon_kpoint_mp_grid 1 1 1 Have a look in the .param file, look up the meaning of any keywords you don\u2019t know (you can use castep.serial -h ). Test your configuration using castep.serial \u2013dryrun h-BN This tells CASTEP to read the intput files and summaries the calculation in the .castep file, but does not run the electronic structure calculation. It is very useful to check syntax before submitting to a batch queue (and finding out later you\u2019d made a spelling mistake!). Check to see if any .err files are produced and fix issues, if any. If / when no errors are returned, congratulations. You have set up the input files, and you can delete the dryrun .castep file. Once you have in place the .cell and .param files you are ready to submit the CASTEP job. This is done using our general script: mpirun -n 4 castep.mpi h-BN which requests a 16-core parallel run. Use the qstat command to monitor the progress of your calculation. When it has finished, you can examine the output file h-BN.castep and find the frequencies. What you see is explained further in the Phonons user guide linked above. There is also a machine-readable file h-BN.phonon which contains the frequencies and also the eigenvectors which we will analyse. Analysis of h-BN phonon output. We will use Castep\u2019s tools to visualise the modes using the free Jmol visualiser. Use secure file transfer to copy the .phonon file back to the PC where Jmol is installed. Start Jmol and bring up a console window from the right-mouse menu. To use the full power of the command-line and find the files it is most convenient to set Jmol's current directory to the location of your working directory containing your output files. (It is possible and simpler to drag and drop the .phonon file onto Jmol window, but you need the power of the command line to display additional periodic repeats.) cd --- report the current directory cd .. or cd -- navigate up/down the directory tree. Then type the Jmol command to load your .castep file load h-BN.phonon {3 3 2} PACKED Note that while you can read in the .phonon file from Jmol's File menu, you need the additional opitions of the command line to display additional periodic repeats. You can then use the Tools-Vibrate menu to turn on mode animation, and navigate the modes. Can you see from the mode eigenvectors which modes are IR-active and which are Raman active? Do you agree with the IR and Raman activity printed in the .castep file?","title":"A. \\Gamma\\Gamma-Point phonon in h-BN"},{"location":"workshop/05_phonon/#generation-of-ir-spectrum","text":"The easiest way to generate a simple model IR spectrum is to use Castep\u2019s dos.pl tool. To run this in the most effective way and automatically display a plot, you will need to be running an X windows server on the PC. In that case the command dos.pl -ir -xg h-BN.phonon will generate a plot script and use the xmgrace plotting program to display it. You can create a gnuplot script instead of xmgrace by changing the -xg flag to -gp . Alternatively you can generate a GNUPLOT script without plotting by dos.pl -ir -gp -np h-BN.phonon > h-BN-phonon.plt You can then copy the h-BN-phonon.plt back to the PC and read this into GNUPLOT.","title":"Generation of IR spectrum"},{"location":"workshop/05_phonon/#generation-of-raman-spectrum","text":"The calculation of a raman intensities is fairly expensive compared to infrared matrix elements and it is therefore not turned on by default however the .param file turned this on: CALCULATE_RAMAN : TRUE RAMAN_METHOD : DFPT You can use the -raman flag of dos.pl to generate and plot a Raman spectrum.","title":"Generation of Raman spectrum"},{"location":"workshop/05_phonon/#b-molecular-modes-in-benzene","text":"The next part of this practical is to compute the modes and spectrum of a molecule and compare the result with a calculation of a molecular crystal. Our example is benzene First run the isolated molecule calculation. Using the supplied PDB format file and using the pdb2cell utility, generate a .cell file for a single molecule calculation. There are a few other considerations to take into account for an isolated molecule calculation. The size of the simulation cell governs the interactions between periodic copies of the molecule and should be large enough that these are negligible. The shape of the simulation cell governs the crystallographic point groups allowed in the handling of the symmetry. It should be chosen to be commensurate (as far as possible) with the molecular point group to maximise the use of symmetry. In the case of benzene it should obviously be hexagonal, here we use a box 8A by 8A by 4A. Recall that there is no electronic dispersion for a molecule, so only a single electronic k-point is needed. The general rule is that all \u201cmolecule in a box\u201d calculations should use the G point only as Castep uses special performance optimisations in this case. Use the norm-conserving pseudopotentials ( NCP in the species_pot block) For simplicity use the local density approximation, LDA . In benzene not all atoms are on special symmetry sites so you should first perform a geometry optimisation, keeping the unit cell fixed (see fix_all_cell keyword in Castep\u2019s help). Then set up a follow-on calculation to compute the Gamma point phonons using the continuation keyword in the .param file. The Phonons User Guide linked above should help you fill in the details, but please ask if you are stuck. Check the phonon frequencies. How many zero frequency modes are there? What frequencies do you get? Can you explain? Benzene Phase III: The next stage is to compute the \\Gamma \\Gamma point phonon modes of the molecular crystal of benzene in the high pressure polymorph, Phase III. You are supplied with a .pdb file. You should use a 2x2x2 grid of electronic k-points, as dispersion is non-zero in this molecular crystal. Make sure that symmetry is detected and enabled using symmetry_generate in the .cell file. Also check that the unit cell parameters are fixed to optimise the geometry and NCP pseudopotentials are used. Use the same .param file as for the molecular case to ensure the settings are the same. Similar to the molecular case run a geometry optimisation followed by a phonon calculation. Once these calculations have completed you should generate a phonon DOS and IR spectra as in the previous practical and compare the molecule with the molecular crystal. You can also use Jmol to identify the modes. Are all your frequencies positive? If not, can you suggest why not?","title":"B. Molecular modes in benzene"},{"location":"workshop/05_phonon/#c-phonon-dispersion-using-interpolation-in-nah","text":"From \\Gamma \\Gamma point only calculations we now explore the whole of the Brillouin zone of phonon wavevectors. Our example is the rocksalt-structured hydride, NaH which should run quickly enough to return results in a few minutes. Based on previous exercises, lectures and the user manual, you should be able to set up and run a DFPT phonon dispersion calculation and display a well converged set of dispersion curves. A starting point for your .cell file is: %block lattice_cart 2.0 2.0 0.0 2.0 0.0 2.0 0.0 2.0 2.0 %endblock lattice_cart %block positions_frac Na 0.0 0.0 0.0 H 0.5 0.5 0.5 %endblock positions_frac Symmetry_generate This contains the primitive fcc unit cell of the B1 rocksalt structure with the Na ion at (0,0,0) and the H ion at (\u00bd,\u00bd,\u00bd). This is a high-symmetry structure so it is important to instruct CASTEP to generate and use the full symmetry set. Also use norm-conserving pseudopotentials. A suitable list of points for the fine q-point path for an FCC crystal is: %block phonon_fine_kpoint_path 0.0 0.0 0.0 ! Gamma 0.5 0.5 0.0 ! X (along Delta 1.0 1.0 1.0 ! Gamma (Sigma ) 0.5 0.5 0.5 ! L (Delta) 0.5 0.75 0.25 ! W (Q) 0.5 0.5 0.0 ! X (Z) %endblock phonon_fine_kpoint_path Although you can now start the phonon calculation, knowing the accuracy of the result (error bounds) is good science. You should perform a k-point convergence test. For a phonon calculation, convergence of the forces is an appropriate test criterion. Since all of the ions are on symmetry positions the forces are zero by symmetry. Try to think of a way around this obstacle. And adopt a suitable compromise between accuracy and run-time.","title":"C. Phonon dispersion using interpolation in NaH"},{"location":"workshop/05_phonon/#cii-phonon-dos-using-interpolation","text":"The task here is to use the NaH example to compute and display not a dispersion curve but a density of states. This will exploit CASTEPs interpolation functionality, and you will be able to compute a good DOS without the need the repeat the expensive electronic structure calculation. To do this you will need to set up a calculation neatly identical to your previous one but with two differences. The calculation should be set up as a continuation. If your previous run wrote a .check file named NaH.check for example, then the param file should contain the line continuation : NaH.check Instead of a %block phonon_fine_kpoint_list in the .cell file, you can specify a grid phonon_fine_kpoint_mp_grid 16 16 16 You can run CASTEP on just 1-4 processors for this You can try this several times with different fine q-point grids. This will produce a .castep and .phonon file as before. You may analyse the .phonon file and generate a DOS using the dos.pl script dos.pl -xg NaH-dos.phonon (again, an X server running on the PC will be needed for grace to display; MobaXterm should have this enabled by default) .","title":"C.II Phonon DOS using interpolation"},{"location":"workshop/07_xc/","text":"XC-Functionals Introduction These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these functionals. They will also demonstrate the effect of chosen functional upon different physical properties. It is important to remember throughout that no XC functional is perfect (as discussed in the XC functional talk). In choosing a functional, we must be guided by an understanding of the XC functional itself and the physics of the system under consideration. It is also important to realise that sometimes ''inappropriate functionals get the 'right' answer for the wrong reasons!'' Some of these exercises will further illustrate this point. Many of the post-LDA functionals (HF, sX-LDA) are computationally intensive. For that reason, this practical session focusses upon small systems. However, by the end of this session you should be able to set up more complex and demanding systems. Where To Find Help If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep -help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep -help kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep -help search symmetry Finally, to list all keywords, use: $ castep -help search all Example 1 - Si: LDA and GGA In this first exercise, we shall explore how to use different XC functionals to determine the electronic structure of silicon. Get the files required for this exercise : Si2 files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. You can use: tar -xvf Si2.tar.gz We will begin by performing a simple band structure calculation. To do this, we must edit the Si2.param file. Open this file. Find the line that says task: . Amend this to say: task : bandstructure We can also choose the XC functional that we wish to employ in the param file. If we set xc_functional : lda then we will run a calculation using the LDA. This is the functional that will be employed in the SCF calculation that determines the ground state electronic density. If we do not specify otherwise, then it will also be used for the band structure calculation. Now we shall examine the .cell file. Open Si2.cell . Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including: %block species_pot NCP %endblock species_pot in your .cell file. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path: %block bs_kpoint_path 0.5 0.5 0.5 0.0 0.0 0.0 0.5 0.0 0.5 0.625 0.25 0.625 0.0 0.0 0.0 %endblock bs_kpoint_path Add this block to the .cell file. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. Now run CASTEP on arcus using the 2-atom input files. $ castepsub -n Number Si2 where Number should be replaced by the number of processors that you wish to use. This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Note down how long the calculation takes for each k-point. We will now analyse the band structure. We can produce a plot of this from the Si2.bands file using: dispersion.pl -xg -bs Si2.bands Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this? I recommend that you save the output from this calculation as Si2_lda or similar as later on we wish to compare with GGA and non-local calculations. Repeat steps 1-8 using a GGA functional. To change the functional employed, amend the .param file as follows: xc_functional : pw91 There is no single unique flavour of GGA, and this specifies the Perdew-Wang 91 implementation of the GGA. Other flavours such as PBE would be specified in similar fashion. How does the use of the GGA affect the band gap? Does it improve upon the LDA value? Why? Example 2 - Si: Non-local functionals We shall now move onto examining what happens with a non-local functional. In principle, we should, for a new functional, determine a ground state electronic density that is consistent with the functional employed. However, CASTEP allows us to be more flexible and to specify a different functional for the band structure calculation. We will use this to save some computational effort by using a LDA-derived ground state density. To begin, carry out a single-point energy calculation on our silicon system using the LDA. This calculation will be very quick. Alongside the .castep file, CASTEP there will also be a file Si2.check. This is the restart file. We will use this restart file to perform a band structure calculation using a different functional from that employed for the SCF. In the Si2.param file, add the following line: continuation : default This tells CASTEP that this is a re-start, and that the restart file is the default, which in this case is Si2.check. We could specify a different file here, if we wished. Add the following line to the .param file: bs_xc_functional : HF This allows us to specify a different functional for the band structure calculation, which in this case will be a Hartree-Fock calculation. However, we are using a LDA-derived ground state density to feed into this calculation. Now run the band structure calculation as before. When examining the .castep output look at the band structure timings. How do these compare to the LDA and GGA cases performed earlier? This should give some idea as to the more computationally intensive nature of a non-local calculation. Similarly, how do the memory estimates change? It is important to understand that this increased memory overhead can limit non-local calculations, even on HPC platforms (indeed, it can be more of a problem than the increased computational effort per step of the calculation). Plot the resulting band structure. How does this compare to the LDA and GGA values? How does the band gap compare? Why is this? Repeat steps 1-5, but for screened exchange with LDA correlation (sX-LDA). To do this, in Step 3 set bs_xc_functional : sX-lda Example 3 - FeO and DFT+U In the XC Functional talk, data were shown illustrating the effect of functional upon the electronic structure of antiferromagnetic FeO. In this example you will learn how to perform DFT+U calculations. Get the files required for this exercise : FeO Files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .cell file. We are interested in examining an anti-ferromagnetic structure. Note the following in the block where the atomic positions are specified: Fe 0.0 0.0 0.0 spin=-4.0 Fe 0.0 0.0 0.0 spin=4.0 This specifies the initial antiferromagnetic spin arrangement, with spin = N_\\text{up}-N_\\text{down} N_\\text{up}-N_\\text{down} defining the initial spin polarisation on each Fe atom. NOTE: the spins specified here should be consistent with the overall spin (i.e. the initial number of unpaired electrons) specified in the .param file using the spin keyword. In this case, as the overall spin is zero (which is the CASTEP default value), we do not need to specify this, but if we examined a ferromagnetic structure then we would. CONVERGENCE NOTE: I suggest using a 6x6x6 MP grid. While not as converged as one would desire for serious science, this is sufficient for demonstrative purposes, and will allow us to perform several calculations in the time available. As we saw in the XC presentation, PBE obtains a metallic ground state for antiferromagnetic FeO. We shall therefore run this calculation as a metal. Ensure that the .param file has the following line: fix_occupancy : false which allows CASTEP to vary electronic occupancies. We shall use the default metals method, which is density mixing. Density mixing is the only method in CASTEP that allows us to specify initial magnetic moments on atoms. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 4. As we wish to examine an anti-ferromagnetic structure in which individual Fe ions have non-zero spin, we must allow the system to be spin-polarised. To do this, open up and edit the .param file. Set: spin_polarized : true 5. We will set the XC functional to be the PBE flavour of GGA ( xc_functional : pbe ). Now run a band structure calculation and produce a band structure plot as before. There are certain features of the band structure plot that you should understand: the dispersive bands are ''sp'' bands derived from ''s'' and ''p'' electrons. The flat non-dispersive bands are derived from Fe ''d'' electrons. Can you explain why the ''d'' bands are so flat? When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section Atomic Populations (Mulliken) Note the spin on each Fe atom. How does this vary from the initial value specified? A DFT+U calculation To do this, open up and edit the .cell file. Add the following block to it: %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use ab initio calculations to determine a value of U then specify this in the .cell file. Run a band structure calculation and plot the results. How does this band structure compare to the PBE+U result? Can you explain which features change and which stay the same? What happens to the band gap? Now examine the spin on each Fe atom. Compare to the PBE values. Can you explain your observations? Repeat steps 7-9 for differing U values. Explain your findings. Example 4 - Graphite and DFT+D Graphite represents a prototypical example of a layered system in which the layers are weakly bound by van der Waals forces. As is well known, local and semi-local functionals such as the LDA and GGA neglect such interactions, and we could perhaps anticipate that they therefore perform poorly for such a system. We will explore the performance of these functionals. This example will also show you how to run dispersion corrected DFT+D functionals. Get the files required for this exercise : Graphite files As before, we shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .param file using a text editor. We will do our first calculation with the PBE GGA functional. Ensure that this is the xc functional specified (see above if you cannot recall how to do this). Graphite has a semimetallic nature, with a non-zero DOS at the Fermi energy for the K and H points in reciprocal space. We will therefore run this calculation as a metal, as we did in the FeO example. Modify the .param file to ensure that this is the case. In contrast to FeO, however, we do not need to worry about spin polarisation. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 We will run a geometry optimisation. Change the .param file so that this is the task. Now open up the .cell file using a text editor. We will perform our calculations for the experimental graphite structure. However, our atomic positions are slightly incommensurate with the symmetry of the unit cell; to remedy this, add the following line to the .cell file: snap_to_symmetry which puts the atoms on the symmetry positions. Now run a variable cell geometry optimisation. If you cannot recall how to do this, consult the earlier tutorial concerning geometry optimisations. Ensure that the calculation is converged with respect to both plane wave and k-point sampling. As we are interested in a geometry optimisation, examining the convergence with respect to force is a suitable criterion. However, as we have placed the ions on high symmetry positions, the forces on them will be zero by symmetry - can you think of how we can still examine the convergence of forces, given this fact? Once the calculation has completed, examine the unit cell parameters - how do they compare to the original (experimental) parameters? Can you explain this behaviour? We shall now investigate what happens with LDA. Repeat the above calculation with the LDA as the XC functional. What happens to the unit cell parameters in this case? Pay particular attention to the c axis. How does this compare to the GGA value? Is this behaviour expected? Can you explain it? Does this mean that LDA is particularly suitable to use to describe van der Waals bound systems? We shall now carry out a GGA calculation with a DFT+D correction. For this you can leave the .cell file unaltered. Open up the .param file using an editor. Add the following line: sedc_apply : true which tells CASTEP that it should apply the semi-empirical dispersion correction (i.e. DFT+D). Now specify the correction scheme. Begin with the G06 scheme (also known as D2): sedc_scheme : g06 Ensure that the XC functional to use is the PBE. Run the geometry optimisation. How do the results compare to the LDA and GGA answers? Repeat 10-13 but using the D4 correction scheme. How do the results change? NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution. NOTE2: the OBS scheme is not compatible with the PBE functional. Further examples If you have worked through to this point in the tutorial, then feel free to apply these functionals to some more sophisticated systems that interest you. If you do not have particular systems in mind, then feel free to discuss possible choices with a demonstrator.","title":" 8 XC"},{"location":"workshop/07_xc/#xc-functionals","text":"","title":"XC-Functionals"},{"location":"workshop/07_xc/#introduction","text":"These exercises are intended to introduce you to some of the XC functionals available in CASTEP. They will show you how to choose and set up calculations using these functionals. They will also demonstrate the effect of chosen functional upon different physical properties. It is important to remember throughout that no XC functional is perfect (as discussed in the XC functional talk). In choosing a functional, we must be guided by an understanding of the XC functional itself and the physics of the system under consideration. It is also important to realise that sometimes ''inappropriate functionals get the 'right' answer for the wrong reasons!'' Some of these exercises will further illustrate this point. Many of the post-LDA functionals (HF, sX-LDA) are computationally intensive. For that reason, this practical session focusses upon small systems. However, by the end of this session you should be able to set up more complex and demanding systems.","title":"Introduction"},{"location":"workshop/07_xc/#where-to-find-help","text":"If you want more information about a particular CASTEP keyword, or you want to find if CASTEP has particular functionality, there are a few places you can look. There is information on this website: www.castep.org . CASTEP has an in built help option to assist with using particular keywords. Information on using CASTEP can be seen by using: $ castep -help To get more information on a particular input file keyword (e.g. kpoint_mp_grid ) use: $ castep -help kpoint_mp_grid If you don't know the keyword you need to use, then you can search on a particular keyword. This returns a list of keywords that you might be interested in, e.g. to look at all keywords which contain a reference to symmetry. $ castep -help search symmetry Finally, to list all keywords, use: $ castep -help search all","title":"Where To Find Help"},{"location":"workshop/07_xc/#example-1-si-lda-and-gga","text":"In this first exercise, we shall explore how to use different XC functionals to determine the electronic structure of silicon. Get the files required for this exercise : Si2 files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. You can use: tar -xvf Si2.tar.gz We will begin by performing a simple band structure calculation. To do this, we must edit the Si2.param file. Open this file. Find the line that says task: . Amend this to say: task : bandstructure We can also choose the XC functional that we wish to employ in the param file. If we set xc_functional : lda then we will run a calculation using the LDA. This is the functional that will be employed in the SCF calculation that determines the ground state electronic density. If we do not specify otherwise, then it will also be used for the band structure calculation. Now we shall examine the .cell file. Open Si2.cell . Later in this tutorial, we shall use non-local functionals. In CASTEP, non-local functionals can only be used with norm-conserving pseudo potentials. (Question: Do you understand as to why this should be so? Ask if you do not.) For this reason, ensure that you are using the norm-conserving pseudo potential library by including: %block species_pot NCP %endblock species_pot in your .cell file. We will also need to set up an appropriate k-point path for the band structure calculation. We will use the following path: %block bs_kpoint_path 0.5 0.5 0.5 0.0 0.0 0.0 0.5 0.0 0.5 0.625 0.25 0.625 0.0 0.0 0.0 %endblock bs_kpoint_path Add this block to the .cell file. Ensure that your calculation is converged with respect to both kinetic energy cut-off and k-point sampling. Now run CASTEP on arcus using the 2-atom input files. $ castepsub -n Number Si2 where Number should be replaced by the number of processors that you wish to use. This should only take a few seconds and produce a readable output file Si2.castep . Examine this file and try to understand the meaning of the various parts. In particular check the section following the header which lists all of the input parameters, both explicit and default. Note what default values of the major parameters CASTEP chose where you did not specify them explicitly. (There will be some whose meaning has not been explained. Don't worry about these.) Note down how long the calculation takes for each k-point. We will now analyse the band structure. We can produce a plot of this from the Si2.bands file using: dispersion.pl -xg -bs Si2.bands Using the band structure plot, determine the band gap. How does this compare to the experimental value? Can you explain this? I recommend that you save the output from this calculation as Si2_lda or similar as later on we wish to compare with GGA and non-local calculations. Repeat steps 1-8 using a GGA functional. To change the functional employed, amend the .param file as follows: xc_functional : pw91 There is no single unique flavour of GGA, and this specifies the Perdew-Wang 91 implementation of the GGA. Other flavours such as PBE would be specified in similar fashion. How does the use of the GGA affect the band gap? Does it improve upon the LDA value? Why?","title":"Example 1 - Si: LDA and GGA"},{"location":"workshop/07_xc/#example-2-si-non-local-functionals","text":"We shall now move onto examining what happens with a non-local functional. In principle, we should, for a new functional, determine a ground state electronic density that is consistent with the functional employed. However, CASTEP allows us to be more flexible and to specify a different functional for the band structure calculation. We will use this to save some computational effort by using a LDA-derived ground state density. To begin, carry out a single-point energy calculation on our silicon system using the LDA. This calculation will be very quick. Alongside the .castep file, CASTEP there will also be a file Si2.check. This is the restart file. We will use this restart file to perform a band structure calculation using a different functional from that employed for the SCF. In the Si2.param file, add the following line: continuation : default This tells CASTEP that this is a re-start, and that the restart file is the default, which in this case is Si2.check. We could specify a different file here, if we wished. Add the following line to the .param file: bs_xc_functional : HF This allows us to specify a different functional for the band structure calculation, which in this case will be a Hartree-Fock calculation. However, we are using a LDA-derived ground state density to feed into this calculation. Now run the band structure calculation as before. When examining the .castep output look at the band structure timings. How do these compare to the LDA and GGA cases performed earlier? This should give some idea as to the more computationally intensive nature of a non-local calculation. Similarly, how do the memory estimates change? It is important to understand that this increased memory overhead can limit non-local calculations, even on HPC platforms (indeed, it can be more of a problem than the increased computational effort per step of the calculation). Plot the resulting band structure. How does this compare to the LDA and GGA values? How does the band gap compare? Why is this? Repeat steps 1-5, but for screened exchange with LDA correlation (sX-LDA). To do this, in Step 3 set bs_xc_functional : sX-lda","title":"Example 2 - Si: Non-local functionals"},{"location":"workshop/07_xc/#example-3-feo-and-dftu","text":"In the XC Functional talk, data were shown illustrating the effect of functional upon the electronic structure of antiferromagnetic FeO. In this example you will learn how to perform DFT+U calculations. Get the files required for this exercise : FeO Files We shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .cell file. We are interested in examining an anti-ferromagnetic structure. Note the following in the block where the atomic positions are specified: Fe 0.0 0.0 0.0 spin=-4.0 Fe 0.0 0.0 0.0 spin=4.0 This specifies the initial antiferromagnetic spin arrangement, with spin = N_\\text{up}-N_\\text{down} N_\\text{up}-N_\\text{down} defining the initial spin polarisation on each Fe atom. NOTE: the spins specified here should be consistent with the overall spin (i.e. the initial number of unpaired electrons) specified in the .param file using the spin keyword. In this case, as the overall spin is zero (which is the CASTEP default value), we do not need to specify this, but if we examined a ferromagnetic structure then we would. CONVERGENCE NOTE: I suggest using a 6x6x6 MP grid. While not as converged as one would desire for serious science, this is sufficient for demonstrative purposes, and will allow us to perform several calculations in the time available. As we saw in the XC presentation, PBE obtains a metallic ground state for antiferromagnetic FeO. We shall therefore run this calculation as a metal. Ensure that the .param file has the following line: fix_occupancy : false which allows CASTEP to vary electronic occupancies. We shall use the default metals method, which is density mixing. Density mixing is the only method in CASTEP that allows us to specify initial magnetic moments on atoms. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 4. As we wish to examine an anti-ferromagnetic structure in which individual Fe ions have non-zero spin, we must allow the system to be spin-polarised. To do this, open up and edit the .param file. Set: spin_polarized : true 5. We will set the XC functional to be the PBE flavour of GGA ( xc_functional : pbe ). Now run a band structure calculation and produce a band structure plot as before. There are certain features of the band structure plot that you should understand: the dispersive bands are ''sp'' bands derived from ''s'' and ''p'' electrons. The flat non-dispersive bands are derived from Fe ''d'' electrons. Can you explain why the ''d'' bands are so flat? When examining magnetic systems, it is also often useful to examine the spin on each atom. This information can be found in the .castep file in the section Atomic Populations (Mulliken) Note the spin on each Fe atom. How does this vary from the initial value specified?","title":"Example 3 - FeO and DFT+U"},{"location":"workshop/07_xc/#a-dftu-calculation","text":"To do this, open up and edit the .cell file. Add the following block to it: %block hubbard_u Fe 1 d: 2.5 Fe 2 d: 2.5 %endblock hubbard_u This specifies a Hubbard U parameter of 2.5 eV for each Fe ion in the system. Whilst schemes exist to determine the value of U from first principles, in CASTEP it is simply specified as a parameter. Of course, one could use ab initio calculations to determine a value of U then specify this in the .cell file. Run a band structure calculation and plot the results. How does this band structure compare to the PBE+U result? Can you explain which features change and which stay the same? What happens to the band gap? Now examine the spin on each Fe atom. Compare to the PBE values. Can you explain your observations? Repeat steps 7-9 for differing U values. Explain your findings.","title":"A DFT+U calculation"},{"location":"workshop/07_xc/#example-4-graphite-and-dftd","text":"Graphite represents a prototypical example of a layered system in which the layers are weakly bound by van der Waals forces. As is well known, local and semi-local functionals such as the LDA and GGA neglect such interactions, and we could perhaps anticipate that they therefore perform poorly for such a system. We will explore the performance of these functionals. This example will also show you how to run dispersion corrected DFT+D functionals. Get the files required for this exercise : Graphite files As before, we shall carry out these calculations on arcus. Transfer the files to arcus, and unzip and untar them. Open the .param file using a text editor. We will do our first calculation with the PBE GGA functional. Ensure that this is the xc functional specified (see above if you cannot recall how to do this). Graphite has a semimetallic nature, with a non-zero DOS at the Fermi energy for the K and H points in reciprocal space. We will therefore run this calculation as a metal, as we did in the FeO example. Modify the .param file to ensure that this is the case. In contrast to FeO, however, we do not need to worry about spin polarisation. The convergence of calculations on metallic systems is often improved by the inclusion of a number of extra empty bands. We can specify this using the nextra_bands keyword. Set this to 14 with: nextra_bands : 14 We will run a geometry optimisation. Change the .param file so that this is the task. Now open up the .cell file using a text editor. We will perform our calculations for the experimental graphite structure. However, our atomic positions are slightly incommensurate with the symmetry of the unit cell; to remedy this, add the following line to the .cell file: snap_to_symmetry which puts the atoms on the symmetry positions. Now run a variable cell geometry optimisation. If you cannot recall how to do this, consult the earlier tutorial concerning geometry optimisations. Ensure that the calculation is converged with respect to both plane wave and k-point sampling. As we are interested in a geometry optimisation, examining the convergence with respect to force is a suitable criterion. However, as we have placed the ions on high symmetry positions, the forces on them will be zero by symmetry - can you think of how we can still examine the convergence of forces, given this fact? Once the calculation has completed, examine the unit cell parameters - how do they compare to the original (experimental) parameters? Can you explain this behaviour? We shall now investigate what happens with LDA. Repeat the above calculation with the LDA as the XC functional. What happens to the unit cell parameters in this case? Pay particular attention to the c axis. How does this compare to the GGA value? Is this behaviour expected? Can you explain it? Does this mean that LDA is particularly suitable to use to describe van der Waals bound systems? We shall now carry out a GGA calculation with a DFT+D correction. For this you can leave the .cell file unaltered. Open up the .param file using an editor. Add the following line: sedc_apply : true which tells CASTEP that it should apply the semi-empirical dispersion correction (i.e. DFT+D). Now specify the correction scheme. Begin with the G06 scheme (also known as D2): sedc_scheme : g06 Ensure that the XC functional to use is the PBE. Run the geometry optimisation. How do the results compare to the LDA and GGA answers? Repeat 10-13 but using the D4 correction scheme. How do the results change? NOTE1: the TS scheme is not particularly suitable for such a small unit cell, as the code will warn you. The results should therefore be treated with caution. NOTE2: the OBS scheme is not compatible with the PBE functional.","title":"Example 4 - Graphite and DFT+D"},{"location":"workshop/07_xc/#further-examples","text":"If you have worked through to this point in the tutorial, then feel free to apply these functionals to some more sophisticated systems that interest you. If you do not have particular systems in mind, then feel free to discuss possible choices with a demonstrator.","title":"Further examples"},{"location":"workshop/08_cif2cell/","text":"We will use cif to cell to generate cell files from cif files. Cif files can be obtained from the ICSD (inorganic crystals) or the CSD (molecular crystals). '''MgO''' Examine the file . Look at the crystal structure with jmol or magresview (drag and drop the file onto the magresview window). You will see a cubic face-centre cubic cell. How many atoms in the cell? Use cif2cell to convert this cif file to a cell file. cif2cell MgO.cif --program=castep -o MgO.cell Look at the cell file. How many atoms in the cell? View this will jmol or magresview. Do you understand what cif2cell has done? '''Molecular Tweezers''' Examine the file","title":" 9 Cif2cell"},{"location":"workshop/09_md/","text":"Molecular Dynamics Learning Objectives Perform ab initio molecular dynamics calculations on simple systems. Investigate factors affecting energy conservation, etc. Use various tools to visualize and analyze the results. N 2 Dimer As a simple example, we will explore the system discussed in the lecture -- the N2 dimer. Download the input files MD_N2.tar.gz Unzip and untar the files, then move into the new directory tar -xzvf MD_N2.tar.gz cd N2 Run this and then read the N2.castep file -- see how the MD information is reported. Plot a graph of temperature vs. time -- does it look correct? Hint: try grep Temp N2.castep | awk '{print c++,$3}' > N2.T to get a 2-column file of temperature vs MD step. Is there an initial transient? What is the effect of electronic convergence ( cut_off_energy , elec_energy_tol , etc) on the energy conservation? What is the effect of changing the time step or the thermostat used? Plot a graph of \"Hamilt Energy\" vs MD step to see. Make a movie of your dynamics. Load the N2.md file in jmol and use Tools/Animate to see it in action. Calculate the average bond length, as a function of temperature -- is the system harmonic or anharmonic? Hint: try something like this: grep ' N 1' N2.castep | awk '{print $4,$5,$6}' > N2.r1 grep ' N 2' N2.castep | awk '{print $4,$5,$6}' > N2.r2 paste N2.r1 N2.r2 | awk '{print c++,10.0*sqrt(($4-$11)^2+($5-$12)^2+($6-$13)^2)}' > N2.r12 H 2 Molecule Copy the N2.cell and N2.param files to a new directory, and edit them to create a suitable set of input files for the H 2 molecule. Use CASTEP to run MD on this new system for a similar amount of time. Do you have any problems? How can you solve them? Extension activities If you wish to explore further, you can use MD to study any system (aperiodic, supercell, bulk etc) that you are interested in. There are many properties that can be calculated sampled within an MD run. For example, if you have population analysis turned on, set md_sample_iter=10 to re-calculate it every 10 steps during the MD run. You can also analyse the resulting MD trajectory using tools such as mdtep . Using MDTEP MDTEP is designed to analyse a CASTEP .md file. To use it you should take the example mdtep input file and customize it as you wish and put it in the directory with your MD run. You can then use it to analyse your MD run using: mdtep mdtep_sample.input Ovito You can also use the Ovito post-processing tool which can read CASTEP output files.","title":" 4 MD"},{"location":"workshop/09_md/#molecular-dynamics","text":"","title":"Molecular Dynamics"},{"location":"workshop/09_md/#learning-objectives","text":"Perform ab initio molecular dynamics calculations on simple systems. Investigate factors affecting energy conservation, etc. Use various tools to visualize and analyze the results.","title":"Learning Objectives"},{"location":"workshop/09_md/#n2-dimer","text":"As a simple example, we will explore the system discussed in the lecture -- the N2 dimer. Download the input files MD_N2.tar.gz Unzip and untar the files, then move into the new directory tar -xzvf MD_N2.tar.gz cd N2 Run this and then read the N2.castep file -- see how the MD information is reported. Plot a graph of temperature vs. time -- does it look correct? Hint: try grep Temp N2.castep | awk '{print c++,$3}' > N2.T to get a 2-column file of temperature vs MD step. Is there an initial transient? What is the effect of electronic convergence ( cut_off_energy , elec_energy_tol , etc) on the energy conservation? What is the effect of changing the time step or the thermostat used? Plot a graph of \"Hamilt Energy\" vs MD step to see. Make a movie of your dynamics. Load the N2.md file in jmol and use Tools/Animate to see it in action. Calculate the average bond length, as a function of temperature -- is the system harmonic or anharmonic? Hint: try something like this: grep ' N 1' N2.castep | awk '{print $4,$5,$6}' > N2.r1 grep ' N 2' N2.castep | awk '{print $4,$5,$6}' > N2.r2 paste N2.r1 N2.r2 | awk '{print c++,10.0*sqrt(($4-$11)^2+($5-$12)^2+($6-$13)^2)}' > N2.r12","title":"N2 Dimer"},{"location":"workshop/09_md/#h2-molecule","text":"Copy the N2.cell and N2.param files to a new directory, and edit them to create a suitable set of input files for the H 2 molecule. Use CASTEP to run MD on this new system for a similar amount of time. Do you have any problems? How can you solve them?","title":"H2 Molecule"},{"location":"workshop/09_md/#extension-activities","text":"If you wish to explore further, you can use MD to study any system (aperiodic, supercell, bulk etc) that you are interested in. There are many properties that can be calculated sampled within an MD run. For example, if you have population analysis turned on, set md_sample_iter=10 to re-calculate it every 10 steps during the MD run. You can also analyse the resulting MD trajectory using tools such as mdtep .","title":"Extension activities"},{"location":"workshop/09_md/#using-mdtep","text":"MDTEP is designed to analyse a CASTEP .md file. To use it you should take the example mdtep input file and customize it as you wish and put it in the directory with your MD run. You can then use it to analyse your MD run using: mdtep mdtep_sample.input","title":"Using MDTEP"},{"location":"workshop/09_md/#ovito","text":"You can also use the Ovito post-processing tool which can read CASTEP output files.","title":"Ovito"},{"location":"workshop/10_GA/","text":"Introduction In this practical we will gain hands on experience using the CASTEP GA to find some `unknown' structures. We will then utilise an on-the-fly machine learned GAP potential to reduce the cost of an ab-initio geometry optimisation. Throughout this practical we will make use of the Stillinger-Weber (SW) pair potential. This allows GA runs to be carried out in a short time on desktops, though all of the approaches translate directly to ab-initio methods. Pair potentials (PP) are fast but far from perfect. Specifically, resultant cells from PP GA runs may not match structures found in nature (or with DFT), but instead be the lowest enthalpy cells based in the PP energy landscape. N.B. The CASTEP GA (specifically the convex hull algorithm) is currently in development. This means that some of the devel code parameters will be promoted to standard input flags. Therefore, the exact keywords used for some of the options in this practical may differ from the release version (though all the functionality will be there). Therefore, if using the GA in future the documentation should be consulted first. As a quick recap the CASTEP GA has 7 main steps: Generate an initial randomised population of parent cells. Perform a geometry optimisation to relax the parents & find their enthalpy based fitness. Select parents based on their fitness for breeding and breed to create a population of children. Mutate the children with a given probability (and to ensure no ionic overlaps). Relax these children with a geometry optimisation & find the enthalpy based fitness of patents and children. If the population has converged, or we have reach maximum allowed generations, then exit. Select members of parents and children based of fitness to be the next generation of parents and go to 3. Setup In this workshop we will be running on a remote machine, teaching0 . However, you can also access all the files in your user directory from the desktop machines. This means, if you would prefer to edit or view files on the desktops rather than the command line you can. All CASTEP commands must however be carried out on the command line on teaching0 . We should then log on to teaching0 using ssh -Y USER@teaching0 where USER should be replaced with your username. We then need to load the environment that contains all the programs we will need ( castep.mpi , castep_GA etc) with source /tmp/castep_GA_workshop_venv/bin/activate This should make everything we need available to us and you should now see (castep_GA_workshop_venv) USER@teaching0: on your command line. Note: if the terminal window is closed, or we disconnect from teaching0 this source command will have to be re-ran to re-load all the required packages. You should be in your home directory, so now extract the GA workshop files into your home directory tar -zxf /tmp/CASTEP_workshop_GA.tar.gz which should create the directory CASTEP_workshop_GA containing all the files we will need in this workshop. Move into this directory with cd CASTEP_workshop_GA CASTEP GA for Ground State Silicon Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA! Input Files First navigate to the directory cd CASTEP_workshop_GA/1_Si_SW_GA which should contain a CASTEP Si.cell and Si.param file, as well as the bash script get_data.sh and a python script plot_results.py (which we will use for results analysis later). Like standard CASTEP, the CASTEP GA requires both a cell and a param file input. However, we likely do not know what the best cell structure is. As such, we give a cell that contains multiple ions of the species that we are interested in. The number of ions given in this cell is used as a baseline for the number of ions in cells created & bred over the course of the GA, where at least one ion of each species will always be represented at least once in each cell. We can also fix the number of ions in each population member to match that in the input cell. We should not add too few ions, as cells with more ions contain more `genetic information', meaning smaller cells don't benefit from breeding operations as much. The exact positions of the ions in the input cell file does not matter, as they will be randomised during the initial population generation. However, the cell given should be a `reasonable' guess w.r.t. the cell density (as the density of the input cell is used when creating the initial randomised population). I.e. the total density of the input cell should not be unreasonable, though the exact ionic positions do not matter. For example, looking at the Si.cell in ./1_Si_SW_GA/Si.cell we see the cell is cubic with a not unreasonable volume for 8 Si ions, though the positions of those 8 ions is random. The param file is similar to a standard CASTEP input file, with some extra GA specific parameters. The GA copies all of the parameters to each bred population member, changing only the task to geometry optimization , before performing geometry optimisations for fitness evaluation. This means we can use any of the tools CASTEP has available during the populations geometry optimisation. N.B. any GA parameters passed to a standard CASTEP geometry optimisation, e.g. ga_pop_size , are ignored by CASTEP. Looking at the Si.param file we see the task is set to genetic algor and we are running with a population size of 12 over 12 generations. There are a few GA specific parameters given in the devel code block, the main ones are CMD: mpirun -n 1 castep.mpi :ENDCMD This gives the command that will be used to call CASTEP to perform the geometry optimisations on each population member. This can be changed to any valid call, for example to run over many cores. A serial calculation is used here as we are using cheap pair potentials. AS=T and MS=3 This allows asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. These parameters are chosen due to computational resources available in this workshop, but can be trivially increased based on available resources. The large comment block at the bottom of the input file lists a lot of parameters that can be used with the various GA methods currently implemented. However, for now let's run a GA! Running the CASTEP GA (Approx. 5-6 mins runtime) First lets check our CASTEP and CASTEP GA binaries are accessible by running: which castep_GA && which castep.mpi This should return something like /tmp/castep_GA_workshop_venv/bin/castep_GA /tmp/castep_GA_workshop_venv/bin/castep.mpi Your paths may differ but as long as this command completes without error everything we need is (hopefully) set up correctly. To run CASTEP GA simply call castep_GA Si and the GA will start, which will take approximately 5-6 minutes to run. While this is running have a look at the next subsection for a description of the output files that are being created. CASTEP GA Output Files The CASTEP GA generates a lot of output files; as well as a main GA output .castep there are also input and output files for each population member. The population member seeds are labeled with the generation and population number, for example Si.gen_002_mem_006.cell is the input cell file for the 6 th member of generation 2. You should see input files being generated periodically (a generation at a time). In-between the output file generation geometry optimisations are automatically performed on each population member (here asynchronously 3 at a time). If the Si CASTEP run we started in the last section is still running we can have a look at the main output file. In a new terminal window navigate to ./CASTEP_workshop_GA/1_Si_SW_GA and run tail -f Si.castep This will show us the output of the main GA Si.castep file being generated in real time. The main output file contains a lot of information and can be a bit overwhelming. It gives all the parent structures and the pre and post geometry optimisation child structures as well as information about mutation operations. Once this GA run has completed move on to the next section to analyse our output files. Analysing the GA Output Files The GA saves the post geometry optimisation structures from all evaluated population members in the file .xyz in standard xyz format. We can view a nice animation of all of the structures the GA explored with jmol by opening this xyz file in jmol with Jmol.jar Si.xyz then going to tools -> animate -> once . In order to analyse the structures created by the GA in more detail we could look at just the enthalpy of the structures, where we may be most interested in the lowest enthalpy structure found. The GA always takes the lowest enthalpy cell into the next generation, so we can look at the last generation to find the lowest enthalpy cell with grep Si.castep -e \"GA: gen # 12\" | tail -n 24 | sort -k10,10g which gives the final generation in order of enthalpy (in eV/ion). However, we gain a lot of information about the phase space with the other cells the GA finds on the way to the minimum enthalpy cell. To explore this a bit more run ./get_data.sh You may need to make this executable by running chmod u+x get_data.sh . This script generates an output file out.put that contains a summary of the data for each population member in 9 columns: Generation number. Parent or child. Member number. Error file detected (T or F). Geometry optimisation converged (T or F). Number of ions in the cell. Enthalpy per ion of converged cell (in eV/ion). Volume of converged cell (in Angstrom/ion). Member filename. We can then plot the population as the enthalpy (per ion) against the cell volume (per ion) by running the python script python plot_results.py This will produce two plots; one is an animation of the population members in each generation, the other is every explored population member over all generations with the lowest enthalpy structure labeled. It will also save these to the current directory. From this representation we can gain information about the phase space of SW Si, where the lower enthalpy structures represent structures on the energy-volume curve for SW Si. There are also structures found by the GA above the energy-volume curve that are likely unstable. We can have a look at the structure of the lowest enthalpy cell (as labeled on your graph) with jmol (or your crystal structure viewing program of choice). If using jmol run Jmol.jar -out.cell where is the seed of the lowest enthalpy population member given on the output graph and the -out.cell postfix gives us the structure post geometry optimisation (it is important to look at this cell rather than the input cell). For example, for me (though your seed may be different than this) this is Jmol.jar Si.gen_006_mem_012-out.cell It can sometimes be difficult to figure out the exact space group of crystals from a visual inspection. So, we can use c2x to find the space group of our lowest enthalpy cell within a tolerance with c2x --int -e=0.1-0.0001 -out.cell which for my lowest enthalpy member is c2x --int -e=0.1-0.0001 Si.gen_006_mem_012-out.cell For me this gives the output Tol=0.001 International symmetry is Fd-3m which is the diamond structure space group we would expect for Si. GA Continuation (Approx. 2 mins runtime) It is possible you won't find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure (or one close to it, remember the GA is a coarse search) as there is some randomness in a GA run and our population size and number of generations is small. But don't worry, it is possible to restart a GA run from exactly where you left off. Let's do this now (even if you did find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure). To perform a continuation open the Si.param file in your text editor of choice. We then tell CASTEP GA we want to continue from where we left off. We do this by giving the location of the .xyz file that contains all explored structures by uncommenting the following in the Si.param file # continuation = Si.xyz so it reads continuation = Si.xyz Also, we want to run for more generations, so change the value for ga_max_gens from 12 to 18 (to run 6 more generations) i.e. in the Si.param file change the line ga_max_gens = 12 # Max number of generations to run for to ga_max_gens = 18 # Max number of generations to run for Important: Do not change the ga_pop_size as this will cause an error. We can then call CASTEP GA as before with castep_GA Si and it will read in the members from generation 12 of our last run and start generation 13 from these. Running for generations 13 to 16 should take approximately 1-2 minutes. Have a look at the outputs of this run by re-running ./get_data.sh and then plotting with python plot_results.py You may want to have a look at the lowest enthalpy structure with Jmol. You may also want to have a look at some of the other structures that are low on the energy/volume plot (a good way to find their seed names will be from the out.put file). SiC Stillinger-Weber GA Now we will look at exploring a more complicated potential energy landscape, to do this we first navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA Luckily CASTEP allows us to add our own parameterisation values for pair potentials. A parameterisation for an SiC SW pair potential has been added to the devel code block of the parameter file SiC.param . This parameterisation leads to a more complex potential energy landscape than we saw with Si. Due to the limitations of this pair potential parameterisation the GA will find different structures than we would find with ab-inito calculations as this is a pair potential energy landscape. However, it will run quickly enough to be usable with the computational and time resources available. As such we will use the GA to explore this unknown potential energy landscape as we did with Si. N.B. Everything we are doing here works just the same with DFT. Running the CASTEP GA (Approx. 5-10 mins runtime) The SiC.param file is very similar to the one used for Si, except the initial population is no longer completely random but instead generated as random high symmetry cells. The cell file contains an equal number of Si and C ions in random positions in a not unreasonably sized cell for this many ions Si and C ions. To run CASTEP GA execute castep_GA SiC and the GA will start, which will take approximately 6-7 minutes to run. You may want to look at the outputs as we did before, or take a quick break! Analysing the GA Output Files The GA outputs for this SiC run can be analysed in the same way as in the case of Si. We can use the same scripts as earlier to create energy volume plots by running ./get_data.sh && python plot_results.py Where this energy volume graph can be analysed as with Si. Make a note of the lowest enthalpy cell for use later. If it looks like would benefit from running a few more generations, we can run a continuation using the same methods as before. Have a look at the cell of the lowest enthalpy structure. It's likely that it seems a bit different to what we would expect in nature. As such, it would be good if we could run a full DFT calculation on some of the cells that have been found by the GA rather than relying on this pair potential parameterisation. However, we are a bit limited in computer power running, with all of the previous runs using only 3 cores. To overcome this hurdle we will exploit machine learning with Gaussian approximation potentials (GAP). Gaussain Approximation Potential Accelerated Geometry Optimisation A common approach to machine learning is to train a model on some dataset of known solutions to a problem. This presents an issue with the application of machine learning to crystal structure optimisation for materials discovery as by definition the parameter landscape is not explored. One approach to this in CASTEP is to use a number of initial geometry optimisation or molecular dynamics steps ran with ab-initio methods as the initial training data. Subsequent geometry optimisation steps are then ran with a machine learned potential using Gaussian approximation potentials (GAP). Ions move over the course of geometry optimisations (or molecular dynamics calculations), therefore the landscape may change such that the potential needs some extra ab-inito data to train on. As such, CASTEP adaptively chooses geometry optimisation steps over the course of the calculation to run with DFT which are then used to re-train the GAP potential. More information about this method is available in the paper by Stenczel et al 1 . In general, less and less DFT geometry optimisation or MD steps will be required as the calculation continues and samples the parameter space more thoroughly (again see 1 ). Note: All methods that are outlined here for the acceleration of a geometry optimisation can also be directly applied to molecular dynamics calculations. In practice, as the cost savings are generally greater the more steps are in the calculation, the cost savings of GAP are greatest for long running molecular dynamics calculations. Using GAP to Accelerate a Geometry Optimisation We now navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA/DFT_polish_GAP which contains 3 files. The first is the SiC_GA_best.cell , we should open this and replace the lattice and positions blocks with those from the best cell from our previous SiC run (that we made a note of earlier, if that note is lost open the image ../all_gens.png ). For me the best cell is ../SiC.gen_009_mem_006-out.cell , but for you this could be different. The cell file we also specifies the QC5 pseudopotential library, a kpoint grid spacing and that the geometry optimisation will be fixed cell. The SiC_GA_best.param file contains standard CASTEP parameters for a Damped Molecular Dynamics (DMD) geometry optimisation. Along with this is the devel code block required to call hybrid-md (which then calls gap_fit ) to perform the GAP fitting. Finally, there is an extra input file required for a GAP run, the .hybrid-md-input.yaml file. This contains specific inputs relating to the GAP fitting. Here we specify a mandatory 10 initial DFT steps for the initial training dataset. After this we specify a minimum of 10 steps with the machine learned potential before re-fitting, whilst allowing CASTEP to vary the number of steps between re-fittings. We also allow GAP to also parellise over 3 cores. N.B. The GAP run we carry out here has rather coarse convergence parameters, designed to allow for a fast run on a desktop in this workshop. Running CASTEP with GAP (Approx. 10-15 mins runtime) To run CASTEP to perform the damped MD geometry optimisation with the aid of GAP call mpirun -n 3 castep.mpi SiC_GA_best Whilst this is running (which will take 10 to 15 minutes) there will be information printed to the terminal window each DMD step. This states if the step is an initial (DFT) step, if the step is using the machine learned potential or if it is being ran with DFT in order to perform a re-fit. It may be illustrative to open a new terminal window, navigate to the working directory and tail the .castep output file with tail -f SiC_GA_best.castep in order to see the geometry optimisation running. Notice the steps using the machine learned potential are essentially free when compared with the DFT steps that require SCF calculations. Looking at the GAP Geometry Optimisation Results First, let us consider the cost of this geometry optimisation. My calculation ran for a total of 152 DMD steps, though your mileage may vary. Using the following command we can see on which DMD steps CASTEP decided to perform DFT calculations grep SiC_GA_best.castep -e \"Decided to perform\" We can also see how many of the DMD steps utilised DFT grep SiC_GA_best.castep -e \"Decided to perform\" | wc -l In my case this showed that 22 of the total DMD steps were using DFT, therefore approximately 85% of the DMD steps were carried out with the machine learned potential. Though there is a cost associated with these steps and with the re-fitting of the GAP potential, it is clear this represents a large cost saving. Very roughly (based on average time for one SCF cycle in my DMD run) without GAP this run would have taken approximately 4 times as long for no extra information. We can also visualize (using jmol or similar) both the output structure from the DMD run ( SiC_GA_best-out.cell ) and the pre-geometry optimisation structure ( SiC_GA_best.cell ). It is likely these are quite different. This is due to the difference (and lower quality!) of the SW parameterisation compared with any DFT approach. (Optional Extension) Running GA with Other Systems You may also want to try the CASTEP GA with another system or pair potential parameterisation (it is likely not possible to run a full DFT run of the GA in the timescale of this practical). If this is the case you can use the blank input file in ./CASTEP_workshop_GA/2.5_GA_blank (Optional Extension) Running GAP with Other Systems If you are interested in applying GAP to your calculations you may want to try GAP with a material of interest to you. If you would like to try with a cell and parameters of your choice there are blank input files in ./CASTEP_workshop_GA/2.5_GAP_blank Footnotes 1 Tam\u00e1s K. Stenczel, Zakariya El-Machachi, Guoda Liepuoniute, Joe D. Morrow, Albert P. Bart\u00f3k, Matt I. J. Probert, G\u00e1bor Cs\u00e1nyi, Volker L. Deringer; Machine-learned acceleration for molecular dynamics in CASTEP. J. Chem. Phys. 28 July 2023; 159 (4): 044803. https://doi.org/10.1063/5.0155621","title":"10 Genetic Algorithm"},{"location":"workshop/10_GA/#introduction","text":"In this practical we will gain hands on experience using the CASTEP GA to find some `unknown' structures. We will then utilise an on-the-fly machine learned GAP potential to reduce the cost of an ab-initio geometry optimisation. Throughout this practical we will make use of the Stillinger-Weber (SW) pair potential. This allows GA runs to be carried out in a short time on desktops, though all of the approaches translate directly to ab-initio methods. Pair potentials (PP) are fast but far from perfect. Specifically, resultant cells from PP GA runs may not match structures found in nature (or with DFT), but instead be the lowest enthalpy cells based in the PP energy landscape. N.B. The CASTEP GA (specifically the convex hull algorithm) is currently in development. This means that some of the devel code parameters will be promoted to standard input flags. Therefore, the exact keywords used for some of the options in this practical may differ from the release version (though all the functionality will be there). Therefore, if using the GA in future the documentation should be consulted first. As a quick recap the CASTEP GA has 7 main steps: Generate an initial randomised population of parent cells. Perform a geometry optimisation to relax the parents & find their enthalpy based fitness. Select parents based on their fitness for breeding and breed to create a population of children. Mutate the children with a given probability (and to ensure no ionic overlaps). Relax these children with a geometry optimisation & find the enthalpy based fitness of patents and children. If the population has converged, or we have reach maximum allowed generations, then exit. Select members of parents and children based of fitness to be the next generation of parents and go to 3.","title":"Introduction"},{"location":"workshop/10_GA/#setup","text":"In this workshop we will be running on a remote machine, teaching0 . However, you can also access all the files in your user directory from the desktop machines. This means, if you would prefer to edit or view files on the desktops rather than the command line you can. All CASTEP commands must however be carried out on the command line on teaching0 . We should then log on to teaching0 using ssh -Y USER@teaching0 where USER should be replaced with your username. We then need to load the environment that contains all the programs we will need ( castep.mpi , castep_GA etc) with source /tmp/castep_GA_workshop_venv/bin/activate This should make everything we need available to us and you should now see (castep_GA_workshop_venv) USER@teaching0: on your command line. Note: if the terminal window is closed, or we disconnect from teaching0 this source command will have to be re-ran to re-load all the required packages. You should be in your home directory, so now extract the GA workshop files into your home directory tar -zxf /tmp/CASTEP_workshop_GA.tar.gz which should create the directory CASTEP_workshop_GA containing all the files we will need in this workshop. Move into this directory with cd CASTEP_workshop_GA","title":"Setup"},{"location":"workshop/10_GA/#castep-ga-for-ground-state-silicon","text":"Let's assume we don't know the ground state Stillinger-Weber silicon structure and set out to discover it using the CASTEP GA!","title":"CASTEP GA for Ground State Silicon"},{"location":"workshop/10_GA/#input-files","text":"First navigate to the directory cd CASTEP_workshop_GA/1_Si_SW_GA which should contain a CASTEP Si.cell and Si.param file, as well as the bash script get_data.sh and a python script plot_results.py (which we will use for results analysis later). Like standard CASTEP, the CASTEP GA requires both a cell and a param file input. However, we likely do not know what the best cell structure is. As such, we give a cell that contains multiple ions of the species that we are interested in. The number of ions given in this cell is used as a baseline for the number of ions in cells created & bred over the course of the GA, where at least one ion of each species will always be represented at least once in each cell. We can also fix the number of ions in each population member to match that in the input cell. We should not add too few ions, as cells with more ions contain more `genetic information', meaning smaller cells don't benefit from breeding operations as much. The exact positions of the ions in the input cell file does not matter, as they will be randomised during the initial population generation. However, the cell given should be a `reasonable' guess w.r.t. the cell density (as the density of the input cell is used when creating the initial randomised population). I.e. the total density of the input cell should not be unreasonable, though the exact ionic positions do not matter. For example, looking at the Si.cell in ./1_Si_SW_GA/Si.cell we see the cell is cubic with a not unreasonable volume for 8 Si ions, though the positions of those 8 ions is random. The param file is similar to a standard CASTEP input file, with some extra GA specific parameters. The GA copies all of the parameters to each bred population member, changing only the task to geometry optimization , before performing geometry optimisations for fitness evaluation. This means we can use any of the tools CASTEP has available during the populations geometry optimisation. N.B. any GA parameters passed to a standard CASTEP geometry optimisation, e.g. ga_pop_size , are ignored by CASTEP. Looking at the Si.param file we see the task is set to genetic algor and we are running with a population size of 12 over 12 generations. There are a few GA specific parameters given in the devel code block, the main ones are CMD: mpirun -n 1 castep.mpi :ENDCMD This gives the command that will be used to call CASTEP to perform the geometry optimisations on each population member. This can be changed to any valid call, for example to run over many cores. A serial calculation is used here as we are using cheap pair potentials. AS=T and MS=3 This allows asynchronous parellisation, where 3 population members will have geom-opts performed at the same time. These parameters are chosen due to computational resources available in this workshop, but can be trivially increased based on available resources. The large comment block at the bottom of the input file lists a lot of parameters that can be used with the various GA methods currently implemented. However, for now let's run a GA!","title":"Input Files"},{"location":"workshop/10_GA/#running-the-castep-ga-approx-5-6-mins-runtime","text":"First lets check our CASTEP and CASTEP GA binaries are accessible by running: which castep_GA && which castep.mpi This should return something like /tmp/castep_GA_workshop_venv/bin/castep_GA /tmp/castep_GA_workshop_venv/bin/castep.mpi Your paths may differ but as long as this command completes without error everything we need is (hopefully) set up correctly. To run CASTEP GA simply call castep_GA Si and the GA will start, which will take approximately 5-6 minutes to run. While this is running have a look at the next subsection for a description of the output files that are being created.","title":"Running the CASTEP GA (Approx. 5-6 mins runtime)"},{"location":"workshop/10_GA/#castep-ga-output-files","text":"The CASTEP GA generates a lot of output files; as well as a main GA output .castep there are also input and output files for each population member. The population member seeds are labeled with the generation and population number, for example Si.gen_002_mem_006.cell is the input cell file for the 6 th member of generation 2. You should see input files being generated periodically (a generation at a time). In-between the output file generation geometry optimisations are automatically performed on each population member (here asynchronously 3 at a time). If the Si CASTEP run we started in the last section is still running we can have a look at the main output file. In a new terminal window navigate to ./CASTEP_workshop_GA/1_Si_SW_GA and run tail -f Si.castep This will show us the output of the main GA Si.castep file being generated in real time. The main output file contains a lot of information and can be a bit overwhelming. It gives all the parent structures and the pre and post geometry optimisation child structures as well as information about mutation operations. Once this GA run has completed move on to the next section to analyse our output files.","title":"CASTEP GA Output Files"},{"location":"workshop/10_GA/#analysing-the-ga-output-files","text":"The GA saves the post geometry optimisation structures from all evaluated population members in the file .xyz in standard xyz format. We can view a nice animation of all of the structures the GA explored with jmol by opening this xyz file in jmol with Jmol.jar Si.xyz then going to tools -> animate -> once . In order to analyse the structures created by the GA in more detail we could look at just the enthalpy of the structures, where we may be most interested in the lowest enthalpy structure found. The GA always takes the lowest enthalpy cell into the next generation, so we can look at the last generation to find the lowest enthalpy cell with grep Si.castep -e \"GA: gen # 12\" | tail -n 24 | sort -k10,10g which gives the final generation in order of enthalpy (in eV/ion). However, we gain a lot of information about the phase space with the other cells the GA finds on the way to the minimum enthalpy cell. To explore this a bit more run ./get_data.sh You may need to make this executable by running chmod u+x get_data.sh . This script generates an output file out.put that contains a summary of the data for each population member in 9 columns: Generation number. Parent or child. Member number. Error file detected (T or F). Geometry optimisation converged (T or F). Number of ions in the cell. Enthalpy per ion of converged cell (in eV/ion). Volume of converged cell (in Angstrom/ion). Member filename. We can then plot the population as the enthalpy (per ion) against the cell volume (per ion) by running the python script python plot_results.py This will produce two plots; one is an animation of the population members in each generation, the other is every explored population member over all generations with the lowest enthalpy structure labeled. It will also save these to the current directory. From this representation we can gain information about the phase space of SW Si, where the lower enthalpy structures represent structures on the energy-volume curve for SW Si. There are also structures found by the GA above the energy-volume curve that are likely unstable. We can have a look at the structure of the lowest enthalpy cell (as labeled on your graph) with jmol (or your crystal structure viewing program of choice). If using jmol run Jmol.jar -out.cell where is the seed of the lowest enthalpy population member given on the output graph and the -out.cell postfix gives us the structure post geometry optimisation (it is important to look at this cell rather than the input cell). For example, for me (though your seed may be different than this) this is Jmol.jar Si.gen_006_mem_012-out.cell It can sometimes be difficult to figure out the exact space group of crystals from a visual inspection. So, we can use c2x to find the space group of our lowest enthalpy cell within a tolerance with c2x --int -e=0.1-0.0001 -out.cell which for my lowest enthalpy member is c2x --int -e=0.1-0.0001 Si.gen_006_mem_012-out.cell For me this gives the output Tol=0.001 International symmetry is Fd-3m which is the diamond structure space group we would expect for Si.","title":"Analysing the GA Output Files"},{"location":"workshop/10_GA/#ga-continuation-approx-2-mins-runtime","text":"It is possible you won't find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure (or one close to it, remember the GA is a coarse search) as there is some randomness in a GA run and our population size and number of generations is small. But don't worry, it is possible to restart a GA run from exactly where you left off. Let's do this now (even if you did find the \\text{Fd}\\overline{3}\\text{m} \\text{Fd}\\overline{3}\\text{m} structure). To perform a continuation open the Si.param file in your text editor of choice. We then tell CASTEP GA we want to continue from where we left off. We do this by giving the location of the .xyz file that contains all explored structures by uncommenting the following in the Si.param file # continuation = Si.xyz so it reads continuation = Si.xyz Also, we want to run for more generations, so change the value for ga_max_gens from 12 to 18 (to run 6 more generations) i.e. in the Si.param file change the line ga_max_gens = 12 # Max number of generations to run for to ga_max_gens = 18 # Max number of generations to run for Important: Do not change the ga_pop_size as this will cause an error. We can then call CASTEP GA as before with castep_GA Si and it will read in the members from generation 12 of our last run and start generation 13 from these. Running for generations 13 to 16 should take approximately 1-2 minutes. Have a look at the outputs of this run by re-running ./get_data.sh and then plotting with python plot_results.py You may want to have a look at the lowest enthalpy structure with Jmol. You may also want to have a look at some of the other structures that are low on the energy/volume plot (a good way to find their seed names will be from the out.put file).","title":"GA Continuation (Approx. 2 mins runtime)"},{"location":"workshop/10_GA/#sic-stillinger-weber-ga","text":"Now we will look at exploring a more complicated potential energy landscape, to do this we first navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA Luckily CASTEP allows us to add our own parameterisation values for pair potentials. A parameterisation for an SiC SW pair potential has been added to the devel code block of the parameter file SiC.param . This parameterisation leads to a more complex potential energy landscape than we saw with Si. Due to the limitations of this pair potential parameterisation the GA will find different structures than we would find with ab-inito calculations as this is a pair potential energy landscape. However, it will run quickly enough to be usable with the computational and time resources available. As such we will use the GA to explore this unknown potential energy landscape as we did with Si. N.B. Everything we are doing here works just the same with DFT.","title":"SiC Stillinger-Weber GA"},{"location":"workshop/10_GA/#running-the-castep-ga-approx-5-10-mins-runtime","text":"The SiC.param file is very similar to the one used for Si, except the initial population is no longer completely random but instead generated as random high symmetry cells. The cell file contains an equal number of Si and C ions in random positions in a not unreasonably sized cell for this many ions Si and C ions. To run CASTEP GA execute castep_GA SiC and the GA will start, which will take approximately 6-7 minutes to run. You may want to look at the outputs as we did before, or take a quick break!","title":"Running the CASTEP GA (Approx. 5-10 mins runtime)"},{"location":"workshop/10_GA/#analysing-the-ga-output-files_1","text":"The GA outputs for this SiC run can be analysed in the same way as in the case of Si. We can use the same scripts as earlier to create energy volume plots by running ./get_data.sh && python plot_results.py Where this energy volume graph can be analysed as with Si. Make a note of the lowest enthalpy cell for use later. If it looks like would benefit from running a few more generations, we can run a continuation using the same methods as before. Have a look at the cell of the lowest enthalpy structure. It's likely that it seems a bit different to what we would expect in nature. As such, it would be good if we could run a full DFT calculation on some of the cells that have been found by the GA rather than relying on this pair potential parameterisation. However, we are a bit limited in computer power running, with all of the previous runs using only 3 cores. To overcome this hurdle we will exploit machine learning with Gaussian approximation potentials (GAP).","title":"Analysing the GA Output Files"},{"location":"workshop/10_GA/#gaussain-approximation-potential-accelerated-geometry-optimisation","text":"A common approach to machine learning is to train a model on some dataset of known solutions to a problem. This presents an issue with the application of machine learning to crystal structure optimisation for materials discovery as by definition the parameter landscape is not explored. One approach to this in CASTEP is to use a number of initial geometry optimisation or molecular dynamics steps ran with ab-initio methods as the initial training data. Subsequent geometry optimisation steps are then ran with a machine learned potential using Gaussian approximation potentials (GAP). Ions move over the course of geometry optimisations (or molecular dynamics calculations), therefore the landscape may change such that the potential needs some extra ab-inito data to train on. As such, CASTEP adaptively chooses geometry optimisation steps over the course of the calculation to run with DFT which are then used to re-train the GAP potential. More information about this method is available in the paper by Stenczel et al 1 . In general, less and less DFT geometry optimisation or MD steps will be required as the calculation continues and samples the parameter space more thoroughly (again see 1 ). Note: All methods that are outlined here for the acceleration of a geometry optimisation can also be directly applied to molecular dynamics calculations. In practice, as the cost savings are generally greater the more steps are in the calculation, the cost savings of GAP are greatest for long running molecular dynamics calculations.","title":"Gaussain Approximation Potential Accelerated Geometry Optimisation"},{"location":"workshop/10_GA/#using-gap-to-accelerate-a-geometry-optimisation","text":"We now navigate to the directory ./CASTEP_workshop_GA/2_SiC_SW_GA/DFT_polish_GAP which contains 3 files. The first is the SiC_GA_best.cell , we should open this and replace the lattice and positions blocks with those from the best cell from our previous SiC run (that we made a note of earlier, if that note is lost open the image ../all_gens.png ). For me the best cell is ../SiC.gen_009_mem_006-out.cell , but for you this could be different. The cell file we also specifies the QC5 pseudopotential library, a kpoint grid spacing and that the geometry optimisation will be fixed cell. The SiC_GA_best.param file contains standard CASTEP parameters for a Damped Molecular Dynamics (DMD) geometry optimisation. Along with this is the devel code block required to call hybrid-md (which then calls gap_fit ) to perform the GAP fitting. Finally, there is an extra input file required for a GAP run, the .hybrid-md-input.yaml file. This contains specific inputs relating to the GAP fitting. Here we specify a mandatory 10 initial DFT steps for the initial training dataset. After this we specify a minimum of 10 steps with the machine learned potential before re-fitting, whilst allowing CASTEP to vary the number of steps between re-fittings. We also allow GAP to also parellise over 3 cores. N.B. The GAP run we carry out here has rather coarse convergence parameters, designed to allow for a fast run on a desktop in this workshop.","title":"Using GAP to Accelerate a Geometry Optimisation"},{"location":"workshop/10_GA/#running-castep-with-gap-approx-10-15-mins-runtime","text":"To run CASTEP to perform the damped MD geometry optimisation with the aid of GAP call mpirun -n 3 castep.mpi SiC_GA_best Whilst this is running (which will take 10 to 15 minutes) there will be information printed to the terminal window each DMD step. This states if the step is an initial (DFT) step, if the step is using the machine learned potential or if it is being ran with DFT in order to perform a re-fit. It may be illustrative to open a new terminal window, navigate to the working directory and tail the .castep output file with tail -f SiC_GA_best.castep in order to see the geometry optimisation running. Notice the steps using the machine learned potential are essentially free when compared with the DFT steps that require SCF calculations.","title":"Running CASTEP with GAP (Approx. 10-15 mins runtime)"},{"location":"workshop/10_GA/#looking-at-the-gap-geometry-optimisation-results","text":"First, let us consider the cost of this geometry optimisation. My calculation ran for a total of 152 DMD steps, though your mileage may vary. Using the following command we can see on which DMD steps CASTEP decided to perform DFT calculations grep SiC_GA_best.castep -e \"Decided to perform\" We can also see how many of the DMD steps utilised DFT grep SiC_GA_best.castep -e \"Decided to perform\" | wc -l In my case this showed that 22 of the total DMD steps were using DFT, therefore approximately 85% of the DMD steps were carried out with the machine learned potential. Though there is a cost associated with these steps and with the re-fitting of the GAP potential, it is clear this represents a large cost saving. Very roughly (based on average time for one SCF cycle in my DMD run) without GAP this run would have taken approximately 4 times as long for no extra information. We can also visualize (using jmol or similar) both the output structure from the DMD run ( SiC_GA_best-out.cell ) and the pre-geometry optimisation structure ( SiC_GA_best.cell ). It is likely these are quite different. This is due to the difference (and lower quality!) of the SW parameterisation compared with any DFT approach.","title":"Looking at the GAP Geometry Optimisation Results"},{"location":"workshop/10_GA/#optional-extension-running-ga-with-other-systems","text":"You may also want to try the CASTEP GA with another system or pair potential parameterisation (it is likely not possible to run a full DFT run of the GA in the timescale of this practical). If this is the case you can use the blank input file in ./CASTEP_workshop_GA/2.5_GA_blank","title":"(Optional Extension) Running GA with Other Systems"},{"location":"workshop/10_GA/#optional-extension-running-gap-with-other-systems","text":"If you are interested in applying GAP to your calculations you may want to try GAP with a material of interest to you. If you would like to try with a cell and parameters of your choice there are blank input files in ./CASTEP_workshop_GA/2.5_GAP_blank","title":"(Optional Extension) Running GAP with Other Systems"},{"location":"workshop/10_GA/#footnotes","text":"1 Tam\u00e1s K. Stenczel, Zakariya El-Machachi, Guoda Liepuoniute, Joe D. Morrow, Albert P. Bart\u00f3k, Matt I. J. Probert, G\u00e1bor Cs\u00e1nyi, Volker L. Deringer; Machine-learned acceleration for molecular dynamics in CASTEP. J. Chem. Phys. 28 July 2023; 159 (4): 044803. https://doi.org/10.1063/5.0155621","title":"Footnotes"},{"location":"workshop/LST_QST/","text":"Transition State Search Tutorial How Transition State Searches Work There have been many suggestions for ways to identify transition states over the years, of which the two most popular are Linear Synchronous Transit / Quadratic Synchronous Transit (LST/QST) and Nudged Elastic Band (NEB) . These two techniques belong to the family of close-ended transition state searches - that is they require both an initial and final structure (reactant and product) and then they attempt to find the lowest barrier between them, the transition state. Open ended searches also exist in the literature, but they find the lowest barrier away from a reactant, which may not be useful for modelling a complex multi-step process. Finally, the gold standard technique (which can be performed in practice but is prohibitively expensive to use for more than verification of transition states) is mode following; the transition state is a stationary state at a saddle point, and accordingly it should have only one imaginary vibrational (phonon) mode. Once a transition structure is predicted, it is possible to perform a phonon calculation in CASTEP to verify this (see phonon tutorials). LST/QST LST/QST is probably the most conceptually simple of the transition state search techniques, and is in itself an extension to the simple LST technique. In LST, a linear interpolation between reactant and product states is made (with a variable weighting), and then the total energy of the system is evaluated at various points (choices of weighting) along this linear interpolation. A bisection search is then performed to find the local maximum along this path. Since LST performs a linear interpolation it is only guaranteed to find the energy maximum on that line - there is no guarantee that this sill in fact be the saddle point. Accordingly in QST , an energy minimisation is performed in directions orthogonal to the LST search direction. This then tends towards the saddle point, improving the estimate of the transition state. It is, however, possible that the QST optimisation will fall off the saddle point, which can make it a tricky process to converge, or cause the saddle point itself to be missed. Example: LST/QST Linear Synchronous Transit/ Quadratic Synchronous Transit (commonly known as LST/QST ) is a quick and reasonably accurate method to find a transition state. In this example, you will determine the transition barrier for a simple (and somewhat uninteresting) reaction, H + H2 -> H2 + H The files for this tutorial may be found at LST_Tutorial Geometry Optimisation Good transition state searches are based upon good structural relaxations of the initial and final states. The first step is therefore to perform geometry optimisations for your reactant H_Initial and product H_Final . Note that ionic constraints have been used in these to prevent translations of 2 of the ions and accelerate the geometry optimisation. You may wish to investigate what happens when these constraints are relaxed. For more complex constrained systems, it is often worthwhile changing the default geometry optimiser from Geom_Method: LBFGS to Geom_Method: TPSD , which is not disrupted by the sharp discontinuities the constraints can induce to the potential energy landscape. Once you have checked your end points are relaxed (ask if you are unsure how to confirm this!), you will need to create a new block: %block positions_frac_product . . . %endblock positions_frac_product where you need to place the atomic positions from H_Final-out.cell . If doing this manually, you may find the following bash commands useful cp reactant-out.cell TS.cell cat product-out.cell >> TS.cell This will append the contents of a hypothetical product-out.cell to the end of the reactant-out.cell in a new file TS.cell . You will then need to rename the second positions_frac block and delete any repeated entries. FOR THIS TUTORIAL: An Example TS.cell and TS.param file have been provided! Run the TS Search job Using castepsub submit the TS job. Results Interpretation To watch the path of the transition search, you can drag the .ts file into Jmol and watch the animations in the same way outlined in the geometry optimisation tutorial. Try and find the LST Transition State in the .castep file. Is this what you would expect? grep -A 7 \"LST Maximum Found\" TS.castep * Try and find the QST Transition state in the .castep file. grep -A 7 \"Transition State Found\" TS.castep * Can you explain why the QST result seems odd? What about the initial geometry optimisation could be improved to give a better result? Extensions Think about XC-functional choice; LDA overbinds - how does this affect the transition barrier and initial structures? What happens when the transition is between non-adjacent minima in the potential energy landscape? (This would require a more complex example than the tutorial) What about longer distances? When do we need Van der Waal's interactions (DFT+D) ? What effect did the constraints have? Can you improve them?","title":"Transition State Search Tutorial"},{"location":"workshop/LST_QST/#transition-state-search-tutorial","text":"","title":"Transition State Search Tutorial"},{"location":"workshop/LST_QST/#how-transition-state-searches-work","text":"There have been many suggestions for ways to identify transition states over the years, of which the two most popular are Linear Synchronous Transit / Quadratic Synchronous Transit (LST/QST) and Nudged Elastic Band (NEB) . These two techniques belong to the family of close-ended transition state searches - that is they require both an initial and final structure (reactant and product) and then they attempt to find the lowest barrier between them, the transition state. Open ended searches also exist in the literature, but they find the lowest barrier away from a reactant, which may not be useful for modelling a complex multi-step process. Finally, the gold standard technique (which can be performed in practice but is prohibitively expensive to use for more than verification of transition states) is mode following; the transition state is a stationary state at a saddle point, and accordingly it should have only one imaginary vibrational (phonon) mode. Once a transition structure is predicted, it is possible to perform a phonon calculation in CASTEP to verify this (see phonon tutorials).","title":"How Transition State Searches Work"},{"location":"workshop/LST_QST/#lstqst","text":"LST/QST is probably the most conceptually simple of the transition state search techniques, and is in itself an extension to the simple LST technique. In LST, a linear interpolation between reactant and product states is made (with a variable weighting), and then the total energy of the system is evaluated at various points (choices of weighting) along this linear interpolation. A bisection search is then performed to find the local maximum along this path. Since LST performs a linear interpolation it is only guaranteed to find the energy maximum on that line - there is no guarantee that this sill in fact be the saddle point. Accordingly in QST , an energy minimisation is performed in directions orthogonal to the LST search direction. This then tends towards the saddle point, improving the estimate of the transition state. It is, however, possible that the QST optimisation will fall off the saddle point, which can make it a tricky process to converge, or cause the saddle point itself to be missed.","title":"LST/QST"},{"location":"workshop/LST_QST/#example-lstqst","text":"Linear Synchronous Transit/ Quadratic Synchronous Transit (commonly known as LST/QST ) is a quick and reasonably accurate method to find a transition state. In this example, you will determine the transition barrier for a simple (and somewhat uninteresting) reaction, H + H2 -> H2 + H The files for this tutorial may be found at LST_Tutorial Geometry Optimisation Good transition state searches are based upon good structural relaxations of the initial and final states. The first step is therefore to perform geometry optimisations for your reactant H_Initial and product H_Final . Note that ionic constraints have been used in these to prevent translations of 2 of the ions and accelerate the geometry optimisation. You may wish to investigate what happens when these constraints are relaxed. For more complex constrained systems, it is often worthwhile changing the default geometry optimiser from Geom_Method: LBFGS to Geom_Method: TPSD , which is not disrupted by the sharp discontinuities the constraints can induce to the potential energy landscape. Once you have checked your end points are relaxed (ask if you are unsure how to confirm this!), you will need to create a new block: %block positions_frac_product . . . %endblock positions_frac_product where you need to place the atomic positions from H_Final-out.cell . If doing this manually, you may find the following bash commands useful cp reactant-out.cell TS.cell cat product-out.cell >> TS.cell This will append the contents of a hypothetical product-out.cell to the end of the reactant-out.cell in a new file TS.cell . You will then need to rename the second positions_frac block and delete any repeated entries. FOR THIS TUTORIAL: An Example TS.cell and TS.param file have been provided! Run the TS Search job Using castepsub submit the TS job. Results Interpretation To watch the path of the transition search, you can drag the .ts file into Jmol and watch the animations in the same way outlined in the geometry optimisation tutorial. Try and find the LST Transition State in the .castep file. Is this what you would expect? grep -A 7 \"LST Maximum Found\" TS.castep * Try and find the QST Transition state in the .castep file. grep -A 7 \"Transition State Found\" TS.castep * Can you explain why the QST result seems odd? What about the initial geometry optimisation could be improved to give a better result?","title":"Example: LST/QST"},{"location":"workshop/LST_QST/#extensions","text":"Think about XC-functional choice; LDA overbinds - how does this affect the transition barrier and initial structures? What happens when the transition is between non-adjacent minima in the potential energy landscape? (This would require a more complex example than the tutorial) What about longer distances? When do we need Van der Waal's interactions (DFT+D) ? What effect did the constraints have? Can you improve them?","title":"Extensions"},{"location":"workshop/optados/6a_dos/","text":"Density of States Outline This is a simple example of using optados for calculating electronic density of states of crystalline silicon in a 2 atom cell. It shows how optados's adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. The tarball for the tutorial files for all of the optados tutorials are here: optados-examples.tgz Input Files: examples/Si2_DOS/Si2.cell - The castep cell file containing information about the simulation cell. examples/Si2_DOS/Si2.param - The castep param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_DOS/Si2.odi - The optados input file, containing the parameters necessary to run optados. Instructions: Perform a castep calculation on the bulk silicon using the Si2.cell and Si2.param input files. This should take a couple of seconds to run. Examine the optados input file - Si2.odi Perform an optados calculation. $ optados.mpi Si2 This generates 3 files: Si2.odo -- optados general output file. Si2.adaptive.dat -- The adaptive broadened DOS raw output data. Si2.adaptive.agr -- The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Examine the Si2.odo file. optados has performed a Density of States calculation. +--------------- Fermi Energy Analysis ------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99961 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99961 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 5.4109 eV <- EfA | +--------------------------------------------------------------+ It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. +----------------------- Electronic Data ---------------------+ | Number of Bands : 23 | | Grid size : 10 x 10 x 10 | | Number of K-points : 110 | | Spin-Polarised Calculation : True | | Number of up-spin electrons : 4.00 | | Number of down-spin electrons : 4.00 | +-------------------------------------------------------------+ Since we had efermi : optados , optados sets the internal value of the Fermi level to the one it has derived from the DOS. This is important for subsequent calculations. Other valid options are file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues; insulator , where optados uses a value calculated from assuming the system is non-metallic; or a value set by the user. optados now performs some analysis of the DOS at the Fermi level, +-------------- DOS at Fermi Energy Analysis ----------------+ | Fermi energy used : 5.4109 eV | | From Adaptive broadening | | Spin Component:1 DOS at Fermi Energy:0.0011 eln/cell <-DEA | | Spin Component:2 DOS at Fermi Energy:0.0011 eln/cell<- DEA | +------------------------------------------------------------+ From this we may assume that there is a band gap. Importantly, then optados calculates the band energy from the DOS is has calculated. +------------------- Band Energy Analysis -------------------+ | Band energy (Adaptive broadening) : 1.3609 eV <- BEA | | Band energy (From CASTEP) : 1.3622 eV <- BEC | +------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Finally optados shifts the Fermi level to 0 eV, for the output files. The DOS is written to Si2.adaptive.dat . This contains 5 columns as described in the header of the file: ################################################################ # # O p t a D O S o u t p u t f i l e # # Density of States using adaptive broadening # Generated on 12 Feb 2012 at 16:50:37 # Column Data # 1 Energy (eV) # 2 Up-spin DOS (electrons per eV) # 3 Down-spin DOS (electrons per eV) # 4 Up-spin Integrated DOS (electrons) # 5 Down-spin Integrated DOS (electrons) # ################################################################ This file can be plotted by your favourite graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace . $ xmgrace Si2.adaptive.agr 1. We now try again with a better sampling of the DOS, by setting DOS_SPACING : 0.001 and also analyse the band gap, by setting COMPUTE_BAND_GAP : true . You can set IPRINT : 2 to see a progress report in Si2.odo . In Si2.odo we now have a new section analysing the band gap in various ways. +----------------------------- Bandgap Analysis ---------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6676272107 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000| | and CBM kpoint: -0.45000 -0.05000 -0.45000| | ==> Indirect Gap | +--------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5542517447 eV <- OBg | | Spin : 2 : 2.5542463024 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +--------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8121372691 eV <- ABg | | Spin : 2 : 3.8121342659 eV <- ABg | | Weighted Average : 3.8121357675 eV <- wAB | +--------------------------------------------------------------+ optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Increasing the number of integration points has improved the band energy of the adaptive smearing: | Band energy (Adaptive broadening) : 1.3623 eV <- BEA | We will now compare the DOS with the adaptive broadening scheme with simple Gaussian smearing. In the optados input file ( Si2.odi ) change the value of BROADENING to fixed . Plotting the fixed broadened DOS over the adaptive we see the advantages of the adaptive broadening. xmgrace Si2.adaptive.agr Si2.fixed.agr","title":"7a DOS"},{"location":"workshop/optados/6a_dos/#density-of-states","text":"","title":"Density of States"},{"location":"workshop/optados/6a_dos/#outline","text":"This is a simple example of using optados for calculating electronic density of states of crystalline silicon in a 2 atom cell. It shows how optados's adaptive broadening can be used to resolve fine spectral features that a fixed broadening scheme will obscure. The tarball for the tutorial files for all of the optados tutorials are here: optados-examples.tgz","title":"Outline"},{"location":"workshop/optados/6a_dos/#input-files","text":"examples/Si2_DOS/Si2.cell - The castep cell file containing information about the simulation cell. examples/Si2_DOS/Si2.param - The castep param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_DOS/Si2.odi - The optados input file, containing the parameters necessary to run optados.","title":"Input Files:"},{"location":"workshop/optados/6a_dos/#instructions","text":"Perform a castep calculation on the bulk silicon using the Si2.cell and Si2.param input files. This should take a couple of seconds to run. Examine the optados input file - Si2.odi Perform an optados calculation. $ optados.mpi Si2 This generates 3 files: Si2.odo -- optados general output file. Si2.adaptive.dat -- The adaptive broadened DOS raw output data. Si2.adaptive.agr -- The adaptive broadened DOS in a file suitable to be plotted by xmgrace. Examine the Si2.odo file. optados has performed a Density of States calculation. +--------------- Fermi Energy Analysis ------------------------+ | From Adaptive broadening | | Spin Component:1 occupation between 3.99961 and 4.00003 <-Oc | | Spin Component:2 occupation between 3.99961 and 4.00003 <-Oc | | Fermi energy (Adaptive broadening) : 5.4109 eV <- EfA | +--------------------------------------------------------------+ It has used the integrated DOS to work out the Fermi level, and has suggested the error in the integration by indicating the number of electrons at the Fermi level. Since we had 4 up electrons and 4 down in the input file this analysis seems satisfactory. +----------------------- Electronic Data ---------------------+ | Number of Bands : 23 | | Grid size : 10 x 10 x 10 | | Number of K-points : 110 | | Spin-Polarised Calculation : True | | Number of up-spin electrons : 4.00 | | Number of down-spin electrons : 4.00 | +-------------------------------------------------------------+ Since we had efermi : optados , optados sets the internal value of the Fermi level to the one it has derived from the DOS. This is important for subsequent calculations. Other valid options are file , where optados uses the value calculated by the electronic structure code that generated the eigenvalues; insulator , where optados uses a value calculated from assuming the system is non-metallic; or a value set by the user. optados now performs some analysis of the DOS at the Fermi level, +-------------- DOS at Fermi Energy Analysis ----------------+ | Fermi energy used : 5.4109 eV | | From Adaptive broadening | | Spin Component:1 DOS at Fermi Energy:0.0011 eln/cell <-DEA | | Spin Component:2 DOS at Fermi Energy:0.0011 eln/cell<- DEA | +------------------------------------------------------------+ From this we may assume that there is a band gap. Importantly, then optados calculates the band energy from the DOS is has calculated. +------------------- Band Energy Analysis -------------------+ | Band energy (Adaptive broadening) : 1.3609 eV <- BEA | | Band energy (From CASTEP) : 1.3622 eV <- BEC | +------------------------------------------------------------+ As the quality of the optados calculation is increased these two values should converge to the same answer. Finally optados shifts the Fermi level to 0 eV, for the output files. The DOS is written to Si2.adaptive.dat . This contains 5 columns as described in the header of the file: ################################################################ # # O p t a D O S o u t p u t f i l e # # Density of States using adaptive broadening # Generated on 12 Feb 2012 at 16:50:37 # Column Data # 1 Energy (eV) # 2 Up-spin DOS (electrons per eV) # 3 Down-spin DOS (electrons per eV) # 4 Up-spin Integrated DOS (electrons) # 5 Down-spin Integrated DOS (electrons) # ################################################################ This file can be plotted by your favourite graph-plotting software. However, optados has made things easy and generated a Si2.adaptive.agr file which is directly plottable using xmgrace . $ xmgrace Si2.adaptive.agr 1. We now try again with a better sampling of the DOS, by setting DOS_SPACING : 0.001 and also analyse the band gap, by setting COMPUTE_BAND_GAP : true . You can set IPRINT : 2 to see a progress report in Si2.odo . In Si2.odo we now have a new section analysing the band gap in various ways. +----------------------------- Bandgap Analysis ---------------+ | Number of kpoints at VBM CBM | | Spin : 1 : 1 1 | | Spin : 2 : 1 1 | | Thermal Bandgap : 0.6676272107 eV <- TBg | | Between VBM kpoint : 0.05000 0.05000 0.05000| | and CBM kpoint: -0.45000 -0.05000 -0.45000| | ==> Indirect Gap | +--------------------------------------------------------------+ | Optical Bandgap | | Spin : 1 : 2.5542517447 eV <- OBg | | Spin : 2 : 2.5542463024 eV <- OBg | | Number of kpoints with this gap | | Spin : 1 : 1 | | Spin : 2 : 1 | +--------------------------------------------------------------+ | Average Bandgap | | Spin : 1 : 3.8121372691 eV <- ABg | | Spin : 2 : 3.8121342659 eV <- ABg | | Weighted Average : 3.8121357675 eV <- wAB | +--------------------------------------------------------------+ optados is very careful in its band gap analysis. It uses the bare eigenvalues (un-broadened) and works out the nature and size of the thermal gap, optical gap and the average gap over all of the Brillouin zone. In cases of multi-valleyed semiconductors optados will report the number of conduction band minima or valence band maxima with identical energies, but will not report the nature of the gap. Increasing the number of integration points has improved the band energy of the adaptive smearing: | Band energy (Adaptive broadening) : 1.3623 eV <- BEA | We will now compare the DOS with the adaptive broadening scheme with simple Gaussian smearing. In the optados input file ( Si2.odi ) change the value of BROADENING to fixed . Plotting the fixed broadened DOS over the adaptive we see the advantages of the adaptive broadening. xmgrace Si2.adaptive.agr Si2.fixed.agr","title":"Instructions:"},{"location":"workshop/optados/6b_pdos/","text":"Projected Density of States We assume the reader is familiar with the previous section on Density of States calculations and is now familiar with running optados . Outline This is a simple example of using optados for calculating electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states. Input Files examples/Si2_PDOS/Si2.cell - The castep .cell file containing information about the simulation cell. examples/Si2_PDOS/Si2.param - The castep .param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_PDOS/Si2.odi - The optados input file, containing the parameters necessary to run optados. Instructions: Examine the optados input file noting TASK : pdos . We choose to decompose the DOS into angular momentum channels PDOS : angular and as in the previous example we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep. Execute optados. The output can be found in Si2.pdos.dat . ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ The header shows that there are four projectors described below. The first containing the s-channels of both silicon atoms, the second the p-channels etc. The output is easily plotted using xmgrace . Setting DOS_SPACING : 0.001 gives a high quality plot, as shown in the figure below. Density of States of Silicon generated by adaptive broadening projected onto LCAO momentum states Other projections to try are: PDOS : Si1;Si2(s) -- Output the PDOS on Si atom 1 and the PDOS on the s-channel of Si atom 2. (Resulting in two projectors) PDOS : sum:Si1-2(s) -- Output the sum of the s-channels on the two Si atoms. (Resulting in one projector) PDOS : Si1(p) -- Output the p-channel on Si atom 1. (Resulting in one projector)","title":"7b Projected DOS"},{"location":"workshop/optados/6b_pdos/#projected-density-of-states","text":"We assume the reader is familiar with the previous section on Density of States calculations and is now familiar with running optados .","title":"Projected Density of States"},{"location":"workshop/optados/6b_pdos/#outline","text":"This is a simple example of using optados for calculating electronic density of states of 2 atoms of crystalline silicon projected onto LCAO basis states.","title":"Outline"},{"location":"workshop/optados/6b_pdos/#input-files","text":"examples/Si2_PDOS/Si2.cell - The castep .cell file containing information about the simulation cell. examples/Si2_PDOS/Si2.param - The castep .param file containing information about the parameters for the SCF and spectral calculations. examples/Si2_PDOS/Si2.odi - The optados input file, containing the parameters necessary to run optados.","title":"Input Files"},{"location":"workshop/optados/6b_pdos/#instructions","text":"Examine the optados input file noting TASK : pdos . We choose to decompose the DOS into angular momentum channels PDOS : angular and as in the previous example we choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep. Execute optados. The output can be found in Si2.pdos.dat . ################################################################ # # O p t a D O S o u t p u t f i l e # # Generated on 13 Feb 2012 at 10:15:10 ################################################################ #+-------------------------------------------------------------+ #| Partial Density of States -- Projectors | #+-------------------------------------------------------------+ #| Projector: 1 contains: | #| Atom AngM Channel | #| Si 1 s | #| Si 2 s | #+-------------------------------------------------------------+ #| Projector: 2 contains: | #| Atom AngM Channel | #| Si 1 p | #| Si 2 p | #+-------------------------------------------------------------+ #| Projector: 3 contains: | #| Atom AngM Channel | #| Si 1 d | #| Si 2 d | #+-------------------------------------------------------------+ #| Projector: 4 contains: | #| Atom AngM Channel | #| Si 1 f | #| Si 2 f | #+-------------------------------------------------------------+ The header shows that there are four projectors described below. The first containing the s-channels of both silicon atoms, the second the p-channels etc. The output is easily plotted using xmgrace . Setting DOS_SPACING : 0.001 gives a high quality plot, as shown in the figure below. Density of States of Silicon generated by adaptive broadening projected onto LCAO momentum states Other projections to try are: PDOS : Si1;Si2(s) -- Output the PDOS on Si atom 1 and the PDOS on the s-channel of Si atom 2. (Resulting in two projectors) PDOS : sum:Si1-2(s) -- Output the sum of the s-channels on the two Si atoms. (Resulting in one projector) PDOS : Si1(p) -- Output the p-channel on Si atom 1. (Resulting in one projector)","title":"Instructions:"},{"location":"workshop/optados/6c_coreloss/","text":"Calculation of core-loss spectra for hBN We begin by running a CASTEP calculation using the files provided. Note that we specify a pseudopotential file for one B atom and both N atom, and use an on-the-fly pseudopotential for the other B atom. This looks a bit weird! It is simply a way to only compute the EELS for one atomic site (core-loss spectra can only be computed for atoms described by on-the-fly potentials). An h-BN cell and param file are provided. Execute optados using the optados input file provided and the file hBN_core_edge.dat will be created. The file contains two columns, the first is the energy and the second is the spectrum. This file contains the following edges: B 1 K1 B:1 OptaDOS has also written a grace file $ xmgrace hBN_core_edge.agr This spectrum has lots of fine detail. To compare with experiment we can include lifetime and instrument broadening effects. First let's add some Gaussian broadening to simulate instrument effects. Add the following the odi file and re-run. CORE_LAI_BROADENING : true LAI_GAUSSIAN_WIDTH : 1.0 The file hBN_core_edge.dat now has three columns. The third column is the broadened spectrum. To compare the broadened and un-broadened spectra xmgrace hBN_core_edge_broad.agr hBN_core_edge.agr Now add some lifetime broadening (look up the meaning of the keywords in the optados user guide) LAI_LORENTZIAN_WIDTH : 0.5 LAI_LORENTZIAN_SCALE : 0.1 Now try running CASTEP and OptaDOS to produce a N K-edge Including a core-hole First we will include a core-hole on atom B:1. To do this we add a modified pseudopotential string into the hBN.cell file B:1 2|1.2|12|14|16|20:21{1s1.00}(qc=8) The core-hole is created by removing a 1s electron from the electronic configuration used in the generation of the pseudopotential. Information about the pseudopotential is included at the top of the hBN.castep file ============================================================ | Pseudopotential Report - Date of generation 17-08-2018 | ------------------------------------------------------------ | Element: B Ionic charge: 3.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.347 | | 2p 1.000 -0.133 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.347 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.133 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ The line | \"2|1.2|12|14|16|20:21(qc=8)\" | specifies the parameters used to create the OFT B pseudopotential. We use this as a starting point and remove one of the core 1s electrons to create the core-hole pseudopotential by including {1s1.00} . To maintain the neutrality of the cell, we include CHARGE : +1 in the hBN.param file. Run the calculation. Compare the K-edge from the core-hole calculation with the previous non-core-hole calculation. The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. Create a 2x2x1 supercell (talk to one of the tutors if you\u2019re unsure about how to do this) and carry out another core-loss B K-edge simulation. Compare the spectra to that from the primitive cell. Construct larger and larger unit cells until the spectrum stops changing with increasing separation between the periodic images. Other things to try include: Include the core-hole on the N atom rather than the B Compare your simulated spectra to experimental data (the EELS database is a good place to find experimental data) Compare to spectra from cubic BN Calculating spectra from graphite (graphene) and diamond","title":"7c Coreloss"},{"location":"workshop/optados/6c_coreloss/#calculation-of-core-loss-spectra-for-hbn","text":"We begin by running a CASTEP calculation using the files provided. Note that we specify a pseudopotential file for one B atom and both N atom, and use an on-the-fly pseudopotential for the other B atom. This looks a bit weird! It is simply a way to only compute the EELS for one atomic site (core-loss spectra can only be computed for atoms described by on-the-fly potentials). An h-BN cell and param file are provided. Execute optados using the optados input file provided and the file hBN_core_edge.dat will be created. The file contains two columns, the first is the energy and the second is the spectrum. This file contains the following edges: B 1 K1 B:1 OptaDOS has also written a grace file $ xmgrace hBN_core_edge.agr This spectrum has lots of fine detail. To compare with experiment we can include lifetime and instrument broadening effects. First let's add some Gaussian broadening to simulate instrument effects. Add the following the odi file and re-run. CORE_LAI_BROADENING : true LAI_GAUSSIAN_WIDTH : 1.0 The file hBN_core_edge.dat now has three columns. The third column is the broadened spectrum. To compare the broadened and un-broadened spectra xmgrace hBN_core_edge_broad.agr hBN_core_edge.agr Now add some lifetime broadening (look up the meaning of the keywords in the optados user guide) LAI_LORENTZIAN_WIDTH : 0.5 LAI_LORENTZIAN_SCALE : 0.1 Now try running CASTEP and OptaDOS to produce a N K-edge","title":"Calculation of core-loss spectra for hBN"},{"location":"workshop/optados/6c_coreloss/#including-a-core-hole","text":"First we will include a core-hole on atom B:1. To do this we add a modified pseudopotential string into the hBN.cell file B:1 2|1.2|12|14|16|20:21{1s1.00}(qc=8) The core-hole is created by removing a 1s electron from the electronic configuration used in the generation of the pseudopotential. Information about the pseudopotential is included at the top of the hBN.castep file ============================================================ | Pseudopotential Report - Date of generation 17-08-2018 | ------------------------------------------------------------ | Element: B Ionic charge: 3.00 Level of theory: PBE | | Atomic Solver: Koelling-Harmon | | | | Reference Electronic Structure | | Orbital Occupation Energy | | 2s 2.000 -0.347 | | 2p 1.000 -0.133 | | | | Pseudopotential Definition | | Beta l e Rc scheme norm | | 1 0 -0.347 1.199 qc 0 | | 2 0 0.250 1.199 qc 0 | | 3 1 -0.133 1.199 qc 0 | | 4 1 0.250 1.199 qc 0 | | loc 2 0.000 1.199 pn 0 | | | | Augmentation charge Rinner = 0.838 | | Partial core correction Rc = 0.838 | ------------------------------------------------------------ | \"2|1.2|12|14|16|20:21(qc=8)\" | ------------------------------------------------------------ | Author: Chris J. Pickard, Cambridge University | ============================================================ The line | \"2|1.2|12|14|16|20:21(qc=8)\" | specifies the parameters used to create the OFT B pseudopotential. We use this as a starting point and remove one of the core 1s electrons to create the core-hole pseudopotential by including {1s1.00} . To maintain the neutrality of the cell, we include CHARGE : +1 in the hBN.param file. Run the calculation. Compare the K-edge from the core-hole calculation with the previous non-core-hole calculation. The periodic images of the core-hole will interact with one another. As this is unphysical, we need to increase the distance between the core-holes. This is done by creating a supercell. Create a 2x2x1 supercell (talk to one of the tutors if you\u2019re unsure about how to do this) and carry out another core-loss B K-edge simulation. Compare the spectra to that from the primitive cell. Construct larger and larger unit cells until the spectrum stops changing with increasing separation between the periodic images. Other things to try include: Include the core-hole on the N atom rather than the B Compare your simulated spectra to experimental data (the EELS database is a good place to find experimental data) Compare to spectra from cubic BN Calculating spectra from graphite (graphene) and diamond","title":"Including a core-hole"},{"location":"workshop/optados/6d_lowloss/","text":"JDOS and OPTICS Joint DOS See examples/Si2_JDOS . This is a simple example of using optados for calculating joint electronic density of states. We choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep, and so EFERMI: OPTADOS is included in the Si2.odi file. Execute castep and optados using the example files. The JDOS is written to Si2.jadaptive.dat . A file suitable for plotting using xmgrace is written to Si2.jadaptive.agr . Check the effect of changing the sampling by increasing and decreasing the value of JDOS_SPACING in the Si2.odi file. Optics Two sets of example files are provided for calculations of optical properties. For each example, the .castep files containing all the cell and simulation parameters are included, along with an optados input file. We assume that the reader is familiar with the previous sections on DOS and JDOS. Silicon See examples/Si2_OPTICS/ . This is a simple example of using optados to calculate the optical properties of crystalline silicon, which is an insulator. Instructions: Execute optados to calculate the optical properties. Several .dat files are produced: Si2_OPTICS_absorption.dat : This file contains the absorption coefficient (second column) as function of energy (first column). Si2_OPTICS_conductivity.dat : This file contains the conductivity outputted in SI units (Siemens per metre). The columns are the energy, real part and imaginary part of the conductivity respectively. Si2_OPTICS_epsilon.dat : This file contains the dielectric function. The columns are the energy and real and imaginary parts of the dielectric function respectively. The file header also includes the result of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') . N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Si2_OPTICS_loss_fn.dat : This file contains the loss function (second column) as a function of energy (first column). The header of the file shows the results of the two sum rules associated with the loss function \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} Si2_OPTICS_reflection.dat : This file contains the reflection coefficient (second column) as a function of energy (first column). Si2_OPTICS_refractive_index.dat : This file contains the refractive index. The columns are the energy and real and imaginary parts of the refractive index respectively. Corresponding .agr files are also generated which can be plotted easily using xmgrace. Change parameters JDOS_SPACING and JDOS_MAX and check the effect on the optical properties. Note: all of the other optical properties are derived from the dielectric function. The optados input file has been set up to calculate the optical properties in the polycrystalline geometry ( optics_geom = polycrystalline ). It is possible to calculate either polarised or unpolarised geometries, or to calculate the full dielectric tensor. To calculate the full dielectric tensor set optics_geom = tensor . This time only the file Si2_OPTICS_epsilon.dat is generated. The format of this file is the same as before (the columns are the energy and the real and imaginary parts of the dielectric function respectively), but this time the six different components of the tensor are listed sequentially in the order \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{yy} \\epsilon_{yy} , \\epsilon_{zz} \\epsilon_{zz} , \\epsilon_{xy} \\epsilon_{xy} , \\epsilon_{xz} \\epsilon_{xz} and \\epsilon_{yz} \\epsilon_{yz} . Additional broadening can be included in the calculation of the loss function. This is done by including the keyword optics_lossfn_broadening in the optados input file. If you include this keyword and re-run optados, you will find that the file Si2_OPTICS_loss_fn.dat now has three columns. These are the energy, unbroadened spectrum and broadened spectrum respectively. Aluminium Aluminium is a metal so we need to include both the interband and intraband contributions to the dielectric function. To include the intraband contribution optics_intraband = true must be included in the optados input file. When you run optados, the same files are generated as when only the interband term is included. The Al_OPTICS_epsilon.dat file has the same format as before, but it now contains sequentially the interband contribution, the intraband contribution and the total dielectric function. The file Al_OPTICS_epsilon.agr only contains the interband term. In the same way, Al_OPTICS_loss_fn.dat contains the interband contribution, intraband contribution and total loss function. All other optical properties are calculated from the total dielectric function and the format of the output files remains the same. In the case where the dielectric tensor is calculated and the intraband term is included, only the Al_OPTICS_epsilon.dat file is generated. As before it contains each component, but this time it lists sequentially the interband contribution, intraband contribution and total dielectric function for each component. This time, if additional broadening for the loss function is included by using the key word optics_lossfn_broadening , AL_OPTICS_loss_fn.dat will contains four sequential data sets. These are the interband contribution, the intraband contribution, the total loss function without the additional broadening and the broadened total loss function.","title":"7d Lowloss"},{"location":"workshop/optados/6d_lowloss/#jdos-and-optics","text":"","title":"JDOS and OPTICS"},{"location":"workshop/optados/6d_lowloss/#joint-dos","text":"See examples/Si2_JDOS . This is a simple example of using optados for calculating joint electronic density of states. We choose to recalculate the Fermi level using the calculated DOS, rather than use the Fermi level suggested by castep, and so EFERMI: OPTADOS is included in the Si2.odi file. Execute castep and optados using the example files. The JDOS is written to Si2.jadaptive.dat . A file suitable for plotting using xmgrace is written to Si2.jadaptive.agr . Check the effect of changing the sampling by increasing and decreasing the value of JDOS_SPACING in the Si2.odi file.","title":"Joint DOS"},{"location":"workshop/optados/6d_lowloss/#optics","text":"Two sets of example files are provided for calculations of optical properties. For each example, the .castep files containing all the cell and simulation parameters are included, along with an optados input file. We assume that the reader is familiar with the previous sections on DOS and JDOS.","title":"Optics"},{"location":"workshop/optados/6d_lowloss/#silicon","text":"See examples/Si2_OPTICS/ . This is a simple example of using optados to calculate the optical properties of crystalline silicon, which is an insulator. Instructions: Execute optados to calculate the optical properties. Several .dat files are produced: Si2_OPTICS_absorption.dat : This file contains the absorption coefficient (second column) as function of energy (first column). Si2_OPTICS_conductivity.dat : This file contains the conductivity outputted in SI units (Siemens per metre). The columns are the energy, real part and imaginary part of the conductivity respectively. Si2_OPTICS_epsilon.dat : This file contains the dielectric function. The columns are the energy and real and imaginary parts of the dielectric function respectively. The file header also includes the result of the sum rule \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') \\int_0^{\\omega'} \\textrm{Im} \\epsilon(\\omega) \\mathrm{d}\\omega = N_\\textrm{eff}(\\omega') . N_\\textrm{eff} N_\\textrm{eff} is the effective number of electrons contributing to the absorption process, and is a function of energy. Si2_OPTICS_loss_fn.dat : This file contains the loss function (second column) as a function of energy (first column). The header of the file shows the results of the two sum rules associated with the loss function \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\omega \\mathrm{d}\\omega = N_\\textrm{eff} and \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} \\int_0^{\\omega'} \\textrm{Im} -\\frac{1}{\\epsilon(\\omega)}\\frac{1}{\\omega} \\mathrm{d}\\omega = \\frac{\\pi}{2} Si2_OPTICS_reflection.dat : This file contains the reflection coefficient (second column) as a function of energy (first column). Si2_OPTICS_refractive_index.dat : This file contains the refractive index. The columns are the energy and real and imaginary parts of the refractive index respectively. Corresponding .agr files are also generated which can be plotted easily using xmgrace. Change parameters JDOS_SPACING and JDOS_MAX and check the effect on the optical properties. Note: all of the other optical properties are derived from the dielectric function. The optados input file has been set up to calculate the optical properties in the polycrystalline geometry ( optics_geom = polycrystalline ). It is possible to calculate either polarised or unpolarised geometries, or to calculate the full dielectric tensor. To calculate the full dielectric tensor set optics_geom = tensor . This time only the file Si2_OPTICS_epsilon.dat is generated. The format of this file is the same as before (the columns are the energy and the real and imaginary parts of the dielectric function respectively), but this time the six different components of the tensor are listed sequentially in the order \\epsilon_{xx} \\epsilon_{xx} , \\epsilon_{yy} \\epsilon_{yy} , \\epsilon_{zz} \\epsilon_{zz} , \\epsilon_{xy} \\epsilon_{xy} , \\epsilon_{xz} \\epsilon_{xz} and \\epsilon_{yz} \\epsilon_{yz} . Additional broadening can be included in the calculation of the loss function. This is done by including the keyword optics_lossfn_broadening in the optados input file. If you include this keyword and re-run optados, you will find that the file Si2_OPTICS_loss_fn.dat now has three columns. These are the energy, unbroadened spectrum and broadened spectrum respectively.","title":"Silicon"},{"location":"workshop/optados/6d_lowloss/#aluminium","text":"Aluminium is a metal so we need to include both the interband and intraband contributions to the dielectric function. To include the intraband contribution optics_intraband = true must be included in the optados input file. When you run optados, the same files are generated as when only the interband term is included. The Al_OPTICS_epsilon.dat file has the same format as before, but it now contains sequentially the interband contribution, the intraband contribution and the total dielectric function. The file Al_OPTICS_epsilon.agr only contains the interband term. In the same way, Al_OPTICS_loss_fn.dat contains the interband contribution, intraband contribution and total loss function. All other optical properties are calculated from the total dielectric function and the format of the output files remains the same. In the case where the dielectric tensor is calculated and the intraband term is included, only the Al_OPTICS_epsilon.dat file is generated. As before it contains each component, but this time it lists sequentially the interband contribution, intraband contribution and total dielectric function for each component. This time, if additional broadening for the loss function is included by using the key word optics_lossfn_broadening , AL_OPTICS_loss_fn.dat will contains four sequential data sets. These are the interband contribution, the intraband contribution, the total loss function without the additional broadening and the broadened total loss function.","title":"Aluminium"}]} \ No newline at end of file diff --git a/workshop/00_starting/index.html b/workshop/00_starting/index.html index a348c91..87e5a5f 100644 --- a/workshop/00_starting/index.html +++ b/workshop/00_starting/index.html @@ -2588,10 +2588,30 @@
  • - - Connecting to the virual desktop + + Connecting to and using the virual desktop + +
  • @@ -2622,8 +2642,8 @@
  • - - Tuorial files + + Tutorial files
    • @@ -2932,10 +2952,30 @@
  • - - Connecting to the virual desktop + + Connecting to and using the virual desktop + +
  • @@ -2966,8 +3006,8 @@
  • - - Tuorial files + + Tutorial files
    • @@ -3015,9 +3055,13 @@

    Signing up to the STFC Traini

    Creating the CASTEP Workspace

    You should recieve an email with a link that you can use to connect to the STFC system. Save this email as you will use it to login during the training.

    Select New Workspace and then select CASTEP TRAINING WORKSHOP 2024 and click create workspace. This will generate you a virtual desktop on the STFC cloud service with access to CASTEP.

    -

    Connecting to the virual desktop

    +

    Connecting to and using the virual desktop

    Mouse over the workspace and you should be presented with buttons to launch the workspace in either a new tab or new window.

    -

    This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several visualisations available.

    +

    This should open a new window and load a virtual desktop within the browser. This is a linux desktop with CASTEP and several other useful tools available.

    +

    Uploading and downloading files from your laptop

    +

    To upload or download any files from your laptop to the VM, navigate to https://training.analysis.stfc.ac.uk/data/, click on Data (left hand menu) and then select Home - that's your home directory where you can upload files to.

    +

    Copying and pasting from your laptop

    +

    To enable copying and pasting between your laptop and the VM, hover your mouse at the top of the virtual desktop and click on Copy & Paste to enable this.

    Loading CASTEP

    Click the applications button in the bottom left and select software -> CASTEP. This will launch a terminal with shortcuts for running CASTEP.

    Accessing the CASTEP help system

    @@ -3031,7 +3075,7 @@

    Running CASTEP

    To run castep in parallel using 16 core (the maximum for these virutal machines) with same Si2 seedname, type

    castep-mpi mpirun -n 16 castep.mpi Si2

    Note that the castep-serial and castep-mpi parts that the start of the above lines are particular to these virtual machines for the tutorial. Running castep on your own machines would typically involve either castep.serial Si2 for the serial version or mpirun -n 4 castep.mpi Si2 for the parallel version.

    -

    Tuorial files

    +

    Tutorial files

    The files needed for these tutorials can be found by navigating from Applications -> Data -> Course Materials (that will open up a file browser in the right place). They can also be accessed via the command line from this location: /course_materials/. Copy the files to somewhere in your home directory before trying to run CASTEP (you can't run CASTEP in the /course_materials directory. You can do that either using the graphical file browser or using the command line. For example:

    Make a folder called Si2 in your home directory:

    mkdir ~/Si2

    @@ -3048,9 +3092,9 @@

    Summary of useful commands

  • ls -l - list files - but give more details than plain ls
  • exit - to close the terminal when you are finished
  • cp fred/* jim/ - copy all the files in the folder fred into the folder jim
    • +
  • cp -r alice bob - copy recursively alice to bob. You need this if you want to copy whole folders.
  • cp ../myfile ./ - copy the file myfile in the folder below to the current folder
  • cp ~/myfile ./ - copy the file myfile in your home folder to the current folder
    • -
  • qstat - look at the list of jobs running and queued on the cluster
  • castep-mpi mpirun -np 8 castep.mpi diamond - submits a castep job with diamond.cell and diamond.param as inputs onto 8 cores with a time limit of 1 hour

    • c2x