.. warning::

        End users will typically not have to call this function because the
        the interactive mode takes care of this.
    )