Simplify input files

[mrp089]

Problem

When manually creating and modifying input files, I noticed a couple of things that made the process more difficult than it needed to be:

1. Sometimes we use dictionaries (main input file, vessel, boundary condition, ...), sometimes lists (all vessels, all boundary conditions, ...).
2. Some blocks have a name and an ID (e.g., vessels), making it confusing what to use.
3. Attribute names (name, type, values) are longer than necessary, e.g., vessel_name, bc_name, junction_name (see Unify attribute names? #85)
4. Some blocks differentiate between inlet and outlet even though there is mathematically no difference (e.g., Junction)
5. vessel_length appears in most input files but is not used by the solver

A simplified example:

{
    "boundary_conditions": [
        {
            "bc_name": "BC_Q_LAD",
            "bc_type": "FLOW",
            "bc_values": {"Q": [1.0, 1.0], "t": [0.0, 1.0]}
        },
        {
            "bc_name": "BC_PLV",
            "bc_type": "PRESSURE",
            "bc_values": {"P": [5000.0, 5000.0], "t": [0.0, 1.0]}
        }
    ],
    "vessels": [
        {
            "vessel_id": 0,
            "vessel_name": "Ra",
            "zero_d_element_type": "Resistance",
            "zero_d_element_values": {"R": 1000.0},
            "boundary_conditions": {"inlet": "BC_Q_LAD"}
        },
        {
            "vessel_id": 1,
            "vessel_name": "Ca",
            "zero_d_element_type": "Capacitance",
            "zero_d_element_values": {"C": 0.0001},
            "boundary_conditions": {"outlet": "BC_Pv0"}
        }
    ],
    "junctions": [
        {
            "junction_name": "J0",
            "junction_type": "NORMAL_JUNCTION",
            "inlet_vessels": [0],
            "outlet_vessels": [1]
        }
    ]
}

Solution

Here are some improvements I came up with:

1. Make everything into a dictionary and don't use lists. This makes it easier to modify in Python.
2. Use the name as the dictionary key and drop the ID. Use the name to connect blocks.
3. Unify everything to name, type, values
4. Replace inlet and outlet with connections when it doesn't make a difference
5. Remove vessel_length from all blocks

I'd be happy to discuss other ideas here! I would drop backwards compatibility but provide a Python script that converts from the old to the new input file format.

The simplified example would look like:

{
    "boundary_conditions": {
        "BC_Q_LAD": {
            "type": "FLOW",
            "values": {"Q": [1.0, 1.0], "t": [0.0, 1.0]}
        },
        "BC_PLV": {
            "type": "PRESSURE",
            "values": {"P": [5000.0, 5000.0], "t": [0.0, 1.0]}
        }
    },
    "vessels": {
        "Ra": {
            "type": "Resistance",
            "values": {"R": 1000.0},
            "boundary_conditions": {"inlet": "BC_Q_LAD"}
        },
        "Ca": {
            "type": "Capacitance",
            "values": {"C": 0.0001},
            "boundary_conditions": {"outlet": "BC_Pv0"}
        }
    },
    "junctions": {
        "J0": {
            "type": "NORMAL_JUNCTION",
            "connections": ["Ra", "Ca"]
        }
    }
}

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

[mrp089]

Some more ideas:

1. I noticed that junctions already support using names instead of IDs via the option inlet_blocks instead of inlet_vessels.
2. In addition, it would be nice if we could connect boundary conditions directly with junctions. Currently, we need a dummy vessel (with zero resistance) in between a junction and a BC.
3. To simplify things further, it could also make sense to treat BCs as "normal" blocks that get connected via junctions. Then we could remove the boundary_conditions option from all blocks (but would introduce more junctions overall). Mathematically, this should be equivalent but offer more flexibility and be more consistent.
4. Introduce a main category normal_junctions, since this is the most common connection to avoid specifying NORMAL_JUNCTIONS every time.

In the above example, this would be:

{
    "boundary_conditions": {
        "BC_Q_LAD": {
            "type": "FLOW",
            "values": {"Q": [1.0, 1.0], "t": [0.0, 1.0]}
        },
        "BC_PLV": {
            "type": "PRESSURE",
            "values": {"P": [5000.0, 5000.0], "t": [0.0, 1.0]}
        }
    },
    "vessels": {
        "Ra": {
            "type": "Resistance",
            "values": {"R": 1000.0}
        },
        "Ca": {
            "type": "Capacitance",
            "values": {"C": 0.0001}
        }
    },
    "normal_junctions": {
        "Jin": ["BC_Q_LAD", "Ra"],
        "J0": ["Ra", "Ca"],
        "Jout": ["Ca", "BC_Pv0"]
    }
}