finrb 1.2.0 → 1.3.0

data/lib/finrb/calendars/base.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Finrb
+  module Calendars
+    # A dated market calendar with explicit business-day adjustment rules.
+    class Base
+      CONVENTIONS = %i[following modified_following preceding modified_preceding half_month_modified_following nearest unadjusted].freeze
+      public_constant :CONVENTIONS
+
+      attr_reader :additional_holidays, :removed_holidays
+
+      def initialize(additional_holidays: [], removed_holidays: [])
+        @additional_holidays = validate_dates(additional_holidays, 'additional_holidays')
+        @removed_holidays = validate_dates(removed_holidays, 'removed_holidays')
+        freeze
+      end
+
+      def business_day?(date)
+        date = normalize_date(date)
+        !weekend?(date) && holiday_names(date).empty?
+      end
+
+      def holiday?(date)
+        !business_day?(date)
+      end
+
+      def holiday_names(date)
+        date = normalize_date(date)
+        names = @removed_holidays.include?(date) ? [] : holidays_for(date)
+        names += ['Additional market holiday'] if @additional_holidays.include?(date)
+        names.uniq.freeze
+      end
+
+      def holidays_between(start_date, end_date, include_weekends: false)
+        start_date = normalize_date(start_date)
+        end_date = normalize_date(end_date)
+        raise(ArgumentError, 'start_date must not be after end_date.') if start_date > end_date
+        raise(ArgumentError, 'include_weekends must be true or false.') unless [true, false].include?(include_weekends)
+
+        holidays =
+          (start_date..end_date).each_with_object({}) do |date, result|
+            names = holiday_names(date)
+            names = ['Weekend'].freeze if include_weekends && weekend?(date) && names.empty?
+            result[date] = names unless names.empty?
+          end
+        holidays.freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && additional_holidays == other.additional_holidays && removed_holidays == other.removed_holidays
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, additional_holidays, removed_holidays].hash
+      end
+
+      def adjust(date, convention:)
+        date = normalize_date(date)
+        raise(ArgumentError, "business-day convention must be one of #{CONVENTIONS.join(', ')}.") unless CONVENTIONS.include?(convention)
+
+        return date if convention == :unadjusted || business_day?(date)
+
+        case convention
+        when :following
+          seek_business_day(date, 1)
+        when :modified_following
+          following = seek_business_day(date, 1)
+          following.month == date.month ? following : seek_business_day(date, -1)
+        when :preceding
+          seek_business_day(date, -1)
+        when :modified_preceding
+          preceding = seek_business_day(date, -1)
+          preceding.month == date.month ? preceding : seek_business_day(date, 1)
+        when :half_month_modified_following
+          following = seek_business_day(date, 1)
+          crosses_month = following.month != date.month
+          crosses_midmonth = date.day <= 15 && following.day > 15
+          crosses_month || crosses_midmonth ? seek_business_day(date, -1) : following
+        when :nearest
+          nearest_business_day(date)
+        else
+          raise(ArgumentError, "unsupported business-day convention: #{convention}.")
+        end
+      end
+
+      def advance(date, business_days:, convention: :following)
+        date = normalize_date(date)
+        raise(ArgumentError, 'business_days must be an integer.') unless business_days.is_a?(Integer)
+        raise(ArgumentError, "business-day convention must be one of #{CONVENTIONS.join(', ')}.") unless CONVENTIONS.include?(convention)
+        return adjust(date, convention:) if business_days.zero?
+
+        direction = business_days.positive? ? 1 : -1
+        remaining = business_days.abs
+        advanced = date
+        while remaining.positive?
+          advanced += direction
+          remaining -= 1 if business_day?(advanced)
+        end
+        advanced
+      end
+
+      protected
+
+      def weekend?(_date)
+        raise(NotImplementedError, 'calendar subclasses must define their weekend days.')
+      end
+
+      def holidays_for(_date)
+        raise(NotImplementedError, 'calendar subclasses must define their market holidays.')
+      end
+
+      private
+
+      def normalize_date(date)
+        raise(ArgumentError, 'date must be a Date.') unless date.is_a?(Date)
+
+        normalized_date = Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+        supported_dates = self.class::SUPPORTED_DATE_RANGE
+        return normalized_date if supported_dates.cover?(normalized_date)
+
+        raise(RangeError, "#{name} supports dates from #{supported_dates.begin} through #{supported_dates.end}.")
+      end
+
+      def validate_dates(dates, name)
+        raise(ArgumentError, "#{name} must be an array of Dates.") unless dates.is_a?(Array) && dates.all?(Date)
+
+        normalized_dates = []
+        dates.each do |date|
+          normalized_date = normalize_date(date)
+          normalized_dates << normalized_date unless normalized_dates.include?(normalized_date)
+        end
+        normalized_dates.freeze
+      end
+
+      def seek_business_day(date, direction)
+        candidate = date
+        370.times do
+          candidate += direction
+          return candidate if business_day?(candidate)
+        end
+        raise(ArgumentError, 'no business day found within one year of the requested date.')
+      end
+
+      def nearest_business_day(date)
+        distance = 1
+        loop do
+          preceding = date - distance
+          following = date + distance
+          return following if business_day?(following)
+          return preceding if business_day?(preceding)
+
+          distance += 1
+          raise(ArgumentError, 'no business day found within one year of the requested date.') if distance > 370
+        end
+      end
+    end
+  end
+end

