.. _faq:

**************************
Frequently Asked Questions
**************************

This is a list of Frequently Asked Questions about GYRE. Suggestions for new entries are always most welcome!

How Do I...
===========

...obtain the GYRE source code?
  See the :ref:`install-download` section.

...compile GYRE?
  See the :ref:`install-compile` section.

...pronounce GYRE?
  With a soft 'g' rhyming with 'wire', like :download:`this <faq/gyre-spoken.mp3>`.

...cite GYRE?
  See the :ref:`citing-gyre` section.

...ask a general question about GYRE?
  Start a new discussion on the GitHub :git:`discussions page <rhdtownsend/gyre/discussions>`.

...get support for a problem I'm having?
  Open an issue on the GitHub :git:`issues page <rhdtownsend/gyre/issues>`.

...contact the GYRE team?
  Send an email to `Rich Townsend <mailto:rhtownsend@wisc.edu>`__.

.. _faq-multicore:

...run GYRE on multiple cores?
  :ref:`performance-parallel` of GYRE should be enabled by
  default, but you can nevertheless force it by setting the :envvar:`OMP`
  environment variable to ``yes`` prior to compilation. Then, set the
  :envvar:`OMP_NUM_THREADS` environment variable to the number of threads
  you want to use (or leave unset for a sensible default choice).

...access the documentation for older releases?
  Click on the 'v:...'  dropdown menu in the bottom-right. Note that this
  menu is only available when viewing the
  `documentation <https://gyre.readthedocs.io/en/stable/>`__ on `Read
  the Docs <https://readthedocs.org/>`__; it isn't available in a
  local build within the :file:`{$GYRE_DIR}/docs` directory.
  Also, the legacy documentation is a work-in-progress, and remains
  incomplete.


What Does...
============
...'Failed during deflate narrow : out-of-domain frequency' mean?
  This is an indication that GYRE's root solver wandered out of bounds
  when trying to find a complex root of the discriminant function. Try running
  with a different choice of :nml:option:`diff_scheme <num.diff_scheme>` option
  (:nml:value:`MAGNUS_GL2` seems to be the most robust), and/or using
  contour method instead (see the :ref:`non-ad-osc` chapter).

Why Does...
===========

...the error 'Illegal Instruction' arise on MacOS when running with large grid sizes?
  This behavior is typically caused by overflow of the OpenMP stack
  (for more info see `here <https://stackoverflow.com/questions/13870564/gfortran-openmp-segmentation-fault-occurs-on-basic-do-loop>`__).
  Try setting the :envvar:`OMP_STACKSIZE` environment variable to 500K or 1M.