tips

This page is intended to collect experience and advice for using hypnotoad. Eventually this should be formalised into a user manual.

• Double Null   When generating double-null grids, if the input equilibrium is not connected you may get strange results around the second X-point if the radial resolution is high enough to see the fact that it is disconnected. The reason is that different code branches are used to set up grids for connected and disconnected equilibria. The 'connected' branch can tolerate small amounts of disconnection and will still produce output for larger amounts, but the output will not be good if the second X-point is more than ~1 grid spacing away from the first separatrix. Instead, set nx_intersep to a non-zero value to use the 'disconnected' code branch.

• x-boundary cells   BOUT++'s nx includes boundary cells (this may change in v5.0), it is recommended that grids should include boundary points in x, although BOUT++ will fill the boundary cells by extrapolation if they are not provided (this may change in v5, see https://github.com/boutproject/BOUT-dev/issues/2128). E.g. if you want 32 radial grid points in the core and 32 in the SOL with 2 boundary points (MXG=2, which is the BOUT++ default), then you need to set nx_core = 34 and nx_sol = 34.

• y-boundary cells   BOUT++ can load grid files with or without y-boundary cells included (this may change to require boundary cells in v5, see https://github.com/boutproject/BOUT-dev/issues/2128). The y-boundary cells are filled by extrapolation if not provided, which can lead to problems (e.g. negative Jacobian), so it is recommended to provide boundary cells in the grid file. This can be done by setting the option y_boundary_guards to a non-zero value (MYG=2 is the default number of y-boundary points in BOUT++). However, creating a grid in the boundaries requires following psi-contours past the wall. If your equilibrium file provides psi on a grid that extends a fair way past the wall then this should usually be fine, but often equilibrium files do not extend much past the wall. Extrapolating psi past the provided input usually does not provide a good result. Extending past the wall may also be a problem if there is a coil very close to the target. In these cases, the problem is minimised when ny is large, corresponding to a small poloidal grid spacing, because then the grid does not extend as far past the target. So the suggested workflow for setting non-zero y_boundary_guards would be: (i) explore parameters at low resolution with y_boundary_guards = 0 (which is the default); (ii) when you are happy with other settings, increase the various ny_* parameters, and see if the grid generates successfully with y_boundary_guards = 0 - if the grid reaches very close to the edge of the psi-contour plot at this point then you may have trouble on the next step; (iii) increase y_boundary_guards to the desired value - if this fails or produces a badly distorted grid in the boundaries, consider whether your model can run with fewer y-guard/y-boundary cells, which would make this gridding easier - if possible obtaining an equilibrium file which provides psi a bit further out is likely to be helpful; (iv) if all else fails, edit the grid file to ensure the values of the metric components, etc. in the y-boundary cells are sensible (whatever that means to you, at least make values that should be positive be positive).

• Errors when refining PsiContour or FineContour objects   creation of PsiContour or FineContour objects may fail when refining points. This often happens if the contour extends into a region where psi is not smooth enough. Some possible work-arounds:

  • if a coil or the centre column is close to a target then when y_boundary_guards>0 so that the contours have to extend past the target, the contours may extend to a region where psi is not smooth enough. One thing to try is increasing the relevant ny setting or decreasing target_*_poloidal_spacing_length to decrease the grid spacing, so that contours extend less far past the target. If this does not help, it may be the underlying FineContour object that is extending too far - in this case try decreasing finecontour_extend_prefactor; finecontour_extend_prefactor should be reduced as little as possible because if it is too small, distances may be calculated by extrapolating past the end of the FineContour, which will give inaccurate results.
  • if warnings about FineContour: maximum iterations (200) exceeded... are produced, try adding 'line' as the first entry of the refine_methods option. The line option seems to be more robust for the small changes needed for the iteration in FineContour.equaliseSpacing(). You could also try increasing finecontour_maxits and/or decreasing finecontour_overdamping_factor (this factor must be between 0 and 1 - closer to 1 is faster if it converges, but less robust, while closer to 0 is more robust).

• Staggered grids   If you use grids that are staggered in the y-direction (CELL_YLOW quantities in BOUT++) and have problems with simulations - possibly showing up as evolution being unphysically fast right from the beginning of a simulation. A possible cause of problems is spikes in the *_ylow metric coefficients due to Bp being very close to zero adjacent to the X-point. A hack to work around this is to set cap_Bp_ylow_xpoint = True - this option limits the minimum of Bp on the ylow points to the average of the adjacent cell-centre points.