Have deckEntrances on Deck and drop DeckEntranceCouple
Robin Thomas
Context:
We created our first DeckPlan example based on real world data of a Talent 3 train. One thing I struggled with was modelling entrances. Currently each entrance/door between rooms has to be modeled twice. Once for each room (DeckSpace) and an additional DeckEntranceCouple that describes that these entrances are actually the same. (as an example look at the door to the toilet from the official train example) At the end I found myself creating an all-encompassing DeckSpace which acts as a parent for all "real" DeckSpaces with the sole purpose of holding all the doors of the carriage. This works and is permitted by the schema, but it feels like a workaround. Also every parent introduces another level of complexity.
Rational:
I already brought this to the table in
Nick JS
last DeckPlan presentation, but I still believe that having deckEntrances on the Deck makes sense as they are a foundational part of the graph model similar to deckSpaces, deckpathJunctions, deckNavigation and deckPathLinks. Especially for external and communicating entrances it feels more plausible to model them as part of the Deck itself as I would consider them similar to the StopPlaceEntrance (describing external access to a place). Also when comparing Deck to StopPlace, entrances is the only counterpart that is missing:
Possible modelling options
Let's shortly explore some possible ways to model 2 DeckSpaces A and B that are connected by a DeckEntrance. I'm using a simplified XML Syntax here which omits the closing elements.
Let's shortly explore some possible ways to model 2 DeckSpaces A and B that are connected by a DeckEntrance. I'm using a simplified XML Syntax here which omits the closing elements.
(M1) DeckEntrance defined in both DeckSpaces & relation via DeckEntranceCouple
- This is the way it is currently done in the examples.
- This requires duplicating any DeckEntrance related data as well as an additional DeckEntranceCouple.
- The DeckEntranceCouple can be defined either in DeckSpace A or DeckSpace B.
- This establishes an explicit relation between the entrances of the two DeckSpaces
<DeckPlan>
<decks>
<Deck>
<deckSpaces>
<DeckSpace id="A">
<deckEntrances>
<DeckEntrance id="1">
<!-- duplicated data here -->
<DeckSpace id="B">
<deckEntrances>
<DeckEntrance id="2">
<!-- duplicated data here -->
<deckEntranceCouples>
<DeckEntranceCouple>
<FromDeckEntranceRef ref="1"/>
<ToDeckEntranceRef ref="2"/>
(M2) DeckEntrance defined in DeckSpace A & referenced from DeckSpace B
- This establishes an implicit relation as DeckSpace B references the DeckEntrance defined in A.
- Referencing elements which are defined in sibling elements is odd.
- The DeckEntrance can be defined either in DeckSpace A or DeckSpace B.
<DeckPlan>
<decks>
<Deck>
<deckSpaces>
<DeckSpace id="A">
<deckEntrances>
<DeckEntrance id="1">
<DeckSpace id="B">
<deckEntrances>
<DeckEntranceRef ref="2">
(M3) Reference DeckEntrance from both DeckSpaces
- This is how it is done for stop places (see example) translated to the DeckPlan context.
- This establishes an implicit relation as both DeckSpaces reference the same DeckEntrance.
- This requires adding deckEntrances to Deck.
<DeckPlan>
<decks>
<Deck>
<!-- allow deckEntrances on Deck -->
<deckEntrances>
<DeckEntrance id="1">
<deckSpaces>
<DeckSpace id="A">
<deckEntrances>
<DeckEntranceRef ref="1">
<DeckSpace id="B">
<deckEntrances>
<DeckEntranceRef ref="1">
(M4) Reference both DeckSpaces from DeckEntrance
- This explicitly models the connecting spaces directly on the entrance. An Entrance can only ever connect two rooms so it basically acts like an edge or DeckPathLink.
- This requires adding deckEntrances to Deck.
- This requires adding two new properties: FromDeckSpace and ToDeckSpace to DeckEntrance.
<DeckPlan>
<decks>
<Deck>
<!-- allow deckEntrances on Deck -->
<deckEntrances>
<DeckEntrance>
<!-- allow describing the spaces this DeckEntrance connects -->
<FromDeckSpace>
<DeckSpaceRef ref="A"/>
<ToDeckSpace>
<DeckSpaceRef ref="B"/>
<deckSpaces>
<DeckSpace id="A">
<DeckSpace id="B">
(M5) Relate DeckEntrance and DeckSpace via DeckPathLink
- This explicitly models the relation between DeckEntrance and DeckSpace via DeckPathLink.
- This requires adding deckEntrances to Deck.
<DeckPlan>
<decks>
<Deck>
<!-- allow deckEntrances on Deck -->
<deckEntrances>
<DeckEntrance id="1">
<deckSpaces>
<DeckSpace id="A">
<DeckSpace id="B">
<deckPathLinks>
<DeckPathLink>
<FromOnboardSpace>
<DeckEntranceRef ref="1"/>
<ToOnboardSpace>
<DeckSpaceRef ref="A"/>
<DeckPathLink>
<FromOnboardSpace>
<DeckEntranceRef ref="1"/>
<ToOnboardSpace>
<DeckSpaceRef ref="B"/>
Proposal:
- Add deckEntrances from DeckSpace also to Deck so a DeckEntrance can be defined outside of a DeckSpace
- This would also allow to model only the external entrances of a vehicle without having to create any DeckSpace
- Model the relation between DeckEntrance and DeckSpace in the same manner as it is done for StopPlace/Site:
- Reference DeckEntrance from DeckSpace (M3)
- Relate DeckEntrance and DeckSpace via DeckPathLink (M5)
- Drop DeckEntranceCouple
Why dropping DeckEntranceCouple
As far as I know nothing like DeckEntranceCouple exists for StopPlace/Site. For StopPlaces the solutions proposed above have proven to be sufficient (in fact that is why I'm proposing to reuse them). The only thing were (M3) doesn't make sense is when coupling train carriages, as each carriage has its own entrance which is then connected to the other. I assume DeckEntranceCouple was created for this purpose in the first place. The only use case of the entrance coupling I can think of is some sort of routing. I believe this use case can sufficiently be covered by linking the communicating DeckEntrances via a DeckPathLink. The coupling could theoretically even be deduced based on the ForwardCoupling in the TrainComponents.
Example for linking two communicating entrances via DeckPathLink:
<!-- first carriage -->
<DeckPlan>
<decks>
<Deck>
<deckEntrances>
<DeckEntrance id="1">
<deckPathLinks>
<DeckPathLink>
<FromOnboardSpace>
<DeckEntranceRef ref="1"/>
<ToOnboardSpace>
<DeckEntranceRef ref="2"/>
<!-- second carriage -->
<DeckPlan>
<decks>
<Deck>
<deckEntrances>
<DeckEntrance id="2">
<deckPathLinks>
<DeckPathLink>
<FromOnboardSpace>
<DeckEntranceRef ref="2"/>
<ToOnboardSpace>
<DeckEntranceRef ref="1"/>
The thinking behind the current model as follows:
You are correct - the DECK ENTRANCE COUPLE was intended in particular to allow one to indicate how the entrances of two different DECKs (e.g. wagons) are connected. For example the two doors between the ends of two different contiguous carriages in a train may or may not be connected. The flexibility is also relevant for describing other modular or reconfigurable spaces, such as on boats (as opposed to more static SITES)
The DECK ENTRANCEs so connected may belong to DECK SPACEs in different DECKs and one doesnt otherwise know that they are linked. This fundamental connectivity exists in a given deck configuration, regardless of any paths that have been declared or computed.
It is more modular (and conveys more information) to have each DECK ENTRANCE owned at the the most specific DECK SPACE it belongs to, rather than the whole DECK. Thus, for example, if one adds or removes a compartment, one automatically adds or removes its entrance. The same DECK ENTRANCE can be coupled from a space other than its parent so one should not have to duplicate definitions of DECK ENTRANCES themselves
In the case where a DECK SPACE with a DECK ENTRANCE is nested within another DECK SPACE (as say in your example of a toilet in a carriage) , I agree it is verbose to have to declare a DECK ENTRANCE COUPLE as well as a DECK ENTRANCE as one can automatically assume that in most cases the entrance of the child space opens onto the parent space (only if it opens onto is a further nested grandchild SPACE will it not) . Perhaps what we are lacking is a semantic rule that states any door to a child DECK SPACE is assumed to be implicitly coupled to the parent DECK SPACE onto which it opens (so does not need to be explicitly declared with a DECK ENTRANCE COUPLE).
We are trying to separate concerns of internal layout (DECK SPACES) from those of the container (DECK). So one should in any case always have a parent DECK SPACE to represent the whole space of the wagon, bus deck, or boat deck - thus placing the ENTRANCES on the DECK doesnt simplify or help. If you prefer to declare all ENTRANCEs at the parent DECK SPACE level rather than the child level that works too, but it is better practice to declare just the external entrances at the top level and to declare other entrances on the nested space (eg compartment, toilet, seating are, etc) that they lead to . (In effect we do this for sites....)
PATH LINKS are intend to be a separate layer indicating the paths that may be taken through the a site or vehicle , not to express the structural connectivity of the DECK SPACES (A separate concern) . computed dynamically from the structure or declared explicitly and may have intermediate points (DECK PATH JUNCTIONs) so are not necessarily just simple coupling links Overloading them to necessarily represent teh structure seems to mix concerns?
This works only to a certain point. It is not possible to describe the coupling of 2 carriages that use the same DECK PLAN (i.a. carriages of the same type). So currently deckEntranceCouples only works if either I model an entire TRAIN with one DECK PLAN or if each carriage has its own DECK PLAN.
Can you please elaborate on this? What would be an example for deckEntranceCouples?
This could be modelled by defining the DECK ENTRANCE in DECK SPACE of DECK A (by convention it could always be the lower Deck) and be referenced via DECK ENTRANCE REF from DECK SPACE of DECK B. I find it a little odd to reference something defined in another DECK/DECK SPACE but deckEntranceCouples don't solve this issue.
Your argument could also be applied to DECK SPACEs that span multiple DECKs like staircases. Yet there is no deckSPACECouples.
I agree with the part that it is nice to define the DECK ENTRANCE directly where it belongs to. However the problem is that it always belongs to 2 (ignoring special cases) DECK SPACEs. I would also be okay if we say we define it once in one of the DECK SPACEs and the other one must reference it.
I don't believe that this is true. Lets consider removal (though the same applies for addition): I have to do more work since I have to remove the DECK ENTRANCE COUPLE from the other DECK SPACE as well (and potentially the DECK ENTRANCE as well). If the DECK ENTRANCE were defined just once then removing it would only involve removing either its reference or its definition and references (depending on what I want).
I don't understand this. Coupling always requires 2 doors. Following the current examples an aisle with compartments requires duplicating the DECK ENTRANCEs.
Consider 3 DECK SPACEs "Aisle" and 2 "Compartments" connected by DECK ENTRANCEs marked as "X":
For each "X" 2 DECK ENTRANCEs (one for each DECK SPACE) + 1 DECK ENTRANCE COUPLE have to be modelled. That is what I mean by "duplication".
I'm not sure if I favour this implicit rule. It doesn't seem obvious to me so I would stick to being explicit.
This has never been done in the examples. ParentDeckSpaceRef is only used once to depict that a luggage bay is part of a bigger DECK SPACE.
Even though it looks nice to separate things into DECKs, sometimes I wish DECKs would not have been introduced at all. It slightly overlaps with the concept of DECK LEVELs, it is vaguely defined (unclear when to create a new DECK vs DECK SPACE) and only seems to add syntactic sugar (at least in the XSD it is only defined as being a container of DECK SPACEs). As far as I know this concept of decks doesn't exist on SITEs. Still I'm not necessarily advocating to remove DECKs but rather treat them like a proper container meaning it should contain DECK ENTRANCEs as well.
Regarding the sites: I wasn't able to find something like this in the NeTEx examples. How are the spaces/entrances linked together in this case? Does e.g. the toilet declare the ENTRANCE and the other space that the toilet is connected to references the ENTRANCE declared for the toilet?
I agree.