NTN-F

def dados(data: DateLike) -> pl.DataFrame:
    """
    Busca as taxas indicativas de NTN-F para a data de referência.

    Args:
        data (DateLike): Data da consulta.

    Returns:
        pl.DataFrame: DataFrame Polars com os dados de NTN-F. Na ausência de
            dados, retorna vazio com as mesmas colunas e tipos.

    Output Columns:
        - data_referencia (Date): Data de referência dos dados.
        - titulo (String): Tipo do título (ex.: "NTN-F").
        - codigo_selic (Int64): Código do título no SELIC.
        - data_base (Date): Data base de emissão do título.
        - data_vencimento (Date): Data de vencimento do título.
        - dias_uteis (Int64): Dias úteis entre referência e vencimento.
        - prazo_medio (Float64): Prazo médio do título em dias corridos.
        - duration (Float64): Macaulay Duration do título (anos).
        - dv01 (Float64): Variação no preço para 1bp de taxa.
        - pu (Float64): Preço unitário (PU).
        - taxa_compra (Float64): Taxa de compra (decimal).
        - taxa_venda (Float64): Taxa de venda (decimal).
        - taxa_indicativa (Float64): Taxa indicativa (decimal).
        - taxa_di (Float64): Taxa de ajuste do DI Futuro interpolada pelo
            método flat forward.
        - taxa_zero (Float64): Taxa zero (zero cupom via bootstrap).
        - premio (Float64): prêmio, isto é, o spread sobre o DI.
        - premio_limpo (Float64): prêmio limpo sobre a curva DI.
        - rentabilidade (Float64): Rentabilidade da NTN-F sobre a curva DI.

    Examples:
        >>> from pyield import ntnf
        >>> df_ntnf = ntnf.dados("23-08-2024")  # doctest: +SKIP
    """
    df = _utils.obter_tpf(data, "NTN-F")
    if df.is_empty():
        return pl.DataFrame(schema=_SCHEMA_DADOS)

    # Adiciona duration, prazo_medio, dv01 e taxa_di
    df = df.with_columns(
        dias_uteis=du.contar_expr("data_referencia", "data_vencimento"),
        duration=duration_expr("data_referencia", "data_vencimento", "taxa_indicativa"),
    ).with_columns(
        prazo_medio=pl.col("duration"),
        dv01=dv01_expr("data_referencia", "data_vencimento", "taxa_indicativa"),
    )
    df = _utils.adicionar_taxa_di(df, data)

    # Busca dados de LTN para bootstrap das taxas spot
    df_ltn = _utils.obter_tpf(data, "LTN").select("data_vencimento", "taxa_indicativa")
    df_spots = taxas_zero(
        data_liquidacao=data,
        vencimentos_ltn=df_ltn["data_vencimento"],
        taxas_ltn=df_ltn["taxa_indicativa"],
        vencimentos_ntnf=df["data_vencimento"],
        taxas_ntnf=df["taxa_indicativa"],
    ).select("data_vencimento", "taxa_zero")
    df = df.join(df_spots, on="data_vencimento", how="left")

    # Busca curva DI para cálculo da rentabilidade
    df_di = di1.dados(data, inicio_mes=True)

    # Calcula prêmios e rentabilidade para cada vencimento
    df = df.with_columns(
        premio=pl.col("taxa_indicativa") - pl.col("taxa_di"),
        premio_limpo=premio_limpo_expr(
            data_liquidacao=data,
            data_vencimento="data_vencimento",
            taxa_ntnf="taxa_indicativa",
            vencimentos_di=df_di["data_vencimento"],
            taxas_di=df_di["taxa_ajuste"],
        ),
        rentabilidade=rentabilidade_expr(
            data_liquidacao=data,
            data_vencimento="data_vencimento",
            taxa_ntnf="taxa_indicativa",
            vencimentos_di=df_di["data_vencimento"],
            taxas_di=df_di["taxa_ajuste"],
        ),
    )

    return df.select(*_SCHEMA_DADOS)