data/lib/finrb/calendars/hebrew_calendar.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Finrb
+  module Calendars
+    # Arithmetic Hebrew calendar dates used for the TASE holiday rules.
+    module HebrewCalendar
+      ANCHOR_HEBREW_YEAR = 5785
+      ANCHOR_ROSH_HASHANAH = Date.new(2024, 10, 3, Date::GREGORIAN)
+      private_constant :ANCHOR_HEBREW_YEAR, :ANCHOR_ROSH_HASHANAH
+
+      module_function
+
+      def leap_year?(year)
+        ((year * 7) + 1) % 19 < 7
+      end
+
+      def date(year, month, day)
+        months = months_in_year(year)
+        raise(ArgumentError, 'invalid Hebrew month.') unless months.include?(month)
+
+        month_length = days_in_month(year, month)
+        raise(ArgumentError, 'invalid Hebrew day.') unless day.between?(1, month_length)
+
+        offset = 0
+        months.each do |candidate_month|
+          break if candidate_month == month
+
+          offset += days_in_month(year, candidate_month)
+        end
+        Date.jd(rosh_hashanah_jd(year) + offset + day - 1, Date::GREGORIAN)
+      end
+
+      def rosh_hashanah_jd(year)
+        ANCHOR_ROSH_HASHANAH.jd + elapsed_days(year) - elapsed_days(ANCHOR_HEBREW_YEAR)
+      end
+
+      def months_in_year(year)
+        after_tishri = (7..(leap_year?(year) ? 13 : 12)).to_a
+        after_tishri + (1..6).to_a
+      end
+
+      def days_in_month(year, month)
+        year_length = elapsed_days(year + 1) - elapsed_days(year)
+        case month
+        when 1, 3, 5, 7, 11
+          30
+        when 2, 4, 6, 10, 13
+          29
+        when 8
+          year_length % 10 == 5 ? 30 : 29
+        when 9
+          year_length % 10 == 3 ? 29 : 30
+        when 12
+          leap_year?(year) ? 30 : 29
+        else
+          raise(ArgumentError, 'invalid Hebrew month.')
+        end
+      end
+
+      def elapsed_days(year)
+        elapsed_months = ((year * 235) - 234) / 19
+        parts_elapsed = ((elapsed_months % 1080) * 793) + 204
+        hours_elapsed = (elapsed_months * 12) + 5 + ((elapsed_months / 1080) * 793) + (parts_elapsed / 1080)
+        day = (elapsed_months * 29) + 1 + (hours_elapsed / 24)
+        parts = ((hours_elapsed % 24) * 1080) + (parts_elapsed % 1080)
+
+        molad_postponement = parts >= 19_440 || ((day % 7) == 2 && parts >= 9_924 && !leap_year?(year)) || ((day % 7) == 1 && parts >= 16_789 && leap_year?(year - 1))
+        day += 1 if molad_postponement
+        day += 1 if [0, 3, 5].include?(day % 7)
+        day
+      end
+      private_class_method :elapsed_days, :days_in_month, :months_in_year, :rosh_hashanah_jd
+    end
+  end
+end

