gcubed.linearisation.workspace_planning

Deterministic memory planning for state-space-form block operations.

The planner derives a hard workspace ceiling from current system, cgroup, and optional process-limit headroom. A configured cap and an offline host performance profile may reduce that ceiling, but neither can increase it. The safety decision remains active when optional memory profiling is disabled.

WORKSPACE_CAP_GIB_ENV_VAR: str = 'GCUBED_SSF_WORKSPACE_CAP_GIB'

PROCESS_MEMORY_LIMIT_GIB_ENV_VAR: str = 'GCUBED_SSF_PROCESS_MEMORY_LIMIT_GIB'

PERFORMANCE_PROFILE_ENV_VAR: str = 'GCUBED_SSF_PERFORMANCE_PROFILE'

MACHINE_RESERVE_PERCENT: float = 5.0

Share of effective additional memory kept outside SSF workspaces.

MACHINE_RESERVE_FLOOR_BYTES: int = 536870912

Minimum machine reserve used when five percent would be smaller.

BLAS_WORKSPACE_BYTES_PER_THREAD: int = 2097152

Per-thread fallback used when no matching host calibration is loaded.

WORKSPACE_PERFORMANCE_PROFILE_SCHEMA_VERSION: int = 2

Supported local workspace-performance profile schema.

type ProfileValue = bool | float | int | str | None

class InsufficientWorkspaceMemoryError(builtins.MemoryError):

Legacy workspace exception retained for API compatibility.

Valid nonempty operations now attempt at least one column after reporting an estimated shortfall. Invalid planner inputs still raise ValueError.

@dataclass(frozen=True)

class WorkspacePerformancePreference:

One measured operation-shape preference from a local host profile.

Attributes: operation: Stable numerical-operation name. dtype: NumPy dtype string used by the operation. layout: Stable description of relevant array layouts. row_count: Result or right-hand-side row count. inner_dimension: Matrix inner dimension, or LU factor order. calibrated_columns: Full operation width used by calibration. preferred_block_columns: Speed-preferred measured block width. preferred_workspace_bytes: Measured speed-preferred workspace ceiling. source_model_id: Build-197 model supplying the representative shape.

WorkspacePerformancePreference( operation: str, dtype: str, layout: str, row_count: int, inner_dimension: int, calibrated_columns: int, preferred_block_columns: int, preferred_workspace_bytes: int, source_model_id: str)

operation: str

dtype: str

layout: str

row_count: int

inner_dimension: int

calibrated_columns: int

preferred_block_columns: int

preferred_workspace_bytes: int

source_model_id: str

def profile_fields(self) -> dict[str, ProfileValue]:

Return JSON-compatible preference fields.

Args: None.

Returns: Operation key, representative dimensions, preferred workspace, and source model.

Raises: No deliberate exceptions are raised.

@dataclass(frozen=True)

class WorkspacePerformanceProfile:

Versioned host-local operation preferences loaded before model solve.

Attributes: source_path: Profile file used by this process. blas_signature: Stable signature of calibrated BLAS libraries. blas_thread_count: Active BLAS thread count during calibration. blas_workspace_bytes_per_thread: Calibrated fixed BLAS allowance. preferences: Representative operation-shape preferences.

WorkspacePerformanceProfile( source_path: str, blas_signature: str, blas_thread_count: int, blas_workspace_bytes_per_thread: int, preferences: tuple[WorkspacePerformancePreference, ...])

source_path: str

blas_signature: str

blas_thread_count: int

blas_workspace_bytes_per_thread: int

preferences: tuple[WorkspacePerformancePreference, ...]

def preferred_workspace( self, estimate: OperationWorkspaceEstimate, *, total_columns: int) -> tuple[int, str] | None:

Return the nearest validated preference for an operation shape.

Args: estimate: Current operation metadata and workspace estimate. total_columns: Full or remaining operation width.

Returns: Preferred workspace and a reproducible source description, or None when no profile shape is sufficiently close.

Raises: ValueError: Raised when total_columns is not positive.

@dataclass(frozen=True)

class WorkspaceConfiguration:

Memory ceilings used for every state-space-form block operation.