def datas_pagamento(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
) -> pl.Series:
    """
    Gera todas as datas de pagamento entre liquidação e vencimento.

    As datas são exclusivas para a liquidação e inclusivas para o vencimento.
    Os pagamentos são semestrais, em 1º de janeiro e 1º de julho. No
    vencimento, o fluxo inclui o último cupom e a amortização do principal. O
    título NTN-F é determinado pela data de vencimento. As datas são contratuais
    e não são ajustadas para dias úteis.

    Args:
        data_liquidacao (DateLike): Data de liquidação.
        data_vencimento (DateLike): Data de vencimento.

    Returns:
        pl.Series: Série com as datas de pagamento entre a liquidação (exclusiva)
            e o vencimento (inclusivo). Retorna série vazia se o vencimento
            for menor ou igual à liquidação.

    Notes:
        Para obter as datas efetivas de processamento, use
        ``yd.du.deslocar(..., 0)``.

    Examples:
        >>> from pyield import ntnf
        >>> ntnf.datas_pagamento("15-05-2024", "01-01-2027")
        shape: (6,)
        Series: 'datas_pagamento' [date]
        [
            2024-07-01
            2025-01-01
            2025-07-01
            2026-01-01
            2026-07-01
            2027-01-01
        ]

        A data de liquidação coincidente com um pagamento é exclusiva:

        >>> ntnf.datas_pagamento("01-07-2024", "01-01-2027")
        shape: (5,)
        Series: 'datas_pagamento' [date]
        [
            2025-01-01
            2025-07-01
            2026-01-01
            2026-07-01
            2027-01-01
        ]
    """
    return _utils.gerar_datas_pagamento(data_liquidacao, data_vencimento)

def duration(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    taxa: float | str,
) -> float:
    r"""
    Calcula a Macaulay duration de uma NTN-F em anos úteis.

    Args:
        data_liquidacao (DateLike): Data de liquidação para o cálculo.
        data_vencimento (DateLike): Data de vencimento do título.
        taxa (float | str): TIR anual efetiva, em decimal, na base de 252 dias
            úteis, usada para descontar os fluxos.
            Aceita também percentual explícito: "5.75%" ou "5,75%".

    Returns:
        float: Macaulay duration em anos úteis. Retorna NaN se inválido.

    Notes:
        A Macaulay duration \(D\), em anos de 252 dias úteis, é:

        \[
        D = \frac{
        \sum_{i=1}^{n}t_i\,\mathrm{FC}_i/(1+y)^{t_i}}
        {\mathrm{PU}}
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(y\): TIR anual efetiva informada em `taxa`, em decimal, na
          base de 252 dias úteis.
        - \(\mathrm{PU}\): soma dos fluxos descontados pela TIR \(y\).

        Os fluxos descontados não aplicam os arredondamentos e truncamentos
        do PU oficial.

    Examples:
        >>> from pyield import ntnf
        >>> ntnf.duration("02-09-2024", "01-01-2035", "12.1785%")
        6.32854218039796
    """
    if isinstance(taxa, str):
        taxa = float(_utils.converter_taxa(taxa))
    if any_is_empty(data_liquidacao, data_vencimento, taxa):
        return float("nan")

    df_fluxos = fluxos_caixa(data_liquidacao, data_vencimento)
    if df_fluxos.is_empty():
        return float("nan")

    anos_uteis = du.contar(data_liquidacao, df_fluxos["data_pagamento"]) / 252
    vp = df_fluxos["valor_pagamento"] / (1 + taxa) ** anos_uteis
    duration = float((vp * anos_uteis).sum()) / float(vp.sum())
    return duration

def duration_expr(
    data_liquidacao: pl.Expr | str,
    data_vencimento: pl.Expr | str,
    taxa: pl.Expr | str,
) -> pl.Expr:
    """Cria expressão Polars para a duration da NTN-F.

    O cálculo é aplicado linha a linha porque a duration depende dos fluxos de
    caixa do título.

    Args:
        data_liquidacao: Nome de coluna ou expressão Polars com a data de
            liquidação.
        data_vencimento: Nome de coluna ou expressão Polars com a data de
            vencimento.
        taxa: Nome de coluna ou expressão Polars com a TIR anual efetiva,
            em decimal, na base de 252 dias úteis.

    Returns:
        pl.Expr: Expressão sem alias com a Macaulay duration em anos úteis.
    """
    return pl.struct(
        _utils.coluna_ou_expr(data_liquidacao, "data_liquidacao"),
        _utils.coluna_ou_expr(data_vencimento, "data_vencimento"),
        _utils.coluna_ou_expr(taxa, "taxa"),
    ).map_elements(
        lambda s: duration(
            s["data_liquidacao"],
            s["data_vencimento"],
            s["taxa"],
        ),
        return_dtype=pl.Float64,
    )

