SCHISM Hotstart Configuration#

Overview#

The SCHISM hotstart system provides a unified way to generate initial condition files (hotstart.nc) for SCHISM simulations. The hotstart functionality is logically integrated with the boundary conditions system, allowing you to generate initial conditions from the same ocean data sources you’re already using for boundary forcing.

A hotstart file contains initial values for temperature, salinity, and other model variables at every grid point and vertical level, allowing SCHISM to begin with realistic ocean conditions rather than starting from rest or uniform values.

Key Features#

  • Integrated Configuration - Hotstart generation is configured alongside boundary conditions

  • Data Source Reuse - Automatically uses temperature and salinity sources from boundary conditions

  • No Duplication - Eliminates the need to specify ocean data sources twice

  • Optional Generation - Completely optional feature that doesn’t interfere with existing workflows

  • Flexible Variables - Configurable variable names to match different ocean model outputs

Architecture#

The hotstart functionality is implemented through:

  • HotstartConfig - Configuration class for hotstart parameters

  • Integration with SCHISMDataBoundaryConditions - Hotstart configured alongside boundaries

  • Automatic data source detection - Finds temperature and salinity sources from boundary configurations

  • SCHISMDataHotstart backend - Handles the actual file generation and interpolation

HotstartConfig Class#

The HotstartConfig class defines all parameters needed for hotstart file generation:

class rompy.schism.data.HotstartConfig(*, enabled: bool = False, temp_var: str = 'temperature', salt_var: str = 'salinity', time_offset: float = 0.0, time_base: datetime = datetime.datetime(2000, 1, 1, 0, 0), output_filename: str = 'hotstart.nc')[source]#

Bases: RompyBaseModel

Configuration for generating SCHISM hotstart files.

This class specifies parameters for creating hotstart.nc files from temperature and salinity data sources already configured in boundary conditions.

field enabled: bool = False#

Whether to generate hotstart file

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'protected_namespaces': ()}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field output_filename: str = 'hotstart.nc'#

Name of the output hotstart file

field salt_var: str = 'salinity'#

Name of salinity variable in source dataset

field temp_var: str = 'temperature'#

Name of temperature variable in source dataset

field time_base: datetime = datetime.datetime(2000, 1, 1, 0, 0)#

Base time for source time values

field time_offset: float = 0.0#

Offset to add to source time values (in days)

Configuration Parameters#

Usage Examples#

Basic Configuration#

The simplest way to enable hotstart generation is to add a hotstart_config section to your boundary conditions:

data:
  boundary_conditions:
    setup_type: "hybrid"
    hotstart_config:
      enabled: true
    boundaries:
      0:
        elev_type: 5  # TIDALSPACETIME
        vel_type: 4   # SPACETIME
        temp_type: 4  # SPACETIME
        salt_type: 4  # SPACETIME
        temp_source:
          data_type: boundary
          source:
            model_type: file
            uri: ocean_data.nc
          variables: [temperature]
          coords:
            t: time
            x: lon
            y: lat
            z: depth
        salt_source:
          data_type: boundary
          source:
            model_type: file
            uri: ocean_data.nc
          variables: [salinity]
          coords:
            t: time
            x: lon
            y: lat
            z: depth

Custom Variable Names#

If your ocean data uses different variable names, you can specify them:

hotstart_config:
  enabled: true
  temp_var: "water_temp"
  salt_var: "sal"
  output_filename: "initial_conditions.nc"

Custom Time Configuration#

For datasets with specific time reference systems:

hotstart_config:
  enabled: true
  time_base: "1990-01-01"
  time_offset: 0.5  # Add 0.5 days to source times

Python API Usage#

You can also configure hotstart generation programmatically:

from rompy.schism.data import SCHISMDataBoundaryConditions, HotstartConfig
from rompy.schism.boundary_conditions import create_hybrid_boundary_config

# Create hotstart configuration
hotstart_config = HotstartConfig(
    enabled=True,
    temp_var="temperature",
    salt_var="salinity",
    output_filename="hotstart.nc"
)

# Create boundary conditions with hotstart
boundary_conditions = create_hybrid_boundary_config(
    tidal_data=tidal_dataset,
    ocean_source=ocean_source,
    hotstart_config=hotstart_config
)

# Generate files (including hotstart if enabled)
result = boundary_conditions.get(destdir, grid, time_range)

# Check if hotstart was generated
if "hotstart" in result:
    print(f"Hotstart file created: {result['hotstart']}")

Integration with Factory Functions#

All boundary condition factory functions support hotstart configuration:

from rompy.schism.boundary_conditions import create_hybrid_boundary_config

# Using factory function with hotstart
boundary_config = create_hybrid_boundary_config(
    tidal_constituents=["M2", "S2", "N2"],
    tidal_database="tpxo",
    ocean_source=hycom_source,
    hotstart_config=HotstartConfig(enabled=True)
)

