Logistically related objects search function

[studyobject]

Hello, I find myself thinking that the implementation of a large function for retrieving related logistical objects (in a broad sense) would look really cool in your project.
It would be great to have a function for retrieving associated objects. For example, an inserter looks for the object it picks up from and the object it puts into. Similarly, a pipe looks for a pipe it connects to, and so on.

I'm sure someone has already tried to do something like this before me (based on your library), but I couldn't find anything.

Modifications to the Pipe Visualizer and Belt Visualizer demonstrate how this could work (as an example).

What do you think about this?

[redruin1]

It certainly sounds useful. Getting inserter inputs/outputs can be done using it's direction, but it's rather tedius since there's no "built-in" code for doing so. For pipes you can filter just pipe objects, but say you wanted to get all connected pipes, then that requires a slow manual search on the users part. And if you wanted to search for any connected fluid entities (tanks, refineries, chemical plants, assemblers, etc), that becomes a much more complex problem.

I guess my next questions would be:

1. What exact use cases are you looking for? It'd be nice to have some sense of how far this "factorio-scope" extends. Should there be search functions for connected wire networks, for example? What about logistic network range; should there be a search function to find all entities within the logistic range of a roboport? What about only entities that have logistic conditions set in range of a particular roboport? What about a connected network of roboports? If I did every possible Factorio gameplay relation, that graph might get rather deep and complex. Some "real-world" use-cases would be helpful to inform just how extensive the feature set needs to be in order to be useful.
2. What do you think the API should look like? I want to keep the interface as straight-forward from a user's perspective as possible. If someone wanted to find all fluid network entities connected to a particular pipe, how would they write that in code?

This sounds like a pretty substantial feature request, and might have to end up in version 2.0, but if there's a genuine demand and use for the feature I'd be happy to implement it.

[studyobject]

“What exact use cases are you looking for?”
There are tasks for which such a function is very useful:

1. Search for inserter extracting products from assembling_machine. Need for setting inserter ★
2. Search for pipe connections between drum filling/emptying machines and liquid consumers. Needed to configure the assembling_machine to fill/empty barrels depending on the assembling_machine recipe. ★
3. Search for related assembling_machines in any item transfer system to set the desired number of recipes or build the entire plant. It's just that without the ability to search for related objects, it is not possible to implement something like this.

★ - these are the tasks that I directly encountered

[redruin1]

Been thinking about the API interface for something like this.

# Search for inserter extracting products from assembling machine
blueprint = Blueprint("...") # Target blueprint
# Grab all assembling machines, or a subset if desired
assembling_machines = blueprint.find_entities_filtered(type="assembling-machine")
# Iterate
for assembling_machine in assembling_machines:
    # We have a couple options
    # Grab the outputs from the blueprint itself, passing in the assembling machine as a parameter
    outputs = blueprint.get_output_entities(target=assembling_machine)
    # This is the easiest to do currently with the internal structure, but is the least elegant
    
    # Grab the outputs from the selected object
    outputs = assembling_machine.get_output_entities(type="inserter") # could also be loaders, technically, so we only grab inserters
    # Nicer and clearer, but still a little verbose; we can use the assembling_machines `parent` (iirc) to search the collection it lives in
    
    # Access the outputs like attribute
    outputs = assembling_machine.output_entities
    outputs = list(filter(lambda entity: entity.type == "inserter", outputs))
    # I imagine there would also be a `assembling_machine.input_entities` compliment
    # But should this be a set of cached data updated as necessary, or a disguised function call that searches for neighbours?
    
    # once you have the list of inserters, do whatever
    for inserter in outputs:
        # presumably you want to set it's filter or something
        inserter.set_filter(get_recipe_outputs(assembling_machine.recipe))
        ...