def dv01(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    taxa: float | Decimal | str,
) -> float:
    r"""
    Calcula o DV01 (Dollar Value of 01) de uma NTN-F em R$.

    Representa a redução do PU teórico para um aumento de 1 bp (0,01 ponto
    percentual) na taxa, calculada pela diferença entre os preços antes e depois
    do aumento.

    Args:
        data_liquidacao (DateLike): Data de liquidação.
        data_vencimento (DateLike): Data de vencimento.
        taxa (float | Decimal | str): TIR anual efetiva, em decimal, na base
            de 252 dias úteis.
            Aceita também percentual explícito: "5.75%" ou "5,75%".

    Returns:
        float: DV01, variação de preço para 1 bp.

    Notes:
        Mantendo liquidação e vencimento fixos, os fluxos e seus prazos
        também ficam fixos. Nesse contexto, o preço teórico em função da TIR é:

        \[
        \mathrm{PU}(y) = \sum_{i=1}^{n}\frac{\mathrm{FC}_i}{(1+y)^{t_i}}
        \]

        O \(\mathrm{DV01}\) é a redução do preço, em R$, para um aumento
        de 1 bp na TIR:

        \[
        \mathrm{DV01} = \mathrm{PU}(y) - \mathrm{PU}(y+0.0001)
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(y\): TIR anual efetiva informada em `taxa`, em decimal, na
          base de 252 dias úteis.
        - \(0.0001\): aumento de 1 bp na TIR em decimal.

        Os preços não aplicam os arredondamentos e truncamentos do PU oficial.

    Examples:
        >>> from pyield import ntnf
        >>> ntnf.dv01("26-03-2025", "01-01-2035", "15.1375%")
        0.39025157587195736
    """
    taxa = _utils.converter_taxa(taxa)
    if any_is_empty(data_liquidacao, data_vencimento, taxa):
        return float("nan")

    pu1 = _valor_presente(data_liquidacao, data_vencimento, taxa)
    pu2 = _valor_presente(data_liquidacao, data_vencimento, float(taxa) + 0.0001)
    return pu1 - pu2

def dv01_expr(
    data_liquidacao: pl.Expr | str,
    data_vencimento: pl.Expr | str,
    taxa: pl.Expr | str,
) -> pl.Expr:
    """Cria expressão Polars para o DV01 da NTN-F.

    O cálculo é aplicado linha a linha e reprifica o PU teórico para um
    aumento de 1 bp na taxa.

    Args:
        data_liquidacao: Nome de coluna ou expressão Polars com a data de
            liquidação.
        data_vencimento: Nome de coluna ou expressão Polars com a data de
            vencimento.
        taxa: Nome de coluna ou expressão Polars com a TIR anual efetiva,
            em decimal, na base de 252 dias úteis.

    Returns:
        pl.Expr: Expressão sem alias com o DV01.
    """
    return pl.struct(
        _utils.coluna_ou_expr(data_liquidacao, "data_liquidacao"),
        _utils.coluna_ou_expr(data_vencimento, "data_vencimento"),
        _utils.coluna_ou_expr(taxa, "taxa"),
    ).map_elements(
        lambda s: dv01(
            s["data_liquidacao"],
            s["data_vencimento"],
            s["taxa"],
        ),
        return_dtype=pl.Float64,
    )

