{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {
    "Notes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "All branches are supported by "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "lambertw",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "module",
                "path": "scipy.special._lambertw:lambertw"
              },
              "kind": "module"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ":"
            }
          ]
        },
        {
          "__type": "BulletList",
          "__tag": 4053,
          "ordered": false,
          "start": 1,
          "children": [
            {
              "__type": "ListItem",
              "__tag": 4054,
              "children": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "lambertw(z)"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " gives the principal solution (branch 0)"
                    }
                  ]
                }
              ]
            },
            {
              "__type": "ListItem",
              "__tag": 4054,
              "children": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "lambertw(z, k)"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " gives the solution on branch "
                    },
                    {
                      "__type": "ParamRef",
                      "__tag": 4071,
                      "name": "k"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The Lambert W function has two partially real branches: the principal branch ("
            },
            {
              "__type": "InlineRole",
              "__tag": 4003,
              "value": "k = 0",
              "domain": null,
              "role": null,
              "inventory": null
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ") is real for real "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "z > -1/e"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", and the "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "k = -1"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " branch is real for "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "-1/e < z < 0"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". All branches except "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "k = 0"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " have a logarithmic singularity at "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "z = 0"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Strong",
              "__tag": 4048,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Possible issues"
                }
              ]
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The evaluation can become inaccurate very close to the branch point at "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "-1/e"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". In some corner cases, "
            },
            {
              "__type": "CrossRef",
              "__tag": 4002,
              "value": "lambertw",
              "reference": {
                "__type": "LocalRef",
                "__tag": 4022,
                "kind": "module",
                "path": "scipy.special._lambertw:lambertw"
              },
              "kind": "module"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " might currently fail to converge, or can end up on the wrong branch."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Strong",
              "__tag": 4048,
              "children": [
                {
                  "__type": "Text",
                  "__tag": 4046,
                  "value": "Algorithm"
                }
              ]
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Halley's iteration is used to invert "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "w * exp(w)"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ", using a first-order asymptotic approximation (O(log(w)) or "
            },
            {
              "__type": "InlineRole",
              "__tag": 4003,
              "value": "O(w)",
              "domain": null,
              "role": null,
              "inventory": null
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ") as the initial estimate."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The definition, implementation and choice of branches is based on "
            },
            {
              "__type": "FootnoteReference",
              "__tag": 4066,
              "label": "2"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Raises": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Yields": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Methods": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Returns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "w",
              "annotation": "array",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "CrossRef",
                      "__tag": 4002,
                      "value": "w",
                      "reference": {
                        "__type": "RefInfo",
                        "__tag": 4000,
                        "module": null,
                        "version": null,
                        "kind": "local",
                        "path": "w"
                      },
                      "kind": "local"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " will have the same shape as "
                    },
                    {
                      "__type": "ParamRef",
                      "__tag": 4071,
                      "name": "z"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Lambert W function."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Receives": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warnings": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Attributes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "z",
              "annotation": "array_like",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Input argument."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "k",
              "annotation": "int, optional",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Branch index."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "tol",
              "annotation": "float, optional",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Evaluation tolerance."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Extended Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The Lambert W function "
            },
            {
              "__type": "InlineRole",
              "__tag": 4003,
              "value": "W(z)",
              "domain": null,
              "role": null,
              "inventory": null
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " is defined as the inverse function of "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "w * exp(w)"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". In other words, the value of "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "W(z)"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " is such that "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "z = W(z) * exp(W(z))"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": " for any complex number "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "z"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The Lambert W function is a multivalued function with infinitely many branches. Each branch gives a separate solution of the equation "
            },
            {
              "__type": "InlineCode",
              "__tag": 4051,
              "value": "z = w exp(w)"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": ". Here, the branches are indexed by the integer "
            },
            {
              "__type": "ParamRef",
              "__tag": 4071,
              "name": "k"
            },
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Other Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    }
  },
  "_ordered_sections": [
    "Summary",
    "Extended Summary",
    "Parameters",
    "Attributes",
    "Methods",
    "Returns",
    "Yields",
    "Receives",
    "Other Parameters",
    "Raises",
    "Warns",
    "Warnings",
    "Notes"
  ],
  "item_file": "/scipy/special/_lambertw.py",
  "item_line": 6,
  "item_type": "function",
  "aliases": [
    "scipy.special.lambertw"
  ],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "The Lambert W function is the inverse of ``w exp(w)``:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "import numpy as np\nfrom scipy.special import lambertw\nw = lambertw(1)\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "w\nw * np.exp(w)\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nAny branch gives a valid inverse:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "w = lambertw(1, k=3)\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "w\nw*np.exp(w)\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\n**Applications to equation-solving**\n\nThe Lambert W function may be used to solve various kinds of\nequations.  We give two examples here.\n\nFirst, the function can be used to solve implicit equations of the\nform\n\n    :math:`x = a + b e^{c x}`\n\nfor :math:`x`.  We assume :math:`c` is not zero.  After a little\nalgebra, the equation may be written\n\n    :math:`z e^z = -b c e^{a c}`\n\nwhere :math:`z = c (a - x)`.  :math:`z` may then be expressed using\nthe Lambert W function\n\n    :math:`z = W(-b c e^{a c})`\n\ngiving\n\n    :math:`x = a - W(-b c e^{a c})/c`\n\nFor example,\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "a = 3\nb = 2\nc = -0.5\n",
        "execution_status": "success"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nThe solution to :math:`x = a + b e^{c x}` is:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "x = a - lambertw(-b*c*np.exp(a*c))/c\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "x\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nVerify that it solves the equation:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "a + b*np.exp(c*x)\n",
        "execution_status": "failure"
      },
      {
        "__type": "Text",
        "__tag": 4046,
        "value": "\nThe Lambert W function may also be used find the value of the infinite\npower tower :math:`z^{z^{z^{\\ldots}}}`:\n\n"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "def tower(z, n):\n    if n == 0:\n        return z\n    return z ** tower(z, n-1)\ntower(0.5, 100)\n",
        "execution_status": "success"
      },
      {
        "__type": "Code",
        "__tag": 4050,
        "value": "-lambertw(-np.log(0.5)) / np.log(0.5)\n",
        "execution_status": "failure"
      }
    ],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [
    {
      "__type": "SeeAlsoItem",
      "__tag": 4028,
      "name": {
        "__type": "CrossRef",
        "__tag": 4002,
        "value": "wrightomega",
        "reference": {
          "__type": "LocalRef",
          "__tag": 4022,
          "kind": "module",
          "path": "scipy.special.cython_special:wrightomega"
        },
        "kind": "module"
      },
      "descriptions": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "the Wright Omega function"
            }
          ]
        }
      ],
      "type": null
    }
  ],
  "signature": {
    "__type": "SignatureNode",
    "__tag": 4029,
    "kind": "function",
    "parameters": [
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "z",
        "annotation": {
          "__type": "Empty",
          "__tag": 4031
        },
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": {
          "__type": "Empty",
          "__tag": 4031
        }
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "k",
        "annotation": {
          "__type": "Empty",
          "__tag": 4031
        },
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "0"
      },
      {
        "__type": "SigParam",
        "__tag": 4030,
        "name": "tol",
        "annotation": {
          "__type": "Empty",
          "__tag": 4031
        },
        "kind": "POSITIONAL_OR_KEYWORD",
        "default": "1e-08"
      }
    ],
    "return_annotation": {
      "__type": "Empty",
      "__tag": 4031
    },
    "target_name": "lambertw"
  },
  "references": [
    ".. [1] https://en.wikipedia.org/wiki/Lambert_W_function",
    ".. [2] Corless et al, \"On the Lambert W function\", Adv. Comp. Math. 5",
    "   (1996) 329-359.",
    "   https://cs.uwaterloo.ca/research/tr/1993/03/W.pdf"
  ],
  "qa": "scipy.special._lambertw:lambertw",
  "arbitrary": [],
  "local_refs": [
    "k",
    "tol",
    "w",
    "z"
  ]
}