grid.GridSpec

grid.GridSpec(
    name,
    output_dir,
    size_m,
    low,
    high,
    steps=None,
    files=dict(),
    variants=dict(),
    time=None,
)

Spatial grid definition plus data file inventory.

Attributes

Name	Type	Description
name	str	Human-readable grid name (e.g., “dev_fine”).
output_dir	Path	Directory where .jshd files live (and grid.yaml is saved).
size_m	int | float	Grid cell size in meters.
low	tuple[float, float]	(latitude, longitude) of the grid’s low corner.
high	tuple[float, float]	(latitude, longitude) of the grid’s high corner.
steps	int | None	Legacy number of simulation timesteps. Use time for grids with time-varying resources.
time	TimeAxis | None	Declared temporal axis for shared time-varying resources.
files	dict[str, dict[str, str]]	Inventory of preprocessed files. Keys are josh external names, values are dicts with "path" (relative to output_dir) and "units".

Methods

Name	Description
describe	Human-readable overview of the grid and its external-data inventory.
file_mappings_for	Resolve file mappings with specific variant values.
from_yaml	Load a GridSpec from a YAML file.
preprocess_csv	Preprocess a CSV point data file using this grid’s geometry.
preprocess_csv_batch	Preprocess a CSV point data file on a remote target using this grid’s geometry.
preprocess_geotiff	Preprocess a GeoTIFF file using this grid’s geometry.
preprocess_geotiff_batch	Preprocess a GeoTIFF file on a remote target using this grid’s geometry.
preprocess_netcdf	Preprocess a NetCDF file using this grid’s geometry.
preprocess_netcdf_batch	Preprocess a NetCDF file on a remote target using this grid’s geometry.
save	Save the GridSpec to a YAML file.
to_summary_dict	Structured overview of the grid for display/inspection.
variant_sweep	Generate a CompoundSweepParameter from variant axes.

describe

grid.GridSpec.describe()

Human-readable overview of the grid and its external-data inventory.

Shows geometry, variant axes, and each external file’s on-disk status — handy for confirming what a preprocessed grid actually provides without writing any code. See :meth:to_summary_dict for the structured form.

file_mappings_for

grid.GridSpec.file_mappings_for(**variant_values)

Resolve file mappings with specific variant values.

Static path files pass through unchanged. template_path files are resolved using the provided values (falling back to defaults for unspecified axes).

Parameters

Name	Type	Description	Default
**variant_values	str	Axis name → value overrides (e.g., scenario="ssp370").	{}

Returns

Name	Type	Description
	dict[str, Path]	Dict mapping josh external names to absolute file Paths.

Raises

Name	Type	Description
	ValueError	If an axis name or value is invalid.

from_yaml

grid.GridSpec.from_yaml(path)

Load a GridSpec from a YAML file.

Parameters

Name	Type	Description	Default
path	str | Path	Path to a grid.yaml file.	required

Returns

Name	Type	Description
	GridSpec	GridSpec with paths resolved relative to the YAML file’s directory.

preprocess_csv

grid.GridSpec.preprocess_csv(
    cli,
    *,
    josh_name,
    data_file,
    variable,
    units,
    timestep,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
)

Preprocess a CSV point data file using this grid’s geometry.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input CSV file.	required
variable	str	Column name to extract.	required
units	str	Data units.	required
timestep	int	Simulation timestep this data maps to.	required
crs	str | None	Coordinate reference system.	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. See :meth:preprocess_geotiff for full semantics and template_path interaction.	False

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

preprocess_csv_batch

grid.GridSpec.preprocess_csv_batch(
    cli,
    *,
    target,
    josh_name,
    data_file,
    variable,
    units,
    timestep,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
    poll_interval=None,
    timeout=None,
)

Preprocess a CSV point data file on a remote target using this grid’s geometry.