def fluxos_caixa(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
) -> pl.DataFrame:
    """
    Gera os fluxos de caixa da NTN-F entre liquidação (exclusiva) e vencimento
    (inclusivo). Os fluxos incluem cupons e o pagamento final no vencimento.

    Args:
        data_liquidacao (DateLike): Data de liquidação (exclusiva).
        data_vencimento (DateLike): Data de vencimento do título.

    Returns:
        pl.DataFrame: DataFrame com as colunas `data_pagamento` e
            `valor_pagamento`.

    Output Columns:
        - data_pagamento (Date): Data contratual do pagamento, sem ajuste para
            dia útil.
        - valor_pagamento (Float64): Valor do pagamento.

    Notes:
        Para obter as datas efetivas de processamento, use
        ``yd.du.deslocar(..., 0)``.

    Examples:
        >>> from pyield import ntnf
        >>> ntnf.fluxos_caixa("15-05-2024", "01-01-2027")
        shape: (6, 2)
        ┌────────────────┬─────────────────┐
        │ data_pagamento ┆ valor_pagamento │
        │ ---            ┆ ---             │
        │ date           ┆ f64             │
        ╞════════════════╪═════════════════╡
        │ 2024-07-01     ┆ 48.80885        │
        │ 2025-01-01     ┆ 48.80885        │
        │ 2025-07-01     ┆ 48.80885        │
        │ 2026-01-01     ┆ 48.80885        │
        │ 2026-07-01     ┆ 48.80885        │
        │ 2027-01-01     ┆ 1048.80885      │
        └────────────────┴─────────────────┘
    """
    if any_is_empty(data_liquidacao, data_vencimento):
        return pl.DataFrame()
    # Normaliza datas de entrada
    liquidacao = cv.converter_datas(data_liquidacao)
    vencimento = cv.converter_datas(data_vencimento)

    # Obtém as datas de pagamento entre liquidação e vencimento
    serie_datas_pagamento = datas_pagamento(liquidacao, vencimento)

    # Retorna DataFrame vazio se não houver pagamentos (liquidação >= vencimento)
    if serie_datas_pagamento.is_empty():
        return pl.DataFrame(
            schema={"data_pagamento": pl.Date, "valor_pagamento": pl.Float64}
        )

    # Define o fluxo final no vencimento e os demais como cupom
    df = pl.DataFrame(
        data={"data_pagamento": serie_datas_pagamento},
    ).with_columns(
        pl.when(pl.col("data_pagamento") == vencimento)
        .then(VALOR_FINAL)
        .otherwise(VALOR_CUPOM)
        .alias("valor_pagamento")
    )

    return df

def premio_limpo(  # noqa
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    taxa_ntnf: float | str,
    vencimentos_di: DatesLike,
    taxas_di: ArrayLike,
) -> float:
    r"""
    Calcula o spread líquido (prêmio limpo no jargão de mercado) da NTN-F sobre a curva DI.

    A função determina o spread que iguala o valor presente dos fluxos ao preço
    do título. Interpola as taxas DI nas datas de pagamento e encontra o spread
    que zera a diferença de preços, retornado em decimal e conversível para bps.

    Args:
        data_liquidacao (DateLike): Data de liquidação para o cálculo.
        data_vencimento (DateLike): Data de vencimento do título.
        taxa_ntnf (float | str): TIR anual efetiva, em decimal, na base de
            252 dias úteis.
            Aceita também percentual explícito: "5.75%" ou "5,75%".
        vencimentos_di (DatesLike): Vencimentos da curva DI.
        taxas_di (ArrayLike): Taxas DI anuais efetivas, em decimal, na base
            de 252 dias úteis, correspondentes aos vencimentos.

    Returns:
        float: Spread líquido em formato decimal (ex.: 0.0012 = 12 bps).
            Retorna NaN para entradas ausentes ou fluxos vazios.
            Também retorna NaN se a resolução numérica falhar.

    Notes:
        O spread \(s\), adicionado a cada taxa DI anual em decimal,
        é a solução de:

        \[
        \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+\mathrm{DI}_i+s)^{t_i}}
        = \mathrm{PU} = \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+y)^{t_i}}
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(y\): TIR anual efetiva informada em `taxa_ntnf`, em decimal,
          na base de 252 dias úteis.
        - \(\mathrm{DI}_i := \mathrm{DI}(t_i)\): taxa DI anual efetiva,
          em decimal, para o prazo do pagamento \(i\), obtida por
          interpolação `flat_forward`, na base de 252 dias úteis.

        Para expressar o spread em pontos-base, multiplique por 10.000. Os preços
        são teóricos, sem os arredondamentos e truncamentos do PU oficial.

    Examples:
        # Obs: apenas algumas taxas DI serão usadas no exemplo.
        >>> exp_dates = ["2025-01-01", "2030-01-01", "2035-01-01"]
        >>> taxas_di = [0.10823, 0.11594, 0.11531]
        >>> spread = premio_limpo(
        ...     data_liquidacao="23-08-2024",
        ...     data_vencimento="01-01-2035",
        ...     taxa_ntnf=0.116586,
        ...     vencimentos_di=exp_dates,
        ...     taxas_di=taxas_di,
        ... )
        >>> round(spread * 10_000, 2)  # Converte para bps para exibição
        12.13
    """
    if isinstance(taxa_ntnf, str):
        taxa_ntnf = float(_utils.converter_taxa(taxa_ntnf))
    if any_is_empty(
        data_liquidacao,
        data_vencimento,
        taxa_ntnf,
        vencimentos_di,
        taxas_di,
    ):
        return float("nan")

    if not isinstance(taxas_di, pl.Series):
        serie_taxas_di = pl.Series(taxas_di)
    else:
        serie_taxas_di = taxas_di

    interpolador_ff = ip.Interpolador(
        du.contar(data_liquidacao, vencimentos_di),
        serie_taxas_di,
        "flat_forward",
    )

    df = fluxos_caixa(data_liquidacao, data_vencimento)
    if df.is_empty():
        return float("nan")

    df = df.with_columns(
        dias_uteis_pagamento=du.contar(data_liquidacao, df["data_pagamento"]),
    ).with_columns(
        taxa_di_interpolada=interpolador_ff.interpolar_expr("dias_uteis_pagamento"),
    )

    anos_uteis_pagamento = df["dias_uteis_pagamento"] / 252
    preco_titulo = _valor_presente(data_liquidacao, data_vencimento, taxa_ntnf)
    fluxos_titulo = df["valor_pagamento"]
    di_interpolada = df["taxa_di_interpolada"]

    def diferenca_preco(spread: float) -> float:
        fluxos_descontados = (
            fluxos_titulo / (1 + di_interpolada + spread) ** anos_uteis_pagamento
        )
        return float(fluxos_descontados.sum()) - preco_titulo

    return _utils.encontrar_raiz(diferenca_preco)

