Refactor(input): encode relaxation variants in relax_method (deepmodeling#7735)

Author: Stardust0831

docs/advanced/input_files/input-main.md

@@ -133,7 +133,6 @@
     - [npart\_sto](#npart_sto)
   - [Geometry relaxation](#geometry-relaxation)
     - [relax\_method](#relax_method)
-    - [relax\_new](#relax_new)
     - [relax\_scale\_force](#relax_scale_force)
     - [relax\_nmax](#relax_nmax)
     - [relax\_cg\_thr](#relax_cg_thr)
@@ -1605,51 +1604,32 @@
 ### relax_method
 
 - **Type**: Vector of string
-- **Description**: The methods to do geometry optimization. The available algorithms depend on the relax_new setting.
+- **Description**: The method used for geometry optimization.
 
   First element (algorithm selection):
 
-  - cg: Conjugate gradient (CG) algorithm. Available for both relax_new = True (default, simultaneous optimization) and relax_new = False (nested optimization). See relax_new for implementation details.
-  - bfgs: Broyden–Fletcher–Goldfarb–Shanno (BFGS) quasi-Newton algorithm. Only available when relax_new = False.
-  - lbfgs: Limited-memory BFGS algorithm, suitable for large systems. Only available when relax_new = False.
-  - cg_bfgs: Mixed method starting with CG and switching to BFGS when force convergence reaches relax_cg_thr. Only available when relax_new = False.
-  - sd: Steepest descent algorithm. Only available when relax_new = False. Not recommended for production use.
-  - fire: Fast Inertial Relaxation Engine method, a molecular-dynamics-based relaxation algorithm. Use by setting calculation to md and md_type to fire. Ionic velocities must be set in STRU file. See fire for details.
+  - cg: Conjugate gradient (CG) algorithm.
+  - bfgs: Broyden–Fletcher–Goldfarb–Shanno (BFGS) quasi-Newton algorithm.
+  - lbfgs: Limited-memory BFGS algorithm, suitable for large systems.
+  - cg_bfgs: Mixed method starting with CG and switching to BFGS when force convergence reaches relax_cg_thr.
+  - sd: Steepest descent algorithm. Not recommended for production use.
 
-  Second element (BFGS variant, only when first element is bfgs):
+  Optional second element:
 
-  - 1: Traditional BFGS that updates the Hessian matrix B and then inverts it.
-  - 2 or omitted: Default BFGS that directly updates the inverse Hessian (recommended).
+  - cg 1: First optimize ionic positions at fixed cell, then update the cell, and repeat.
+  - cg 2 or omitted: Simultaneously optimize ionic positions and cell parameters with line search (recommended).
+  - bfgs 1: Traditional BFGS that updates the Hessian matrix B and then inverts it.
+  - bfgs 2 or omitted: Default BFGS that directly updates the inverse Hessian (recommended).
 
-  > Note: In the 3.10-LTS version, the type of this parameter is std::string. It can be set to "cg", "bfgs", "cg_bfgs", "bfgs_trad", "lbfgs", "sd", "fire".
-- **Default**: cg 1
-
-### relax_new
+  The second element is not accepted by other methods.
 
-- **Type**: Boolean
-- **Description**: Controls which implementation of geometry relaxation to use. At the end of 2022, a new implementation of the Conjugate Gradient (CG) method was introduced for relax and cell-relax calculations, while the old implementation was kept for backward compatibility.
-
-
-  - True (default): Use the new CG implementation with the following features:
-   - Simultaneous optimization of ionic positions and cell parameters (for cell-relax)
-   - Line search algorithm for step size determination
-   - Only CG algorithm is available (relax_method must be cg)
-   - Supports advanced cell constraints: fixed_axes = "shape", "volume", "a", "b", "c", etc.
-   - Supports fixed_ibrav to maintain lattice type
-   - More efficient for variable-cell relaxation
-   - Step size controlled by relax_scale_force
-
-  - False: Use the old implementation with the following features:
-   - Nested optimization procedure: ionic positions optimized first, then cell parameters (for cell-relax)
-   - Multiple algorithms available: cg, bfgs, lbfgs, sd, cg_bfgs
-   - Limited cell constraints: only fixed_axes = "volume" is supported
-   - Traditional approach with separate ionic and cell optimization steps
-- **Default**: True
+  > Note: In the 3.10-LTS version, the type of this parameter is std::string. It can be set to "cg", "bfgs", "cg_bfgs", "bfgs_trad", "lbfgs", "sd", "fire".
+- **Default**: cg 2
 
 ### relax_scale_force
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new set to True*
+- **Availability**: *Only used when relax_method is cg 2*
 - **Description**: The paramether controls the size of the first conjugate gradient step. A smaller value means the first step along a new CG direction is smaller. This might be helpful for large systems, where it is safer to take a smaller initial step to prevent the collapse of the whole configuration.
 - **Default**: 0.5
 
@@ -1662,7 +1642,7 @@
 ### relax_cg_thr
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method = cg_bfgs*
+- **Availability**: *Only used when relax_method is cg_bfgs*
 - **Description**: When relax_method is set to cg_bfgs, a mixed algorithm of conjugate gradient (CG) and Broyden–Fletcher–Goldfarb–Shanno (BFGS) is used. The ions first move according to the CG method, then switch to the BFGS method when the maximum force on atoms is reduced below this threshold.
 - **Default**: 0.5
 - **Unit**: eV/Angstrom
@@ -1691,37 +1671,37 @@
 ### relax_bfgs_w1
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method is bfgs or cg_bfgs*
+- **Availability**: *Only used when relax_method is bfgs or cg_bfgs*
 - **Description**: Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the sufficient decrease condition (c1 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177.
 - **Default**: 0.01
 
 ### relax_bfgs_w2
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method is bfgs or cg_bfgs*
+- **Availability**: *Only used when relax_method is bfgs or cg_bfgs*
 - **Description**: Controls the Wolfe condition for the Broyden–Fletcher–Goldfarb–Shanno (BFGS) algorithm used in geometry relaxation. This parameter sets the curvature condition (c2 in Wolfe conditions). For more information, see Phys. Chem. Chem. Phys., 2000, 2, 2177.
 - **Default**: 0.5
 
 ### relax_bfgs_rmax
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method is bfgs or cg_bfgs*
+- **Availability**: *Only used when relax_method is bfgs or cg_bfgs*
 - **Description**: Maximum allowed total displacement of all atoms during geometry optimization. The sum of atomic displacements can increase during optimization steps but cannot exceed this value.
 - **Default**: 0.8
 - **Unit**: Bohr
 
 ### relax_bfgs_rmin
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method = bfgs 1 (traditional BFGS)*
+- **Availability**: *Only used when relax_method is bfgs 1 (traditional BFGS)*
 - **Description**: Minimum allowed total displacement of all atoms. When the total atomic displacement falls below this value and force convergence is not achieved, the calculation will terminate. Note: This parameter is not used in the default BFGS algorithm (relax_method = bfgs 2 or bfgs).
 - **Default**: 1e-5
 - **Unit**: Bohr
 
 ### relax_bfgs_init
 
 - **Type**: Real
-- **Availability**: *Only used when relax_new = False and relax_method is bfgs or cg_bfgs*
+- **Availability**: *Only used when relax_method is bfgs or cg_bfgs*
 - **Description**: Initial total displacement of all atoms in the first BFGS step. This sets the scale for the initial movement.
 - **Default**: 0.5
 - **Unit**: Bohr
@@ -1758,9 +1738,9 @@
 
 - **Type**: String
 - **Availability**: *Only used when calculation is set to cell-relax*
-- **Description**: Specifies which cell degrees of freedom are fixed during variable-cell relaxation. The available options depend on the relax_new setting:
+- **Description**: Specifies which cell degrees of freedom are fixed during variable-cell relaxation. The available options depend on relax_method:
 
-  When relax_new = True (default), all options are available:
+  With relax_method = cg 2 (default), all options are available:
 
   - None: Default; all cell parameters can relax freely
   - volume: Relaxation with fixed volume (allows shape changes)
@@ -1771,21 +1751,17 @@
   - ab: Fix both a and b axes during relaxation
   - ac: Fix both a and c axes during relaxation
   - bc: Fix both b and c axes during relaxation
+  - abc: Fix all three lattice vectors during relaxation
 
-  When relax_new = False, all options are now available:
-
-  - None: Default; all cell parameters can relax freely
-  - volume: Relaxation with fixed volume (allows shape changes). Volume is preserved by rescaling the lattice after each update.
-  - shape: Fix shape but allow volume changes (hydrostatic pressure only). Stress tensor is replaced with isotropic pressure.
-  - a, b, c, ab, ac, bc: Fix specific lattice vectors. Gradients for fixed vectors are set to zero.
+  With relax_method set to cg 1, bfgs, lbfgs, sd, or cg_bfgs, None and a, b, c, ab, ac, bc, abc are available. The shape and volume options require cg 2.
 
-  > Note: For VASP users, see the ISIF correspondence table in the geometry optimization documentation. Both implementations now support all constraint types.
+  > Note: For VASP users, see the ISIF correspondence table in the geometry optimization documentation.
 - **Default**: None
 
 ### fixed_ibrav
 
 - **Type**: Boolean
-- **Availability**: *Can be used with both relax_new = True and relax_new = False. A specific latname must be provided.*
+- **Availability**: *Only used with relax_method = cg 2. A specific latname must be provided.*
 - **Description**: - True: the lattice type will be preserved during relaxation. The lattice vectors are reconstructed to match the specified Bravais lattice type after each update.
   - False: No restrictions are exerted during relaxation in terms of lattice type
 

docs/advanced/opt.md

@@ -2,13 +2,13 @@
 
 By setting `calculation` to be `relax` or `cell-relax`, ABACUS supports structural relaxation and variable-cell relaxation.
 
-ABACUS provides two implementations for variable-cell relaxation, controlled by the [relax_new](./input_files/input-main.md#relax_new) parameter:
+ABACUS provides two CG implementations for variable-cell relaxation, selected by the [relax_method](./input_files/input-main.md#relax_method) parameter:
 
-- **New implementation** (`relax_new = True`, default since v3.8): Uses a simultaneous conjugate gradient (CG) optimization for both ionic positions and cell parameters. Both degrees of freedom are optimized together in each step.
+- **CG variant 2** (`relax_method = cg 2` or `relax_method = cg`, default since v3.8): Uses simultaneous conjugate gradient (CG) optimization for both ionic positions and cell parameters. Both degrees of freedom are optimized together in each step.
 
-- **Old implementation** (`relax_new = False`): Follows a nested procedure where fixed-cell structural relaxation is performed first, followed by an update of the cell parameters, and the process is repeated until convergence is achieved.
+- **CG variant 1** (`relax_method = cg 1`): Follows a nested procedure where fixed-cell structural relaxation is performed first, followed by an update of the cell parameters, and the process is repeated until convergence is achieved.
 
-An example of the variable cell relaxation can be found in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/relax/pw_al), which is provided with the reference output file log.ref. When using the old implementation (`relax_new = False`), each ionic step is labelled in the following manner:
+An example of the variable cell relaxation can be found in our [repository](https://github.com/deepmodeling/abacus-develop/tree/develop/examples/relax/pw_al), which is provided with the reference output file log.ref. When using CG variant 1, each ionic step is labelled in the following manner:
 ```
  -------------------------------------------
  RELAX CELL : 3
@@ -21,28 +21,22 @@ indicating that this is the first ionic step of the 3rd cell configuration, and
 
 ## Optimization Algorithms
 
-ABACUS offers multiple optimization algorithms for structural relaxation, which can be selected using the [relax_method](./input_files/input-main.md#relax_method) keyword. The available algorithms and their behavior depend on the [relax_new](./input_files/input-main.md#relax_new) setting:
+ABACUS offers multiple optimization algorithms for structural relaxation, which can be selected using the [relax_method](./input_files/input-main.md#relax_method) keyword. The optional second value selects an implementation variant for CG or BFGS. For both methods, variant 1 is the traditional implementation and variant 2 is the recommended default.
 
-### Algorithm Availability
+### Available Algorithms
 
-**New implementation** (`relax_new = True`, default):
-- **CG (Conjugate Gradient)**: Simultaneous optimization of both ionic positions and cell parameters using CG with line search. This is the only algorithm available for the new implementation.
-
-**Old implementation** (`relax_new = False`):
-- **CG (Conjugate Gradient)**: For ionic relaxation; CG is also used for cell parameter optimization in the nested procedure
-- **BFGS**: Quasi-Newton method for ionic relaxation
-- **LBFGS**: Limited-memory BFGS for ionic relaxation
-- **SD (Steepest Descent)**: Simple gradient descent for ionic relaxation
-- **CG-BFGS**: Mixed method that starts with CG and switches to BFGS when force convergence reaches the threshold set by [relax_cg_thr](./input_files/input-main.md#relax_cg_thr)
+- **CG (Conjugate Gradient)**: Variant 1 optimizes ionic positions and cell parameters in separate stages; variant 2 optimizes them simultaneously with line search.
+- **BFGS**: Quasi-Newton method for ionic relaxation.
+- **LBFGS**: Limited-memory BFGS for ionic relaxation.
+- **SD (Steepest Descent)**: Simple gradient descent for ionic relaxation.
+- **CG-BFGS**: Mixed method that starts with CG and switches to BFGS when force convergence reaches the threshold set by [relax_cg_thr](./input_files/input-main.md#relax_cg_thr).
 
 We also provide a [list of keywords](./input_files/input-main.md#geometry-relaxation) for controlling the relaxation process.
 
 ### BFGS method
 
 The [BFGS method](https://en.wikipedia.org/wiki/Broyden%E2%80%93Fletcher%E2%80%93Goldfarb%E2%80%93Shanno_algorithm) is a quasi-Newton method for solving nonlinear optimization problems. It belongs to the class of quasi-Newton methods where the Hessian matrix is approximated during the optimization process. If the initial point is not far from the extrema, BFGS tends to work better than gradient-based methods.
 
-**Note**: BFGS is only available with the old implementation (`relax_new = False`).
-
 ABACUS provides two BFGS implementations, controlled by the second element of [relax_method](./input_files/input-main.md#relax_method):
 
 - **Default BFGS** (`relax_method = bfgs 2` or `relax_method = bfgs`): Updates the inverse of the approximate Hessian matrix B directly. This is the recommended implementation.
@@ -53,14 +47,12 @@ ABACUS provides two BFGS implementations, controlled by the second element of [r
 
 The [L-BFGS (Limited-memory BFGS)](https://en.wikipedia.org/wiki/Limited-memory_BFGS) method is a memory-efficient variant of BFGS that stores only a few vectors representing the Hessian approximation instead of the full matrix. This makes it particularly suitable for large systems with many atoms.
 
-**Note**: LBFGS is only available with the old implementation (`relax_new = False`). Set `relax_method = lbfgs` to use this method.
+Set `relax_method = lbfgs` to use this method.
 
 ### SD method
 
 The [SD (steepest descent) method](https://en.wikipedia.org/wiki/Gradient_descent) is one of the simplest first-order optimization methods, where in each step the motion is along the direction of the gradient, where the function descends the fastest.
 
-**Note**: SD is only available with the old implementation (`relax_new = False`).
-
 In practice, the SD method may take many iterations to converge, and is generally not recommended for production calculations.
 
 ### CG method
@@ -69,9 +61,11 @@ The [CG (conjugate gradient) method](https://en.wikipedia.org/wiki/Conjugate_gra
 
 ABACUS provides two implementations of the CG method:
 
-- **New CG implementation** (`relax_new = True`, default): Performs simultaneous optimization of both ionic positions and cell parameters using a line search algorithm. This implementation is more efficient for `cell-relax` calculations as it optimizes all degrees of freedom together. The step size can be controlled by [relax_scale_force](./input_files/input-main.md#relax_scale_force).
+- **CG variant 2** (`relax_method = cg 2` or `relax_method = cg`, default): Performs simultaneous optimization of both ionic positions and cell parameters using a line search algorithm. This implementation is more efficient for `cell-relax` calculations as it optimizes all degrees of freedom together. The step size can be controlled by [relax_scale_force](./input_files/input-main.md#relax_scale_force).
+
+- **CG variant 1** (`relax_method = cg 1`): Uses a nested procedure where ionic positions are optimized first using CG, followed by cell parameter optimization (also using CG) in `cell-relax` calculations. This is the traditional approach where the two optimization steps are separated.
 
-- **Old CG implementation** (`relax_new = False`): Uses a nested procedure where ionic positions are optimized first using CG, followed by cell parameter optimization (also using CG) in `cell-relax` calculations. This is the traditional approach where the two optimization steps are separated.
+The former `relax_new` parameter has been removed. Replace `relax_new = True` with `relax_method = cg 2`, and replace `relax_new = False` with `relax_method = cg 1` when using CG. The `bfgs`, `lbfgs`, `sd`, and `cg_bfgs` methods do not require a separate switch.
 
 ## Constrained Optimization
 
@@ -111,17 +105,15 @@ Sometimes we want to do variable-cell relaxation with some of the cell degrees o
 
 **Available constraints by implementation:**
 
-- **New implementation** (`relax_new = True`):
+- **CG variant 2** (`relax_method = cg 2` or `relax_method = cg`):
   - `fixed_axes = "shape"`: Only allows volume changes (hydrostatic pressure), cell shape is fixed
   - `fixed_axes = "volume"`: Allows shape changes but keeps volume constant
-  - `fixed_axes = "a"`, `"b"`, `"c"`, etc.: Fix specific lattice vectors or combinations
+  - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice vectors or combinations
   - `fixed_ibrav = True`: Maintain the Bravais lattice type during relaxation
 
-- **Old implementation** (`relax_new = False`):
-  - **All `fixed_axes` options now supported**: "shape", "volume", "a", "b", "c", "ab", "ac", "bc", "abc"
-  - **`fixed_ibrav` now supported**: Maintains Bravais lattice type during relaxation
-  - Can combine `fixed_axes` with `fixed_ibrav` for constrained relaxation
-  - **Implementation approach**: Uses post-update constraint enforcement (volume rescaling and lattice reconstruction after each CG step)
+- **`relax_method = cg 1`, `bfgs`, `lbfgs`, `sd`, or `cg_bfgs`**:
+  - `fixed_axes = "a"`, `"b"`, `"c"`, `"ab"`, `"ac"`, `"bc"`, or `"abc"`: Fix specific lattice vectors or combinations
+  - `fixed_axes = "shape"`, `"volume"` and `fixed_ibrav = True` are not available
 
 **VASP ISIF correspondence:**
 
@@ -142,4 +134,4 @@ Providing a file named `EXIT`:
 ```
 stop_ion    true
 ```
-ABACUS will end normally and produce a complete file.
+ABACUS will end normally and produce a complete file.