Batch-dispatch counterpart of :meth:preprocess_csv; same output path computation and file registration, dispatched via :meth:JoshCLI.preprocess_batch instead of run locally.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
target	str	Target profile name (required).	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input CSV file.	required
variable	str	Column name to extract.	required
units	str	Data units.	required
timestep	int	Simulation timestep this data maps to.	required
crs	str | None	Coordinate reference system.	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. See :meth:preprocess_geotiff for full semantics and template_path interaction.	False
poll_interval	int | None	Polling interval in seconds (optional).	None
timeout	int | None	Maximum seconds to wait for completion (optional).	None

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

preprocess_geotiff

grid.GridSpec.preprocess_geotiff(
    cli,
    *,
    josh_name,
    data_file,
    band,
    units,
    timestep,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
)

Preprocess a GeoTIFF file using this grid’s geometry.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input GeoTIFF.	required
band	int	Band index (0-based).	required
units	str	Data units.	required
timestep	int	Simulation timestep this data maps to.	required
crs	str | None	Coordinate reference system (if not embedded in file).	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. The file is read transparently at simulation time via josh’s MultiFormatExternalGetter, typically 5-20x smaller on geospatial rasters. Incompatible with template_path (raises ValueError) — template_path users should put .jshdz directly into the template string instead. Note: amend=True with compress=True may not be supported by the underlying JAR; the JAR will report any incompatibility at run time.	False

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

preprocess_geotiff_batch

grid.GridSpec.preprocess_geotiff_batch(
    cli,
    *,
    target,
    josh_name,
    data_file,
    band,
    units,
    timestep,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
    poll_interval=None,
    timeout=None,
)

Preprocess a GeoTIFF file on a remote target using this grid’s geometry.

Batch-dispatch counterpart of :meth:preprocess_geotiff; same output path computation, script sizing, and file registration, dispatched via :meth:JoshCLI.preprocess_batch instead of run locally.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
target	str	Target profile name (required).	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input GeoTIFF.	required
band	int	Band index (0-based).	required
units	str	Data units.	required
timestep	int	Simulation timestep this data maps to.	required
crs	str | None	Coordinate reference system (if not embedded in file).	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. See :meth:preprocess_geotiff for full semantics and template_path interaction.	False
poll_interval	int | None	Polling interval in seconds (optional).	None
timeout	int | None	Maximum seconds to wait for completion (optional).	None

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

preprocess_netcdf

grid.GridSpec.preprocess_netcdf(
    cli,
    *,
    josh_name,
    data_file,
    variable,
    units,
    x_coord='lon',
    y_coord='lat',
    time_coord='time',
    timestep=None,
    time_type=None,
    time_start=None,
    time_unit=None,
    time_count=None,
    time_increment=None,
    time_interval=None,
    time_instant=None,
    time=None,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
)

Preprocess a NetCDF file using this grid’s geometry.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input NetCDF file.	required
variable	str	NetCDF variable name to extract.	required
units	str	Data units.	required
x_coord	str	Name of the X/longitude dimension.	'lon'
y_coord	str	Name of the Y/latitude dimension.	'lat'
time_coord	str | None	Name of the time dimension. Set to None for a source with no time dimension (emits --no-time-dim).	'time'
timestep	int | None	Optional specific time slice to extract.	None
time_type	str | None	Temporal axis type: "count" or "ISO".	None
time_start	str | int | float | None	First count coordinate or ISO date.	None
time_unit	str | None	Unit for a count axis.	None
time_count	int | None	Number of declared temporal coordinates.	None
time_increment	int | float | None	Increment between count coordinates.	None
time_interval	str | None	ISO-8601 period between ISO dates.	None
time_instant	str | int | float | None	Single count coordinate or ISO date for one output slice.	None
time	TimeAxis | None	Per-resource temporal-axis override. When omitted, this GridSpec’s time axis supplies omitted temporal options.	None
crs	str | None	Coordinate reference system.	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. See :meth:preprocess_geotiff for full semantics and template_path interaction.	False

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

preprocess_netcdf_batch

grid.GridSpec.preprocess_netcdf_batch(
    cli,
    *,
    target,
    josh_name,
    data_file,
    variable,
    units,
    x_coord='lon',
    y_coord='lat',
    time_coord='time',
    timestep=None,
    time_type=None,
    time_start=None,
    time_unit=None,
    time_count=None,
    time_increment=None,
    time_interval=None,
    time_instant=None,
    time=None,
    crs=None,
    parallel=False,
    amend=False,
    subdirectory=None,
    variant=None,
    compress=False,
    poll_interval=None,
    timeout=None,
)