data/lib/finrb/calendars/israel_tase.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'hebrew_calendar'
+
+module Finrb
+  module Calendars
+    # Tel Aviv Stock Exchange full-day trading calendar.
+    class IsraelTase < Base
+      # Contract window: QuantLib 1.43 supplies TASE holiday data through 2050.
+      # Earlier dates and later projections are not validated by this profile.
+      SUPPORTED_START_DATE = Date.new(2000, 1, 1, Date::GREGORIAN)
+      SUPPORTED_END_DATE = Date.new(2050, 12, 31, Date::GREGORIAN)
+      SUPPORTED_DATE_RANGE = (SUPPORTED_START_DATE..SUPPORTED_END_DATE)
+      public_constant :SUPPORTED_START_DATE, :SUPPORTED_END_DATE, :SUPPORTED_DATE_RANGE
+
+      TRADING_WEEK_CHANGE = Date.new(2026, 1, 5, Date::GREGORIAN)
+      WEEKEND_BEFORE_CHANGE = [5, 6].freeze
+      WEEKEND_AFTER_CHANGE = [0, 6].freeze
+      public_constant :TRADING_WEEK_CHANGE
+      private_constant :WEEKEND_BEFORE_CHANGE, :WEEKEND_AFTER_CHANGE
+
+      def name
+        'Israel TASE'
+      end
+
+      protected
+
+      def weekend?(date)
+        weekend_days = date < TRADING_WEEK_CHANGE ? WEEKEND_BEFORE_CHANGE : WEEKEND_AFTER_CHANGE
+        weekend_days.include?(date.wday)
+      end
+
+      def holidays_for(date)
+        names = {}
+        ((date.year + 3759)..(date.year + 3761)).each do |hebrew_year|
+          hebrew_holidays(hebrew_year).each do |holiday_date, name|
+            (names[holiday_date] ||= []).concat(name)
+          end
+        end
+        add(names, Date.new(2026, 1, 4, Date::GREGORIAN), 'TASE trading-week transition')
+        names.fetch(date, [])
+      end
+
+      private
+
+      def hebrew_holidays(year)
+        holidays = {}
+        add(holidays, HebrewCalendar.date(year - 1, 6, 29), 'Rosh Hashanah Eve')
+        add(holidays, HebrewCalendar.date(year, 7, 1), 'Rosh Hashanah I')
+        add(holidays, HebrewCalendar.date(year, 7, 2), 'Rosh Hashanah II')
+        add(holidays, HebrewCalendar.date(year, 7, 9), 'Yom Kippur Eve')
+        add(holidays, HebrewCalendar.date(year, 7, 10), 'Yom Kippur')
+        add(holidays, HebrewCalendar.date(year, 7, 14), 'Sukkot Eve')
+        add(holidays, HebrewCalendar.date(year, 7, 15), 'Sukkot')
+        add(holidays, HebrewCalendar.date(year, 7, 21), 'Shemini Atzeret Eve')
+        add(holidays, HebrewCalendar.date(year, 7, 22), 'Shemini Atzeret / Simchat Torah')
+
+        adar = HebrewCalendar.leap_year?(year) ? 13 : 12
+        add(holidays, HebrewCalendar.date(year, adar, 14), 'Purim')
+
+        add(holidays, HebrewCalendar.date(year, 1, 14), 'Passover Eve I')
+        add(holidays, HebrewCalendar.date(year, 1, 15), 'Passover I')
+        add(holidays, HebrewCalendar.date(year, 1, 20), 'Passover Eve VII')
+        add(holidays, HebrewCalendar.date(year, 1, 21), 'Passover VII')
+        add(holidays, israel_independence_day(year) - 1, 'Memorial Day')
+        add(holidays, israel_independence_day(year), 'Independence Day')
+        add(holidays, HebrewCalendar.date(year, 3, 5), 'Shavuot Eve')
+        add(holidays, HebrewCalendar.date(year, 3, 6), 'Shavuot')
+        add(holidays, tisha_bav(year), 'Tisha B’Av')
+        holidays
+      end
+
+      def israel_independence_day(year)
+        date = HebrewCalendar.date(year, 2, 5)
+        day =
+          case date.wday
+          when 6 then 3
+          when 5 then 4
+          when 1 then 6
+          else 5
+          end
+        HebrewCalendar.date(year, 2, day)
+      end
+
+      def tisha_bav(year)
+        date = HebrewCalendar.date(year, 5, 9)
+        date.saturday? ? date + 1 : date
+      end
+
+      def add(holidays, date, name)
+        (holidays[date] ||= []) << name
+      end
+    end
+  end
+end

