Troubleshooting - #40
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a dedicated troubleshooting guide to the mdBook documentation and expands the README troubleshooting section with more actionable optimizer/convergence remedies.
Changes:
- Added
docs/src/troubleshooting.mdwith common error causes and configuration-based remedies. - Linked the new troubleshooting page into the mdBook TOC via
docs/src/SUMMARY.md. - Expanded the README “Slow Convergence” solutions with concrete
max_stepsand optimizer configuration examples.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Expands troubleshooting “Slow Convergence” solutions with multiple optimizer configuration examples. |
| docs/src/troubleshooting.md | New troubleshooting page covering common errors, SCF issues, slow convergence, and optimizer reference tables. |
| docs/src/SUMMARY.md | Adds a new “Troubleshooting” section and links to the new page. |
Comments suppressed due to low confidence (1)
README.md:1988
- The fenced code block for the “gradient” blend example is missing its opening
fence. As written, the lines starting with `#===== Blend mode with hybrid ... gradient` will render as normal text, and the closingat the end will be unmatched. Add an opening fence before this example (or remove the stray closing fence) so the Markdown renders correctly.
#===== Blend mode with hybrid GDIIS/GEDIIS gradient ===================================
switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only
hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix
# Note: blend mode requires a direct Hessian method.
use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS,
# blend=GDIIS_blend with trust region
use_hybrid_gediis = true # activated when use_gediis = true or blend
# options: true/false
gediis_blend_mode = gradient # activated when use_gediis = blend AND use_hybrid_gediis = true
# options: fixed, fixed_sequential (default), gradient, sequential
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ``` | ||
| max_steps = 300 # maximum optimization steps | ||
| ``` | ||
| - Try other optimizers, for examples: | ||
| ``` | ||
| #===== Pure GDIIS: blend mode but zero contribution of GEDIIS =================================== | ||
| switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only | ||
| hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix | ||
| # Note: blend mode requires a direct Hessian method. | ||
| use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, | ||
| # blend=GDIIS_blend with trust region | ||
| use_hybrid_gediis = false # activated when use_gediis = true or blend | ||
| # options: true/false | ||
| gediis_blend_mode = fixed_sequential # activated when use_gediis = blend AND use_hybrid_gediis = true | ||
| # options: fixed, fixed_sequential (default), gradient, sequential | ||
|
|
||
| ``` |
| ``` | ||
| max_steps = 300 # maximum optimization steps | ||
| ``` | ||
| - Try other optimizers, for examples: |
| #===== Pure GDIIS: blend mode but zero contribution of GEDIIS =================================== | ||
| switch_step = 3 # 0=DIIS-only, 3=BFGS→DIIS (default), >=max_steps=BFGS-only | ||
| hessian = direct_psb # direct_psb (default) | inverse_bfgs | bofill | powell | bfgs_powell_mix | ||
| # Note: blend mode requires a direct Hessian method. | ||
| use_gediis = blend # options: false/none=GDIIS (default), true/sequential=GEDIIS, | ||
| # blend=GDIIS_blend with trust region | ||
| use_hybrid_gediis = false # activated when use_gediis = true or blend | ||
| # options: true/false | ||
| gediis_blend_mode = fixed_sequential # activated when use_gediis = blend AND use_hybrid_gediis = true | ||
| # options: fixed, fixed_sequential (default), gradient, sequential |
No description provided.