0.2.0

tutorials/00_test.py

@@ -0,0 +1,3 @@
+# 测试代码
+import guan
+guan.test()

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

tutorials/daily_scenarios/01_ai_chat.py

@@ -0,0 +1,19 @@
+# AI 对话
+import guan
+
+response, history = guan.openai_chat("你好", model="qwen-plus") # 需要 API Key
+print()
+
+response = guan.langchain_chat_without_memory(prompt="你好", model="qwen-plus") # 需要 API Key
+response == guan.langchain_chat_with_memory(prompt="你好", model="qwen-plus") # 需要 API Key
+print()
+
+response = guan.ollama_chat(prompt='你好', model="qwen2.5:0.5b")  # 需要运行 Ollama 和下载对应的模型
+print()
+
+llm = guan.load_llama_model(model_path="D:/models/Qwen/Qwen3-0.6B-GGUF/Qwen3-0.6B-Q8_0.gguf") # 需要有模型文件
+response, history = guan.llama_chat(llm, '你好 /no_think')
+print()
+
+model, tokenizer = guan.load_modelscope_model(model_name="D:/models/Qwen/Qwen3-0.6B") # 需要有模型文件
+response, history = guan.modelscope_chat(model, tokenizer, '你好 /no_think')

tutorials/daily_scenarios/02_timing_log.py

@@ -0,0 +1,7 @@
+# 运行时间日志
+import guan
+import time
+guan.logging_with_day_and_time(content='start')
+for i in range(3):
+    time.sleep(5)
+    guan.logging_with_day_and_time(f'end_of_{i}')

tutorials/daily_scenarios/03_function_timer.py

@@ -0,0 +1,25 @@
+# 函数计时器
+import guan
+
+@guan.timer_decorator
+def test1(a, b):
+    import time
+    print(a)
+    time.sleep(1)
+    print(b)
+    print('Run finished.')
+
+for _ in range(2):
+    test1(10, b=20)
+
+print()
+
+def test2(a, b):
+    import time
+    print(a)
+    time.sleep(1)
+    print(b)
+    print('Run finished.')
+
+for _ in range(2):
+    guan.timer(test2, 100, b=200)

tutorials/daily_scenarios/04_try_except.py

@@ -0,0 +1,23 @@
+# try except 简写
+import guan
+
+@guan.try_decorator
+def test1(a, b):
+    print(a)
+    bug_code
+    print(b)
+    return 'return_message1'
+    
+result1 = test1(10, b=20)
+print(result1)
+
+print()
+
+def test2(a, b):
+    print(a)
+    bug_code
+    print(b)
+    return 'return_message2'
+
+result2 = guan.try_except(test2, 100, b=200)
+print(result2)

tutorials/daily_scenarios/05_dump_and_load_data.py

@@ -0,0 +1,7 @@
+# 变量写入文件
+import guan
+import numpy as np
+data = np.array([1, 2, 3])
+guan.dump_data(data, filename='a')
+loaded_data = guan.load_data(filename='a')
+print(loaded_data)

tutorials/daily_scenarios/06_print_array.py

@@ -0,0 +1,4 @@
+# 打印数组
+import guan
+a = [1, 2, 3, 'a', 'b', 'c']
+guan.print_array(a)

tutorials/daily_scenarios/07_matrix_in_file.py

@@ -0,0 +1,6 @@
+# 矩阵写入文件后查看
+import guan
+import numpy as np
+matrix = np.random.rand(5, 5)
+guan.write_matrix_in_markdown_format(matrix=matrix, filename='markdown_matrix')
+guan.write_matrix_in_latex_format(matrix=matrix, filename='latex_matrix')

tutorials/daily_scenarios/08_parallel_calculation.py

@@ -0,0 +1,15 @@
+# 并行计算
+import guan
+import time
+import os
+
+def run_proc(name):
+    start_time = time.time()
+    time.sleep(5)
+    end_time = time.time()
+    print ('Process id running on name %s = %s' % (name, os.getpid()), '; running time = %s' % (end_time-start_time))
+    return f'name_{name}'
+
+if __name__ == '__main__':
+    result_array = guan.parallel_calculation_with_multiprocessing_Pool(func=run_proc, args_list=range(32), show_time=1)
+    print(result_array)

tutorials/daily_scenarios/09_loop_calculation.py

