TB Drug Types and Parameters¶

This module provides comprehensive drug type definitions, parameter management, and drug regimen configuration for tuberculosis treatment interventions.

TB Drug Type Enumeration¶

TB Drug Types enumeration matching EMOD-Generic’s TBDrugType.

This enum defines the different types of TB drug regimens available, with the same values as EMOD-Generic for compatibility. Each drug type represents a different treatment approach with varying efficacy, cost, and side effect profiles.

tbsim.interventions.tb_drug_types.TBDrugType.DOTS¶: Standard Directly Observed Treatment, Short-course (most common)

tbsim.interventions.tb_drug_types.TBDrugType.DOTS_IMPROVED¶: Enhanced DOTS with better support and monitoring

tbsim.interventions.tb_drug_types.TBDrugType.EMPIRIC_TREATMENT¶: Treatment without confirmed drug sensitivity

tbsim.interventions.tb_drug_types.TBDrugType.FIRST_LINE_COMBO¶: First-line combination therapy for drug-sensitive TB

tbsim.interventions.tb_drug_types.TBDrugType.SECOND_LINE_COMBO¶: Second-line therapy for MDR-TB

tbsim.interventions.tb_drug_types.TBDrugType.THIRD_LINE_COMBO¶: Third-line therapy for XDR-TB

tbsim.interventions.tb_drug_types.TBDrugType.LATENT_TREATMENT¶: Treatment for latent TB infection

Example

>>> drug_type = TBDrugType.DOTS
>>> print(drug_type.name)  # 'DOTS'
>>> print(drug_type.value)  # 1

TB Drug Parameters¶

Base class for TB drug parameters.

This class defines the standard parameters that all TB drugs have, similar to EMOD-Generic’s TBDrugTypeParameters. It provides a consistent interface for accessing drug-specific effects and characteristics.

tbsim.interventions.tb_drug_types.TBDrugParameters.drug_name¶: Human-readable name of the drug regimen

tbsim.interventions.tb_drug_types.TBDrugParameters.drug_type¶: TBDrugType enum value for this drug

tbsim.interventions.tb_drug_types.TBDrugParameters.inactivation_rate¶: Rate at which the drug inactivates TB bacteria

tbsim.interventions.tb_drug_types.TBDrugParameters.cure_rate¶: Probability of successful cure with this drug

tbsim.interventions.tb_drug_types.TBDrugParameters.resistance_rate¶: Rate at which resistance develops to this drug

tbsim.interventions.tb_drug_types.TBDrugParameters.relapse_rate¶: Rate of relapse after successful treatment

tbsim.interventions.tb_drug_types.TBDrugParameters.mortality_rate¶: Reduction in mortality rate due to treatment

tbsim.interventions.tb_drug_types.TBDrugParameters.primary_decay_time_constant¶: Time constant for drug effectiveness decay

tbsim.interventions.tb_drug_types.TBDrugParameters.duration¶: Standard treatment duration in days

tbsim.interventions.tb_drug_types.TBDrugParameters.adherence_rate¶: Expected adherence rate for this regimen

tbsim.interventions.tb_drug_types.TBDrugParameters.cost_per_course¶: Cost per complete treatment course in USD

Example

>>> params = TBDrugParameters("Test Drug", TBDrugType.DOTS)
>>> params.configure({'cure_rate': 0.85, 'duration': 180})
>>> print(f"Cure rate: {params.cure_rate}")

tbsim.interventions.tb_drug_types.TBDrugParameters.__delattr__(self, name, /)¶: Implement delattr(self, name).

tbsim.interventions.tb_drug_types.TBDrugParameters.__dir__(self, /)¶: Default dir() implementation.

tbsim.interventions.tb_drug_types.TBDrugParameters.__eq__(self, value, /)¶: Return self==value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__format__(self, format_spec, /)¶: Default object formatter.

