Vehicle Database Reorg master issue

[kylecarow]

PR #259

https://github.com/NatLabRockies/fastsim-vehicles

Already existing metadata fields:

• name
• doc
• chassis.drive_type: FWD/RWD/AWD/4WD

Introduce metadata fields:

• min_fastsim_version
  • serde backwards compatibility?
    • default to current version
  • Behavior:
    • version checks dont cause errors, but emit warnings before deserialization errors throw
    • table of scenarios and associated warnings:

Scenario	min_fastsim_version in file	Installed version	Warning emitted?
Normal load	3.1.0	3.1.0	No
File needs a newer patch	3.1.1	3.1.0	Yes — "requires FASTSim >= 3.1.1"
File needs a newer minor	3.2.0	3.1.0	Yes — "requires FASTSim >= 3.2.0"
File needs a newer major	4.0.0	3.1.0	Yes — "requires FASTSim >= 4.0.0"
File is from an older patch	3.1.0	3.1.1	No
File is from an older minor	3.0.0	3.1.0	No
File is from an older major	2.0.0	3.1.0	Yes — "older major version … breaking changes"
Field missing from file	(field absent, defaults to current)	3.1.0	No
Loaded via from_yaml / from_json (string)	any	any	No — only from_file, from_resource, from_url route through from_reader

• make
  • serde backwards compatibility?
    • default to None
• model
  • serde backwards compatibility?
    • default to None
• year: Option<String>
  • converted from a mandatory u32 field
  • serde backwards compatibility?
    • although there are no quotes in previously-serialized vehicles, it deserializes to Option<String> just fine

Fill out preliminary schema structure in github.com/NatLabRockies/fastsim-vehicles

• Doesnt need to be perfect, just do something for development, stabilize later
• a few example vehicles
• port all models over

Convenience functions:

• loading from github.com/NatLabRockies/fastsim-vehicles
  • there is likely old work that we should include here, utilizing SerdeAPI
  • gate in tests with env variable or something, if querying from the internet in CI proves problematic
  • preliminary API

# on Vehicle class:
def from_db(
    cls,
    db_path_or_url: str | None = None,
    schema: int = 1,
    **kwargs: Any,
) -> Self:
    """Load a vehicle from a schema-versioned FASTSim vehicle database.

    Parameters
    ----------
    db_path_or_url : str | None, default None
        Database source selector.

        - ``None``: use the schema-specific default remote database URL.
        - ``"http://..."`` or ``"https://..."``: use remote database loading.
        - any other string: treat as a local filesystem database path.

    schema : int, default 1
        Database schema version used for dispatch. Currently only ``schema=1``
        is supported.

    **kwargs
        Arguments forwarded to the schema-specific loader.

        Valid kwargs for ``schema=1``:
        - ``make`` (str): vehicle make, e.g. ``"Ford"``
        - ``model`` (str): vehicle model, e.g. ``"F-150"``
        - ``year`` (str): vehicle model year, e.g. ``"2022"``
        - ``model_version`` (int): model revision, e.g. ``1``
        - ``fastsim_version`` (int, optional): FASTSim version namespace. Defaults to the installed FASTSim major version (e.g. ``3``).
        - ``skip_init`` (bool, optional): forwarded to Rust loader, defaults to ``False``.

    Returns
    -------
    Vehicle
        Loaded vehicle instance.
    """

• Example usage:

# %%
import fastsim

# %%
# Providing a path to a local database
fastsim.Vehicle.from_db(
    "/Users/kcarow/Repositories/fastsim-vehicles",
    make="ford",
    model="fusion",
    year="2012",
    model_version="v1"
)


# %%
# Can provide `~` etc and it will resolve
fastsim.Vehicle.from_db(
    "~/Repositories/fastsim-vehicles",
    make="ford",
    model="fusion",
    year="2012",
    model_version="v1"
)

# %%
# Loads from https://github.com/NatLabRockies/fastsim-vehicles if nothing provided
fastsim.Vehicle.from_db(
    make="ford",
    model="fusion",
    year="2012",
    model_version="v1"
)

# %%

• the code is extremely future proof if we ever want to change the organizational schema
• searching/querying vehicles in github.com/NatLabRockies/fastsim-vehicles
  • automatically filter out vehicles requiring more recent version of fastsim

Remove cal_and_val

• lower priority, not blocking

[kylecarow]

Schema TODOs:

• ponder thermal/dfco/etc variants in schema
• model version number necessary? could replace on git but maybe thats bad for reproducibility
• accept strings at every level, instead of ints for fastsim major version and model version?
  • if we take model version as a string, we can accept the string "latest"
• make utility for reading with a full supplied path rather than path components