Advertising

Ad platform simulation with audience tiers, advertisers, and bidding.

Advertising economics simulation components.

Models the dynamics of digital advertising platforms, including audience targeting tiers, advertiser profitability analysis, and the Adverse Advertising Amplification (AAA) effect.

The AAA effect describes how small changes in consumer sentiment cause disproportionately large revenue losses for advertising platforms. This happens because outer-ring (broad, high-CPA) campaigns become unprofitable first and get shut off, removing the platform's most lucrative revenue streams.

Typical usage::

platform = AdPlatform("Meta")
tiers = [
    AudienceTier("Niche", base_monthly_sales=100, base_cpa=10.0),
    AudienceTier("Broad", base_monthly_sales=1000, base_cpa=40.0),
]
advertiser = Advertiser(
    "PosterShop",
    product_price=100.0,
    production_cost=50.0,
    tiers=tiers,
    platform=platform,
)
sim = Simulation(entities=[platform, advertiser], end_time=...)
for e in advertiser.start_events():
    sim.schedule(e)
sim.run()

AudienceTier dataclass

AudienceTier(
    name: str, base_monthly_sales: int, base_cpa: float
)

An audience segment with specific advertising economics.

Represents one concentric ring of advertising reach. Inner rings (niche audiences) have high conversion rates and low cost per acquisition (CPA). Outer rings (broad audiences) have low conversion rates and high CPA.

The ad spend for a tier is constant regardless of consumer sentiment (you reach the same audience at the same cost). When sentiment drops, fewer people convert, so CPA rises. When CPA exceeds the profit margin, a rational advertiser shuts off the tier entirely.

Parameters:

Name	Type	Description	Default
name	str	Human-readable tier label.	required
base_monthly_sales	int	Expected sales per period at sentiment=1.0.	required
base_cpa	float	Cost per acquisition at sentiment=1.0.	required

monthly_ad_spend property

monthly_ad_spend: float

Fixed monthly ad spend (reach cost is constant).

effective_cpa

effective_cpa(sentiment: float) -> float

CPA adjusted for current consumer sentiment.

monthly_sales

monthly_sales(sentiment: float) -> float

Expected sales given current sentiment.

breakeven_sentiment

breakeven_sentiment(margin: float) -> float

Minimum sentiment at which this tier is profitable.

Below this value, CPA exceeds margin and a rational advertiser would shut off the campaign.

is_profitable

is_profitable(sentiment: float, margin: float) -> bool

Whether this tier generates positive profit at given sentiment.

tier_profit

tier_profit(sentiment: float, margin: float) -> float

Advertiser profit from this tier for one period.

tier_platform_revenue

tier_platform_revenue(
    sentiment: float, margin: float
) -> float

Platform revenue from this tier for one period.

Returns zero if the tier is shut off (unprofitable). When active, the platform collects the full fixed ad spend regardless of conversion count.

AdvertiserStats dataclass

AdvertiserStats(
    periods_evaluated: int = 0,
    total_profit: float = 0.0,
    total_platform_revenue: float = 0.0,
    tier_shutoff_events: int = 0,
)

Aggregate statistics for an advertiser.

Advertiser

Advertiser(
    name: str,
    *,
    product_price: float,
    production_cost: float,
    tiers: list[AudienceTier],
    platform: AdPlatform,
    evaluation_interval: float = 1.0,
)

Bases: Entity

A business that sells products through advertising on a platform.

Manages multiple audience tiers, periodically evaluating profitability and shutting off tiers that don't generate positive profit. Reports ad revenue to the associated AdPlatform.

The margin (product_price - production_cost) determines the maximum CPA tolerable. As consumer sentiment drops, CPA rises and outer tiers become unprofitable first.

Parameters:

Name	Type	Description	Default
name	str	Entity name.	required
product_price	float	Selling price per unit.	required
production_cost	float	Non-advertising cost per unit.	required
tiers	list[AudienceTier]	List of AudienceTier objects, from niche to broad.	required
platform	AdPlatform	The AdPlatform entity to report revenue to.	required
evaluation_interval	float	Simulated seconds between evaluations.	1.0

stats property

stats: AdvertiserStats

Return a frozen snapshot of advertiser statistics.

reset

reset() -> None

Reset internal state for simulation replay.

start_events

start_events() -> list[Event]

Generate the initial evaluation event.

sensitivity_analysis

sensitivity_analysis(
    sentiment_range: tuple[float, float] = (0.0, 1.0),
    steps: int = 100,
) -> list[dict]

Static analysis of profit/revenue across sentiment values.

Returns a list of dicts with keys: sentiment, advertiser_profit, platform_revenue, active_tiers, tier_names.

AdPlatformStats dataclass

AdPlatformStats(
    revenue_events: int = 0, total_revenue: float = 0.0
)

Aggregate statistics for an ad platform.

AdPlatform

AdPlatform(name: str)

Bases: Entity

An advertising platform that collects revenue from advertisers.

Passively receives AdRevenue events from Advertiser entities and tracks cumulative and per-period revenue.

Parameters:

Name	Type	Description	Default
name	str	Entity name (e.g., "Meta", "Google").	required

stats property

stats: AdPlatformStats

Return a frozen snapshot of platform statistics.

reset

reset() -> None

Reset internal state for simulation replay.