tbsim.interventions.tb_drug_types.TBDrugParameters.__ge__(self, value, /)¶: Return self>=value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__getattribute__(self, name, /)¶: Return getattr(self, name).

tbsim.interventions.tb_drug_types.TBDrugParameters.__gt__(self, value, /)¶: Return self>value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__hash__(self, /)¶: Return hash(self).

tbsim.interventions.tb_drug_types.TBDrugParameters.__init_subclass__()¶

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

tbsim.interventions.tb_drug_types.TBDrugParameters.__le__(self, value, /)¶: Return self<=value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__lt__(self, value, /)¶: Return self<value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__ne__(self, value, /)¶: Return self!=value.

tbsim.interventions.tb_drug_types.TBDrugParameters.__new__(*args, **kwargs)¶: Create and return a new object. See help(type) for accurate signature.

tbsim.interventions.tb_drug_types.TBDrugParameters.__reduce__(self, /)¶: Helper for pickle.

tbsim.interventions.tb_drug_types.TBDrugParameters.__reduce_ex__(self, protocol, /)¶: Helper for pickle.

tbsim.interventions.tb_drug_types.TBDrugParameters.__setattr__(self, name, value, /)¶: Implement setattr(self, name, value).

tbsim.interventions.tb_drug_types.TBDrugParameters.__sizeof__(self, /)¶: Size of object in memory, in bytes.

tbsim.interventions.tb_drug_types.TBDrugParameters.__str__(self, /)¶: Return str(self).

tbsim.interventions.tb_drug_types.TBDrugParameters.__subclasshook__()¶

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

TB Drug Type Parameters¶

Factory class for creating drug parameters for different drug types.

This class provides predefined parameter sets for each drug type, similar to how EMOD-Generic configures different drug regimens. Each factory method creates a TBDrugParameters object with realistic values based on clinical evidence and WHO guidelines.

The parameter values are based on: - WHO treatment guidelines - Clinical trial results - Cost-effectiveness studies - Real-world implementation data

Example