Attributes: workspace_cap_bytes: Optional user upper bound for one block. None selects a completely automatic machine-headroom ceiling. process_memory_limit_bytes: Optional target process RSS ceiling. performance_profile: Optional validated host-local speed preferences.

WorkspaceConfiguration( workspace_cap_bytes: int | None, process_memory_limit_bytes: int | None, performance_profile: WorkspacePerformanceProfile | None = None)

workspace_cap_bytes: int | None

process_memory_limit_bytes: int | None

performance_profile: WorkspacePerformanceProfile | None = None

def blas_workspace_bytes_per_thread(self, *, blas_signature: str, blas_thread_count: int) -> int:

Return matching host-calibrated or fallback BLAS workspace.

Args: blas_signature: Stable signature of active BLAS libraries. blas_thread_count: Active BLAS thread count.

Returns: Bytes reserved per active BLAS thread.

Raises: ValueError: Raised when the signature is empty or thread count is not positive.

def profile_fields(self) -> dict[str, ProfileValue]:

Return JSON-compatible configuration fields for profiling.

Args: None.

Returns: Workspace mode, optional cap/process limit, reserve formula, and local performance-profile identity.

Raises: No deliberate exceptions are raised.

@dataclass(frozen=True)

class MemorySnapshot:

Current process and machine memory values used by the planner.

Attributes: rss_bytes: Current resident set size of this process. peak_rss_bytes: Process high-water resident set size. system_available_bytes: Linux MemAvailable when present. cgroup_available_bytes: Remaining finite cgroup memory allowance. effective_available_bytes: Minimum available value from applicable system and cgroup sources. effective_available_source: Source that limited effective availability.

rss_bytes: int | None

peak_rss_bytes: int | None

system_available_bytes: int | None

cgroup_available_bytes: int | None

effective_available_bytes: int | None

effective_available_source: str | None

def profile_fields(self) -> dict[str, ProfileValue]:

Return JSON-compatible memory snapshot fields.

Args: None.

Returns: Process, system, cgroup, and effective memory values.

Raises: No deliberate exceptions are raised.

@dataclass(frozen=True)

class OperationWorkspaceEstimate:

Fixed and per-column memory estimates for one numerical operation.

Attributes: operation: Stable operation name used in profiler events. fixed_workspace_bytes: Workspace independent of block width. result_bytes_per_column: Newly resident result bytes per column. temporary_output_bytes_per_column: Independently allocated numerical output bytes per column. reusable_output_bytes_per_column: Reusable output-buffer bytes per column. packing_bytes_per_column: Conservative LAPACK or BLAS packing bytes per column. blas_workspace_bytes: Portion of fixed workspace assigned to BLAS. dtype: NumPy result dtype string used for performance-profile matching. layout: Stable relevant-array layout description. row_count: Output or right-hand-side rows for this operation. inner_dimension: Matrix inner dimension, or LU factor order. blas_signature: Stable active-library signature. blas_thread_count: Active BLAS thread count.

OperationWorkspaceEstimate( operation: str, fixed_workspace_bytes: int, result_bytes_per_column: int, temporary_output_bytes_per_column: int, reusable_output_bytes_per_column: int, packing_bytes_per_column: int, blas_workspace_bytes: int = 0, dtype: str = 'unknown', layout: str = 'unknown', row_count: int = 1, inner_dimension: int = 1, blas_signature: str = 'unknown', blas_thread_count: int = 1)

operation: str

fixed_workspace_bytes: int

result_bytes_per_column: int

temporary_output_bytes_per_column: int

reusable_output_bytes_per_column: int

packing_bytes_per_column: int

blas_workspace_bytes: int = 0

dtype: str = 'unknown'

layout: str = 'unknown'

row_count: int = 1

inner_dimension: int = 1

blas_signature: str = 'unknown'

blas_thread_count: int = 1

bytes_per_column: int

Return total estimated workspace for one additional column.

Args: None.

Returns: Sum of result, reusable-output, and packing bytes per column.

Raises: No deliberate exceptions are raised.

@dataclass(frozen=True)

class WorkspaceBudget:

Machine-derived capacity and performance planning ceilings.

