123 lines
4.1 KiB
ReStructuredText
123 lines
4.1 KiB
ReStructuredText
:orphan:
|
|
|
|
###########################################
|
|
Frequently asked questions for LightningCLI
|
|
###########################################
|
|
|
|
************************
|
|
What does CLI stand for?
|
|
************************
|
|
CLI is short for command line interface. This means it is a tool intended to be run from a terminal, similar to commands
|
|
like ``git``.
|
|
|
|
----
|
|
|
|
.. _what-is-a-yaml-config-file:
|
|
|
|
***************************
|
|
What is a yaml config file?
|
|
***************************
|
|
A YAML is a standard for configuration files used to describe parameters for sections of a program. It is a common tool
|
|
in engineering and has recently started to gain popularity in machine learning. An example of a YAML file is the
|
|
following:
|
|
|
|
.. code:: yaml
|
|
|
|
# file.yaml
|
|
car:
|
|
max_speed:100
|
|
max_passengers:2
|
|
plane:
|
|
fuel_capacity: 50
|
|
class_3:
|
|
option_1: 'x'
|
|
option_2: 'y'
|
|
|
|
If you are unfamiliar with YAML, the short introduction at `realpython.com#yaml-syntax
|
|
<https://realpython.com/python-yaml/#yaml-syntax>`__ might be a good starting point.
|
|
|
|
----
|
|
|
|
*********************
|
|
What is a subcommand?
|
|
*********************
|
|
A subcommand is what is the action the LightningCLI applies to the script:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py [subcommand]
|
|
|
|
See the Potential subcommands with:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py --help
|
|
|
|
which prints:
|
|
|
|
.. code:: bash
|
|
|
|
...
|
|
|
|
fit Runs the full optimization routine.
|
|
validate Perform one evaluation epoch over the validation set.
|
|
test Perform one evaluation epoch over the test set.
|
|
predict Run inference on your data.
|
|
|
|
use a subcommand as follows:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit
|
|
python main.py test
|
|
|
|
----
|
|
|
|
*******************************************************
|
|
What is the relation between LightningCLI and argparse?
|
|
*******************************************************
|
|
|
|
:class:`~lightning.pytorch.cli.LightningCLI` makes use of `jsonargparse <https://github.com/omni-us/jsonargparse>`__
|
|
which is an extension of `argparse <https://docs.python.org/3/library/argparse.html>`__. Due to this,
|
|
:class:`~lightning.pytorch.cli.LightningCLI` follows the same arguments style as many POSIX command line tools. Long
|
|
options are prefixed with two dashes and its corresponding values are separated by space or an equal sign, as ``--option
|
|
value`` or ``--option=value``. Command line options are parsed from left to right, therefore if a setting appears
|
|
multiple times, the value most to the right will override the previous ones.
|
|
|
|
----
|
|
|
|
*******************************************
|
|
What is the override order of LightningCLI?
|
|
*******************************************
|
|
|
|
The final configuration of CLIs implemented with :class:`~lightning.pytorch.cli.LightningCLI` can depend on default
|
|
config files (if defined), environment variables (if enabled) and command line arguments. The override order between
|
|
these is the following:
|
|
|
|
1. Defaults defined in the source code.
|
|
2. Existing default config files in the order defined in ``default_config_files``, e.g. ``~/.myapp.yaml``.
|
|
3. Entire config environment variable, e.g. ``PL_FIT__CONFIG``.
|
|
4. Individual argument environment variables, e.g. ``PL_FIT__SEED_EVERYTHING``.
|
|
5. Command line arguments in order left to right (might include config files).
|
|
|
|
----
|
|
|
|
****************************
|
|
How do I troubleshoot a CLI?
|
|
****************************
|
|
The standard behavior for CLIs, when they fail, is to terminate the process with a non-zero exit code and a short
|
|
message to hint the user about the cause. This is problematic while developing the CLI since there is no information to
|
|
track down the root of the problem. To troubleshoot set the environment variable ``JSONARGPARSE_DEBUG`` to any value
|
|
before running the CLI:
|
|
|
|
.. code:: bash
|
|
|
|
export JSONARGPARSE_DEBUG=true
|
|
python main.py fit
|
|
|
|
.. note::
|
|
|
|
When asking about problems and reporting issues, please set the ``JSONARGPARSE_DEBUG`` and include the stack trace
|
|
in your description. With this, users are more likely to help identify the cause without needing to create a
|
|
reproducible script.
|