>>> dots_params = TBDrugTypeParameters.create_dots_parameters()
>>> print(f"DOTS cure rate: {dots_params.cure_rate}")
>>> all_params = TBDrugTypeParameters.get_all_parameter_sets()
>>> len(all_params)
7

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__delattr__(self, name, /)¶: Implement delattr(self, name).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__dir__(self, /)¶: Default dir() implementation.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__eq__(self, value, /)¶: Return self==value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__format__(self, format_spec, /)¶: Default object formatter.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__ge__(self, value, /)¶: Return self>=value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__getattribute__(self, name, /)¶: Return getattr(self, name).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__gt__(self, value, /)¶: Return self>value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__hash__(self, /)¶: Return hash(self).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__init__(self, /, *args, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__init_subclass__()¶

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__le__(self, value, /)¶: Return self<=value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__lt__(self, value, /)¶: Return self<value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__ne__(self, value, /)¶: Return self!=value.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__new__(*args, **kwargs)¶: Create and return a new object. See help(type) for accurate signature.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__reduce__(self, /)¶: Helper for pickle.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__reduce_ex__(self, protocol, /)¶: Helper for pickle.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__repr__(self, /)¶: Return repr(self).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__setattr__(self, name, value, /)¶: Implement setattr(self, name, value).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__sizeof__(self, /)¶: Size of object in memory, in bytes.

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__str__(self, /)¶: Return str(self).

tbsim.interventions.tb_drug_types.TBDrugTypeParameters.__subclasshook__()¶

Abstract classes can override this to customize issubclass().

Utility Functions¶

TB Drug Types and Parameters for TBsim

This module implements TB drug types and parameters similar to EMOD-Generic’s approach, providing detailed drug-specific parameters for different TB treatment regimens.

The module provides: - TBDrugType enum: Defines different TB drug regimens with values matching EMOD-Generic - TBDrugParameters class: Base class for drug-specific parameters - TBDrugTypeParameters factory: Creates predefined parameter sets for each drug type - Convenience functions: Easy access to drug parameters

Example

>>> from tbsim.interventions import get_dots_parameters, TBDrugType
>>> dots_params = get_dots_parameters()
>>> print(f"DOTS cure rate: {dots_params.cure_rate}")
>>> first_line_params = get_drug_parameters(TBDrugType.FIRST_LINE_COMBO)
>>> print(f"First line cost: ${first_line_params.cost_per_course}")

References

EMOD-Generic TBDrugType enum and TBDrugTypeParameters class
WHO guidelines for TB treatment regimens
Standard TB drug efficacy and cost parameters

class tbsim.interventions.tb_drug_types.TBDrugType(value)[source]¶

Bases: IntEnum

TB Drug Types enumeration matching EMOD-Generic’s TBDrugType.

DOTS¶: Standard Directly Observed Treatment, Short-course (most common)

DOTS_IMPROVED¶: Enhanced DOTS with better support and monitoring

EMPIRIC_TREATMENT¶: Treatment without confirmed drug sensitivity

FIRST_LINE_COMBO¶: First-line combination therapy for drug-sensitive TB

SECOND_LINE_COMBO¶: Second-line therapy for MDR-TB

THIRD_LINE_COMBO¶: Third-line therapy for XDR-TB

LATENT_TREATMENT¶: Treatment for latent TB infection

Example

>>> drug_type = TBDrugType.DOTS
>>> print(drug_type.name)  # 'DOTS'
>>> print(drug_type.value)  # 1

DOTS = 1¶

DOTS_IMPROVED = 2¶

EMPIRIC_TREATMENT = 3¶

FIRST_LINE_COMBO = 4¶

SECOND_LINE_COMBO = 5¶

THIRD_LINE_COMBO = 6¶

LATENT_TREATMENT = 7¶

classmethod get_name(value: int) → str[source]¶

Get the string name for a drug type value.

Parameters:: value – Integer value of the drug type
Returns:: String name of the drug type, or ‘UNKNOWN_X’ if not found

Example

>>> TBDrugType.get_name(1)
'DOTS'
>>> TBDrugType.get_name(999)
'UNKNOWN_999'

classmethod get_all_types() → list[source]¶

Get all drug types as a list.

Returns:: List of all TBDrugType enum values

Example

>>> types = TBDrugType.get_all_types()
>>> len(types)
7
>>> TBDrugType.DOTS in types
True

class tbsim.interventions.tb_drug_types.TBDrugParameters(drug_name: str, drug_type: TBDrugType)[source]¶

Bases: object

Base class for TB drug parameters.

drug_name¶: Human-readable name of the drug regimen

drug_type¶: TBDrugType enum value for this drug

inactivation_rate¶: Rate at which the drug inactivates TB bacteria

cure_rate¶: Probability of successful cure with this drug

resistance_rate¶: Rate at which resistance develops to this drug

relapse_rate¶: Rate of relapse after successful treatment

mortality_rate¶: Reduction in mortality rate due to treatment

primary_decay_time_constant¶: Time constant for drug effectiveness decay

duration¶: Standard treatment duration in days

adherence_rate¶: Expected adherence rate for this regimen

cost_per_course¶: Cost per complete treatment course in USD

Example

>>> params = TBDrugParameters("Test Drug", TBDrugType.DOTS)
>>> params.configure({'cure_rate': 0.85, 'duration': 180})
>>> print(f"Cure rate: {params.cure_rate}")

__init__(drug_name: str, drug_type: TBDrugType)[source]¶

Initialize drug parameters.

Parameters:

drug_name – Name of the drug regimen (e.g., “DOTS”, “First Line Combo”)
drug_type – Type of drug from TBDrugType enum

Example

>>> params = TBDrugParameters("DOTS", TBDrugType.DOTS)
>>> params.drug_name
'DOTS'
>>> params.drug_type
<TBDrugType.DOTS: 1>

configure(parameters: Dict[str, Any]) → None[source]¶

Configure drug parameters from a dictionary.

This method allows setting multiple parameters at once by providing a dictionary of parameter names and values. Only parameters that exist as attributes of the object will be set.

Parameters:: parameters – Dictionary containing parameter values to set

Example

>>> params = TBDrugParameters("Test", TBDrugType.DOTS)
>>> params.configure({
...     'cure_rate': 0.85,
...     'duration': 180,
...     'cost_per_course': 100
... })
>>> params.cure_rate
0.85

get_effectiveness(time_on_treatment: float) → float[source]¶

Calculate drug effectiveness based on time on treatment.

This method models how drug effectiveness changes over time during treatment. Effectiveness typically increases initially as the drug builds up in the system, then may decay due to various factors like bacterial adaptation or drug metabolism.

Mathematical Model:

Days 0-30: Linear increase from 0 to 1.0 (drug building up)
Days 30+: Exponential decay with time constant
Minimum effectiveness: 10% (drug never completely loses effect)

Parameters:: time_on_treatment – Time in days since treatment started
Returns:: Effectiveness multiplier (0.0 to 1.0) where 1.0 = 100% effective

Example

>>> params = TBDrugParameters("Test", TBDrugType.DOTS)
>>> params.get_effectiveness(0)
0.0
>>> params.get_effectiveness(30)
1.0
>>> params.get_effectiveness(60)
0.368  # Approximately e^(-1)

__repr__() → str[source]¶

String representation of the drug parameters.

Returns:: String showing drug name and type

Example

>>> params = TBDrugParameters("DOTS", TBDrugType.DOTS)
>>> repr(params)
'TBDrugParameters(DOTS, type=DOTS)'

class tbsim.interventions.tb_drug_types.TBDrugTypeParameters[source]¶

Bases: object

Factory class for creating drug parameters for different drug types.

The parameter values are based on: - WHO treatment guidelines - Clinical trial results - Cost-effectiveness studies - Real-world implementation data

Example

>>> dots_params = TBDrugTypeParameters.create_dots_parameters()
>>> print(f"DOTS cure rate: {dots_params.cure_rate}")
>>> all_params = TBDrugTypeParameters.get_all_parameter_sets()
>>> len(all_params)
7

static create_dots_parameters() → TBDrugParameters[source]¶

Create parameters for DOTS regimen.

DOTS (Directly Observed Treatment, Short-course) is the standard TB treatment regimen recommended by WHO. It involves directly observed therapy to ensure adherence and completion.

Parameter values based on: - WHO DOTS guidelines - Meta-analysis of DOTS effectiveness - Cost studies from multiple countries

Returns:: TBDrugParameters object configured for DOTS treatment

Example

>>> params = TBDrugTypeParameters.create_dots_parameters()
>>> params.cure_rate
0.85
>>> params.duration
180.0

static create_dots_improved_parameters() → TBDrugParameters[source]¶

Create parameters for improved DOTS regimen.

Improved DOTS includes enhanced support mechanisms, better patient education, and improved monitoring compared to standard DOTS.

Parameter values based on: - Enhanced DOTS program evaluations - Patient support intervention studies - Improved monitoring system data

Returns:: TBDrugParameters object configured for improved DOTS treatment

Example

>>> params = TBDrugTypeParameters.create_dots_improved_parameters()
>>> params.cure_rate
0.9
>>> params.adherence_rate
0.9

static create_empiric_treatment_parameters() → TBDrugParameters[source]¶

Create parameters for empiric treatment.

Empiric treatment is given when drug sensitivity is unknown, typically in emergency situations or when diagnostic testing is not available.

Parameter values based on: - Empiric treatment guidelines - Emergency TB treatment protocols - Unknown sensitivity scenario modeling

Returns:: TBDrugParameters object configured for empiric treatment

Example

>>> params = TBDrugTypeParameters.create_empiric_treatment_parameters()
>>> params.cure_rate
0.7
>>> params.resistance_rate
0.05

static create_first_line_combo_parameters() → TBDrugParameters[source]¶

Create parameters for first-line combination therapy.

First-line combination therapy uses multiple drugs with different mechanisms of action to maximize efficacy and minimize resistance development.

Parameter values based on: - First-line combination therapy trials - Multi-drug regimen effectiveness studies - Resistance prevention data

Returns:: TBDrugParameters object configured for first-line combination therapy

Example

>>> params = TBDrugTypeParameters.create_first_line_combo_parameters()
>>> params.cure_rate
0.95
>>> params.resistance_rate
0.01

static create_second_line_combo_parameters() → TBDrugParameters[source]¶

Create parameters for second-line combination therapy.

Second-line therapy is used for MDR-TB cases that have failed first-line treatment or are resistant to first-line drugs.

Parameter values based on: - MDR-TB treatment protocols - Second-line drug efficacy studies - MDR-TB treatment outcomes

Returns:: TBDrugParameters object configured for second-line combination therapy

Example

>>> params = TBDrugTypeParameters.create_second_line_combo_parameters()
>>> params.cure_rate
0.75
>>> params.duration
240.0

static create_third_line_combo_parameters() → TBDrugParameters[source]¶

Create parameters for third-line combination therapy.

Third-line therapy is used for XDR-TB cases that have failed both first and second-line treatments.

Parameter values based on: - XDR-TB treatment protocols - Third-line drug availability and efficacy - XDR-TB treatment outcomes

Returns:: TBDrugParameters object configured for third-line combination therapy

Example

>>> params = TBDrugTypeParameters.create_third_line_combo_parameters()
>>> params.cure_rate
0.6
>>> params.cost_per_course
1000.0

static create_latent_treatment_parameters() → TBDrugParameters[source]¶

Create parameters for latent TB treatment.

Latent TB treatment (also called preventive therapy) is given to people with latent TB infection to prevent progression to active disease.

Parameter values based on: - Latent TB treatment guidelines - Preventive therapy efficacy studies - Latent TB treatment outcomes

Returns:: TBDrugParameters object configured for latent TB treatment

Example

>>> params = TBDrugTypeParameters.create_latent_treatment_parameters()
>>> params.cure_rate
0.9
>>> params.duration
90.0

static create_parameters_for_type(drug_type: TBDrugType) → TBDrugParameters[source]¶

Create parameters for a specific drug type.

This is the main factory method that routes to the appropriate specific factory method based on the drug type provided.

Parameters:: drug_type – The drug type to create parameters for
Returns:: TBDrugParameters object with appropriate values
Raises:: ValueError – If the drug type is not recognized

Example

>>> params = TBDrugTypeParameters.create_parameters_for_type(TBDrugType.DOTS)
>>> params.drug_type
<TBDrugType.DOTS: 1>
>>> params.cure_rate
0.85

static get_all_parameter_sets() → Dict[TBDrugType, TBDrugParameters][source]¶

Get all predefined parameter sets.

This method creates parameter sets for all drug types and returns them as a dictionary for easy access and comparison.

Returns:: Dictionary mapping drug types to their parameters

Example

>>> all_params = TBDrugTypeParameters.get_all_parameter_sets()
>>> len(all_params)
7
>>> all_params[TBDrugType.DOTS].cure_rate
0.85
>>> all_params[TBDrugType.FIRST_LINE_COMBO].cure_rate
0.95

Model Overview¶

The TB Drug Types module provides a comprehensive framework for managing tuberculosis drug regimens and treatment parameters:

Drug Type Definitions

DOTS (1): Standard Directly Observed Treatment, Short-course
DOTS_IMPROVED (2): Enhanced DOTS with better support and monitoring
EMPIRIC_TREATMENT (3): Treatment without confirmed drug sensitivity
FIRST_LINE_COMBO (4): First-line combination therapy for drug-sensitive TB
SECOND_LINE_COMBO (5): Second-line therapy for MDR-TB
THIRD_LINE_COMBO (6): Third-line therapy for XDR-TB
LATENT_TREATMENT (7): Treatment for latent TB infection

Parameter Management

Drug-specific effectiveness curves
Time-dependent treatment outcomes
Configurable treatment parameters
Standardized parameter sets

Integration Capabilities

Treatment intervention integration
Dynamic parameter adjustment
Drug resistance modeling
Treatment outcome tracking

Key Features¶

Comprehensive Drug Coverage

All WHO-recommended TB drug regimens
Drug resistance level specific treatments
Latent TB infection treatment options
Empiric treatment protocols

Parameter Standardization

Pre-configured parameter sets for each drug type
Evidence-based effectiveness curves
Configurable treatment parameters
Validation and error checking

Treatment Effectiveness Modeling

Time-dependent effectiveness curves
Drug-specific outcome patterns
Adherence consideration
Resistance development modeling

Flexible Configuration

Custom parameter modification
Drug type switching
Dynamic parameter updates
Batch parameter management

Usage Examples¶

Basic drug type usage:

from tbsim.interventions.tb_drug_types import TBDrugType

# Get drug type information
dots_type = TBDrugType.DOTS
print(f"DOTS value: {dots_type.value}")
print(f"DOTS name: {dots_type.name}")

# Get all available drug types
all_types = TBDrugType.get_all_types()
print(f"Available types: {all_types}")

Creating drug parameters:

from tbsim.interventions.tb_drug_types import TBDrugParameters, TBDrugType

# Create custom drug parameters
custom_drug = TBDrugParameters(
    drug_name="Custom Regimen",
    drug_type=TBDrugType.FIRST_LINE_COMBO
)

# Configure parameters
custom_drug.configure({
    'base_effectiveness': 0.85,
    'time_to_peak': 30,
    'peak_effectiveness': 0.95,
    'decay_rate': 0.02
})

Using pre-configured parameters:

from tbsim.interventions.tb_drug_types import get_dots_parameters, get_drug_parameters

# Get standard DOTS parameters
dots_params = get_dots_parameters()

# Get parameters for specific drug type
first_line_params = get_drug_parameters(TBDrugType.FIRST_LINE_COMBO)

# Get all parameter sets
from tbsim.interventions.tb_drug_types import get_all_drug_parameters
all_params = get_all_drug_parameters()

Drug effectiveness analysis:

# Analyze treatment effectiveness over time
dots_params = get_dots_parameters()

# Get effectiveness at different time points
effectiveness_30d = dots_params.get_effectiveness(30)   # 30 days
effectiveness_90d = dots_params.get_effectiveness(90)   # 90 days
effectiveness_180d = dots_params.get_effectiveness(180) # 180 days

print(f"Effectiveness at 30 days: {effectiveness_30d:.3f}")
print(f"Effectiveness at 90 days: {effectiveness_90d:.3f}")
print(f"Effectiveness at 180 days: {effectiveness_180d:.3f}")

Integration with Treatment Interventions¶

Enhanced TB Treatment Integration

Direct integration with EnhancedTBTreatment class
Automatic parameter loading
Drug type validation
Treatment outcome tracking

Parameter Validation

Range checking for all parameters
Type validation
Consistency checking
Error reporting and handling

Dynamic Parameter Management

Runtime parameter updates
Drug type switching
Effectiveness curve modification
Resistance pattern updates

Mathematical Framework¶

Effectiveness Curves

Time-dependent effectiveness modeling
Peak effectiveness timing
Decay rate calculations
Adherence effects

Treatment Outcomes

Success probability calculations
Failure rate modeling
Resistance development
Relapse probability

Parameter Relationships

Drug type specific relationships
Cross-drug interactions
Resistance patterns
Treatment sequencing

For detailed information about specific methods and parameters, see the individual class documentation above. All methods include comprehensive mathematical models and implementation details in their docstrings.