Whatever the API ends up as, theres also another consideration; do we search the blueprint for these associations every time (which could get slow and redundant if we're using this information frequently) or do we store all this information in the blueprint when it's created and keep it up to date (more complex, more resource intensive, and likely may want some way to control exactly what information is stored to mitigate the previous issues).
For example, there's no reason to bloat the Blueprint object with information about inserter inputs and outputs if you don't need them, but if you do need them and use them every second, searching the same space every time could get rather slow and storing the data once at startup could be beneficial.

# Search for pipe connections between barrel emptying and liquid consuming machines

blueprint = Blueprint("...") # Target blueprint
# Grab a fluid-consuming machine
fluid_consumer = blueprint.entities["sulfur_production"] # chemical plant, for example
assert fluid_consumer.recipe == "sulfur"

# We need to first figure out the place where a connected input pipe would be
pipe_location = fluid_consumer.fluid_inputs[0] # 2 possible fluid inputs for a chemical plant, probably spatially ordered

# Alternatively, with more complex recipes it might be more convenient to have a helper function that allows you to search by fluid type
pipe_locations = fluid_consumer.get_fluid_input_locations("petroleum-gas")
# And, because there can be multiple fluid input/output locations, it returns a list which we select from
pipe_location = pipe_locations[0]

# See whats at that position
pipe = blueprint.find_entity_at_position(pipe_location)
# Make sure it's actually a pipe(!)
assert pipe.type == "pipe" or pipe.type == "pipe-to-ground"
# This would be more elegant if you say wanted to search all input locations, and error if there are no valid inputs

# Then we need to graph search the entire pipe network and grab any that have connected fluid boxes 
connected_entities = blueprint.get_connected_fluid_network(pipe)
# or
connected_entities = pipe.get_connected_fluid_network()

# We then probably only want machines of type assembling machine in the network
connected_machines = list(filter(lambda entity: entity.type == "assembling-machine", connected_entities))

# Now, I'm still unsure of exactly what you're trying to do, but it would probably be useful to discern between 
# machines that are connected via output and machines that are connected via input:
fluid_producers = []
for connected_machine in connected_machines:
    # Search for any pipes located at the output locations
    output_pipes = []
    for fluid_output in connected_machine.fluid_outputs:
        pipe = blueprint.find_entity_at_position(fluid_output)
        if pipe and pipe.type == "pipe" or pipe.type == "pipe-to-ground":
            output_pipes.append(pipe)
    
    # Check to see if any of those pipes are connected to the searched pipe network
    for pipe in output_pipes:
        if pipe in connected_entities:
            fluid_producers.append(connected_machine)

# `fluid_producers` now contains all the machines outputting fluid to the system, presumably the ones you want to configure
for fluid_producer in fluid_producers:
    ...

Alternatively it might make sense to add some kind of filter parameter to the get_connected_fluid_network() function instead of writing the latter filter function. I imagine there would also be complimentary get_connected_wire_network() and get_connected_logistic_network() that could also be filtered as well.

Thoughts?

[studyobject]

I think the approach to solving this problem should involve creating a kind of map consisting of a grid similar to Factorio with dynamic state within it, where each cell's parameters will have a link to the influencing source (an object) (though I don't know how to create this link effectively).

I can suggest the following option.
Create a large dictionary with keys representing the coordinates of Factorio world cells, where each coordinate corresponds to several parameters describing the potential interaction of objects affecting that cell.

For example:

title_dict_base =\
    {
        (0, 0): {'collision': "collision with object above cell, link to object",
                 'push_belt': "link to the 'belt' object (belt (0, 1))",
                 'pickup_inserter': "link to the 'inserter' object"},
        (1, 0): {'collision': "collision with object above cell, link to object"},
        (2, 0): {'collision': "collision with object above cell, link to object (electric furnace)",
                 'drop_inserter': "link to the 'inserter' object"},
        (2, 1): {'collision': "collision with object above cell, link to object (electric furnace)"},
        ...
        (4, 1): {'collision': "collision with object above cell, link to object (electric furnace)"},
        (4, 0): {'collision': "collision with object above cell, link to object (electric furnace)",
                 'pickup_inserter': "link to the 'inserter' object"},
        ...
     }

You can also add an interaction parameter - power area, drone station network, liquid supply, or any other factor affecting the cell (simplified).

Modifications to title_dict_base during blueprint editing can be made through another function that rechecks dependent cells. For example, if an inserter was moved up one cell, updating title_dict_base can be achieved by applying the cell update function specific to that object:
get_grid_update_for(blueprint.entities.data[i])

I'm a programming cancer so keep that in mind as you review the content I've made.