@@ -0,0 +1,33 @@
+# 循环参数计算
+
+import guan
+import numpy as np
+
+def test_1(x):
+    return 2*x
+
+x_array = np.arange(0, 5, 1)
+result_array = guan.loop_calculation_with_one_parameter(test_1, x_array)
+print(result_array)
+guan.plot(x_array, result_array)
+print()
+
+def test_2(x, y):
+    return x+y
+
+x_array = np.arange(0, 5, 1)
+y_array = np.arange(0, 3, 1)
+result_array = guan.loop_calculation_with_two_parameters(test_2, x_array, y_array)
+print(result_array)
+guan.plot_contour(x_array, y_array, result_array)
+print()
+
+def test_3(x, y, z):
+    return x+y+z
+
+x_array = np.arange(0, 5, 1)
+y_array = np.arange(0, 3, 1)
+z_array = np.arange(0, 2, 1)
+result_array = guan.loop_calculation_with_three_parameters(test_3, x_array, y_array, z_array)
+print(result_array)
+guan.plot_contour(y_array, z_array, result_array[:, :, 4])

tutorials/daily_scenarios/10_is_hermitian.py

@@ -0,0 +1,16 @@
+# 检查是否为厄米矩阵
+import guan
+
+matrix1 = [
+    [2, 1.00001-1j],
+    [1+1j, 1]
+]
+
+print(guan.is_hermitian(matrix1))
+
+matrix2 = [
+    [2, 1.00002-1j],
+    [1+1j, 1]
+]
+
+print(guan.is_hermitian(matrix2))

tutorials/daily_scenarios/11_split_parameters.py

@@ -0,0 +1,9 @@
+# 数组分割
+import numpy as np
+import guan
+task_num = 4
+parameter_array_all = np.arange(0, 17, 1) 
+for task_index in range(task_num):
+    parameter_array = guan.preprocess_for_parallel_calculations(parameter_array_all, task_num, task_index)
+    print(parameter_array)
+    print()

tutorials/physics_scenarios/01_pauli_matrices.py

@@ -0,0 +1,4 @@
+# 泡利矩阵
+import guan
+sigma_x = guan.sigma_x()
+print(sigma_x)

tutorials/physics_scenarios/02_real_space_hamiltonian.py

@@ -0,0 +1,5 @@
+# 实空间哈密顿量
+import guan
+print('\n', guan.hamiltonian_of_finite_size_system_along_one_direction(3), '\n')
+print(guan.hamiltonian_of_finite_size_system_along_two_directions_for_square_lattice(2, 2), '\n')
+print(guan.hamiltonian_of_finite_size_system_along_three_directions_for_cubic_lattice(2, 2, 2), '\n')

tutorials/physics_scenarios/03_band_structure.py

@@ -0,0 +1,14 @@
+# 能带图计算
+import guan
+import numpy as np
+k_array = np.linspace(-np.pi, np.pi, 100)
+ # one dimensional chain
+hamiltonian_function = guan.one_dimensional_fourier_transform_with_k(unit_cell=0, hopping=1)
+eigenvalue_array = guan.calculate_eigenvalue_with_one_parameter(k_array, hamiltonian_function)
+guan.plot(k_array, eigenvalue_array, xlabel='k', ylabel='E', style='-k', fontfamily=None)
+# square lattice ribbon
+eigenvalue_array = guan.calculate_eigenvalue_with_one_parameter(k_array, guan.hamiltonian_of_square_lattice_in_quasi_one_dimension)
+guan.plot(k_array, eigenvalue_array, xlabel='k', ylabel='E', style='-k', fontfamily=None)
+# graphene ribbon
+eigenvalue_array = guan.calculate_eigenvalue_with_one_parameter(k_array, guan.hamiltonian_of_graphene_with_zigzag_in_quasi_one_dimension)
+guan.plot(k_array, eigenvalue_array, xlabel='k', ylabel='E', style='-k', fontfamily=None)

tutorials/physics_scenarios/04_chern_number_and_wilson_loop.py

@@ -0,0 +1,9 @@
+# 陈数和Wilson loop计算
+import guan
+import numpy as np
+chern_number = guan.calculate_chern_number_for_square_lattice_with_efficient_method(guan.hamiltonian_of_one_QAH_model, precision=100)
+print('\nChern number=', chern_number, '\n')
+wilson_loop_array = guan.calculate_wilson_loop(guan.hamiltonian_of_ssh_model)
+print('Wilson loop =', wilson_loop_array)
+p = np.log(wilson_loop_array)/2/np.pi/1j
+print('\np =', p, '\n')