def premio_limpo_expr(
    data_liquidacao: DateLike,
    data_vencimento: pl.Expr | str,
    taxa_ntnf: pl.Expr | str,
    vencimentos_di: DatesLike,
    taxas_di: ArrayLike,
) -> pl.Expr:
    """Cria expressão Polars para o prêmio limpo da NTN-F sobre a curva DI.

    O cálculo é aplicado linha a linha porque o prêmio limpo depende dos fluxos
    de caixa do título, da interpolação da curva DI e da resolução de raiz.
    Falhas de resolução retornam NaN apenas na linha afetada. Outros erros
    são propagados.

    Args:
        data_liquidacao: Data de liquidação para o cálculo.
        data_vencimento: Nome de coluna ou expressão Polars com a data de
            vencimento da NTN-F.
        taxa_ntnf: Nome de coluna ou expressão Polars com a TIR anual efetiva
            da NTN-F, em decimal, na base de 252 dias úteis.
        vencimentos_di: Datas de vencimento da curva DI.
        taxas_di: Taxas DI anuais efetivas, em decimal, na base de 252 dias
            úteis, correspondentes aos vencimentos.

    Returns:
        pl.Expr: Expressão sem alias com o prêmio limpo da NTN-F sobre a curva
        DI.
    """
    return pl.struct(
        _utils.coluna_ou_expr(data_vencimento, "data_vencimento"),
        _utils.coluna_ou_expr(taxa_ntnf, "taxa_ntnf"),
    ).map_elements(
        lambda row: premio_limpo(
            data_liquidacao=data_liquidacao,
            data_vencimento=row["data_vencimento"],
            taxa_ntnf=row["taxa_ntnf"],
            vencimentos_di=vencimentos_di,
            taxas_di=taxas_di,
        ),
        return_dtype=pl.Float64,
    )

