Experiment Configuration¶

Experiment configuration defines the core settings of the simulation experiment, including the process and environment parameters.

Main Fields¶

ExpConfig Fields:

name (str): Experiment name, default default_experiment
id (UUID): Experiment unique identifier, automatically generated
workflow (list[WorkflowStepConfig]): Workflow step list, required
environment (EnvironmentConfig): Environment configuration

EnvironmentConfig Fields:

start_tick (int): Start time of a day (seconds), default 28800 (8:00)
metric_interval (int): Metric collection interval (seconds), default 3600
weather (str): Weather description, default “The weather is sunny”
temperature (str): Temperature description, default “The temperature is 23C”
workday (bool): Whether it is a workday, default true
other_information (str): Other environment information, default empty

Workflow Step Types¶

Main Execution Types:

run: Execute simulation by days
- days (float): Simulation days
- ticks_per_step (int): Time interval per step (seconds)
step: Execute simulation by steps
- steps (int): Number of execution steps
- ticks_per_step (int): Time interval per step (seconds)

Agent Interaction Types:

interview: Send interview messages to specified agents
- target_agent: Target Agent Selection Settings
- interview_message (str): Interview message
survey: Send questionnaire surveys to specified agents
- target_agent: Target Agent Selection Settings
- survey: Survey questionnaire object, see below Survey Configuration for details
message: Send intervention messages to agents
- target_agent: Target Agent Selection Settings
- intervene_message (str): Intervention message
update_state: Directly update agent state
- target_agent: Target Agent Selection Settings
- key (str): Agent state key
- value (Any): State value

save_context: Save agent context to global Context variable (dict), which is finally stored as a file
- target_agent: Target Agent Selection Settings
- key (str): Agent state key
- save_as (str): Context key for saving agent state in the global variable context
delete_agent: Delete specified agent
- target_agent: Target Agent Selection Settings

Environment Control Types:

environment: Modify environment variables, i.e., other fields in EnvironmentConfig except start_tick
- key (str): Environment variable key
- value (Any): Environment variable value

Other Types:

next_round: Enter the next round of simulation, which will reset all agents (calling agent.reset(), the specific implementation is determined by the agent class)
function: Execute custom function

Target Agent Selection Settings¶

The target_agent parameter is used to specify the target agent for operations, supporting two formats:

Agent ID List¶

Directly specify the list of agent IDs to be operated on:

target_agent: [1, 2, 3, 4, 5]

Agent Filtering Configuration Object¶

Use a configuration object to specify filtering criteria, including a list of agent class names (optional) and filtering conditions (optional):

target_agent:
  agent_class: ["SocietyAgent"]
  filter_str: "${profile.age} > 30"

Filtering Configuration Field Description:

agent_class (Optional[list[str]]): List of agent class names, used to filter agents by type
filter_str (Optional[str]): Filtering condition string, supporting conditional judgments on agent attributes

Filtering Condition Syntax: Filtering conditions use Python expression syntax, accessing agent attributes through ${profile.attribute_name}:

Supports comparison operations: >, <, >=, <=, ==, !=
Supports logical operations: and, or, not
Numerical comparison: ${profile.age} > 30
String comparison: ${profile.gender} == 'male'
Combined conditions: ${profile.age} > 25 and ${profile.income} < 10000

Filtering Configuration Examples:

Filter by agent type:

target_agent:
  agent_class: ["SocietyAgent"]

Filter by attribute conditions:

target_agent:
  filter_str: "${profile.age} >= 18 and ${profile.age} <= 65"

Combined filtering (agents of specific types that meet conditions):

target_agent:
  agent_class: ["SocietyAgent"]
  filter_str: "${profile.gender} == 'female' and ${profile.education} == 'university'"

target_agent:
  filter_str: "(${profile.age} > 30 and ${profile.income} > 8000) or ${profile.occupation} == 'teacher'"

Notes:

At least one of agent_class and filter_str must be provided
If the agent attribute is empty or the attribute in the filtering condition does not exist, the agent will be excluded
Attribute names in filtering conditions must exactly match attribute names in the agent configuration file

Survey Configuration¶

Survey configuration is used to define the questionnaire used in the survey workflow step.

Main Fields of Survey¶

id (UUID): Questionnaire unique identifier
title (str): Questionnaire title, optional, default is empty
description (str): Questionnaire description, optional, default is empty
pages (list[Page]): Questionnaire page list, required

Page Fields¶

name (str): Page name, required
elements (list[Question]): List of questions on the page, required

Question Fields¶

name (str): Question name, required, used as a unique identifier
title (str): Question title, required, the question text displayed to users
type (QuestionType): Question type, required, see below for question types
choices (list[str]): List of choices, used for multiple choice questions, default is empty
required (bool): Whether required, default is true
min_rating (int): Minimum rating value, used for rating questions, default is 1
max_rating (int): Maximum rating value, used for rating questions, default is 5

