Skip to content

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:

HotstartConfig

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.

Source code in rompy_schism/data.py 
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
class HotstartConfig(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.
    """

    enabled: bool = Field(
        default=False, description="Whether to generate hotstart file"
    )
    temp_var: str = Field(
        default="temperature",
        description="Name of temperature variable in source dataset",
    )
    salt_var: str = Field(
        default="salinity", description="Name of salinity variable in source dataset"
    )
    time_offset: float = Field(
        default=0.0, description="Offset to add to source time values (in days)"
    )
    time_base: datetime = Field(
        default=datetime(2000, 1, 1), description="Base time for source time values"
    )
    output_filename: str = Field(
        default="hotstart.nc", description="Name of the output hotstart file"
    )

Attributes

enabled class-attribute instance-attribute 

enabled: bool = Field(default=False, description='Whether to generate hotstart file')

temp_var class-attribute instance-attribute 

temp_var: str = Field(default='temperature', description='Name of temperature variable in source dataset')

salt_var class-attribute instance-attribute 

salt_var: str = Field(default='salinity', description='Name of salinity variable in source dataset')

time_offset class-attribute instance-attribute 

time_offset: float = Field(default=0.0, description='Offset to add to source time values (in days)')

time_base class-attribute instance-attribute 

time_base: datetime = Field(default=datetime(2000, 1, 1), description='Base time for source time values')

output_filename class-attribute instance-attribute 

output_filename: str = Field(default='hotstart.nc', description='Name of the output hotstart file')

Configuration Parameters

Parameter Default Description
enabled False Whether to generate hotstart file
temp_var "temperature" Name of temperature variable in source dataset
salt_var "salinity" Name of salinity variable in source dataset
time_offset 0.0 Offset to add to source time values (in days)
time_base "2000-01-01" Base time for source time calculations
output_filename "hotstart.nc" Name of the output hotstart file

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.

  1. Check Variable Names

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

  1. Time Alignment

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

  1. Grid Resolution

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

  1. 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