Improved Version of RailToolKit/schema by kaat0 · Pull Request #23 · railtoolkit/schema

kaat0 · 2025-02-25T22:37:57Z

Changelog

Major change:

model_fidelity attribute on different levels for Rolling Stock

Added

running path:
- added description attribute (see Issue Running Path Schema - difference between id and uuid #5)
- added track to characteristic sections for grouping track sections
- added groups array to points_of_interest for categorizing points
- added comprehensive test suite with valid and invalid test cases
- added example file with block sections and signals
rolling stock:
- added description attribute to trains and vehicles (see Issue Running Path Schema - difference between id and uuid #5)
- added hydraulic and misc to power_type options
- added non-revenue to vehicle_type options
- added complete schema for simplified_characteristics with required fields and constraints
- added coasting parameter to simplified characteristics
- added emergency_deceleration to simplified characteristics
- added model_fidelity attribute on different levels
- added comprehensive brake model configuration with multiple fidelity levels
- added detailed brake types: eddy_current_brake, electrodynamic_brake, and friction_brake
- added brake timing parameters: reaction_time, response_time, threshold_time
- added new train types: snow_removal, construction, emergency
- added comprehensive documentation for all attributes and model fidelity levels

Changed

running path:
- running path arrays now contain named attributes (see Issue characteristic_sections of Running Path Schema should contain named attributes #4)
- characteristic sections now require at least one of speed, resistance, or track attributes
- measures for points_of_interest can now take three values: "front", "middle", and "rear"
rolling stock:
- changed tractive_effort to require at least 3 unique pairs
- changed rotation_mass description to specify >= 1
- changed train requirements to need either formation or simplified_characteristics
- changed train_type to include comprehensive list of train service types
- changed brake modeling to support multiple fidelity levels
- changed model_fidelity to be required at top level and component levels
- refined train_type categories into passenger, freight, and special groups
- improved documentation with detailed explanations of model fidelity rationale

Removed

running path:
- removed name attribute (see Issue Running Path Schema - difference between id and uuid #5)
- removed UUID attribute (see Issue Running Path Schema - difference between id and uuid #5)
rolling stock:
- removed name attribute from trains and vehicles (see Issue Running Path Schema - difference between id and uuid #5)
- removed UUID attribute from trains and vehicles (see Issue Running Path Schema - difference between id and uuid #5)
- removed diesel from power_type options

cleanup, renamed "name" to "description", removed UUID, updated "power_type" and "vehicle_type"

Update unit descriptions in schema files and documentation

gwehrle

For now, I only reviewed Rolling-Stock.md and Runng-Path.md, because these are the definitions. If we cleared all my annotations, I'll review the other files too.

I really like the running path definition a lot! Great effort. Looks much cleaner and more intuitive.
Also, I think it's pretty cool to have some flexibility in defining rolling stock. I added some comments.

Two more general thoughts that apply to multiple definitions:

"An array of at least one"
Should an empty array be invalid? For example, if you comment out or create a scaffold, the file would be invalid.

"model_fidelity"
Is there an advantage to define the model explicit? For me, it would make perfect sense to have an implicit behavior. With traction it could look like this:

There are two ways to define traction:

Direct values / table

Attributes Necessity Description

rated_power required Rated power of the vehicle (kW).

initial_tractive_force required Initial tractive force (kN).

As list of speed-force pairs

Attributes Necessity Description

speed required Speed at which the brake effort is applied (km/h)

force required Brake force applied at the specified speed (kN)

gwehrle · 2025-08-13T16:05:49Z

doc/Rolling-Stock.md

-| `schema_version`     | required     | Version of the JSON schema. |
+| `schema_version`     | required     | Version of the JSON schema (current version `2024.07`). |
+| `model_fidelity`     | required     | Level of detail for train dynamics modeling. Values: `simplified`, `detailed`. |
 | `trains`             | optional[^1] | An array of [trains](#Attributes-in-trains). |


Why is at least one of trains or vehicles required?
It wouldn't make sense, but I think the file should still be valid.

gwehrle · 2025-08-13T16:09:21Z

doc/Rolling-Stock.md

-| `schema_version`     | required     | Version of the JSON schema. |
+| `schema_version`     | required     | Version of the JSON schema (current version `2024.07`). |
+| `model_fidelity`     | required     | Level of detail for train dynamics modeling. Values: `simplified`, `detailed`. |
 | `trains`             | optional[^1] | An array of [trains](#Attributes-in-trains). |


Maybe it's better to use a more common word instead of array like list?

If you agree to change it: There are several appearances. I'll only comment this one.

addressed in 8a048b5

gwehrle · 2025-08-13T16:16:21Z

doc/Rolling-Stock.md

+### Model Fidelity Rationale
+
+The `model_fidelity` attribute specifies the level of detail for train dynamics modeling:
+
+- `simplified`: Uses basic acceleration and deceleration parameters. Suitable for high-level planning and simple simulations where detailed dynamics are not required. Parameters are defined in `trains.simplified_characteristics`.
+
+- `detailed`: Uses detailed vehicle parameters including physical properties and effort tables. Appropriate for precise simulations where accurate force calculations are needed. Parameters are defined in `vehicles`.
+
+A file may contain data for both fidelity levels, but only values from the selected level will be used in calculations. The attribute `model_fidelity` acts as a switch to select which level of detail to use, ensuring that the appropriate parameters are applied based on the chosen fidelity level.
+
+The `model_fidelity` attribute is not only used at the top level but also plays a crucial role in lower-level objects such as `resistance`, `traction`, and `brakes`. This allows for varying levels of detail in the modeling of these components, ensuring that the appropriate parameters are applied based on the selected fidelity level.
+


I think the paragraph explains very well what the attribute is for.

Personally, however, I consider it to be a mixture of logic and the definition of properties. In my view, it should be the implementation logic of the interpreting program that chooses which model to use for a simulation or similar. I don't think I see model_fidelity as a property of rolling stock.

I do see your point!

gwehrle · 2025-08-13T16:22:29Z

doc/Rolling-Stock.md

+| `id`                         | required     | Identifier of the train. |
+| `description`                | optional     | Description of the train. |
+| `train_type`                 | optional     | Type of train service. See [Train Types](#train-types) below. |
+| `simplified_characteristics` | optional[^2] | Basic motion parameters when using `simplified_characteristics` model fidelity. See [Simplified Characteristics](#simplified-characteristics) below. |


Basic motion parameters when using simplified_characteristics model fidelity

I think you mean simplified?

gwehrle · 2025-08-13T16:27:55Z

doc/Rolling-Stock.md

-| `UUID`               | optional  | The unique identifier for a vehicle. |
-| `vehicle_type`       | required  | Type of vehicle; values: `traction unit`, `freight`, `passenger`, or `multiple unit`. |
+| `id`                 | required  | Identifier of the vehicle |
+| `vehicle_type`       | required  | Type of vehicle; values: `traction unit`, `freight`, `passenger`, `multiple unit`, or `non-revenue` |


vehicle_types should be snake case. Like long_distance and heavy_freight before

i keeped the non-revenue and did not change it to non_revenue

see issue #26

gwehrle · 2025-08-13T16:29:05Z

doc/Rolling-Stock.md

-| `UUID`               | optional  | The unique identifier for a vehicle. |
-| `vehicle_type`       | required  | Type of vehicle; values: `traction unit`, `freight`, `passenger`, or `multiple unit`. |
+| `id`                 | required  | Identifier of the vehicle |
+| `vehicle_type`       | required  | Type of vehicle; values: `traction unit`, `freight`, `passenger`, `multiple unit`, or `non-revenue` |


Why is vehicle_type required while train_type is not?

gwehrle · 2025-08-13T16:34:39Z

doc/Rolling-Stock.md

+
+| Attributes           | Necessity     | Description |
+| -------------------- | ------------- | ----------- |
+| `model_fidelity`     | required      | Type of resistance model; values: `table` or `calculated`. |


Is it fidelity or should it be changed to just model?

doc/Running-Path.md

kaat0 · 2025-08-25T17:59:49Z

"model_fidelity" Is there an advantage to define the model explicit? For me, it would make perfect sense to have an implicit behavior. With traction it could look like this:

There are two ways to define traction:

Direct values / table

Attributes
Necessity
Description

rated_power
required
Rated power of the vehicle (kW).

initial_tractive_force
required
Initial tractive force (kN).

As list of speed-force pairs

Attributes
Necessity
Description

speed
required
Speed at which the brake effort is applied (km/h)

force
required
Brake force applied at the specified speed (kN)

The implicit behaviour is indeed viable for resistance, traction and brakes. However, I still think it makes sense at the top level. I thought of it as a switch between simplified characteristics and detailed calculations, so that a file can contain both. Does this makes sense?

kaat0 added 16 commits January 2, 2025 23:18

updated creditials

78340d3

extended "points_of_interest

a0420cc

new tests + added track attribute to characteristic sections

618d4d1

extended running path example with track schematics

281f3ad

add gitignore

1d4da1c

thinner resistance lines

b764569

cleanup

d68f6ed

cleanup, renamed "name" to "description", removed UUID, updated "power_type" and "vehicle_type"

attributes and description for simplified_characteristics

9759c18

minor changes and fixes

53c50b5

changed "model_fidelity" to enum "simplified", "detailed"

857902a

docs: standardize unit notation and add dimensionless values

a2fe215

Update unit descriptions in schema files and documentation

Updated name and description

d062553

added emergency_deceleration to the simplified use case

387a754

fix section header

a6a9c46

added detailed model for rolling stock

1bc7838

include units as $defs

695e623

kaat0 requested a review from gwehrle February 25, 2025 22:37

kaat0 added 4 commits February 25, 2025 23:45

added missing values for valid file

f4c22a5

fixed running-path tests

da6e18b

updated roadmap

bff4593

updated license

a075307

gwehrle requested changes Aug 13, 2025

View reviewed changes

gwehrle assigned kaat0 Aug 13, 2025

allowed for empty list (see issue #24)

8ec1510

kaat0 mentioned this pull request Aug 25, 2025

Add Type of Value #25

Closed

added data type for attributes (see issue #25)

c9584f4

kaat0 force-pushed the development branch from cb61e2c to c9584f4 Compare August 25, 2025 18:20

making descriptions for arrays for human-friendly

8a048b5

kaat0 mentioned this pull request Aug 25, 2025

vehicle_types should be snake case. Like long_distance and heavy_freight before #26

Closed

kaat0 force-pushed the development branch 2 times, most recently from c858592 to 6074e7c Compare August 25, 2025 18:58

snake_case for vehicle_type (see issue #26)

193df3e

kaat0 force-pushed the development branch from 6074e7c to 193df3e Compare August 25, 2025 19:02

Attributes	Necessity	Description
`rated_power`	required	Rated power of the vehicle (kW).
`initial_tractive_force`	required	Initial tractive force (kN).

Attributes	Necessity	Description
`speed`	required	Speed at which the brake effort is applied (km/h)
`force`	required	Brake force applied at the specified speed (kN)

Conversation

kaat0 commented Feb 25, 2025

Changelog

Major change:

Added

Changed

Removed

Uh oh!

gwehrle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gwehrle Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kaat0 commented Aug 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gwehrle Aug 13, 2025 •

edited

Loading