World.py

This module includes the World class and methods to create it.

A `World' object holds and handles all the information about the world necessary to run a simulation. It also includes methods for creating the World class, and populating the world.

Classes:

Name	Description
World	a world class class.

Functions:

Name	Description
generate_world_from_geography	Creates an instance of the World class, given a Geography.
_populate_areas	Optimized population area creation with lightweight visualization sampling.

World

This Class creates the world that will later be simulated.

Source code in june/world.py

class World:
    """This Class creates the world that will later be simulated."""

    def __init__(self):
        """Initialises an empty world.

        """
        from june.mpi_wrapper import MovablePeople

        self.areas = None
        self.super_areas = None
        self.regions = None
        self.people = None
        self.households = None
        self.care_homes = None
        self.student_dorms = None
        self.schools = None
        self.companies = None
        self.hospitals = None
        self.pubs = None
        self.groceries = None
        self.cinemas = None
        self.cemeteries = None
        self.universities = None
        self.airports = None
        self.aircrafts = None
        self.cities = None
        self.stations = None
        self.private_rooms = None
        self.friendships = None  # Add a FriendshipDistributor attribute
        self.movable_people = MovablePeople()  # Initialise MovablePeople


    def __iter__(self):
        ret = []
        for attr_name, attr_value in self.__dict__.items():
            if isinstance(attr_value, Supergroup):
                ret.append(attr_value)
        return iter(ret)

    def distribute_people(self, include_households=True):
        """Distributes people to buildings, using configurations and settings.

        Args:
            include_households (bool): (Default value = True)

        """


        # Handle households
        if include_households:
            household_distributor = HouseholdDistributor()
            result = household_distributor.distribute_people_to_households(self.areas)

            # Save households to world
            self.households = result['households']  # This is a Households object

            for household in self.households:
                if hasattr(household, 'area') and household.area is not None:
                    household.area.households.append(household)

            # Keep unallocated people for care homes and student dorms
            self.unallocated_people = result['unallocated_people']

            ''' unallocated_people structure: a dict of lists
            {
                'area_id': {
                    'kids': {'m': [Person, Person, ...], 'f': [Person, ...]},
                    'young_adults': {'m': [...], 'f': [...]},
                    'adults': {'m': [...], 'f': [...]},
                    'old_adults': {'m': [...], 'f': [...]}
                }
            }

            '''

        #Handle care homes
        if self.care_homes is not None:
            try:
                carehome_distr = CareHomeDistributor()
                care_home_result = carehome_distr.distribute_unallocated_people(self.care_homes, self.unallocated_people)

                # Update unallocated_people with the remaining people after care home distribution
                if isinstance(care_home_result, dict) and 'unallocated_people' in care_home_result:
                    self.unallocated_people = care_home_result['unallocated_people']

            except Exception as e:
                logger.warning(f"Error populating care homes: {e}")

        #TODO triangulate boarding school communal residences with actual boarding school data
        if self.boarding_schools is not None:
            try:
                boarding_school_distr = BoardingSchoolDistributor.from_file()
                boarding_school_result = boarding_school_distr.distribute_unallocated_people(self.boarding_schools, self.unallocated_people)

                # Update unallocated_people with the remaining people after student dorm distribution
                if isinstance(boarding_school_result, dict) and 'unallocated_people' in boarding_school_result:
                    self.unallocated_people = boarding_school_result['unallocated_people']

            except Exception as e:
                logger.warning(f"Error populating boarding schools: {e}")

        # Handle student dorms
        if self.student_dorms is not None:
            try:
                student_dorm_distr = StudentDormDistributor.from_file()
                student_dorm_result = student_dorm_distr.distribute_unallocated_people(self.student_dorms, self.unallocated_people)

                # Update unallocated_people with the remaining people after student dorm distribution
                if isinstance(student_dorm_result, dict) and 'unallocated_people' in student_dorm_result:
                    self.unallocated_people = student_dorm_result['unallocated_people']

            except Exception as e:
                logger.warning(f"Error populating student dorms: {e}")



        # Allocate remaining people to households that originally had expandable compositions
        if include_households and self.households is not None and self.unallocated_people:
            try:
                # Count households before allocation
                households_before = len(self.households)

                self.unallocated_people = household_distributor.allocate_all_remaining_people_to_expandable_households(
                    self.households, self.unallocated_people
                )

                # Count households after allocation
                households_after = len(self.households) 
                new_households = households_after - households_before

                if new_households > 0:
                    # Assign any NEW households to their areas (the original ones were already assigned)
                    assigned_count = 0
                    for household in self.households[households_before:]:  # Only check the new households
                        if hasattr(household, 'area') and household.area is not None:
                            household.area.households.append(household)
                            assigned_count += 1

                # Generate composition comparison summary per area
                """ household_distributor.stats_reporter.generate_composition_comparison_summary(
                    self.households, self.areas
                ) """

                """ # Generate detailed household listing for specific area
                household_distributor.stats_reporter.generate_detailed_household_listing(
                    self.households, "E00105050"
                ) """
            except Exception as e:
                logger.warning(f"Error allocating remaining people to expandable households: {e}")

        #CLAUDE! remove unassigned people from world goes here!
        self._remove_unassigned_people()

        # Handle ethnicity assignment to all residents
        try:
            logger.info("Assigning ethnicities...")
            ethnicity_distributor = EthnicityDistributor()
            ethnicity_distributor.assign_ethnicities_to_all_residents(self)
            logger.info("Ethnicity assignment completed for all residents")
        except Exception as e:
            logger.warning(f"Error assigning ethnicities: {e}")


        # Handle comorbidity assignment to all residents
        try:
            logger.info("Assigning comorbidities...")
            comorbidity_distributor = ComorbidityDistributor()
            comorbidity_distributor.assign_comorbidities_to_all_residents(self)
            logger.info("Comorbidity assignment completed for all residents")
        except Exception as e:
            logger.warning(f"Error assigning comorbidities: {e}")



        # Handle schools
        if self.schools is not None:
            try:
                school_distributor = SchoolDistributor(self.schools)
                school_distributor.distribute_kids_to_school(self.areas)
                school_distributor.limit_classroom_sizes()
                school_distributor.distribute_teachers_to_schools_in_super_areas(
                    self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing schools: {e}")

        # Handle universities
        if self.universities is not None:
            try:
                uni_distributor = UniversityDistributor(self.universities)
                uni_distributor.distribute_students_to_universities(
                    areas=self.areas, people=self.people
                )
            except Exception as e:
                logger.warning(f"Error distributing universities: {e}")


        # Distribute workers if any relevant groups exist
        if (
            self.companies is not None
            or self.hospitals is not None
            or self.schools is not None
            or self.care_homes is not None
        ):

            try:
                worker_distr = WorkerDistributorNew.for_super_areas(
                    area_names=[super_area.name for super_area in self.super_areas],
                    config_file = (
                        paths.configs_path / "defaults/distributors/worker_distributor.yaml"
                    ),
                    policy_config_file = (
                        paths.configs_path / "defaults/policy/company_closure.yaml"
                    ))
                worker_distr.distribute(
                    areas=self.areas, super_areas=self.super_areas, population=self.people
                )
            except Exception as e:
                import traceback
                logger.error(f"Error during worker distribution: {e}")
                logger.error(f"Full traceback:\n{traceback.format_exc()}")
                raise e 




        # Distribute care home workers
        if self.care_homes is not None:
            try:
                carehome_distr.distribute_workers_to_care_homes(
                    super_areas=self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing care home workers: {e}")

        if self.hospitals is not None:
            try:
                hospital_distributor = HospitalDistributor.from_file(
                    self.hospitals
                )
                hospital_distributor.distribute_medics_to_super_areas(
                    self.super_areas
                )
                hospital_distributor.assign_closest_hospitals_to_super_areas(
                    self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing hospitals: {e}")

        # Handle companies
        if self.companies is not None:
            try:
                company_distributor = CompanyDistributor()
                company_distributor.distribute_adults_to_companies_in_super_areas(
                    self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing companies: {e}")

        #self._summarize_18_year_olds()

    def _summarize_18_year_olds(self):
        """Generate comprehensive summary of all 18-year-old people in the world"""
        import pandas as pd

        logger.info("=== SUMMARIZING ALL 18-YEAR-OLDS ===")

        eighteen_year_olds = []
        couple_household_details = []

        # Collect all 18-year-olds from the world
        for person in self.people:

            if person.age == 18:
                # Determine residence type and details
                residence_type = "Unknown"
                residence_details = "Unknown"
                household_type = None
                household = None

                # Check different possible residential locations
                if hasattr(person, 'residence') and person.residence:
                    if hasattr(person.residence, 'group'):
                        # Person's residence points to a subgroup, get the actual group
                        residence = person.residence.group
                        residence_type = residence.__class__.__name__

                        if residence_type == "Household":
                            household = residence
                            household_type = getattr(residence, 'type', 'Unknown')
                            residence_details = f"Household ({household_type})"
                        elif residence_type == "CareHome":
                            residence_details = f"Care Home (ID: {getattr(residence, 'id', 'Unknown')})"
                        elif residence_type == "StudentDorm":
                            residence_details = f"Student Dorm (ID: {getattr(residence, 'id', 'Unknown')})"
                        elif residence_type == "BoardingSchool":
                            residence_details = f"Boarding School (ID: {getattr(residence, 'id', 'Unknown')})"
                        else:
                            residence_details = residence_type
                    else:
                        # Direct residence assignment
                        residence = person.residence
                        residence_type = residence.__class__.__name__
                        residence_details = residence_type

                # If this 18-year-old lives in a couple household, collect household member details
                if household_type == "couple" and household:
                    household_members = []
                    for resident in household.residents:
                        household_members.append({
                            'Person_ID': resident.id,
                            'Age': resident.age,
                            'Sex': resident.sex
                        })

                    couple_household_details.append({
                        'EighteenYearOld_ID': person.id,
                        'EighteenYearOld_Sex': person.sex,
                        'Household_ID': getattr(household, 'id', 'Unknown'),
                        'Total_Residents': len(household.residents),
                        'Household_Members': household_members,
                        'All_Ages': [r.age for r in household.residents],
                        'All_Sexes': [r.sex for r in household.residents]
                    })

                # Get primary activity details
                primary_activity = getattr(person, 'primary_activity', None)
                primary_activity_type = "None"
                primary_activity_details = "None"

                if primary_activity:
                    if hasattr(primary_activity, '__class__'):
                        primary_activity_type = primary_activity.__class__.__name__
                        if hasattr(primary_activity, 'id'):
                            primary_activity_details = f"{primary_activity_type} (ID: {primary_activity.id})"
                        else:
                            primary_activity_details = primary_activity_type

                # Get work sector if applicable
                work_sector = getattr(person, 'sector', None)
                work_sub_sector = getattr(person, 'sub_sector', None)

                # Get area information
                area_name = "Unknown"
                if hasattr(person, 'area') and person.area:
                    area_name = getattr(person.area, 'name', 'Unknown')

                eighteen_year_olds.append({
                    'Person_ID': person.id,
                    'Sex': person.sex,
                    'Area': area_name,
                    'Residence_Type': residence_type,
                    'Residence_Details': residence_details,
                    'Household_Type': household_type,
                    'Primary_Activity_Type': primary_activity_type,
                    'Primary_Activity_Details': primary_activity_details,
                    'Work_Sector': work_sector,
                    'Work_Sub_Sector': work_sub_sector,
                    'Lockdown_Status': getattr(person, 'lockdown_status', None)
                })

        # Convert to DataFrame for analysis
        df = pd.DataFrame(eighteen_year_olds)

        logger.info(f"Found {len(eighteen_year_olds)} people aged 18")

        if len(eighteen_year_olds) > 0:
            # Summary by residence type
            print("\n=== 18-YEAR-OLDS BY RESIDENCE TYPE ===")
            residence_summary = df.groupby(['Residence_Type', 'Household_Type']).size().reset_index(name='Count')
            print(residence_summary.to_string(index=False))

            # Detailed analysis of 18-year-olds in couple households
            if couple_household_details:
                print(f"\n=== DETAILED ANALYSIS OF {len(couple_household_details)} 18-YEAR-OLDS IN COUPLE HOUSEHOLDS ===")

                for detail in couple_household_details:
                    print(f"\n18-year-old {detail['EighteenYearOld_ID']} ({detail['EighteenYearOld_Sex']}) lives in household {detail['Household_ID']} with {detail['Total_Residents']} residents:")
                    print(f"  Ages of all residents: {detail['All_Ages']}")
                    print(f"  Sexes of all residents: {detail['All_Sexes']}")
                    print("  Individual residents:")
                    for member in detail['Household_Members']:
                        print(f"    - Person {member['Person_ID']}: Age {member['Age']}, Sex {member['Sex']}")

            # Summary by primary activity
            print("\n=== 18-YEAR-OLDS BY PRIMARY ACTIVITY ===")
            activity_summary = df.groupby('Primary_Activity_Type').size().reset_index(name='Count')
            print(activity_summary.to_string(index=False))

            # Summary by work sector
            print("\n=== 18-YEAR-OLDS BY WORK SECTOR ===")
            sector_summary = df.groupby(['Work_Sector', 'Work_Sub_Sector']).size().reset_index(name='Count')
            print(sector_summary.to_string(index=False))

            # Sample of detailed records
            print("\n=== SAMPLE OF 18-YEAR-OLDS (First 10) ===")
            sample_df = df.head(10)[['Person_ID', 'Sex', 'Residence_Details', 'Primary_Activity_Details', 'Work_Sector']]
            print(sample_df.to_string(index=False))

            # Export to CSV for detailed analysis
            csv_filename = "18_year_olds_summary.csv"
            df.to_csv(csv_filename, index=False)
            logger.info(f"Detailed 18-year-olds data exported to {csv_filename}")

        logger.info("=== END 18-YEAR-OLDS SUMMARY ===")

    def _remove_unassigned_people(self):
        """Remove people who still have residence = None after all distribution rounds.
        Optimized for large populations (60M+ people).

        """
        if not self.people or not self.people.people:
            logger.info("No people to check for unassigned residents")
            return

        logger.info(f"Checking {len(self.people.people)} people for unassigned residents...")

        # Use list comprehension for faster filtering - single pass through population
        original_people = self.people.people
        assigned_people = []
        unassigned_people = []

        # Single pass: separate assigned from unassigned
        for person in original_people:
            if hasattr(person, 'residence') and person.residence is not None:
                assigned_people.append(person)
            else:
                unassigned_people.append(person)

        unassigned_count = len(unassigned_people)
        if unassigned_count == 0:
            logger.info("No unassigned people found - all people have been assigned to a residence")
            return

        logger.info(f"Found {unassigned_count} unassigned people to remove")

        # Replace world population list in one operation (much faster than individual removes)
        self.people.people = assigned_people

        # Group unassigned people by area for efficient area-level removal
        people_by_area = {}
        for person in unassigned_people:
            if hasattr(person, 'area') and person.area:
                area = person.area
                if area not in people_by_area:
                    people_by_area[area] = []
                people_by_area[area].append(person)

        # Remove from areas in batches
        removed_from_areas = 0
        for area, area_unassigned in people_by_area.items():
            if hasattr(area, 'people') and area.people:
                # Convert to set for O(1) lookup, then filter in one pass
                unassigned_set = set(area_unassigned)
                area.people = [p for p in area.people if p not in unassigned_set]
                removed_from_areas += len(area_unassigned)

        # Basic statistics (minimal processing for performance)
        logger.info(f"Removed {unassigned_count} unassigned people from world population")
        logger.info(f"Removed {removed_from_areas} people from their areas")
        logger.info(f"Population reduced from {len(original_people)} to {len(assigned_people)}")

        # Optional detailed statistics (only if needed for debugging)
        if logger.isEnabledFor(logging.DEBUG):
            self._collect_and_display_removal_stats_fast(unassigned_people)

        # Clear unallocated_people
        if hasattr(self, 'unallocated_people') and self.unallocated_people:
            self.unallocated_people = {}

    def _collect_and_display_removal_stats_fast(self, unassigned_people):
        """Fast statistics collection for debug mode only.

        Args:
            unassigned_people: 

        """
        if not unassigned_people:
            return

        # Use numpy for fast calculations if available, otherwise use basic counts
        try:
            import numpy as np
            ages = np.array([p.age for p in unassigned_people])
            logger.debug(f"Unassigned people age stats: mean={np.mean(ages):.1f}, "
                        f"median={np.median(ages):.1f}, range={ages.min()}-{ages.max()}")
        except ImportError:
            pass

        # Basic counts
        kids = sum(1 for p in unassigned_people if p.age <= 17)
        adults = len(unassigned_people) - kids
        males = sum(1 for p in unassigned_people if p.sex == 'm')

        logger.debug(f"Unassigned breakdown: {kids} kids, {adults} adults, "
                    f"{males} males, {len(unassigned_people)-males} females")

        """
        # Handle hospitals
        if self.hospitals is not None:
            try:
                hospital_distributor = HospitalDistributor.from_file(
                    self.hospitals
                )
                hospital_distributor.distribute_medics_to_super_areas(
                    self.super_areas
                )
                hospital_distributor.assign_closest_hospitals_to_super_areas(
                    self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing hospitals: {e}")

        # Handle companies
        if self.companies is not None:
            try:
                company_distributor = CompanyDistributor()
                company_distributor.distribute_adults_to_companies_in_super_areas(
                    self.super_areas
                )
            except Exception as e:
                logger.warning(f"Error distributing companies: {e}")

        # Handle friendships and relationships
        if self.people and len(self.people.people) > 0:
            try:
                friendship_distributor = FriendshipDistributor(
                    people=self.people.people)


                friendship_distributor.link_all_friends(
                    super_areas=self.super_areas,
                )

                sexual_relationship_distributor = SexualRelationshipDistributor(
                    people=self.people.people,
                    random_seed=12345  # Use a fixed seed for reproducibility
                    )

                sexual_relationship_distributor.distribute_sexual_relationships(super_areas=self.super_areas)

                # Collect private rooms from relationship distributors and create PrivateRooms supergroup
                self._collect_private_rooms_from_distributors(sexual_relationship_distributor)
            except Exception as e:
                logger.warning(f"Error distributing friendships or relationships: {e}") """



    def _collect_private_rooms_from_distributors(self, sexual_relationship_distributor):
        """Collect private rooms from relationship distributors and create PrivateRooms supergroup.

        Args:
            sexual_relationship_distributor: The sexual relationship distributor that created private rooms

        """
        from june.groups import PrivateRooms

        all_private_rooms = []

        # Collect from sexual relationship distributor
        if hasattr(sexual_relationship_distributor, 'created_private_rooms'):
            all_private_rooms.extend(sexual_relationship_distributor.created_private_rooms)
            logger.info(f"Collected {len(sexual_relationship_distributor.created_private_rooms)} private rooms from sexual relationship distributor")

        # TODO: Collect from household distributor if needed
        # This would require modifying the household distribution to also track created private rooms

        if all_private_rooms:
            # Create PrivateRooms supergroup
            self.private_rooms = PrivateRooms(all_private_rooms)
            logger.info(f"Created PrivateRooms supergroup with {len(all_private_rooms)} private rooms")
        else:
            logger.info("No private rooms created")
            self.private_rooms = None





    def to_hdf5(self, file_path: str, chunk_size=100000):
        """Saves the world to an hdf5 file. All supergroups and geography
        are stored as groups. Class instances are substituted by ids of the
        instances. To load the world back, one needs to call the
        generate_world_from_hdf5 function.

        Args:
            file_path (str): path of the hdf5 file
            chunk_size:
                How many units of supergroups to process at a time.
                It is advise to keep it around 1e5 (Default value = 100000)

        """
        from june.hdf5_savers import save_world_to_hdf5

        save_world_to_hdf5(world=self, file_path=file_path, chunk_size=chunk_size)

__init__()

Initialises an empty world.

Source code in june/world.py

def __init__(self):
    """Initialises an empty world.

    """
    from june.mpi_wrapper import MovablePeople

    self.areas = None
    self.super_areas = None
    self.regions = None
    self.people = None
    self.households = None
    self.care_homes = None
    self.student_dorms = None
    self.schools = None
    self.companies = None
    self.hospitals = None
    self.pubs = None
    self.groceries = None
    self.cinemas = None
    self.cemeteries = None
    self.universities = None
    self.airports = None
    self.aircrafts = None
    self.cities = None
    self.stations = None
    self.private_rooms = None
    self.friendships = None  # Add a FriendshipDistributor attribute
    self.movable_people = MovablePeople()  # Initialise MovablePeople

distribute_people(include_households=True)

Distributes people to buildings, using configurations and settings.

Parameters:

Name	Type	Description	Default
include_households	bool	(Default value = True)	True

Source code in june/world.py

def distribute_people(self, include_households=True):
    """Distributes people to buildings, using configurations and settings.

    Args:
        include_households (bool): (Default value = True)

    """


    # Handle households
    if include_households:
        household_distributor = HouseholdDistributor()
        result = household_distributor.distribute_people_to_households(self.areas)

        # Save households to world
        self.households = result['households']  # This is a Households object

        for household in self.households:
            if hasattr(household, 'area') and household.area is not None:
                household.area.households.append(household)

        # Keep unallocated people for care homes and student dorms
        self.unallocated_people = result['unallocated_people']

        ''' unallocated_people structure: a dict of lists
        {
            'area_id': {
                'kids': {'m': [Person, Person, ...], 'f': [Person, ...]},
                'young_adults': {'m': [...], 'f': [...]},
                'adults': {'m': [...], 'f': [...]},
                'old_adults': {'m': [...], 'f': [...]}
            }
        }

        '''

    #Handle care homes
    if self.care_homes is not None:
        try:
            carehome_distr = CareHomeDistributor()
            care_home_result = carehome_distr.distribute_unallocated_people(self.care_homes, self.unallocated_people)

            # Update unallocated_people with the remaining people after care home distribution
            if isinstance(care_home_result, dict) and 'unallocated_people' in care_home_result:
                self.unallocated_people = care_home_result['unallocated_people']

        except Exception as e:
            logger.warning(f"Error populating care homes: {e}")

    #TODO triangulate boarding school communal residences with actual boarding school data
    if self.boarding_schools is not None:
        try:
            boarding_school_distr = BoardingSchoolDistributor.from_file()
            boarding_school_result = boarding_school_distr.distribute_unallocated_people(self.boarding_schools, self.unallocated_people)

            # Update unallocated_people with the remaining people after student dorm distribution
            if isinstance(boarding_school_result, dict) and 'unallocated_people' in boarding_school_result:
                self.unallocated_people = boarding_school_result['unallocated_people']

        except Exception as e:
            logger.warning(f"Error populating boarding schools: {e}")

    # Handle student dorms
    if self.student_dorms is not None:
        try:
            student_dorm_distr = StudentDormDistributor.from_file()
            student_dorm_result = student_dorm_distr.distribute_unallocated_people(self.student_dorms, self.unallocated_people)

            # Update unallocated_people with the remaining people after student dorm distribution
            if isinstance(student_dorm_result, dict) and 'unallocated_people' in student_dorm_result:
                self.unallocated_people = student_dorm_result['unallocated_people']

        except Exception as e:
            logger.warning(f"Error populating student dorms: {e}")



    # Allocate remaining people to households that originally had expandable compositions
    if include_households and self.households is not None and self.unallocated_people:
        try:
            # Count households before allocation
            households_before = len(self.households)

            self.unallocated_people = household_distributor.allocate_all_remaining_people_to_expandable_households(
                self.households, self.unallocated_people
            )

            # Count households after allocation
            households_after = len(self.households) 
            new_households = households_after - households_before

            if new_households > 0:
                # Assign any NEW households to their areas (the original ones were already assigned)
                assigned_count = 0
                for household in self.households[households_before:]:  # Only check the new households
                    if hasattr(household, 'area') and household.area is not None:
                        household.area.households.append(household)
                        assigned_count += 1

            # Generate composition comparison summary per area
            """ household_distributor.stats_reporter.generate_composition_comparison_summary(
                self.households, self.areas
            ) """

            """ # Generate detailed household listing for specific area
            household_distributor.stats_reporter.generate_detailed_household_listing(
                self.households, "E00105050"
            ) """
        except Exception as e:
            logger.warning(f"Error allocating remaining people to expandable households: {e}")

    #CLAUDE! remove unassigned people from world goes here!
    self._remove_unassigned_people()

    # Handle ethnicity assignment to all residents
    try:
        logger.info("Assigning ethnicities...")
        ethnicity_distributor = EthnicityDistributor()
        ethnicity_distributor.assign_ethnicities_to_all_residents(self)
        logger.info("Ethnicity assignment completed for all residents")
    except Exception as e:
        logger.warning(f"Error assigning ethnicities: {e}")


    # Handle comorbidity assignment to all residents
    try:
        logger.info("Assigning comorbidities...")
        comorbidity_distributor = ComorbidityDistributor()
        comorbidity_distributor.assign_comorbidities_to_all_residents(self)
        logger.info("Comorbidity assignment completed for all residents")
    except Exception as e:
        logger.warning(f"Error assigning comorbidities: {e}")



    # Handle schools
    if self.schools is not None:
        try:
            school_distributor = SchoolDistributor(self.schools)
            school_distributor.distribute_kids_to_school(self.areas)
            school_distributor.limit_classroom_sizes()
            school_distributor.distribute_teachers_to_schools_in_super_areas(
                self.super_areas
            )
        except Exception as e:
            logger.warning(f"Error distributing schools: {e}")

    # Handle universities
    if self.universities is not None:
        try:
            uni_distributor = UniversityDistributor(self.universities)
            uni_distributor.distribute_students_to_universities(
                areas=self.areas, people=self.people
            )
        except Exception as e:
            logger.warning(f"Error distributing universities: {e}")


    # Distribute workers if any relevant groups exist
    if (
        self.companies is not None
        or self.hospitals is not None
        or self.schools is not None
        or self.care_homes is not None
    ):

        try:
            worker_distr = WorkerDistributorNew.for_super_areas(
                area_names=[super_area.name for super_area in self.super_areas],
                config_file = (
                    paths.configs_path / "defaults/distributors/worker_distributor.yaml"
                ),
                policy_config_file = (
                    paths.configs_path / "defaults/policy/company_closure.yaml"
                ))
            worker_distr.distribute(
                areas=self.areas, super_areas=self.super_areas, population=self.people
            )
        except Exception as e:
            import traceback
            logger.error(f"Error during worker distribution: {e}")
            logger.error(f"Full traceback:\n{traceback.format_exc()}")
            raise e 




    # Distribute care home workers
    if self.care_homes is not None:
        try:
            carehome_distr.distribute_workers_to_care_homes(
                super_areas=self.super_areas
            )
        except Exception as e:
            logger.warning(f"Error distributing care home workers: {e}")

    if self.hospitals is not None:
        try:
            hospital_distributor = HospitalDistributor.from_file(
                self.hospitals
            )
            hospital_distributor.distribute_medics_to_super_areas(
                self.super_areas
            )
            hospital_distributor.assign_closest_hospitals_to_super_areas(
                self.super_areas
            )
        except Exception as e:
            logger.warning(f"Error distributing hospitals: {e}")

    # Handle companies
    if self.companies is not None:
        try:
            company_distributor = CompanyDistributor()
            company_distributor.distribute_adults_to_companies_in_super_areas(
                self.super_areas
            )
        except Exception as e:
            logger.warning(f"Error distributing companies: {e}")

to_hdf5(file_path, chunk_size=100000)

Saves the world to an hdf5 file. All supergroups and geography are stored as groups. Class instances are substituted by ids of the instances. To load the world back, one needs to call the generate_world_from_hdf5 function.

Parameters:

Name	Type	Description	Default
file_path	str	path of the hdf5 file	required
chunk_size		How many units of supergroups to process at a time. It is advise to keep it around 1e5 (Default value = 100000)	100000

Source code in june/world.py

def to_hdf5(self, file_path: str, chunk_size=100000):
    """Saves the world to an hdf5 file. All supergroups and geography
    are stored as groups. Class instances are substituted by ids of the
    instances. To load the world back, one needs to call the
    generate_world_from_hdf5 function.

    Args:
        file_path (str): path of the hdf5 file
        chunk_size:
            How many units of supergroups to process at a time.
            It is advise to keep it around 1e5 (Default value = 100000)

    """
    from june.hdf5_savers import save_world_to_hdf5

    save_world_to_hdf5(world=self, file_path=file_path, chunk_size=chunk_size)

generate_world_from_geography(geography, demography=None, include_households=True, ethnicity=True, comorbidity=True)

Initialises the world given a geography.

If not provided, the Demography is calculated with the default settings for that geography.

Parameters:

Name	Type	Description	Default
geography	Geography	Geography	required
demography	Demography	Demography object for all areas in the given geography (Default value = None)	None
include_households	bool	(Default value = True)	True
ethnicity	bool	(Default value = True)	True
comorbidity	bool	(Default value = True)	True

Returns:

Name	Type	Description
world	World	An instance of the World class.

Source code in june/world.py

def generate_world_from_geography(
    geography: Geography,
    demography: Optional[Demography] = None,
    include_households=True,
    ethnicity=True,
    comorbidity=True,
) -> World:
    """Initialises the world given a geography.

    If not provided, the Demography is calculated with the default settings for that geography.

    Args:
        geography (Geography): Geography
        demography (Demography, optional): Demography object for all areas in the given geography (Default value = None)
        include_households (bool, optional): (Default value = True)
        ethnicity (bool, optional): (Default value = True)
        comorbidity (bool, optional): (Default value = True)

    Returns:
        world (World):
            An instance of the World class. 

    """
    from june.groups.travel import Aircrafts

    world = World()
    if demography is None:
        demography = Demography.for_geography(geography)
    world.areas = geography.areas
    world.super_areas = geography.super_areas
    world.regions = geography.regions
    # Use optimized population creation without detailed stats collection for performance
    world.people = _populate_areas(world.areas, demography, enable_detailed_stats=False)


    # Add transfer of airports and aircraft with proper checks
    if hasattr(geography, 'airports') and geography.airports is not None:
        world.airports = geography.airports
        # Initialise aircraft fleet based on airports
        world.aircrafts = Aircrafts.from_airports(world.airports)
        logger.info(f"Added {len(geography.airports)} airports to world")
        logger.info(f"Created aircraft fleet with {len(world.aircrafts)} aircraft")
    else:
        logger.info("No airports found in geography")
        world.airports = None
        world.aircrafts = None

    # Transfer groups from geography to world
    for possible_group in possible_groups:
        try:
            geography_group = getattr(geography, possible_group)
            if geography_group is not None:
                setattr(world, possible_group, geography_group)
        except AttributeError:
            logger.info(f"No {possible_group} attribute found in geography. This component will be skipped.")

    # Distribute people based on available groups
    world.distribute_people(
        include_households=include_households
    )

    world.cemeteries = Cemeteries()
    return world