(spinw-gencoupling)=

# spinw.gencoupling method

## Syntax
 
`gencoupling(obj,Name,Value)`
 
## Description
 
`gencoupling(obj,Name,Value)` generates all bonds up to a certain length
between magnetic atoms. It also groups bonds based either on crystal
symmetry (is space group is not $P0$) or bond length (with `tolDist`
tolerance) is space group is not defined. Sorting bonds based on length
can be forced by setting the `forceNoSym` parameter to true. To check
whether a space group is defined call the [spinw.symmetry](#spinw-symmetry) function.
 
{% include warning.html content=" This function has to be used after the crystal structure is defined.
  The [spinw.addcoupling](#spinw-addcoupling) function will only work afterwards. " %}
 
## Examples
 
A triangular lattice is generated using `spinw.gencoupling` and
the [spinw.table](#spinw-table) function lists the 1st, 2nd and 3rd neighbor bonds:
 
```matlab
cryst = spinw
cryst.genlattice('lat_const',[3 3 5],'angled',[90 90 120])
cryst.addatom('r',[0 0 0],'S',1)
cryst.gencoupling
cryst.table('bond',1:3)
```
*Output*
```
  7×10 table
    idx    subidx         dl               dr          length     matom1     idx1     matom2     idx2        matrix    
    ___    ______    _____________    _____________    ______    ________    ____    ________    ____    ______________
     1       1       0     1     0    0     1     0        3     'atom_1'     1      'atom_1'     1      ''    ''    ''
     1       2       1     0     0    1     0     0        3     'atom_1'     1      'atom_1'     1      ''    ''    ''
     1       3       1     1     0    1     1     0        3     'atom_1'     1      'atom_1'     1      ''    ''    ''
     2       1       0     0     1    0     0     1        5     'atom_1'     1      'atom_1'     1      ''    ''    ''
     3       1       1    -1     0    1    -1     0    5.196     'atom_1'     1      'atom_1'     1      ''    ''    ''
     3       2       1     2     0    1     2     0    5.196     'atom_1'     1      'atom_1'     1      ''    ''    ''
     3       3       2     1     0    2     1     0    5.196     'atom_1'     1      'atom_1'     1      ''    ''    ''
```
 
 
## Input Arguments
 
`obj`
: [spinw](#spinw) object.
 
## Name-Value Pair Arguments
 
`'forceNoSym'`
: If `true`, equivalent bonds are always generated based on
  bond length with `tolDist` length tolerance and effectively reducing
  the bond symmetry to `P0`. If `false` symmetry operators will be used
  if they are given ([spinw.symmetry](#spinw-symmetry) returns `true`).
 
`'maxDistance'`
: Maximum bond length that will be stored in the
  [spinw.coupling](#spinw-coupling) property in units of Å. Default value is 8.
 
`'maxSym'`
: Maximum bond length until the symmetry equivalent bonds are
  generated. It is usefull if long bonds have to be generated for the
  dipolar interaction, but the symmetry analysis of them is not
  necessary. Default value is equal to `maxDistance`.
 
`'tolDist'`
: Tolerance of distance, within two bonds are considered
  equivalent, default value is $10^{-3}$Å. Only used, when no
  space group is defined.
 
`'dMin'`
: Minimum bond length, below which an error is triggered.
  Default value is 0.5 Å.
 
`'fid'`
: Defines whether to provide text output. The default value is determined
  by the `fid` preference stored in [swpref](#swpref). The possible values are:
  * `0`   No text output is generated.
  * `1`   Text output in the MATLAB Command Window.
  * `fid` File ID provided by the `fopen` command, the output is written
          into the opened file stream.
 
## Output Arguments
 
The [spinw.coupling](#spinw-coupling) field of `obj` will store the new bond list, while
overwriting previous bond list. This will also remove any previous
assignment of exchange matrices to bonds.
 
## See Also
 
[spinw](#spinw) \| [spinw.symmetry](#spinw-symmetry) \| [spinw.nosym](#spinw-nosym)