def pu(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    taxa: float | Decimal | str,
) -> Decimal:
    r"""
    Calcula o PU da NTN-F pela metodologia da STN para leilões primários.

    O preço equivale ao valor presente dos fluxos descontados pela TIR
    informada.

    Args:
        data_liquidacao (DateLike): Data de liquidação para cálculo do preço.
        data_vencimento (DateLike): Data de vencimento do título.
        taxa: TIR anual efetiva, em decimal, na base de 252 dias úteis.
            Aceita também percentual explícito: "5.75%" ou "5,75%".
            Antes do cálculo, é truncada em oito casas decimais (seis na
            forma percentual), descartando as casas excedentes sem arredondar.

    Returns:
        Decimal: Preço da NTN-F truncado em seis casas decimais.

    Notes:
        O PU teórico é:

        \[
        \mathrm{PU} = \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+y)^{t_i}}
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(y\): TIR anual efetiva informada em `taxa`, em decimal, na
          base de 252 dias úteis.

        Os fluxos e os prazos são determinados pela liquidação e pelo vencimento.
        No cálculo oficial, além do truncamento da TIR descrito em `Args`,
        cada prazo \(t_i\) é truncado em 14 casas decimais, cada fluxo
        descontado é arredondado em nove casas e a soma é truncada em seis.

    References:
        - Secretaria do Tesouro Nacional. Metodologia de Cálculo dos Títulos
          Públicos Federais Ofertados nos Leilões Primários.
          https://crdcj.github.io/PYield/referencias/metodologia-calculo-tpf-stn/
        - O cupom semestral é 48,81, que representa 10% a.a. com capitalização
          semestral e arredondamento para 5 casas, conforme a STN.

    Examples:
        >>> from pyield import ntnf
        >>> ntnf.pu("05-07-2024", "01-01-2035", "11.921%")
        Decimal('895.359254')
        >>> ntnf.pu("01-07-2024", "01-01-2027", "10%")
        Decimal('999.931303')
    """
    return truncar_decimal(_calcular_pu(data_liquidacao, data_vencimento, taxa), 6)