Generated Files#

When hotstart generation is enabled, the boundary conditions system will create:

Standard Boundary Files#

  • bctides.in - Tidal boundary configuration

  • elev2D.th.nc - Elevation boundary data

  • uv3D.th.nc - Velocity boundary data

  • TEM_3D.th.nc - Temperature boundary data

  • SAL_3D.th.nc - Salinity boundary data

Hotstart File#

  • hotstart.nc - Initial conditions file containing:

    • Temperature and salinity at all grid nodes and vertical levels

    • Zero initial velocities and turbulence variables

    • Proper SCHISM NetCDF format with all required variables

File Structure#

The generated hotstart.nc file contains the standard SCHISM hotstart format:

Variable

Description

tr_nd

Node-based tracers (temperature, salinity)

tr_el

Element-based tracers

eta2

Surface elevation

we

Vertical velocity

su2, sv2

Horizontal velocities at sides

q2, xl

Turbulence variables

dfv, dfh

Diffusivity variables

idry

Dry/wet flags

Data Source Requirements#

For hotstart generation to work, your boundary conditions must include:

Required Sources#

  • Temperature source - A boundary data source with temperature variables

  • Salinity source - A boundary data source with salinity variables

The sources can be: * Separate files for temperature and salinity * Same file containing both variables * Any combination that provides both temperature and salinity data

Coordinate Requirements#

  • Time dimension - For selecting the appropriate time slice

  • Horizontal coordinates - Longitude/latitude or x/y for spatial interpolation

  • Vertical coordinate - Depth or sigma levels for vertical interpolation

Example Ocean Data Sources#

HYCOM Global Model:

temp_source:
  source:
    model_type: file
    uri: "hycom_global.nc"
  variables: ["water_temp"]
  coords:
    t: time
    x: lon
    y: lat
    z: depth

ROMS Regional Model:

temp_source:
  source:
    model_type: file
    uri: "roms_output.nc"
  variables: ["temp"]
  coords:
    t: ocean_time
    x: lon_rho
    y: lat_rho
    z: s_rho

Error Handling#

The hotstart system includes comprehensive error checking:

Missing Data Sources#

If hotstart is enabled but temperature or salinity sources are not available:

ValueError: Hotstart generation requires both temperature and salinity sources
to be configured in boundary conditions

Variable Name Mismatches#

If the specified variable names don’t exist in the source data, the system will attempt to find alternative names or report an error with suggestions.

Time Range Issues#

If the requested time is outside the available data range, the system will use the closest available time and issue a warning.

Best Practices#

  1. Use Same Data Sources

    Configure hotstart to use the same ocean model data you’re using for boundary conditions to ensure consistency.

  2. Check Variable Names

    Verify that temp_var and salt_var match the actual variable names in your ocean data files.

  3. Time Alignment

    Ensure your hotstart time aligns with your simulation start time for optimal initial conditions.

  4. Grid Resolution

    Higher resolution ocean data will provide better interpolated initial conditions, especially in coastal areas.

  5. Validation

    Always check the generated hotstart.nc file to ensure reasonable temperature and salinity ranges for your domain.

Troubleshooting#

Common Issues and Solutions#

Hotstart file not generated

Check that enabled: true is set in hotstart_config

Variable not found errors

Verify variable names match your ocean data using temp_var and salt_var parameters

Interpolation warnings

Normal for coastal areas - the system will use nearest neighbor interpolation for missing data

Large file sizes

Hotstart files can be large for high-resolution grids - this is normal

Time coordinate issues

Adjust time_base and time_offset to match your ocean data’s time reference

Migration from Legacy Hotstart#

If you were previously using the standalone SCHISMDataHotstart class:

Old Configuration:

data:
  hotstart:
    source:
      model_type: file
      uri: ocean_data.nc
    temp_var: temperature
    salt_var: salinity
    coords:
      t: time
      x: lon
      y: lat
      z: depth

New Integrated Configuration:

data:
  boundary_conditions:
    hotstart_config:
      enabled: true
      temp_var: temperature
      salt_var: salinity
    boundaries:
      0:
        temp_source:
          source:
            model_type: file
            uri: ocean_data.nc
          variables: [temperature]
          coords:
            t: time
            x: lon
            y: lat
            z: depth
        salt_source:
          source:
            model_type: file
            uri: ocean_data.nc
          variables: [salinity]
          coords:
            t: time
            x: lon
            y: lat
            z: depth

The new approach eliminates data source duplication and creates a more logical configuration structure.

See Also#

  • enhanced_tides - Boundary conditions documentation

  • Core Concepts - Core ROMPY concepts

  • SCHISM Manual - Official SCHISM documentation