Module scheduling

Create a business day Calendar, instrument Schedule and perform financial date manipulation.

The purpose of this module is to provide objects which are capable of replicating all of the complexities of financial instrument specification, including examples such as;

• FX spot determination including all of the various currency pair rules.
• Business day calendar combination for multi-currency derivatives.
• Standard schedule generation including all of the accrual and payment Adjuster rules, like modified following, CDS’s unadjusted last period etc.
• Inference for stub dates and monthly RollDay when utilising a UI which extends to users being allowed to supply unknown or ambiguous parameters.

The supplementary material discusses the algorithms, architecture and implementation of these objects.

Calendars and Date Adjustment

Calendars

Rateslib provides three calendar types: Cal, UnionCal and NamedCal and the container enum Calendar. These are based on simple holiday and weekend specification and union rules for combinations. Some common calendars are implemented directly by name, and can be combined with string parsing syntax.

All calendars implement the DateRoll trait which provide simple date adjustment, which rateslib calls rolling. This involves moving forward or backward from non-business days (or non-settleable days) to specific business days or settleable business days.

Example

This example creates a business day calendar defining Saturday and Sunday weekends and a specific holiday (the Early May UK Bank Holiday). It uses a date rolling method to manipulate Saturday 29th April 2017 under the ‘following’ and ‘modified following’ rules.

let cal = Cal::new(vec![ndt(2017, 5, 1)], vec![5, 6]);
assert_eq!(ndt(2017, 5, 2), cal.roll_forward_bus_day(&ndt(2017, 4, 29)));
assert_eq!(ndt(2017, 4, 28), cal.roll_mod_forward_bus_day(&ndt(2017, 4, 29)));

Date Adjustment

Date adjustment allows for a more complicated set of rules than simple date rolling. The Adjuster is an enum which defines the implementation of all of these rules and may be extended in the future if more rules are required for more complex instruments. It implements the Adjustment trait requiring some object capable of performing DateRoll to define the operations.

All Calendar types implement the CalendarAdjustment trait which permits date adjustment when an Adjuster is cross-provided.

Example

This example performs the complex rule of adjusting a given date forward by 5 calendar days and then rolling that result forward to the next settleable business day.

let adjuster = Adjuster::CalDaysLagSettle(5);
assert_eq!(ndt(2017, 5, 2), cal.adjust(&ndt(2017, 4, 27), &adjuster));
assert_eq!(ndt(2017, 5, 2), cal.adjust(&ndt(2017, 4, 24), &adjuster));

Schedules

A Schedule is an ordered and patterned array of periods and dates. Again, more details can be found in the supplementary material.

All Schedule objects in rateslib are centered about the definition of their Frequency, which is an enum describing a regular period of time. Certain Frequency variants have additional information to fully parametrise them. For example a Frequency::BusDays variant requires a Calendar to define its valid days, and a Frequency::Months variant requires a RollDay to define the day in the month that separates its periods.

The Frequency implements the Scheduling trait which allows periods and stubs to be defined, alluding to the documented definition of regular and irregular schedules as well as permitting the pattern of periods that can form a valid Schedule.

Example

This example creates a new Schedule by inferring that it can be constructed as a regular schedule (one without stubs) if the RollDay is asserted to be the RollDay::IMM variant. Without an IMM roll-day this schedule would be irregular with a short front stub.

let schedule = Schedule::try_new_inferred(
   ndt(2024, 3, 20),                        // effective
   ndt(2025, 9, 17),                        // termination
   Frequency::Months{number:3, roll: None}, // frequency
   None,                                    // front_stub
   None,                                    // back_stub
   Calendar::Cal(cal),                      // calendar
   Adjuster::ModifiedFollowing{},           // accrual_adjuster
   Adjuster::BusDaysLagSettle(2),           // payment_adjuster
   false,                                   // eom
   Some(StubInference::ShortFront),         // stub_inference
);
assert_eq!(schedule.frequency, Frequency::Months{number:3, roll: Some(RollDay::IMM())});
assert!(schedule.is_regular());

The next example creates a new Schedule by inferring that its termination is an adjusted end-of-month date, and therefore its RollDay is asserted to be the RollDay::Day(31) variant, and its utermination is therefore 30th November and it infers a ufront_stub correctly as 31st May 2025.

let schedule = Schedule::try_new_inferred(
   ndt(2025, 4, 15),                        // effective
   ndt(2025, 11, 28),                       // termination
   Frequency::Months{number:3, roll: None}, // frequency
   None,                                    // front_stub
   None,                                    // back_stub
   Calendar::Cal(cal),                      // calendar
   Adjuster::ModifiedFollowing{},           // accrual_adjuster
   Adjuster::BusDaysLagSettle(2),           // payment_adjuster
   true,                                    // eom
   Some(StubInference::ShortFront),         // stub_inference
);
assert_eq!(schedule.frequency, Frequency::Months{number:3, roll: Some(RollDay::Day(31))});
assert_eq!(schedule.utermination, ndt(2025, 11, 30));
assert_eq!(schedule.ufront_stub, Some(ndt(2025, 5, 31)));

Structs

Cal

A basic business day calendar containing holidays.

NamedCal

A wrapper for a UnionCal struct specified by a string representation.

Schedule

A generic financial schedule with regular contiguous periods and, possibly, stubs.

UnionCal

A business day calendar which is the potential union of multiple calendars.

Enums

Adjuster

Specifier for date adjustment rules.

Calendar

Container for calendar types.

Convention

Specifier for day count conventions

Frequency

Specifier for generating unadjusted scheduling periods.

Imm

Specifier for IMM date definitions.

RollDay

A roll-day used with a Frequency::Months variant.

StubInference

Specifier used by Schedule::try_new_inferred to instruct its inference logic.

Traits

Adjustment

Perform date adjustment according to calendar definitions, i.e. a known DateRoll.

CalendarAdjustment

Perform date adjustment according to adjustment rules, i.e. a given Adjuster.

DateRoll

Simple date adjustment defining business, settleable and holidays and rolling.

Scheduling

Used to define periods of financial instrument schedules.

Functions

ndt

Create a NaiveDateTime with default null time.