Attributes: effective_additional_headroom_bytes: Smallest reliable machine or process-limit capacity above current RSS. effective_additional_headroom_source: Capacity source defining that value. hard_workspace_ceiling_bytes: Smallest raw machine, process, or user workspace limit before planning reserves are subtracted. The legacy hard name identifies the source; an estimated shortfall is now advisory. hard_workspace_ceiling_source: Source defining that raw limit. machine_reserve_bytes: Dynamic memory retained outside model work. conservative_nonworkspace_bytes: Phase demand still expected above current RSS. automatic_hard_ceiling_bytes: Capacity left after reserve and phase demand, before optional user/performance limits. performance_preferred_workspace_bytes: Matching offline preference. performance_preference_source: Profile sample used for the preference. selected_workspace_bytes: Final ceiling used to calculate block width. limiting_constraint: Constraint defining the selected ceiling.

WorkspaceBudget( effective_additional_headroom_bytes: int | None, effective_additional_headroom_source: str | None, hard_workspace_ceiling_bytes: int | None, hard_workspace_ceiling_source: str | None, machine_reserve_bytes: int, conservative_nonworkspace_bytes: int, automatic_hard_ceiling_bytes: int | None, performance_preferred_workspace_bytes: int | None, performance_preference_source: str | None, selected_workspace_bytes: int, limiting_constraint: str)

effective_additional_headroom_bytes: int | None

effective_additional_headroom_source: str | None

hard_workspace_ceiling_bytes: int | None

hard_workspace_ceiling_source: str | None

machine_reserve_bytes: int

conservative_nonworkspace_bytes: int

automatic_hard_ceiling_bytes: int | None

performance_preferred_workspace_bytes: int | None

performance_preference_source: str | None

selected_workspace_bytes: int

limiting_constraint: str

def profile_fields(self) -> dict[str, ProfileValue]:

Return JSON-compatible workspace-budget evidence.

Args: None.

Returns: Capacity, reserve, phase allowance, preference, final ceiling, and limiting source.

Raises: No deliberate exceptions are raised.

@dataclass(frozen=True)

class BlockPlan:

Selected width and evidence for one block operation.

Attributes: estimate: Operation-specific workspace estimate. configuration: Active memory ceilings. memory: Memory values sampled for this decision. budget: Machine-derived workspace budget for this decision. total_columns: Columns remaining in the operation. maximum_columns: Shrink-only width ceiling inherited from the operation. block_columns: Selected number of columns for this block. safe_workspace_bytes: Ordinary policy ceiling before any one-column progress-floor attempt. one_column_workspace_bytes: Estimated bytes needed for minimum progress. minimum_progress_floor_applied: Whether execution borrowed from a planning reserve to select one column. policy_workspace_shortfall_bytes: Bytes by which the ordinary policy ceiling missed the one-column requirement. hard_workspace_shortfall_bytes: Bytes by which measured or configured raw headroom missed one column, or None when raw capacity is unavailable. memory_estimate_exceeded: Whether the selected one-column attempt exceeds an ordinary policy or raw-capacity estimate. estimated_workspace_bytes: Estimated workspace for the selected block. estimated_process_peak_bytes: Current RSS plus estimated workspace. limiting_constraint: Source defining the ordinary policy ceiling. width_limiting_constraint: Reason the selected width cannot be larger.

BlockPlan( estimate: OperationWorkspaceEstimate, configuration: WorkspaceConfiguration, memory: MemorySnapshot, budget: WorkspaceBudget, total_columns: int, maximum_columns: int, block_columns: int, safe_workspace_bytes: int, one_column_workspace_bytes: int, minimum_progress_floor_applied: bool, policy_workspace_shortfall_bytes: int, hard_workspace_shortfall_bytes: int | None, memory_estimate_exceeded: bool, estimated_workspace_bytes: int, estimated_process_peak_bytes: int | None, limiting_constraint: str, width_limiting_constraint: str)

estimate: OperationWorkspaceEstimate

configuration: WorkspaceConfiguration

memory: MemorySnapshot

budget: WorkspaceBudget

total_columns: int

maximum_columns: int

block_columns: int

safe_workspace_bytes: int

one_column_workspace_bytes: int