data/lib/finrb/calendars/us_federal_reserve.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Finrb
+  module Calendars
+    # Federal Reserve Bank payment-business calendar (not NYSE or federal staff leave).
+    class USFederalReserve < Base
+      # Contract window: QuantLib 1.43 was exhaustively checked over these years;
+      # pre-1950 history is intentionally outside this profile and later dates
+      # are rejected rather than silently extrapolated.
+      SUPPORTED_START_DATE = Date.new(1950, 1, 1, Date::GREGORIAN)
+      SUPPORTED_END_DATE = Date.new(2065, 12, 31, Date::GREGORIAN)
+      SUPPORTED_DATE_RANGE = (SUPPORTED_START_DATE..SUPPORTED_END_DATE)
+      public_constant :SUPPORTED_START_DATE, :SUPPORTED_END_DATE, :SUPPORTED_DATE_RANGE
+
+      WEEKEND_DAYS = [0, 6].freeze
+      private_constant :WEEKEND_DAYS
+
+      def name
+        'US Federal Reserve'
+      end
+
+      protected
+
+      def weekend?(date)
+        WEEKEND_DAYS.include?(date.wday)
+      end
+
+      def holidays_for(date)
+        year = date.year
+        holidays = {}
+        add_fixed_holiday(holidays, year, 1, 1, "New Year's Day")
+        add_weekday_holiday(holidays, nth_weekday(year, 1, 1, 3), 'Birthday of Martin Luther King, Jr.') if year >= 1983
+        if year < 1971
+          add_pre_1971_fixed_holiday(holidays, Date.new(year, 2, 22, Date::GREGORIAN), "Washington's Birthday")
+          add_pre_1971_fixed_holiday(holidays, Date.new(year, 5, 30, Date::GREGORIAN), 'Memorial Day')
+        else
+          add_weekday_holiday(holidays, nth_weekday(year, 2, 1, 3), "Washington's Birthday")
+          add_weekday_holiday(holidays, last_weekday(year, 5, 1), 'Memorial Day')
+        end
+        add_fixed_holiday(holidays, year, 6, 19, 'Juneteenth National Independence Day') if year >= 2021
+        add_fixed_holiday(holidays, year, 7, 4, 'Independence Day')
+        add_weekday_holiday(holidays, nth_weekday(year, 9, 1, 1), 'Labor Day')
+        add_weekday_holiday(holidays, nth_weekday(year, 10, 1, 2), 'Columbus Day') if year >= 1971
+        add_fixed_holiday(holidays, year, 11, 11, 'Veterans Day') unless year.between?(1971, 1977)
+        add_weekday_holiday(holidays, nth_weekday(year, 10, 1, 4), 'Veterans Day') if year.between?(1971, 1977)
+        add_weekday_holiday(holidays, nth_weekday(year, 11, 4, 4), 'Thanksgiving Day')
+        add_fixed_holiday(holidays, year, 12, 25, 'Christmas Day')
+        holidays.fetch(date, [])
+      end
+
+      private
+
+      def add_fixed_holiday(holidays, year, month, day, name)
+        date = Date.new(year, month, day, Date::GREGORIAN)
+        add_weekday_holiday(holidays, date, name)
+        add_weekday_holiday(holidays, date + 1, name) if date.sunday?
+      end
+
+      def add_pre_1971_fixed_holiday(holidays, date, name)
+        add_weekday_holiday(holidays, date, name)
+        add_weekday_holiday(holidays, date - 1, name) if date.saturday?
+        add_weekday_holiday(holidays, date + 1, name) if date.sunday?
+      end
+
+      def add_weekday_holiday(holidays, date, name)
+        (holidays[date] ||= []) << name
+      end
+
+      def nth_weekday(year, month, weekday, occurrence)
+        first = Date.new(year, month, 1, Date::GREGORIAN)
+        first + ((weekday - first.wday) % 7) + ((occurrence - 1) * 7)
+      end
+
+      def last_weekday(year, month, weekday)
+        last = Date.new(year, month, -1, Date::GREGORIAN)
+        last - ((last.wday - weekday) % 7)
+      end
+    end
+  end
+end

data/lib/finrb/calendars.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'finrb/calendars/base'
+require 'finrb/calendars/hebrew_calendar'
+require 'finrb/calendars/israel_tase'
+require 'finrb/calendars/us_federal_reserve'

