Expand description
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.
- Named
Cal - A wrapper for a UnionCal struct specified by a string representation.
- Schedule
- A generic financial schedule with regular contiguous periods and, possibly, stubs.
- Union
Cal - A business day calendar which is the potential union of multiple calendars.
Enums§
- Adjuster
- A list of rules for performing date adjustment.
- Calendar
- Container for calendar types.
- Convention
- Frequency
- A frequency for generating unadjusted scheduling periods.
- Imm
- An IMM date definition.
- RollDay
- A roll-day used with a
Frequency::Months
variant. - Stub
Inference - An indicator 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
. - Calendar
Adjustment - Perform date adjustment according to adjustment rules, i.e. a given
Adjuster
. - Date
Roll - 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.