minimum_progress_floor_applied: bool

policy_workspace_shortfall_bytes: int

hard_workspace_shortfall_bytes: int | None

memory_estimate_exceeded: bool

estimated_workspace_bytes: int

estimated_process_peak_bytes: int | None

limiting_constraint: str

width_limiting_constraint: str

def profile_fields(self) -> dict[str, ProfileValue]:

Return reproducible planner inputs and outputs for profiling.

Args: None.

Returns: Flattened configuration, memory, estimate, and width fields.

Raises: No deliberate exceptions are raised.

def workspace_configuration_from_environment() -> WorkspaceConfiguration:

Return validated state-space-form workspace settings.

Args: None.

Returns: Automatic configuration with optional user upper bounds and a validated local performance profile.

Raises: ValueError: Raised when a configured GiB value is malformed, nonfinite, negative, or zero where a positive value is required.

def blas_library_signature(thread_pools: Sequence[Mapping[str, typing.Any]]) -> str:

Return a stable signature for active BLAS implementations.

Args: thread_pools: Values returned by :func:threadpoolctl.threadpool_info.

Returns: Canonical JSON containing the library implementation, version, architecture, and threading layer for each BLAS pool. Thread counts are excluded because they are stored separately in the profile key.

Raises: TypeError: Raised when a value cannot be JSON serialized.

def load_workspace_performance_profile( path: pathlib.Path) -> WorkspacePerformanceProfile:

Load and validate a versioned local performance profile.

Args: path: JSON profile path produced by the host-calibration command.

Returns: Immutable validated performance profile.

Raises: FileNotFoundError: Raised when path is absent. OSError: Propagated when the file cannot be read. json.JSONDecodeError: Raised when the file is not valid JSON. TypeError: Raised when the JSON root or preferences have invalid types. ValueError: Raised for an unsupported schema or invalid field value. KeyError: Raised when a required field is absent.

def memory_snapshot() -> MemorySnapshot:

Read current process, system, and cgroup memory values.

Args: None.

Returns: Snapshot using the minimum finite system or cgroup availability as the effective available memory.

Raises: No deliberate exceptions are raised. Missing or unreadable Linux files are represented by None fields.

def workspace_budget( configuration: WorkspaceConfiguration, estimate: OperationWorkspaceEstimate, *, total_columns: int, memory: MemorySnapshot, conservative_nonworkspace_bytes: int = 0) -> WorkspaceBudget:

Calculate the hard and speed-preferred workspace ceilings.

Args: configuration: Optional user upper bounds and local performance data. estimate: Current operation metadata used for profile matching. total_columns: Columns remaining in the operation. memory: Current process and machine memory snapshot. conservative_nonworkspace_bytes: Phase memory still expected to be allocated above current RSS.

Returns: Reproducible capacity, reserve, preference, and selected workspace.

Raises: ValueError: Raised for nonpositive columns or negative phase demand.

def dynamic_machine_reserve_bytes(effective_headroom_bytes: int) -> int:

Return the calibrated reserve for current effective headroom.

Args: effective_headroom_bytes: Smallest reliable additional capacity.

Returns: The larger of 512 MiB and five percent of effective headroom, with the percentage result rounded upward to a whole byte.

Raises: ValueError: Raised when headroom is negative.

def plan_block( configuration: WorkspaceConfiguration, estimate: OperationWorkspaceEstimate, *, total_columns: int, maximum_columns: int | None = None, memory: MemorySnapshot | None = None, conservative_nonworkspace_bytes: int = 0) -> BlockPlan:

Select a positive block using active memory estimates.

Args: configuration: Configured workspace, reserve, and process ceilings. estimate: Operation-specific fixed and per-column estimates. total_columns: Columns remaining in the operation. maximum_columns: Optional shrink-only ceiling from an earlier decision. memory: Optional injected memory snapshot, primarily for deterministic tests. Current values are read when omitted. conservative_nonworkspace_bytes: Phase demand still expected above current RSS and therefore unavailable to this operation.

Returns: A block plan containing every input needed to reproduce the decision.

Raises: ValueError: Raised when column counts are not positive. Estimated shortfalls remain visible in the returned plan and select a one-column attempt.