0.2.0

tutorials/README.md

@@ -0,0 +1,93 @@
+# Tutorials
+
+Learning examples for the [Guan package](https://py.guanjihuan.com), extracted from the blog post
+[Guan软件包学习示例](https://www.guanjihuan.com/archives/38367).
+
+One example per file. Each file is a self-contained script that you can run directly, or copy the
+functions you need into your own project.
+
+## Installation
+
+```bash
+pip install --upgrade guan
+```
+
+```python
+import guan
+```
+
+## Run the examples
+
+```bash
+python tutorials/daily_scenarios/01_ai_chat.py
+python tutorials/physics_scenarios/03_band_structure.py
+```
+
+## Directory
+
+```
+tutorials/
+├── 00_test.py                                  # package self test
+├── daily_scenarios/                            # 一、日常场景
+│   ├── 01_ai_chat.py
+│   ├── 02_timing_log.py
+│   ├── 03_function_timer.py
+│   ├── 04_try_except.py
+│   ├── 05_dump_and_load_data.py
+│   ├── 06_print_array.py
+│   ├── 07_matrix_in_file.py
+│   ├── 08_parallel_calculation.py
+│   ├── 09_loop_calculation.py
+│   ├── 10_is_hermitian.py
+│   └── 11_split_parameters.py
+└── physics_scenarios/                          # 二、物理场景
+    ├── 01_pauli_matrices.py
+    ├── 02_real_space_hamiltonian.py
+    ├── 03_band_structure.py
+    ├── 04_chern_number_and_wilson_loop.py
+    ├── 05_density_of_states_with_green_function.py
+    ├── 06_conductance_and_scattering_matrix.py
+    └── 07_wavefunction_gauge.py
+```
+
+## 一、日常场景 / Daily scenarios
+
+| File | 说明 | Requirements |
+| --- | --- | --- |
+| `00_test.py` | 软件包自检 `guan.test()` | - |
+| `01_ai_chat.py` | AI 对话：内置模型、OpenAI 兼容接口、LangChain、Ollama、llama.cpp、ModelScope | OpenAI 接口需要 API Key；Ollama / llama.cpp / ModelScope 需要本地模型 |
+| `02_timing_log.py` | 带日期和时间的运行日志 `guan.logging_with_day_and_time` | - |
+| `03_function_timer.py` | 函数计时器：`@guan.timer_decorator` 与 `guan.timer` | - |
+| `04_try_except.py` | try except 简写：`@guan.try_decorator` 与 `guan.try_except` | - |
+| `05_dump_and_load_data.py` | 变量写入文件并读回 | numpy |
+| `06_print_array.py` | 打印数组 | numpy |
+| `07_matrix_in_file.py` | 矩阵写入 Markdown / LaTeX 格式文件后查看 | numpy |
+| `08_parallel_calculation.py` | 多进程并行计算 | - |
+| `09_loop_calculation.py` | 循环参数计算（一、二、三个参数）与作图 | numpy, matplotlib |
+| `10_is_hermitian.py` | 检查是否为厄米矩阵（相对误差 1e-5） | numpy |
+| `11_split_parameters.py` | 数组分割，为并行计算准备参数 | numpy |
+
+## 二、物理场景 / Physics scenarios
+
+| File | 说明 | Requirements |
+| --- | --- | --- |
+| `01_pauli_matrices.py` | 泡利矩阵 | numpy |
+| `02_real_space_hamiltonian.py` | 一维 / 二维方格 / 三维立方格的实空间哈密顿量 | numpy |
+| `03_band_structure.py` | 能带图计算：一维链、方格带、石墨烯锯齿形带 | numpy, matplotlib |
+| `04_chern_number_and_wilson_loop.py` | 陈数与 Wilson loop 计算 | numpy |
+| `05_density_of_states_with_green_function.py` | 用格林函数计算态密度（方格与立方格，局域态密度） | numpy, matplotlib |
+| `06_conductance_and_scattering_matrix.py` | 电导与散射矩阵的计算 | numpy, matplotlib |
+| `07_wavefunction_gauge.py` | 波函数规范（fixed gauge）的选取 | numpy |
+
+## 说明 / Notes
+
++ Some examples need an API Key, a local Ollama/llama.cpp/ModelScope model, or a specific model path.
+  Edit the paths in the scripts before running them.
++ `04_try_except.py` contains a deliberate `bug_code` call to demonstrate the exception handling.
++ Figures are saved to the current working directory when the plotting functions are used.
+
+## License / 许可
+
+The source post is published under [CC BY](https://www.guanjihuan.com), by
+[Ji-Huan Guan](https://www.guanjihuan.com/about). Please cite the source when quoting:
+https://www.guanjihuan.com/archives/38367