{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# 环境搭建"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"在这份文档中，我们会大量使用 Python 与 PySCF，并通常使用 Jupyter Notebook 进行笔记记录与程序呈现。因此，在开始这份笔记之前，我们需要先搭建好程序环境。"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**提示**\n",
"\n",
"由于 PySCF 一般只在 Linux 环境下运行，因此请使用 Linux 机器、Linux 虚拟机、或者使用 Windows Subsystem of Linux (WSL)。WSL 只在 Windows 10/11 系统上运作，其安装方式参考 [微软文档](https://docs.microsoft.com/en-us/windows/wsl/install-win10)。\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Python 环境"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"在这里，我们使用 PyPI 进行库管理。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**提示**\n",
"\n",
"Python 的库管理工具有许多；一般来说，最常用的 PyPI 是 Python 社区支持的库索引，Anaconda 则是另一个大型商业的社区库索引。PyPI 的库管理工具是 `pip`，而 Anaconda 的库管理工具是 `conda`。\n",
"\n",
"由于 conda 管理工具的效率较低，在图方便的情况下，我们可以使用 pip 管理当前的 Python 库；但如果担心依赖包冲突的情况，则使用 conda 安装 pyscf。当然，大多数情况下，我们可以同时使用两者进行库管理．\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"对于我们目前的工作，安装必须库所执行的命令是\n",
"\n",
" $ pip install numpy pyscf jupyter"
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**任务**\n",
"\n",
"1. 先在用户目录下安装一个 Python 发行版。Python 发行版可以是 [官方发行版](https://www.python.org/downloads/) 或操作系统提供的版本，但更通常的做法是使用 [Anaconda 发行版](https://www.anaconda.com/distribution/#download-section)。Anaconda 发行版在大小适中的硬盘空间下，配置了绝大多数科学计算所必须的 Python 库，较为便利。注意请尽量不要安装 Python 3.6 及以下的版本。\n",
"\n",
"2. 安装后，请先执行 `python`，并在 Bash 下执行 `which python` 查看 Python 可执行文件是否正确。若不正确，请向 `$HOME/.bash_profile` 或 `$HOME/.bashrc` 中修改 `PATH` 路径。\n",
"\n",
"3. (可选) 根据 [清华镜像 PyPI 帮助](https://mirror.tuna.tsinghua.edu.cn/help/pypi/) 文档的指示，修改默认 PyPI 索引镜像，以加速 Python 库的下载速度。如果使用 conda 进行库管理，也可类似地修改镜像源。\n",
"\n",
"4. (可选) 有时，我们想要在一套全新干净的 Python 环境中工作；有时，会碰到 Python 库依赖冲突的问题。在这种情况下，我们可以考虑使用虚环境解决这些问题。若只用 PyPI 进行库管理，可以使用 [virtualenv](https://virtualenv.pypa.io/en/latest/userguide/) 进行管理 (一份有用的中文帮助可以参考 [廖雪峰的博文](https://www.liaoxuefeng.com/wiki/0014316089557264a6b348958f449949df42a6d3a2e542c000/001432712108300322c61f256c74803b43bfd65c6f8d0d0000))。如果使用 conda 进行库管理，开可以使用 `conda create` 构建新的虚环境；可以在 Bash 下执行 `conda create -h` 查看帮助与示例。\n",
"\n",
"5. (可选) 在了解如何构建虚环境后，可以考虑将在一个新的虚环境中使用 Intel 提供的 Python 主程序与各种关键的数学库。可以参照 [Intel Python 安装文档](https://software.intel.com/en-us/distribution-for-python/choose-download) 配置你的 Python 环境。Intel Python 提供了 conda 与 pip 的安装途径。\n",
"\n",
"6. (可选) 如果我们还希望通过一阶梯度信息进行几何结构优化，一个方便的 Python 库是 [berny 库](https://jan.hermann.name/pyberny/)。安装方式如下：\n",
"\n",
" ```bash\n",
" $ pip install pyberny\n",
" ```\n",
"\n",
"7. (可选) Jupyter Notebook 具有一些非官方的插件，譬如代码折叠、文档标题折叠、代码块隐藏、PEP8 检查等功能。若对这些功能感兴趣，可以参考 [Unofficial Jupyter Notebook Extensions](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/)。\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**提示**\n",
"\n",
"在组内服务器上，默认情况下我们可能无法连接到互联网，从而难以更新 Python 库。一种解决方案是使用信息办提供的脚本。解决方案文档请参考\n",
"\n",
" /share/home/zyzhu/Documents-Shared/group_related/2019-01-09-how_to_connect_internet.markdown\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## `pyxdh` 库配置"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"为了运行文档，我们还需要对库 `pyxdh` 进行配置。该库可以执行 xDH 型泛函的梯度、MP2 的二阶梯度等分子性质，并且可以提取计算过程中的中间矩阵。以后的文档会经常使用该库。\n",
"\n",
"请参考代码库主页文档 [README.md](https://github.com/ajz34/Py_xDH#usage) 进行配置，并运行以下代码。下述验证与 Gaussian 所得到的 B3LYP 梯度的代码应当要能执行通过。关于下述代码的解释，将会在以后的文档中说明。"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([[-0.03447596, 0.0666383 , 0.1260704 ],\n",
" [ 0.00989735, 0.16068374, -0.160493 ],\n",
" [ 0.00681508, 0.01243452, 0.03260963],\n",
" [ 0.01776359, -0.2397567 , 0.00181296]])"
]
},
"execution_count": 1,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from pyxdh.DerivOnce import GradSCF\n",
"from pyxdh.Utilities.test_molecules import Mol_H2O2\n",
"\n",
"H2O2 = Mol_H2O2()\n",
"grad_helper = GradSCF({\"scf_eng\": H2O2.gga_eng})\n",
"grad_helper.E_1"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [],
"source": [
"from pkg_resources import resource_filename\n",
"from pyxdh.Utilities import FormchkInterface\n",
"formchk = FormchkInterface(resource_filename(\"pyxdh\", \"Validation/gaussian/H2O2-B3LYP-freq.fchk\"))"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"True"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import numpy as np\n",
"np.allclose(grad_helper.E_1, formchk.grad(), atol=1e-5, rtol=1e-4)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## PySCF 环境"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"绝大多数情况下，我们无需更改 PySCF 的代码就能调用并调试其中的函数。因此，一般来说，无需作任何准备。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**注意**\n",
"\n",
"我们在以前的软件 Hacking 过程中，经常会通过语句打印来了解程序运行流程与结果；并通过修改程序以引入新的功能。\n",
"\n",
"但若用常识思考，打印语句其实不是很便利，而修改程序则是非常危险的行为。即使使用版本控制工具，也可能因为使用不善造成工作损失，或者在代码更改历史中迷失方向。\n",
"\n",
"对于面向对象语言，在已有程序上实现新功能可以通过类的继承于重载来实现。大多数 Fortran 与 C 语言 (或者写得不友好的 C++ 程序) 的软件难以做到这一点。当然，面向对象的优势不只具有修改程序的安全性，毕竟“面向对象”的本来的主要意义是使用类 (Class) 打包方法 (method function) 与成员 (member)，不过这是后话；我们以后也会渐渐接触类的概念。\n",
"\n",
"而程序流程的控制与结果的打印则可以通过集成开发环境 (IDE) 不更改代码地通过打断点，并使用代码逐步执行的功能实现。对于 Python，一般来说还支持在程序运行过程中计算数据。\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## PyCharm 环境"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"若要了解说明文档的运行，Jupyter Notebook 的环境已经足够。但 `pyxdh` 库作为程序，如果打算作更为细致的阅读与调试，IDE 是必不可少的。\n",
"\n",
"IDE 通常可以大大加速代码的阅读、调试与编写能力。有许多 IDE 支持 Python；作者通常使用 PyCharm。不同 IDE 之间的功能会大同小异，因此读者跟着自己的习惯就行。常用的其它 IDE 可以是 Spyder、Visual Studio、Eclipse。常用的带有 IDE 功能的文本编辑器是 Visual Studio Code。尽管带插件的 Vim 编辑器应当也可以当作 IDE 使用，但通常来说，体验会远差于 IDE。不带插件的 Vim 不推荐用来调试与编写 Python 程序。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n",
"**任务**\n",
"\n",
"下面的任务专门针对 PyCharm。\n",
"\n",
"1. 对于学校用户，可以使用 PyCharm Professional。请参考 JetBrain 公司网页 [Free individual licenses for students and faculty members](https://www.jetbrains.com/student/)。你也许同时可以注册一个 [GitHub Student Developer Pack](https://education.github.com/pack)。\n",
"\n",
"2. 对于 Windows 用户，PyCharm Professional 支持 WSL 下的 Python 解释器。请参考 PyCharm 下的设置、以及下述网页：[Configure a remote interpreter using WSL](https://www.jetbrains.com/help/pycharm/using-wsl-as-a-remote-interpreter.html)\n",
"\n",
"3. (可选) 若需要对 IDE 的使用特性快速入门，可以尝试 JetBrain 的另一个产品 IntelliJ IDEA (Java 语言)。该软件在安装过程中提供了交互的 IDE 的新手入门插件。PyCharm 也属于 IntelliJ 系列；可以参考该入门以熟悉 IntelliJ 的一系列产品。\n",
"\n",
"下面的任务可以看作使用 IDE 的练习，但需要对 Python 或其它编程语言的代码风格约定有一定的认识。当然，IDE 的功能不仅仅是检查语法错误和代码风格；其它的功能需要真正地编写或调试程序才会使用到。\n",
"\n",
"4. [PEP 8](https://www.python.org/dev/peps/pep-0008/) 是一种通用与宽松的 Python 代码风格约定。良好的代码风格会帮助程序的书写与阅读。请通过 IDE 打开程序 `pyxdh/DerivOnce/grad_scf.py`，指出程序中不符合 PEP 8 规则的代码以及原因。`pyxdh` 库一般来说会避免 PEP 8 coding style violation，但少数情况下不可避免地使用不良风格的代码。\n",
"\n",
"5. (可选) 如果你没有找到 PEP 8 naming convention violation，请尝试到 Setting 重新打开命名规则检查。`pyxdh` 库的绝大部分变量名称不遵守 PEP 8 规则。\n",
"\n",
"6. (可选) (作者未尝试解决) PEP 8 尽管有很多限制，但现实中有更为严格的代码风格。若对 Python 稍有了解，则可以参考 [Google Python Style Guide](http://google.github.io/styleguide/pyguide.html)，理解一些规则的来龙去脉，并对程序的代码风格作一些判断。你可能会发现 `pyxdh` 的代码风格并不好。如果希望尝试一些自动化的初步的代码风格纠正工具，可以参考 [black](https://github.com/python/black)。\n",
"\n",
"
"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.2"
}
},
"nbformat": 4,
"nbformat_minor": 2
}