Utility Functions

def xrsplit(array):
    """
    Split an array to a list of all the components.
    
    Parameters:
    - array: xarray.DataArray - Array to split
    
    Returns:
        list: List of shape 0 xarray.DataArrays with coordinates
    """

def rearrange(data, dims, coords):
    """
    Returns a xarray.DataArray object with the given coords and dims.
    
    Parameters:
    - data: float or xarray.DataArray - Input data to rearrange
    - dims: list - Ordered list of the dimensions
    - coords: dict - Dictionary of dimension names as keys with their values
    
    Returns:
        xarray.DataArray: Rearranged data array
    """

def compute_shape(coords, reshape_len=None, py_name=""):
    """
    Computes the 'shape' of a coords dictionary.
    
    Parameters:
    - coords: dict - Ordered dictionary of dimension names as keys with their values
    - reshape_len: int or None - Number of dimensions of the output shape
    - py_name: str - Name to print if an error is raised
    
    Returns:
        list: Shape of the ordered dictionary or desired table/vector
    """

def load_model_data(root, model_name):
    """
    Used for models split in several files. Loads subscripts and modules dictionaries.
    
    Parameters:
    - root: pathlib.Path - Path to the model file
    - model_name: str - Name of the model without file type extension
    
    Returns:
        tuple: (subscripts dict, modules dict)
    """

def load_modules(module_name, module_content, work_dir, submodules):
    """
    Used to load model modules from the main model file when split_views=True.
    
    Parameters:
    - module_name: str - Name of the module to load
    - module_content: dict or list - Content of the module
    - work_dir: pathlib.Path - Path to the module file
    - submodules: list - List updated at every recursive iteration
    
    Returns:
        str: String representations of modules/submodules to execute
    """

def load_outputs(file_name, transpose=False, columns=None, encoding=None):
    """
    Load outputs file from CSV or tab-delimited format.
    
    Parameters:
    - file_name: str or pathlib.Path - Output file to read (must be .csv or .tab)
    - transpose: bool - If True reads transposed outputs file (default False)
    - columns: list or None - List of column names to load (default None for all)
    - encoding: str or None - Encoding type to read file (default None)
    
    Returns:
        pandas.DataFrame: DataFrame with the output values
    """

def get_return_elements(return_columns, namespace):
    """
    Takes a list of return elements formatted in Vensim's format Varname[Sub1, Sub2]
    and returns model elements and their addresses.
    
    Parameters:
    - return_columns: list - List of return column strings
    - namespace: dict - Model namespace dictionary
    
    Returns:
        tuple: (capture_elements list, return_addresses dict)
    """

def get_key_and_value_by_insensitive_key_or_value(key, dict):
    """
    Search for key or value in dictionary ignoring case sensitivity.
    
    Parameters:
    - key: str - Key or value to look for in the dictionary
    - dict: dict - Dictionary to search in
    
    Returns:
        tuple: (real_key, real_value) or (None, None) if not found
    """

def get_current_computer_time():
    """
    Returns the current machine time. Needed to mock machine time in tests.
    
    Returns:
        datetime.datetime: Current machine time
    """

def detect_encoding(filename):
    """
    Detects the encoding of a file.
    
    Parameters:
    - filename: str - Name of the file to detect encoding
    
    Returns:
        str: The encoding of the file
    """

def print_objects_format(object_set, text):
    """
    Return a printable version of variables in object_set with the header text.
    
    Parameters:
    - object_set: set - Set of objects to format
    - text: str - Header text
    
    Returns:
        str: Formatted string representation
    """

class Dependencies:
    """
    Representation of variables dependencies.
    
    Attributes:
    - c_vars: set - Set of all selected model variables
    - d_deps: dict - Dictionary of dependencies needed to run vars and modules
    - s_deps: set - Set of stateful objects to update when integrating
    """

class ProgressBar:
    """
    Progress bar for integration.
    
    Methods:
    - __init__(max_value=None): Initialize progress bar
    - update(): Update progress bar
    - finish(): Finish progress bar
    """

class UniqueDims:
    """
    Helper class to create unique dimension names for data_vars with the same
    dimension name but different coords in xarray Datasets.
    
    Methods:
    - __init__(original_dim_name): Initialize with original dimension name
    - name_new_dim(dim_name, coords): Returns new or existing dimension name
    - is_new(coords): Checks if coords is already in unique_dims list
    """

from pysd import utils
import xarray as xr

# Split an array into components
data = xr.DataArray([1, 2, 3], dims=['x'], coords={'x': ['a', 'b', 'c']})
components = utils.xrsplit(data)

# Rearrange data with new dimensions
dims = ['time', 'variable']
coords = {'time': [0, 1, 2], 'variable': ['x', 'y']}
reshaped = utils.rearrange(data, dims, coords)

# Compute shape of coordinates
shape = utils.compute_shape(coords)

# Load CSV output file
outputs = utils.load_outputs('model_results.csv')

# Load specific columns with custom encoding
selected_outputs = utils.load_outputs(
    'results.csv', 
    columns=['Time', 'Population', 'Birth Rate'],
    encoding='utf-8'
)

# Load transposed output file
transposed = utils.load_outputs('results.tab', transpose=True)

# Utility type definitions
Dependencies = dataclass  # With c_vars, d_deps, s_deps attributes
ProgressBar = class      # Progress monitoring utility
UniqueDims = class       # Dimension name management utility