data/lib/finrb/day_count.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+require 'date'
+
+module Finrb
+  # Year-fraction calculations used to express elapsed time under a named
+  # financial day-count convention.
+  module DayCount
+    CONVENTIONS = %i[actual_365_fixed actual_360 actual_actual_icma].freeze
+    DEFAULT = :actual_365_fixed
+    public_constant :CONVENTIONS, :DEFAULT
+
+    module_function
+
+    # Calculate a signed year fraction. Actual/Actual ICMA requires the regular
+    # coupon reference period and coupon frequency containing the date range.
+    def year_fraction(start_date, end_date, convention: DEFAULT, reference_period_start: nil, reference_period_end: nil, frequency: nil)
+      raise(ArgumentError, "day-count convention must be one of #{CONVENTIONS.join(', ')}.") unless CONVENTIONS.include?(convention)
+
+      start_date = normalize_date(start_date, 'start_date')
+      end_date = normalize_date(end_date, 'end_date')
+
+      if convention == :actual_actual_icma
+        icma_year_fraction(start_date, end_date, reference_period_start, reference_period_end, frequency)
+      else
+        reject_reference_period_arguments!(reference_period_start, reference_period_end, frequency)
+        denominator = convention == :actual_360 ? 360 : 365
+
+        Flt::DecNum((end_date - start_date).to_i.to_s) / Flt::DecNum(denominator.to_s)
+      end
+    end
+
+    def icma_year_fraction(start_date, end_date, reference_period_start, reference_period_end, frequency)
+      raise(ArgumentError, 'Actual/Actual ICMA requires reference_period_start, reference_period_end, and frequency.') unless reference_period_start && reference_period_end && frequency
+
+      reference_period_start = normalize_date(reference_period_start, 'reference_period_start')
+      reference_period_end = normalize_date(reference_period_end, 'reference_period_end')
+      raise(ArgumentError, 'reference_period_end must be after reference_period_start.') if reference_period_end <= reference_period_start
+      raise(ArgumentError, 'frequency must be a positive integer.') unless frequency.is_a?(Integer) && frequency.positive?
+
+      elapsed_days = Flt::DecNum((end_date - start_date).to_i.to_s)
+      reference_days = Flt::DecNum((reference_period_end - reference_period_start).to_i.to_s)
+      elapsed_days / (reference_days * frequency)
+    end
+    private_class_method :icma_year_fraction
+
+    def reject_reference_period_arguments!(reference_period_start, reference_period_end, frequency)
+      return if reference_period_start.nil? && reference_period_end.nil? && frequency.nil?
+
+      raise(ArgumentError, 'reference-period arguments are only valid for Actual/Actual ICMA.')
+    end
+    private_class_method :reject_reference_period_arguments!
+
+    def normalize_date(date, name)
+      raise(ArgumentError, "#{name} must be a Date.") unless date.instance_of?(Date)
+
+      Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+    end
+    private_class_method :normalize_date
+  end
+end

