The Component Configuration Parser

The ComponentConfigurationParser is responsible for taking a list or hierarchical LayeredConfigTree of components derived from a model specification yaml file and turning it into a list of instantiated component objects. When a model specification yaml file is loaded, the components come in as strings. In order for the simulation to be able to use these components, they have to be converted into the actual objects they represent. This occurs via the get_components method of the parser, which is used anytime a simulation is initialized from a model specification file.

There are three steps to this process.

Parsing the model specification’s components
Validating the arguments and prepping each component
Importing and instantiating the actual components

exception vivarium.framework.components.parser.ParsingError[source]: Error raised when component configurations are not specified correctly.

class vivarium.framework.components.parser.ComponentConfigurationParser[source]

Parses component configuration from model specification and initializes components.

To define your own set of parsing rules, you should write a parser class that inherits from this class and overrides parse_component_config. You can then define a set of parsing rules that turn component configuration information into a string which is the full python import path to the class followed by a set of parentheses containing initialization arguments.

For example, say your component configuration specifies FancyClass from the important_module of your made_up_package and that FancyClass has two initialization parameters, 'important_thing1' and 'important_thing2'. Your implementation of parse_component_config needs to generate the string 'made_up_package.important_module.FancyClass ("important_thing1", "important_thing2")' and include it in the list of components to generate.

All classes that are initialized from the yaml configuration must either take no arguments or take arguments specified as strings.

get_components(component_config)[source]

Extracts component specifications from configuration information and returns initialized components.

This method encapsulates the three steps described above of parsing, validating/prepping, and importing/instantiating.

The first step of parsing is only done for component configurations that come in as a LayeredConfigTree. Configurations that are provided in the form of a list are already assumed to be in the correct form.

Return type:: list[Component]
Parameters:: component_config (LayeredConfigTree | list[str]) – A hierarchical component specification blob. This configuration information needs to be parsable into a full import path and a set of initialization arguments by the parse_component_config method.
Returns:: A list of initialized components.

parse_component_config(component_config)[source]

Helper function for parsing a LayeredConfigTree into a flat list of Components.

This function converts the LayeredConfigTree into a dictionary and passes it along with an empty prefix list to process_level. The result is a flat list of components.

Return type:: list[Component]
Parameters:: component_config (LayeredConfigTree) – A LayeredConfigTree representing a hierarchical component specification blob.
Returns:: A flat list of Components

process_level(level, prefix)[source]

Helper function for parsing hierarchical component configuration into a flat list of Components.

This function recursively walks the hierarchical component configuration, treating it like a prefix tree and building the import path prefix. When it hits a string, it prepends the built prefix onto the string. If the dictionary contains multiple lists, the prefix-prepended lists are combined. For example, a component configuration dictionary like the following:

component_config = {
    'vivarium_examples': {
        'disease_model': {
            'population': ['BasePopulation()', 'Mortality()']
            'disease': ['SIS_DiseaseModel("diarrhea")]
        }
    }
}

would be parsed by this function into the following list:

['vivarium_examples.disease_model.population.BasePopulation()',
 'vivarium_examples.disease_model.population.Mortality()',
 'vivarium_examples.disease_model.disease.SIS_DiseaseModel("diarrhea")']

Return type:

list[Component]

Parameters:

level (str | list[str] | dict[str, str | list[str] | dict[str, str | list[str] | _NestedDict]]) – A level of the hierarchical component specification blob.
prefix (list[str]) – A list of strings representing the import path prefix.

Returns:

A flat list of Components

create_component_from_string(component_string)[source]

Helper function for creating a component from a string.

This function takes a string representing a component and turns it into an instantiated component object.

Return type:: Component
Parameters:: component_string (str) – A string representing the full python import path to the component, the component name, and any arguments.
Returns:: An instantiated component object.

prep_component(component_string)[source]

Transform component description string into a tuple of component paths and required arguments.

Return type:: tuple[str, tuple[str, ...]]
Parameters:: component_string (str) – The component description to transform.
Returns:: Component/argument tuple.

static import_and_instantiate_component(component_path, args)[source]

Transform a tuple representing a Component into an actual instantiated component object.

Return type:

Component

Parameters:

component_path (str) – A string with the full import path to the component and the component name
args (tuple[str, ...]) – A tuple of arguments to the component specified at component_path.

Returns:

An instantiated component object.