Preprocess a NetCDF file on a remote target using this grid’s geometry.

Batch-dispatch counterpart of :meth:preprocess_netcdf; same declared temporal axis resolution, stub-script sizing, and file registration, dispatched via :meth:JoshCLI.preprocess_batch instead of run locally.

Parameters

Name	Type	Description	Default
cli	JoshCLI	JoshCLI instance.	required
target	str	Target profile name (required).	required
josh_name	str	Name the josh model uses for this external data.	required
data_file	str | Path	Path to the input NetCDF file.	required
variable	str	NetCDF variable name to extract.	required
units	str	Data units.	required
x_coord	str	Name of the X/longitude dimension.	'lon'
y_coord	str	Name of the Y/latitude dimension.	'lat'
time_coord	str | None	Name of the time dimension. Set to None for a source with no time dimension (emits --no-time-dim).	'time'
timestep	int | None	Optional specific time slice to extract.	None
time_type	str | None	Temporal axis type: "count" or "ISO".	None
time_start	str | int | float | None	First count coordinate or ISO date.	None
time_unit	str | None	Unit for a count axis.	None
time_count	int | None	Number of declared temporal coordinates.	None
time_increment	int | float | None	Increment between count coordinates.	None
time_interval	str | None	ISO-8601 period between ISO dates.	None
time_instant	str | int | float | None	Single count coordinate or ISO date for one output slice.	None
time	TimeAxis | None	Per-resource temporal-axis override. When omitted, this GridSpec’s time axis supplies omitted temporal options.	None
crs	str | None	Coordinate reference system.	None
parallel	bool	Enable parallel processing.	False
amend	bool	Append to existing .jshd file.	False
subdirectory	str | None	Optional subdirectory within output_dir.	None
variant	dict[str, str] | None	Variant values to resolve template_path (e.g., {"scenario": "ssp370"}). When provided, the output path is resolved from the file’s template_path and _register_file() is skipped.	None
compress	bool	If True, write XZ-compressed .jshdz output instead of plain .jshd. See :meth:preprocess_geotiff for full semantics and template_path interaction.	False
poll_interval	int | None	Polling interval in seconds (optional).	None
timeout	int | None	Maximum seconds to wait for completion (optional).	None

Returns

Name	Type	Description
	CLIResult	CLIResult from the preprocessing command.

save

grid.GridSpec.save(path=None)

Save the GridSpec to a YAML file.

Parameters

Name	Type	Description	Default
path	str | Path | None	Output path. Defaults to output_dir / "grid.yaml".	None

Returns

Name	Type	Description
	Path	Path to the written file.

to_summary_dict

grid.GridSpec.to_summary_dict()

Structured overview of the grid for display/inspection.

Captures geometry, variant axes (values + default), and the external-data inventory with each file’s resolved path(s) and whether they exist on disk. Templated files are expanded across the variant values they reference, so you can see exactly which preprocessed .jshd files are available. Pure read-only (only stats files for existence).

Returns

Name	Type	Description
	dict[str, Any]	A JSON-serializable dict (see :meth:describe for a human view).

variant_sweep

grid.GridSpec.variant_sweep(axis=None, *, axes=None, values=None)

Generate a CompoundSweepParameter from variant axes.

Finds all template_path files referencing the given axis/axes, builds one FileSweepParameter per file, and wraps them in a CompoundSweepParameter so all files switch together.

Parameters

Name	Type	Description	Default
axis	str | None	Single axis name (common case).	None
axes	list[str] | None	List of axis names for multi-axis cross-product.	None
values	list[str] | None	Subset of values to sweep (single-axis only).	None

Returns

Name	Type	Description
	CompoundSweepParameter	A CompoundSweepParameter ready for
	CompoundSweepParameter	SweepConfig.compound_parameters.

Raises

Name	Type	Description
	ValueError	If axis/axes are invalid, both provided, or values used with multi-axis.