data/lib/finrb/fixed_rate_bond.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative 'calendars'
+require_relative 'config'
+require_relative 'day_count'
+require_relative 'errors'
+require_relative 'numerical/brent'
+require_relative 'numerical/rate_search'
+require_relative 'schedule'
+require_relative 'transaction'
+require_relative 'validation'
+
+module Finrb
+  # Fixed-coupon bullet bond valuation under explicit Actual/Actual ICMA rules.
+  class FixedRateBond
+    PRICE_TYPES = %i[clean dirty].freeze
+    public_constant :PRICE_TYPES
+
+    CouponPeriod = Data.define(:accrual_start_date, :accrual_end_date, :payment_date, :amount)
+    private_constant :CouponPeriod
+
+    attr_reader :face_value, :coupon_rate, :issue_date, :maturity_date, :frequency, :schedule, :calendar, :business_day_convention
+
+    def initialize(face_value:, coupon_rate:, issue_date:, maturity_date:, frequency: :semiannual, calendar: nil, business_day_convention: nil)
+      @face_value = Validation.positive_decimal(face_value, name: 'face value')
+      @coupon_rate = Validation.non_negative_decimal(coupon_rate, name: 'annual coupon rate')
+      @schedule = Schedule.new(start_date: issue_date, maturity_date:, frequency:, calendar:, business_day_convention:)
+
+      @issue_date = schedule.start_date
+      @maturity_date = schedule.maturity_date
+      @frequency = frequency
+      @coupon_frequency = 12 / Schedule::FREQUENCY_MONTHS.fetch(frequency)
+      @calendar = calendar
+      @business_day_convention = business_day_convention
+      @coupon_periods = build_coupon_periods.freeze
+      freeze
+    end
+
+    def day_count
+      :actual_actual_icma
+    end
+
+    # Return future coupon and redemption cashflows as dated positive transactions.
+    def cashflows(settlement_date:)
+      settlement_date = validate_settlement_date!(settlement_date)
+      cashflows =
+        @coupon_periods.filter_map.with_index do |period, index|
+          next if period.payment_date <= settlement_date
+
+          amount = period.amount
+          amount += face_value if index == @coupon_periods.length - 1
+          Transaction.new(amount, date: period.payment_date)
+        end
+      cashflows.freeze
+    end
+
+    def accrued_interest(settlement_date:)
+      settlement_date = validate_settlement_date!(settlement_date)
+      period = @coupon_periods.find { |coupon_period| coupon_period.payment_date > settlement_date }
+      return Flt::DecNum(0) if period.nil?
+
+      accrual_end = [settlement_date, period.accrual_end_date].min
+      return Flt::DecNum(0) if accrual_end <= period.accrual_start_date
+
+      fraction = icma_fraction(period.accrual_start_date, accrual_end, period.accrual_start_date, period.accrual_end_date)
+      face_value * coupon_rate * fraction
+    end
+
+    def dirty_price(settlement_date:, yield_rate:)
+      settlement_date = validate_settlement_date!(settlement_date)
+      yield_rate = Validation.decimal_greater_than(yield_rate, minimum: -1, name: 'bond yield', error: DomainError)
+      periodic_yield = yield_rate / @coupon_frequency
+      discount_base = periodic_yield + 1
+
+      @coupon_periods.each_with_index.sum(Flt::DecNum(0)) do |period, index|
+        next Flt::DecNum(0) if period.payment_date <= settlement_date
+
+        amount = period.amount
+        amount += face_value if index == @coupon_periods.length - 1
+        elapsed_coupon_periods = schedule_year_fraction(settlement_date, period.payment_date) * @coupon_frequency
+        amount / (discount_base**elapsed_coupon_periods)
+      end
+    end
+
+    def clean_price(settlement_date:, yield_rate:)
+      dirty_price(settlement_date:, yield_rate:) - accrued_interest(settlement_date:)
+    end
+
+    def yield_to_maturity(settlement_date:, price:, price_type: :clean, guess: Finrb.config.guess)
+      settlement_date = validate_settlement_date!(settlement_date)
+      raise(ArgumentError, "price_type must be one of #{PRICE_TYPES.join(', ')}.") unless PRICE_TYPES.include?(price_type)
+
+      quoted_price = Validation.positive_decimal(price, name: "#{price_type} bond price", error: DomainError)
+      dirty_price_target = price_type == :clean ? quoted_price + accrued_interest(settlement_date:) : quoted_price
+      rate_function = ->(rate) { dirty_price(settlement_date:, yield_rate: rate) - dirty_price_target }
+      bounds = Numerical::RateSearch.new.bracket(rate_function, guess:)
+      return bounds.first if bounds.first == bounds.last
+
+      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(rate_function, lower: bounds.first, upper: bounds.last)
+    end
+
+    private
+
+    def build_coupon_periods
+      previous_unadjusted_date = issue_date
+      schedule.periods.map do |period|
+        accrual_start_date = previous_unadjusted_date
+        accrual_end_date = period.unadjusted_payment_date
+        fraction = icma_fraction(accrual_start_date, accrual_end_date, accrual_start_date, accrual_end_date)
+        coupon_amount = face_value * coupon_rate * fraction
+        previous_unadjusted_date = accrual_end_date
+        CouponPeriod.new(accrual_start_date:, accrual_end_date:, payment_date: period.payment_date, amount: coupon_amount)
+      end
+    end
+
+    def icma_fraction(start_date, end_date, reference_period_start, reference_period_end)
+      DayCount.year_fraction(start_date, end_date, convention: :actual_actual_icma, reference_period_start:, reference_period_end:, frequency: @coupon_frequency)
+    end
+
+    def schedule_year_fraction(start_date, end_date)
+      @coupon_periods.sum(Flt::DecNum(0)) do |period|
+        overlap_start = [start_date, period.accrual_start_date].max
+        overlap_end = [end_date, period.accrual_end_date].min
+        next Flt::DecNum(0) if overlap_end <= overlap_start
+
+        icma_fraction(overlap_start, overlap_end, period.accrual_start_date, period.accrual_end_date)
+      end
+    end
+
+    def validate_settlement_date!(date)
+      raise(ArgumentError, 'settlement_date must be a Date.') unless date.instance_of?(Date)
+
+      date = Date.new(date.year, date.month, date.day, Date::GREGORIAN)
+      raise(ArgumentError, 'settlement_date must be on or after issue_date.') if date < issue_date
+      raise(ArgumentError, 'settlement_date must be before maturity_date.') if date >= maturity_date
+
+      date
+    end
+  end
+end