Question Types¶

1. Text Question (text)

Free text input
No additional configuration required

2. Single Choice Question (radiogroup)

Select one from multiple options
Need to configure the choices field

3. Multiple Choice Question (checkbox)

Select multiple from multiple options
Need to configure the choices field

4. Rating Question (rating)

Numerical rating
Configurable min_rating and max_rating

Survey Configuration Examples¶

Basic Questionnaire Configuration:

survey:
  id: "550e8400-e29b-41d4-a716-446655440000"
  title: "社区生活满意度调查"
  description: "了解您对社区生活的看法和建议"
  pages:
    - name: "基本信息"
      elements:
        - name: "age_group"
          title: "您的年龄段是？"
          type: "radiogroup"
          choices: ["18-25岁", "26-35岁", "36-45岁", "46-60岁", "60岁以上"]
        - name: "satisfaction"
          title: "请为社区整体满意度评分"
          type: "rating"
          min_rating: 1
          max_rating: 10

Complex Questionnaire Configuration:

survey:
  id: "550e8400-e29b-41d4-a716-446655440001"
  title: "工作与生活平衡调查"
  description: "了解您的工作生活状态"
  pages:
    - name: "工作状况"
      elements:
        - name: "work_from_home"
          title: "您是否支持远程办公？"
          type: "radiogroup"
          choices: ["是", "否"]
        - name: "work_benefits"
          title: "您希望公司提供哪些福利？"
          type: "checkbox"
          choices: ["健康保险", "弹性工作时间", "年假", "培训机会", "健身房"]
        - name: "feedback"
          title: "请分享您对工作的看法"
          type: "text"

Using Questionnaires in Workflow:

exp:
  name: "满意度调查实验"
  workflow:
    - type: run
      days: 1
      ticks_per_step: 3600
    - type: survey
      target_agent:
        agent_class: ["SocietyAgent"]
        filter_str: "${profile.age} >= 18"
      survey:
        id: "550e8400-e29b-41d4-a716-446655440000"
        title: "社区生活满意度调查"
        description: "了解您对社区生活的看法和建议"
        pages:
          - name: "满意度评价"
            elements:
              - name: "overall_satisfaction"
                title: "您对社区生活的整体满意度如何？"
                type: "rating"
                min_rating: 1
                max_rating: 5
              - name: "improvement_areas"
                title: "您认为社区最需要改进的方面有哪些？"
                type: "checkbox"
                choices: ["交通便利性", "环境卫生", "安全状况", "商业配套", "社区活动"]

Configuration Example¶

Basic Experiment Configuration:

This configuration demonstrates a simple simulation experiment, including the following elements:

Experiment name: basic_simulation
Workflow: Contains only one run step, lasting 3 days, with actions executed every 5 minutes
Environment settings: Start at 8:00 AM (28800 seconds), set weather to sunny, temperature to 25°C, and specify as a workday

exp:
  name: basic_simulation
  workflow:
    - type: run
      days: 3
      ticks_per_step: 300
  environment:
    start_tick: 28800
    weather: "晴天"
    temperature: "温度25°C"
    workday: true

Complex Experiment with Interventions:

This configuration demonstrates a complex experiment that includes multiple intervention operations:

Experiment name: intervention_study
Workflow contains 4 steps:
1. Run 1 day of simulation (initial phase)
2. 环境干预：将天气改为“下雨”
3. Conduct questionnaire survey on specified agents (IDs 1-5)
4. Continue running 1 day of simulation (observation phase)
Environment settings: Start at 7:00 AM (25200 seconds), collect metrics every 30 minutes (1800 seconds)

exp:
  name: intervention_study
  workflow:
    - type: run
      days: 1
      ticks_per_step: 300
    - type: environment
      key: weather
      value: "下雨"
    - type: survey
      target_agent: [1, 2, 3, 4, 5]
      survey:
        id: "550e8400-e29b-41d4-a716-446655440002"
        title: "天气影响调查"
        description: "了解天气变化对日常生活的影响"
        pages:
          - name: "出行影响"
            elements:
              - name: "travel_impact"
                title: "天气变化如何影响您的出行计划？"
                type: "text"
    - type: run
      days: 1
      ticks_per_step: 300
  environment:
    start_tick: 25200
    metric_interval: 1800

Agent Filtering Configuration:

exp:
  name: targeted_intervention
  workflow:
    - type: run
      days: 1
      ticks_per_step: 600
    - type: interview
      target_agent:
        agent_class: ["SocietyAgent"]
        filter_str: "${profile.age} > 30"
      interview_message: "请描述您对当前经济状况的看法"
  environment:
    start_tick: 28800