def rentabilidade(  # noqa
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    taxa_ntnf: float | str,
    vencimentos_di: DatesLike,
    taxas_di: ArrayLike,
) -> float:
    r"""
    Calcula a rentabilidade de uma NTN-F sobre a curva DI.

    Compara as taxas diárias equivalentes da TIR da NTN-F e da TIR de referência
    obtida pela curva DI, conforme o Anexo 2 de *Dívida Pública: a experiência
    brasileira*, do Tesouro Nacional. Interpola as taxas DI nas datas de pagamento,
    calcula o valor presente dos fluxos contratuais usando essas taxas e encontra
    a TIR única que reproduz esse preço de referência.

    Args:
        data_liquidacao (DateLike): Data de liquidação para o cálculo.
        data_vencimento (DateLike): Data de vencimento da NTN-F.
        taxa_ntnf (float | str): TIR anual efetiva da NTN-F, em formato decimal.
            Aceita também percentual explícito: "5.75%" ou "5,75%".
        vencimentos_di (DatesLike): Datas de vencimento da curva DI.
        taxas_di (ArrayLike): Taxas DI anuais efetivas, em formato decimal,
            correspondentes aos vencimentos.

    Returns:
        float: Razão entre as taxas diárias equivalentes. Por exemplo, 1.01
            representa 101% da taxa diária equivalente de referência DI.
            Retorna NaN para entradas ausentes, fluxos vazios ou preço calculado
            NaN. Também retorna NaN se a resolução numérica falhar.

    Examples:
        >>> # Obs: apenas algumas taxas DI serão usadas no exemplo.
        >>> exp_dates = ["2025-01-01", "2030-01-01", "2035-01-01"]
        >>> taxas_di = [0.10823, 0.11594, 0.11531]
        >>> rentabilidade(
        ...     data_liquidacao="23-08-2024",
        ...     data_vencimento="01-01-2035",
        ...     taxa_ntnf="11.6586%",
        ...     vencimentos_di=exp_dates,
        ...     taxas_di=taxas_di,
        ... )
        1.0099602280683393

    Notes:
        **Preço de referência pela curva DI**

        O preço de referência é:

        \[
        P_{\mathrm{DI}} = \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+\mathrm{DI}_i)^{t_i}}
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(\mathrm{DI}(t)\): taxa DI para o prazo \(t\), anual efetiva e
          em decimal, na base de 252 dias úteis.
        - \(\mathrm{DI}_i := \mathrm{DI}(t_i)\): taxa DI para o prazo do
          pagamento \(i\), obtida por interpolação `flat_forward`.

        **TIR equivalente da referência**

        A função resolve numericamente a TIR anual efetiva
        \(y_{\mathrm{DI}}\), em decimal, que desconta os mesmos fluxos ao
        preço de referência:

        \[
        \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+y_{\mathrm{DI}})^{t_i}}
        = P_{\mathrm{DI}}
        \]

        Essa TIR é uma taxa única para todos os pagamentos, enquanto cada
        \(\mathrm{DI}_i\) corresponde
        ao prazo do pagamento \(i\).

        **Rentabilidade relativa**

        A rentabilidade relativa \(q\) é a razão entre as taxas diárias
        equivalentes:

        \[
        q = \frac{(1+y_{\mathrm{NTNF}})^{1/252}-1}
        {(1+y_{\mathrm{DI}})^{1/252}-1}
        \]

        onde \(y_{\mathrm{NTNF}}\) é a TIR informada em `taxa_ntnf`.

        O indicador compara taxas implícitas; não representa o retorno realizado
        entre compra e venda. Também não calibra um spread ou um multiplicador
        uniforme sobre os vértices da curva DI.

        Os fluxos mantêm as datas contratuais, excluem pagamentos na liquidação
        e incluem o vencimento. O preço de referência não aplica os arredondamentos
        e truncamentos do PU oficial. Não há extrapolação na ponta longa da curva;
        pagamentos além do último vértice DI resultam em NaN.

        ??? note "Comparação com a LTN"

            A LTN possui um único pagamento. Nesse caso, a TIR equivalente da
            referência coincide com a taxa zero DI do vencimento, e a fórmula
            se reduz à utilizada por `yd.ltn.rentabilidade`. Na NTN-F, a TIR
            equivalente considera também os cupons intermediários.

        Referência: Tesouro Nacional, *Dívida Pública: a experiência brasileira*,
        Parte 3, capítulo 2, Anexo 2, item 2, páginas 329–330:
        [Prêmio das NTN-Fs](https://thot-arquivos.tesouro.gov.br/publicacao-anexo/4710).
    """
    if isinstance(taxa_ntnf, str):
        taxa_ntnf = float(_utils.converter_taxa(taxa_ntnf))
    if any_is_empty(
        data_liquidacao,
        data_vencimento,
        taxa_ntnf,
        vencimentos_di,
        taxas_di,
    ):
        return float("nan")

    if not isinstance(taxas_di, pl.Series):
        serie_taxas_di = pl.Series(taxas_di)
    else:
        serie_taxas_di = taxas_di

    df_fluxos = fluxos_caixa(data_liquidacao, data_vencimento)
    if df_fluxos.is_empty():
        return float("nan")

    interpolador_ff = ip.Interpolador(
        du.contar(data_liquidacao, vencimentos_di),
        serie_taxas_di,
        "flat_forward",
    )

    df = df_fluxos.with_columns(
        dias_uteis=du.contar(data_liquidacao, df_fluxos["data_pagamento"]),
    ).with_columns(
        anos_uteis=pl.col("dias_uteis") / 252,
        taxa_di=interpolador_ff.interpolar_expr("dias_uteis"),
    )

    preco_referencia = _utils.calcular_pv(
        fluxos_caixa=df["valor_pagamento"],
        taxas=df["taxa_di"],
        prazos=df["anos_uteis"],
    )

    if math.isnan(preco_referencia):
        return float("nan")

    def diferenca_preco(taxa: float) -> float:
        fluxos_descontados = df["valor_pagamento"] / (1 + taxa) ** df["anos_uteis"]
        return float(fluxos_descontados.sum()) - preco_referencia

    tir_di = _utils.encontrar_raiz(diferenca_preco)

    fator_ntnf = (1 + taxa_ntnf) ** (1 / 252)
    fator_di = (1 + tir_di) ** (1 / 252)
    if fator_di == 1:
        return float("inf") if fator_ntnf > 1 else 0.0

    rentabilidade = (fator_ntnf - 1) / (fator_di - 1)
    return rentabilidade