tutorials/physics_scenarios/05_density_of_states_with_green_function.py

@@ -0,0 +1,34 @@
+# 使用格林函数计算态密度
+import guan
+import numpy as np
+
+hamiltonian = guan.hamiltonian_of_finite_size_system_along_two_directions_for_square_lattice(2,2)
+fermi_energy_array = np.linspace(-4, 4, 400)
+total_dos_array = guan.total_density_of_states_with_fermi_energy_array(fermi_energy_array, hamiltonian, broadening=0.1)
+guan.plot(fermi_energy_array, total_dos_array, xlabel='E', ylabel='Total DOS', style='-', fontfamily=None)
+
+fermi_energy = 0
+N1 = 3
+N2 = 4
+hamiltonian = guan.hamiltonian_of_finite_size_system_along_two_directions_for_square_lattice(N1,N2)
+LDOS = guan.local_density_of_states_for_square_lattice(fermi_energy, hamiltonian, N1=N1, N2=N2)
+print('square lattice:\n', LDOS, '\n')
+h00 = guan.hamiltonian_of_finite_size_system_along_one_direction(N2)
+h01 = np.identity(N2)
+LDOS = guan.local_density_of_states_for_square_lattice_using_dyson_equation(fermi_energy, h00=h00, h01=h01, N2=N2, N1=N1)
+print(LDOS, '\n\n')
+LDOS2 = guan.local_density_of_states_for_square_lattice_using_dyson_equation_with_second_method(fermi_energy, h00, h01, N2, N1, internal_degree=1, broadening=0.01)
+print(LDOS2, '\n\n')
+guan.plot_contour(range(N1), range(N2), LDOS, fontfamily=None)
+guan.plot_contour(range(N1), range(N2), LDOS2, fontfamily=None)
+
+N1 = 3
+N2 = 4
+N3 = 5
+hamiltonian = guan.hamiltonian_of_finite_size_system_along_three_directions_for_cubic_lattice(N1, N2, N3)
+LDOS = guan.local_density_of_states_for_cubic_lattice(fermi_energy, hamiltonian, N1=N1, N2=N2, N3=N3)
+print('cubic lattice:\n', LDOS, '\n')
+h00 = guan.hamiltonian_of_finite_size_system_along_two_directions_for_square_lattice(N2, N3)
+h01 = np.identity(N2*N3)
+LDOS = guan.local_density_of_states_for_cubic_lattice_using_dyson_equation(fermi_energy, h00, h01, N3=N3, N2=N2, N1=N1)
+print(LDOS)

tutorials/physics_scenarios/06_conductance_and_scattering_matrix.py

@@ -0,0 +1,12 @@
+# 电导和散射矩阵的计算
+import guan
+import numpy as np
+
+fermi_energy_array = np.linspace(-4, 4, 400)
+h00 = guan.hamiltonian_of_finite_size_system_along_one_direction(4)
+h01 = np.identity(4)
+conductance_array = guan.calculate_conductance_with_fermi_energy_array(fermi_energy_array, h00, h01)
+guan.plot(fermi_energy_array, conductance_array, xlabel='E', ylabel='Conductance', style='-', fontfamily=None)
+
+fermi_energy = 0
+guan.print_or_write_scattering_matrix(fermi_energy, h00, h01)

tutorials/physics_scenarios/07_wavefunction_gauge.py

@@ -0,0 +1,22 @@
+# 波函数规范的选取
+import numpy as np
+import cmath
+import guan
+
+# Fixed gauge example 1
+vector = np.array([np.sqrt(0.5), np.sqrt(0.5)])*cmath.exp(np.random.uniform(0, 1)*1j)
+print('\nExample 1\n', vector)
+print(np.dot(vector.transpose().conj(), vector), '\n')
+
+vector = guan.find_vector_with_fixed_gauge_by_making_one_component_real(vector)
+print(vector)
+print(np.dot(vector.transpose().conj(), vector), '\n')
+
+# Fixed gauge example 2
+vector = np.array([1, 0])*cmath.exp(np.random.uniform(0, 1)*1j)
+print('\nExample 2\n', vector)
+print(np.dot(vector.transpose().conj(), vector), '\n')
+
+vector = guan.find_vector_with_fixed_gauge_by_making_one_component_real(vector)
+print(vector)
+print(np.dot(vector.transpose().conj(), vector), '\n')