def rentabilidade_expr(
    data_liquidacao: DateLike,
    data_vencimento: pl.Expr | str,
    taxa_ntnf: pl.Expr | str,
    vencimentos_di: DatesLike,
    taxas_di: ArrayLike,
) -> pl.Expr:
    """Cria expressão Polars para a rentabilidade da NTN-F sobre a curva DI.

    O cálculo é aplicado linha a linha porque a rentabilidade depende dos fluxos
    de caixa do título, da interpolação da curva DI e da resolução de raiz.
    Falhas de resolução retornam NaN apenas na linha afetada. Outros erros
    são propagados.

    Args:
        data_liquidacao: Data de liquidação para o cálculo.
        data_vencimento: Nome de coluna ou expressão Polars com a data de
            vencimento da NTN-F.
        taxa_ntnf: Nome de coluna ou expressão Polars com a TIR anual efetiva
            da NTN-F, em decimal, na base de 252 dias úteis.
        vencimentos_di: Datas de vencimento da curva DI.
        taxas_di: Taxas DI anuais efetivas, em decimal, na base de 252 dias
            úteis, correspondentes aos vencimentos.

    Returns:
        pl.Expr: Expressão sem alias com a rentabilidade da NTN-F sobre a curva
        DI.
    """
    return pl.struct(
        _utils.coluna_ou_expr(data_vencimento, "data_vencimento"),
        _utils.coluna_ou_expr(taxa_ntnf, "taxa_ntnf"),
    ).map_elements(
        lambda row: rentabilidade(
            data_liquidacao=data_liquidacao,
            data_vencimento=row["data_vencimento"],
            taxa_ntnf=row["taxa_ntnf"],
            vencimentos_di=vencimentos_di,
            taxas_di=taxas_di,
        ),
        return_dtype=pl.Float64,
    )

def taxa(
    data_liquidacao: DateLike,
    data_vencimento: DateLike,
    pu: float | Decimal,
) -> float:
    r"""
    Calcula a TIR implícita de uma NTN-F a partir de um PU informado.

    A função resolve numericamente a taxa que aproxima o PU informado pelo
    valor presente bruto dos fluxos. Como o valor presente não é arredondado
    nem truncado, o resultado não pretende reproduzir exatamente a taxa usada
    para gerar um PU canônico por ``pu()``.

    Args:
        data_liquidacao (DateLike): Data de liquidação.
        data_vencimento (DateLike): Data de vencimento.
        pu: Preço unitário (PU) do título.

    Returns:
        float: TIR implícita em formato decimal, sem arredondamento. Retorna
            NaN para entradas ausentes, PU não positivo ou falha na resolução
            numérica.

    Notes:
        A TIR implícita \(y\), anual efetiva, em decimal e na base de
        252 dias úteis, é a solução de:

        \[
        \sum_{i=1}^{n}
        \frac{\mathrm{FC}_i}{(1+y)^{t_i}}
        = \mathrm{PU}_{\mathrm{informado}}
        \]

        onde:

        - \(\mathrm{FC}_i\): valor do pagamento \(i\), incluindo cupom e
          amortização quando aplicável.
        - \(\mathrm{DU}_i\): dias úteis entre liquidação e pagamento \(i\).
        - \(t_i = \mathrm{DU}_i/252\): prazo até o pagamento \(i\), em anos
          de 252 dias úteis.
        - \(n\): número de pagamentos restantes.
        - \(\mathrm{PU}_{\mathrm{informado}}\): preço recebido em `pu`.

        A soma representa o preço teórico, sem os arredondamentos e truncamentos
        do PU oficial.

    Examples:
        Exibe as taxas em formato decimal:

        >>> from pyield import ntnf
        >>> ntnf.taxa("13-03-2026", "01-01-2035", 820.995125)
        0.1427430001649857
        >>> ntnf.taxa("21-05-2008", "01-01-2014", 903.039091) * 100
        13.661101023197176
    """
    if any_is_empty(data_liquidacao, data_vencimento, pu):
        return float("nan")

    pu_float = float(pu)
    if pu_float <= 0:
        return float("nan")

    def diferenca_preco(taxa_encontrada: float) -> float:
        return (
            _valor_presente(data_liquidacao, data_vencimento, taxa_encontrada)
            - pu_float
        )

    return _utils.encontrar_raiz(diferenca_preco)