{ "base_url": "https://remilab.ai/rfx", "channel": "development", "package_version": "2.0.0rc1", "schema_version": 1, "source_sha": "2c32b7cf79b796fae825bfa08fc73d9914e61723", "support_contracts": [ "https://remilab.ai/rfx/api/support/support_matrix.json", "https://remilab.ai/rfx/api/support/sparameter_support_matrix.json" ], "support_policy": "Importable does not imply validated. Consult the unchanged support contracts and prose for the chosen configuration; no per-symbol support level is inferred.", "symbols": [ { "docstring": "Bounded compiler-memory certificate for one exact compiled executable.\n\nThe report is derived from a caller-supplied JAX compiled object's\n``memory_analysis()`` result plus complete exact-scope metadata. It is not a\nuniversal peak-memory predictor, runtime profiler artifact, RF validation\nresult, or proof that source/config digests correspond to an opaque\nexecutable.", "kind": "class", "name": "rfx.ADCompiledMemoryCertificate", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "status" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "status_reason" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_memory_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_fraction" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_memory_gb" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "compiler_reported_required_bytes" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "compiler_reported_required_gb" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "temp_size_in_bytes" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "argument_size_in_bytes" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "output_size_in_bytes" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "alias_size_in_bytes" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "temp_gb" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "argument_gb" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "output_gb" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "alias_gb" }, { "annotation": "ForwardRef('Mapping[str, object] | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "exact_scope" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "scope_status" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "scope_status_reason" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "scope_digest" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "config_digest" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "environment_digest" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "memory_analysis_status" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "memory_analysis_status_reason" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "jax_version" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "evidence_boundaries" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendations" }, { "annotation": "ForwardRef('object | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_preflight" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADCompiledMemoryCertificate", "returns": { "annotation": null }, "signature": "(status: ForwardRef('str'), status_reason: ForwardRef('str'), available_memory_gb: ForwardRef('float'), target_fraction: ForwardRef('float'), target_memory_gb: ForwardRef('float'), compiler_reported_required_bytes: ForwardRef('int | None'), compiler_reported_required_gb: ForwardRef('float | None'), temp_size_in_bytes: ForwardRef('int | None'), argument_size_in_bytes: ForwardRef('int | None'), output_size_in_bytes: ForwardRef('int | None'), alias_size_in_bytes: ForwardRef('int | None'), temp_gb: ForwardRef('float | None'), argument_gb: ForwardRef('float | None'), output_gb: ForwardRef('float | None'), alias_gb: ForwardRef('float | None'), exact_scope: ForwardRef('Mapping[str, object] | None'), scope_status: ForwardRef('str'), scope_status_reason: ForwardRef('str'), scope_digest: ForwardRef('str | None'), config_digest: ForwardRef('str | None'), environment_digest: ForwardRef('str | None'), memory_analysis_status: ForwardRef('str'), memory_analysis_status_reason: ForwardRef('str'), jax_version: ForwardRef('str'), evidence_boundaries: ForwardRef('tuple[str, ...]'), recommendations: ForwardRef('tuple[str, ...]'), source_preflight: ForwardRef('object | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L472", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "2D TMz ADI-FDTD state: (Ez, Hx, Hy) on an (Nx, Ny) grid.", "kind": "class", "name": "rfx.ADIState2D", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ez: ForwardRef('jnp.ndarray'), hx: ForwardRef('jnp.ndarray'), hy: ForwardRef('jnp.ndarray'), step: ForwardRef('jnp.ndarray'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L133", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "3D ADI-FDTD state: all 6 field components on (Nx, Ny, Nz) grid.", "kind": "class", "name": "rfx.ADIState3D", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ex" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ey" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hz" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ex: ForwardRef('jnp.ndarray'), ey: ForwardRef('jnp.ndarray'), ez: ForwardRef('jnp.ndarray'), hx: ForwardRef('jnp.ndarray'), hy: ForwardRef('jnp.ndarray'), hz: ForwardRef('jnp.ndarray'), step: ForwardRef('jnp.ndarray'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L844", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Actionable AD-memory preflight hint derived from planning evidence.", "kind": "class", "name": "rfx.ADMemoryActionHint", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "code" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "severity" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "message" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "action" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_mode" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_every" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_segments" }, { "annotation": "ForwardRef('bool')", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "blocking" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADMemoryActionHint", "returns": { "annotation": null }, "signature": "(code: ForwardRef('str'), severity: ForwardRef('str'), message: ForwardRef('str'), action: ForwardRef('str'), checkpoint_mode: ForwardRef('str | None') = None, checkpoint_every: ForwardRef('int | None') = None, checkpoint_segments: ForwardRef('int | None') = None, blocking: ForwardRef('bool') = False)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L193", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Named contribution to a reverse-mode AD memory explanation.", "kind": "class", "name": "rfx.ADMemoryComponent", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "memory_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "share_of_selected" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "kind" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "unit" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "count" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "bytes_per_unit_gb" }, { "annotation": "ForwardRef('str')", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "explanation" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADMemoryComponent", "returns": { "annotation": null }, "signature": "(name: ForwardRef('str'), memory_gb: ForwardRef('float'), share_of_selected: ForwardRef('float'), kind: ForwardRef('str'), unit: ForwardRef('str | None') = None, count: ForwardRef('int | None') = None, bytes_per_unit_gb: ForwardRef('float | None') = None, explanation: ForwardRef('str') = '')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L163", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Static reverse-mode AD memory explainability artifact.\n\nThe report decomposes the selected AD estimate into named components so\nusers can see whether field tape, segment-boundary carries, CPML/material\nstate, or monitor state dominates the planning artifact. It is still static\nplanning evidence, not profiler evidence or a bounded certificate.", "kind": "class", "name": "rfx.ADMemoryExplainabilityReport", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "strategy" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "selected_memory_gb" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "selected_memory_field" }, { "annotation": "ForwardRef('AD_MemoryEstimate')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "estimate" }, { "annotation": "ForwardRef('tuple[ADMemoryComponent, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "components" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dominant_component" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendations" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADMemoryExplainabilityReport", "returns": { "annotation": null }, "signature": "(n_steps: ForwardRef('int'), strategy: ForwardRef('str'), selected_memory_gb: ForwardRef('float'), selected_memory_field: ForwardRef('str'), estimate: ForwardRef('AD_MemoryEstimate'), components: ForwardRef('tuple[ADMemoryComponent, ...]'), dominant_component: ForwardRef('str'), recommendations: ForwardRef('tuple[str, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L232", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Checkpoint planning result for reverse-mode AD memory.\n\n``checkpoint_every`` is the non-uniform segmented-scan chunk length.\n``checkpoint_segments`` is the uniform segmented-scan segment count.\n``checkpoint_mode`` is the knob selector, not a runnable-fit verdict:\ncheck ``full_ad_fits`` first, then require ``segmented_fits`` before wiring\nthe selected segmented knob. A non-fitting plan may still carry the\nleast-memory candidate knob for diagnostics.\n``fit_safety_factor`` records the conservative multiplier used before an\nestimate is allowed to set ``full_ad_fits`` or ``segmented_fits``.\n``evidence_class`` labels this artifact as a calibrated conservative plan,\nnot a certificate or observed runtime profile.", "kind": "class", "name": "rfx.ADMemoryPlan", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_memory_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_fraction" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_memory_gb" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_every" }, { "annotation": "ForwardRef('AD_MemoryEstimate')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "selected_estimate" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "full_ad_fits" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "segmented_fits" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendation" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_segments" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_mode" }, { "annotation": "ForwardRef('float')", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "fit_safety_factor" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADMemoryPlan", "returns": { "annotation": null }, "signature": "(n_steps: ForwardRef('int'), available_memory_gb: ForwardRef('float'), target_fraction: ForwardRef('float'), target_memory_gb: ForwardRef('float'), checkpoint_every: ForwardRef('int | None'), selected_estimate: ForwardRef('AD_MemoryEstimate'), full_ad_fits: ForwardRef('bool'), segmented_fits: ForwardRef('bool'), recommendation: ForwardRef('str'), checkpoint_segments: ForwardRef('int | None') = None, checkpoint_mode: ForwardRef('str | None') = None, fit_safety_factor: ForwardRef('float') = 1.0)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L277", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Composite AD-memory preflight artifact.\n\nThis report composes static memory planning, static explainability,\noptional mesh advisories, and optional trace-time JAX saved-residual\ndiagnostics. It is not runtime profiler evidence, XLA memory analysis,\na peak-memory guarantee, a certificate, or RF validation.", "kind": "class", "name": "rfx.ADMemoryPreflightReport", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_memory_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_fraction" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_memory_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fit_safety_factor" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "status" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "supported_checkpoint_mode" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_every" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_segments" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "full_ad_fits" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpointing_fits" }, { "annotation": "ForwardRef('ADMemoryPlan')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "memory_plan" }, { "annotation": "ForwardRef('ADMemoryExplainabilityReport')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "explainability" }, { "annotation": "ForwardRef('MeshIntelligenceReport | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mesh_report" }, { "annotation": "ForwardRef('object | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "residual_diagnostic" }, { "annotation": "ForwardRef('tuple[ADMemoryActionHint, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "action_hints" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "evidence_boundaries" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendation" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADMemoryPreflightReport", "returns": { "annotation": null }, "signature": "(n_steps: ForwardRef('int'), available_memory_gb: ForwardRef('float'), target_fraction: ForwardRef('float'), target_memory_gb: ForwardRef('float'), fit_safety_factor: ForwardRef('float'), status: ForwardRef('str'), supported_checkpoint_mode: ForwardRef('str | None'), checkpoint_every: ForwardRef('int | None'), checkpoint_segments: ForwardRef('int | None'), full_ad_fits: ForwardRef('bool'), checkpointing_fits: ForwardRef('bool'), memory_plan: ForwardRef('ADMemoryPlan'), explainability: ForwardRef('ADMemoryExplainabilityReport'), mesh_report: ForwardRef('MeshIntelligenceReport | None'), residual_diagnostic: ForwardRef('object | None'), action_hints: ForwardRef('tuple[ADMemoryActionHint, ...]'), evidence_boundaries: ForwardRef('tuple[str, ...]'), recommendation: ForwardRef('str'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L381", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Parser health summary for saved-residual diagnostics.", "kind": "class", "name": "rfx.ADParserHealth", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "record_count" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "known_count" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "unknown_count" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "unknown_fraction" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "warnings" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADParserHealth", "returns": { "annotation": null }, "signature": "(record_count: ForwardRef('int'), known_count: ForwardRef('int'), unknown_count: ForwardRef('int'), unknown_fraction: ForwardRef('float'), warnings: ForwardRef('tuple[str, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L184", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Grouped summary of saved residual records.", "kind": "class", "name": "rfx.ADResidualGroup", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "key" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_kind" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dtype" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "record_count" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "known_count" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "unknown_count" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "known_estimated_bytes" }, { "annotation": "ForwardRef('tuple[int, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "line_indices" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADResidualGroup", "returns": { "annotation": null }, "signature": "(key: ForwardRef('str'), source_kind: ForwardRef('str'), name: ForwardRef('str | None'), dtype: ForwardRef('str | None'), record_count: ForwardRef('int'), known_count: ForwardRef('int'), unknown_count: ForwardRef('int'), known_estimated_bytes: ForwardRef('int'), line_indices: ForwardRef('tuple[int, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L150", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Structured artifact for JAX saved-residual inspection.\n\nThis artifact is produced from ``jax.ad_checkpoint.print_saved_residuals``.\nIt explains what JAX says would be saved for reverse-mode AD under the given\nPython function and sample arguments. It is not a runtime profile, not an\nXLA memory report, and not a peak-memory certificate.", "kind": "class", "name": "rfx.ADResidualInspection", "parameters": [ { "annotation": "ForwardRef('tuple[ADResidualRecord, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "records" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "raw_lines" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "total_estimated_bytes" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "total_estimated_gb" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "unknown_estimate_count" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADResidualInspection", "returns": { "annotation": null }, "signature": "(records: ForwardRef('tuple[ADResidualRecord, ...]'), raw_lines: ForwardRef('tuple[str, ...]'), total_estimated_bytes: ForwardRef('int | None'), total_estimated_gb: ForwardRef('float | None'), unknown_estimate_count: ForwardRef('int'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L111", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One line from JAX saved-residual inspection.\n\n``estimated_bytes`` is derived from the printed abstract value when shape\nand dtype are parseable. It is a static byte count for the residual value,\nnot allocator overhead, fragmentation, or measured peak memory.", "kind": "class", "name": "rfx.ADResidualRecord", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "aval" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dtype" }, { "annotation": "ForwardRef('tuple[int, ...] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "shape" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "size" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "estimated_bytes" }, { "annotation": "ForwardRef('str')", "default": "'unknown'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_kind" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "ForwardRef('str')", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "raw_line" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "line_index" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADResidualRecord", "returns": { "annotation": null }, "signature": "(aval: ForwardRef('str'), source: ForwardRef('str'), dtype: ForwardRef('str | None') = None, shape: ForwardRef('tuple[int, ...] | None') = None, size: ForwardRef('int | None') = None, estimated_bytes: ForwardRef('int | None') = None, source_kind: ForwardRef('str') = 'unknown', name: ForwardRef('str | None') = None, raw_line: ForwardRef('str') = '', line_index: ForwardRef('int | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L73", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "rfx saved-residual diagnostic report.\n\nThe report summarizes JAX saved-residual evidence for one differentiated\ncallable and sample argument set. It is trace-time explainability, not a\nruntime profiler, XLA memory report, peak-memory guarantee, certificate, or\nRF/gradient validation artifact.", "kind": "class", "name": "rfx.ADSavedResidualDiagnosticReport", "parameters": [ { "annotation": "ForwardRef('ADResidualInspection')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inspection" }, { "annotation": "ForwardRef('tuple[ADResidualRecord, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "top_residuals" }, { "annotation": "ForwardRef('tuple[ADResidualGroup, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "groups" }, { "annotation": "ForwardRef('ADParserHealth')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "parser_health" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "known_estimated_bytes" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "known_estimated_gb" }, { "annotation": "ForwardRef('int | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "total_estimated_bytes" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "total_estimated_gb" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "jax_version" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "workflow" }, { "annotation": "ForwardRef('Mapping[str, object] | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "context" }, { "annotation": "ForwardRef('Mapping[str, object]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "artifact_snapshots" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendations" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ADSavedResidualDiagnosticReport", "returns": { "annotation": null }, "signature": "(inspection: ForwardRef('ADResidualInspection'), top_residuals: ForwardRef('tuple[ADResidualRecord, ...]'), groups: ForwardRef('tuple[ADResidualGroup, ...]'), parser_health: ForwardRef('ADParserHealth'), known_estimated_bytes: ForwardRef('int'), known_estimated_gb: ForwardRef('float'), total_estimated_bytes: ForwardRef('int | None'), total_estimated_gb: ForwardRef('float | None'), jax_version: ForwardRef('str'), workflow: ForwardRef('str | None'), context: ForwardRef('Mapping[str, object] | None'), artifact_snapshots: ForwardRef('Mapping[str, object]'), recommendations: ForwardRef('tuple[str, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L204", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Reverse-mode AD memory estimate (issue #30 CHECK 4 / #39).\n\nAll sizes are in gigabytes. ``warning`` is populated when the\nselected estimate exceeds 85% of ``available_gb``.\n\n``ad_checkpointed_gb`` is the legacy ``jax.checkpoint(step_fn)``\nestimate; for FDTD on the non-uniform path this is *not* a\nrealistic memory number because the scan carry itself is not\nrematerialised (see issue #31 VESSL 369367233490). Use\n``ad_segmented_gb`` for the runner-supported segmented paths:\n``checkpoint_every`` on the non-uniform scan-of-scan path and\n``checkpoint_segments`` on the uniform segmented-scan path. The\nsegmented model counts segment-boundary storage (carry + cotangent,\n``2 × active_segments``) PLUS the live-segment rematerialization tape\n(one segment's per-step field tape resident during backward replay,\nissue #277); it is minimized near ``sqrt(2 × n_steps)`` steps per\nsegment. When present,\n``ad_segmented_active_segments`` is the actual number of active segment\nboundaries/carry snapshots used by the segmented estimate after warmup.\n``evidence_class`` labels this artifact as a static estimate so downstream\ntooling does not confuse it with observed profiler evidence or a bounded\ncompiled-executable certificate.", "kind": "class", "name": "rfx.AD_MemoryEstimate", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "forward_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_checkpointed_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_full_gb" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_dft_gb" }, { "annotation": "ForwardRef('float | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_gb" }, { "annotation": "ForwardRef('str | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "warning" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_segmented_gb" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_every" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "checkpoint_segments" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_active_steps" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_segmented_active_segments" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_kind" }, { "annotation": "ForwardRef('str | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_source" }, { "annotation": "ForwardRef('tuple[int, int, int] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_shape" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sheet_gb" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#AD_MemoryEstimate", "returns": { "annotation": null }, "signature": "(forward_gb: ForwardRef('float'), ad_checkpointed_gb: ForwardRef('float'), ad_full_gb: ForwardRef('float'), ntff_dft_gb: ForwardRef('float'), available_gb: ForwardRef('float | None'), warning: ForwardRef('str | None'), ad_segmented_gb: ForwardRef('float | None') = None, checkpoint_every: ForwardRef('int | None') = None, checkpoint_segments: ForwardRef('int | None') = None, ad_active_steps: ForwardRef('int | None') = None, ad_segmented_active_segments: ForwardRef('int | None') = None, grid_kind: ForwardRef('str | None') = None, grid_source: ForwardRef('str | None') = None, grid_shape: ForwardRef('tuple[int, int, int] | None') = None, sheet_gb: ForwardRef('float | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L67", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Paths written by :func:`export_artifact_bundle`.", "kind": "class", "name": "rfx.ArtifactBundle", "parameters": [ { "annotation": "Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "root" }, { "annotation": "Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "report_json" }, { "annotation": "Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "manifest_json" }, { "annotation": "Path | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "report_markdown" }, { "annotation": "Path | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "scene_json" }, { "annotation": "Path | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry_json" }, { "annotation": "Path | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "field_vtk" }, { "annotation": "tuple[Path, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "files" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ArtifactBundle", "returns": { "annotation": "None" }, "signature": "(root: 'Path', report_json: 'Path', manifest_json: 'Path', report_markdown: 'Path | None' = None, scene_json: 'Path | None' = None, geometry_json: 'Path | None' = None, field_vtk: 'Path | None' = None, files: 'tuple[Path, ...]' = ()) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L70", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "str(object='') -> str\nstr(bytes_or_buffer[, encoding[, errors]]) -> str\n\nCreate a new string object from the given object. If encoding or\nerrors is specified, then the object must expose a data buffer\nthat will be decoded using the given encoding and error handler.\nOtherwise, returns the result of object.__str__() (if defined)\nor repr(object).\nencoding defaults to sys.getdefaultencoding().\nerrors defaults to 'strict'.", "kind": "object", "name": "rfx.BATCH_MANIFEST_SCHEMA", "reference_url": null, "source_url": null, "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Impedance bandwidth extraction result.\n\ncenter_freq : float, Hz\nbandwidth_hz : float, Hz\nfractional_bandwidth : float (ratio, e.g. 0.10 = 10 %)\nfreq_lo : float, Hz — lower edge\nfreq_hi : float, Hz — upper edge", "kind": "class", "name": "rfx.BandwidthResult", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "center_freq" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth_hz" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fractional_bandwidth" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_lo" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_hi" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#BandwidthResult", "returns": { "annotation": null }, "signature": "(center_freq: ForwardRef('float'), bandwidth_hz: ForwardRef('float'), fractional_bandwidth: ForwardRef('float'), freq_lo: ForwardRef('float'), freq_hi: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L268", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result record returned by :func:`run_batch_with_manifest`.\n\n``result`` is ``None`` for cases skipped through resume.", "kind": "class", "name": "rfx.BatchCaseResult", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "case_id" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "params" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "status" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "metrics" }, { "annotation": "dict[str, str]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "artifacts" }, { "annotation": "Any", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "error" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "skipped" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#BatchCaseResult", "returns": { "annotation": "None" }, "signature": "(case_id: 'str', params: 'dict[str, Any]', status: 'str', metrics: 'dict[str, Any]', artifacts: 'dict[str, str]', result: 'Any' = None, error: 'str | None' = None, skipped: 'bool' = False) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L22", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Axis-aligned box defined by two corners (meters).\n\n**Rasterization convention (read before drawing a PEC obstacle).**\nOn each axis the volume branch is **half-open** ``[lo, hi)`` over\n**node** coordinates: node ``j`` at ``y_j`` belongs to the box\niff ``lo - tol <= y_j < hi - tol``, with ``tol = NODE_TIE_REL *\nnode_widths[j]`` (#1138), using each node's forward primal cell width\nand repeating the last width at the final node. The convention is\ndeliberate and several paths depend on it (see ``_axis_mask`` for the\nissue history), but it has two consequences when a box is drawn to a\nnominal physical size:\n\n1. **The ``hi`` face contributes no cell.** A box whose corners both\n land on node planes, ``lo = i*dx`` and ``hi = k*dx``, occupies nodes\n ``i .. k-1``. Its realized extent between the first and last occupied\n node plane is therefore ``(hi - lo) - dx``, one cell short of the\n drawn extent, and the shortfall is entirely at the ``hi`` face, so a\n **single box** is also displaced by ``dx/2`` toward ``lo``. Note the\n two faces are NOT interchangeable: ``lo`` is inclusive and ``hi`` is\n exclusive. Whether that per-box displacement survives in a\n multi-object structure depends on which face of each object is the\n load-bearing one — see the facing-pair discussion below, where it\n cancels in one case and not the other.\n\n2. **Float arithmetic within the on-lattice band keeps the face on\n its node.** Concrete coordinates and comparisons remain host\n float64, independent of ``jax_enable_x64`` (#802). A corner drawn\n through ``m*dx``, ``lo + N*dx``, repeated addition or a graded\n cumulative sum can differ from its node by a few ULP. The shared\n ``1e-9``-local-cell band includes that node at ``lo`` and excludes\n it at ``hi`` (#1138), preserving the half-open cell count.\n\n Historical (pre-#802, kept because committed values were pinned to\n it): masks compared float32 coordinates, themselves double-rounded\n ``f32(f32(i) * f32(dx))``, so a WR-90 f64 node reconstruction\n disagreed with production on 30 of 31 nodes by up to 1.1e-9 m and\n the SAME drawing recipe gave ``d + dx`` at one aperture and\n ``d + 2*dx`` at another, unpredictably. That scatter is gone:\n drawing fins to the nominal opening now costs exactly one cell\n (the ``hi``-face retreat), at every aperture.\n\nFor a **PEC obstacle** the occupied nodes are where the tangential ``E``\nis zeroed, so consequence (1) is an *electrical* dimension error, not a\nsub-cell cosmetic one. **Transverse to the propagation direction** — an\naperture width, a guide width, anything that sets a cutoff — the\nelectrical dimension is the span between the innermost ZEROED node\nplanes, ``(n_open + 1) * dx``, the same measure that reproduces the\nguide's own width ``a = cells * dx`` exactly (counting open nodes alone\nwould call WR-90 22.098 mm instead of 22.86 at a/30). An independent\nrefit of 16 committed WR-90 single-iris configurations across two meshes\npins the realized transverse aperture offset to within 1/20 of a cell of\nthat identity (measured during the stage-S3 / issue #499 review; no\ncommitted record carries the refit yet, so like the longitudinal caution\nbelow it is a recorded observation, not a number to build on).\n\n**Do not carry that identity into the propagation direction.** The\nelectrical *thickness* of an obstacle (an iris's extent along the guide\naxis) is not the zeroed-plane span: it is set by how the fields interact\nwith the discontinuity, not by a cutoff condition. Measured on a\nsingle-iris geometry at four drawn thicknesses, the effective thickness\nlands consistently **between** ``t_cells * dx`` and\n``(t_cells - 1) * dx``, so *neither* integer rule is right and the\nresidual is a fixed per-face offset rather than a discretization error\nthat shrinks with ``dx``. The longitudinal convention is **not settled**;\ntreat it as an unknown of order half a cell, and if a comparator needs a\nthickness, make the sensitivity to that half cell part of the reported\nenvelope rather than picking a rule. (Measured during the stage-S3 /\nissue #499 review; no committed record carries it yet, so it is stated\nhere as a caution, not as a number to build on.) This measured\n*effective* thickness is a different quantity from a cascade\ncomparator's electrical-length bookkeeping — issue #499's comparator\ndeliberately draws ``t_c = round(t/dx) + 1`` so that ``(t_c - 1)*dx``\nconserves the cascade's total electrical length; that bookkeeping choice\nanswers a different question and is not contradicted by this caution.\n\n**A facing pair is not symmetric under this rule, because its two\ninterior faces are different kinds of corner.** For fins drawn from each\nwall inward, the lo fin's interior face is a ``hi`` corner, which\nhalf-openness **always** drops, so that fin always retreats one cell.\nThe hi fin's interior face is a ``lo`` corner, which the banded window\n**keeps**, including float dust within the on-lattice band. Historically,\nbefore that band, the realized opening was:\n\n* ``d + dx`` when only the lo fin retreated. The opening is then\n **asymmetric**: its centre sits ``dx/2`` below the guide centre.\n* ``d + 2*dx`` when rounding made the hi fin retreat as well. The two\n retreats cancel and the opening is **symmetric**.\n\nSince #802 the nominal drawing landed on the FIRST case at every\naperture (measured across the WR-90 table at a/30 and a/60: excess is\nuniformly one cell, asymmetric): the hi fin's lo corner, being an\nexact node value, captured its node. #1138 also keeps a lo face a few\nULP above that node from retreating. Historical (pre-#802, float32): which case you got\nwas unpredictable — ``d`` = 12.192 mm gave ``d + 2*dx`` while 7.620\nand 18.288 mm gave ``d + dx``, and over ~99k (guide, mesh, aperture)\ncombinations the split was 82% / 9% / 8% across ``d + dx`` /\n``d + 2*dx`` / ``d`` at even parity.\nShifting each interior face half a cell the *wrong* way (toward the\nmetal) retreats both faces by construction rather than by luck, giving\n``d + 2*dx`` deterministically at every aperture — that is the drawing\ncase 18's blocked revision used, and it is why re-comparing that\nrevision against ``oracle(d + 2*dx)`` collapsed every row.\n\nIn PR #480's WR-90 single-iris lane this inflated the ``|S11|`` error\nagainst an analytic mode-matching oracle by 4-6x, and because it scales\nwith ``dx`` it is easy to misread as first-order convergence. For a\n**resonant** structure (multi-iris filter, cavity) it shifts the\npassband rather than widening a magnitude tolerance, so it will not look\nlike a discretization error at all.\n\n**Recipe**, two conditions, both needed:\n\n* Put interior corners on **cell midpoints**, ``(j + 0.5) * dx``, to make\n node ``j`` the innermost occupied plane. Every corner value in a\n one-cell-wide interval selects the same footprint (``(j*dx, (j+1)*dx]``\n for a ``hi`` corner, ``[j*dx, (j+1)*dx)`` for a ``lo`` corner), and the\n midpoint is that interval's **centre** — not merely a safe nudge away\n from the node. That is precisely why it is immune to the float32\n effects in (2), which only ever perturb a corner by a fraction of a\n cell.\n* Keep the metal depth an exact number of cells, i.e. for a symmetric\n obstacle keep ``(cells - d_cells)`` **even**. When it is odd,\n ``fin_depth = (cells - d_cells)//2`` truncates and a symmetric opening\n of that width is simply not representable on the grid: the opening is\n one cell **wider** however it is drawn. That is a representability\n limit, not a rasterization defect.\n\nUnder both conditions the realized opening equals the nominal one\nexactly (measured, 100% of ~50k even-parity combinations). Then still\nassert the realized footprint (count the occupied node planes) against\nthe intended one.\n\n**Odd parity is a fork, not a dead end.** Symmetric fins can only realize\napertures whose cell count has the parity of ``cells``, so when the\naperture you want has the wrong parity you must choose, and both options\ncost something:\n\n* change ``dx`` (or the aperture) so the parity works, which moves every\n other dimension on that axis; or\n* place the fins **asymmetrically** on purpose, accepting a known\n half-cell offset of the opening rather than rounding the aperture to\n the wrong parity — which would change the aperture itself, the quantity\n that sets the cutoff.\n\nThis docstring does **not** recommend one over the other: how much the\nhalf-cell offset costs has not been measured here, so treat it as an\nopen trade rather than a cheap escape. What is *not* optional is that the\noffset be recorded and **representable by whatever you compare against** —\nan off-centre aperture only stays a known quantity if the oracle can model\nit. If your comparator assumes a centred obstacle, an intentional offset\nsilently becomes comparator error, which is the failure mode this whole\ndocstring exists to prevent.\n\nA box thinner than one local cell takes a separate **thin-sheet**\nbranch (a single node); the notes above apply to the volume branch\nonly. The thin branch's node is chosen by the volume rule whenever\nthat rule is decisive: a thin box whose half-open ``[lo, hi)`` window\nselects exactly one node realizes on THAT node — so a face-registered\none-cell box lands on its ``lo``-face node deterministically, not on\nwhichever side of the exact half-cell tie the last f64 ulp of\n``(lo+hi)*0.5`` favours (#802 follow-up). Only a window with zero\nnodes (a sub-cell box straddling none) or several falls back to the\nnearest-node rule.", "kind": "class", "name": "rfx.Box", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Box", "returns": { "annotation": "None" }, "signature": "(corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/csg.py#L89", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Continuous-wave sinusoidal source with smooth ramp-up.\n\nParameters\n----------\nf0 : float\n Frequency in Hz.\namplitude : float\n Peak amplitude.\nramp_steps : int\n Number of source-frequency cycles over which to apply a cosine\n taper onset. 0 means instant full-amplitude.", "kind": "class", "name": "rfx.CWSource", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ramp_steps" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#CWSource", "returns": { "annotation": "None" }, "signature": "(f0: 'float', amplitude: 'float' = 1.0, ramp_steps: 'int' = 50) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/sources.py#L691", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Specs returned by :func:`build_coaxial_tem_plane_source_specs`.\n\nThe lists carry the nonzero transverse edges of the realized TEM mode.\nThe electric profile is the discrete gradient of a unit-voltage\nelectrostatic potential on the staircased conductor cross-section.", "kind": "class", "name": "rfx.CoaxialPlaneSourceSpec", "parameters": [ { "annotation": "ForwardRef('tuple')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "electric_sources" }, { "annotation": "ForwardRef('tuple')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "magnetic_sources" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "plane_axial_index" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "plane_axis" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_cell_count" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "field_scale" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "magnetic_ratio" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_tem_ohm" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(electric_sources: ForwardRef('tuple'), magnetic_sources: ForwardRef('tuple'), plane_axial_index: ForwardRef('int'), plane_axis: ForwardRef('str'), source_cell_count: ForwardRef('int'), field_scale: ForwardRef('float'), magnetic_ratio: ForwardRef('float'), z_tem_ohm: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L639", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "SMA-style coaxial probe port for cavity coupling.\n\nModels: outer conductor (PEC cylinder), PTFE dielectric fill,\ncenter pin (PEC rod), lumped excitation gap at the base.\n\nParameters\n----------\nposition : (x, y, z) in metres\n Center of port on the cavity wall (gap cell location).\nface : str\n Which wall the port passes through: \"top\", \"bottom\", \"front\",\n \"back\", \"left\", or \"right\".\npin_length : float\n Protrusion of center pin into the cavity (metres). Default 5 mm.\npin_radius : float\n Center pin radius (metres). Default 0.635 mm (SMA standard).\nouter_radius : float\n Outer conductor radius (metres). Default 2.055 mm (SMA standard).\nimpedance : float\n Port reference impedance in ohms. Default 50.\nexcitation : object\n Source waveform (GaussianPulse, ModulatedGaussian, etc.).", "kind": "class", "name": "rfx.CoaxialPort", "parameters": [ { "annotation": "ForwardRef('tuple')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "face" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "pin_length" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "pin_radius" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "outer_radius" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "impedance" }, { "annotation": "ForwardRef('object')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "excitation" }, { "annotation": "ForwardRef('tuple')", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "terminates" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#CoaxialPort", "returns": { "annotation": null }, "signature": "(position: ForwardRef('tuple'), face: ForwardRef('str'), pin_length: ForwardRef('float'), pin_radius: ForwardRef('float'), outer_radius: ForwardRef('float'), impedance: ForwardRef('float'), excitation: ForwardRef('object'), terminates: ForwardRef('tuple') = ())", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L77", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "TEM V/I extracted from tangential Cartesian field-plane samples.\n\nThe plane-local coordinates are ``u`` and ``v``. ``e_u/e_v`` and\n``h_u/h_v`` are tangential field samples on that plane, with arbitrary\nleading axes such as frequency. This is the adapter needed between a\nfrequency-domain FDTD plane dump and :func:`coaxial_tem_reference_plane_vi`.", "kind": "class", "name": "rfx.CoaxialTEMCartesianPlaneVI", "parameters": [ { "annotation": "ForwardRef('CoaxialTEMReferencePlaneVI')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "vi" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radial_positions_m" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "azimuthal_angles_rad" }, { "annotation": "ForwardRef('tuple[float, float]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "center_uv_m" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(vi: ForwardRef('CoaxialTEMReferencePlaneVI'), radial_positions_m: ForwardRef('np.ndarray'), azimuthal_angles_rad: ForwardRef('np.ndarray'), center_uv_m: ForwardRef('tuple[float, float]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L129", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Calibrated TEM V/I extracted from a coaxial reference plane.\n\n``voltage`` is the radial electric-field line integral from the inner\nconductor to the outer conductor. ``current`` is the azimuthal magnetic\nfield loop integral around the center conductor. Both quantities use the\npublic port convention: positive current flows into the device under test.", "kind": "class", "name": "rfx.CoaxialTEMReferencePlaneVI", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "voltage" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "current" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radial_positions_m" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_sample_radius_m" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inner_radius_m" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "outer_radius_m" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(voltage: ForwardRef('np.ndarray'), current: ForwardRef('np.ndarray'), radial_positions_m: ForwardRef('np.ndarray'), h_sample_radius_m: ForwardRef('float'), inner_radius_m: ForwardRef('float'), outer_radius_m: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L112", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Structured result from a mesh convergence study.\n\nAttributes\n----------\ndx_values : ndarray\n Cell sizes tested (coarse to fine).\nmetrics : ndarray\n Metric value at each cell size.\nextrapolated : float\n Richardson-extrapolated grid-independent value.\norder : float\n Estimated convergence order.\nerrors : ndarray\n Relative error of each metric w.r.t. the extrapolated value.\nresults : list\n Raw simulation results (one per dx).", "kind": "class", "name": "rfx.ConvergenceResult", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx_values" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "metrics" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "extrapolated" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "order" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "errors" }, { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "results" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ConvergenceResult", "returns": { "annotation": "None" }, "signature": "(dx_values: 'np.ndarray', metrics: 'np.ndarray', extrapolated: 'float', order: 'float', errors: 'np.ndarray', results: 'list') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/convergence.py#L159", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "A rectangular patch curved along one axis with a given radius.\n\nThe patch is approximated as a series of flat Box segments\n(staircase approximation). The number of segments depends on\nthe grid resolution dx.\n\nParameters\n----------\ncenter : tuple (x, y, z)\n Center of the patch in 3D space.\nlength : float\n Patch length along the curvature axis.\nwidth : float\n Patch width perpendicular to curvature.\nradius : float\n Curvature radius (larger = flatter).\naxis : str\n Axis along which the patch is curved (\"x\" or \"y\").", "kind": "class", "name": "rfx.CurvedPatch", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "center" }, { "annotation": null, "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "length" }, { "annotation": null, "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "width" }, { "annotation": null, "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "radius" }, { "annotation": null, "default": "'x'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "axis" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#CurvedPatch", "returns": { "annotation": null }, "signature": "(*, center, length, width, radius, axis='x')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/curved.py#L15", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "User-defined waveform wrapper.\n\nParameters\n----------\nfunc : callable\n Function ``f(t: float) -> float`` returning the source amplitude\n at time *t*.", "kind": "class", "name": "rfx.CustomWaveform", "parameters": [ { "annotation": "object", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "func" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#CustomWaveform", "returns": { "annotation": "None" }, "signature": "(func: 'object') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/sources.py#L721", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Cylinder along a given axis.", "kind": "class", "name": "rfx.Cylinder", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "center" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "height" }, { "annotation": "str", "default": "'z'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Cylinder", "returns": { "annotation": "None" }, "signature": "(center: 'tuple[float, float, float]', radius: 'float', height: 'float', axis: 'str' = 'z') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/csg.py#L464", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of a Debye pole fit.\n\neps_inf : float\n High-frequency permittivity (dimensionless).\npoles : list[DebyePole]\n Fitted Debye poles.\nfit_error : float\n Relative RMS fit error.", "kind": "class", "name": "rfx.DebyeFitResult", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_inf" }, { "annotation": "ForwardRef('list')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "poles" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fit_error" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#DebyeFitResult", "returns": { "annotation": null }, "signature": "(eps_inf: ForwardRef('float'), poles: ForwardRef('list'), fit_error: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L36", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Single Debye pole parameters.\n\ndelta_eps : float\n Permittivity contribution Δε (dimensionless).\ntau : float\n Relaxation time in seconds.", "kind": "class", "name": "rfx.DebyePole", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "delta_eps" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "tau" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#DebyePole", "returns": { "annotation": null }, "signature": "(delta_eps: ForwardRef('float'), tau: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/debye.py#L51", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Rectangular region where material parameters are optimizable.\n\nParameters\n----------\ncorner_lo, corner_hi : (x, y, z) in metres\n Bounding box of the design region.\neps_range : (eps_min, eps_max)\n Permittivity bounds. The optimizer works in a continuous\n latent space and projects to this range via sigmoid.", "kind": "class", "name": "rfx.DesignRegion", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" }, { "annotation": "tuple[float, float]", "default": "(1.0, 12.0)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_range" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#DesignRegion", "returns": { "annotation": "None" }, "signature": "(corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]', eps_range: 'tuple[float, float]' = (1.0, 12.0)) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L33", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One finding, with named SI scalars or explanatory strings.\n\nValues are copied and made read-only. Path is absent for checks performed\nbefore execution dispatch. The record contains no solver or array objects.", "kind": "class", "name": "rfx.Diagnostic", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "code" }, { "annotation": "Severity", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "severity" }, { "annotation": "str | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "subject" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "message" }, { "annotation": "Mapping[str, int | float | str]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "values" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Diagnostic", "returns": { "annotation": "None" }, "signature": "(code: 'str', severity: 'Severity', subject: 'str | None', message: 'str', values: 'Mapping[str, int | float | str]', path: 'str | None' = None, source: 'str | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/diagnostic_records.py#L36", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Far-field radiation result.\n\nE_theta, E_phi : (n_freqs, n_theta, n_phi) complex\n Angular far-field components (V·s: the accumulator weights each sample by dt; the 1/r factor is omitted).\ntheta : (n_theta,) radians\nphi : (n_phi,) radians\nfreqs : (n_freqs,) Hz", "kind": "class", "name": "rfx.FarFieldResult", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "E_theta" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "E_phi" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#FarFieldResult", "returns": { "annotation": null }, "signature": "(E_theta: ForwardRef('np.ndarray'), E_phi: ForwardRef('np.ndarray'), theta: ForwardRef('np.ndarray'), phi: ForwardRef('np.ndarray'), freqs: ForwardRef('np.ndarray'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L145", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Running DFT accumulators for Floquet mode extraction.\n\nAccumulates field DFTs on the injection/extraction planes to\ncompute incident, reflected, and transmitted Floquet mode amplitudes.\n\nFields are stored as complex arrays: (n_freqs, ny, nz) for a\nz-normal port, or similar for other orientations.", "kind": "class", "name": "rfx.FloquetDFTAccumulator", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_tang1_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_tang2_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_tang1_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_tang2_dft" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(e_tang1_dft: ForwardRef('jnp.ndarray'), e_tang2_dft: ForwardRef('jnp.ndarray'), h_tang1_dft: ForwardRef('jnp.ndarray'), h_tang2_dft: ForwardRef('jnp.ndarray'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L183", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Floquet port for periodic structure excitation and mode extraction.\n\nFor a unit cell with periodic BC, the Floquet port injects a\nplane wave at a specified scan angle and extracts reflected\nand transmitted Floquet modes.\n\nParameters\n----------\nposition : float\n Position along the propagation axis (z typically), in metres.\naxis : str\n Normal axis of the port plane (\"x\", \"y\", or \"z\").\nscan_theta : float\n Scan angle theta from broadside (degrees). Default 0 (broadside).\nscan_phi : float\n Scan angle phi in the xy-plane (degrees). Default 0.\npolarization : str\n Polarization: \"te\" or \"tm\". Default \"te\".\nn_modes : int\n Number of Floquet modes to extract (default 1 = specular only).\nfreqs : array-like or None\n Analysis frequencies (Hz). If None, auto-generated.\nn_freqs : int\n Number of frequencies if freqs is None.\nf0 : float or None\n Source center frequency. If None, uses freq_max / 2.\nbandwidth : float\n Source bandwidth. Default 0.5.\namplitude : float\n Source amplitude. Default 1.0.", "kind": "class", "name": "rfx.FloquetPort", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'z'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "scan_theta" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "scan_phi" }, { "annotation": "str", "default": "'te'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "polarization" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_modes" }, { "annotation": "object", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_freqs" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#FloquetPort", "returns": { "annotation": "None" }, "signature": "(position: 'float', axis: 'str' = 'z', scan_theta: 'float' = 0.0, scan_phi: 'float' = 0.0, polarization: 'str' = 'te', n_modes: 'int' = 1, freqs: 'object' = None, n_freqs: 'int' = 50, f0: 'float | None' = None, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L384", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Running DFT accumulator for Poynting flux through a plane.\n\nAccumulates frequency-domain E and H tangential components on a\n(possibly finite-size) region of the plane to compute\n∫ Re(E × H*) · n̂ dA at each frequency.\n\nFor x-normal plane: flux = Re(Ey·Hz* - Ez·Hy*) integrated over y,z.\nFor y-normal plane: flux = Re(Ez·Hx* - Ex·Hz*) integrated over x,z.\nFor z-normal plane: flux = Re(Ex·Hy* - Ey·Hx*) integrated over x,y.", "kind": "class", "name": "rfx.FluxMonitor", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e1_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e2_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h1_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h2_dft" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "index" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dA" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "total_steps" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "window" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "window_alpha" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lo1" }, { "annotation": "ForwardRef('int')", "default": "-1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "hi1" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lo2" }, { "annotation": "ForwardRef('int')", "default": "-1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "hi2" }, { "annotation": "ForwardRef('jnp.ndarray | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dA2" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#FluxMonitor", "returns": { "annotation": null }, "signature": "(e1_dft: ForwardRef('jnp.ndarray'), e2_dft: ForwardRef('jnp.ndarray'), h1_dft: ForwardRef('jnp.ndarray'), h2_dft: ForwardRef('jnp.ndarray'), freqs: ForwardRef('jnp.ndarray'), axis: ForwardRef('int'), index: ForwardRef('int'), dA: ForwardRef('jnp.ndarray'), total_steps: ForwardRef('int'), window: ForwardRef('str'), window_alpha: ForwardRef('float'), lo1: ForwardRef('int') = 0, hi1: ForwardRef('int') = -1, lo2: ForwardRef('int') = 0, hi2: ForwardRef('int') = -1, dA2: ForwardRef('jnp.ndarray | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L685", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Minimal differentiable simulation result.\n\nCarries only the observables needed by gradient-based objectives,\navoiding the broader stateful surface of :class:`Result`. The\n``settling_db`` and ``settling_witness`` properties score the concrete\nuser-probe record using the same host diagnostic as ``run()``. They\nreport absence while records are traced; read them on the returned\nconcrete result, not as gradient objectives. Numeric\n``settling_probe_info`` preserves the selected columns, component\nlabels and the #1090 source-dominated flag as integers, without\ninserting strings into a JAX result tree. ``settling_source_end_index``\ncarries the first post-source sample, including free-space transit;\nmissing timing or insufficient post-source samples yields no witness.\nThese lazy properties are\nnot stored fields in ``_asdict()``. ``wire_port_sparams`` is a tuple of\n``(meta, accs)`` pairs on both lanes; the lane-specific type of ``meta``\nand the accumulator channels are documented on :class:`Result`.\n\n``lumped_port_sparams`` exposes the raw per-port\n``(V_dft, I_dft, V_ref_dft)`` tuples accumulated inside the JIT scan body\nwhen ``forward(port_s11_freqs=...)`` is used. V and I are the\nPOST-injection physical channels (I carrying the Yee half-step phase);\n``V_ref`` is the PRE-injection drive sample, which only the N-port\noff-diagonal incident wave consumes. Single-port objectives can keep\nusing ``s_params`` (per-port S11: the driven terminal reflection\n:func:`rfx.probes.probes.driven_port_reflection` at an excited port, the\nport-branch :func:`extract_lumped_s11` at a passive one). Multi-port AD\nobjectives (e.g. 2-port |S21| topology optimisation) read the raw\nchannels from this field and compose their own wave decomposition, since\na diagonal collapses each port to its self-reflection only.\n\n``dft_planes`` exposes the JIT-scan-accumulated complex DFT plane\nprobes registered via :meth:`Simulation.add_dft_plane_probe`. Each\nentry is a :class:`DFTPlaneProbe` whose ``accumulator`` field is a\nJAX-traceable complex array shaped ``(n_freqs, *plane_shape)``, with\nplane-resolved field values usable by gradient-based objectives that\nneed plane-integrated V/I (e.g. waveguide-port or microstrip-port\nline-integrated voltage / closed-loop current). ``None`` when no\nplane probes were registered.\n\n``dt`` is the time step the solver advanced by, the spacing of\n``time_series``. Read time and frequency with it, not with\n``grid.dt``: ``stencil_order=4`` steps at ``0.857 * grid.dt``.\n\n``ringdown`` is a :class:`rfx.ringdown.RingdownForwardResult` when\n``forward(ringdown=RingdownSpec())`` was called (issue #1254): the\ncompleted wire-port S-parameters, traced and differentiable, and a lazy\nhost report on the concrete result. ``None`` otherwise.\n\n``design_box_held_edges`` is the tuple of ``(axis, i, j, k)`` E edges a\npermittivity design box held on the drawn materials' coefficients\n(``forward(design_box_holds_ports=True)``; axis 0, 1, 2 for Ex, Ey, Ez):\n``()`` for a box that held none, ``None`` when no such box was given.\n\n``adjoint_settling`` is the primal design-edge max|E| over the last period of\nthe lowest monitor bin (capped at the record length), divided by the record maximum.\nAbove about 1e-2 means unsettled; small proves nothing: it follows the strongest field\nand says nothing about the adjoint record. None for autodiff, NaN for zero signal.\nUse :func:`rfx.gradient_record_length_witness` to witness an adjoint gradient.", "kind": "class", "name": "rfx.ForwardResult", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_box" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lumped_port_sparams" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "wire_port_sparams" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_planes" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_probe_info" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ringdown" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "design_box_held_edges" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_data" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_monitor" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "adjoint_settling" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_source_end_index" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_freq_max" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sparam_time_records" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_time_records" }, { "annotation": "ForwardRef('tuple[Diagnostic, ...]')", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "diagnostics" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ForwardResult", "returns": { "annotation": null }, "signature": "(time_series: ForwardRef('jnp.ndarray'), ntff_data: ForwardRef('object') = None, ntff_box: ForwardRef('object') = None, grid: ForwardRef('object') = None, s_params: ForwardRef('object') = None, freqs: ForwardRef('object') = None, lumped_port_sparams: ForwardRef('object') = None, wire_port_sparams: ForwardRef('object') = None, dft_planes: ForwardRef('object') = None, settling_probe_info: ForwardRef('object') = None, dt: ForwardRef('object') = None, ringdown: ForwardRef('object') = None, design_box_held_edges: ForwardRef('object') = None, current_moment_data: ForwardRef('object') = None, current_moment_monitor: ForwardRef('object') = None, adjoint_settling: ForwardRef('object') = None, settling_source_end_index: ForwardRef('object') = None, settling_freq_max: ForwardRef('object') = None, sparam_time_records: ForwardRef('tuple | None') = None, dft_time_records: ForwardRef('object') = None, diagnostics: ForwardRef('tuple[Diagnostic, ...]') = ())", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1065", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Differentiated Gaussian pulse with center frequency f0.\n\ns(t) = -2 * ((t - t0) / tau) * exp(-((t - t0) / tau)^2)\n\nThe onset truncation at t=0 leaves a nonzero time integral: over the\nsampled table, S = sum s(t_n)*dt ~ -amplitude * tau * exp(-cutoff^2).\nA soft current source deposits exactly that integral as a net static\nend-charge q = S/((1+loss)*dz_src) (issue #388), so the deposited DC\nscales as e^(-cutoff^2): raising ``cutoff`` from 3.0 to 4.5 cuts the\ndeposited charge by e^(4.5^2 - 3^2) ~ 7.7e4 — about 5 decades.\nUse a higher cutoff when a static source remnant matters (e.g. the\n``until_decay`` interior-energy stop on absorbing boundaries).\n\nParameters\n----------\nf0 : float\n Center frequency (Hz).\nbandwidth : float\n Fractional bandwidth (0–1). Default 0.5.\namplitude : float\n Peak amplitude (V/m). Default 1.0.\ncutoff : float\n Number of tau between t=0 and the pulse peak: t0 = cutoff * tau.\n Default 3.0 (historical value; waveform values are unchanged at\n the default). Higher values buy an e^(-cutoff^2) reduction of the\n deposited-DC integral at the cost of a longer onset (issue #388).", "kind": "class", "name": "rfx.GaussianPulse", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "float", "default": "3.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cutoff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#GaussianPulse", "returns": { "annotation": "None" }, "signature": "(f0: 'float', bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, cutoff: 'float' = 3.0) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/sources.py#L223", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of AD-vs-FD gradient comparison.\n\nAttributes\n----------\nad_grad : jnp.ndarray\n Gradient from reverse-mode autodiff.\nfd_grad : jnp.ndarray\n Gradient from central finite differences.\nrelative_error : float\n max |ad - fd| / (max |ad| + max |fd| + 1e-30).", "kind": "class", "name": "rfx.GradientCheckResult", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_grad" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fd_grad" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "relative_error" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#GradientCheckResult", "returns": { "annotation": "None" }, "signature": "(ad_grad: 'jnp.ndarray', fd_grad: 'jnp.ndarray', relative_error: 'float') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L545", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "What two record lengths said about one gradient.\n\nEvery array carries a leading bin axis of length ``n_bins`` (``1`` when the\nobjective returned a scalar, in which case ``observable_is_scalar`` is\nTrue), so a scalar and a per-frequency objective are read the same way.\n\nAttributes\n----------\nn_steps, n_steps_long : int\n The two record lengths, in timesteps.\nfactor : float\n ``n_steps_long = ceil(factor * n_steps)``.\ntol : float\n The caller's declared bar on ``worst``.\npassed : bool\n ``worst <= tol``. A gradient whose witness did not pass is not\n reportable, whatever the shorter record's settling level says.\nworst : float\n THE VERDICT. The largest ``rel_by_bin`` over the bins -- a norm-level\n relative change of the whole gradient vector, with no floor in it.\nworst_bin : int or None\n Bin index holding ``worst``.\nworst_leaf : str or None\n Within ``worst_bin``, the leaf contributing the largest\n ``||g_long - g_short||``. Where the change sits, not a second verdict.\nrel_by_bin : numpy.ndarray\n ``||g_long - g_short|| / ||g_long||`` per bin, over every parameter\n element of every leaf concatenated, shaped ``(n_bins,)``. ``inf`` where\n the long record's gradient is identically zero and the short one's is\n not; ``0.0`` where both are.\ncosine_by_bin : numpy.ndarray\n Per bin, the cosine between the two arms' gradient vectors (the real\n part of the Hermitian inner product, normalised). ``1.0`` means the\n descent DIRECTION is unchanged and only the step length moved; a value\n below 1 means the direction itself turned. ``nan`` where either arm's\n gradient is identically zero.\nvalue, value_long : numpy.ndarray\n The observable at each length, shaped ``(n_bins,)``. Complex when the\n objective returned a complex observable.\nvalue_rel_change : numpy.ndarray\n ``|value_long - value| / max(|value_long|, floor)``, shaped\n ``(n_bins,)``, with ``|.|`` the complex magnitude where the observable\n is complex. Reported so the value's convergence and the gradient's can\n be read side by side; it is NOT part of the verdict.\nworst_value_rel_change : float\n Largest entry of ``value_rel_change``.\ngrad, grad_long : dict\n Leaf path -> gradient array shaped ``(n_bins,) + leaf.shape``. Complex\n (``dObservable/dp`` as ``dRe/dp + i dIm/dp``) for a complex observable.\ngrad_rel_change : dict\n Leaf path -> per-ELEMENT ``|g_long - g| / max(|g_long|, floor)``, same\n shape. A REPORT, not the verdict: it locates where a change sits once\n ``worst`` has already failed. An element whose gradient is a tiny\n fraction of the dominant one reads a large ratio off its own rounding,\n which is what the floor and the norm-level verdict exist to keep out of\n the decision.\nworst_elementwise : float\n Largest entry of ``grad_rel_change``, with\n ``worst_elementwise_leaf`` / ``worst_elementwise_bin`` locating it.\n Reported for the same reason the table is.\nsettling_db, settling_db_long : float or None\n Ring-down levels of the two records, when the objective's aux supplied\n them. ``None`` means the objective did not report one, never that the\n record settled.\nfloor_frac : float\n The floor used in ``grad_rel_change`` only, as a fraction of the\n largest ``|gradient|`` across leaves in that bin, at either record\n length.\nobservable_is_scalar, observable_is_complex : bool\n What the objective returned.", "kind": "class", "name": "rfx.GradientRecordLengthWitness", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps_long" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "factor" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "tol" }, { "annotation": "bool", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "passed" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst" }, { "annotation": "int | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_bin" }, { "annotation": "str | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_leaf" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rel_by_bin" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cosine_by_bin" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value_long" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value_rel_change" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_value_rel_change" }, { "annotation": "dict[str, np.ndarray]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grad" }, { "annotation": "dict[str, np.ndarray]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grad_long" }, { "annotation": "dict[str, np.ndarray]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grad_rel_change" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_elementwise" }, { "annotation": "str | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_elementwise_leaf" }, { "annotation": "int | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "worst_elementwise_bin" }, { "annotation": "float | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "float | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db_long" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "floor_frac" }, { "annotation": "bool", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "observable_is_scalar" }, { "annotation": "bool", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "observable_is_complex" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(n_steps: 'int', n_steps_long: 'int', factor: 'float', tol: 'float', passed: 'bool', worst: 'float', worst_bin: 'int | None', worst_leaf: 'str | None', rel_by_bin: 'np.ndarray', cosine_by_bin: 'np.ndarray', value: 'np.ndarray', value_long: 'np.ndarray', value_rel_change: 'np.ndarray', worst_value_rel_change: 'float', grad: 'dict[str, np.ndarray]', grad_long: 'dict[str, np.ndarray]', grad_rel_change: 'dict[str, np.ndarray]', worst_elementwise: 'float', worst_elementwise_leaf: 'str | None', worst_elementwise_bin: 'int | None', settling_db: 'float | None', settling_db_long: 'float | None', floor_frac: 'float', observable_is_scalar: 'bool', observable_is_complex: 'bool') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_gradient_witness.py#L185", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Rectilinear FDTD grid with uniform cell size.\n\nSupports 3D and 2D (TMz/TEz) modes. In 2D mode the grid has\n``nz=1`` and the Courant factor uses √2 instead of √3. The\nexisting 3D update equations naturally reduce to 2D because\nz-derivatives vanish when the z-axis is periodic with one cell.\n\nParameters\n----------\nfreq_max : float\n Maximum simulation frequency (Hz). Used for auto-resolution.\ndomain : tuple[float, float, float]\n Physical domain size (Lx, Ly, Lz) in meters.\n For 2D modes, Lz is ignored (set nz=1 internally).\ndx : float | None\n Cell size override. If None, auto-computed as λ_min / 20.\ncpml_layers : int\n Number of CPML absorbing layers on each face.\ncpml_axes : str\n Axes that receive CPML padding. Default ``\"xyz\"``.\nmode : str\n ``\"3d\"`` (default), ``\"2d_tmz\"`` (Ez, Hx, Hy), or\n ``\"2d_tez\"`` (Hz, Ex, Ey).", "kind": "class", "name": "rfx.Grid", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_max" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "domain" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_layers" }, { "annotation": "str", "default": "'xyz'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_axes" }, { "annotation": "str", "default": "'3d'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "kappa_max" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_faces" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pmc_faces" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "face_layers" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "conformal_faces" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "periodic_axes" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Grid", "returns": { "annotation": null }, "signature": "(freq_max: 'float', domain: 'tuple[float, float, float]', dx: 'float | None' = None, cpml_layers: 'int' = 8, cpml_axes: 'str' = 'xyz', mode: 'str' = '3d', kappa_max: 'float | None' = None, pec_faces: 'set[str] | None' = None, pmc_faces: 'set[str] | None' = None, face_layers: 'dict | None' = None, conformal_faces: 'set[str] | None' = None, periodic_axes: 'str' = '')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/grid.py#L168", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "A single resonant mode extracted by Harminv.", "kind": "class", "name": "rfx.HarminvMode", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "decay" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Q" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phase" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "error" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#HarminvMode", "returns": { "annotation": null }, "signature": "(freq: ForwardRef('float'), decay: ForwardRef('float'), Q: ForwardRef('float'), amplitude: ForwardRef('float'), phase: ForwardRef('float'), error: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/harminv.py#L93", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of a Lorentz pole fit.\n\neps_inf : float\n High-frequency permittivity (dimensionless).\npoles : list[LorentzPole]\n Fitted Lorentz poles.\nfit_error : float\n Relative RMS fit error.", "kind": "class", "name": "rfx.LorentzFitResult", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_inf" }, { "annotation": "ForwardRef('list')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "poles" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fit_error" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#LorentzFitResult", "returns": { "annotation": null }, "signature": "(eps_inf: ForwardRef('float'), poles: ForwardRef('list'), fit_error: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L51", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Single Lorentz oscillator pole.\n\nomega_0 : float\n Resonant angular frequency (rad/s). Set to 0 for Drude.\ndelta : float\n Damping coefficient (rad/s).\nkappa : float\n Coupling strength = Δε · ω₀² for Lorentz, ω_p² for Drude.", "kind": "class", "name": "rfx.LorentzPole", "parameters": [ { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "omega_0" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "delta" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "kappa" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#LorentzPole", "returns": { "annotation": null }, "signature": "(omega_0: ForwardRef('float'), delta: ForwardRef('float'), kappa: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/lorentz.py#L44", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Lumped RLC element specification.\n\nParameters\n----------\nR : float\n Resistance in ohms. 0 = no resistive component.\nL : float\n Inductance in henries. 0 = no inductive component.\nC : float\n Capacitance in farads. 0 = no capacitive component.\ntopology : str\n \"series\" or \"parallel\". Series topology tracks a shared\n current through R, L, C via ADE (true series RLC). Parallel\n topology folds R/C into material properties independently\n and uses an ADE only for L.\nposition : (x, y, z) in metres\ncomponent : str\n E-field component (\"ex\", \"ey\", or \"ez\").", "kind": "class", "name": "rfx.LumpedRLCSpec", "parameters": [ { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "R" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "L" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "C" }, { "annotation": "str", "default": "'series'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "topology" }, { "annotation": "tuple[float, float, float]", "default": "(0.0, 0.0, 0.0)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#LumpedRLCSpec", "returns": { "annotation": "None" }, "signature": "(R: 'float' = 0.0, L: 'float' = 0.0, C: 'float' = 0.0, topology: 'str' = 'series', position: 'tuple[float, float, float]' = (0.0, 0.0, 0.0), component: 'str' = 'ez') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/lumped.py#L89", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "dict() -> new empty dictionary\ndict(mapping) -> new dictionary initialized from a mapping object's\n (key, value) pairs\ndict(iterable) -> new dictionary initialized as if via:\n d = {}\n for k, v in iterable:\n d[k] = v\ndict(**kwargs) -> new dictionary initialized with the name=value pairs\n in the keyword argument list. For example: dict(one=1, two=2)", "kind": "object", "name": "rfx.MATERIAL_LIBRARY", "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MATERIAL_LIBRARY", "source_url": null, "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Per-MSL-port downstream-reflector layout diagnosis, in metres.\n\n``satisfied`` means no considered conductor candidate violates the\nexisting recommendation. ``insufficient`` records a known violation;\n``unavailable`` means missing coordinates or unevaluated conductors\nprevent that conclusion. A known violation remains insufficient even\nwhen other conductors could not be evaluated.\n\nThis uses registered conductor bounds and the existing candidate scan,\nnot a modal-purity or S-accuracy test. It does not replace source/absorber,\nsettling or low-signal checks. Negative gaps mean the probe has passed\nthe candidate's first boundary along the port direction. ``None`` gaps\nwith satisfied status mean the scan found no candidate. Probe coordinates\nare scalar positions on ``axis``. The threshold is evaluated at the\nsimulation's design frequency, not independently at every result bin.", "kind": "class", "name": "rfx.MSLProbeClearance", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_name" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "Literal['satisfied', 'insufficient', 'unavailable']", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "status" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rule_frequency_hz" }, { "annotation": "float | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommended_gap_m" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "first_probe_m" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "deepest_probe_m" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "first_gap_m" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "deepest_gap_m" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reflector" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "unevaluated_conductors" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "note" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MSLProbeClearance", "returns": { "annotation": "None" }, "signature": "(port_name: 'str', axis: 'str', status: \"Literal['satisfied', 'insufficient', 'unavailable']\", rule_frequency_hz: 'float', recommended_gap_m: 'float | None', first_probe_m: 'float | None' = None, deepest_probe_m: 'float | None' = None, first_gap_m: 'float | None' = None, deepest_gap_m: 'float | None' = None, reflector: 'str | None' = None, unevaluated_conductors: 'tuple[str, ...]' = (), note: 'str | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1581", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "MSL S-matrix result.\n\nAttributes\n----------\nS : (n_ports, n_ports, n_freqs) complex\n Power-wave S-matrix at each port's FIRST probe plane, formed from\n a=(V+R*I)/(2*sqrt(R)), b=(V-R*I)/(2*sqrt(R)) with the positive real\n analytic Hammerstad-Jensen reference R of each port. There\n is no translation back to the physical feed planes. Bracketing H\n samples are interpolated to this E-node plane using physical\n coordinates, with the temporal leapfrog offset corrected separately.\n The fitted ``Z0`` below is a diagnostic, not the reference used to form S.\nreference_impedances : (n_ports,) float, optional\n Actual positive real R values used to define S, in ohms and in\n port_names order. These are distinct from fitted Z0 and the\n source/load resistances. Present on generated results; None is\n retained for manually constructed legacy result objects.\nfreqs : (n_freqs,) float\n Frequency grid in Hz.\nZ0 : (n_ports, n_freqs) complex\n Characteristic impedance extracted via the N-probe SVD\n least-squares wave-decomposition fit (issue #80 Fix C),\n per driven-port run (``Z0[i, :]`` is from run with port i driven).\nbeta : (n_freqs,) complex\n Propagation constant β from the N-probe least-squares fit\n (issue #80 Fix C) at the first port's run.\nreliable : (n_ports, n_freqs) bool, optional\n Relative low-signal mask. ``reliable[p, k]`` is False when both\n |V| and |I| at port p fall below 10% of that record's own band\n medians in at least one driven run. All drive/port records used by\n the solve are covered; S is retained unchanged.\n\n A False entry does not by itself prove matrix corruption: a true\n transmission zero can have zero passive-port phasors with a\n well-conditioned drive matrix. Inspect absolute signal uncertainty,\n settling and drive conditioning before interpreting those bins.\n A True entry is not an accuracy certificate either. The numerical\n threshold and the policies used by callers are unchanged.\nprobe_clearance : tuple[MSLProbeClearance, ...], optional\n Separate downstream-reflector layout diagnosis in port order, using\n the resolved probe ladder. Status is satisfied, insufficient or\n unavailable; physical probe coordinates and signed gap estimates\n accompany it. This is independent of ``reliable`` and does not\n certify mode purity or S accuracy.\n\n **The two fields answer different questions** (issue #726).\n ``reliable`` is a per-bin FIT-QUALITY mask; ``probe_clearance`` is\n the GEOMETRIC condition, and neither is the other's proxy — on the\n board runs that opened #726 ``reliable`` was True on 100 % of in-band\n bins while the fitted Z0 was 2.4x the analytic value. What the\n geometric condition costs was measured (VESSL 369367260508, cv06b\n fixed-source, same source/load/DUT with only the p1 observation\n offset varied, both arms settled below −118 dB): the FITTED Z0/beta\n are what corrupt — the near-reflector arm's β scan railed on 51/51\n bins over 3–5 GHz against 0/51 for the compliant arm — while raw S11\n at the 3.77125 GHz notch bin read +0.026895 dB on the near-reflector\n arm and +0.018065 dB on the compliant one, against the analytic 0 dB\n that quarter-wave open-stub notch has. Both sit ABOVE unity on a\n passive structure, by 0.31 % and 0.21 %, which is never reported here\n as physics: they are raw, unprojected values carrying the coherent\n power excess recorded in #838 (closed as not planned). Their 0.009 dB difference is one\n fixture (cv06b), one bin (3.77125 GHz), an arm-to-arm difference —\n NOT a bound on ``S`` — and the comparison's producer verdict was\n ``not_read``. What it does show is that ``S`` moves far less than the\n fit, because it normalizes with the analytic Hammerstad–Jensen Z0\n rather than with the fit.\n\n So: gate on ``probe_clearance`` for the layout, on ``beta_railed``\n for the fitted-value symptom, and treat ``Z0``/``beta`` as\n UNREADABLE — not merely uncertain — when the status is\n ``insufficient``. ``S`` stands with the 0.009 dB caveat. The fix is\n a longer uniform feed or a moved reference plane; raising\n ``n_probe_offset`` alone moves the probes toward the reflector.\n ``rfx.preflight.msl.MSL_PROBE_CLEARANCE_EFFECT`` is the single text\n every warning about this condition embeds.\nsettling_db : (n_ports,) float, optional\n Per-drive pole-tail amplitude share in dB over modal voltage,\n loop-current, and witness-probe records at the extraction bins.\nS_raw : (n_ports, n_ports, n_freqs) complex, optional\n The S-matrix exactly as extracted, BEFORE passivity projection.\n ``None`` on the default path, where ``S`` already IS that matrix;\n set only when ``enforce_passivity=True`` clipped something, so no\n information is discarded by enforcing the bound.\npassivity_correction : (n_freqs,) float, optional\n Per-frequency amount clipped by the passivity projection:\n ``max(sigma_max(S_raw(f)) - 1, 0)``. ``None`` unless\n ``enforce_passivity=True`` actually clipped a bin — it records\n what the projection REMOVED, so on the default path there is\n nothing for it to record and ``sigma_max_excess`` is the field to\n read.\nsigma_max_excess : (n_freqs,) float, optional\n Per-frequency ``max(sigma_max(S(f)) - 1, 0)`` of the RAW\n extraction, measured before any opt-in projection and filled on\n every concrete call (``None`` only while tracing, which has no\n value to take singular values of). Zero where the extraction was\n already passive. This is the honesty metric, and it does not\n depend on ``enforce_passivity``: a bin with a large excess is a\n measurement artifact (check ``reliable`` and ``settling_db`` for\n the cause), whether the returned ``S`` carries that excess or a\n projection clipped it away. Where a projection did clip,\n ``passivity_correction`` equals this on the touched bins.\n\n Near neighbour, different quantity: the ``passivity_excess`` key of\n :func:`rfx.io.network_quality_metrics` is a single SCALAR over the\n whole sweep, measured in POWER (``max(sigma_max^2 - 1, 0)``). This\n field is per frequency and in amplitude. The two names differ so\n the numbers are not read as interchangeable; do not compare them.\nport_names : tuple[str, ...]\nassembly : str, optional\n Which rule produced ``S`` — ``\"multi_drive_solve\"`` (normal:\n ``S = B·A⁻¹`` over all drives, issue #507) or\n ``\"single_ratio_fallback\"``. The fallback is taken when the solve\n returns non-finite entries on a degenerate drive system; it is the\n SUPERSEDED per-column rule ``S[j, d] = b_j / a_d``, which reports a\n passive port's echo as the driven port's own reflection whenever\n that port is not matched.\n\n **Read this before trusting a fallback result.** The fallback's\n characteristic symptom is column power above 1, which the default\n ``enforce_passivity=False`` leaves standing in ``S`` and\n ``sigma_max_excess`` measures. Under ``enforce_passivity=True``\n the symptom is clipped out of ``S`` — but it is not erased from\n the result: ``passivity_correction`` records how much was clipped\n and ``S_raw`` keeps the unprojected matrix, and the run also emits\n both a fallback warning and a passivity-guard\n warning. So a fallback is not silent; this field is simply the\n *specific* signal. Column power above 1 has several causes (an\n under-settled record, a standing-wave null, a mis-scaled current) and\n only one of them is the fallback — that is what this field\n disambiguates. ``None`` while tracing (the finiteness test cannot run\n on a tracer, so the solve result is taken as-is — see ``cond_a``).\ncond_a : (n_freqs,) float, optional\n Per-frequency condition number of the power-wave drive matrix ``A``\n (one common row scale cancels from this condition number). Bounds\n DEGENERACY of the drive system only — it is **not** a reliability\n or accuracy score, and a low value does not certify the result\n (same contract as the coax lane's\n :func:`rfx.sources.coaxial_port.solve_two_port_from_wave_amplitudes`).\n ``None`` while tracing.\nbeta_railed : (n_ports, n_freqs) bool, optional\n Per-port β-scan rail mask for the FITTED numbers (issue #681).\n ``beta_railed[p, k]`` is True when port *p*'s own-drive N-probe β\n scan failed to bracket its residual optimum at bin *k* — the raw\n argmin sat at an edge node of the ±35% window around the analytic\n Hammerstad-Jensen guess, or the refined β landed within half a\n grid step of a window limit. ``Z0[p, k]`` (and ``beta[k]`` for\n ``p = 0``) at such a bin is the scan-window limit, NOT a\n measurement — do not quote it. Fitted Z0/beta do not enter S11/S21,\n which use the analytic Z0 anchor and measured V/I. This separation\n does not certify the V/I or reference impedance: shared record\n contamination can affect both the fit and S. The\n own-drive diagonal is exactly the provenance of every fitted\n number this result carries (``Z0[i, :]`` comes from port *i*'s\n own driven run). ``None`` while tracing.", "kind": "class", "name": "rfx.MSLSMatrixResult", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "S" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Z0" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reliable" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "S_raw" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "passivity_correction" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "assembly" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cond_a" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta_railed" }, { "annotation": "tuple[MSLProbeClearance, ...] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_clearance" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_impedances" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma_max_excess" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_witness" }, { "annotation": "tuple[Diagnostic, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "diagnostics" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MSLSMatrixResult", "returns": { "annotation": "None" }, "signature": "(S: 'np.ndarray', freqs: 'np.ndarray', Z0: 'np.ndarray', beta: 'np.ndarray', port_names: 'tuple[str, ...]' = (), reliable: 'np.ndarray | None' = None, settling_db: 'np.ndarray | None' = None, S_raw: 'np.ndarray | None' = None, passivity_correction: 'np.ndarray | None' = None, assembly: 'str | None' = None, cond_a: 'np.ndarray | None' = None, beta_railed: 'np.ndarray | None' = None, probe_clearance: 'tuple[MSLProbeClearance, ...] | None' = None, reference_impedances: 'np.ndarray | None' = None, sigma_max_excess: 'np.ndarray | None' = None, settling_witness: 'tuple | None' = None, diagnostics: 'tuple[Diagnostic, ...]' = ()) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1613", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of differentiable material fitting.\n\nAttributes\n----------\neps_inf : float\n High-frequency permittivity.\ndebye_poles : list[DebyePole]\n Fitted Debye poles (may be empty).\nlorentz_poles : list[LorentzPole]\n Fitted Lorentz poles (may be empty).\nloss_history : list[float]\n Loss value at each iteration.\nfinal_s_params : np.ndarray or None\n S-parameters from the final simulation.\nfreqs : np.ndarray\n Frequency array in Hz.\nconverged : bool\n Whether the optimizer converged (loss plateau).", "kind": "class", "name": "rfx.MaterialFitResult", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_inf" }, { "annotation": "list", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "debye_poles" }, { "annotation": "list", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lorentz_poles" }, { "annotation": "list", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "loss_history" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "final_s_params" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "converged" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MaterialFitResult", "returns": { "annotation": "None" }, "signature": "(eps_inf: 'float', debye_poles: 'list' = , lorentz_poles: 'list' = , loss_history: 'list' = , final_s_params: 'np.ndarray | None' = None, freqs: 'np.ndarray | None' = None, converged: 'bool' = False) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/differentiable_material_fit.py#L82", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Consolidated mesh/memory preflight summary.\n\nThis is a lightweight user-facing planning object for the\n\"subgrid-like\" non-uniform lane: it combines existing preflight\nadvisories with cell-count and AD-memory estimates, including a\nuniform-fine comparator for non-uniform meshes.", "kind": "class", "name": "rfx.MeshIntelligenceReport", "parameters": [ { "annotation": "ForwardRef('tuple[int, int, int]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_shape" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cells" }, { "annotation": "ForwardRef('tuple[int, int, int]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "uniform_fine_shape" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "uniform_fine_cells" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cell_savings_factor" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "min_cell_size" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "nominal_dx" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "uses_nonuniform" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "preflight_issues" }, { "annotation": "ForwardRef('AD_MemoryEstimate | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ad_memory" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendation" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MeshIntelligenceReport", "returns": { "annotation": null }, "signature": "(grid_shape: ForwardRef('tuple[int, int, int]'), cells: ForwardRef('int'), uniform_fine_shape: ForwardRef('tuple[int, int, int]'), uniform_fine_cells: ForwardRef('int'), cell_savings_factor: ForwardRef('float'), min_cell_size: ForwardRef('float'), nominal_dx: ForwardRef('float'), uses_nonuniform: ForwardRef('bool'), preflight_issues: ForwardRef('tuple[str, ...]'), ad_memory: ForwardRef('AD_MemoryEstimate | None'), recommendation: ForwardRef('str'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L335", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Inspectable mesh-planning result built from existing rfx facts.\n\n``MeshPlan`` is an advisory artifact. It serializes the derived mesh,\nCFL basis, memory estimate, support rows, and intended artifact paths\nwithout writing files or claiming deterministic solver replay.", "kind": "class", "name": "rfx.MeshPlan", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "schema_version" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "plan_source" }, { "annotation": "tuple[float | None, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "str | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "accuracy" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "boundary" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cell_sizes" }, { "annotation": "tuple[int, int, int]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_shape" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "domain" }, { "annotation": "float | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "margin" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfl" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "absorber" }, { "annotation": "list[dict[str, Any]]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "resolution_basis" }, { "annotation": "list[dict[str, Any]]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "support_checks" }, { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "memory" }, { "annotation": "dict[str, dict[str, Any]]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "artifact_declarations" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "warnings" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "recommendation" }, { "annotation": "SimConfig | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "_sim_config" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MeshPlan", "returns": { "annotation": "None" }, "signature": "(schema_version: 'str', plan_source: 'str', freq_range: 'tuple[float | None, float]', accuracy: 'str | None', boundary: 'str', cell_sizes: 'dict[str, Any]', grid_shape: 'tuple[int, int, int]', domain: 'tuple[float, float, float]', margin: 'float | None', cfl: 'dict[str, Any]', absorber: 'dict[str, Any]', resolution_basis: 'list[dict[str, Any]]', support_checks: 'list[dict[str, Any]]', memory: 'dict[str, Any]', artifact_declarations: 'dict[str, dict[str, Any]]', warnings: 'tuple[str, ...]' = (), recommendation: 'str' = '', _sim_config: 'SimConfig | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/mesh_planner.py#L92", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Occupancy ``Shape`` backed by a watertight triangle mesh (point-in-mesh).\n\nConstruct from a file with :meth:`from_file` (the common path) or wrap an\nalready-loaded ``trimesh.Trimesh`` directly with ``MeshShape(mesh)``.\n\nParameters\n----------\nmesh : trimesh.Trimesh\n An already-loaded, already-scaled/positioned watertight mesh (metres).\nvalidate : bool, default True\n Raise ``ValueError`` if the mesh is not watertight.", "kind": "class", "name": "rfx.MeshShape", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mesh" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "validate" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MeshShape", "returns": { "annotation": null }, "signature": "(mesh, *, validate: 'bool' = True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/mesh_import.py#L130", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Mixed-family S-matrix result (issue #488, lumped/wire + MSL v1).\n\n``S`` here is in the **Kurokawa\npower-wave convention** (every wave amplitude divided by\n``sqrt(Re(Z0_port))``): with unequal reference impedances across\nfamilies a pseudo-wave ``b/a`` ratio is off by ``sqrt(Z_j/Z_i)``\n(issue #460), so the mixed lane normalizes to power waves by\nconstruction. Off-diagonal PHASE across families is provisional —\nthe lumped/wire cell and the MSL de-embedded plane are different\nreference-plane conventions (magnitude is the validated observable).\n\nAttributes\n----------\nS : (n_ports, n_ports, n_freqs) complex\n Power-wave S-matrix; ``S[i, j]`` = response at port *i* driving\n port *j*. Port order: lumped/wire ports (registration order),\n then MSL ports (registration order).\nfreqs : (n_freqs,) float\n Frequency grid in Hz.\nport_names : tuple of str\n Combined port names (lumped/wire ports are auto-named\n ``\"lw\"``; MSL ports keep their registered names).\nport_families : tuple of str\n ``\"lumped\"`` / ``\"wire\"`` / ``\"msl\"`` per port, same order.\nz0_ref : (n_ports,) float\n Power-wave reference impedance per port: the registered port\n impedance for lumped/wire, analytic Hammerstad-Jensen Z0 for MSL.\nsettling_db : (n_ports,) float, optional\n Per-drive pole-tail amplitude share in dB over recorded S channels\n and witness probes at the extraction bins.\ns21_power_witness : np.ndarray | None\n (n_msl, n_lw, n_freqs) real — extractor-independent |S21|\n cross-check for lumped/wire-driven columns: the MSL arriving\n power-wave magnitude over ``|a_drive|`` reconstructed from the\n delivered power ``P_del = 0.5*Re(Z_in)*|I|^2`` and\n ``(1 - |S_jj|^2)`` (does not trust the port-cell a-wave\n magnitude; issue #313 triangulation).\nreliable : np.ndarray | None\n (n_msl, n_freqs) bool — relative low-signal mask from each MSL\n port's own driven run. A False entry is not by itself proof of\n an incorrect S-matrix; see :class:`MSLSMatrixResult`.\nprobe_clearance : tuple[MSLProbeClearance, ...], optional\n MSL-only downstream layout diagnoses, in MSL registration order.\n Lumped/wire ports have no entries here, as with ``reliable``.\n Same contract as :attr:`MSLSMatrixResult.probe_clearance`, including\n what the ``insufficient`` status costs and what to gate on (#726):\n the FITTED Z0/beta go unreadable, ``S`` carries a measured 0.009 dB\n caveat, and ``reliable`` gates neither.\nbeta_railed : np.ndarray | None\n (n_msl, n_freqs) bool — β-scan rail mask from each MSL port's\n own driven run, same criterion as\n :attr:`MSLSMatrixResult.beta_railed` (issue #681). In this lane\n the N-probe fit is DIAGNOSTIC ONLY (the |Zc| deviation warning);\n a True bin means that diagnostic's β/|Zc| are the scan-window\n limit, not a measurement. Fitted beta/Z0 do not enter S, but\n this does not certify their shared measured V/I.\nS_raw / passivity_correction :\n As in :class:`MSLSMatrixResult` — set only when the passivity\n projection touched at least one bin.", "kind": "class", "name": "rfx.MixedSMatrixResult", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "S" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "tuple[str, ...]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "tuple[str, ...]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_families" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z0_ref" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "s21_power_witness" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reliable" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "S_raw" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "passivity_correction" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta_railed" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "S_wave" }, { "annotation": "str", "default": "'wave'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "magnitude_channel" }, { "annotation": "tuple[MSLProbeClearance, ...] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_clearance" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_witness" }, { "annotation": "tuple[Diagnostic, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "diagnostics" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#MixedSMatrixResult", "returns": { "annotation": "None" }, "signature": "(S: 'np.ndarray', freqs: 'np.ndarray', port_names: 'tuple[str, ...]', port_families: 'tuple[str, ...]', z0_ref: 'np.ndarray', settling_db: 'np.ndarray | None' = None, s21_power_witness: 'np.ndarray | None' = None, reliable: 'np.ndarray | None' = None, S_raw: 'np.ndarray | None' = None, passivity_correction: 'np.ndarray | None' = None, beta_railed: 'np.ndarray | None' = None, S_wave: 'np.ndarray | None' = None, magnitude_channel: 'str' = 'wave', probe_clearance: 'tuple[MSLProbeClearance, ...] | None' = None, settling_witness: 'tuple | None' = None, diagnostics: 'tuple[Diagnostic, ...]' = ()) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1790", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Gaussian-envelope modulated carrier (Meep-style source).\n\ns(t) = amplitude * sin(2π·f0·t) * exp(-((t - t0) / tau)^2)\n\nThe carrier-centered spectrum generally reduces low-frequency/DC content\nrelative to a differentiated Gaussian. A finite sampled pulse does not in\ngeneral have an exactly zero integral, so DC-sensitive calculations should\ninspect the sampled spectrum and fields explicitly.\n\nDC suppression is set by the envelope width: the spectrum is a Gaussian\ncentered at f0, and its value at DC relative to the carrier peak is\ne^(-1/bandwidth^2) — about 0.5 at bandwidth=1.2 but 0.018 at\nbandwidth=0.5. Wide fractional bandwidths therefore keep substantial DC\ndrive; when the net deposited charge of a soft source matters (e.g. the\n``until_decay`` interior-energy stop, issue #388), use bandwidth <= 0.4\n(measured relative DC 4.0e-4 at the issue-#388 demo scale — below the\nrun() warning's 1e-3 threshold, which bandwidth=0.5 at ~2.6e-2 still\nexceeds) or a :class:`GaussianPulse` with a higher ``cutoff``.\n\nParameters\n----------\nf0 : float\n Center/carrier frequency (Hz).\nbandwidth : float\n Fractional bandwidth (0–1). Default 0.5.\namplitude : float\n Peak amplitude. Default 1.0.\ncutoff : float\n Number of tau before the envelope peak. Controls how gradually\n the source turns on. Default 5.0 (Meep convention: source starts\n at t=0 and peaks at t = cutoff * tau). Use 3.0 for a faster\n onset with a slightly non-zero initial amplitude.", "kind": "class", "name": "rfx.ModulatedGaussian", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "float", "default": "5.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cutoff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ModulatedGaussian", "returns": { "annotation": "None" }, "signature": "(f0: 'float', bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, cutoff: 'float' = 5.0) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/sources.py#L274", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Near-to-far-field transform surface (Huygens box).\n\nGrid indices defining a closed rectangular box. Must be inside the\ncomputational domain and outside any PEC or source regions.", "kind": "class", "name": "rfx.NTFFBox", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i_hi" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "j_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "j_hi" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "k_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "k_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_lo_x" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_hi_x" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_lo_y" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_hi_y" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_lo_z" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_hi_z" }, { "annotation": "ForwardRef('bool')", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "face_centre" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_x_lo" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_x_hi" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_y_lo" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_y_hi" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_z_lo" }, { "annotation": "ForwardRef('float')", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "w_z_hi" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#NTFFBox", "returns": { "annotation": null }, "signature": "(i_lo: ForwardRef('int'), i_hi: ForwardRef('int'), j_lo: ForwardRef('int'), j_hi: ForwardRef('int'), k_lo: ForwardRef('int'), k_hi: ForwardRef('int'), freqs: ForwardRef('jnp.ndarray'), cpml_lo_x: ForwardRef('int | None') = None, cpml_hi_x: ForwardRef('int | None') = None, cpml_lo_y: ForwardRef('int | None') = None, cpml_hi_y: ForwardRef('int | None') = None, cpml_lo_z: ForwardRef('int | None') = None, cpml_hi_z: ForwardRef('int | None') = None, face_centre: ForwardRef('bool') = False, w_x_lo: ForwardRef('float') = 0.5, w_x_hi: ForwardRef('float') = 0.5, w_y_lo: ForwardRef('float') = 0.5, w_y_hi: ForwardRef('float') = 0.5, w_z_lo: ForwardRef('float') = 0.5, w_z_hi: ForwardRef('float') = 0.5)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L35", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Accumulated DFT of tangential fields on 6 faces.\n\nx faces store [ey, ez, hy, hz], y faces [ex, ez, hx, hz],\nz faces [ex, ey, hx, hy]. Shape: (n_freqs, face_n1, face_n2, 4).\n\nKahan compensation arrays (c_*) maintain near-float64 precision in\ncomplex64 accumulation over thousands of timesteps. The value read by the\nfar-field transform is ``x_lo`` (the compensated running sum); ``c_x_lo``\nis the running Kahan residual carried to the next add, not added at read.", "kind": "class", "name": "rfx.NTFFData", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "y_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "y_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_x_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_x_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_y_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_y_hi" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_z_lo" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "c_z_hi" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#NTFFData", "returns": { "annotation": null }, "signature": "(x_lo: ForwardRef('jnp.ndarray'), x_hi: ForwardRef('jnp.ndarray'), y_lo: ForwardRef('jnp.ndarray'), y_hi: ForwardRef('jnp.ndarray'), z_lo: ForwardRef('jnp.ndarray'), z_hi: ForwardRef('jnp.ndarray'), c_x_lo: ForwardRef('jnp.ndarray') = None, c_x_hi: ForwardRef('jnp.ndarray') = None, c_y_lo: ForwardRef('jnp.ndarray') = None, c_y_hi: ForwardRef('jnp.ndarray') = None, c_z_lo: ForwardRef('jnp.ndarray') = None, c_z_hi: ForwardRef('jnp.ndarray') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L119", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "A complete six-face surface, in global physical coordinates.\n\n``E_t`` and ``H_t`` have shape (frequency, sample, xyz); their normal\ncomponents are zero. They are the raw running DFT integrals, NOT CW\nphasors: sum(field * exp(-j*omega*t) * dt). Units are V*s/m and A*s/m.\nE and H already have their own Yee timestamps; do not shift H again.\n``J_s`` = n cross H [A*s/m], ``M_s`` = -n cross E [V*s/m]. Multiply by\n``areas`` [m^2] for integrated current moments. No source normalization,\nfactor of two, phase-origin translation or distance scaling is applied.\n\nFaces are x_lo, x_hi, y_lo, y_hi, z_lo, z_hi. Within each face, samples\nfollow C order along the two increasing tangential coordinate axes.\n``face_offsets`` gives the seven boundaries of these sample slices.\nPositions [m], normals and areas have shape (sample, 3), (sample, 3),\nand (sample,). Frequencies are in Hz. Arrays are owned, read-only copies.\n\nClock metadata describes complete consecutive accumulation steps:\nE at (step_start + n + 1)*dt, H half a step earlier. The caller must\nsupply the ACTUAL run dt and record range; NTFFData cannot verify them.\nA free-space Huygens consumer additionally requires a closed surface in\nhomogeneous, source-free material outside PML enclosing the scatterer.\nExport alone does not certify these simulation/material conditions.", "kind": "class", "name": "rfx.NTFFSurface", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "positions" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "normals" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "areas" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "E_t" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "H_t" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "face_offsets" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "step_start" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_subtracted" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(freqs: 'np.ndarray', positions: 'np.ndarray', normals: 'np.ndarray', areas: 'np.ndarray', E_t: 'np.ndarray', H_t: 'np.ndarray', face_offsets: 'np.ndarray', dt: 'float', n_steps: 'int', step_start: 'int' = 0, reference_subtracted: 'bool' = False) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ntff_surface.py#L24", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Non-uniform grid with per-axis cell-size arrays.\n\n``dx`` / ``dy`` are the BOUNDARY cell sizes (used by CPML and any\nlegacy code that reads a scalar spacing); ``dx_arr`` / ``dy_arr`` /\n``dz`` hold the per-cell spacings. In the uniform-xy case,\n``dx_arr`` is ``jnp.full(nx, dx)`` and ``dy_arr`` is analogous.\n\n``pad_{axis}_{lo|hi}`` mirror ``rfx.grid.Grid`` per-face padding —\na face whose token is ``pmc``/``pec``/``periodic`` gets 0 cells on\nthat side even when the axis as a whole uses CPML. For back-compat\nthe six fields default to ``cpml_layers`` on every face (the\npre-per-face-allocation symmetric layout).", "kind": "class", "name": "rfx.NonUniformGrid", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "nx" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ny" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "nz" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx_arr" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy_arr" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz" }, { "annotation": "ForwardRef('float | jax.Array')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_layers" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dx" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dy" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dz" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dx_h" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dy_h" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inv_dz_h" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_x_lo" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_x_hi" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_y_lo" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_y_hi" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_z_lo" }, { "annotation": "ForwardRef('int')", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pad_z_hi" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx_arr_f64" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy_arr_f64" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz_f64" }, { "annotation": "ForwardRef('dict[str, int] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "face_layers" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#NonUniformGrid", "returns": { "annotation": null }, "signature": "(nx: ForwardRef('int'), ny: ForwardRef('int'), nz: ForwardRef('int'), dx: ForwardRef('float'), dy: ForwardRef('float'), dx_arr: ForwardRef('jnp.ndarray'), dy_arr: ForwardRef('jnp.ndarray'), dz: ForwardRef('jnp.ndarray'), dt: ForwardRef('float | jax.Array'), cpml_layers: ForwardRef('int'), inv_dx: ForwardRef('jnp.ndarray'), inv_dy: ForwardRef('jnp.ndarray'), inv_dz: ForwardRef('jnp.ndarray'), inv_dx_h: ForwardRef('jnp.ndarray'), inv_dy_h: ForwardRef('jnp.ndarray'), inv_dz_h: ForwardRef('jnp.ndarray'), pad_x_lo: ForwardRef('int') = 0, pad_x_hi: ForwardRef('int') = 0, pad_y_lo: ForwardRef('int') = 0, pad_y_hi: ForwardRef('int') = 0, pad_z_lo: ForwardRef('int') = 0, pad_z_hi: ForwardRef('int') = 0, dx_arr_f64: ForwardRef('np.ndarray | None') = None, dy_arr_f64: ForwardRef('np.ndarray | None') = None, dz_f64: ForwardRef('np.ndarray | None') = None, face_layers: ForwardRef('dict[str, int] | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/nonuniform.py#L57", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of an optimization run.\n\nAttributes\n----------\neps_design : (nx_d, ny_d, nz_d) float array\n Optimized permittivity in the design region.\nloss_history : list of float\n Objective value at each iteration.\nlatent : jnp.ndarray\n Final latent parameters (pre-sigmoid).", "kind": "class", "name": "rfx.OptimizeResult", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_design" }, { "annotation": "list[float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "loss_history" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "latent" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#OptimizeResult", "returns": { "annotation": "None" }, "signature": "(eps_design: 'jnp.ndarray', loss_history: 'list[float]', latent: 'jnp.ndarray') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L50", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "A static solid box with explicitly oriented body axes.\n\n``center`` and positive ``size`` are in metres. The columns of the\nproper orthogonal ``rotation`` matrix are the body axes in simulation\ncoordinates. Inputs are copied to immutable tuples; geometry and mesh\ncoordinates must be concrete. Rotation is checked in host float64 to\n32 machine epsilons, without projecting an invalid matrix onto SO(3).\n\n``mask`` / ``mask_on_coords`` sample nodes, with half-open body bounds\n``-size/2 <= rotation.T @ (point-center) < size/2``. Material assembly\nexplicitly samples physical cell centres instead. This opt-in volume\ndoes not change :class:`Box`'s sampling convention. Subpixel smoothing,\nconformal weights and thin-conductor sheet conversion are unsupported.", "kind": "class", "name": "rfx.OrientedBox", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "center" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "size" }, { "annotation": "tuple[tuple[float, float, float], ...]", "default": "((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "rotation" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(center: 'tuple[float, float, float]', size: 'tuple[float, float, float]', rotation: 'tuple[tuple[float, float, float], ...]' = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/csg.py#L387", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Single PCB layer (copper or dielectric).\n\nParameters\n----------\nthickness : float\n Layer thickness in metres.\nmaterial : str\n Material identifier — must be a key in ``MATERIAL_LIBRARY``\n (e.g. ``\"copper\"``, ``\"fr4\"``, ``\"rogers4003c\"``) or a known\n alias (``\"prepreg\"``). Users may also register custom materials\n on the :class:`Simulation` object.\nname : str or None\n Optional human-readable label (e.g. ``\"top\"``, ``\"core\"``).\n Named layers can be looked up with :meth:`Stackup.get_layer_z`.", "kind": "class", "name": "rfx.PCBLayer", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "thickness" }, { "annotation": "str", "default": "'copper'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "material" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#PCBLayer", "returns": { "annotation": "None" }, "signature": "(thickness: 'float', material: 'str' = 'copper', name: 'str | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pcb.py#L80", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Define a multi-dimensional parameter sweep.\n\nParameters are given as keyword arguments, each mapping to an array\nof values. The sweep iterates over the full Cartesian product.\n\nExample\n-------\n>>> sweep = ParameterSweep(width=[0.01, 0.02], eps_r=[2.0, 4.0])\n>>> sweep.total\n4\n>>> list(sweep.combinations())\n[{'width': 0.01, 'eps_r': 2.0}, {'width': 0.01, 'eps_r': 4.0}, ...]", "kind": "class", "name": "rfx.ParameterSweep", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "params" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ParameterSweep", "returns": { "annotation": null }, "signature": "(**params)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L39", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Pareto frontier artifact for a finite set of objective vectors.", "kind": "class", "name": "rfx.ParetoFront", "parameters": [ { "annotation": "ForwardRef('tuple[ParetoPoint, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "points" }, { "annotation": "ForwardRef('tuple[bool, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "minimize" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective_names" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_count" }, { "annotation": "ForwardRef('tuple[int, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "front_indices" }, { "annotation": "ForwardRef('tuple[int, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dominated_indices" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ParetoFront", "returns": { "annotation": null }, "signature": "(points: ForwardRef('tuple[ParetoPoint, ...]'), minimize: ForwardRef('tuple[bool, ...]'), objective_names: ForwardRef('tuple[str, ...]'), source_count: ForwardRef('int'), front_indices: ForwardRef('tuple[int, ...]'), dominated_indices: ForwardRef('tuple[int, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L50", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One candidate in a Pareto front.", "kind": "class", "name": "rfx.ParetoPoint", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_index" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "id" }, { "annotation": "ForwardRef('tuple[float, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "ForwardRef('Mapping[str, object] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "metadata" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ParetoPoint", "returns": { "annotation": null }, "signature": "(source_index: ForwardRef('int'), id: ForwardRef('str'), objectives: ForwardRef('tuple[float, ...]'), metadata: ForwardRef('Mapping[str, object] | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L32", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Wire defined by a polyline path with constant circular cross-section.\n\nVoxelizes by computing the distance from each grid point to the nearest\nline segment of the polyline. Grid points within ``radius`` of any\nsegment are marked as inside.\n\nParameters\n----------\npoints : tuple of tuple[float, float, float]\n Ordered vertices in metres, e.g. ((x0,y0,z0), (x1,y1,z1), ...).\nradius : float\n Wire radius in metres. For PEC realization, a positive radius must\n be at least half the smallest local cell at the vertices (a volume\n wire). Smaller positive radii refuse; refine the mesh to resolve\n the wire. Zero retains the legacy lattice filament without a\n declared physical radius.", "kind": "class", "name": "rfx.PolylineWire", "parameters": [ { "annotation": "tuple[tuple[float, float, float], ...]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "points" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radius" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#PolylineWire", "returns": { "annotation": "None" }, "signature": "(points: 'tuple[tuple[float, float, float], ...]', radius: 'float') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/csg.py#L552", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Metadata for a raw port-observable dump.\n\nThe schema is intentionally explicit because dump replays are physics\nevidence, not just regression fixtures. At minimum, claims-bearing dumps\nshould record the commit, geometry/material/grid/boundary setup, port and\nreference-plane definitions, waveform, time step, frequency grid, raw\nphasor convention, and the production S-matrix being audited.", "kind": "class", "name": "rfx.PortDumpMetadata", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "commit_hash" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "boundaries" }, { "annotation": "tuple[Mapping[str, Any], ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_definitions" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_planes" }, { "annotation": "Mapping[str, Any]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveform" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt_s" }, { "annotation": "tuple[float, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "frequency_grid_hz" }, { "annotation": "str", "default": "'V/I'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "raw_phasor_type" }, { "annotation": "str", "default": "'exp(-j omega t)'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "phase_convention" }, { "annotation": "str", "default": "'positive_into_dut'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_convention" }, { "annotation": "str", "default": "'port_branch'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "diagonal_frame" }, { "annotation": "str", "default": "'port coordinate is positive into the DUT; positive offset moves the raw measurement plane toward the reported reference plane'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_plane_shift_convention" }, { "annotation": "str", "default": "'S[receiver_port, driven_port, frequency_index]'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "production_smatrix_schema" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "notes" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(commit_hash: 'str', geometry: 'Mapping[str, Any]' = , materials: 'Mapping[str, Any]' = , grid: 'Mapping[str, Any]' = , boundaries: 'Mapping[str, Any]' = , port_definitions: 'tuple[Mapping[str, Any], ...]' = (), reference_planes: 'Mapping[str, Any]' = , waveform: 'Mapping[str, Any]' = , dt_s: 'float | None' = None, frequency_grid_hz: 'tuple[float, ...]' = (), raw_phasor_type: 'str' = 'V/I', phase_convention: 'str' = 'exp(-j omega t)', current_convention: 'str' = 'positive_into_dut', diagonal_frame: 'str' = 'port_branch', reference_plane_shift_convention: 'str' = 'port coordinate is positive into the DUT; positive offset moves the raw measurement plane toward the reported reference plane', production_smatrix_schema: 'str' = 'S[receiver_port, driven_port, frequency_index]', notes: 'str' = '') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L42", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Comparison between independent replay and production S-matrix output.", "kind": "class", "name": "rfx.PortReplayComparison", "parameters": [ { "annotation": "bool", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ok" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "max_abs_diff" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "max_allowed" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_ports" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_freqs" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "atol" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rtol" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(ok: 'bool', max_abs_diff: 'float', max_allowed: 'float', n_ports: 'int', n_freqs: 'int', atol: 'float', rtol: 'float') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L128", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Canonical S-matrix-like RF port observable.\n\nParameters\n----------\ns_params\n Complex array with shape ``(n_ports, n_ports, n_freqs)``.\nfreqs\n One-dimensional frequency array in Hz with length ``n_freqs``.\nport_names\n Unique names for the ``n_ports`` rows/columns.\nsource\n Human-readable provenance label used in validation diagnostics.", "kind": "class", "name": "rfx.PortSMatrixObservable", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "tuple[str, ...]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "str", "default": "'port_smatrix'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(s_params: 'np.ndarray', freqs: 'np.ndarray', port_names: 'tuple[str, ...]', source: 'str' = 'port_smatrix') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L20", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Raw V/I phasor dump for independent S-matrix replay.\n\nArrays use shape ``(n_driven, n_ports, n_freqs)``. The replay function\nrecomputes ``S[receiver, driven, frequency]`` from these raw phasors and\nnever calls the production extractor being audited.", "kind": "class", "name": "rfx.PortVIDump", "parameters": [ { "annotation": "Mapping[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "metadata" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "voltages" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "currents" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_impedances" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "tuple[int, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "driven_port_indices" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "production_smatrix" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_plane_offsets_m" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "propagation_constants" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(metadata: 'Mapping[str, Any]', freqs: 'np.ndarray', voltages: 'np.ndarray', currents: 'np.ndarray', port_impedances: 'np.ndarray', port_names: 'tuple[str, ...]' = (), driven_port_indices: 'tuple[int, ...]' = (), production_smatrix: 'np.ndarray | None' = None, reference_plane_offsets_m: 'np.ndarray | None' = None, propagation_constants: 'np.ndarray | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L107", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One validation diagnostic for an RF port observable.", "kind": "class", "name": "rfx.PortValidationIssue", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "code" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "message" }, { "annotation": "str", "default": "'error'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "severity" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "frequency_index" }, { "annotation": "tuple[int, ...] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_indices" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "value" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "limit" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#PortValidationIssue", "returns": { "annotation": "None" }, "signature": "(code: 'str', message: 'str', severity: 'str' = 'error', frequency_index: 'int | None' = None, port_indices: 'tuple[int, ...] | None' = None, value: 'float | None' = None, limit: 'float | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L149", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Validation result returned by :func:`validate_port_smatrix`.", "kind": "class", "name": "rfx.PortValidationReport", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_ports" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_freqs" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "tuple[PortValidationIssue, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "issues" }, { "annotation": "Mapping[str, float]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "metrics" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#PortValidationReport", "returns": { "annotation": "None" }, "signature": "(source: 'str', n_ports: 'int' = 0, n_freqs: 'int' = 0, port_names: 'tuple[str, ...]' = (), issues: 'tuple[PortValidationIssue, ...]' = (), metrics: 'Mapping[str, float]' = ) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L162", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of a progressive_optimize run.\n\nAttributes\n----------\nstages : list of OptimizeResult\n Per-stage optimize() output, in schedule order.\nfinal_eps_design : jnp.ndarray\n Optimized permittivity at the finest stage's design-region shape.\nfinal_latent : jnp.ndarray\n Final latent at the finest stage's shape.\nloss_history : list of float\n Concatenated loss across all stages.\nstage_boundaries : list of int\n Iteration index where each stage starts (cumulative sum of\n ``n_iters``). Useful for plotting.", "kind": "class", "name": "rfx.ProgressiveOptimizeResult", "parameters": [ { "annotation": "list[OptimizeResult]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "stages" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "final_eps_design" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "final_latent" }, { "annotation": "list[float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "loss_history" }, { "annotation": "list[int]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "stage_boundaries" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ProgressiveOptimizeResult", "returns": { "annotation": "None" }, "signature": "(stages: 'list[OptimizeResult]', final_eps_design: 'jnp.ndarray', final_latent: 'jnp.ndarray', loss_history: 'list[float]', stage_boundaries: 'list[int]') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L685", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One resolution stage in a progressive_optimize schedule.\n\nAttributes\n----------\ndx : float\n Target cell size for this stage (metres). Passed to ``sim_factory``.\nn_iters : int\n Number of Adam iterations at this resolution.\nlr : float\n Learning rate for this stage (defaults to 0.01).\nnum_periods : float\n Periods at freq_max for auto n_steps computation (default 20).\nn_steps : int or None\n Explicit step count override. None -> auto from ``num_periods``.", "kind": "class", "name": "rfx.ProgressiveStage", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_iters" }, { "annotation": "float", "default": "0.01", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lr" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "num_periods" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ProgressiveStage", "returns": { "annotation": "None" }, "signature": "(dx: 'float', n_iters: 'int', lr: 'float' = 0.01, num_periods: 'float' = 20.0, n_steps: 'int | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L661", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Radar cross section computation result.\n\nfreqs : (n_freqs,) Hz\ntheta : (n_theta,) radians\nphi : (n_phi,) radians\nrcs_dbsm : (n_freqs, n_theta, n_phi) in dBsm\nrcs_linear : (n_freqs, n_theta, n_phi) in m^2\nmonostatic_rcs : (n_freqs,) backscatter RCS in dBsm, evaluated\n exactly at the backscatter direction (opposite the incident\n propagation vector), independent of the theta/phi observation\n grid. For normal-incidence +x propagation this is\n (theta=pi/2, phi=pi), i.e. -x.\n\nVALIDATION SCOPE (read before trusting the full pattern)\n-------------------------------------------------------\n``monostatic_rcs`` is compared with exact Mie in the committed\n``tests/fixtures/rcs_sphere_mie/`` PEC-sphere case. The default unsubtracted\n``rcs_dbsm`` / ``rcs_linear`` bistatic pattern is NOT validated: the NTFF side faces\nrecord the full incident field inside the total-field slab, and\nincreasing ``ntff_offset`` alone does not remove it. Results produced by\n``compute_rcs(..., subtract_incident_reference=True)`` use two-run complex\nfar-field subtraction; that path is validated only for the documented\nka~1 sphere comparison. ``RCSResult`` does not record which option produced\nit, so retain the call configuration with archived results. See\n``compute_rcs`` (\"Bistatic pattern caveat\") for limits and convergence\nchecks.", "kind": "class", "name": "rfx.RCSResult", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rcs_dbsm" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rcs_linear" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "monostatic_rcs" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_witness" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#RCSResult", "returns": { "annotation": null }, "signature": "(freqs: ForwardRef('np.ndarray'), theta: ForwardRef('np.ndarray'), phi: ForwardRef('np.ndarray'), rcs_dbsm: ForwardRef('np.ndarray'), rcs_linear: ForwardRef('np.ndarray'), monostatic_rcs: ForwardRef('np.ndarray'), settling_db: ForwardRef('float | None') = None, settling_witness: ForwardRef('dict | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/rcs.py#L39", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Structured result from an RIS parameter sweep.\n\nAttributes\n----------\nphases : (n_params, n_freqs) ndarray\n Reflection phase in degrees.\namplitudes : (n_params, n_freqs) ndarray\n Reflection amplitude (linear, 0-1).\nfreqs : (n_freqs,) ndarray\n Frequency points in Hz.\ncapacitances : (n_params,) ndarray or None\n Swept capacitance values (None for angle sweeps).\nangles : (n_params,) ndarray or None\n Swept scan angles in degrees (None for capacitance sweeps).", "kind": "class", "name": "rfx.RISSweepResult", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phases" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitudes" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "capacitances" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "angles" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#RISSweepResult", "returns": { "annotation": "None" }, "signature": "(phases: 'np.ndarray', amplitudes: 'np.ndarray', freqs: 'np.ndarray', capacitances: 'np.ndarray | None' = None, angles: 'np.ndarray | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ris.py#L43", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "RIS unit cell simulation wrapper.\n\nAutomates: periodic BC + Floquet port + sweep bias/geometry\nto produce reflection phase / amplitude curves.\n\nParameters\n----------\ncell_size : (Lx, Ly) in metres\n Unit cell lateral dimensions.\nsubstrate_thickness : float\n Substrate thickness in metres.\nsubstrate_material : str\n Substrate material name (must be in ``MATERIAL_LIBRARY`` or\n registered as custom). Default ``\"fr4\"``.\nfreq_range : (f_min, f_max) in Hz\n Frequency range for analysis.\nn_freqs : int\n Number of frequency points. Default 21.\nscan_angles : list of (theta, phi) or None\n Default scan angles for characterisation. If None, broadside only.\npolarization : str\n ``\"te\"`` or ``\"tm\"``. Default ``\"te\"``.\nn_steps : int\n Number of FDTD timesteps per simulation. Default 300.\ndx : float or None\n Uniform cell size. Required when a varactor is added; otherwise\n auto-computed if None.\ncpml_layers : int\n CPML layers on the port-normal axis. Default 8.\nground_plane : bool\n Whether to include a PEC ground plane below the substrate.\n Default True (standard RIS backed by metal).", "kind": "class", "name": "rfx.RISUnitCell", "parameters": [ { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "cell_size" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "substrate_thickness" }, { "annotation": "str", "default": "'fr4'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "substrate_material" }, { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "freq_range" }, { "annotation": "int", "default": "21", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "list[tuple[float, float]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scan_angles" }, { "annotation": "str", "default": "'te'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polarization" }, { "annotation": "int", "default": "300", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_layers" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ground_plane" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#RISUnitCell", "returns": { "annotation": null }, "signature": "(*, cell_size: 'tuple[float, float]', substrate_thickness: 'float', substrate_material: 'str' = 'fr4', freq_range: 'tuple[float, float]', n_freqs: 'int' = 21, scan_angles: 'list[tuple[float, float]] | None' = None, polarization: 'str' = 'te', n_steps: 'int' = 300, dx: 'float | None' = None, cpml_layers: 'int' = 8, ground_plane: 'bool' = True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ris.py#L99", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Grid-resolved metadata for one RLC element.\n\nPrecomputed once and captured by the scan closure.", "kind": "class", "name": "rfx.RLCCellMeta", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "j" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "k" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "has_inductor" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "has_capacitor" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "gamma" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "D0" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt_dx_over_L" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt_over_C_dx" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dual_area" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "R" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "is_series" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(i: ForwardRef('int'), j: ForwardRef('int'), k: ForwardRef('int'), component: ForwardRef('str'), has_inductor: ForwardRef('bool'), has_capacitor: ForwardRef('bool'), gamma: ForwardRef('float'), D0: ForwardRef('float'), dx: ForwardRef('float'), dt_dx_over_L: ForwardRef('float'), dt_over_C_dx: ForwardRef('float'), dual_area: ForwardRef('float'), R: ForwardRef('float'), dt: ForwardRef('float'), is_series: ForwardRef('bool'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/lumped.py#L200", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "ADE auxiliary state for one lumped RLC element.", "kind": "class", "name": "rfx.RLCState", "parameters": [ { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inductor_current" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "capacitor_charge" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(inductor_current: ForwardRef('jnp.ndarray'), capacitor_charge: ForwardRef('jnp.ndarray'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/lumped.py#L122", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Structured simulation result.\n\nAttributes\n----------\nstate : FDTDState\n Final field state (useful for visualization).\ntime_series : (n_steps, n_probes) float array\n Probe recordings over time.\ns_params : (n_ports, n_ports, n_freqs) complex or None\n S-parameter matrix (computed only when ports are present and\n ``compute_s_params=True``). With no driven port, passive-port ratios\n from the main record are termination diagnostics, not an S-matrix\n of the structure under independent port drives.\nfreqs : (n_freqs,) float or None\n Frequency array for S-parameters.\nntff_data : NTFFData or None\n Raw NTFF DFT data (use ``compute_far_field`` for radiation pattern).\nntff_box : NTFFBox or None\n NTFF box specification (needed for ``compute_far_field``).\ndft_planes : dict[str, DFTPlaneProbe] or None\n Frequency-domain plane probes keyed by name.\nwaveguide_ports : dict[str, WaveguidePortConfig] or None\n Final accumulated waveguide-port configs keyed by name.\nwaveguide_sparams : dict[str, WaveguideSParamResult] or None\n High-level calibrated waveguide S-parameters keyed by port name.\nsnapshots : dict[str, ndarray] or None\n Field snapshots keyed by component name, each\n ``(n_steps // interval, ...)``: frame ``k`` holds the fields after\n step ``(k + 1) * interval`` (see ``SnapshotSpec``). Indexed on the\n padded lattice, like ``state``.\ngrid : Grid or None\n Grid metadata for post-processing helpers and advanced objectives.\nsettling_db : float or None\n Worst identified pole-tail share over recorded channels and read bins,\n in amplitude dB. Missing identification yields a non-pass witness.\nsettling_witness : dict or None\n Status, reason, per-bin tail shares and identification errors, and\n selected-record provenance for the value witness.", "kind": "class", "name": "rfx.Result", "parameters": [ { "annotation": "ForwardRef('object')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_box" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_planes" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "flux_monitors" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveguide_ports" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveguide_sparams" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveguide_port_flux" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshots" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_witness" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "wire_port_sparams" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ringdown" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshot_axes" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_data" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_monitor" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "realized_geometry" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sparam_time_records" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_time_records" }, { "annotation": "ForwardRef('tuple[Diagnostic, ...]')", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "diagnostics" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Result", "returns": { "annotation": null }, "signature": "(state: ForwardRef('object'), time_series: ForwardRef('jnp.ndarray'), s_params: ForwardRef('np.ndarray | None'), freqs: ForwardRef('np.ndarray | None'), ntff_data: ForwardRef('object') = None, ntff_box: ForwardRef('object') = None, dft_planes: ForwardRef('dict | None') = None, flux_monitors: ForwardRef('dict | None') = None, waveguide_ports: ForwardRef('dict | None') = None, waveguide_sparams: ForwardRef('dict | None') = None, waveguide_port_flux: ForwardRef('tuple | None') = None, snapshots: ForwardRef('dict | None') = None, grid: ForwardRef('object') = None, dt: ForwardRef('float | None') = None, freq_range: ForwardRef('tuple | None') = None, settling_db: ForwardRef('float | None') = None, settling_witness: ForwardRef('dict | None') = None, wire_port_sparams: ForwardRef('tuple | None') = None, ringdown: ForwardRef('object') = None, snapshot_axes: ForwardRef('dict | None') = None, current_moment_data: ForwardRef('object') = None, current_moment_monitor: ForwardRef('object') = None, realized_geometry: ForwardRef('object') = None, sparam_time_records: ForwardRef('tuple | None') = None, dft_time_records: ForwardRef('object') = None, diagnostics: ForwardRef('tuple[Diagnostic, ...]') = ())", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L655", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One incident-polarization column of a phase-referenced scattering matrix.\n\nWith the ``exp(+j omega t)`` convention, the outgoing field at\n``reference_position + R * s_hat`` is ``exp(-jkR) / R`` times\n``(F_theta, F_phi) * E_inc(reference_position)``. F has units of metres,\nshape ``(n_freqs, n_theta, n_phi)``, and uses the spherical output basis\nof ``rcs.theta``/``rcs.phi``. Run both ``ey`` and ``ez`` for two columns.\n``incident_spectrum`` is the actual E-field DFT at that reference, not\nthe source waveform. Grid/record convergence still bounds accuracy.", "kind": "class", "name": "rfx.ScatteringResponse", "parameters": [ { "annotation": "ForwardRef('RCSResult')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rcs" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "F_theta" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "F_phi" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "incident_spectrum" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_position" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "polarization" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ScatteringResponse", "returns": { "annotation": null }, "signature": "(rcs: ForwardRef('RCSResult'), F_theta: ForwardRef('np.ndarray'), F_phi: ForwardRef('np.ndarray'), incident_spectrum: ForwardRef('np.ndarray'), reference_position: ForwardRef('np.ndarray'), polarization: ForwardRef('str'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/rcs.py#L77", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One PEC sheet: a node footprint on ONE plane, zero thickness (§1.3).\n\n``footprint`` is a boolean ``(nx, ny, nz)`` NODE mask that is True only\non layer ``plane`` along ``normal_axis`` (the full-shape layout keeps it\ninterchangeable with ``SheetImpedanceSpec.mask``, so a lossy f0 sheet\nand a PEC sheet are one footprint with a different operator — the #677\nG4 identity by construction). ``plane`` is a static Python int: a\nsheet's plane is never a traced quantity (the ``argmin`` cliff). A\nsheet owns NO cell — it adds nothing to the cell mask and writes no\nmaterial.", "kind": "class", "name": "rfx.SheetSpec", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "normal_axis" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "plane" }, { "annotation": "object", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "footprint" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "unwrapped_footprint" }, { "annotation": "tuple", "default": "(None, None, None)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "end_rows" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "drawn" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(normal_axis: 'int', plane: 'int', footprint: 'object', name: 'str | None' = None, unwrapped_footprint: 'object | None' = None, end_rows: 'tuple' = (None, None, None), drawn: 'tuple | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/boundaries/pec.py#L202", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Auto-derived simulation configuration.", "kind": "class", "name": "rfx.SimConfig", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "domain" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_layers" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "margin" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "accuracy" }, { "annotation": "str", "default": "'j_source'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_type" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_info" }, { "annotation": "list[str]", "default": "", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "warnings" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz_profile" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "boundary" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#SimConfig", "returns": { "annotation": "None" }, "signature": "(dx: 'float', domain: 'tuple[float, float, float]', cpml_layers: 'int', n_steps: 'int', freq_range: 'tuple[float, float]', margin: 'float', dt: 'float', accuracy: 'str', source_type: 'str' = 'j_source', source_info: 'str' = '', warnings: 'list[str]' = , dz_profile: 'np.ndarray | None' = None, boundary: 'str' = 'cpml') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/auto_config.py#L231", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compiled simulation output.\n\ntime_series : (n_steps, n_probes) float array, or (n_steps, 0) if\n no probes were specified.\nntff_data : NTFFData or None\n Accumulated near-to-far-field DFT data (if NTFF box was used).\ndft_planes : tuple[DFTPlaneProbe, ...] or None\n Final accumulated DFT plane probes.\nwaveguide_ports : tuple[WaveguidePortConfig, ...] or None\n Final accumulated waveguide-port configs.\nwire_port_sparams : tuple | None\n Final V/I/V_inc DFT accumulators for wire port S-params.\nlumped_port_sparams : tuple | None\n Final V/I DFT accumulators for lumped port S-params (issue #72).\n Each entry is ``(LumpedPortSParamSpec, (v_dft, i_dft, v_ref_dft))``;\n v/i are POST-injection (i with the Yee half-step phase) and\n v_ref is the PRE-injection drive sample.\nwire_refplane_sparams : tuple | None\n Final reference-plane V/I DFT accumulators for the opt-in wire\n S-matrix plane path (issue #313). Each entry is\n ``(WireRefPlaneSpec, (v_dft, i_minus_dft, i_plus_dft))``; two\n entries per opted port (plane slots 0 and 1).\nsnapshots : dict[str, ndarray] or None\n Field snapshots keyed by component name, each\n ``(n_steps // interval, ...)``; see ``SnapshotSpec``.\nntff_box : NTFFBox or None\n NTFF box specification used for accumulation.\ngrid : Grid or None\n Grid metadata needed by post-processing / objective helpers.\nsnapshot_axes : dict[str, rfx.snapshots.SnapshotAxes] or None\n Per snapshot component: sample coordinates in metres, the slice\n plane, and the step count and time of each frame (#1259). ``None``\n when no snapshot was recorded.\ndt : float or None\n The time step the scan actually advanced by, in seconds. It is\n ``grid.dt`` except under ``stencil_order=4``, whose step is derated\n by ``_ORDER4_CFL_FACTOR``; the time series and every frame are\n sampled at this step, so time and frequency must be read with it,\n not with ``grid.dt``.\ncurrent_moment_data : (accumulator, kahan) or None\n Block current moments accumulated inside the time loop\n (``rfx.current_moments``). The accumulator is\n ``(n_freqs, n_blocks, 3, n_weights)``.\ncurrent_moment_monitor : CurrentMomentMonitor or None\n The slab, block map and centres those moments belong to.", "kind": "class", "name": "rfx.SimResult", "parameters": [ { "annotation": "ForwardRef('FDTDState | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_planes" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "flux_monitors" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveguide_ports" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "wire_port_sparams" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lumped_port_sparams" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshots" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_box" }, { "annotation": "ForwardRef('Grid | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "wire_refplane_sparams" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshot_axes" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_data" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "current_moment_monitor" }, { "annotation": "ForwardRef('object')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "adjoint_settling" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sparam_time_records" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_time_records" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#SimResult", "returns": { "annotation": null }, "signature": "(state: ForwardRef('FDTDState | None'), time_series: ForwardRef('jnp.ndarray'), ntff_data: ForwardRef('object') = None, dft_planes: ForwardRef('tuple | None') = None, flux_monitors: ForwardRef('tuple | None') = None, waveguide_ports: ForwardRef('tuple | None') = None, wire_port_sparams: ForwardRef('tuple | None') = None, lumped_port_sparams: ForwardRef('tuple | None') = None, snapshots: ForwardRef('dict | None') = None, ntff_box: ForwardRef('object') = None, grid: ForwardRef('Grid | None') = None, wire_refplane_sparams: ForwardRef('tuple | None') = None, snapshot_axes: ForwardRef('dict | None') = None, dt: ForwardRef('float | None') = None, current_moment_data: ForwardRef('object') = None, current_moment_monitor: ForwardRef('object') = None, adjoint_settling: ForwardRef('object') = None, sparam_time_records: ForwardRef('tuple | None') = None, dft_time_records: ForwardRef('tuple | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L274", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Declarative FDTD simulation builder.\n\nParameters\n----------\nfreq_max : float\n Maximum simulation frequency (Hz).\ndomain : (Lx, Ly, Lz) in metres\n Physical domain size. For 2D modes Lz is ignored.\nboundary : \"pec\", \"cpml\", or \"upml\"\n Boundary condition. Default \"cpml\".\ncpml_layers : int\n Number of CPML layers per face. Default 16 (ignored for \"pec\").\ndx : float or None\n Cell size override (metres). Auto-computed if None.\nmode : str\n ``\"3d\"`` (default), ``\"2d_tmz\"`` (Ez, Hx, Hy), or\n ``\"2d_tez\"`` (Hz, Ex, Ey).\nsnap : {\"strict\", \"declared\"}\n Strict (default) refuses PEC sheets solved more than 1% off their\n drawn in-plane size. \"declared\" accepts the difference as a warning\n and records the choice in realized geometry; no solved numbers change.\ndt : float or None\n Concrete time step (s) for the NON-UNIFORM lane, used instead of\n the Courant step derived from the smallest cell. ``None`` (the\n default) keeps the derived step and is byte-identical to before;\n passing it without any of ``dz_profile`` / ``dx_profile`` /\n ``dy_profile`` is refused, because the uniform lane derives its own\n step in ``Grid.courant_dt``.\n\n Why it exists: the derived step is a function of ``min(cell)``, so a\n mesh that is a design variable moves ``dt`` as it deforms and every\n observable read off the run carries the step change alongside the\n geometry change. One pinned step makes a deformation sweep one board\n at one step. A step above the Courant limit of the REALIZED cells is\n refused, never clipped.\ndt_min_cell : float or None\n Smallest cell size (m) the caller's TRACED axes reach anywhere in\n the family they will run. Required with ``dt`` when a profile is a\n JAX tracer, because a tracer carries no host cell size for the\n limit to be measured against at build time. Concrete axes are always\n measured from their realized profile; a traced axis is measured\n against this declared floor when the run builds its mesh, and the\n run is refused if the realized cells fall below it.\nprecision : str\n ``\"float32\"`` (default), ``\"mixed\"``, or ``\"float64\"``. When\n ``\"mixed\"``, field arrays (E, H) use float16 for ~2x memory\n reduction while material coefficients and DFT accumulators stay\n float32. When ``\"float64\"``, field arrays use float64 storage\n AND the Yee update arithmetic runs at float64 (issue #630 — prior\n releases hard-pinned the Yee curl/update arithmetic to float32\n regardless of storage dtype, so float64 fields were silently\n re-quantized to float32 every timestep; the arithmetic dtype is\n now ``jnp.promote_types(field_dtype, jnp.float32)``, so\n ``\"float32\"``/``\"mixed\"`` are numerically unaffected and\n byte-identical to before). ``\"float64\"`` requires JAX's x64 mode\n to already be enabled by the caller (``jax.config.update(\n \"jax_enable_x64\", True)`` or ``jax.experimental.enable_x64()``) —\n without it JAX silently downcasts float64 arrays back to\n float32, and ``preflight()`` warns if this mismatch is detected.\n Material coefficients (``eps_r``/``sigma``/``mu_r``) and\n precomputed CPML profile arrays stay float32 either way (fixed\n setup-time constants measurably bias the primal but do not\n create the per-timestep rounding-lattice noise floor that the\n compute-dtype pin did — see issue #630's f64-lift measurement).\n ``\"mixed\"``/``\"float64\"`` are UNIFORM-SINGLE-DEVICE-LANE ONLY\n today: ``field_dtype`` is threaded only by\n ``rfx/runners/uniform.py`` — the non-uniform-mesh, distributed\n (``devices=``/``distributed=True``), and subgridded\n (``refinement``) runners do not thread it, so a non-float32\n precision there would silently run float32 fields. ``run()`` /\n ``forward()`` raise ``NotImplementedError`` rather than do that\n silently; ``preflight()`` also warns in advance for the\n non-uniform-mesh case (the distributed case is a call-time\n ``run()``/``forward()`` kwarg, invisible to preflight, so its\n `NotImplementedError` at dispatch is the only enforcement point).\n\n ACCURACY CAVEAT for ``\"mixed\"`` with a CPML boundary (issue #644):\n float16 field storage is fine for transient and field-shape work\n (measured 0.20% relative L2 error on Ez vs ``\"float32\"`` at 50\n steps), but it raises the absorber's residual floor. On the\n fixture in ``tests/unit/grid/test_mixed_precision.py`` — a 40**3 domain,\n dx = 3.0 mm, point source, 400 steps — total field energy settles\n to about -76 dB below peak under ``\"float32\"`` but only about\n -59.5 dB under ``\"mixed\"``: roughly 17 dB worse, consistent with\n float16's ~1e-3 machine epsilon quantizing the stored fields.\n Those two numbers are from that one fixture, not a universal\n bound; the floor scales with float16 epsilon, so expect the same\n order wherever the field storage is float16. Practical rule:\n ``\"mixed\"`` is not a drop-in ``\"float32\"`` substitute when the\n quantity of interest is a reflection coefficient, an S-parameter,\n or anything else living near the absorber floor — use\n ``\"float32\"`` (the default) for those.\nsolver : str\n ``\"yee\"`` (default) for the standard explicit scheme or\n ``\"adi\"`` for the experimental ADI-FDTD path. The homogeneous,\n lossless split with compatible domain boundaries removes the\n explicit CFL stability restriction. Interior PEC (sheets, wires,\n volumes) is refused at every factor on both lanes: its projection\n does not inherit that guarantee. Cavity accuracy without interior\n PEC is tested in 2D TMz (``mode=\"2d_tmz\"``, 2% resonance gate at\n 5x CFL, ``test_adi_cavity_resonance``) and 3D\n (full Zheng–Chen–Zhang two-sub-step scheme since\n 2026-07-13, issue #338: 2% PEC-cavity eigenfrequency gate at 2x\n CFL, ~15 cells/wavelength). 3D dispersion error grows ~dt^2, so\n preflight emits an ``adi_3d_accuracy`` envelope advisory when\n ``adi_cfl_factor > 2`` on a 3D grid — large factors trade\n wavelength-scale accuracy for stiff-mesh throughput.\nadi_cfl_factor : float\n Timestep multiplier relative to the grid's Yee CFL timestep when\n ``solver=\"adi\"``. Default 2.0; for quantitative wavelength-scale\n 3D results prefer <= 2.0 (see ``solver``).\nstencil_order : int\n Spatial finite-difference order for the explicit Yee update: ``2``\n (default, the standard (2,2) scheme — BYTE-IDENTICAL to prior\n releases) or ``4`` (the (2,4) fourth-order-in-space stencil). Order\n 4 is supported ONLY on the plain uniform Cartesian vacuum/dielectric\n path: boundary ``pec``/``periodic`` (NOT cpml/upml), default ``yee``\n solver (NOT adi), uniform mesh (no dz/dx/dy profile), no dispersive\n materials, no anisotropic/subpixel eps, no conformal PEC, no Kerr,\n not distributed. Any unsupported combination with\n ``stencil_order=4`` raises ``NotImplementedError``. Order 4 derates\n the timestep by ~0.857x for stability (the (2,4) CFL bound).", "kind": "class", "name": "rfx.Simulation", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_max" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "domain" }, { "annotation": "str | BoundarySpec | dict", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "int", "default": "16", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_layers" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_kappa_max" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx" }, { "annotation": "str", "default": "'3d'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dz_profile" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx_profile" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dy_profile" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt_min_cell" }, { "annotation": "str", "default": "'float32'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "precision" }, { "annotation": "str", "default": "'yee'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "solver" }, { "annotation": "float", "default": "2.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "adi_cfl_factor" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stencil_order" }, { "annotation": "str", "default": "'sampled'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "interface_eps" }, { "annotation": "str", "default": "'strict'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "snap" }, { "annotation": null, "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "_removed_kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation", "returns": { "annotation": null }, "signature": "(freq_max: 'float', domain: 'tuple[float, float, float]', *, boundary: 'str | BoundarySpec | dict' = 'cpml', cpml_layers: 'int' = 16, cpml_kappa_max: 'float' = 1.0, dx: 'float | None' = None, mode: 'str' = '3d', dz_profile: 'np.ndarray | None' = None, dx_profile: 'np.ndarray | None' = None, dy_profile: 'np.ndarray | None' = None, dt: 'float | None' = None, dt_min_cell: 'float | None' = None, precision: 'str' = 'float32', solver: 'str' = 'yee', adi_cfl_factor: 'float' = 2.0, stencil_order: 'int' = 2, interface_eps: 'str' = 'sampled', snap: 'str' = 'strict', **_removed_kwargs)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L181", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Positions and times of the samples in one recorded field array.\n\nOne per component, in ``Result.snapshot_axes[comp]`` or from\n:func:`snapshot_axes`. The array it describes has dimensions ``dims``:\n``\"frame\"`` first, then the spatial axes kept by the recording, in\n``x, y, z`` order. Every array here is read-only float64 (``steps`` is\nint64).\n\nAttributes\n----------\ncomponent : str\n ``\"ex\"`` ... ``\"hz\"``.\ndims : tuple of str\n Axis names of the recorded array, e.g. ``(\"frame\", \"x\", \"y\")`` for a\n slice normal to z, ``(\"frame\", \"x\", \"y\", \"z\")`` for a full field.\ncoords : dict[str, ndarray]\n For each spatial axis in ``dims``, the coordinate in metres of every\n sample along that axis, in the model frame (see the module docstring).\n ``len(coords[a])`` equals the array's extent along ``a``; it includes\n the CPML cells.\nstagger : (float, float, float)\n This component's offset from the E node, in cells, per axis.\nslice_axis : str or None\n ``\"x\"``, ``\"y\"`` or ``\"z\"`` for a slice, ``None`` for the full field.\nslice_index : int or None\n The recorded ``SnapshotSpec.slice_index``, a PADDED lattice index (the\n same index space as ``grid.shape`` and ``grid.position_to_index``,\n CPML cells counted), normalised to be non-negative.\nslice_coord : float or None\n Position in metres of the plane this component's slice samples lie\n on. It includes the component's own stagger along the slice axis, so\n one ``slice_index`` gives different planes for different components\n (``ez`` at ``k`` lies on ``z_{k+1/2}``, ``ex`` at ``k`` on ``z_k``).\ninterval : int\n ``SnapshotSpec.interval`` of the run.\nn_steps : int\n Time steps the run completed.\nsteps : ndarray of int64\n Steps completed when each frame was taken: ``interval, 2*interval,\n ..., (n_steps // interval) * interval``.\ntimes_s : ndarray of float64\n Time in seconds of each frame: ``steps * dt`` for E components,\n ``(steps - 1/2) * dt`` for H components.\ndt : float\n The run's time step in seconds.", "kind": "class", "name": "rfx.SnapshotAxes", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": "tuple", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dims" }, { "annotation": "Mapping[str, np.ndarray]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "coords" }, { "annotation": "tuple", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "stagger" }, { "annotation": "str | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "slice_axis" }, { "annotation": "int | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "slice_index" }, { "annotation": "float | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "slice_coord" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "interval" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "steps" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "times_s" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(component: 'str', dims: 'tuple', coords: 'Mapping[str, np.ndarray]', stagger: 'tuple', slice_axis: 'str | None', slice_index: 'int | None', slice_coord: 'float | None', interval: 'int', n_steps: 'int', steps: 'np.ndarray', times_s: 'np.ndarray', dt: 'float') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/snapshots.py#L74", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Mid-simulation field snapshot specification.\n\ninterval : int\n Record a frame every *interval* time steps; an integer >= 1, anything\n else is refused. Counting is 1-based over completed steps: a run of\n ``n_steps`` records ``n_steps // interval`` frames, frame ``k``\n (0-based) holding the fields after step ``(k + 1) * interval``, i.e.\n after steps ``interval, 2*interval, ...``. The last\n ``n_steps % interval`` steps record no frame. ``interval=1`` records\n every step. Memory scales with the frame count.\ncomponents : tuple of str\n Field components to capture, e.g. (\"ez\",) or (\"ex\", \"hy\").\nslice_axis : int or None\n 0, 1 or 2. If not None and *slice_index* is not None, capture a 2-D\n slice at *slice_index* along this axis instead of the full 3-D field\n (saves memory). With *slice_index* None the full field is recorded.\nslice_index : int or None\n PADDED lattice index along *slice_axis*: the same index space as\n ``grid.shape`` and ``grid.position_to_index``, CPML cells counted\n (``grid.position_to_index(pos)[axis]`` gives the index of a physical\n position).\n\nWhere each recorded sample sits (metres) and when each frame was taken\n(seconds): ``Result.snapshot_axes`` after a run, or\n``rfx.snapshot_axes(grid, spec, n_steps)`` before one (``rfx/snapshots.py``\nstates the lattice layout and the E/H time convention).", "kind": "class", "name": "rfx.SnapshotSpec", "parameters": [ { "annotation": "ForwardRef('int')", "default": "10", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "interval" }, { "annotation": "ForwardRef('tuple')", "default": "('ez',)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "components" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "slice_axis" }, { "annotation": "ForwardRef('int | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "slice_index" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#SnapshotSpec", "returns": { "annotation": null }, "signature": "(interval: ForwardRef('int') = 10, components: ForwardRef('tuple') = ('ez',), slice_axis: ForwardRef('int | None') = None, slice_index: ForwardRef('int | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L638", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Sphere defined by center and radius.", "kind": "class", "name": "rfx.Sphere", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "center" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radius" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Sphere", "returns": { "annotation": "None" }, "signature": "(center: 'tuple[float, float, float]', radius: 'float') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/csg.py#L523", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "PCB stackup builder.\n\nLayers are specified bottom-to-top (index 0 is the lowest z layer).\nThe stackup is centred at z = 0 so that\n``z_bottom = -total_thickness / 2`` and\n``z_top = +total_thickness / 2``.\n\nParameters\n----------\nlayers : sequence of :class:`PCBLayer`\n Ordered from bottom to top.", "kind": "class", "name": "rfx.Stackup", "parameters": [ { "annotation": "Sequence[PCBLayer]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "layers" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Stackup", "returns": { "annotation": null }, "signature": "(layers: 'Sequence[PCBLayer]')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pcb.py#L107", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One validation issue for a subgridded simulation.", "kind": "class", "name": "rfx.SubgridValidationIssue", "parameters": [ { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "severity" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "code" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "message" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(severity: ForwardRef('str'), code: ForwardRef('str'), message: ForwardRef('str'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/subgridding/validation.py#L19", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Validation report for ``Simulation.add_refinement``.", "kind": "class", "name": "rfx.SubgridValidationReport", "parameters": [ { "annotation": "ForwardRef('bool')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "supported" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "support_level" }, { "annotation": "ForwardRef('SubgridRegion | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "region" }, { "annotation": "ForwardRef('tuple[SubgridValidationIssue, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "issues" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(supported: ForwardRef('bool'), mode: ForwardRef('str'), support_level: ForwardRef('str'), region: ForwardRef('SubgridRegion | None'), issues: ForwardRef('tuple[SubgridValidationIssue, ...]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/subgridding/validation.py#L69", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Structured result from a parametric sweep.\n\nAttributes\n----------\nresults : list\n One ``rfx.api.Result`` (or equivalent) per parameter value.\nparam_name : str\n Label for the swept parameter.\nparam_values : ndarray\n 1-D array of parameter values that were swept.", "kind": "class", "name": "rfx.SweepResult", "parameters": [ { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "results" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_name" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_values" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#SweepResult", "returns": { "annotation": "None" }, "signature": "(results: 'list', param_name: 'str', param_values: 'np.ndarray') -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sweep.py#L59", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Thin conductor specification.\n\nParameters\n----------\nshape : Shape\n Geometric region of the thin conductor.\nsigma_bulk : float\n Bulk conductivity (S/m). e.g. copper = 5.8e7.\n When >= 1e6, treated as PEC thin sheet (added to PEC mask).\nthickness : float\n Physical thickness in metres.\neps_r : float\n Relative permittivity (default 1.0).\nsurface_impedance_f0 : float | Array | None\n Band-centre frequency (Hz) for the opt-in Leontovich surface-\n impedance loss model (issue #669). ``None`` (default) keeps the\n exact legacy semantics: metal -> lossless PEC sheet, sub-threshold\n -> DC lossy fold ``sigma_bulk*t/d``. When set, the sheet is a\n resistive sheet of sheet resistance ``Rs0 = leontovich_rs(f0,\n sigma_bulk)`` for ANY ``sigma_bulk > 0``, realized as\n ``sigma_eff = 1/(Rs0*d_norm)``.", "kind": "class", "name": "rfx.ThinConductor", "parameters": [ { "annotation": "Shape", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "shape" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma_bulk" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "thickness" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "float | jnp.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "surface_impedance_f0" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#ThinConductor", "returns": { "annotation": "None" }, "signature": "(shape: 'Shape', sigma_bulk: 'float', thickness: 'float', eps_r: 'float' = 1.0, surface_impedance_f0: 'float | jnp.ndarray | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/thin_conductor.py#L192", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Density-based design region for topology optimization.\n\nEach cell in the region has a continuous density rho in [0, 1].\nrho=0 corresponds to *material_bg* (background) and rho=1 to\n*material_fg* (foreground).\n\nParameters\n----------\ncorner_lo, corner_hi : (x, y, z) in metres\n Bounding box of the design region.\nmaterial_bg : str\n Background material name (from MATERIAL_LIBRARY).\nmaterial_fg : str\n Foreground material name.\nfilter_radius : float or None\n Radius (in metres) for the cone density filter.\n If None, no filtering is applied.\nbeta_projection : float\n Initial sharpness of the threshold projection.\n beta=1 is gentle; beta>=64 is near-binary.\nmin_feature_size : float or None\n Alias for filter_radius (diameter = 2 * filter_radius).\n If provided, overrides filter_radius.", "kind": "class", "name": "rfx.TopologyDesignRegion", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" }, { "annotation": "str", "default": "'air'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "material_bg" }, { "annotation": "str", "default": "'pec'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "material_fg" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "filter_radius" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta_projection" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "min_feature_size" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#TopologyDesignRegion", "returns": { "annotation": "None" }, "signature": "(corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]', material_bg: 'str' = 'air', material_fg: 'str' = 'pec', filter_radius: 'float | None' = None, beta_projection: 'float' = 1.0, min_feature_size: 'float | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L56", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result of a topology optimization run.\n\nAttributes\n----------\ndensity : jnp.ndarray\n Final (raw) density field in the design region.\ndensity_projected : jnp.ndarray\n Final density after filtering and projection.\neps_design : jnp.ndarray\n Final permittivity distribution in the design region.\nhistory : list of float\n Objective value at each iteration.\nbeta_history : list of float\n Projection sharpness at each iteration.\nfinal_result : object\n Simulation result from the last iteration.", "kind": "class", "name": "rfx.TopologyResult", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "density" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "density_projected" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_design" }, { "annotation": "list[float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "history" }, { "annotation": "list[float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta_history" }, { "annotation": "object", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "final_result" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_occupancy_design" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#TopologyResult", "returns": { "annotation": "None" }, "signature": "(density: 'jnp.ndarray', density_projected: 'jnp.ndarray', eps_design: 'jnp.ndarray', history: 'list[float]', beta_history: 'list[float]', final_result: 'object' = None, pec_occupancy_design: 'jnp.ndarray | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L285", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Metadata-aware Touchstone read result.\n\nThe legacy :func:`read_touchstone` API intentionally returns only\n``(s_params, freqs, z0)``. Use this dataclass through\n:func:`read_touchstone_full` when Touchstone 2.0 metadata such as per-port\nreference impedances or explicit matrix layout matters.", "kind": "class", "name": "rfx.TouchstoneData", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z0" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "version" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "parameter" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fmt" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_unit" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "layout" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "matrix_format" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "two_port_order" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "comments" }, { "annotation": "tuple[str, ...]", "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "information" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#TouchstoneData", "returns": { "annotation": "None" }, "signature": "(s_params: 'np.ndarray', freqs: 'np.ndarray', z0: 'float | np.ndarray', reference: 'np.ndarray', version: 'str', parameter: 'str', fmt: 'str', freq_unit: 'str', layout: 'str', matrix_format: 'str', two_port_order: 'str', comments: 'tuple[str, ...]' = (), information: 'tuple[str, ...]' = ()) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L38", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Via through-hole for multi-layer PCB structures.\n\nParameters\n----------\ncenter : tuple (x, y)\n Position in the xy-plane (meters).\ndrill_radius : float\n Drill hole radius (meters). Determines the width of the\n vertical conductor.\npad_radius : float\n Copper pad radius (meters) on each layer boundary.\nlayers : list of (z_bottom, z_top)\n PCB layer boundaries from bottom to top (meters).\n Each tuple defines one dielectric layer.\nmaterial : str, optional\n Material name assigned to all generated shapes.\n Defaults to ``\"pec\"``.", "kind": "class", "name": "rfx.Via", "parameters": [ { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "center" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "drill_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "pad_radius" }, { "annotation": "list[tuple[float, float]]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "layers" }, { "annotation": "str", "default": "'pec'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "material" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Via", "returns": { "annotation": null }, "signature": "(*, center: 'tuple[float, float]', drill_radius: 'float', pad_radius: 'float', layers: 'list[tuple[float, float]]', material: 'str' = 'pec')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/geometry/via.py#L19", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result from a vmapped material sweep.\n\nAttributes\n----------\ntime_series : ndarray, shape (n_batch, n_steps, n_probes)\n Probe recordings for every sweep value.\nparam_name : str\n Name of the swept parameter.\nparam_values : ndarray, shape (n_batch,)\n The parameter values that were swept.\nfinal_fields : dict or None\n Never populated (``return_fields=True`` raises ``ValueError``\n instead of silently returning ``None`` here — see\n ``vmap_material_sweep``). Reserved for a future final-field-state\n implementation; use ``sim.run()``/``sim.forward()`` or\n ``parametric_sweep()`` for final fields today.\ndft_planes : dict[str, ndarray] or None\n DFT plane accumulators, keyed by the ``add_dft_plane_probe`` name,\n each shaped ``(n_batch, n_freqs, n1, n2)`` complex — a leading\n batch axis over the same accumulator ``Result.dft_planes[name]``\n exposes for a single run (#578). Populated on BOTH the vmap fast\n path and the sequential fallback (the fallback stacks each\n swept-value ``Result.dft_planes[name].accumulator``), so the field\n is uniform regardless of which path a given ``Simulation`` takes.\n ``None`` if no ``add_dft_plane_probe`` was registered. Appended\n AFTER ``final_fields`` (not inserted before it) to preserve the\n positional-construction meaning of this publicly exported\n dataclass for any existing caller using positional args.", "kind": "class", "name": "rfx.VmapSweepResult", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_name" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_values" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "final_fields" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_planes" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#VmapSweepResult", "returns": { "annotation": "None" }, "signature": "(time_series: 'np.ndarray', param_name: 'str', param_values: 'np.ndarray', final_fields: 'dict | None' = None, dft_planes: 'dict | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/vmap_sweep.py#L65", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "A single waveguide eigenmode on the cross-section grid.\n\nAttributes\n----------\ney_profile : ndarray, shape (nu, nv)\n Transverse E-field, first local axis component.\nez_profile : ndarray, shape (nu, nv)\n Transverse E-field, second local axis component.\nhy_profile : ndarray, shape (nu, nv)\n Transverse H-field, first local axis component.\nhz_profile : ndarray, shape (nu, nv)\n Transverse H-field, second local axis component.\nbeta : ndarray, shape (n_freqs,)\n Propagation constant at each frequency. Real above cutoff,\n imaginary (stored as complex) below cutoff.\nf_cutoff : float\n Cutoff frequency in Hz.\nmode_type : str\n ``\"TE\"`` or ``\"TM\"``.\nmode_indices : tuple[int, int]\n ``(m, n)`` mode indices.", "kind": "class", "name": "rfx.WaveguideMode", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ey_profile" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez_profile" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy_profile" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hz_profile" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_cutoff" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_type" }, { "annotation": "ForwardRef('tuple[int, int]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_indices" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#WaveguideMode", "returns": { "annotation": null }, "signature": "(ey_profile: ForwardRef('np.ndarray'), ez_profile: ForwardRef('np.ndarray'), hy_profile: ForwardRef('np.ndarray'), hz_profile: ForwardRef('np.ndarray'), beta: ForwardRef('np.ndarray'), f_cutoff: ForwardRef('float'), mode_type: ForwardRef('str'), mode_indices: ForwardRef('tuple[int, int]'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/eigenmode.py#L30", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Waveguide port definition.\n\nx_index : int\n Plane index along the port normal axis (legacy name kept for\n backwards compatibility).\ny_slice : (y_lo, y_hi) or None\n Legacy x-normal first transverse slice (y) when `normal_axis='x'`.\nz_slice : (z_lo, z_hi) or None\n Legacy x-normal second transverse slice (z) when `normal_axis='x'`.\na : float\n Waveguide width in meters along the first local transverse axis.\nb : float\n Waveguide height in meters along the second local transverse axis.\nmode : (m, n)\n Mode indices. (1, 0) for TE10 dominant mode.\nmode_type : str\n \"TE\" or \"TM\". Default \"TE\".\ndirection : str\n Propagation direction when the port is driven. ``\"+x\"`` for a left\n port launching into the guide, ``\"-x\"`` for a right port launching\n back toward the guide interior.\nx_position : float | None\n Physical location (metres) of the source plane along the port normal\n axis. If omitted, helpers fall back to `x_index * dx`.\nnormal_axis : {\"x\",\"y\",\"z\"}\n Port-normal axis. Default `\"x\"` for the original straight-guide model.\nu_slice, v_slice : tuple[int, int] or None\n Generic transverse aperture slices used for non-x-normal ports.\n\n CELL spans, not node spans: these index the FIELD ARRAYS through\n :func:`_plane_indexer`, so ``hi - lo`` is the number of aperture cells\n the transverse mode operator is built on and ``sum(widths)`` over the\n slice must equal ``a`` (resp. ``b``). A node span — which is what\n ``rfx/api/_compile.py::_range_to_slice`` and\n ``rfx/runners/nonuniform.py::_range_to_slice_nu`` produce, both\n reporting the physical aperture as ``(hi - lo - 1) * d`` — has ONE\n ENTRY TOO MANY and must be converted at the call site (issue #868:\n unconverted, it put ``f_cutoff`` on a guide one cell wider than the\n walls make, 10 % low at ``dx = a/9`` and 2.7 % low at ``dx = a/36``).", "kind": "class", "name": "rfx.WaveguidePort", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_index" }, { "annotation": "ForwardRef('tuple[int, int] | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "y_slice" }, { "annotation": "ForwardRef('tuple[int, int] | None')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_slice" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "a" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "b" }, { "annotation": "ForwardRef('tuple[int, int]')", "default": "(1, 0)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode" }, { "annotation": "ForwardRef('str')", "default": "'TE'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_type" }, { "annotation": "ForwardRef('str')", "default": "'+x'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "direction" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_position" }, { "annotation": "ForwardRef('str')", "default": "'x'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "normal_axis" }, { "annotation": "ForwardRef('tuple[int, int] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "u_slice" }, { "annotation": "ForwardRef('tuple[int, int] | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_slice" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#WaveguidePort", "returns": { "annotation": null }, "signature": "(x_index: ForwardRef('int'), y_slice: ForwardRef('tuple[int, int] | None'), z_slice: ForwardRef('tuple[int, int] | None'), a: ForwardRef('float'), b: ForwardRef('float'), mode: ForwardRef('tuple[int, int]') = (1, 0), mode_type: ForwardRef('str') = 'TE', direction: ForwardRef('str') = '+x', x_position: ForwardRef('float | None') = None, normal_axis: ForwardRef('str') = 'x', u_slice: ForwardRef('tuple[int, int] | None') = None, v_slice: ForwardRef('tuple[int, int] | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L78", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compiled waveguide port config for time-stepping.", "kind": "class", "name": "rfx.WaveguidePortConfig", "parameters": [ { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_index" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ref_x" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_x" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "y_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "y_hi" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_hi" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "normal_axis" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "u_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "u_hi" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_lo" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_hi" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_u_component" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_v_component" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_u_component" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_v_component" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ey_profile" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez_profile" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy_profile" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hz_profile" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_type" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "direction" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_cutoff" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "a" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "b" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "u_widths" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_widths" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_x_m" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_x_m" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_x_m" }, { "annotation": "ForwardRef('int')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_total_steps" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "src_amp" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "src_t0" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "src_tau" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "src_fcen" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveform" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_probe_t" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_ref_t" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i_probe_t" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i_ref_t" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_inc_t" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps_recorded" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_inc_table" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_inc_table" }, { "annotation": "ForwardRef('jnp.ndarray')", "default": "Array([], shape=(0, 0), dtype=float32)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "aperture_dA" }, { "annotation": "ForwardRef('tuple[float, float]')", "default": "(0.0, 0.0)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_offset" }, { "annotation": "ForwardRef('tuple[int, int]')", "default": "(0, 0)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_indices" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#WaveguidePortConfig", "returns": { "annotation": null }, "signature": "(x_index: ForwardRef('int'), ref_x: ForwardRef('int'), probe_x: ForwardRef('int'), y_lo: ForwardRef('int'), y_hi: ForwardRef('int'), z_lo: ForwardRef('int'), z_hi: ForwardRef('int'), normal_axis: ForwardRef('str'), u_lo: ForwardRef('int'), u_hi: ForwardRef('int'), v_lo: ForwardRef('int'), v_hi: ForwardRef('int'), e_u_component: ForwardRef('str'), e_v_component: ForwardRef('str'), h_u_component: ForwardRef('str'), h_v_component: ForwardRef('str'), ey_profile: ForwardRef('jnp.ndarray'), ez_profile: ForwardRef('jnp.ndarray'), hy_profile: ForwardRef('jnp.ndarray'), hz_profile: ForwardRef('jnp.ndarray'), mode_type: ForwardRef('str'), direction: ForwardRef('str'), f_cutoff: ForwardRef('float'), a: ForwardRef('float'), b: ForwardRef('float'), dx: ForwardRef('float'), dt: ForwardRef('float'), u_widths: ForwardRef('jnp.ndarray'), v_widths: ForwardRef('jnp.ndarray'), source_x_m: ForwardRef('float'), reference_x_m: ForwardRef('float'), probe_x_m: ForwardRef('float'), dft_total_steps: ForwardRef('int'), src_amp: ForwardRef('float'), src_t0: ForwardRef('float'), src_tau: ForwardRef('float'), src_fcen: ForwardRef('float'), waveform: ForwardRef('str'), freqs: ForwardRef('jnp.ndarray'), v_probe_t: ForwardRef('jnp.ndarray'), v_ref_t: ForwardRef('jnp.ndarray'), i_probe_t: ForwardRef('jnp.ndarray'), i_ref_t: ForwardRef('jnp.ndarray'), v_inc_t: ForwardRef('jnp.ndarray'), n_steps_recorded: ForwardRef('jnp.ndarray'), e_inc_table: ForwardRef('jnp.ndarray'), h_inc_table: ForwardRef('jnp.ndarray'), aperture_dA: ForwardRef('jnp.ndarray') = Array([], shape=(0, 0), dtype=float32), h_offset: ForwardRef('tuple[float, float]') = (0.0, 0.0), mode_indices: ForwardRef('tuple[int, int]') = (0, 0))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L133", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Waveguide scattering result assembled one driven port at a time.\n\n``settling_db`` records the worst per-bin pole-tail amplitude share\nacross modal V/I records for each drive. Paired extractions include\ndevice and reference runs. ``settling_witness`` carries identification\nstatus, reasons, and per-bin shares and errors.\n\n``s21_phase_residual_deg_rms`` is the post-solve discretization witness\n(#894, post-v1.8 plan item 5): the RMS over the measured bins of\n``wrap(angle(S21) + beta(f)*L)``, in degrees, with ``beta`` the\nEXTRACTOR'S OWN (``_compute_beta`` at the port config's discrete\n``f_cutoff``, ``dt`` and ``dx``) and ``L`` the separation of the two\nreference planes reported in ``reference_planes``. Unlike a near-cutoff\n``|S11|`` headline it does not pass through the absorber: measured\ninvariant to absorber thickness (3x), record length (2.5x) and precision,\nand second order in dx at every band down to ``f/f_c = 1.010``\n(``tests/fixtures/waveguide_vi_envelope/s21_phase_residual_witness.json``).\nSo it answers \"is the port the problem?\" when a reflection number looks\nwrong -- for an EMPTY or matched guide between the two reference planes.\nA device between them adds its own transmission phase to ``angle(S21)``,\nand the number is then the device's phase against ``-beta*L``, not a\nport witness. It is REPORTED, never gated — nothing in the library compares it\nwith a threshold. ``None`` when the residual is not defined: a result that\nis not a single-mode two-port, a traced AD run, two ports with different\ndiscrete cutoffs or on different axes, a band whose every bin fell\nbelow the weak-signal phase mask\n(``rfx.api._sparams.WAVEGUIDE_PHASE_MAG_FLOOR``), or a ``normalize=True``\nlane, whose S21 has the empty-guide reference's propagation phase\ndivided out so the residual is not defined there (``normalize=\"flux\"``\nand ``normalize=False`` keep it).\n``s21_phase_residual_meta`` always carries ``beta_convention``,\n``f_cutoff_hz``, ``L_m``, ``n_bins``, ``masked_bins`` and ``normalize``\n(the lane the number was read under), plus a ``reason`` when the value\nis ``None``.", "kind": "class", "name": "rfx.WaveguideSMatrixResult", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_names" }, { "annotation": "ForwardRef('tuple[str, ...]')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_directions" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_planes" }, { "annotation": "ForwardRef('np.ndarray | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_db" }, { "annotation": "ForwardRef('float | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "s21_phase_residual_deg_rms" }, { "annotation": "ForwardRef('dict | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "s21_phase_residual_meta" }, { "annotation": "ForwardRef('tuple | None')", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "settling_witness" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#WaveguideSMatrixResult", "returns": { "annotation": null }, "signature": "(s_params: ForwardRef('np.ndarray'), freqs: ForwardRef('np.ndarray'), port_names: ForwardRef('tuple[str, ...]'), port_directions: ForwardRef('tuple[str, ...]'), reference_planes: ForwardRef('np.ndarray'), settling_db: ForwardRef('np.ndarray | None') = None, s21_phase_residual_deg_rms: ForwardRef('float | None') = None, s21_phase_residual_meta: ForwardRef('dict | None') = None, settling_witness: ForwardRef('tuple | None') = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1351", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "High-level calibrated waveguide S-parameter data.", "kind": "class", "name": "rfx.WaveguideSParamResult", "parameters": [ { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s11" }, { "annotation": "ForwardRef('np.ndarray')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s21" }, { "annotation": "ForwardRef('str')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "calibration_preset" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "source_plane" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "measured_reference_plane" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "measured_probe_plane" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_plane" }, { "annotation": "ForwardRef('float')", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_plane" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#WaveguideSParamResult", "returns": { "annotation": null }, "signature": "(freqs: ForwardRef('np.ndarray'), s11: ForwardRef('np.ndarray'), s21: ForwardRef('np.ndarray'), calibration_preset: ForwardRef('str'), source_plane: ForwardRef('float'), measured_reference_plane: ForwardRef('float'), measured_probe_plane: ForwardRef('float'), reference_plane: ForwardRef('float'), probe_plane: ForwardRef('float'))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_spec.py#L1338", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One PEC filament: the E edges of an axis-aligned lattice path (§1.4).\n\n``edges`` is the ``(Mx, My, Mz)`` boolean triple naming the edges on the\npath — built by :func:`wire_path_edge_masks` from the path's node\nindices. A wire owns no cell. Positive subcell radii are refused by\nthe PEC classifier; this is the legacy filament without a physical radius.", "kind": "class", "name": "rfx.WireSpec", "parameters": [ { "annotation": "tuple", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "edges" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(edges: 'tuple', name: 'str | None' = None) -> None", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/boundaries/pec.py#L332", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Advance (Ez, Hx, Hy) by one full ADI timestep.\n\nImplements the Zheng et al. (2000) 2D TMz ADI-FDTD scheme.\n\nYee grid staggering (2D TMz):\n Ez[i,j] at integer points (i, j)\n Hx[i,j] at (i, j+1/2) — lives on y-edges\n Hy[i,j] at (i+1/2, j) — lives on x-edges\n\nFinite differences follow the standard Yee convention:\n dEz/dx|_{i+1/2,j} = (Ez[i+1,j] - Ez[i,j]) / dx (forward)\n dHy/dx|_{i,j} = (Hy[i,j] - Hy[i-1,j]) / dx (backward)\n\n**Half-step 1** (n -> n+1/2, implicit in x):\n\n.. math::\n H_x^{n+1/2} = H_x^n - \\frac{\\Delta t}{2\\mu_0\\Delta y}\n (E_z^n[i,j+1] - E_z^n[i,j])\n\n H_y^{n+1/2} = H_y^n + \\frac{\\Delta t}{2\\mu_0\\Delta x}\n (E_z^{n+1/2}[i+1,j] - E_z^{n+1/2}[i,j])\n\n \\varepsilon E_z^{n+1/2} = \\varepsilon E_z^n\n + \\frac{\\Delta t}{2} \\left(\n \\frac{H_y^{n+1/2}[i,j] - H_y^{n+1/2}[i-1,j]}{\\Delta x}\n - \\frac{H_x^n[i,j] - H_x^n[i,j-1]}{\\Delta y}\n \\right)\n\nSubstituting the Hy^{n+1/2} expression into the Ez equation and\ncollecting terms in Ez^{n+1/2} gives a tridiagonal system along x.\n\n**Half-step 2** is symmetric with roles of x/y swapped.\n\nParameters\n----------\nez, hx, hy : (Nx, Ny) field arrays\neps_r, sigma : (Nx, Ny) material arrays\ndt, dx, dy : scalars\n\nReturns\n-------\nez_new, hx_new, hy_new : updated fields", "kind": "function", "name": "rfx.adi_step_2d", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez_pec_mask" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ez: 'jnp.ndarray', hx: 'jnp.ndarray', hy: 'jnp.ndarray', eps_r: 'jnp.ndarray', sigma: 'jnp.ndarray', dt: 'float', dx: 'float', dy: 'float', ez_pec_mask: 'jnp.ndarray | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L293", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Advance all 6 field components by one full 3D ADI timestep.\n\nImplements the Zheng–Chen–Zhang (ZCZ) 3D ADI-FDTD scheme (F. Zheng,\nZ. Chen, J. Zhang, IEEE Trans. MTT 48(9), 2000; identical scheme in\nNamiki's 3D extension): two sub-steps of ``dt/2``. In each sub-step\nevery E component is implicit along exactly one axis (tridiagonal\nThomas solve) and every H component is updated explicitly from the\njust-solved E; the two sub-steps swap which curl term is implicit.\n\nThis is the Peaceman–Rachford alternation\n``(I - dt/2·A) u' = (I + dt/2·B) u`` then\n``(I - dt/2·B) u'' = (I + dt/2·A) u'`` with the curl split into the\nA/B term families. With the zero-padded difference operators used\nhere, backward differences are exactly minus the transpose of forward\ndifferences (boundary rows included), so both split operators are\nskew-symmetric in the energy variables and the full-step map is\nsimilar to a product of two unitary Cayley transforms — the scheme is\nstable without the explicit CFL restriction for the homogeneous, lossless\nproblem with compatible PEC domain boundaries. This argument does not\nestablish stability for the internal PEC projection below.\n\nAccuracy envelope (12^3 PEC cavity, TE101 at ~15 cells per\nwavelength): eigenfrequency error is -1.4% at 2x the 3D Yee CFL\nlimit (test-measured, ``tests/unit/misc/test_review_tier1_validation_battery.py``),\ngrowing ~dt^2 (Crank–Nicolson-like temporal lag) to ~ -6.7% at 5x CFL\n(von Neumann analysis — the 5x point is not test-measured). For that\ncavity without internal PEC, large factors are quantitative only for features\nmuch coarser than the timestep. Use large CFL factors for stiff\nmeshes (thin substrates), not wavelength-scale resonances.\n\nCaveat: the *internal* ``pec_edge_masks`` are enforced by post-solve\nprojection (as on the 2D path), not by exact Dirichlet rows. Both\nlanes exhibit growing solutions with interior PEC, even at unit CFL.\nA supplied internal mask is therefore refused at every timestep; the\ncode remains here for research, not as a supported conductor solver.\n\nParameters\n----------\nex, ey, ez, hx, hy, hz : (Nx, Ny, Nz) field arrays\neps_r, sigma : (Nx, Ny, Nz) material arrays\ndt, dx, dy, dz : scalars\n\nReturns\n-------\nex, ey, ez, hx, hy, hz : updated fields", "kind": "function", "name": "rfx.adi_step_3d", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ex" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ey" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hz" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ex, ey, ez, hx, hy, hz, eps_r, sigma, dt, dx, dy, dz, pec_edge_masks=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L918", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract critical dimensions and material properties from geometry.\n\nParameters\n----------\ngeometry : list of (Shape, material_name) tuples\nmaterials : dict of material_name -> MaterialSpec or dict\npec_threshold : sigma above which material is PEC\nthin_conductors : iterable of ThinConductor\n Declared sheets (``sim.add_thin_conductor``). Their planes join the\n zero-thickness PEC boxes found in ``geometry`` as z FEATURES\n (#931 §1.9): a sheet has no thickness to resolve, but the mesh must\n carry a node at its plane.", "kind": "function", "name": "rfx.analyze_features", "parameters": [ { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry" }, { "annotation": "dict", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "float", "default": "1000000.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_threshold" }, { "annotation": null, "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "thin_conductors" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#analyze_features", "returns": { "annotation": "FeatureInfo" }, "signature": "(geometry: 'list', materials: 'dict', pec_threshold: 'float' = 1000000.0, thin_conductors=()) -> 'FeatureInfo'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/auto_config.py#L131", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Impedance bandwidth where |S11| < *threshold_db*.\n\nFinds the widest contiguous frequency range below the threshold.\n\nParameters\n----------\ns11 : (n_freqs,) complex or real.\n If complex, magnitude is computed. If real, assumed to be in dB.\nfreqs : (n_freqs,) Hz.\nthreshold_db : float\n Threshold in dB (default -10 dB).\n\nReturns\n-------\nBandwidthResult", "kind": "function", "name": "rfx.antenna_bandwidth", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s11" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "-10.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "threshold_db" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#antenna_bandwidth", "returns": { "annotation": "BandwidthResult" }, "signature": "(s11: 'np.ndarray', freqs: 'np.ndarray', *, threshold_db: 'float' = -10.0) -> 'BandwidthResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L284", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Radiation efficiency eta = P_rad / P_in.\n\nP_rad requires full-sphere coverage (a single phi cut assumes axisymmetry),\neven though input_power is supplied.\n\nParameters\n----------\nff : FarFieldResult\ninput_power : array-like (n_freqs,) or scalar\n Total input power in watts.\n\nReturns\n-------\neta : (n_freqs,) array, values in [0, inf) theoretically in (0, 1].", "kind": "function", "name": "rfx.antenna_efficiency", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "np.ndarray | float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "input_power" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#antenna_efficiency", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult', input_power: 'np.ndarray | float') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L111", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Antenna gain G(theta, phi) for each frequency.\n\nG = 4*pi * U(theta, phi) / P_ref\n\nwhere P_ref = P_rad (IEEE gain) when *input_power* is ``None``,\nor P_ref = P_in (realized gain) when *input_power* is given.\nP_rad requires full-sphere coverage (a single phi cut assumes\naxisymmetry). Realized gain accepts partial angular patterns.\n\nParameters\n----------\nff : FarFieldResult\ninput_power : array-like (n_freqs,) or scalar, optional\n Total input power in watts. When provided the result is\n *realized gain* which accounts for mismatch loss.\n\nReturns\n-------\ngain : (n_freqs, n_theta, n_phi) array (linear, not dB)", "kind": "function", "name": "rfx.antenna_gain", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "np.ndarray | float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "input_power" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#antenna_gain", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult', *, input_power: 'np.ndarray | float | None' = None) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L59", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Antenna gain in dBi. Same interface as :func:`antenna_gain`.", "kind": "function", "name": "rfx.antenna_gain_dB", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "np.ndarray | float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "input_power" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#antenna_gain_dB", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult', *, input_power: 'np.ndarray | float | None' = None) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L97", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Cone-shaped density filter for minimum feature size control.\n\nConvolves the density field with a normalized cone kernel:\n w(r) = max(0, 1 - r/R)\nwhere R is the filter radius in cells.\n\nThis is a standard technique from topology optimization (Bruns & Tortorelli,\n2001) that ensures smooth density fields and imposes a minimum length scale.\n\nParameters\n----------\nrho : array, shape (..., nx, ny, nz) or (nx, ny) or (nx, ny, nz)\n Density field in [0, 1].\nradius_cells : float\n Filter radius in grid cells.\n\nReturns\n-------\nrho_filtered : same shape as rho, values in [0, 1]", "kind": "function", "name": "rfx.apply_density_filter", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rho" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radius_cells" } ], "reference_url": null, "returns": { "annotation": "jnp.ndarray" }, "signature": "(rho: 'jnp.ndarray', radius_cells: 'float') -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L110", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Smooth Heaviside projection for binarization.\n\nProjects continuous densities toward 0 or 1 using:\n rho_proj = (tanh(beta*eta) + tanh(beta*(rho - eta)))\n / (tanh(beta*eta) + tanh(beta*(1 - eta)))\n\nParameters\n----------\nrho : array\n Filtered density field, values in [0, 1].\nbeta : float\n Sharpness parameter. beta=1 is gentle, beta>=64 is near-binary.\neta : float\n Threshold level (default 0.5).\n\nReturns\n-------\nrho_projected : same shape, values in [0, 1]\n\nReferences\n----------\nWang, F., Lazarov, B. S., & Sigmund, O. (2011). On projection methods,\nconvergence and robust formulations in topology optimization.", "kind": "function", "name": "rfx.apply_projection", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rho" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eta" } ], "reference_url": null, "returns": { "annotation": "jnp.ndarray" }, "signature": "(rho: 'jnp.ndarray', beta: 'float', eta: 'float' = 0.5) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L185", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Apply thin conductor subcell correction to material arrays.\n\nFor lossy conductors (σ < 1e6, no f0): modifies σ_eff in the material\narrays (DC fold). For PEC thin sheets (σ >= 1e6): emits a\n:class:`~rfx.boundaries.pec.SheetSpec` into ``sheets`` (#931) — the\nPEC mask is returned UNCHANGED; a sheet owns no cell.\n\nParameters\n----------\ngrid : Grid\nconductor : ThinConductor\nmaterials : MaterialArrays\npec_mask : bool array or None\n Existing PEC (volume) mask, passed through untouched.\nsheets : list or None\n Collector for PEC sheets. A PEC thin conductor with no collector\n raises: the lane would otherwise simulate no sheet at all (the\n #369 vaporized-metal class).\nsheet_specs : list or None\n Collector for surface-impedance (``surface_impedance_f0``) sheets\n (#677). An f0-mode conductor no longer touches the material arrays;\n when a list is passed, a :class:`SheetImpedanceSpec` is appended to\n it for the caller to assemble into a runtime\n :class:`SheetImpedanceCtx`. When ``None`` (legacy callers), the f0\n branch still validates the sheet but emits nothing — the assembled\n arrays are sheet-free either way, and lanes that cannot apply the\n ctx must refuse f0 sheets at their entry point.\n\nReturns\n-------\n(materials, pec_mask) — updated material arrays and PEC mask.", "kind": "function", "name": "rfx.apply_thin_conductor", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "ThinConductor", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "conductor" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_mask" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sheet_specs" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sheets" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry_masks" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry_key" }, { "annotation": "str", "default": "'strict'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "snap" } ], "reference_url": null, "returns": { "annotation": "tuple[MaterialArrays, jnp.ndarray | None]" }, "signature": "(grid: 'Grid', conductor: 'ThinConductor', materials: 'MaterialArrays', pec_mask: 'jnp.ndarray | None' = None, sheet_specs: 'list | None' = None, sheets: 'list | None' = None, geometry_masks: 'list | None' = None, geometry_key: 'int | None' = None, snap: 'str' = 'strict') -> 'tuple[MaterialArrays, jnp.ndarray | None]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/thin_conductor.py#L429", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Apply the thirds rule at conductor-dielectric boundaries.\n\nAt each boundary index, splits the cell so that the E-field sampling\npoint falls at 1/3 inside the conductor and 2/3 outside. This avoids\nplacing an E-field node exactly on the material interface, which gives\nworst-case interpolation error.\n\nInspired by OpenEMS thirds rule and Tidy3D corner_refinement.\n\nParameters\n----------\ncells : array-like\n Cell sizes along the graded axis.\nboundary_indices : list of int\n Indices in the cumulative cell array where material boundaries occur.\n A boundary at index *k* means the interface lies at the edge between\n cell k-1 and cell k. The cell on the lower side (k-1) is treated\n as conductor, the cell on the upper side (k) as dielectric.\n\nReturns\n-------\nnp.ndarray\n Cell array with boundary cells split into 1/3 + 2/3 pairs.", "kind": "function", "name": "rfx.apply_thirds_rule", "parameters": [ { "annotation": "list[float] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cells" }, { "annotation": "list[int]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "boundary_indices" } ], "reference_url": null, "returns": { "annotation": "np.ndarray" }, "signature": "(cells: 'list[float] | np.ndarray', boundary_indices: 'list[int]') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/auto_config.py#L900", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "TFSF-style E correction at the port source plane.\n\nOther half of the one-sided TFSF boundary. Adds the incident H-side\ncontribution that the Yee curl-H stencil at ``x_src`` expects from a\nforward-only wave; reading from the precomputed ``cfg.h_inc_table``\nso the correction is broadband-accurate with only an O((β·dx)²)\nnumerical-dispersion residue.\n\nSame pattern as ``apply_tfsf_e`` in ``rfx/sources/tfsf.py``. Call AFTER\n``update_e``, along with the paired ``apply_waveguide_port_h``.", "kind": "function", "name": "rfx.apply_waveguide_port_e", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(state, cfg: 'WaveguidePortConfig', step, dt: 'float', dx: 'float')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1236", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "TFSF-style H correction at the port's upstream half-cell.\n\nHalf of the one-sided TFSF boundary for a waveguide-mode source.\nReads the bandpass-filtered source amplitude from ``cfg.e_inc_table``\n(not the raw differentiated Gaussian) so sub-cutoff DC content — which\ncannot propagate in the guide anyway — never reaches the 3D grid.\n\nSame pattern as ``apply_tfsf_h`` in ``rfx/sources/tfsf.py``.\n\nWhen ``cfg.e_inc_table`` is empty (init was called without ``dt``),\nthe TFSF pair cannot be computed — this function is a no-op and\n``apply_waveguide_port_e`` handles source emission via the legacy\nsoft-E path instead. This keeps low-level callers that predate the\nTFSF pair working without API changes.", "kind": "function", "name": "rfx.apply_waveguide_port_h", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(state, cfg: 'WaveguidePortConfig', step, dt: 'float', dx: 'float')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1180", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Validate and raise ``AssertionError`` on failure.\n\nReturns the report on success so tests can inspect metrics without running\nvalidation twice.", "kind": "function", "name": "rfx.assert_port_smatrix_valid", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_POSITIONAL", "name": "args" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#assert_port_smatrix_valid", "returns": { "annotation": "PortValidationReport" }, "signature": "(*args: 'Any', **kwargs: 'Any') -> 'PortValidationReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L512", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Derive all simulation parameters from geometry + frequency range.\n\nParameters\n----------\ngeometry : list of (Shape, material_name) tuples\nfreq_range : (f_min, f_max) in Hz\nmaterials : dict of material definitions (name -> {eps_r, sigma, ...})\naccuracy : \"draft\", \"standard\", or \"high\"\n draft: 10 cells/λ, 0.15λ margin (fast, ~10% error)\n standard: 20 cells/λ, 0.25λ margin (~3% error)\n high: 40 cells/λ, 0.50λ margin (~1% error)\nboundary : \"cpml\" or \"pec\"\n Boundary condition type. Determines source type recommendation:\n - \"cpml\": J-source with Cb/dV normalization (Meep convention)\n - \"pec\": raw E-field source (no Cb normalization needed)\ndx_override : force specific cell size\nmargin_override : force specific margin\nn_steps_override : force specific step count\nmax_memory_mb : float or None\n GPU memory budget in megabytes. When set, ``dx`` is\n automatically coarsened (increased) until\n ``estimated_memory_mb <= max_memory_mb``. Useful for\n keeping reverse-mode AD within a 24 GB GPU. Ignored when\n *dx_override* is provided.\n\n Practical limits (approximate, with gradient checkpointing):\n\n - 8 GB GPU: ``max_memory_mb=6000``\n - 24 GB GPU: ``max_memory_mb=18000``\n - 48 GB GPU: ``max_memory_mb=36000``\nwaveform : source waveform or None\n Used only for the source-time term of the ``n_steps`` estimate:\n when the waveform exposes ``t0`` (``GaussianPulse`` /\n ``ModulatedGaussian``: ``t0 = cutoff*tau``), the source window is\n ``2*t0`` so a longer-onset pulse (e.g. ``cutoff=4.5`` →\n ``9*tau``) is fully covered. Without a waveform the historical\n cutoff=3 envelope (``6*tau`` at bw=0.8) is used, bitwise-identical\n to the previous hardcode.\nthin_conductors : iterable of ThinConductor\n Declared sheets. Their planes (and any zero-thickness PEC box in\n ``geometry``) become z FEATURES: the non-uniform z profile puts a\n mesh line on each, so a sheet is realized where it was declared\n (#931 §1.9).\n\nReturns\n-------\nSimConfig with all derived parameters.", "kind": "function", "name": "rfx.auto_configure", "parameters": [ { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry" }, { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "str", "default": "'standard'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "accuracy" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx_override" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "margin_override" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps_override" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_memory_mb" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": null, "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "thin_conductors" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#auto_configure", "returns": { "annotation": "SimConfig" }, "signature": "(geometry: 'list', freq_range: 'tuple[float, float]', materials: 'dict | None' = None, accuracy: 'str' = 'standard', *, boundary: 'str' = 'cpml', dx_override: 'float | None' = None, margin_override: 'float | None' = None, n_steps_override: 'int | None' = None, max_memory_mb: 'float | None' = None, waveform=None, thin_conductors=()) -> 'SimConfig'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/auto_config.py#L346", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Automatically add a refinement region based on the error indicator.\n\nComputes the error indicator from *result*, finds the dominant high-\nerror region, and calls ``sim.add_refinement()`` with the\ncorresponding z-range.\n\nParameters\n----------\nsim : Simulation\n The simulation to add refinement to (mutated in-place).\nresult : Result\n Completed coarse simulation result.\nthreshold : float\n Error threshold for region suggestion (default 0.5).\ncomponent : str\n Field component for the error indicator (default ``\"ez\"``).\nmin_region_size : int\n Minimum cells per axis for a suggested region (default 2).\nratio : int\n Subgrid refinement ratio passed to ``add_refinement()`` (default 2).\n\nReturns\n-------\nsim : Simulation\n The same simulation object (for chaining).", "kind": "function", "name": "rfx.auto_refine", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "threshold" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "min_region_size" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ratio" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#auto_refine", "returns": { "annotation": null }, "signature": "(sim, result, *, threshold: 'float' = 0.5, component: 'str' = 'ez', min_region_size: 'int' = 1, ratio: 'int' = 2)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/amr.py#L166", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Axial ratio (AR) of far-field polarization.\n\nAR = |E_major| / |E_minor| (≥ 1). AR = 1 for circular, ∞ for linear.\n\nReturns (n_freqs, n_theta, n_phi) array.", "kind": "function", "name": "rfx.axial_ratio", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#axial_ratio", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1510", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Axial ratio in dB. 0 dB = circular, large = linear.", "kind": "function", "name": "rfx.axial_ratio_dB", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#axial_ratio_dB", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1547", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Benchmark FDTD throughput across grid sizes.\n\nReturns a list of BenchResult sorted by grid size.", "kind": "function", "name": "rfx.benchmark", "parameters": [ { "annotation": "list[tuple[int, int, int]] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_sizes" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#benchmark", "returns": { "annotation": "list[BenchResult]" }, "signature": "(grid_sizes: 'list[tuple[int, int, int]] | None' = None, n_steps: 'int' = 100) -> 'list[BenchResult]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/gpu.py#L58", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return TFSF-style transverse E/M source specs for a coaxial port.\n\n``shell_inner_radius`` is the inner face of the outer conductor, i.e. the\nouter edge of the PTFE annulus. Pass the value\n:func:`stamp_coaxial_line` returned for this line; omitted, it defaults to\nthe declared ``port.outer_radius``, which is where that function puts it.\n``pec_cell_mask`` is that stamper's realized conductor-cell mask; the\nsource solves Laplace on its cross-section and injects the resulting\ndiscrete TEM edge profile. Without a mask it realizes the declared\ncylinders on the same grid. The fill is homogeneous with relative\npermittivity ``eps_r``; the profile depends only on concrete geometry.\n\nBakes a Yee-half-step-correct one-side TFSF correction pair into per-\ncell ``SourceSpec`` / ``MagneticSourceSpec`` lists. The additive\n``src_vals`` / ``mag_src_vals`` injection in :func:`rfx.simulation.run`\nhas the same leapfrog timing as the waveguide-port TFSF apply pair\n(``apply_waveguide_port_h`` / ``apply_waveguide_port_e``) so the\nadditive specs reproduce its unidirectional injection without\nrequiring a separate apply hook in the simulation runner.\n\nThree structural fixes vs the M67/M72 prototype-promotion of the\nplane-source (whose bidirectional emission held PEC-short ``|S11|``\nnear 0.2-0.4 regardless of termination):\n\n* **Cross-coupling**: H sources are driven by the E mode profile\n (the realized electrostatic ``Ex, Ey``), and E sources are driven\n by its magnetic dual ``(-Ey, Ex) / eta``. The previous implementation\n drove H from H and E from E, which does not enforce the curl\n coupling that makes the wave unidirectional.\n* **Spatial half-cell offset**: H sources move from the source plane\n to the upstream half-cell on the scattered side of the TFSF\n boundary (``plane_index - 1`` for ``+z`` forward, ``plane_index``\n for ``-z`` forward).\n* **Yee half-step phase**: ``h_inc(t_n) = waveform(t_n + Δt) / Z₀``\n with ``Δt = dt/2 + dz·sqrt(εr)/(2c)``; the previous version sampled\n both E and H at integer ``n·dt`` so the H source carried no Yee\n half-step phase relative to E.\n\nThe :class:`CoaxialPlaneSourceSpec` return contract is unchanged:\n``plane_axial_index`` is still the *E* reference plane (where the V/I\nextractor reads). The mag-source list now lives one cell upstream.\n\nFor ``face='top'`` (pin going ``-z`` into cavity), forward = ``-z``\nand the pattern follows the waveguide ``-x``-direction conventions.\nFor ``face='bottom'``, forward = ``+z`` and the ``+x`` pattern is\nused.\n\nParameters\n----------\ngrid:\n The simulation grid.\nport:\n :class:`CoaxialPort` with geometry and excitation waveform.\nn_steps:\n Number of FDTD timesteps the simulation will execute. The waveform\n is materialised at each step so this must match the runner.\nfield_scale:\n Linear scale on the radial E waveform. Increase to lift the plane\n signal above DFT noise; the V/I extraction is amplitude-linear.\nmagnetic_ratio:\n Multiplier on the ``H`` waveform after the local ``1/eta``\n factor (already baked into ``h_inc`` so a unit ratio means\n Poynting-balanced TEM). Kept for diagnostic ablation; production\n callers should leave it at ``1.0``.\nreference_plane_axial_index_offset:\n Shift of the source plane (and therefore the V/I reference plane)\n relative to ``port.pin_center`` along the port axis. ``0`` injects\n at the pin centre plane.\nplane_axial_index:\n Explicit E-plane node for a calculator's internally indexed source.\n If supplied, bypasses the physical pin-centre lookup; the offset\n above is still applied. Declared ports use the default lookup.\neps_r:\n Coaxial dielectric permittivity for the analytic ``Z_TEM`` and the\n Yee-half-step delay (``v_phase = c / sqrt(εr)``). Default\n :data:`PTFE_EPS_R` matches the SMA helper.\npec_cell_mask:\n Optional conductor-cell mask returned by ``stamp_coaxial_line``.\n Its source-plane cross-section sets the Laplace Dirichlet nodes.\n\nReturns\n-------\nCoaxialPlaneSourceSpec\n Lists of per-cell source specs plus bookkeeping needed by the V/I\n extractor.", "kind": "function", "name": "rfx.build_coaxial_tem_plane_source_specs", "parameters": [ { "annotation": "'Grid'", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "grid" }, { "annotation": "CoaxialPort", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "port" }, { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "10000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_scale" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "magnetic_ratio" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_plane_axial_index_offset" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "plane_axial_index" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "shell_inner_radius" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_cell_mask" } ], "reference_url": null, "returns": { "annotation": "CoaxialPlaneSourceSpec" }, "signature": "(*, grid: \"'Grid'\", port: 'CoaxialPort', n_steps: 'int', field_scale: 'float' = 10000.0, magnetic_ratio: 'float' = 1.0, reference_plane_axial_index_offset: 'int' = 0, plane_axial_index: 'int | None' = None, eps_r: 'float' = 2.1, shell_inner_radius: 'float | None' = None, pec_cell_mask=None) -> 'CoaxialPlaneSourceSpec'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L738", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Build a complete runtime artifact report for a live simulation.", "kind": "function", "name": "rfx.build_runtime_report", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "Any", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "dict[str, Any] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "extra" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" } ], "reference_url": null, "returns": { "annotation": "dict[str, Any]" }, "signature": "(sim: 'Any', result: 'Any' = None, *, extra: 'dict[str, Any] | None' = None, n_steps: 'int | None' = None, available_memory_gb: 'float | None' = None) -> 'dict[str, Any]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L619", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Build a JSON-serializable artifact of the live native rfx scene.\n\nThe returned mapping is intentionally a summary of runtime state, not a CAD\nexport. It uses ``scene`` as the canonical geometry vocabulary and avoids\ndumping large arrays or arbitrary private object state by default.", "kind": "function", "name": "rfx.build_scene_artifact", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_private" } ], "reference_url": null, "returns": { "annotation": "dict[str, Any]" }, "signature": "(sim: 'Any', *, include_private: 'bool' = False) -> 'dict[str, Any]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L313", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a stable, compact case id for a parameter dictionary.", "kind": "function", "name": "rfx.case_id_from_params", "parameters": [ { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "params" }, { "annotation": "str", "default": "'case'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "prefix" } ], "reference_url": null, "returns": { "annotation": "str" }, "signature": "(params: 'dict[str, Any]', *, prefix: 'str' = 'case') -> 'str'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L90", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assert lower/upper bounds for an array-like value inside JAX tracing.", "kind": "function", "name": "rfx.check_bounds", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lower" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "upper" }, { "annotation": "str", "default": "'value'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#check_bounds", "returns": { "annotation": null }, "signature": "(value: 'Any', *, lower: 'float | None' = None, upper: 'float | None' = None, name: 'str' = 'value')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/jax_checks.py#L57", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assert a finite positive Courant-like number at or below ``limit``.\n\nThe check is inclusive (``courant <= limit``), matching the textbook CFL\nbound. The default ``limit=1.0`` is the 1-D ceiling; pass the\ndimensionality-appropriate bound for the target engine (e.g. ``1/sqrt(3)``\n~= 0.577 for 3-D FDTD) rather than relying on the default.", "kind": "function", "name": "rfx.check_courant_number", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "courant" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "limit" }, { "annotation": "str", "default": "'courant'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#check_courant_number", "returns": { "annotation": null }, "signature": "(courant: 'Any', *, limit: 'float' = 1.0, name: 'str' = 'courant')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/jax_checks.py#L75", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assert that all entries of ``value`` are finite inside JAX tracing.", "kind": "function", "name": "rfx.check_finite", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value" }, { "annotation": "str", "default": "'value'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#check_finite", "returns": { "annotation": null }, "signature": "(value: 'Any', name: 'str' = 'value')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/jax_checks.py#L40", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assert that all entries of ``value`` are positive or non-negative.", "kind": "function", "name": "rfx.check_positive", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "value" }, { "annotation": "str", "default": "'value'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "allow_zero" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#check_positive", "returns": { "annotation": null }, "signature": "(value: 'Any', name: 'str' = 'value', *, allow_zero: 'bool' = False)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/jax_checks.py#L47", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a checkified wrapper for user and optional automatic checks.\n\nUser checks are always enabled because the helpers below emit\n``checkify.check`` predicates. ``float_checks`` additionally catches NaN and\ndivide-by-zero errors inserted by JAX checkify. ``index_checks`` is opt-in\nbecause it can be noisier for code that intentionally uses masked indexing.", "kind": "function", "name": "rfx.checkify_invariants", "parameters": [ { "annotation": "F", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fun" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "float_checks" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "index_checks" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#checkify_invariants", "returns": { "annotation": "Callable[..., tuple[checkify.Error, Any]]" }, "signature": "(fun: 'F', *, float_checks: 'bool' = True, index_checks: 'bool' = False) -> 'Callable[..., tuple[checkify.Error, Any]]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/jax_checks.py#L19", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Closed-form reflection coefficient for a coaxial load.", "kind": "function", "name": "rfx.coaxial_load_reflection", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "load_impedance" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_impedance" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(load_impedance, reference_impedance: 'float')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L198", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Analytic capacitance per metre for a lossless coaxial TEM line.", "kind": "function", "name": "rfx.coaxial_tem_capacitance_per_m", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inner_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "outer_radius" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" } ], "reference_url": null, "returns": { "annotation": "float" }, "signature": "(inner_radius: 'float', outer_radius: 'float', eps_r: 'float' = 2.1) -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L144", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Analytic characteristic impedance ``Z0 = sqrt(L'/C')`` for coax TEM.", "kind": "function", "name": "rfx.coaxial_tem_characteristic_impedance", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inner_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "outer_radius" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mu_r" } ], "reference_url": null, "returns": { "annotation": "float" }, "signature": "(inner_radius: 'float', outer_radius: 'float', eps_r: 'float' = 2.1, mu_r: 'float' = 1.0) -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L170", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Analytic inductance per metre for a lossless coaxial TEM line.", "kind": "function", "name": "rfx.coaxial_tem_inductance_per_m", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "inner_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "outer_radius" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mu_r" } ], "reference_url": null, "returns": { "annotation": "float" }, "signature": "(inner_radius: 'float', outer_radius: 'float', mu_r: 'float' = 1.0) -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L157", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Analytic lossless TEM phase constant ``beta`` for frequency array.", "kind": "function", "name": "rfx.coaxial_tem_phase_constant", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs_hz" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mu_r" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(freqs_hz, eps_r: 'float' = 2.1, mu_r: 'float' = 1.0)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L185", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Convert calibrated TEM V/I phasors to one-port S11.\n\nThe convention is the same power-wave split used by the raw V/I replay\nhelpers: ``a = (V + Z0 I) / 2`` and ``b = (V - Z0 I) / 2``.", "kind": "function", "name": "rfx.coaxial_tem_reference_plane_s11", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "voltage" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "current" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "reference_impedance" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(voltage, current, reference_impedance: 'float')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L442", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract calibrated coaxial TEM voltage/current from field samples.\n\nParameters\n----------\nradial_positions_m:\n 1-D sample positions on a radial line from inner to outer conductor.\ne_radial_samples:\n Radial electric field samples. The last axis must match\n ``radial_positions_m``. Leading axes (for example frequency) are\n preserved in the returned voltage.\nh_phi_samples:\n Azimuthal magnetic field samples around a circular loop at\n ``h_sample_radius_m``. The last axis is averaged over azimuthal sample\n angle. Leading axes are preserved in the returned current.\nh_sample_radius_m:\n Radius of the magnetic-field sampling loop.\ninner_radius, outer_radius, eps_r:\n Coax geometry. ``eps_r`` is validated for consistency with the other\n TEM helpers even though it is not needed by the field integrals.\nvoltage_sign, current_sign:\n Optional convention flips for callers whose field orientation differs\n from the public port convention.\n\nNotes\n-----\nThis helper is the calibration primitive for a coaxial reference-plane\nTEM extractor. It does not run FDTD and does not by itself promote\n``add_coaxial_port(...)`` to a high-level S-parameter API.", "kind": "function", "name": "rfx.coaxial_tem_reference_plane_vi", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "radial_positions_m" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_radial_samples" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_phi_samples" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "h_sample_radius_m" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "inner_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "outer_radius" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "voltage_sign" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_sign" } ], "reference_url": null, "returns": { "annotation": "CoaxialTEMReferencePlaneVI" }, "signature": "(radial_positions_m, e_radial_samples, h_phi_samples, *, h_sample_radius_m: 'float', inner_radius: 'float', outer_radius: 'float', eps_r: 'float' = 2.1, voltage_sign: 'float' = 1.0, current_sign: 'float' = 1.0) -> 'CoaxialTEMReferencePlaneVI'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L213", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract coaxial TEM V/I from Cartesian tangential field-plane samples.\n\nParameters\n----------\nu_coords_m, v_coords_m:\n Strictly increasing coordinate arrays for the two tangential plane\n axes. Field arrays must use these as their last two dimensions.\ne_u_samples, e_v_samples:\n Tangential electric-field DFT samples on the plane.\nh_u_samples, h_v_samples:\n Tangential magnetic-field DFT samples on the same plane.\ncenter_u_m, center_v_m:\n Coax center on the sampled plane.\ninner_radius, outer_radius:\n Coax conductor radii in metres.\nradial_positions_m:\n Optional radial integration points. By default, all available\n positive-``u`` grid coordinates that lie inside ``[inner, outer]`` are\n used. The caller may pass a denser grid for synthetic or interpolated\n data.\nh_sample_radius_m:\n Optional radius for the azimuthal H-loop. Defaults to the geometric\n mean of the inner and outer conductor radii.\nazimuthal_angles_rad:\n Optional loop sample angles. Defaults to 16 equiangular samples.\n\nNotes\n-----\nThis adapter performs bilinear interpolation and then delegates the actual\nTEM V/I integration to :func:`coaxial_tem_reference_plane_vi`. It does not\nrun FDTD and is not a promoted coaxial S-parameter API.", "kind": "function", "name": "rfx.coaxial_tem_reference_plane_vi_from_cartesian_plane", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "u_coords_m" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "v_coords_m" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_u_samples" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_v_samples" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_u_samples" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_v_samples" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "center_u_m" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "center_v_m" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "inner_radius" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "outer_radius" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "radial_positions_m" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "h_sample_radius_m" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "azimuthal_angles_rad" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "voltage_sign" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_sign" } ], "reference_url": null, "returns": { "annotation": "CoaxialTEMCartesianPlaneVI" }, "signature": "(u_coords_m, v_coords_m, e_u_samples, e_v_samples, h_u_samples, h_v_samples, *, center_u_m: 'float', center_v_m: 'float', inner_radius: 'float', outer_radius: 'float', eps_r: 'float' = 2.1, radial_positions_m=None, h_sample_radius_m: 'float | None' = None, azimuthal_angles_rad=None, voltage_sign: 'float' = 1.0, current_sign: 'float' = 1.0) -> 'CoaxialTEMCartesianPlaneVI'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L312", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compare an independent replay against production S-matrix output.", "kind": "function", "name": "rfx.compare_replayed_smatrix", "parameters": [ { "annotation": "PortSMatrixObservable | Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "replayed" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "production" }, { "annotation": "float", "default": "1e-09", "has_default": true, "kind": "KEYWORD_ONLY", "name": "atol" }, { "annotation": "float", "default": "1e-06", "has_default": true, "kind": "KEYWORD_ONLY", "name": "rtol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compare_replayed_smatrix", "returns": { "annotation": "PortReplayComparison" }, "signature": "(replayed: 'PortSMatrixObservable | Any', production: 'Any', *, atol: 'float' = 1e-09, rtol: 'float' = 1e-06) -> 'PortReplayComparison'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L733", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute spatial error indicator from a simulation result.\n\nReturns a 3-D array where high values indicate regions that would\nbenefit from mesh refinement. The proxy is the magnitude of the\nspatial gradient of the final-state field component, normalized to\n[0, 1].\n\nParameters\n----------\nresult : Result or SimResult\n A completed simulation result whose ``.state`` carries the final\n field arrays (``ex``, ``ey``, ``ez``, ``hx``, ``hy``, ``hz``).\ncomponent : str\n Field component to analyze (default ``\"ez\"``).\n\nReturns\n-------\nerror : ndarray, shape (Nx, Ny, Nz)\n Normalized error indicator in [0, 1]. Values near 1 mark cells\n with the steepest field gradients.", "kind": "function", "name": "rfx.compute_error_indicator", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_error_indicator", "returns": { "annotation": "np.ndarray" }, "signature": "(result, *, component: 'str' = 'ez') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/amr.py#L29", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute far-field radiation pattern from NTFF DFT data.\n\nEvery face cell contributes one sample of the equivalent surface\ncurrents J = n x H and M = -n x E, weighted by the cell's area and\nphased by its position. Where that sample is taken is what decides the\norder of the rule: with ``box.collocation == \"face_centre\"`` it sits at\nthe centre of the cell, matching what ``accumulate_ntff`` stored there,\nand the sum is a midpoint rule — second order in the cell size. With\n``\"node\"`` (the legacy layout, and the default for a hand-built box) it\nsits at the cell's lower-corner node, which is a left-endpoint\nrectangle rule — first order.\n\nAutomatically dispatches to the JAX-differentiable implementation\nwhen called inside ``jax.grad`` or other JAX tracing contexts.\nUse this function for both post-processing and optimization objectives.\n\nParameters\n----------\nntff_data : NTFFData\n Accumulated frequency-domain tangential fields.\nbox : NTFFBox\ngrid : Grid\ntheta : (n_theta,) array in radians [0, pi]\nphi : (n_phi,) array in radians [0, 2*pi]\n\nReturns\n-------\nFarFieldResult", "kind": "function", "name": "rfx.compute_far_field", "parameters": [ { "annotation": "NTFFData", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": "NTFFBox", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "box" }, { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_far_field", "returns": { "annotation": "FarFieldResult" }, "signature": "(ntff_data: 'NTFFData', box: 'NTFFBox', grid: 'Grid', theta: 'np.ndarray', phi: 'np.ndarray') -> 'FarFieldResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L966", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "JAX-differentiable far-field computation for use inside jax.grad.\n\nSame physics as ``compute_far_field`` — including its face-cell sample\nplacement, which is the midpoint rule when the box says\n``collocation=\"face_centre\"`` and the legacy corner-node rule when it\nsays ``\"node\"`` — but uses ``jnp`` throughout, enabling end-to-end\ndifferentiation for far-field optimization.\n\n``max_phase_bytes`` bounds the (n_freqs, n_directions, n_cells) phase\narray the transform materializes per face; the direction grid is\nsplit to stay under it. Splitting theta is EXACT — the sum over\nsurface cells is independent per direction — and the chunked result\nis bit-identical to the single-shot one. Pass ``float(\"inf\")`` to\nforce a single pass.", "kind": "function", "name": "rfx.compute_far_field_jax", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "box" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" }, { "annotation": "float", "default": "4000000000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_phase_bytes" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_far_field_jax", "returns": { "annotation": null }, "signature": "(ntff_data, box, grid, theta, phi, *, max_phase_bytes: 'float' = 4000000000.0)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1255", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute Floquet S-parameters from DFT accumulators.\n\n.. warning:: **Experimental.** This pipeline carries an E0 contract test\n (``tests/unit/ports/test_floquet_s_params_contract.py``) — the first real pytest\n caller, a passivity check on pre-isolated pure-wave input, and a\n finite-grad AD smoke (the path is jnp-pure and AD-traceable) — but **no\n accuracy validation against an external periodic-cell solver**. It also\n presumes the input accumulators already isolate the incident /\n reflected / transmitted waves: a naive single-run soft-source drive\n does NOT (a bidirectional source leaves no pure-forward monitor plane),\n so ``|S11|`` from such a drive can exceed 1. Do not build accuracy\n claims on it. Tracking: https://github.com/bk-squared/rfx/issues/141\n\n **Drive-isolation scoping (2026-07-05, R2-STOP):** the obvious fix — a\n two-run empty-vs-device reference subtraction (``E_scat = E_dev −\n E_empty`` at a +z-side plane, the pattern that works for waveguide/coax\n ports) — does NOT resolve this for a periodic Floquet cell. On an εr=4\n slab vs the exact analytic Airy S11, the two-run extraction is\n non-physical: |S11|≈1.5 at band-center 6 GHz where Airy=0.09 (the ~1.5\n extraction-error floor swamps the small true reflection) and larger\n blow-ups at band edges (small-incident normalization noise). TFSF\n one-way plane-wave sources — the clean isolation route — are explicitly\n barred with Floquet ports (see ``add_floquet_port``). A real fix needs\n dedicated numerics (clean incident normalization + higher-order-mode\n filtering, or a Floquet-compatible one-way source), NOT a parameter\n flip; and drive-isolation is the PREREQUISITE to any external (RCWA /\n Meep-Bloch) accuracy validation — the external reference is moot until\n FDTD yields a physical |S11|≤1 on a real periodic structure.\n\nUses incident, reflected, and (optionally) transmitted plane\nDFT data to compute S11 (reflection) and S21 (transmission).\n\nParameters\n----------\nacc_inc : FloquetDFTAccumulator\n DFT at the source/reference plane (incident side).\nacc_ref : FloquetDFTAccumulator\n DFT at the reflection measurement plane.\nacc_trans : FloquetDFTAccumulator or None\n DFT at the transmission measurement plane (if present).\ndx : float\n Cell size.\nLx, Ly : float\n Unit cell periods.\nfreqs : (n_freqs,) array\n Frequencies.\ntheta_deg, phi_deg : float\n Scan angles.\n\nReturns\n-------\ndict with 'S11', 'S21' (if transmission plane exists), 'freqs'.", "kind": "function", "name": "rfx.compute_floquet_s_params", "parameters": [ { "annotation": "FloquetDFTAccumulator", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "acc_inc" }, { "annotation": "FloquetDFTAccumulator", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "acc_ref" }, { "annotation": "FloquetDFTAccumulator | None", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "acc_trans" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Lx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Ly" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_deg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_deg" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_floquet_s_params", "returns": { "annotation": "dict" }, "signature": "(acc_inc: 'FloquetDFTAccumulator', acc_ref: 'FloquetDFTAccumulator', acc_trans: 'FloquetDFTAccumulator | None', dx: 'float', Lx: 'float', Ly: 'float', freqs: 'jnp.ndarray', theta_deg: 'float' = 0.0, phi_deg: 'float' = 0.0) -> 'dict'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L525", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute radar cross section of the scatterer defined in materials.\n\nParameters\n----------\ngrid : Grid\n Simulation grid (must already include CPML padding).\nmaterials : MaterialArrays\n Material arrays with the scatterer defined (e.g., PEC regions\n with very high conductivity or high eps_r).\nn_steps : int\n Number of FDTD timesteps.\nf0 : float\n Center frequency of the Gaussian pulse (Hz).\nbandwidth : float\n Fractional bandwidth of the pulse.\ntheta_inc : float\n Incident angle in degrees (0 = +x propagation). Non-zero values tilt the\n illumination in the x-y plane and route through the open-domain oblique\n Method-B TFSF (2.5-D: open transverse y, thin-periodic z). Only the\n far-field PATTERN / specular direction is validated at oblique incidence\n (specular peak phi = 180 - theta_inc at theta_obs = 90 deg). Measured\n envelope on the committed gate configuration (2.2-lambda plate, 700\n steps, public path, corner-inclusive kernels): peak error 0 deg at\n theta_inc=20 and 3 deg at theta_inc=40 (4 deg on the pre-fix exclusive\n kernels), gated at +/-6 deg, with a 3-7 deg peak-azimuth\n sensitivity to domain size at fixed dx/plate/CPML (PR #461 audit,\n measured on the PRE-fix exclusive kernels; not re-measured in-tree\n on the inclusive kernels) —\n i.e. the argmax azimuth of the broad specular lobe is NOT converged to\n ~1 deg. See ``tests/oracle/test_oblique_rcs_specular.py``.\n\n ABSOLUTE oblique sigma (issue #471 F7, all numbers measured): the\n normalization is the MEASURED 1D-aux incident spectrum (see\n ``tfsf_oblique_open.measure_incident_spectrum``), which removed a\n +6.58/+4.51 dB (theta 20/40 deg) inflation the analytic normal-path\n spectrum caused. Against a PO uniform-aperture oracle on the gate\n grid (dx=2 mm = lambda/30): specular-peak Delta +0.86/+0.85 dB\n (theta 20/40), lobe-flat over +/-12 deg. The returned sigma is that\n of an aperture of height ``h_eff = (k_hi - k_lo)*dx`` of the NTFF\n z-box (span-doubling ratio 4.000 measured — sigma scales as\n h_eff^2); the oblique path's hardcoded 2-cell midplane box means\n h_eff = 2*dx, so scale by ``(L_z/h_eff)^2`` for a physical strip\n height ``L_z``. CAVEAT (measured, pinned-geometry): halving dx to\n lambda/60 moves Delta to -1.55 dB — a 2.4 dB resolution\n sensitivity, so treat absolute oblique sigma as a +/-2 dB-class\n number at lambda/30-lambda/60, NOT sub-dB (the committed test gates\n |Delta| <= 1.5 dB at the fixed gate grid as a regression lock, not\n an accuracy claim). Requires ``polarization='ez'`` and a uniform\n grid; other combos raise ``NotImplementedError`` (issue #404 arc).\nphi_inc : float\n Incident azimuth in degrees (reserved for future oblique support).\npolarization : str\n Electric field polarization: \"ez\" or \"ey\".\ntheta_obs : array or None\n Observation elevation angles in radians. Default: 0 to pi, 37 points.\nphi_obs : array or None\n Observation azimuth angles in radians. Default: [0, pi/2].\nfreqs : array or None\n Frequencies at which to compute RCS (Hz). Default: [f0].\nboundary : str\n Boundary condition type (\"cpml\" or \"pec\").\ncpml_layers : int\n Number of CPML layers (must match grid.cpml_layers).\ntfsf_margin : int\n Cells between CPML edge and TFSF boundary.\nntff_offset : int\n Cells between TFSF boundary and NTFF box (NTFF must be in the\n scattered-field region, i.e., outside the TFSF box). The default\n (1) places the Huygens surface deep in the reactive near field.\n See \"Bistatic pattern caveat\" below: this default is validated\n for the backscatter/monostatic bin, but is NOT a validated\n bistatic setup, and increasing it does not close the oblique gap\n at test scale.\nsubtract_incident_reference : bool\n If True (default False), run a second vacuum (no-scatterer) pass\n with the identical TFSF+NTFF setup and subtract its far-field from\n the target's at the COMPLEX level (E_scat = E_far[target] -\n E_far[vacuum]) before forming the RCS. This is the standard\n total-field/scattered-field normalization; it removes the full incident\n field read by NTFF side faces inside the total-field slab, which\n otherwise produces a spurious forward-oblique lobe (issue #280).\n Doubles the solve cost. Default False keeps the validated\n monostatic path byte-identical; opt in for the bistatic pattern.\n Without ``phase_reference``, ``monostatic_rcs`` is computed from the raw\n (unsubtracted) run regardless of this flag, preserving the separately\n checked monostatic extraction.\nphase_reference : (x, y, z) in metres, optional\n Opt in to a ``ScatteringResponse`` with complex scattering amplitudes\n referenced to this physical point. Requires normal +x incidence, a\n uniform 3-D grid with symmetric CPML, and\n ``subtract_incident_reference=True``. The x coordinate must be on an\n E-node plane inside the total-field slab; it is never silently\n snapped. The normal incident wave is uniform in y/z. Only finite,\n positive frequencies with a nonzero incident spectrum are admitted;\n the caller must additionally check adequate source bandwidth and\n record/mesh convergence. Without this option the return is unchanged.\n\nReturns\n-------\nRCSResult\n freqs, theta, phi, rcs_dbsm (dBsm), rcs_linear (m^2),\n monostatic_rcs (dBsm, evaluated exactly at the true backscatter\n direction — for +x incidence that is (theta=pi/2, phi=pi) under\n the farfield r_hat convention; it does not depend on\n theta_obs/phi_obs).\n With ``phase_reference`` set, ``ScatteringResponse.rcs`` holds the\n RCS normalized by the incident measured at that reference, consistent\n with its complex F components. Frequencies are the realized NTFF bins.\n\nBistatic pattern caveat\n-----------------------\n``RCSResult.monostatic_rcs`` is evaluated from the raw target run at\nexact backscatter, independently of the observation grid. Its current\nMie comparison is in ``tests/fixtures/rcs_sphere_mie/``.\n\nThe default unsubtracted ``rcs_dbsm`` / ``rcs_linear`` bistatic pattern\nis NOT VALIDATED. The source's total-field slab is infinite transversely,\nso the side faces of a closed NTFF box record the full incident field.\nIncreasing ``ntff_offset`` does not remove that contribution; off-axis\nbins cannot be interpreted as the scatterer's bistatic response.\n\nSet ``subtract_incident_reference=True`` for the reference-subtracted\npath. It doubles the solve cost and subtracts a matching vacuum run at\nthe complex far-field level. The committed sphere comparison is in\n``tests/fixtures/rcs280_reference_subtraction/``; its scope is limited\nto that sphere, frequency, polarization, angle cut and discretization.\n\nAfter subtraction, refine curved surfaces, repeat with a longer run, vary\nNTFF placement and CPML thickness, and enlarge the domain when deep pattern\nnulls matter. Compare each new target and configuration with an analytic or\nindependent reference before treating the bistatic values as quantitative.", "kind": "function", "name": "rfx.compute_rcs", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bandwidth" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "theta_inc" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "phi_inc" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polarization" }, { "annotation": "jnp.ndarray | np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "theta_obs" }, { "annotation": "jnp.ndarray | np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "phi_obs" }, { "annotation": "jnp.ndarray | np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_layers" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tfsf_margin" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ntff_offset" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "subtract_incident_reference" }, { "annotation": "tuple[float, float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "phase_reference" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_rcs", "returns": { "annotation": "RCSResult | ScatteringResponse" }, "signature": "(grid: 'Grid', materials: 'MaterialArrays', n_steps: 'int', *, f0: 'float', bandwidth: 'float' = 0.5, theta_inc: 'float' = 0.0, phi_inc: 'float' = 0.0, polarization: 'str' = 'ez', theta_obs: 'jnp.ndarray | np.ndarray | None' = None, phi_obs: 'jnp.ndarray | np.ndarray | None' = None, freqs: 'jnp.ndarray | np.ndarray | None' = None, boundary: 'str' = 'cpml', cpml_layers: 'int' = 8, tfsf_margin: 'int' = 3, ntff_offset: 'int' = 1, subtract_incident_reference: 'bool' = False, phase_reference: 'tuple[float, float, float] | None' = None) -> 'RCSResult | ScatteringResponse'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/rcs.py#L189", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "JAX-differentiable RCS(θ,φ) from NTFF data — the AD counterpart of ``compute_rcs``.\n\n``compute_rcs`` orchestrates (TFSF setup → ``run`` → far-field → RCS) with a numpy\npost-processor, so it is NOT on the AD tape. This function is the differentiable\nPOST-PROCESSING half: given ``ntff_data`` accumulated by a differentiable\n``run(..., tfsf=…, ntff=…)`` (whose accumulators flow through the ``lax.scan`` AD\ntape w.r.t. the scatterer materials), it returns σ as a ``jnp`` array so\n``jax.grad`` flows scatterer-ε → RCS. It is the primitive behind differentiable\nRCS-reduction / -shaping inverse design.\n\nSame formula as ``compute_rcs`` (σ = 4π·|E_far|²/|E_inc|², ``compute_far_field``'s\n``E_θ``/``E_φ`` already carry the ``jk/4π`` factor so ``|E_θ|²+|E_φ|²`` is the\nr-scaled scattered power), evaluated with ``compute_far_field_jax``. For the\nmonostatic (backscatter) bin at normal +x incidence pass ``theta=[π/2], phi=[π]``.\n\nParameters\n----------\nntff_data : NTFFData\n NTFF surface accumulators from ``run(..., tfsf=…, ntff=…)`` (JAX arrays, on tape).\nbox : NTFFBox\ngrid : Grid\ntheta, phi : arrays in radians\n Observation directions. Backscatter for +x incidence is ``(π/2, π)``.\ne_inc_amplitude : (n_freqs,) complex array\n Incident plane-wave spectral amplitude for normalization — source-only, hence a\n CONSTANT for the gradient. At normal incidence use\n :func:`rfx.sources.tfsf.measure_normal_incident_spectrum`\n (``cfg, state, n_steps, freqs, dt``) on the same ``init_tfsf`` config the run\n uses — the incident the grid carries, as ``compute_rcs`` does. The source\n waveform's own DFT (``_incident_spectrum_amplitude``) is about 1.1 dB larger\n than that incident and makes σ low by the same 1.1 dB (issue #820).\n\nReturns\n-------\njnp.ndarray\n ``rcs_linear`` (n_freqs, n_theta, n_phi) in m², differentiable in ``ntff_data``\n (hence in the scatterer permittivity upstream). Take ``10·log10`` for dBsm.\n\nSee Also\n--------\ncompute_rcs : the numpy orchestrator (Mie-validated monostatic bin).\ncompute_far_field_jax : the differentiable far-field this builds on.", "kind": "function", "name": "rfx.compute_rcs_jax", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ntff_data" }, { "annotation": "NTFFBox", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "box" }, { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "e_inc_amplitude" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#compute_rcs_jax", "returns": { "annotation": null }, "signature": "(ntff_data, box: 'NTFFBox', grid: 'Grid', theta, phi, e_inc_amplitude)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/rcs.py#L131", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a mesh convergence study.\n\nParameters\n----------\nsim_factory : callable(dx) -> Simulation\n Builds a simulation at the given cell size.\ndx_values : list of float\n Cell sizes to test (coarse to fine).\nmetric_fn : callable(Result) -> float\n Extracts the metric of interest (e.g., resonance frequency).\nn_steps : int or None\n If given, passed as ``n_steps`` to each ``sim.run()``.\nuntil_decay : float or None\n If given, passed as ``until_decay`` to each ``sim.run()``.\nrun_kwargs : dict or None\n Additional keyword arguments forwarded to ``sim.run()``.\nexpected_order : float\n Initial guess for convergence order (default 2 for standard Yee).\n\nReturns\n-------\nConvergenceResult\n Container with dx_values, metrics, extrapolated value, order,\n relative errors, and raw results.", "kind": "function", "name": "rfx.convergence_study", "parameters": [ { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx_values" }, { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "metric_fn" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "until_decay" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_kwargs" }, { "annotation": "float", "default": "2.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "expected_order" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#convergence_study", "returns": { "annotation": "ConvergenceResult" }, "signature": "(sim_factory: 'Callable', dx_values, metric_fn: 'Callable', *, n_steps: 'int | None' = None, until_decay: 'float | None' = None, run_kwargs: 'dict | None' = None, expected_order: 'float' = 2.0) -> 'ConvergenceResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/convergence.py#L274", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "The radiation pattern of the block current moments a run accumulated.\n\n``result`` is what ``Simulation.run()`` or ``Simulation.forward()``\nreturned for a simulation that declared\n:meth:`~rfx.Simulation.add_current_moment_monitor`. Returns the same\n:class:`rfx.farfield.FarFieldResult` that :func:`rfx.compute_far_field`\nreturns for an NTFF box, in the same convention (``E_theta``, ``E_phi``\nomitting the ``1/r`` factor, ``exp(+jk rhat.r)`` phase), so\n:func:`rfx.directivity`, :func:`rfx.radiation_pattern` and\n:func:`rfx.axial_ratio` take it unchanged. The pattern is evaluated at\nevery monitored frequency.\n\nInside ``jax.grad`` or ``jax.jit`` (the accumulator is a tracer) the\npattern is built with ``jnp`` throughout and stays differentiable, as\n:func:`rfx.compute_far_field` dispatches to its JAX twin.", "kind": "function", "name": "rfx.current_moment_far_field", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(result, theta, phi)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/current_moments.py#L884", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Remove port extension (transmission line) effects from S-parameters.\n\nShifts the reference plane inward by removing the phase delay of the\nfeed lines at each port. Assumes lossless, matched feed lines (same\nimpedance as the port reference impedance) so only a phase correction\nis needed.\n\nParameters\n----------\ns_matrix : ndarray, shape (n_ports, n_ports, n_freqs)\n Complex S-parameter matrix.\nfreqs : ndarray, shape (n_freqs,)\n Frequency points in Hz.\nport_lengths : list of float or ndarray, shape (n_ports,)\n Physical length to de-embed from each port, in metres.\nz0 : float\n Port reference impedance (ohm). Not used in the phase-only\n correction but kept for API consistency and future lossy extension.\neps_eff : float or ndarray\n Effective relative permittivity of the feed line. A scalar\n applies uniformly; an array of shape ``(n_freqs,)`` supports\n dispersive media.\n\nReturns\n-------\nndarray, shape (n_ports, n_ports, n_freqs)\n De-embedded S-parameter matrix.", "kind": "function", "name": "rfx.deembed_port_extension", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_matrix" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "list[float] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_lengths" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "z0" }, { "annotation": "float | np.ndarray", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_eff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#deembed_port_extension", "returns": { "annotation": "np.ndarray" }, "signature": "(s_matrix: 'np.ndarray', freqs: 'np.ndarray', port_lengths: 'list[float] | np.ndarray', z0: 'float' = 50.0, eps_eff: 'float | np.ndarray' = 1.0) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/deembed.py#L30", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "De-embed a DUT using a thru-line measurement (TRL-lite).\n\nAssumes a symmetric two-port fixture: the thru standard captures the\ncombined effect of both fixture halves in cascade. The fixture\nhalf-network is extracted from the thru, inverted, and removed from\neach side of the measured DUT.\n\nThis is a simplified single-thru calibration; for full TRL accuracy,\nreflect and line standards would also be needed.\n\nThe algorithm:\n\n1. Convert the thru S-matrix to a transfer (T) matrix.\n2. Take the matrix square root to get the fixture half T-matrix.\n3. Invert the fixture half.\n4. Cascade: T_dut = T_fix_inv @ T_meas @ T_fix_inv.\n5. Convert back to S-parameters.\n\nParameters\n----------\ns_measured : ndarray, shape (2, 2, n_freqs)\n Measured S-parameters of the DUT including fixture.\ns_thru : ndarray, shape (2, 2, n_freqs)\n Measured S-parameters of the thru standard (fixture back-to-back).\n\nReturns\n-------\nndarray, shape (2, 2, n_freqs)\n De-embedded S-parameters of the DUT.\n\nRaises\n------\nValueError\n If inputs are not 2-port matrices or have mismatched frequency counts.", "kind": "function", "name": "rfx.deembed_thru", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_measured" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_thru" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#deembed_thru", "returns": { "annotation": "np.ndarray" }, "signature": "(s_measured: 'np.ndarray', s_thru: 'np.ndarray') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/deembed.py#L103", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Backward-compatible density -> (eps, sigma) helper.", "kind": "function", "name": "rfx.density_to_eps", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rho" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_bg" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_fg" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "filter_radius_cells" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "beta" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma_bg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma_fg" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#density_to_eps", "returns": { "annotation": "tuple[jnp.ndarray, jnp.ndarray]" }, "signature": "(rho: 'jnp.ndarray', eps_bg: 'float', eps_fg: 'float', filter_radius_cells: 'float | None' = None, beta: 'float' = 1.0, sigma_bg: 'float' = 0.0, sigma_fg: 'float' = 0.0) -> 'tuple[jnp.ndarray, jnp.ndarray]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L259", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Report available JAX compute devices.", "kind": "function", "name": "rfx.device_info", "parameters": [], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#device_info", "returns": { "annotation": "DeviceInfo" }, "signature": "() -> 'DeviceInfo'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/gpu.py#L32", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Result accessor for one or more registered DFT-plane probes.\n\nParameters\n----------\nnames : str or sequence of str\n The ``name=`` (or auto-generated default) given to\n ``add_dft_plane_probe(...)``. A single name returns the raw\n ``(n_freqs, n1, n2)`` complex accumulator directly (no dict\n wrapping -- there is nothing to disambiguate). A sequence of names\n returns either a stacked array or a dict, controlled by *stack*.\nstack : bool\n When *names* is a sequence and ``stack=True`` (default), the\n accessor stacks all requested planes into one\n ``(n_names, n_freqs, n1, n2)`` array ALONG A NEW LEADING AXIS --\n but only when every requested plane has the same\n ``(n_freqs, n1, n2)`` shape (planes at different axes/coordinates\n commonly do not, e.g. a yz-plane vs an xz-plane monitor). When the\n shapes differ, stacking is impossible and the accessor RAISES\n ``ValueError`` naming the mismatched shapes and pointing at\n ``stack=False``; it never silently truncates or broadcasts. Pass\n ``stack=False`` explicitly to opt into the per-name\n ``dict[name] -> array`` form instead (also the unconditional return\n form when *names* is a sequence and ``stack=False``, even if the\n shapes happen to match). Mixed-dtype stacking (e.g. a complex64\n plane alongside a complex128 one, possible if planes were\n registered under different ``jax_enable_x64`` states) follows\n ordinary ``jnp.stack`` dtype promotion -- the result takes the\n wider dtype.\n\nReturns\n-------\ncallable(result) -> jnp.ndarray | dict[str, jnp.ndarray]\n JAX-differentiable: the returned array(s) are views/stacks of the\n same accumulator that was carried through the FDTD scan, so\n ``jax.grad`` flows through them unchanged.\n\nRaises\n------\nValueError\n If *result* carries no ``dft_planes`` at all, is missing one of the\n requested *names*, or (list form, ``stack=True``) the requested\n planes' shapes do not match -- naming the fix in each case.", "kind": "function", "name": "rfx.dft_field", "parameters": [ { "annotation": "str | Sequence[str]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "names" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stack" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#dft_field", "returns": { "annotation": "Callable" }, "signature": "(names: 'str | Sequence[str]', *, stack: 'bool' = True) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/observables.py#L133", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return an rfx diagnostic report for JAX saved residuals.\n\nThe report layers rfx-owned summaries and recommendations on top of\n``inspect_ad_saved_residuals``. It inspects ``fun(*args, **kwargs)`` and\npreserves exceptions from tracing the callable. Optional ``context`` and\n``artifacts`` are serialized as snapshots only; they are not used to infer\nruntime memory fit or physics validity.", "kind": "function", "name": "rfx.diagnose_ad_saved_residuals", "parameters": [ { "annotation": "Callable[..., Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fun" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_POSITIONAL", "name": "args" }, { "annotation": "int", "default": "10", "has_default": true, "kind": "KEYWORD_ONLY", "name": "top_n" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "workflow" }, { "annotation": "Mapping[str, object] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "context" }, { "annotation": "Mapping[str, object] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "artifacts" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#diagnose_ad_saved_residuals", "returns": { "annotation": "ADSavedResidualDiagnosticReport" }, "signature": "(fun: 'Callable[..., Any]', *args: 'Any', top_n: 'int' = 10, workflow: 'str | None' = None, context: 'Mapping[str, object] | None' = None, artifacts: 'Mapping[str, object] | None' = None, **kwargs: 'Any') -> 'ADSavedResidualDiagnosticReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L523", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Fit dispersive material poles to S-parameter data via jax.grad through FDTD.\n\nParameters\n----------\nsim_factory : callable(eps_inf, debye_poles, lorentz_poles) -> Simulation\n Factory that builds a ``Simulation`` with the given material\n parameters. The fixture geometry, ports, and probes are set\n inside this callable. It is called once outside the gradient\n tape for static setup and again with traced poles for each loss\n evaluation. Declarations not carried by the fit's assembly are\n refused before FDTD (#1290), including wire/passive/MSL/modal\n ports, plain/TFSF sources, lumped RLC, periodic overrides, Kerr,\n conformal walls, point ports on PEC edges, and non-default solver,\n precision, stencil or interface settings. Refinements, non-uniform\n meshes, and surface-impedance sheets retain their existing refusals.\ns_measured : (n_ports, n_ports, n_freqs) complex array\n Measured S-parameter matrix.\nfreqs : (n_freqs,) array in Hz\n Frequency points matching ``s_measured``.\nn_debye_poles : int\n Number of Debye poles to fit.\nn_lorentz_poles : int\n Number of Lorentz poles to fit.\nn_iterations : int\n Number of Adam optimization iterations.\nlearning_rate : float\n Adam learning rate.\ninitial_guess : DebyeFitResult, LorentzFitResult, or None\n Initial pole parameters from ``fit_debye`` / ``fit_lorentz``.\n If None, a frequency-band-based default is used.\nweight_mag, weight_phase : float\n Weights for magnitude and phase in the S-parameter loss.\ncheckpoint : bool\n Use ``jax.checkpoint`` in the FDTD loop (recommended).\nverbose : bool\n Print progress.\nnormalization : {\"per_probe_max\", \"reference_probe\"}\n Loss-proxy normalization mode (issue #580; see the module\n docstring's ACCURACY CAVEAT for when each is appropriate).\n ``\"per_probe_max\"`` (default, legacy) is shape-only and BLIND to\n magnitude-acting parameters such as conductivity;\n ``\"reference_probe\"`` divides every probe spectrum, complex and\n per-frequency, by the designated reference probe's spectrum, so\n magnitude and inter-probe level enter the loss while the shared\n drive amplitude cancels.\nreference_probe : int or None\n Required (and only used) with ``normalization=\"reference_probe\"``:\n index into the fixture's registered probe list of the probe that\n records the reference (incident-side) signal. Must not be one of\n the first ``n_ports`` probes — those are the response probes the\n proxy is built from, and self-referencing would reintroduce the\n degeneracy this mode exists to remove.\n\nReturns\n-------\nMaterialFitResult\n ``final_s_params`` carries the LAST iteration's model-side proxy\n spectrum (same normalization as the loss) — previously this field\n was always ``None``.", "kind": "function", "name": "rfx.differentiable_material_fit", "parameters": [ { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_measured" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_debye_poles" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_lorentz_poles" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_iterations" }, { "annotation": "float", "default": "0.01", "has_default": true, "kind": "KEYWORD_ONLY", "name": "learning_rate" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "initial_guess" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "weight_mag" }, { "annotation": "float", "default": "0.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "weight_phase" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "verbose" }, { "annotation": "str", "default": "'per_probe_max'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "normalization" }, { "annotation": "'int | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_probe" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#differentiable_material_fit", "returns": { "annotation": "MaterialFitResult" }, "signature": "(sim_factory: 'Callable', s_measured: 'np.ndarray', freqs: 'np.ndarray', n_debye_poles: 'int' = 1, n_lorentz_poles: 'int' = 0, *, n_iterations: 'int' = 50, learning_rate: 'float' = 0.01, initial_guess=None, weight_mag: 'float' = 1.0, weight_phase: 'float' = 0.1, checkpoint: 'bool' = True, verbose: 'bool' = True, normalization: 'str' = 'per_probe_max', reference_probe: \"'int | None'\" = None) -> 'MaterialFitResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/differentiable_material_fit.py#L375", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Directivity in dBi for each frequency.\n\nIntegrates radiated power over the full sphere using gradient weights\nand computes D = 4π U_max / P_rad. Requires full-sphere coverage;\na single phi cut assumes an axisymmetric pattern.\n\nReturns (n_freqs,) array.", "kind": "function", "name": "rfx.directivity", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#directivity", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1491", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a Drude pole from plasma frequency and collision rate.\n\nParameters\n----------\nomega_p : float\n Plasma frequency (rad/s).\ngamma : float\n Collision rate (rad/s).", "kind": "function", "name": "rfx.drude_pole", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "omega_p" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "gamma" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#drude_pole", "returns": { "annotation": "LorentzPole" }, "signature": "(omega_p: 'float', gamma: 'float') -> 'LorentzPole'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/lorentz.py#L59", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "True iff the E edge ``component`` at index ``(i, j, k)`` is PEC.\n\n``component`` is ``\"ex\"``/``\"ey\"``/``\"ez\"``, ``\"x\"``/``\"y\"``/``\"z\"`` or\n0/1/2. Wire-port live-cell logic (#556 end gap, #929 ``port_in_pec``),\nprobes and sources read this instead of scanning a cell mask.", "kind": "function", "name": "rfx.edge_is_pec", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "edge_masks" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "i" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "j" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "k" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#edge_is_pec", "returns": { "annotation": "bool" }, "signature": "(edge_masks, component, i, j, k) -> 'bool'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/boundaries/pec.py#L774", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return points satisfying raw epsilon constraints per objective.\n\nFor minimization objectives the constraint is ``objective <= epsilon``; for\nmaximization objectives it is ``objective >= epsilon``. Objective indices not\npresent in ``epsilons`` are unconstrained.", "kind": "function", "name": "rfx.epsilon_constraint_mask", "parameters": [ { "annotation": "Sequence[Sequence[float]] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "Mapping[int, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "epsilons" }, { "annotation": "bool | Sequence[bool]", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "minimize" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "atol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#epsilon_constraint_mask", "returns": { "annotation": "np.ndarray" }, "signature": "(objectives: 'Sequence[Sequence[float]] | np.ndarray', epsilons: 'Mapping[int, float]', *, minimize: 'bool | Sequence[bool]' = True, atol: 'float' = 0.0) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L262", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Evaluate a Debye model at given frequencies.\n\nParameters\n----------\nfreqs : (N,) array in Hz\neps_inf : high-frequency permittivity\npoles : list of DebyePole\n\nReturns\n-------\neps_complex : (N,) complex array", "kind": "function", "name": "rfx.eval_debye", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_inf" }, { "annotation": "list[DebyePole]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "poles" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#eval_debye", "returns": { "annotation": "np.ndarray" }, "signature": "(freqs: 'np.ndarray', eps_inf: 'float', poles: 'list[DebyePole]') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L455", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Evaluate a Lorentz or Drude pole model at given frequencies.\n\nParameters\n----------\nfreqs : (N,) array in Hz\neps_inf : high-frequency permittivity\npoles : list of LorentzPole (``lorentz_pole`` or ``drude_pole``; a Drude\n pole has ``omega_0 == 0`` and gives eps_inf - omega_p^2 / (w^2 - j*gamma*w))\n\nReturns\n-------\neps_complex : (N,) complex array", "kind": "function", "name": "rfx.eval_lorentz", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_inf" }, { "annotation": "list[LorentzPole]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "poles" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#eval_lorentz", "returns": { "annotation": "np.ndarray" }, "signature": "(freqs: 'np.ndarray', eps_inf: 'float', poles: 'list[LorentzPole]') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L473", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Write a runtime artifact bundle directory and return its paths.", "kind": "function", "name": "rfx.export_artifact_bundle", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "Any", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_markdown" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_scene" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_geometry_json" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_field_vtk" }, { "annotation": "Any", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_state" }, { "annotation": "Any", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_grid" }, { "annotation": "dict[str, Any] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "extra" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#export_artifact_bundle", "returns": { "annotation": "ArtifactBundle" }, "signature": "(path: 'str | Path', sim: 'Any', result: 'Any' = None, *, include_markdown: 'bool' = True, include_scene: 'bool' = True, include_geometry_json: 'bool' = True, include_field_vtk: 'bool' = False, field_state: 'Any' = None, field_grid: 'Any' = None, extra: 'dict[str, Any] | None' = None) -> 'ArtifactBundle'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L867", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export a lightweight geometry *index* as JSON (bounding boxes only).\n\nIntended for dataset indexing and eyeball review. Each geometry entry is\nrecorded as its shape class name plus a bounding box, so a ``Cylinder`` and\na ``Box`` with the same bounds are indistinguishable here, and materials are\nreduced to scalar ``eps_r``/``sigma``/``mu_r`` (dispersion poles are\ndropped). Sources are recorded as position + component only.\n\nThis output therefore **cannot round-trip** and is not a design description:\ndo not drive an external solver from it. For a round-trip-complete design\ndocument use :func:`rfx.interop.design_to_dict` /\n:func:`rfx.interop.design_to_json`, which record constructor parameters and\nrefuse rather than degrade what they cannot represent.\n\nParameters\n----------\npath : str or Path\nsim : Simulation", "kind": "function", "name": "rfx.export_geometry_json", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#export_geometry_json", "returns": { "annotation": null }, "signature": "(path, sim)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L879", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export simulation geometry as a signed distance field.\n\nBuilds a 3-D grid at the requested *resolution* covering the\nsimulation domain and evaluates the geometry mask. The SDF is\napproximated from the binary mask via a distance transform:\n\n- negative inside geometry (material regions)\n- positive outside\n- magnitude = approximate Euclidean distance to the nearest boundary\n (in metres)\n\nThis is suitable as input to geometry-conditioned neural operators\n(e.g., DeepONet, Fourier Neural Operator).\n\n**Sheets.** A conductor declared as a sheet — ``add_thin_conductor``,\nor a zero-thickness PEC Box, which is the same declaration (lattice\nownership contract §1.5) — has no interior, so a containment test\nfinds it only if its plane happens to land exactly on a sample. Before\nthis it did not land: ``add_thin_conductor`` sheets are not in\n``sim._geometry`` at all and never reached the exporter, so every\nsheet-declared ground plane, patch and trace was missing from the\nexported training data with no error anywhere.\n\nA zero-thickness region cannot be represented in a sampled occupancy\nfield as zero thickness. The convention here, stated rather than\ninferred: **a sheet occupies exactly ONE sample layer** — the sample\nplane nearest its declared mid-plane, with the drawn footprint sampled\nclosed in-plane — so the distance transform reads ``-resolution`` on\nthe sheet and the sheet's apparent thickness in the SDF is one sample,\nnot zero. That is the same realization rule the solve uses (a sheet is\none node plane); only the lattice differs. A sheet whose plane or\nfootprint cannot be placed on this lattice raises rather than\nvanishing — refine ``resolution``.\n\nParameters\n----------\nsim : Simulation\n A configured simulation with geometry added.\nresolution : float\n Spatial resolution of the SDF grid (metres). Default 1 mm.\n\nReturns\n-------\nsdf : ndarray, shape (Nx, Ny, Nz)\n Signed distance field in metres.", "kind": "function", "name": "rfx.export_geometry_sdf", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "float", "default": "0.001", "has_default": true, "kind": "KEYWORD_ONLY", "name": "resolution" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#export_geometry_sdf", "returns": { "annotation": "np.ndarray" }, "signature": "(sim, *, resolution: 'float' = 0.001) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/surrogate.py#L160", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export a completed host NTFF record without changing its phase or scale.\n\nRequires all six face-centred accumulators (gather distributed data first).\nPass the actual run dt, not grid.dt when the runner derates its timestep.\nGeometry uses the grid's physical metric, including actual asymmetric pads\nand graded cells. The grid/box must be the ones used for accumulation.\nLegacy node-layout data cannot be retrospectively collocated and is refused.\nSubgrid result grids lack a global-origin contract and are also refused.\nRaw data may already be a scattered field; no total/scattered classification\nor incident-field subtraction is inferred. This is not a JIT/AD operation.", "kind": "function", "name": "rfx.export_ntff_surface", "parameters": [ { "annotation": "NTFFData", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "data" }, { "annotation": "NTFFBox", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "box" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "dt" }, { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "step_start" } ], "reference_url": null, "returns": { "annotation": "NTFFSurface" }, "signature": "(data: 'NTFFData', box: 'NTFFBox', grid, *, dt: 'float', n_steps: 'int', step_start: 'int' = 0) -> 'NTFFSurface'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ntff_surface.py#L159", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export radiation pattern as CSV for measurement comparison.\n\nColumns: theta_deg, phi_deg, E_theta_mag, E_theta_phase_deg,\n E_phi_mag, E_phi_phase_deg, gain_dBi\n\nParameters\n----------\npath : str or Path\nff_result : FarFieldResult\nfreq_idx : int\n Frequency index to export.\ninput_power : array-like (n_freqs,) or scalar, optional\n Input power in watts, passed to :func:`rfx.antenna.antenna_gain_dB`\n for realized gain. Without it, gain_dBi is absolute IEEE gain\n normalized by total radiated power. That integral requires full-sphere\n coverage, or one phi cut under an axisymmetric assumption. Realized\n gain with input_power accepts partial angular patterns.", "kind": "function", "name": "rfx.export_radiation_pattern", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff_result" }, { "annotation": null, "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_idx" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "input_power" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#export_radiation_pattern", "returns": { "annotation": null }, "signature": "(path, ff_result, freq_idx=0, *, input_power=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L832", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export parametric sweep results as neural network training data.\n\nFrom a ``SweepResult`` or ``VmapSweepResult``, creates arrays:\n\n- **inputs** : parameter values, shape ``(n_samples, 1)``\n- **outputs** : time-series probe data, shape ``(n_samples, n_steps, n_probes)``\n (``SweepResult``) or ``(n_samples, n_steps, n_probes)``\n (``VmapSweepResult``). When S-parameters are available (``SweepResult``\n with ports), an ``s_params`` array is also stored.\n- **metadata** : parameter name and frequency array (when available).\n\nParameters\n----------\nsweep_result : SweepResult or VmapSweepResult\n Output of ``parametric_sweep`` or ``vmap_material_sweep``.\noutput_path : str or Path\n Destination file path.\nformat : ``\"npz\"``\n Output format (currently only NumPy ``.npz`` is supported).\n\nReturns\n-------\nPath\n The written file path.\n\nRaises\n------\nValueError\n If format is unsupported or sweep_result type is unrecognised.", "kind": "function", "name": "rfx.export_training_data", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sweep_result" }, { "annotation": "str | Path", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "output_path" }, { "annotation": "str", "default": "'npz'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "format" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#export_training_data", "returns": { "annotation": "Path" }, "signature": "(sweep_result, *, output_path: 'str | Path', format: 'str' = 'npz') -> 'Path'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/surrogate.py#L28", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Pull V/I phasors from DFT plane probes at the coaxial reference plane.\n\nA convenience wrapper (its first caller, the single-plane coaxial lane,\nwas removed in #1212): it takes the DFT-plane outputs (one per\nEx/Ey/Hx/Hy component) and delegates to\n:func:`coaxial_tem_reference_plane_vi_from_cartesian_plane`, which\nalready implements the radial line-integral / azimuthal loop-integral\nextraction with bilinear interpolation.\n\nThe plane probes must be on the same cross-section that\n:func:`build_coaxial_tem_plane_source_specs` injected on, i.e.\n``plane_axial_index``.\n\nThe ``current_sign`` is derived from the port's face direction. The\nraw azimuthal-loop integral ``2π·r·⟨H_φ⟩`` measures the line current\nflowing in the ``+ẑ`` direction; the standard ``V/I = +Z_TEM`` forward-\nwave convention requires this to align with the *forward* direction of\nthe source. For ``face='top'`` the source emits in ``-z`` (pin extends\ninto ``-z``), so ``current_sign = -1`` gives ``V/I = +Z_TEM`` for a\nclean forward wave; ``face='bottom'`` emits ``+z`` and uses\n``current_sign = +1``. Without this, a power-wave S11 built from these\nphasors reads ``|S11| = 1/Γ`` instead of ``Γ`` for ``face='top'`` ports —\nsame magnitude for lossless reflections but the wrong phase, and\nbiased away from 1 by numerical asymmetries.", "kind": "function", "name": "rfx.extract_coaxial_plane_vi_from_dft", "parameters": [ { "annotation": "'Grid'", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "grid" }, { "annotation": "CoaxialPort", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "port" }, { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "plane_axial_index" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "ex_dft" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "ey_dft" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "hx_dft" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "hy_dft" }, { "annotation": "float", "default": "2.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" } ], "reference_url": null, "returns": { "annotation": "CoaxialTEMCartesianPlaneVI" }, "signature": "(*, grid: \"'Grid'\", port: 'CoaxialPort', plane_axial_index: 'int', ex_dft: 'np.ndarray', ey_dft: 'np.ndarray', hx_dft: 'np.ndarray', hy_dft: 'np.ndarray', eps_r: 'float' = 2.1) -> 'CoaxialTEMCartesianPlaneVI'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/coaxial_port.py#L993", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract Floquet mode amplitudes from accumulated DFT data.\n\nOnly the specular ``(0,0)`` mode with **TE** polarization is implemented (the\nextractor reads the (Ex, Hy) tangential pair and the TE wave impedance\n``eta0/cos(theta)``). ``n_modes > 1`` (higher-order grating lobes) and TM\npolarization are NOT implemented and are rejected fail-loud rather than\nsilently returning wrong results (RF-audit 2026-07-23).\n\nParameters\n----------\nacc : FloquetDFTAccumulator\n Accumulated field DFTs on the port plane.\ndx : float\n Grid cell size (metres).\nLx, Ly : float\n Unit cell periods (metres).\nfreqs : (n_freqs,) array\n Frequencies.\ntheta_deg, phi_deg : float\n Scan angles (degrees).\nn_modes : int\n Number of Floquet modes to extract.\n\nReturns\n-------\ndict with keys:\n 'S' : (n_modes, n_freqs) complex array of Floquet S-parameters\n 'modes' : list of (m, n) mode index tuples\n 'freqs' : frequency array", "kind": "function", "name": "rfx.extract_floquet_modes", "parameters": [ { "annotation": "FloquetDFTAccumulator", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "acc" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Lx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Ly" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_deg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_deg" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_modes" } ], "reference_url": null, "returns": { "annotation": "dict" }, "signature": "(acc: 'FloquetDFTAccumulator', dx: 'float', Lx: 'float', Ly: 'float', freqs: 'jnp.ndarray', theta_deg: 'float' = 0.0, phi_deg: 'float' = 0.0, n_modes: 'int' = 1) -> 'dict'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L297", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assemble a multi-mode waveguide S-matrix.\n\n``field_dtype`` is forwarded to every core run; ``None`` uses float32.\nModal records preserve their precision and widen for field storage.\nSpectra and S promote the record and frequency dtypes.\n\nEach physical port may have multiple modes. The S-matrix indices\nenumerate (port_index, mode_index) pairs.\n\nParameters\n----------\ngrid : Grid\n Simulation grid.\nmaterials : MaterialArrays\n Material arrays.\nport_mode_cfgs : list of list of WaveguidePortConfig\n ``port_mode_cfgs[p]`` is a list of configs for physical port ``p``,\n one per mode.\nn_steps : int\n Number of timesteps per run.\nref_shifts : list[float] or None\n Reference-plane shifts per physical port. Applied to all modes\n of each port.\n\nReturns\n-------\ns_matrix : jnp.ndarray, shape (N, N, n_freqs)\n S-matrix where N = sum of modes across all ports.\nmode_map : list of (port_idx, mode_idx, mode_type, (m, n))\n Ordering of rows/columns in the S-matrix.", "kind": "function", "name": "rfx.extract_multimode_s_matrix", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "list[list[WaveguidePortConfig]]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_mode_cfgs" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "str", "default": "'yz'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_axes" }, { "annotation": "tuple[bool, bool, bool] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "periodic" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz" }, { "annotation": "list[float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shifts" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_eps" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_weights" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_dtype" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "settling_details" } ], "reference_url": null, "returns": { "annotation": "tuple[jnp.ndarray, list[tuple[int, int, str, tuple[int, int]]]]" }, "signature": "(grid, materials, port_mode_cfgs: 'list[list[WaveguidePortConfig]]', n_steps: 'int', *, boundary: 'str' = 'cpml', cpml_axes: 'str | None' = None, pec_axes: 'str' = 'yz', periodic: 'tuple[bool, bool, bool] | None' = None, debye: 'tuple | None' = None, lorentz: 'tuple | None' = None, ref_shifts: 'list[float] | None' = None, aniso_eps: 'tuple | None' = None, conformal_weights: 'tuple | None' = None, aniso_inv_eps: 'tuple | None' = None, pec_edge_masks: 'tuple | None' = None, field_dtype=None, settling_details: 'list | None' = None) -> 'tuple[jnp.ndarray, list[tuple[int, int, str, tuple[int, int]]]]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L2856", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract full N-port S-parameter matrix for WirePort objects.\n\nRuns N simulations (one per excitation port). All port impedances\nare active in every run so that port loading is consistent.\n\nParameters\n----------\ngrid : Grid\nmaterials : MaterialArrays\n Base materials **without** port impedances folded in.\nports : list of WirePort\nfreqs : (n_freqs,) Hz\nn_steps : int or None\n Defaults to ``grid.num_timesteps(num_periods=30)``.\nboundary : \"pec\" or \"cpml\"\ncpml_axes : str or None: the grid's absorbing axes when omitted; subsets accepted\ndebye_spec, lorentz_spec : optional dispersion specs\nreturn_vi_dump : bool\n When True, return a :class:`WirePortVIReplayBundle` containing the\n production S-matrix plus raw midpoint-cell V/I phasors for independent\n replay of the current wire-port convention.\n\nReturns\n-------\nS or WirePortVIReplayBundle\n By default, returns an S-matrix. With ``return_vi_dump=True``, the\n bundle also carries raw phasors and per-port wire cell counts.", "kind": "function", "name": "rfx.extract_s_matrix_wire", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ports" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "str", "default": "'pec'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "tuple[list, list[jnp.ndarray]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye_spec" }, { "annotation": "tuple[list, list[jnp.ndarray]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz_spec" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_vi_dump" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#extract_s_matrix_wire", "returns": { "annotation": "jnp.ndarray | WirePortVIReplayBundle" }, "signature": "(grid, materials, ports: 'list', freqs: 'jnp.ndarray', n_steps: 'int | None' = None, *, boundary: 'str' = 'pec', cpml_axes: 'str | None' = None, debye_spec: 'tuple[list, list[jnp.ndarray]] | None' = None, lorentz_spec: 'tuple[list, list[jnp.ndarray]] | None' = None, pec_edge_masks: 'object | None' = None, return_vi_dump: 'bool' = False) -> 'jnp.ndarray | WirePortVIReplayBundle'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L1874", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return port-local (incident, outgoing) waves at a shifted reference plane.\n\nThe spectra are recomputed POST-SCAN from the per-step modal V/I\ntime series via a rectangular full-record DFT (matching OpenEMS's\n``utilities.DFT_time2freq``). The legacy in-scan windowed/gated\nDFT accumulators were removed in the Phase 2 cleanup\n(2026-04-25): they integrated partially-decayed standing waves\nand produced ``|S11|`` that grew without bound as the gate widened.", "kind": "function", "name": "rfx.extract_waveguide_port_waves", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shift" } ], "reference_url": null, "returns": { "annotation": "tuple[jnp.ndarray, jnp.ndarray]" }, "signature": "(cfg: 'WaveguidePortConfig', *, ref_shift: 'float' = 0.0) -> 'tuple[jnp.ndarray, jnp.ndarray]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1719", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract S11 from backward/forward modal amplitudes with optional de-embedding.", "kind": "function", "name": "rfx.extract_waveguide_s11", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shift" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#extract_waveguide_s11", "returns": { "annotation": "jnp.ndarray" }, "signature": "(cfg: 'WaveguidePortConfig', *, ref_shift: 'float' = 0.0) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1711", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract S21 from forward-wave modal amplitudes with optional de-embedding.", "kind": "function", "name": "rfx.extract_waveguide_s21", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shift" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_shift" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#extract_waveguide_s21", "returns": { "annotation": "jnp.ndarray" }, "signature": "(cfg: 'WaveguidePortConfig', dt: 'float' = 0.0, *, ref_shift: 'float' = 0.0, probe_shift: 'float' = 0.0) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1697", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Assemble an x-directed waveguide S-matrix via one-driven-port-at-a-time runs.\n\n``field_dtype`` is forwarded to every core run; ``None`` uses float32.\nModal records preserve their precision and widen for field storage.\nSpectra and S promote the record and frequency dtypes.\n\nPEC realization (#931 §1.7): interior ``Box(material='pec')`` walls\nreach this lane as the realized edge masks ``pec_edge_masks``\n(``rfx.boundaries.pec.realized_pec_edge_masks``), applied per step by\nthe shared ``apply_pec_edges``. Until #931 the caller folded the PEC\nCELL mask into ``sigma = 1e10`` instead — a fourth realization of the\nsame geometry, and one that damped only the components indexed by the\noccupied cell, so a one-cell-thick wall or iris got its lower face and\nnever its far one. An empty-guide REFERENCE run gets no interior edge\nmasks; per-port reference geometry supplies its own.\n\n\n``return_settling=True`` (issue #538) additionally returns the\nper-driven-run pole-tail amplitude witness: ``(S, settling_db)`` with\n``settling_db`` shape ``(n_ports,)`` from\n:func:`settling_db_from_port_records` (NaN per run under tracing).\nDefault ``False`` keeps the legacy single-array return for existing\ncallers, and the S values are identical either way — the witness is\npost-processing of records the scan already produces.\n\ncheckpoint_segments : int or None\n When set, enables segmented gradient checkpointing on each per-port\n FDTD run (forwarded to ``rfx.simulation.run`` as\n ``checkpoint=True, checkpoint_segments=K``). See\n :meth:`Simulation.compute_waveguide_s_matrix` for full semantics.", "kind": "function", "name": "rfx.extract_waveguide_s_matrix", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "list[WaveguidePortConfig]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_cfgs" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "str", "default": "'yz'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_axes" }, { "annotation": "tuple[bool, bool, bool] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "periodic" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz" }, { "annotation": "list[float] | tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shifts" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_eps" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_weights" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_settling" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "settling_details" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sheet_impedance" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_dtype" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#extract_waveguide_s_matrix", "returns": { "annotation": "'jnp.ndarray | tuple[jnp.ndarray, np.ndarray]'" }, "signature": "(grid, materials, port_cfgs: 'list[WaveguidePortConfig]', n_steps: 'int', *, boundary: 'str' = 'cpml', cpml_axes: 'str | None' = None, pec_axes: 'str' = 'yz', periodic: 'tuple[bool, bool, bool] | None' = None, debye: 'tuple | None' = None, lorentz: 'tuple | None' = None, ref_shifts: 'list[float] | tuple[float, float] | None' = None, aniso_eps: 'tuple | None' = None, conformal_weights: 'tuple | None' = None, aniso_inv_eps: 'tuple | None' = None, checkpoint_segments: 'int | None' = None, return_settling: 'bool' = False, settling_details: 'list | None' = None, sheet_impedance: 'object | None' = None, pec_edge_masks: 'tuple | None' = None, field_dtype=None) -> \"'jnp.ndarray | tuple[jnp.ndarray, np.ndarray]'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1888", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract (S11, S21) with optional reference-plane shifts.\n\nThe Phase 2 cleanup (2026-04-25) removed the in-scan DFT accumulators\n(``cfg.v_ref_dft`` etc.) from ``WaveguidePortConfig``. Callers that\nused to read those fields off the config now must either:\n\n1. Pass V/I DFT spectra explicitly via the ``*_dft`` keyword args\n (used by direct unit-test mock paths and by callers that have\n precomputed the spectra outside the FDTD scan); OR\n2. Use ``extract_waveguide_port_waves`` /\n ``extract_waveguide_s_matrix`` which run the canonical post-scan\n rectangular full-record DFT on ``cfg.v_ref_t`` / ``cfg.i_ref_t``.\n\nWhen the explicit DFTs are not provided this function falls back to\nthe post-scan rect-DFT path on the recorded time series.\n\nParameters\n----------\nref_shift : float\n Metres to shift the reference-plane reporting location relative to the\n stored reference probe. Positive is downstream (+x), negative upstream.\nprobe_shift : float\n Metres to shift the probe-plane reporting location relative to the\n stored probe plane. Positive is downstream (+x), negative upstream.\nv_ref_dft, i_ref_dft, v_probe_dft, i_probe_dft : array or None\n Optional precomputed V/I spectra at the reference and probe\n planes. When all are given the wave decomposition runs against\n them directly; otherwise the recorded time-series on ``cfg`` is\n used.", "kind": "function", "name": "rfx.extract_waveguide_sparams", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_shift" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_shift" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "v_ref_dft" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "i_ref_dft" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "v_probe_dft" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "i_probe_dft" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#extract_waveguide_sparams", "returns": { "annotation": "tuple[jnp.ndarray, jnp.ndarray]" }, "signature": "(cfg: 'WaveguidePortConfig', *, ref_shift: 'float' = 0.0, probe_shift: 'float' = 0.0, v_ref_dft: 'jnp.ndarray | None' = None, i_ref_dft: 'jnp.ndarray | None' = None, v_probe_dft: 'jnp.ndarray | None' = None, i_probe_dft: 'jnp.ndarray | None' = None) -> 'tuple[jnp.ndarray, jnp.ndarray]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1633", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Per-entity declared-vs-realized audit; returns a list of dicts.\n\nFindings never predict physics. Each entry reports, in input units:\n\n* rasterization — occupied cell count (0 = the entity is silently\n ABSENT from the solve), realized bounds from the run's own node\n coordinates, per-axis face residuals and extent deltas;\n* realization class for conductors (#931 lattice ownership contract)\n — volumetric PEC / one-cell PEC volume (walls on BOTH bounding node\n planes, interior shorted); a zero-thickness Box or a PEC thin\n conductor is a sheet and owns no cell;\n* materialization for dielectrics — the assembled eps_r/sigma inside\n the entity's cells vs the declared values (later entities may have\n overwritten earlier ones);\n* a mechanical remedy per finding class (no impact estimates).\n\nThe list LEADS with a ``\"domain (the solved box)\"`` pseudo-entity —\nthe only row a cavity/waveguide model has, since there the box IS the\ngeometry. Its per-axis ``n_cells`` / ``realized_extent_um`` are the\nwall-to-wall CELL count and length, i.e. ``cells_spanning(L, dx)`` cells,\nnot the ``+ 1`` node count the grid allocates. That was a bare\n``ceil(L / dx)`` until #1070, which made a ratio within a few ULP of an\ninteger snap to it rather than buy a cell no declared Box reaches. An axis the solve\ndoes not have — ``z`` under ``mode=\"2d_tmz\"``, where ``grid.nz == 1``\nand the declared ``Lz`` is ignored — is not compared: that axis dict\ncarries a ``note`` key (rendered by the printed report) instead of a\nfinding.", "kind": "function", "name": "rfx.fidelity_report", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "print_report" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(sim, print_report: 'bool' = True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/fidelity.py#L153", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Objective factory: ``sum(|field|**2)`` over one or more DFT planes.\n\nSums squared magnitude over every element (space AND frequency) of\nevery requested plane. Trivially smooth (a sum of squares is C-infinity\nin the accumulator), so this is a good first objective to sanity-check\na new DFT-plane setup with before reaching for :func:`field_softmax`.\n\nParameters\n----------\nnames : str or sequence of str\n Plane name(s) to sum over -- see :func:`dft_field`. Shapes need not\n match between planes (unlike ``dft_field(..., stack=True)``): each\n plane's energy is summed independently, so mixing e.g. a yz-plane\n and an xz-plane monitor is fine.\nweights : dict[str, float] or None\n Optional per-plane scalar weight (default 1.0 for every plane not\n listed), applied before summing -- e.g. to down-weight a monitor\n plane closer to the source.\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.field_energy", "parameters": [ { "annotation": "str | Sequence[str]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "names" }, { "annotation": "dict[str, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "weights" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#field_energy", "returns": { "annotation": "Callable" }, "signature": "(names: 'str | Sequence[str]', *, weights: 'dict[str, float] | None' = None) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/observables.py#L201", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Coordinates in metres of every sample of one full field array.\n\nFor the ``(nx, ny, nz)`` arrays of ``Result.state`` and of a full-field\nsnapshot on a uniform ``grid``: ``{\"x\": (nx,), \"y\": (ny,), \"z\": (nz,)}``,\nfloat64, in the model frame, CPML cells included (see the module\ndocstring for the layout). The field ``F[i, j, k]`` of ``component`` sits\nat ``(x[i], y[j], z[k])``.\n\nIn 2-D mode the z axis holds one sample and its coordinate is nominal.", "kind": "function", "name": "rfx.field_sample_coords", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" } ], "reference_url": null, "returns": { "annotation": "dict[str, np.ndarray]" }, "signature": "(grid, component: 'str') -> 'dict[str, np.ndarray]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/snapshots.py#L203", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Objective factory: smooth (soft) max of ``|field|**2`` over space+frequency.\n\nUses the standard log-sum-exp soft-max, AUTO-SCALED to the field's own\nmagnitude each call: ``beta_eff = beta / stop_gradient(max(vals))``,\n``softmax = logsumexp(beta_eff * vals) / beta_eff``, computed with\n``jax.nn.logsumexp`` for numerical stability. As *beta* (equivalently\n``beta_eff * max(vals)``, which the normalization pins to exactly\n*beta* by construction -- see \"Auto-scaling\", below) grows this\nconverges to the true ``max(|field|**2)``; a smaller *beta* trades a\nlooser max approximation for a smoother, better-conditioned gradient\n(useful early in an optimization run, e.g. the shielding case: minimize\nthe worst-case leaked field anywhere behind a barrier, over all\nmonitored frequencies, rather than the mean leaked field).\n\nParameters\n----------\nnames : str or sequence of str\n Plane name(s) to pool over -- see :func:`dft_field`. All requested\n planes' elements (space AND frequency, across every plane) are\n pooled into ONE soft-max, so this composes the register-N-planes\n pattern: register one plane per physical monitor location, then\n soft-max over all of them at once for a single worst-case scalar.\nbeta : float\n Soft-max sharpness (default 1.0), now DIMENSIONLESS -- see\n \"Auto-scaling\" below. Must be positive.\n\nAuto-scaling (fixes a measured footgun -- read before raising *beta*\n\"to be safe\")\n-------------------------------------------------------------------\nEarlier versions of this function computed ``logsumexp(beta*vals)/beta``\ndirectly against the RAW ``|field|**2`` values, so *beta* had to be\nhand-matched to whatever physical units/magnitude the accumulator\nhappened to carry (rfx's own DFT-plane accumulators commonly sit\naround ``|field|**2`` ~1e-10 to 1e-22 depending on\ngeometry/normalization). At the then-default ``beta=1.0`` the\nobjective sat at ~100.000002% of the design-independent constant\n``log(count)/beta`` (measured, `#619`): both the value and its\ngradient were differentiating ROUNDING NOISE in that constant, not\nphysics, and it could coincidentally still pass a single\nfinite-difference check while failing at a different step size (a\n`feedback_gate_can_bind_artifact`-class trap).\n\nThis function now computes ``beta_eff = beta / stop_gradient(max(vals))``\nand uses ``beta_eff`` in place of a raw *beta* everywhere above.\nBecause ``vals``' own current max scales out of the product exactly,\n``beta_eff * max(vals) == beta`` ALWAYS (BEFORE any overflow -- see\nthe next paragraph), regardless of the field's physical units -- the\n``log(count)/beta`` swallow above cannot recur at any REPRESENTABLE\n(nonzero) field magnitude, at any *beta*, including the default. This\nis scoped deliberately: below the working dtype's smallest\nrepresentable magnitude (~1.4e-45 for float32 subnormals) ``vals``\nitself underflows to a literal ``0`` array, the degenerate all-zero\nfallback below kicks in (``beta_eff = beta``, i.e. UNSCALED), and the\noriginal swallow pattern can in principle recur there -- rfx's own\nrealistic DFT-plane field magnitudes (``|field|**2`` ~1e-10 to\n1e-22) sit ~23-35 orders of magnitude above that floor, so this is a\ndtype-representability edge, not a practical concern at any field\nmagnitude this simulator actually produces. ``stop_gradient`` on\nthe normalizer is deliberate: without it, the returned scalar would\ndifferentiate the (physically meaningless) rescaling itself rather\nthan approximating ``max``; with it, the gradient is the standard\nsoftmax-weighted average at the CURRENT call's ``beta_eff`` (a real,\ndirectionally-correct signal, recomputed fresh -- and re-normalized --\nevery call).\n\nWhat *beta* now controls (and does not control): a larger *beta*\ntightens the approximation -- the softmax value can exceed the true\n``max(vals)`` by a factor of at most ``1 + log(count)/beta`` (default\n``beta=1.0`` is therefore LOOSE for a field with many samples: e.g.\n~14.8x at ``count=1e6``), so raise *beta* (5-50 is a reasonable range\nfor most plane sizes) for a tighter approximation once you know you\nneed one, exactly as before -- and the DEFAULT is now safe at any\nfield magnitude, merely loose, never rounding-noise.\n\n.. warning::\n **The top-end overflow footgun MOVED, it did not disappear --\n and it now has TWO thresholds, not one.** Auto-scaling divides by\n ``max(vals)`` instead of multiplying by the raw field magnitude,\n so a large enough *beta* against a physically tiny field can\n still overflow -- now in computing ``beta_eff = beta /\n max(vals)`` itself, before ``vals`` is even touched. Measured at\n ``max(vals)`` ~2.24e-22 (this repo's realistic DFT-plane range):\n\n 1. **Value overflow (``beta_eff`` itself overflows).** ``beta``\n at or above ~1e17 makes ``beta_eff`` exceed float32's range,\n previously returning ``value=nan, grad=nan`` silently, no\n exception. This function guards it: when ``beta_eff`` would\n be non-finite, it is clipped to the largest finite value the\n working dtype represents (``jnp.finfo(vals.dtype).max``)\n rather than propagating ``nan``. The clipped VALUE is\n accurate (still converges to the true ``max(vals)``, verified\n at ``beta`` up to 1e38).\n 2. **Gradient collapse, measured to start EARLIER (~1e15-1e17)\n and NOT covered by the value clip above.** Even where the\n value stays finite and correct, the returned gradient\n silently drops to EXACTLY ``0.0`` somewhere in this range --\n the precise threshold is FIXTURE-DEPENDENT (measured to shift\n by up to 10x between two fixtures differing only in element\n values, so no single number is trustworthy across geometries)\n -- a sharp cliff, not a gradual falloff, correct to machine\n precision on one side and exactly ``0.0`` on the other. A\n reciprocal-of-a-huge-number precision limit in the VJP's\n ``1/beta_eff`` term, distinct from (and tighter than) the\n value-overflow threshold above. This is NOT fixed by the\n value clip (it happens at a lower *beta* than clipping even\n engages) and is not attempted here: it would need a\n different numerical formulation (e.g. normalizing ``vals`` by\n ``scale`` before scaling by *beta*, which trades this\n gradient cliff for a symmetric one on the VALUE side at\n extreme *beta* / tiny-field combinations -- no formulation\n tried avoids both).\n\n **Practical guidance**: both thresholds sit many orders of\n magnitude above the 5-50 dimensionless range recommended above,\n and above the 100-1e6 range this repo's own re-calibrated tests\n and examples actually use -- treat *beta* past ~1e6 as\n unverified, not merely \"less sharp than useful.\"", "kind": "function", "name": "rfx.field_softmax", "parameters": [ { "annotation": "str | Sequence[str]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "names" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "beta" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#field_softmax", "returns": { "annotation": "Callable" }, "signature": "(names: 'str | Sequence[str]', *, beta: 'float' = 1.0) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/observables.py#L241", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Fit Debye relaxation model to measured permittivity data.\n\nUses ``scipy.optimize.minimize`` (L-BFGS-B) to find optimal Debye pole\nparameters that minimize the relative RMS error.\n\nModel:\n eps(f) = eps_inf + sum_k delta_eps_k / (1 + j*2*pi*f*tau_k)\n\nParameters\n----------\nfreqs : (N,) array\n Measurement frequencies in Hz.\neps_measured : (N,) complex array\n Measured complex permittivity.\nn_poles : int\n Number of Debye poles to fit.\neps_inf : float or None\n If provided, fix the high-frequency permittivity. If None, it is\n included as a free parameter (initialized from the highest-frequency\n measurement).\n\nReturns\n-------\nDebyeFitResult\n Named tuple with ``eps_inf``, ``poles`` (list of DebyePole), and\n ``fit_error`` (relative RMS).", "kind": "function", "name": "rfx.fit_debye", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_measured" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_poles" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_inf" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#fit_debye", "returns": { "annotation": "DebyeFitResult" }, "signature": "(freqs: 'np.ndarray', eps_measured: 'np.ndarray', n_poles: 'int' = 1, *, eps_inf: 'float | None' = None) -> 'DebyeFitResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L169", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Fit Lorentz oscillator model to measured permittivity data.\n\nUses ``scipy.optimize.minimize`` (L-BFGS-B) to find optimal Lorentz\npole parameters.\n\nModel:\n eps(f) = eps_inf + sum_k delta_eps_k * omega_k^2 /\n (omega_k^2 - omega^2 + j*omega*gamma_k)\n\nParameters\n----------\nfreqs : (N,) array\n Measurement frequencies in Hz.\neps_measured : (N,) complex array\n Measured complex permittivity.\nn_poles : int\n Number of Lorentz poles to fit.\neps_inf : float or None\n If provided, fix the high-frequency permittivity. If None, it is\n included as a free parameter.\n\nReturns\n-------\nLorentzFitResult\n Named tuple with ``eps_inf``, ``poles`` (list of LorentzPole), and\n ``fit_error`` (relative RMS).", "kind": "function", "name": "rfx.fit_lorentz", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_measured" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_poles" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_inf" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#fit_lorentz", "returns": { "annotation": "LorentzFitResult" }, "signature": "(freqs: 'np.ndarray', eps_measured: 'np.ndarray', n_poles: 'int' = 1, *, eps_inf: 'float | None' = None) -> 'LorentzFitResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L313", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute Bloch phase shifts for periodic BC at a given scan angle.\n\nParameters\n----------\nLx : float\n Unit cell period in x (metres).\nLy : float\n Unit cell period in y (metres).\nfreq : float\n Frequency (Hz).\ntheta_deg : float\n Scan angle theta from broadside (degrees).\nphi_deg : float\n Scan angle phi in the xy-plane (degrees).\n\nReturns\n-------\nphase_x, phase_y : complex\n Bloch phase factors: exp(j * kx * Lx), exp(j * ky * Ly).\n At broadside (theta=0), both are 1+0j.", "kind": "function", "name": "rfx.floquet_phase_shift", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Lx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "Ly" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_deg" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_deg" } ], "reference_url": null, "returns": { "annotation": "tuple[complex, complex]" }, "signature": "(Lx: 'float', Ly: 'float', freq: 'float', theta_deg: 'float', phi_deg: 'float') -> 'tuple[complex, complex]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L45", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute the Floquet wave vector components.\n\nParameters\n----------\nfreq : float\n Frequency (Hz).\ntheta_deg : float\n Scan angle theta from broadside (degrees).\nphi_deg : float\n Scan angle phi in the xy-plane (degrees).\n\nReturns\n-------\nkx, ky, kz : float\n Wave vector components (rad/m).", "kind": "function", "name": "rfx.floquet_wave_vector", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_deg" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_deg" } ], "reference_url": null, "returns": { "annotation": "tuple[float, float, float]" }, "signature": "(freq: 'float', theta_deg: 'float', phi_deg: 'float') -> 'tuple[float, float, float]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L86", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute Poynting flux spectrum from accumulated DFT fields.\n\nReturns\n-------\nflux : (n_freqs,) float\n ∫ Re(E × H*) · n̂ dA at each frequency.\n Positive = power flowing in +axis direction.\n\nNotes\n-----\nWith x64 disabled the accumulators are complex64, and per-cell E×H*\nproducts below the float32 minimum normal (~1.18e-38) are flushed to\nzero by XLA — a physically tiny-but-nonzero flux then returns EXACTLY\n0.0 at every frequency with healthy field accumulators (issue #304;\nsingle-cell fixed-amplitude sources radiate P ~ dx^6, so fine grids hit\nthis readily). Eager calls detect that state with a float64 NumPy\nrecompute of the identical sum and emit a UserWarning; under\njit/grad the check is skipped entirely (tracer-safe, off the AD tape).\n\n``exact_f64=True`` performs that float64 NumPy recompute AS the result\n(eager-only; raises under tracing): the per-cell products and the sum\nrun in complex128 from the (healthy) float32 accumulators, which is\nthe #304 warning's own sanctioned remedy. Absolute-scale energy\nconsumers (the #589 flux-adjudication witness channel) use this path —\npartial subnormal flushing corrupts small-magnitude sums well before\nthey reach exact zero, so the warning alone is not sufficient there.\nThe default path is unchanged.", "kind": "function", "name": "rfx.flux_spectrum", "parameters": [ { "annotation": "FluxMonitor", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mon" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "exact_f64" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#flux_spectrum", "returns": { "annotation": "jnp.ndarray" }, "signature": "(mon: 'FluxMonitor', *, exact_f64: 'bool' = False) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L847", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Front-to-back ratio in dB.\n\nF/B = max gain in forward hemisphere (theta < 90 deg)\n - max gain in backward hemisphere (theta > 90 deg)\n\nParameters\n----------\nff : FarFieldResult\nfreq_idx : frequency index.\n\nReturns\n-------\nfb_dB : float", "kind": "function", "name": "rfx.front_to_back_ratio", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_idx" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#front_to_back_ratio", "returns": { "annotation": "float" }, "signature": "(ff: 'FarFieldResult', *, freq_idx: 'int' = 0) -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L224", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compare AD gradient with finite-difference gradient.\n\nRuns the simulation via ``sim.forward()`` with permittivity\noverrides derived from *design_params*, computes the gradient\nof *objective_fn* with respect to *design_params* using both\nreverse-mode AD and central finite differences, and returns\nthe comparison.\n\nParameters\n----------\nsim : Simulation\n Configured simulation (ports, probes already added).\ndesign_params : jnp.ndarray\n Flat array of design parameters. These are added element-wise\n to the baseline ``eps_r`` from ``sim._assemble_materials()``.\n Shape must broadcast with ``grid.shape``.\nobjective_fn : callable(SimResult) -> scalar\n Differentiable objective function.\neps : float\n Finite-difference perturbation (default 1e-3).\nn_steps : int or None\n Number of timesteps. Passed to ``sim.forward()``.\nnum_periods : float\n Periods at freq_max if *n_steps* is None.\n\nReturns\n-------\nGradientCheckResult\n Contains ad_grad, fd_grad, and relative_error.", "kind": "function", "name": "rfx.gradient_check", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "design_params" }, { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective_fn" }, { "annotation": "float", "default": "0.001", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#gradient_check", "returns": { "annotation": "GradientCheckResult" }, "signature": "(sim, design_params: 'jnp.ndarray', objective_fn: 'Callable', *, eps: 'float' = 0.001, n_steps: 'int | None' = None, num_periods: 'float' = 20.0) -> 'GradientCheckResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L563", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Is this gradient converged in RECORD LENGTH, not just in value?\n\nDifferentiates ``objective`` at ``n_steps`` and again at\n``ceil(factor * n_steps)`` and asks whether the gradient VECTOR moved.\nPhysically: a resonance that is still ringing when the record ends leaves a\nterm in every DFT bin whose phase is ``(w - w_r) * T``; a parameter that\nmoves ``w_r`` spins that phase, and the spin enters the derivative\nmultiplied by ``T``. The value hides it, the gradient does not.\n\nThe verdict is ``||g_long - g_short|| / ||g_long||`` per bin, over every\nparameter element of every leaf, with no floor in it, and the cosine\nbetween the two arms is reported beside it so a change of step LENGTH can\nbe told from a change of DIRECTION. The per-element table\n(``grad_rel_change``) is a report for locating a failure, not the verdict --\nsee the class docstring.\n\nParameters\n----------\nobjective : callable\n ``objective(params, n_steps)`` returning the observable -- a scalar or\n a 1-D array over frequency bins, real or COMPLEX (an S-parameter, a DFT\n phasor). For a complex observable the full complex sensitivity\n ``dRe/dp + i dIm/dp`` is compared, not its real part: a parameter that\n rotates a phasor at constant magnitude moves only the imaginary part.\n With ``has_aux=True`` it returns ``(observable, aux)`` instead. It must\n be differentiable w.r.t. its first argument, and ``n_steps`` must be the\n number of timesteps of the record it takes the observable from.\nparams : pytree\n The differentiation point. Any JAX pytree of REAL float leaves -- a\n permittivity, a dimension, a component value. Complex and integer leaves\n are refused with a message rather than silently halved or zeroed.\nn_steps : int\n The record length under test, in timesteps.\ntol : float\n Required. The largest relative gradient change that still counts as\n converged. There is deliberately NO default: the right bar depends on\n the structure's Q, on how far the parameter moves the resonance and on\n what the gradient is for, and a default here would be a number nobody\n measured. Measurements to calibrate against, all with ``factor=2``:\n\n * Grounded-slab patch, graded z, float32, 50 ohm wire port,\n ``d ln|S11|^2 / d ln eps_r``: a 2200-step record settling to\n -39.7 dB (so a PASS on the -40 dB bar) moved 9.7 % at 5.75 GHz and\n 23 % at 6.5 GHz; a local-permittivity parameter on the same record\n moved 8.7 % and 38 %. At 4400 steps (-75 dB) the worst was 2.1 %.\n * The same board driven by a soft source instead of a port settles far\n more slowly (-40.9 dB in 6000 steps where the port reaches -101.5 dB):\n there ``d ln U(0) / d ln eps_r`` read 5.79 against a converged 6.80\n (15 % low) and a pattern-ratio gradient 0.331 against 0.070 (5x).\n * The committed cavity fixture\n (``tests/unit/autodiff/test_gradient_record_length_witness.py``):\n 1600 steps, settling -46.7 dB, the POWER converged to 0.399 %,\n the gradient vector moved 11.0 %\n (its direction by cos 0.9989); 3200 steps, settling -89.1 dB, gradient\n moved 0.12 %.\n\n A bar of a few percent is what the -75 dB rows above support; tighten\n or loosen it against your own sweep, and record which.\nfactor : float, default 2.0\n Record-length ratio of the long arm. Must be greater than 1. The\n witness only sees ringing that the LONGER record resolves: a record\n too short by more than ``factor`` can still pass, because both arms\n then carry a similar leftover. Pair this with the -40 dB settling rule\n (``settling_verdict``); it does not replace it.\nhas_aux : bool, default False\n Whether ``objective`` returns ``(observable, aux)``. The witness reads\n exactly one thing out of ``aux``: if it is a mapping with a finite\n numeric ``\"settling_db\"``, that value is recorded as the record's\n ring-down level. Anything else is accepted and reported as ``None``.\nfloor_frac : float, default 1e-3\n Applies to the per-element REPORT table only, never to the verdict. It\n is the floor in that table's denominator, as a fraction of the largest\n ``|gradient|`` across all leaves in that bin at either record length,\n so an element carrying no sensitivity does not fill the table with\n ratios off its own rounding. The verdict is a ratio of norms and needs\n no floor.\n\nReturns\n-------\nGradientRecordLengthWitness\n\nNotes\n-----\nCost: two differentiated runs, one of them ``factor`` times longer, and one\ncompile each, because the record length is a traced-in constant. Roughly\n``1 + factor`` times the steps of the run being checked plus a second\ncompile. This is an opt-in diagnostic, not something ``forward()`` does on\nits own.\n\nExamples\n--------\n>>> def objective(p, n): # doctest: +SKIP\n... result = sim.forward(eps_override=base * jnp.exp(p), n_steps=n)\n... return ln_power_at_bins(result.time_series)\n>>> w = gradient_record_length_witness( # doctest: +SKIP\n... objective, 0.0, 1600, tol=0.05)\n>>> w.passed, w.worst # doctest: +SKIP\n(False, 0.110)", "kind": "function", "name": "rfx.gradient_record_length_witness", "parameters": [ { "annotation": "Callable[[Any, int], Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "params" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "tol" }, { "annotation": "float", "default": "2.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "factor" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "has_aux" }, { "annotation": "float", "default": "0.001", "has_default": true, "kind": "KEYWORD_ONLY", "name": "floor_frac" } ], "reference_url": null, "returns": { "annotation": "GradientRecordLengthWitness" }, "signature": "(objective: 'Callable[[Any, int], Any]', params: 'Any', n_steps: 'int', *, tol: 'float', factor: 'float' = 2.0, has_aux: 'bool' = False, floor_frac: 'float' = 0.001) -> 'GradientRecordLengthWitness'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_gradient_witness.py#L311", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Half-power (3 dB) beamwidth in degrees.\n\nParameters\n----------\nff : FarFieldResult\nplane : ``\"E\"`` (phi=0 cut) or ``\"H\"`` (phi=pi/2 cut).\nfreq_idx : frequency index.\n\nReturns\n-------\nhpbw : float, degrees. Returns ``nan`` if the 3 dB points\n cannot be found (e.g. omnidirectional in the cut plane).", "kind": "function", "name": "rfx.half_power_beamwidth", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "str", "default": "'E'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "plane" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_idx" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#half_power_beamwidth", "returns": { "annotation": "float" }, "signature": "(ff: 'FarFieldResult', *, plane: 'str' = 'E', freq_idx: 'int' = 0) -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L143", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract resonant modes via the Matrix Pencil Method.\n\n.. warning::\n\n **Lossless closed cavities have infinite physical Q — do not read a Q\n off a finite window.** In a PEC-bounded domain with no material loss\n (an empty or lossless-filled cavity), a resonance never decays, so the\n Q returned here is a pure *windowing artefact*: it swings by orders of\n magnitude with the run length rather than tracking any physics. The\n resonant *frequency* is still meaningful; the *Q* is not. To measure a\n meaningful Q, add a realistic loss (a finite ``sigma`` / ``tan_delta``\n on the fill, or a lossy load) so the cavity has a finite physical Q, or\n use an open (CPML) boundary so radiation sets the Q.\n\nParameters\n----------\nsignal : 1D real or complex array\n Time-domain signal.\ndt : float\n Timestep in seconds.\nf_min, f_max : float\n Frequency search range in Hz.\npencil_parameter : float\n Fraction of signal length for pencil size L (0.2-0.5).\nmin_Q : float\n Discard modes with Q < min_Q.\nmax_modes : int\n Maximum complex-pole rank and maximum modes to return. Both members\n of a real signal's conjugate pair consume rank before reporting.\nsv_threshold : float\n Relative singular value threshold for rank determination (relative\n to the largest singular value). The same threshold is used after\n resampling; it is not a calibrated noise-confidence bound.\ndecimate : {\"auto\", False}\n Automatically reduce oversampled, band-limited inputs before matrix\n pencil analysis. With the default ``\"auto\"``, decimation is applied\n when ``1 / dt > 8 * f_max`` using a target factor of\n ``int(1 / dt / (4 * f_max))``. Anti-aliased, zero-phase FIR stages of\n at most 13 are used, and the effective timestep is passed to the core\n algorithm. At each stage, outputs touching the filter's zero-padded\n boundary are excluded: filtering an interior exponential preserves\n its pole, while zero padding introduces transients. This SHORTENS\n the usable record; ``harminv_record_duration`` reports its duration.\n A stage is omitted if fewer than 10 interior samples would remain or\n its pencil could not hold ``max_modes`` poles plus one singular\n direction for rank selection. If the original pencil is smaller,\n its existing capacity is preserved instead. This is a dimension\n safeguard, not a guarantee that noisy/nearby modes are identifiable.\n Set to ``False`` to retain every input sample. Decimation avoids\n redundant work because the estimator scales approximately as\n :math:`O(N^{2.7})`.\n\nReturns\n-------\nlist of HarminvMode, sorted by amplitude (strongest first).\n Amplitude and phase describe jointly fitted complex coefficients at\n the original input's first sample. For a real cosine of peak A the\n positive-frequency coefficient has magnitude A/2; its conjugate is\n fitted too, then omitted from the returned list. Relative weights\n depend on source/probe placement and are not modal energies.", "kind": "function", "name": "rfx.harminv", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "signal" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_min" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_max" }, { "annotation": "float", "default": "0.33", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pencil_parameter" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "min_Q" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_modes" }, { "annotation": "float", "default": "0.001", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sv_threshold" }, { "annotation": "str | bool", "default": "'auto'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decimate" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#harminv", "returns": { "annotation": "list[HarminvMode]" }, "signature": "(signal: 'np.ndarray', dt: 'float', f_min: 'float', f_max: 'float', *, pencil_parameter: 'float' = 0.33, min_Q: 'float' = 1.0, max_modes: 'int' = 50, sv_threshold: 'float' = 0.001, decimate: 'str | bool' = 'auto') -> 'list[HarminvMode]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/harminv.py#L126", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Extract resonances from a simulation probe time series.\n\nAutomatically windows the signal to use only the ring-down\nportion (after source has decayed).\n\n.. warning::\n\n A **lossless closed (PEC) cavity** has infinite physical Q, so the Q\n returned here is a window-length artefact, not physics — add a\n realistic loss or use an open (CPML) boundary before trusting a Q.\n See :func:`harminv` for the full note. (The frequency is fine.)\n\nParameters\n----------\ntime_series : 1D array\ndt : float\nfreq_range : (f_min, f_max) in Hz\nsource_decay_time : float\n Time at which source has decayed (seconds).", "kind": "function", "name": "rfx.harminv_from_probe", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "source_decay_time" }, { "annotation": null, "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#harminv_from_probe", "returns": { "annotation": "list[HarminvMode]" }, "signature": "(time_series: 'np.ndarray', dt: 'float', freq_range: 'tuple[float, float]', *, source_decay_time: 'float' = 0.0, **kwargs) -> 'list[HarminvMode]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/harminv.py#L340", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Initialize zero-valued Floquet DFT accumulators.\n\nParameters\n----------\nn_freqs : int\n Number of frequency points.\nplane_shape : (nu, nv)\n Shape of the 2D extraction plane.", "kind": "function", "name": "rfx.init_floquet_dft", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_freqs" }, { "annotation": "tuple[int, int]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "plane_shape" } ], "reference_url": null, "returns": { "annotation": "FloquetDFTAccumulator" }, "signature": "(n_freqs: 'int', plane_shape: 'tuple[int, int]') -> 'FloquetDFTAccumulator'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L200", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a Poynting flux monitor on a (possibly finite-size) plane region.\n\n``lo1/hi1`` and ``lo2/hi2`` restrict the DFT accumulation to a\nsub-region of the tangential plane. -1 means \"full extent\".\n\n``d1`` / ``d2`` are the cell sizes along the two tangential axes of\nthe monitor plane (axis-1 / axis-2 of ``_FLUX_COMPONENTS``). Each may\nbe a scalar (uniform mesh) or a per-cell 1-D array (non-uniform). The\nWith ``staggered_area=True``, nodal axes use adjacent-cell dual widths\nand each E/H product has its own area. PMC face nodes have half weight;\nunused high cell-centered ghosts have zero weight. Otherwise the\nflux area element is ``dA = d1 * d2`` — for an x-normal plane that is\n``dy * dz``, etc. (PROBE-C1 fix: the old API took a single scalar\n``dx`` and assumed a cubic cell.)", "kind": "function", "name": "rfx.init_flux_monitor", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "index" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "tuple[int, int, int]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid_shape" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "d1" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "d2" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_total_steps" }, { "annotation": "str", "default": "'rect'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_window" }, { "annotation": "float", "default": "0.25", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_window_alpha" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lo1" }, { "annotation": "int", "default": "-1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "hi1" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "lo2" }, { "annotation": "int", "default": "-1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "hi2" }, { "annotation": "frozenset", "default": "frozenset()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pmc_faces" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "staggered_area" } ], "reference_url": null, "returns": { "annotation": "FluxMonitor" }, "signature": "(axis: 'int', index: 'int', freqs: 'jnp.ndarray', grid_shape: 'tuple[int, int, int]', d1, d2, dft_total_steps: 'int' = 0, dft_window: 'str' = 'rect', dft_window_alpha: 'float' = 0.25, lo1: 'int' = 0, hi1: 'int' = -1, lo2: 'int' = 0, hi2: 'int' = -1, pmc_faces: 'frozenset' = frozenset(), staggered_area: 'bool' = False) -> 'FluxMonitor'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L725", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Initialize a multi-mode waveguide port.\n\nExpands a single physical port into ``n_modes`` independent\n``WaveguidePortConfig`` objects, one per analytical eigenmode.\nEach config has the profile of a different waveguide mode, but shares\nthe same physical location and aperture.\n\nOnly the first mode (lowest cutoff, typically TE10) is driven with a\nsource; higher-order modes are passive listeners that extract modal\namplitudes via overlap integrals.\n\nParameters\n----------\nport : WaveguidePort\n Physical port definition (location, aperture, direction).\n The ``mode`` and ``mode_type`` fields are ignored when\n ``n_modes > 1``; modes are auto-enumerated by cutoff.\ndx : float\n Cell size (metres).\nfreqs : jnp.ndarray\n Frequency array for DFT extraction.\nn_modes : int\n Number of lowest-cutoff modes to include.\nf0, bandwidth, amplitude, probe_offset, ref_offset : ...\n Passed to ``init_waveguide_port`` for each mode config.\ndft_total_steps : int\n Total simulation steps; sets the time-series record length used\n by the post-scan rectangular full-record DFT.\n\nReturns\n-------\nlist[WaveguidePortConfig]\n One config per mode, sorted by cutoff frequency.\n Only the first config has a nonzero source amplitude.", "kind": "function", "name": "rfx.init_multimode_waveguide_port", "parameters": [ { "annotation": "WaveguidePort", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_modes" }, { "annotation": "float", "default": "5000000000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude" }, { "annotation": "int", "default": "10", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_offset" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_offset" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_total_steps" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt" }, { "annotation": "str", "default": "'modulated_gaussian'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "str", "default": "'discrete'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode_profile" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "grid" }, { "annotation": "tuple[float, float]", "default": "(0.5, 0.5)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "h_offset" }, { "annotation": null, "default": "jax.numpy.float32", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_dtype" } ], "reference_url": null, "returns": { "annotation": "list[WaveguidePortConfig]" }, "signature": "(port: 'WaveguidePort', dx: 'float', freqs: 'jnp.ndarray', n_modes: 'int' = 1, *, f0: 'float' = 5000000000.0, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, probe_offset: 'int' = 10, ref_offset: 'int' = 3, dft_total_steps: 'int' = 0, dt: 'float' = 0.0, waveform: 'str' = 'modulated_gaussian', mode_profile: 'str' = 'discrete', grid=None, h_offset: 'tuple[float, float]' = (0.5, 0.5), field_dtype=) -> 'list[WaveguidePortConfig]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L2715", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Initialize a waveguide port with precomputed mode profiles.\n\nParameters\n----------\ndx : float or grid\n Either a scalar Yee cell size (uniform grid path) or a Grid-like\n object exposing per-axis cell-width arrays. NonUniformGrid is\n supported via duck-typing on ``dx_arr``/``dy_arr``/``dz``.\nprobe_offset : int\n Cells downstream from source for measurement probe.\nref_offset : int\n Cells downstream from source for reference probe.\ngrid : Grid or None\n Optional Grid object for face-aware aperture pruning. When passed,\n the modal V/I aperture excludes \"ghost\" cells whose centre lies\n inside a PEC conductor (the cell at the array boundary on a +face\n marked PEC). Without this, uniform-Grid callers integrate over\n the ghost row, producing an ~8% PEC-short |S11| deficit.", "kind": "function", "name": "rfx.init_waveguide_port", "parameters": [ { "annotation": "WaveguidePort", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "5000000000.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "int", "default": "10", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe_offset" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ref_offset" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_total_steps" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "str", "default": "'modulated_gaussian'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveform" }, { "annotation": "str", "default": "'discrete'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mode_profile" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "tuple[float, float]", "default": "(0.5, 0.5)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "h_offset" }, { "annotation": null, "default": "jax.numpy.float32", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "field_dtype" } ], "reference_url": null, "returns": { "annotation": "WaveguidePortConfig" }, "signature": "(port: 'WaveguidePort', dx, freqs: 'jnp.ndarray', f0: 'float' = 5000000000.0, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, probe_offset: 'int' = 10, ref_offset: 'int' = 3, dft_total_steps: 'int' = 0, dt: 'float' = 0.0, waveform: 'str' = 'modulated_gaussian', mode_profile: 'str' = 'discrete', grid=None, h_offset: 'tuple[float, float]' = (0.5, 0.5), field_dtype=) -> 'WaveguidePortConfig'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L603", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a zeroed SParamProbe for a WirePort.\n\nThe port_index is set to the midpoint cell of the LIVE wire run\n(issue #764; identical to the all-extent midpoint with no dead cells).", "kind": "function", "name": "rfx.init_wire_sparam_probe", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_total_steps" }, { "annotation": "str", "default": "'rect'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_window" }, { "annotation": "float", "default": "0.25", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dft_window_alpha" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": null, "returns": { "annotation": "SParamProbe" }, "signature": "(grid, port, freqs: 'jnp.ndarray', dft_total_steps: 'int' = 0, dft_window: 'str' = 'rect', dft_window_alpha: 'float' = 0.25, pec_edge_masks=None) -> 'SParamProbe'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L1172", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Inject a Floquet plane-wave source at the port plane.\n\nUses a soft source (additive) that launches a Gaussian-modulated\nplane wave. For non-zero scan angles, the spatial phase gradient\nacross the port plane is applied.\n\nParameters\n----------\nstate : FDTDState\nport_index : int\n Grid index along the normal axis.\naxis : int\n Normal axis (0=x, 1=y, 2=z).\ndt, dx : float\n Timestep and cell size.\nstep : int\n Current timestep index.\nf0 : float\n Center frequency (Hz).\nbandwidth : float\n Fractional bandwidth.\namplitude : float\n Source amplitude (V/m).\npolarization : str\n \"te\" or \"tm\".\ntheta_deg, phi_deg : float\n Scan angles (degrees).\nLx, Ly : float\n Unit cell periods for phase computation.", "kind": "function", "name": "rfx.inject_floquet_source", "parameters": [ { "annotation": "FDTDState", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_index" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f0" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "bandwidth" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude" }, { "annotation": "str", "default": "'te'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "polarization" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_deg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_deg" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "Lx" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "Ly" } ], "reference_url": null, "returns": { "annotation": "FDTDState" }, "signature": "(state: 'FDTDState', port_index: 'int', axis: 'int', dt: 'float', dx: 'float', step: 'int', f0: 'float', bandwidth: 'float', amplitude: 'float', polarization: 'str' = 'te', theta_deg: 'float' = 0.0, phi_deg: 'float' = 0.0, Lx: 'float' = 0.0, Ly: 'float' = 0.0) -> 'FDTDState'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L434", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Legacy soft-E source (superseded by TFSF-style pair in scan body).\n\nRetained for backwards compatibility — direct callers still get a soft\nE source. The simulation scan body no longer invokes this function;\nit now uses ``apply_waveguide_port_h`` and ``apply_waveguide_port_e``\ntogether, which form a one-sided TFSF boundary and launch a\nunidirectional mode wave (no spurious backward emission).\n\nDispatches on ``cfg.waveform`` so a user who built the port with\n``waveform=\"modulated_gaussian\"`` sees a consistent pulse shape\nwhether they call this helper manually or rely on the scan-body pair.", "kind": "function", "name": "rfx.inject_waveguide_port", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "t" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(state, cfg: 'WaveguidePortConfig', t: 'float', dt: 'float', dx: 'float')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1145", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Inspect JAX saved residuals for ``fun(*args, **kwargs)``.\n\nThe implementation captures ``jax.ad_checkpoint.print_saved_residuals`` and\nparses the printed abstract values into a structured, JSON-serializable\nartifact. Exceptions from tracing ``fun`` propagate to the caller.\n\nCaveat: capture uses a process-global ``contextlib.redirect_stdout`` while\ntracing ``fun``. It is therefore not thread-safe, and any stray ``print()``\nexecuted by ``fun`` during tracing is captured and parsed as a residual\nline (it degrades to an ``unknown`` record that nulls the byte total rather\nthan raising). Avoid printing inside ``fun`` when using this helper.", "kind": "function", "name": "rfx.inspect_ad_saved_residuals", "parameters": [ { "annotation": "Callable[..., Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "fun" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_POSITIONAL", "name": "args" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#inspect_ad_saved_residuals", "returns": { "annotation": "ADResidualInspection" }, "signature": "(fun: 'Callable[..., Any]', *args: 'Any', **kwargs: 'Any') -> 'ADResidualInspection'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L341", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Batched forward-mode Jacobian of ``sim_fn`` at ``params`` (issue #577).\n\n``jax.jvp`` / ``jax.jacfwd`` / ``jax.vmap(jax.jvp)`` already run\nend-to-end through ``sim.forward(eps_override=...)`` ->\n:func:`dft_field` / :func:`field_energy` / :func:`field_softmax` today,\nwith zero solver changes -- this function is a thin, gated PACKAGING\nlayer over that stock-JAX capability (tangent-basis construction,\ndtype/shape validation, primal de-duplication, sequential-vs-batched\ndispatch), not a new AD engine. It computes\n\n ``value, jacobian = jacobian_fwd(sim_fn, params)``\n\nwhere ``value = sim_fn(params)`` (bit-identical to calling ``sim_fn``\ndirectly -- see the API trap note below) and ``jacobian`` has the SAME\npytree structure as *value* (``sim_fn``'s OUTPUT, not *params* -- this\nis what ``jax.jvp``'s own tangent output mirrors, and this function\ndoes not reshape it into a params-keyed structure the way\n``jax.jacfwd`` does), with every leaf gaining one new LEADING axis of\nsize ``n_t``: ``jacobian`` (or ``jacobian[k]`` for an output pytree\nwith leaf ``k``) has shape ``(n_t,) + value.shape``, row ``i`` holding\nthe directional derivative of *value* along tangent direction ``i``.\nWith the default ``tangents=\"identity\"``, direction ``i`` corresponds\nto ``params``' ``i``-th flattened leaf (``jax.tree_util.tree_flatten``\norder) -- i.e. ``jacobian[i]`` is ``d(value)/d(params_leaf[i])``.\n\nMechanism: ``jax.vmap`` over the TANGENT argument of ``jax.jvp`` (NOT\n``jax.linearize``). Measured on the real uniform-lane FDTD scan: the\n``vmap(jvp)`` jaxpr contains exactly ONE ``lax.scan`` (the FDTD time\nloop) whose carry holds one UNBATCHED copy of the field state (the\nprimal sweep) plus ``n_t`` BATCHED tangent copies -- the primal sweep\nreally is shared across every tangent direction, which is the premise\n#577 asked to verify. ``jax.linearize`` was measured to cost 24x more\npeak memory on the same fixture (8654 MB vs 355 MB at n_steps=600,\nn_t=10) because it materialises the whole scan's primal residuals --\ni.e. the reverse-mode tape -- which forward mode never needs.\n\nAPI TRAP (verify this, do not assume it): a naive\n``jax.vmap(jax.jvp(...))`` ALSO stacks the primal, returning a\n``(n_t,) + value.shape`` array of ``n_t`` copies of the same value.\nThis function passes ``out_axes=(None, 0)`` to ``jax.vmap`` so the\nreturned ``value`` is the single, unstacked primal -- but that only\nworks because the primal computation genuinely does not depend on\nwhich tangent direction is being evaluated. If you change ``sim_fn``\nin a way that breaks that invariant, ``jax.vmap`` raises loudly\n(``out_axes=None`` on an output that DOES depend on the mapped axis is\na vmap error, not a silent wrong answer). ``batch_tangents=False``\n(the sequential path) has NO ``jax.vmap`` of its own to inherit that\ncheck from -- it just calls ``jax.jvp`` ``n_t`` times in a plain\nPython loop and returns ``values[0]``, so without an explicit guard a\n``sim_fn`` that violates the invariant would silently return one\narbitrary tangent row's primal on that path instead of raising. This\nfunction closes that gap on the sequential path via two guards, so\nthe memory-vs-speed knob is not also a safety-vs-speed knob: (1) a\n``jax.eval_shape`` abstract trace of the SAME ``out_axes=(None, 0)``\nvmap the batched path actually runs -- shape-only, zero FLOPs, zero\nextra memory (verified: reproduces the identical\n``ValueError`` a real violating vmap call raises, including when this\nwhole call is itself wrapped in an outer ``jax.jit`` by the caller,\nsince ``eval_shape`` is trace-time like ``vmap``'s own check); (2)\nwhen running eagerly (params are not themselves tracers, so the\ncomputed primal values are concrete), an exact pairwise comparison of\nall ``n_t`` sequentially-computed primal values, raising ``ValueError``\non any mismatch -- a strictly stronger, numeric confirmation of the\nsame invariant, skipped only when it is not expressible (under an\nenclosing ``jax.jit``, where guard (1) is the check in effect).\n\nCost characterization: NOT \"a few times one solve\" -- see\n``scripts/benchmark_jacobian_fwd.py`` (regenerable; run it for current\nnumbers on your hardware/grid) and the CHANGELOG entry for this issue\nfor measured wall-time/flops/memory ratios. The honest summary: wall\ntime and flops scale roughly as ``(1 + n_t)`` plain solves and that\nratio MOVES with grid size (do not trust one ratio across problem\nsizes); memory is the argument FOR this mode, not speed -- forward-mode\npeak is ``O(state) * (1 + n_t)`` and independent of ``n_steps``, while\nreverse mode without segmented checkpointing is tens of times one\nplain solve even for a single scalar output, and ``jax.jacrev`` refuses\na complex-valued observable outright (raises ``TypeError`` without\n``holomorphic=True``). Numbers are never published here -- see the\nanti-rot rule in the module/CHANGELOG instead of trusting a docstring\nnumber, which rots.\n\nParameters\n----------\nsim_fn : Callable\n ``params -> value``, JAX-differentiable (typically\n ``lambda p: dft_field(name)(sim.forward(eps_override=eps(p), ...))``\n or the same composed with :func:`field_energy` /\n :func:`field_softmax`). Called under ``jax.jvp``, so it must be\n traceable the same way any ``jax.grad``/``jax.jvp`` target is.\nparams : Any\n A JAX pytree of the design variables to differentiate with respect\n to. With the default ``tangents=\"identity\"``, every leaf must be a\n floating-dtype SCALAR (shape ``()``) -- see :func:`_identity_tangent_batch`.\n A flat ``(n_p,)`` array (one non-scalar leaf) needs the explicit\n ``tangents=`` escape hatch below.\ntangents : \"identity\" or a pytree, optional\n ``\"identity\"`` (default): build one one-hot tangent direction per\n scalar leaf of *params* (``n_t = number of leaves``); fails loud\n (``ValueError``) if any leaf is non-scalar or non-floating -- see\n :func:`_identity_tangent_batch`'s docstring for the measured trap\n this avoids. Otherwise: an explicit tangent BATCH -- a pytree with\n the same structure as *params*, every leaf carrying one extra\n LEADING axis of a common size ``n_t`` (e.g. ``tangents=jnp.eye(n_p)``\n when *params* is a flat ``(n_p,)`` array, for the full Jacobian, or\n any ``(n_t, n_p)`` slice of it for a subset of columns).\nbatch_tangents : bool, optional\n ``True`` (default): run all ``n_t`` tangent directions as ONE\n ``jax.vmap(jax.jvp(...))`` call -- lower wall time (measured 2.3-3.1x\n faster than the sequential control at n_t in {4, 10}), higher peak\n memory (``O(state) * (1 + n_t)``, all ``n_t`` tangent copies live\n at once). ``False``: run the ``n_t`` directions as independent\n sequential ``jax.jvp`` calls in a plain Python loop -- the\n memory-vs-speed knob, trading the wall-time win for a peak that\n scales with ONE tangent copy at a time instead of ``n_t``\n (measured: primal-sharing still holds sequentially, at ``~1 + n_t``\n compute but with a lower peak than the batched path scales to as\n ``n_t`` grows). CORRECTION: this function does not call\n ``jax.jit`` itself on EITHER path -- there is no ``jax.jit``\n CALL anywhere in this module (verify:\n ``grep -nE '@jax\\.jit|jax\\.jit\\(' rfx/observables.py`` returns\n nothing -- a plain ``grep jax.jit`` also matches this sentence's\n own prose, so it is not a useful self-check). ``batch_tangents=False`` runs the ``n_t``\n sequential ``jax.jvp`` calls exactly as written, at whatever JIT\n boundary the CALLER supplies (eager if the caller does not\n ``jax.jit`` anything; compiled as part of one program if the\n caller wraps its own outer function, as\n ``scripts/benchmark_jacobian_fwd.py`` and\n ``tests/unit/autodiff/test_jacobian_fwd.py`` both do for compiled/jaxpr\n measurement) -- an earlier version of this docstring claimed\n ``jax.jit`` wrapping was part of this function's own behaviour,\n which was never true. The two paths (batched vs. sequential) are\n DIFFERENT XLA programs and may disagree at float32 reassociation\n scale (~1e-6 relative); they are not bit-identical. See \"Fail-loud\n fences\" below for how the two paths' SAFETY differs, not just\n their performance.\n\nReturns\n-------\n(value, jacobian) : tuple\n ``value``: the single primal, ``sim_fn(params)`` bit-identical\n (verify this in your own test if you change *sim_fn*'s structure --\n see the API trap above). ``jacobian``: a pytree mirroring *value*\n (``sim_fn``'s output, NOT *params* -- see the paragraph above the\n signature), each leaf an array of shape ``(n_t,) + value.shape``.\n\nComplex-Jacobian convention\n----------------------------\nFor a complex-valued *value* (e.g. :func:`dft_field`'s output), the\nreturned Jacobian is ``dy/dx`` UNCONJUGATED -- exactly what forward-mode\nAD produces for a real input tangent and a complex output. This\nDIFFERS BY A CONJUGATE from anything derived through ``jax.vjp`` /\n``jax.grad`` on the same computation (measured: 0.02% relative error\nagainst an unconjugated central-difference reference, 198% against the\nconjugated one). If you compare this Jacobian against anything built\nfrom reverse-mode AD, conjugate one side first. This is also why\n``jax.jacrev`` cannot be used as a drop-in alternative here: it refuses\na complex-dtype output outright (``TypeError``, needs\n``holomorphic=True``) -- forward mode is the only stock-JAX mode that\nhands back this Jacobian without a holomorphy declaration.\n\nFail-loud fences\n-----------------\nThree configurations are unsafe to combine with ``jacobian_fwd`` on\n``sim_fn`` bodies built on ``Simulation.forward(...)``. This function\nis intentionally generic over *sim_fn* (it never sees ``forward()``'s\nown keyword arguments -- they live inside your closure), so the first\ntwo are enforced by a RAISE that propagates up through ``jax.jvp``\nfrom ``forward()``'s own pre-existing checks; the remaining one has no\nraise to inherit and cannot be intercepted from outside the closure,\nso it is a DOCUMENTED trap instead. Read the RAISES/DOCS tag on each\nbefore assuming \"it didn't raise\" means \"it's fine\":\n\n- **[RAISES, inherited]** non-uniform + ``distributed=True`` with a\n registered DFT-plane probe: ``forward()`` itself raises\n ``NotImplementedError`` (the #619 fence, ``rfx/api/_execute.py``) --\n neither sharded runner accumulates DFT-plane fields. ``jacobian_fwd``\n scope is the uniform single-device lane only; a distributed\n ``sim_fn`` fails loud before this function's own machinery runs.\n- **[RAISES, inherited]** ``n_warmup``: ``forward()`` itself raises\n ``NotImplementedError`` for a nonzero ``n_warmup`` on the uniform\n lane (issue #626) -- so on ``jacobian_fwd``'s supported (uniform)\n lane, a ``n_warmup``-using ``sim_fn`` already fails loud. It used to\n be a measured SILENT NO-OP (bit-identical value AND tangent at\n ``n_warmup=0`` vs ``n_warmup=60`` of 80 steps) before the fence was\n added. Do not read this as \"n_warmup is safe elsewhere\": on the\n non-uniform lane where it IS implemented, ``n_warmup`` truncation\n error DEPENDS ON DISTANCE FROM THE SOURCE TO THE DESIGN REGION, not\n merely on ``n_warmup``'s value -- it is (near-)exact while\n ``n_warmup`` stays below the wavefront's arrival time at the design\n region (``K_safe ~= floor(min_distance(source, design_region) /\n (C0 * dt))``) and grows sharply beyond it, up to ~6-7% at half the\n pre-loss-window length, 58% at the loss-window boundary itself,\n exactly zero once far enough beyond it, FOR A NEAR-SOURCE\n placement specifically (issue #626 part 2 / addendum -- a\n far-from-source placement stays within this repo's ~1.5% AD-vs-FD\n noise floor for every ``n_warmup <= K_safe`` (growing smoothly, not\n a sharp cliff, from <0.01% well below ``K_safe`` to ~1.2% AT\n ``K_safe`` itself), see ``rfx/nonuniform.py``'s ``n_warmup split``\n comment for the full measured curves and formula) -- it is\n not fenced there (truncated-BPTT is a legitimate, if\n placement-dependent, construction), and any future non-uniform\n extension of this function must account for ``K_safe``, not treat\n ``n_warmup`` as uniformly lossy OR uniformly free.\n- **[DOCS ONLY -- inert, not a raise]** ``checkpoint`` /\n ``checkpoint_segments``: measured EXACTLY NEUTRAL under forward mode\n (flops/temp bytes identical across ``checkpoint=False``,\n ``checkpoint=True`` (the ``forward()`` default), and\n ``checkpoint_segments=K``) -- remat only pays off under reverse-mode\n transposition, and forward mode builds no tape to transpose. A\n ``sim_fn`` built for use with ``jacobian_fwd`` should pass\n ``checkpoint=False`` explicitly (``forward()`` defaults to\n ``checkpoint=True``) to avoid inheriting dead HLO plus\n ``checkpoint_segments``' ``n_steps % K == 0`` divisibility raise for\n no forward-mode benefit. These are reverse-mode knobs; document them\n as such, do not reach for them here.\n\nScope limits\n-------------\n- Uniform single-device lane only (see the fences above).\n- \"Geometry parameter\" is NOT a parametric dimension here. A traced\n ``Box`` corner raises ``ConcretizationTypeError``\n (``rfx/geometry/csg.py``) and ``forward()``'s material rasterisation\n is a binary ``jnp.where`` mask with zero gradient almost everywhere.\n The only continuous geometry design channels this package has are\n topology density (via :func:`rfx.topology.density_to_material_fields`),\n ``pec_occupancy_override``, and the non-uniform ``dz_profile``. If you\n want ``d/d(patch width in metres)``, this function cannot supply that\n column -- rfx does not have it to give, on any AD mode.\n- Nonlinear (Kerr chi3) tangents ran clean under ``vmap(jvp)`` in\n testing but were numerically indistinguishable from the linear\n baseline at the tested chi3 -- that is NOT a validation of the\n nonlinear tangent path. Treat it as unverified until measured at a\n chi3 large enough to move the Jacobian outside noise.", "kind": "function", "name": "rfx.jacobian_fwd", "parameters": [ { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_fn" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "params" }, { "annotation": "Any", "default": "'identity'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tangents" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "batch_tangents" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#jacobian_fwd", "returns": { "annotation": "tuple[Any, Any]" }, "signature": "(sim_fn: 'Callable', params: 'Any', *, tangents: 'Any' = 'identity', batch_tangents: 'bool' = True) -> 'tuple[Any, Any]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/observables.py#L499", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load measured material data from a CSV file.\n\nSupports two input formats:\n\n1. Complex permittivity: columns for frequency, real part, and imaginary\n part of permittivity.\n2. Loss tangent: columns for frequency, real part, and tan(delta).\n The imaginary part is computed as ``eps_r * tan_delta``.\n\nParameters\n----------\npath : str\n Path to the CSV file.\nfreq_col : str\n Column name for frequency in Hz.\neps_real_col : str\n Column name for the real part of permittivity.\neps_imag_col : str\n Column name for the imaginary part of permittivity.\ntan_delta_col : str or None\n Column name for loss tangent. If provided, ``eps_imag_col`` is ignored\n and the imaginary part is derived from ``eps_r * tan_delta``.\n\nReturns\n-------\nfreqs : ndarray, shape (N,)\n Frequencies in Hz.\neps_complex : ndarray, shape (N,), dtype complex128\n Complex relative permittivity ``eps' - j*eps''``.", "kind": "function", "name": "rfx.load_material_csv", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "str", "default": "'freq_hz'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_col" }, { "annotation": "str", "default": "'eps_r'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_real_col" }, { "annotation": "str", "default": "'eps_i'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_imag_col" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tan_delta_col" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#load_material_csv", "returns": { "annotation": "tuple[np.ndarray, np.ndarray]" }, "signature": "(path: 'str', *, freq_col: 'str' = 'freq_hz', eps_real_col: 'str' = 'eps_r', eps_imag_col: 'str' = 'eps_i', tan_delta_col: 'str | None' = None) -> 'tuple[np.ndarray, np.ndarray]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L70", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load material arrays from an HDF5 file.", "kind": "function", "name": "rfx.load_materials", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" } ], "reference_url": null, "returns": { "annotation": "MaterialArrays" }, "signature": "(path: 'str | Path') -> 'MaterialArrays'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L254", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load optimization result from HDF5.\n\nReturns\n-------\ndict with keys: eps_design, loss_history, latent, density, etc.", "kind": "function", "name": "rfx.load_optimization_result", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#load_optimization_result", "returns": { "annotation": null }, "signature": "(path)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L784", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load a compact ``.npz`` V/I dump.", "kind": "function", "name": "rfx.load_port_vi_dump_npz", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" } ], "reference_url": null, "returns": { "annotation": "PortVIDump" }, "signature": "(path: 'str | Path') -> 'PortVIDump'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L824", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load field snapshots from an HDF5 file.\n\nReturns\n-------\nsnapshots : dict mapping component name to numpy array\nmetadata : dict\n File attributes; ``metadata[\"axes\"]`` holds the\n ``{component: SnapshotAxes}`` saved with ``axes=``, when there are\n any.", "kind": "function", "name": "rfx.load_snapshots", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" } ], "reference_url": null, "returns": { "annotation": "tuple[dict[str, np.ndarray], dict]" }, "signature": "(path: 'str | Path') -> 'tuple[dict[str, np.ndarray], dict]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L152", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Load FDTD state from an HDF5 file.\n\nReturns\n-------\nstate : FDTDState\nmetadata : dict\n Grid metadata if it was saved, otherwise empty dict.", "kind": "function", "name": "rfx.load_state", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#load_state", "returns": { "annotation": "tuple[FDTDState, dict]" }, "signature": "(path: 'str | Path') -> 'tuple[FDTDState, dict]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L65", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a Lorentz pole from physical parameters.\n\nParameters\n----------\ndelta_eps : float\n Permittivity contribution Δε (dimensionless).\nomega_0 : float\n Resonant angular frequency (rad/s).\ndelta : float\n Damping coefficient (rad/s).", "kind": "function", "name": "rfx.lorentz_pole", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "delta_eps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "omega_0" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "delta" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#lorentz_pole", "returns": { "annotation": "LorentzPole" }, "signature": "(delta_eps: 'float', omega_0: 'float', delta: 'float') -> 'LorentzPole'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/materials/lorentz.py#L72", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Build a 1-D cell-size profile whose interfaces land on node planes\nand whose adjacent-cell ratios obey ``max_ratio`` everywhere.\n\nAxis-agnostic: the same output serves ``dx_profile``, ``dy_profile``\nor ``dz_profile`` of :func:`make_nonuniform_grid`.\n\nParameters\n----------\nedges : sequence of float\n Sorted physical coordinates (m) of every interface that must lie\n on a node plane, INCLUDING the domain start and end.\ncell_sizes : sequence of float\n Target cell size (m) per segment, ``len(edges) - 1`` entries.\nmax_ratio : float\n Cap on every adjacent-cell ratio (default 1.4 — the validated\n z-axis multi-band cap; pass 1.3 for an in-plane profile, the\n in-plane threshold, see docs/guides/support_matrix.md). Must be\n finite and ``>= 1.0001`` (a 2x transition at that ratio already\n needs 6932 cells; the plateau solve's cost grows with the ramp\n length — measured 0.03 s at 1.0001 on a 40-cell profile and\n 0.4 s for a 1 um pin descending into 10 mm of 100 um cells, an\n 8110-cell profile).\nprotected : sequence of bool, optional\n Per segment. A protected segment is realized UNIFORM —\n ``n = max(min_cells, ceil(span / target - 1e-9))`` equal cells —\n and never hosts a ramp cell; a free segment (default) may host the\n ramps its neighbours need.\nboundary_cell : float, optional\n Pins ``cells[0] == cells[-1] == boundary_cell`` exactly (the x/y\n CPML contract of :func:`make_nonuniform_grid`). Both end segments\n must be free and wide enough to hold the pinned cell plus its ramp\n (``ValueError`` otherwise).\nmin_cells : int\n Minimum cell count of a PROTECTED segment (default 1).\n\nReturns\n-------\nnp.ndarray\n float64 cells. Invariants, for any valid input: every edge is a\n cumulative node coordinate to 1e-12 m; every adjacent ratio is\n ``<= max_ratio`` (to 1e-9), INCLUDING seams between two protected\n segments; the sum equals ``edges[-1] - edges[0]`` to 1e-12 m;\n with ``boundary_cell``, both end cells equal it bit-exactly.\n The two 1e-12 m figures are float64 accumulation of the cells\n (a running sum, as the rasterizer positions nodes) and hold for\n columns up to about 1 m with up to 1e4 cells; the miss grows\n with column length and cell count (measured 1e-11 m on a 10 m\n column of 1e5 cells, 2.2e-9 m on 100 m / 1e6 cells), while each\n cell itself matches its declared value to 1e-15 relative.\n\nRaises\n------\nValueError\n On inconsistent input: edges not strictly increasing or two edges\n closer than 1e-12 m (the node tolerance — merge them), a\n non-positive cell size, ``max_ratio`` not finite or below 1.0001,\n a protected end segment with ``boundary_cell``, an end segment\n shorter than the pinned cell or too short to hold the pin plus\n its ramp, and a profile that would exceed 1,000,000 cells (a\n sliver segment pulls its neighbours down to its size under the\n ratio law: a 1e-9 m protected sliver between 1 mm blocks asks\n for 1.4e6 cells).\n\nNotes\n-----\nRamps are geometric (per-step ratio spread evenly, ``<= max_ratio``)\nand placed INSIDE the coarser free segment on whichever side needs\none; the free run's plateau value is solved so the run sums to its\ndeclared span exactly (no cell above its target, no rescale). Two\nadjacent PROTECTED segments whose seam exceeds the cap cannot be\nserved by a ramp: the coarser one's uniform cell is reduced (more\ncells) until the seam complies, iterated to a fixed point. The cost\nis cells AND, whenever the refined block was the coarsest declared\ncell, a smaller minimum cell than declared — the time step follows\nthe global minimum, so dt drops with it. Measured on 3000 seeded\nstacks (rng 1; 2-6 segments, spans 20 um-3 mm, targets 0.05-2x the\nspan, 70 % protected, caps 1.2-1.4): the realized minimum sits below\nthe declared minimum in 410 of them, down to 0.31x in the worst case\n(two single-cell protected blocks whose span ratio just exceeds the\ncap at 1.2). Hand case: ``[0, 0.1, 0.1355] mm, [25, 100] um, both\nprotected, 1.4`` realizes 5 x 20 um + 2 x 17.75 um, minimum 0.71x\nthe declared 25 um. A free segment too thin for any ramp is a\nrefinement source for its neighbours in the same way.", "kind": "function", "name": "rfx.make_band_profile", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "edges" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cell_sizes" }, { "annotation": "float", "default": "1.4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_ratio" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "protected" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary_cell" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "min_cells" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_band_profile", "returns": { "annotation": "np.ndarray" }, "signature": "(edges, cell_sizes, *, max_ratio: 'float' = 1.4, protected=None, boundary_cell: 'float | None' = None, min_cells: 'int' = 1) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/nonuniform.py#L1728", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a properly normalized current source for non-uniform grid.\n\nThe waveform specifies CURRENT (Amperes). The E-field addition is:\nE += (dt/ε) × I_source / dV\nwhere dV is the E node's control volume: the PRIMAL per-cell width on\nthe component's own axis and the DUAL spacing ``(d[k-1]+d[k])/2`` on the\ntwo transverse axes (issue #672). On a uniform mesh the two coincide and\nthis is the familiar ``dx × dy × dz``.\n\nThis gives resolution-independent injected POWER regardless of cell size.\nSame approach as Meep's internal source normalization.\n\nNative amplitude convention (issue #571): ``'current'`` —\n``amplitude_kind`` of None or ``'current'`` is bit-identical to the\nhistorical output (no extra multiply). ``amplitude_kind='field'``\nreturns the waveform directly, without reading a material coefficient.\nThe shared builder preserves the current drive's differentiable Cb/dV.", "kind": "function", "name": "rfx.make_current_source", "parameters": [ { "annotation": "NonUniformGrid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position_ijk" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveform_fn" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude_kind" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_current_source", "returns": { "annotation": null }, "signature": "(grid: 'NonUniformGrid', position_ijk, component, waveform_fn, n_steps, materials, amplitude_kind=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/nonuniform.py#L1952", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a non-uniform Yee grid.\n\nParameters\n----------\ndomain_xy : (Lx, Ly) in metres\n Only used when ``dx_profile`` / ``dy_profile`` are None — in\n that case the xy mesh is uniform with spacing ``dx``.\ndz_profile : 1D array of z cell sizes in metres (physical domain only)\ndx : float\n Boundary cell size (also used for CPML padding and as the\n uniform-xy spacing when no xy profile is provided).\ncpml_layers : int\n Number of CPML cells added to each face (when that face is\n absorbing — see ``pec_faces`` / ``pmc_faces``).\ndx_profile, dy_profile : 1D arrays or None\n Optional per-cell x / y spacings for the physical (non-CPML)\n interior. When provided, the first and last values must match\n ``dx`` (they set the boundary cell size used by the CPML).\npec_faces, pmc_faces : set of str or None\n Face labels (``x_lo``, ``x_hi``, ``y_lo``, ``y_hi``, ``z_lo``,\n ``z_hi``) where the boundary is PEC / PMC. Per-face pad count\n is forced to 0 on these faces so the reflector plane aligns\n with the user domain edge. Added 2026-04 to close the\n PMC+CPML composition gap on the non-uniform mesh path.\ncpml_axes : str\n Axes that participate in CPML allocation (default ``\"xyz\"``).\n Per-face allocation still applies; an axis absent from\n ``cpml_axes`` gets pad=0 on both faces.\ndt : float or None\n Concrete time step (s) to use INSTEAD of the Courant step this\n builder derives from ``min(cell)``. ``None`` (default) keeps the\n derived step and is byte-identical to the historical behaviour.\n\n Why it exists: the derived step is a function of the smallest\n cell, so a mesh that is a design variable moves ``dt`` with the\n deformation, and every observable read off the run then carries\n the step change as well as the geometry change. Pinning one step\n across a deformation family makes the sweep one antenna at one\n step. The value must be CONCRETE — a traced ``dt`` would put the\n step itself in the derivative.\ndt_min_cell : float or None\n Smallest cell size (m) the caller's TRACED axes reach anywhere in\n the family they will run. Required with ``dt`` when any profile is\n a tracer, because a tracer carries no host value to measure the\n realized Courant limit against. Concrete axes are always measured\n from their realized profile; this declared number is used only for\n the axes that cannot be.", "kind": "function", "name": "rfx.make_nonuniform_grid", "parameters": [ { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "domain_xy" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz_profile" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_layers" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx_profile" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dy_profile" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_faces" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pmc_faces" }, { "annotation": "str", "default": "'xyz'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "dict[str, int] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "face_layers" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt_min_cell" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt_caller" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_nonuniform_grid", "returns": { "annotation": "NonUniformGrid" }, "signature": "(domain_xy: 'tuple[float, float]', dz_profile: 'np.ndarray', dx: 'float', cpml_layers: 'int' = 8, *, dx_profile: 'np.ndarray | None' = None, dy_profile: 'np.ndarray | None' = None, pec_faces: 'set[str] | None' = None, pmc_faces: 'set[str] | None' = None, cpml_axes: 'str' = 'xyz', face_layers: 'dict[str, int] | None' = None, dt: 'float | None' = None, dt_min_cell: 'float | None' = None, dt_caller: 'str | None' = None) -> 'NonUniformGrid'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/nonuniform.py#L856", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create an NTFF box from physical coordinates.\n\nThe box is built for face-centre collocation (the second-order layout);\npass ``collocation=\"node\"`` for the pre-second-order geometry.", "kind": "function", "name": "rfx.make_ntff_box", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "str", "default": "'face_centre'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "collocation" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_ntff_box", "returns": { "annotation": "NTFFBox" }, "signature": "(grid: 'Grid', corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]', freqs, *, collocation: 'str' = 'face_centre') -> 'NTFFBox'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L352", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a SourceSpec for a lumped port (Cb-corrected waveform).\n\nThe port impedance must already be folded into *materials* via\n``setup_lumped_port()``.", "kind": "function", "name": "rfx.make_port_source", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_port_source", "returns": { "annotation": null }, "signature": "(grid: 'Grid', port, materials: 'MaterialArrays', n_steps)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L442", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a ProbeSpec from a physical position.", "kind": "function", "name": "rfx.make_probe", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_probe", "returns": { "annotation": null }, "signature": "(grid: 'Grid', position, component)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L491", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Create a SourceSpec by precomputing a waveform function (raw E-field add).\n\nWARNING: raw field source causes DC accumulation on PEC surfaces.\nPrefer ``make_j_source`` for resonance detection.\n\nNative amplitude convention (issue #571): ``'field'`` — ``E += w``.\n``amplitude_kind='current'`` uses the shared source-table builder's\n``Cb/dV`` coefficient and REQUIRES\n``materials`` (for Cb at the source cell). ``amplitude_kind`` of\nNone or ``'field'`` is bit-identical to the historical output (no\nmultiply is applied at all). ``materials`` is accepted and unused in\nthat legacy/native case.", "kind": "function", "name": "rfx.make_source", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "waveform_fn" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "amplitude_kind" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#make_source", "returns": { "annotation": null }, "signature": "(grid: 'Grid', position, component, waveform_fn, n_steps, materials=None, amplitude_kind=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L372", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Maximize the bandwidth where |S11| < threshold.\n\nEvaluates S11 over a frequency band ``[f_center − f_bw/2, f_center + f_bw/2]``\nand returns a soft loss that is lower when more frequency bins satisfy\n``|S11|_dB < s11_threshold``.\n\nThe loss is computed as the mean of ``max(|S11|²_dB − threshold, 0)``\nacross the band, so it drives the optimizer to push all bins below\nthreshold simultaneously, effectively maximizing matched bandwidth.\n\nParameters\n----------\nf_center : float\n Center frequency (Hz).\nf_bw : float\n Bandwidth span (Hz).\ns11_threshold : float\n Threshold in dB (default −10 dB).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.maximize_bandwidth", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_center" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "f_bw" }, { "annotation": "float", "default": "-10.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "s11_threshold" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#maximize_bandwidth", "returns": { "annotation": "Callable" }, "signature": "(f_center: 'float', f_bw: 'float', s11_threshold: 'float' = -10.0) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L222", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Maximize directivity in a target direction (ratio-based, scale-invariant).\n\nComputes the directivity ratio ``U(θ_target, φ_target) / P_rad`` where\n``U = |E_θ|² + |E_φ|²`` is the radiation intensity and ``P_rad`` is\nthe total radiated power integrated over the FULL sphere (the same\ncoverage as ``farfield.directivity()`` and ``antenna._total_radiated_power``,\nretaining this objective's JAX trapezoid endpoint weights — so the\noptimized quantity is the true directivity, not an upper-hemisphere proxy\nthat would inflate D for antennas with any back radiation). The ratio is\nscale-invariant, so the absolute magnitude of the NTFF spectral integral\ndrops out — gradients reflect pattern shape only.\n\nPrior versions used absolute ``|E|²`` at the target direction, which\nis ~1e-27 in rfx's spectral NTFF convention and produces zero\ngradients in ``topology_optimize`` (GitHub issue #32).\n\nParameters\n----------\ntheta_target : float\n Polar angle in radians [0, π].\nphi_target : float\n Azimuthal angle in radians [0, 2π].\nn_theta : int, optional\n Number of polar samples in [0, π] for the full-sphere P_rad\n integration (default 37 → 5° spacing).\nn_phi : int, optional\n Number of azimuthal samples in [0, 2π] (default 73 → 5° spacing).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)\n\nParameters (continued)\n----------------------\nlog_ratio : bool, optional\n Default ``True``: optimize ``-(log U - log P)`` — the full, sign-correct\n quotient gradient ``U'/U - P'/P`` that is right for every degree of\n freedom (including power-changing ones). ``log_ratio=False`` is refused\n because it gives wrong-sign gradients for power-changing variables.\neps : float, optional\n Floor for the ``log_ratio`` log arguments (default 1e-37). It only\n guards ``log(0)``; the log-ratio gradient ``U'/U`` is scale-invariant, so\n eps must be BELOW the working U/P magnitude (rfx spectral NTFF U,P are\n ~1e-27 in full antenna runs, ~1e-32 in small/early sims). A floor at or\n above U/P (e.g. the old 1e-30 on a 1e-32 sim) clamps the log argument and\n zeros the gradient — keep eps well below min(U, P).\n\nNotes\n-----\nThe removed ``log_ratio=False`` mode omitted the denominator derivative,\ngiving wrong-sign gradients for power-changing variables. Use the default.", "kind": "function", "name": "rfx.maximize_directivity", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "theta_target" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "phi_target" }, { "annotation": "int", "default": "37", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_theta" }, { "annotation": "int", "default": "73", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_phi" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "log_ratio" }, { "annotation": "float", "default": "1e-37", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#maximize_directivity", "returns": { "annotation": "Callable" }, "signature": "(theta_target: 'float', phi_target: 'float', *, n_theta: 'int' = 37, n_phi: 'int' = 73, log_ratio: 'bool' = True, eps: 'float' = 1e-37) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L283", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Maximize |S21|² (transmission) over specified frequencies.\n\nReturns ``-mean|S21|²`` so that *minimizing* this objective\nmaximizes transmission.\n\nParameters\n----------\nfreqs : array-like, shape (n,)\n Target frequencies (Hz).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.maximize_s21", "parameters": [ { "annotation": "jnp.ndarray | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#maximize_s21", "returns": { "annotation": "Callable" }, "signature": "(freqs: 'jnp.ndarray | np.ndarray') -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L128", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Time-domain S21 proxy: maximize energy at an output probe.\n\nReturns the negated total squared energy at the output probe, so\nthat *minimizing* this objective maximizes transmission.\n\nThis objective works with ``optimize()`` and ``topology_optimize()``\nbecause it uses only ``result.time_series`` (no S-parameters needed).\n\nParameters\n----------\noutput_probe_idx : int\n Index into ``result.time_series`` columns for the output probe.\n Default -1 (last probe).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.maximize_transmitted_energy", "parameters": [ { "annotation": "int", "default": "-1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "output_probe_idx" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#maximize_transmitted_energy", "returns": { "annotation": "Callable" }, "signature": "(output_probe_idx: 'int' = -1) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L548", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Effective relative permittivity of a microstrip line (Hammerstad).\n\nParameters\n----------\nwidth : float\n Conductor (trace) width in metres.\nheight : float\n Substrate (dielectric) thickness in metres.\neps_r : float\n Substrate relative permittivity (dimensionless, >= 1).\n\nReturns\n-------\nfloat\n Effective relative permittivity ``eps_eff`` seen by the quasi-TEM\n mode (``1 <= eps_eff <= eps_r``).\n\nNotes\n-----\nUses the Hammerstad form (Pozar §3.8, eq. 3.195); the\n``(w/h < 1)`` branch adds the ``(1 - w/h)^2`` thin-line correction.", "kind": "function", "name": "rfx.microstrip_eps_eff", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "width" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "height" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#microstrip_eps_eff", "returns": { "annotation": "float" }, "signature": "(width: 'float', height: 'float', eps_r: 'float') -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/microstrip.py#L56", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Characteristic impedance and eps_eff of a microstrip line (analysis).\n\nParameters\n----------\nwidth : float\n Conductor (trace) width in metres.\nheight : float\n Substrate (dielectric) thickness in metres.\neps_r : float\n Substrate relative permittivity (dimensionless, >= 1).\n\nReturns\n-------\n(z0, eps_eff) : tuple of float\n ``z0`` is the characteristic impedance in ohms; ``eps_eff`` is the\n effective relative permittivity.\n\nNotes\n-----\nTwo-regime Wheeler/Hammerstad expression (Pozar §3.8, eq. 3.196):\n\n* ``w/h <= 1``: ``z0 = eta_0 / (2*pi*sqrt(eps_eff))\n * ln(8 h/w + w/(4 h))``\n* ``w/h >= 1``: ``z0 = eta_0 / (sqrt(eps_eff)\n * (w/h + 1.393 + 0.667 ln(w/h + 1.444)))``", "kind": "function", "name": "rfx.microstrip_impedance", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "width" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "height" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#microstrip_impedance", "returns": { "annotation": "tuple[float, float]" }, "signature": "(width: 'float', height: 'float', eps_r: 'float') -> 'tuple[float, float]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/microstrip.py#L88", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Trace width that yields a target characteristic impedance (synthesis).\n\nSolves the inverse problem: *given* a desired ``z0`` (e.g. 50 ohm), a\nsubstrate thickness, and a substrate permittivity, return the\nmicrostrip conductor width.\n\nParameters\n----------\nz0 : float\n Target characteristic impedance in ohms (> 0).\nheight : float\n Substrate (dielectric) thickness in metres.\neps_r : float\n Substrate relative permittivity (dimensionless, >= 1).\n\nReturns\n-------\nfloat\n Conductor (trace) width in metres.\n\nNotes\n-----\nClosed-form Wheeler/Hammerstad synthesis (Pozar §3.8, eq. 3.197).\nA trial ``w/h`` is computed for both the narrow and wide regimes and\nthe branch consistent with its own validity condition is selected.", "kind": "function", "name": "rfx.microstrip_width", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z0" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "height" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#microstrip_width", "returns": { "annotation": "float" }, "signature": "(z0: 'float', height: 'float', eps_r: 'float') -> 'float'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/microstrip.py#L128", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Time-domain S11 proxy: minimize late-time reflected energy at port.\n\nComputes the ratio of energy in the second half of the probe time\nseries (dominated by reflections) to energy in the first half\n(dominated by the incident pulse). Minimizing this ratio drives\nthe optimizer toward better impedance matching.\n\nThis objective works with ``optimize()`` and ``topology_optimize()``\nbecause it uses only ``result.time_series`` (no S-parameters needed).\n\n.. warning::\n The \"late half = reflection\" split is only valid when the round trip\n from the port to the reflecting feature and back arrives *after* the\n split (``1 - late_fraction`` of the series) and *before* the run ends.\n On a short round-trip geometry (thin substrate, feature near the port)\n the reflection lands in the early window and the late window is nearly\n empty, so this ratio collapses toward 0 and its gradient is numerical\n noise -- with no error raised. Sanity-check the returned magnitude (a\n meaningfully reflecting design sits near 1e-2--1e-1, not ~1e-7), then fix\n an empty window by its mode: enlarge ``n_steps`` if the reflection\n arrives after the run ends; RAISE ``late_fraction`` (which moves the\n split earlier) if it arrives before the split; if the incident pulse and\n reflection overlap in time on a very short round trip, no split separates\n them -- narrow the source bandwidth or use an impedance-referenced port.\n An AD-vs-finite-difference check does NOT catch this: both differentiate\n the same empty window and agree.\n\nParameters\n----------\nport_probe_idx : int\n Index into ``result.time_series`` columns identifying the probe\n co-located with the excitation port (default 0).\nlate_fraction : float\n Fraction of the time series considered \"late\" (default 0.5).\n A value of 0.5 means the second half is treated as reflection.\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.minimize_reflected_energy", "parameters": [ { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_probe_idx" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "late_fraction" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#minimize_reflected_energy", "returns": { "annotation": "Callable" }, "signature": "(port_probe_idx: 'int' = 0, *, late_fraction: 'float' = 0.5) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L431", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Minimize |S11|² over specified frequencies.\n\nReturns a callable ``objective(result) -> scalar`` that computes the\nmean |S11|² across the nearest frequency bins. If the mean S11 is\nalready below *target_db* the loss is clamped to zero.\n\nParameters\n----------\nfreqs : array-like, shape (n,)\n Target frequencies (Hz) over which to minimize S11.\ntarget_db : float\n Threshold in dB. When mean |S11|² is below this, loss = 0.\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.minimize_s11", "parameters": [ { "annotation": "jnp.ndarray | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "-10.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_db" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#minimize_s11", "returns": { "annotation": "Callable" }, "signature": "(freqs: 'jnp.ndarray | np.ndarray', target_db: 'float' = -10.0) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L78", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return common RF network quality metrics for an S-matrix cube.\n\nThe input must have shape ``(n_ports, n_ports, n_freqs)``. Metrics are\nhost-side diagnostics for reports and interop gates; they do not alter any\nsolver path.", "kind": "function", "name": "rfx.network_quality_metrics", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "float", "default": "1e-12", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reciprocity_tol" }, { "annotation": "float", "default": "1e-12", "has_default": true, "kind": "KEYWORD_ONLY", "name": "passivity_tol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#network_quality_metrics", "returns": { "annotation": "dict[str, object]" }, "signature": "(s_params: 'np.ndarray', *, reciprocity_tol: 'float' = 1e-12, passivity_tol: 'float' = 1e-12) -> 'dict[str, object]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L674", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Normalize rfx S-matrix-like outputs into a canonical observable.\n\nThe function uses duck typing so it works for:\n- :class:`rfx.api.Result` / ``Result.s_params``\n- :class:`rfx.api.WaveguideSMatrixResult` / ``.s_params``\n- :class:`rfx.api.MSLSMatrixResult` / ``.S``\n- direct ``s_params=...`` and ``freqs=...`` arrays\n\nIt raises ``ValueError`` for schema problems. Use\n:func:`validate_port_smatrix` when you want a non-raising report.", "kind": "function", "name": "rfx.normalize_port_smatrix", "parameters": [ { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "obj" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s_params" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_names" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "source" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#normalize_port_smatrix", "returns": { "annotation": "PortSMatrixObservable" }, "signature": "(obj: 'Any | None' = None, *, s_params: 'Any | None' = None, freqs: 'Any | None' = None, port_names: 'Any | None' = None, source: 'str | None' = None) -> 'PortSMatrixObservable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L295", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run gradient-based optimization on a design region.\n\nRefuses simulations with refinement, as the underlying ``forward()``\npath has no subgridded solve.\n\nParameters\n----------\nsim : Simulation\n Base simulation (the design region overrides eps_r in its box).\nregion : DesignRegion\n Design region specification.\nobjective : callable(Result) -> scalar\n Objective function to minimize. Must be JAX-differentiable\n through the simulation.\nn_iters : int\n Number of optimization iterations.\nlr : float\n Learning rate (Adam).\ninit_latent : array or None\n Initial latent parameters. If None, initialized to zeros\n (maps to midpoint of eps_range).\nn_steps : int or None\n Number of simulation timesteps per iteration. Controls memory\n usage — fewer steps = less memory for ``jax.grad``. If None,\n auto-computed from *num_periods*.\nnum_periods : float\n Periods at freq_max for auto n_steps (default 20). Reduce to\n 10 for lower memory usage with minimal accuracy loss.\nverbose : bool\n Print progress every 10 iterations.\nn_warmup : int\n Forwarded verbatim to ``sim.forward(n_warmup=...)`` at every\n iteration (issue #40). On a non-uniform / distributed-non-uniform\n ``sim``, this trades an APPROXIMATE (truncated) gradient for\n reduced reverse-mode memory/compute — see ``Simulation.forward``'s\n own ``n_warmup`` docstring for the measured error curve (issue\n #626 part 2); a design loop built on this objective inherits that\n bias, not just a single forward call, so verify the bias is\n acceptable for your loss window before using a nonzero value here.\n On a uniform-mesh ``sim`` it raises ``NotImplementedError``\n (issue #626 — previously a silent no-op). Default ``0`` (no\n warmup split, full gradient).\nport_s11_freqs : array-like or None\n Frequencies (Hz) at which to accumulate per-port V/I DFTs in the\n JIT scan body so that ``result.s_params`` is populated with\n wave-decomposition |S11| values. Required when the objective is\n :func:`minimize_s11_at_freq_wave_decomp` (issue #72).\ncheckpoint_segments : int or None\n If set, route ``sim.forward`` through the segmented-checkpoint\n path (issue #73) which trades ≈2× compute for ≈√n_steps memory.\n Must divide ``n_steps``; useful when ``n_steps`` is large enough\n that the linear-memory scan would OOM. ``None`` (default)\n preserves the legacy per-step ``jax.checkpoint`` behaviour.\n\n Currently wired only on the uniform single-device forward path.\n Non-uniform meshes and ``distributed=True`` will raise\n ``NotImplementedError``; NU support is tracked as a follow-up\n on issue #73.\nn_starts : int\n Number of random-initialized restarts (opt-in; default 1 = the\n legacy single run). Start 0 always uses ``init_latent`` (so\n ``n_starts=1`` is byte-identical to before this parameter existed);\n starts 1..N-1 draw i.i.d. standard-normal latents from ``seed``.\n The best restart by final loss (or best-visited loss when\n ``best_iterate=True``) is returned. Promoted from the MSL\n open-stub multimodal example (issue #171); the surface must be\n multimodal for extra starts to help.\nbest_iterate : bool\n If True, return the lowest-loss iterate visited during the run\n rather than the final iterate (default False = final iterate =\n legacy behaviour). Guards the sharp-null overshoot the #171 GPU\n run caught. Selection among ``n_starts`` restarts uses the same\n best-visited loss when this is True.\nstep_clamp : float or None\n If set (>0), clamp the L2 norm of each Adam latent update to this\n value, rescaling the whole step (direction preserved) when it\n overshoots. Default None = unclamped = legacy behaviour. Generic\n analogue of the example's physical-length clamp.\nseed : int\n PRNG seed for the extra ``n_starts`` restart inits (deterministic /\n reproducible). Unused when ``n_starts=1``.\njit : bool\n Compile the loss and its gradient once per ``optimize()`` call and\n reuse the program in every iteration and every start (#1225).\n Default False runs ``jax.value_and_grad`` eagerly, which compiles\n the whole FDTD solve again on every iteration — on a board-sized\n model most of the iteration's wall time.\n\n With ``jit=True`` the objective is traced, not run, so it must not\n read a traced value on the host (``float(...)``, ``np.asarray(...)``,\n a Python ``if`` on an array). Wire ports on either mesh and lumped\n ports on a graded mesh trace since #1225. Known exception: a model\n with an MSL port —\n its port set-up reads the realized PEC mask on the host\n (``rfx/sources/msl_port.py``) and the MSL wave-decomposition\n extractor converts a grid spacing with ``float()``\n (``rfx/sparams/_common.py:143``); under ``jit=True`` the call stops\n with ``TracerArrayConversionError`` or ``ConcretizationTypeError``.\n Use the default there.\n\n The jitted loss and gradient can differ from the eager ones in the\n last float32 bits, because XLA compiles the whole step as one\n program. Measured on CPU in float32 ULP at the peak of each array\n (``max|eager - jitted|`` over the spacing at ``max|eager|``): 0 to 9\n in the loss and up to ~20 in a design-region gradient on the models\n tested, and ~150 in the loss of a waveguide-port model. These are\n measurements, not a bound: on a wire-port model where two parts of\n the objective's gradient partly cancel at the port cell, the\n whole-grid permittivity gradient differed by 12 to 56 ULP at the\n peak. The optimisation path can therefore drift from an eager run's\n at that level.\n\nReturns\n-------\nOptimizeResult\n For ``n_starts>1`` this is the winning restart's result\n (``loss_history`` is that restart's own trajectory).", "kind": "function", "name": "rfx.optimize", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "DesignRegion", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "region" }, { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_iters" }, { "annotation": "float", "default": "0.01", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lr" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "init_latent" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "verbose" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "emit_time_series" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "distributed" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_s11_freqs" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_starts" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "best_iterate" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "step_clamp" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "seed" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "jit" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#optimize", "returns": { "annotation": "OptimizeResult" }, "signature": "(sim, region: 'DesignRegion', objective: 'Callable', *, n_iters: 'int' = 50, lr: 'float' = 0.01, init_latent: 'jnp.ndarray | None' = None, n_steps: 'int | None' = None, num_periods: 'float' = 20.0, verbose: 'bool' = True, skip_preflight: 'bool' = False, checkpoint_every: 'int | None' = None, emit_time_series: 'bool' = True, n_warmup: 'int' = 0, distributed: 'bool' = False, port_s11_freqs: 'object | None' = None, checkpoint_segments: 'int | None' = None, n_starts: 'int' = 1, best_iterate: 'bool' = False, step_clamp: 'float | None' = None, seed: 'int' = 0, jit: 'bool' = False) -> 'OptimizeResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L253", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run multiple simulations with different parameter values.\n\nParameters\n----------\nsim_factory : callable\n ``sim_factory(param_value) -> Simulation``. Called once per value\n in *param_values* to create a fully configured ``Simulation`` object.\nparam_name : str\n Human-readable name of the parameter being swept (used for labels).\nparam_values : array-like\n 1-D sequence of parameter values to sweep over.\nn_steps : int or None\n If given, passed as ``n_steps`` to each ``sim.run()``.\nuntil_decay : float or None\n If given, passed as ``until_decay`` to each ``sim.run()``.\nrun_kwargs : dict or None\n Additional keyword arguments forwarded to ``sim.run()``.\n\nReturns\n-------\nSweepResult\n Container with ``.results``, ``.param_values``, and ``.param_name``.", "kind": "function", "name": "rfx.parametric_sweep", "parameters": [ { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_name" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_values" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "until_decay" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#parametric_sweep", "returns": { "annotation": "SweepResult" }, "signature": "(sim_factory: 'Callable', param_name: 'str', param_values, *, n_steps: 'int | None' = None, until_decay: 'float | None' = None, run_kwargs: 'dict | None' = None) -> 'SweepResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sweep.py#L170", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Build a JSON-serializable Pareto-front artifact.", "kind": "function", "name": "rfx.pareto_front", "parameters": [ { "annotation": "Sequence[Sequence[float]] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "bool | Sequence[bool]", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "minimize" }, { "annotation": "Sequence[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ids" }, { "annotation": "Sequence[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "objective_names" }, { "annotation": "Sequence[Mapping[str, object] | None] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "metadata" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "atol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#pareto_front", "returns": { "annotation": "ParetoFront" }, "signature": "(objectives: 'Sequence[Sequence[float]] | np.ndarray', *, minimize: 'bool | Sequence[bool]' = True, ids: 'Sequence[str] | None' = None, objective_names: 'Sequence[str] | None' = None, metadata: 'Sequence[Mapping[str, object] | None] | None' = None, atol: 'float' = 0.0) -> 'ParetoFront'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L163", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a boolean mask selecting non-dominated objective rows.\n\n``minimize`` may be one bool for all objectives or one bool per objective.\nObjectives marked ``False`` are treated as maximization objectives. ``atol``\nraises the bar for *strict improvement*: after orientation a point ``p``\ndominates ``q`` only if ``p`` is no worse than ``q`` on every objective\n(exact ``<=``) and better by more than ``atol`` on at least one. This keeps\nthe relation a strict partial order (transitive, no dominance cycles), so a\nlarger ``atol`` retains *more* points and the front is never empty for\nnon-empty finite input.", "kind": "function", "name": "rfx.pareto_mask", "parameters": [ { "annotation": "Sequence[Sequence[float]] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "bool | Sequence[bool]", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "minimize" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "atol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#pareto_mask", "returns": { "annotation": "np.ndarray" }, "signature": "(objectives: 'Sequence[Sequence[float]] | np.ndarray', *, minimize: 'bool | Sequence[bool]' = True, atol: 'float' = 0.0) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L121", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Parse one line printed by JAX saved-residual inspection.\n\nUnknown future JAX formats are preserved as raw text with parseable fields\nset to ``None`` instead of being silently discarded.", "kind": "function", "name": "rfx.parse_saved_residual_line", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "line" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "line_index" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#parse_saved_residual_line", "returns": { "annotation": "ADResidualRecord" }, "signature": "(line: 'str', *, line_index: 'int | None' = None) -> 'ADResidualRecord'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/ad_diagnostics.py#L309", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plan a mesh from geometry and frequency inputs using ``auto_configure``.\n\nThis function is a facade around ``auto_configure``; it does not duplicate\nthe mesh preset math. The returned ``MeshPlan`` adds structured audit rows,\nartifact declarations, and serialization helpers. ``artifact_root`` only\ndeclares intended paths; it never creates directories or writes files.", "kind": "function", "name": "rfx.plan_mesh", "parameters": [ { "annotation": "list", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "geometry" }, { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_range" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "str", "default": "'standard'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "accuracy" }, { "annotation": "str", "default": "'cpml'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx_override" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "margin_override" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps_override" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_memory_mb" }, { "annotation": "str | Path | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "artifact_root" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plan_mesh", "returns": { "annotation": "MeshPlan" }, "signature": "(geometry: 'list', freq_range: 'tuple[float, float]', materials: 'dict | None' = None, accuracy: 'str' = 'standard', *, boundary: 'str' = 'cpml', dx_override: 'float | None' = None, margin_override: 'float | None' = None, n_steps_override: 'int | None' = None, max_memory_mb: 'float | None' = None, artifact_root: 'str | Path | None' = None) -> 'MeshPlan'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/mesh_planner.py#L339", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plan/audit a configured ``Simulation`` using existing preflight APIs.\n\n``artifact_root`` only declares intended paths; it never creates directories\nor writes files.\n\n``sparameter_calculator=\"waveguide\"`` is the one calculator whose preflight\nis not free: it builds the grid and solves each waveguide port's mode so\nthe setup audits can read the runner's own plane indices and cutoffs. It\nruns no FDTD, but on a fine mesh with several ports it is seconds rather\nthan milliseconds. Those audits also file an informational row per port\npair (the known E-plane offset), which is a ``status=\"info\"`` row, not a\n``\"warn\"`` one.", "kind": "function", "name": "rfx.plan_simulation_mesh", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sparameter_calculator" }, { "annotation": "str | Path | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "artifact_root" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plan_simulation_mesh", "returns": { "annotation": "MeshPlan" }, "signature": "(sim: 'Any', *, n_steps: 'int | None' = None, checkpoint_every: 'int | None' = None, available_memory_gb: 'float | None' = None, sparameter_calculator: 'str | None' = None, artifact_root: 'str | Path | None' = None) -> 'MeshPlan'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/mesh_planner.py#L495", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Multi-panel antenna summary figure.\n\nPanels:\n1. Radiation pattern (polar, E-plane and H-plane)\n2. Gain vs theta (rectangular)\n3. S11 vs frequency (if provided)\n4. Efficiency vs frequency or gain statistics\n\nParameters\n----------\nff : FarFieldResult\ns11 : (n_freqs,) complex or real, optional\nfreqs : (n_freqs,) Hz for the S11 data, optional\nfreq_idx : frequency index for pattern plots.\ninput_power : for realized gain computation, optional.\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_antenna_summary", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s11" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_idx" }, { "annotation": "np.ndarray | float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "input_power" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_antenna_summary", "returns": { "annotation": "object" }, "signature": "(ff: 'FarFieldResult', *, s11: 'np.ndarray | None' = None, freqs: 'np.ndarray | None' = None, freq_idx: 'int' = 0, input_power: 'np.ndarray | float | None' = None) -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/antenna.py#L382", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "3D field visualization with isosurface or volume rendering.\n\nParameters\n----------\nstate : FDTDState\ngrid : Grid\ncomponent : field component name\nthreshold : float\n Isosurface threshold as fraction of peak value (0-1).\ntitle : str or None\nfigsize : tuple\ncmap : colormap name\nscale : coordinate scale factor\nscale_label : unit label\nbackend : \"auto\", \"matplotlib\", or \"pyvista\"\n\nReturns\n-------\nFigure (matplotlib) or Plotter (pyvista)", "kind": "function", "name": "rfx.plot_field_3d", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "float", "default": "0.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "threshold" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" }, { "annotation": "tuple[float, float]", "default": "(10, 8)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "figsize" }, { "annotation": "str", "default": "'RdBu_r'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cmap" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale" }, { "annotation": "str", "default": "'mm'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale_label" }, { "annotation": "str", "default": "'auto'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "backend" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_field_3d", "returns": { "annotation": "object" }, "signature": "(state, grid, *, component: 'str' = 'ez', threshold: 'float' = 0.1, title: 'str | None' = None, figsize: 'tuple[float, float]' = (10, 8), cmap: 'str' = 'RdBu_r', scale: 'float' = 1000.0, scale_label: 'str' = 'mm', backend: 'str' = 'auto') -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize3d.py#L289", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot a 2D slice of a field component.\n\nParameters\n----------\nstate : FDTDState\ngrid : Grid\ncomponent : field name (\"ex\", \"ey\", \"ez\", \"hx\", \"hy\", \"hz\")\naxis : normal axis for the slice (\"x\", \"y\", or \"z\")\nindex : grid index along axis (default: center)\ntitle : plot title\ncmap : colormap\nvmax : symmetric color range [-vmax, vmax]\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_field_slice", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "str", "default": "'z'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "axis" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "index" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" }, { "annotation": "str", "default": "'RdBu_r'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cmap" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "vmax" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_field_slice", "returns": { "annotation": "object" }, "signature": "(state, grid, *, component: 'str' = 'ez', axis: 'str' = 'z', index: 'int | None' = None, title: 'str | None' = None, cmap: 'str' = 'RdBu_r', vmax: 'float | None' = None) -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize.py#L26", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Render simulation geometry in 3D.\n\nParameters\n----------\nsim : Simulation\n rfx Simulation object with geometry and ports defined.\nshow_domain : bool\n Show the computational domain wireframe.\nshow_ports : bool\n Show port locations as arrows.\ntitle : str or None\n Plot title.\nfigsize : tuple\n Figure size.\nscale : float\n Coordinate scale factor (default 1e3 for mm).\nscale_label : str\n Unit label for axes.\nbackend : str\n \"auto\" (pyvista if available, else matplotlib), \"matplotlib\", or \"pyvista\".\n\nReturns\n-------\nFigure (matplotlib) or Plotter (pyvista)", "kind": "function", "name": "rfx.plot_geometry_3d", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "show_domain" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "show_ports" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" }, { "annotation": "tuple[float, float]", "default": "(10, 8)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "figsize" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale" }, { "annotation": "str", "default": "'mm'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale_label" }, { "annotation": "str", "default": "'auto'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "backend" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_geometry_3d", "returns": { "annotation": "object" }, "signature": "(sim, *, show_domain: 'bool' = True, show_ports: 'bool' = True, title: 'str | None' = None, figsize: 'tuple[float, float]' = (10, 8), scale: 'float' = 1000.0, scale_label: 'str' = 'mm', backend: 'str' = 'auto') -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize3d.py#L61", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot measured vs fitted complex permittivity.\n\nCreates a two-panel plot showing real and imaginary parts of permittivity\nas a function of frequency.\n\nParameters\n----------\nfreqs : (N,) array\n Frequencies in Hz.\neps_measured : (N,) complex array\n Measured permittivity.\neps_fitted : (N,) complex array\n Fitted permittivity from the model.\nax : matplotlib Axes or None\n If None, a new figure with two subplots is created.\n\nReturns\n-------\nfig : matplotlib Figure", "kind": "function", "name": "rfx.plot_material_fit", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_measured" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_fitted" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ax" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_material_fit", "returns": { "annotation": "object" }, "signature": "(freqs: 'np.ndarray', eps_measured: 'np.ndarray', eps_fitted: 'np.ndarray', *, ax: 'object | None' = None) -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/material_fit.py#L504", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot radiation pattern in polar coordinates.\n\nParameters\n----------\nff : FarFieldResult\nfreq_idx : frequency index\nphi_idx : phi cut index\ndb : plot in dB (normalized)\ntitle : plot title\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_radiation_pattern", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_idx" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "phi_idx" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "db" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_radiation_pattern", "returns": { "annotation": "object" }, "signature": "(ff, *, freq_idx: 'int' = 0, phi_idx: 'int' = 0, db: 'bool' = True, title: 'str | None' = None) -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize.py#L1059", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot RCS pattern in polar or rectangular coordinates.\n\nParameters\n----------\nrcs_result : RCSResult\n Output from ``compute_rcs()``.\nfreq_idx : int\n Frequency index to plot.\nphi_idx : int\n Phi cut index to plot.\npolar : bool\n If True, plot in polar coordinates. If False, rectangular.\ntitle : str or None\n Plot title.\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_rcs", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "rcs_result" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freq_idx" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "phi_idx" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polar" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_rcs", "returns": { "annotation": "object" }, "signature": "(rcs_result, *, freq_idx: 'int' = 0, phi_idx: 'int' = 0, polar: 'bool' = True, title: 'str | None' = None) -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize.py#L1146", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot S-parameter magnitudes vs frequency.\n\nParameters\n----------\ns_params : (n_ports, n_ports, n_freqs) complex\nfreqs : (n_freqs,) Hz\ndb : plot in dB\ntitle : plot title\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_s_params", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "db" }, { "annotation": "str", "default": "'S-Parameters'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_s_params", "returns": { "annotation": "object" }, "signature": "(s_params: 'np.ndarray', freqs: 'np.ndarray', *, db: 'bool' = True, title: 'str' = 'S-Parameters') -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize.py#L1015", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot S11 data on a Smith chart.\n\nParameters\n----------\ns11 : (n_freqs,) complex\n Reflection coefficient (Gamma) values.\nfreqs : (n_freqs,) Hz\n Corresponding frequencies.\nz0 : float\n Reference impedance (used only for annotation, not for\n re-normalisation).\nax : matplotlib Axes, optional\n Axes to plot on. If *None*, a new figure is created.\nshow_vswr : bool\n If True, draw VSWR = 2 and VSWR = 3 circles.\nmarkers : list of float, optional\n Frequencies (in Hz) at which to place labelled markers.\ntitle : str, optional\n Plot title. Defaults to ``\"Smith Chart\"``.\n\nReturns\n-------\nmatplotlib Axes", "kind": "function", "name": "rfx.plot_smith", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s11" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "z0" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ax" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "show_vswr" }, { "annotation": "list[float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "markers" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_smith", "returns": { "annotation": null }, "signature": "(s11: 'np.ndarray', freqs: 'np.ndarray', *, z0: 'float' = 50.0, ax=None, show_vswr: 'bool' = True, markers: 'list[float] | None' = None, title: 'str | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/smith.py#L92", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Visualize how a metric varies across the swept parameter.\n\nParameters\n----------\nsweep_result : SweepResult\n Output of ``parametric_sweep``.\nmetric : str or callable\n Built-in metric name (``\"s11_min_db\"`` or ``\"peak_field\"``), or a\n callable ``metric(result) -> float`` applied to each result.\ntitle : str or None\n Plot title. Defaults to ``\" sweep\"`` .\nylabel : str or None\n Y-axis label. Defaults to the metric name.\nmarker : str\n Matplotlib line/marker style (default ``\"o-\"``).\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_sweep", "parameters": [ { "annotation": "SweepResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sweep_result" }, { "annotation": "str", "default": "'s11_min_db'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "metric" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ylabel" }, { "annotation": "str", "default": "'o-'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "marker" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_sweep", "returns": { "annotation": "object" }, "signature": "(sweep_result: 'SweepResult', metric: 'str' = 's11_min_db', *, title: 'str | None' = None, ylabel: 'str | None' = None, marker: 'str' = 'o-') -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sweep.py#L241", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Plot probe time series.\n\nParameters\n----------\ntime_series : (n_steps, n_probes) array\ndt : timestep in seconds\nlabels : probe labels\ntitle : plot title\n\nReturns\n-------\nmatplotlib Figure", "kind": "function", "name": "rfx.plot_time_series", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "time_series" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "list[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "labels" }, { "annotation": "str", "default": "'Probe Time Series'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "title" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#plot_time_series", "returns": { "annotation": "object" }, "signature": "(time_series: 'np.ndarray', dt: 'float', *, labels: 'list[str] | None' = None, title: 'str' = 'Probe Time Series') -> 'object'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize.py#L1107", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Polarization sense: +1 = RHCP, -1 = LHCP, 0 = linear.\n\nReturns (n_freqs, n_theta, n_phi) array of integers.", "kind": "function", "name": "rfx.polarization_sense", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#polarization_sense", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1571", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Polarization tilt angle (orientation of major axis) in radians.\n\nReturns (n_freqs, n_theta, n_phi) array.", "kind": "function", "name": "rfx.polarization_tilt", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#polarization_tilt", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1552", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Progressive multi-resolution inverse design (issue #42).\n\nRuns ``optimize()`` at each stage in ``schedule``, upsampling the\nlatent between stages. Coarse stages produce a fast loss-landscape\nscan; finer stages refine on top.\n\nParameters\n----------\nsim_factory : callable(dx) -> Simulation\n Builds a Simulation at the given dx. Called once per stage.\nregion : DesignRegion\n Design region in physical coordinates (resolution-independent).\nobjective : callable(Result) -> scalar\n JAX-differentiable loss.\nschedule : list of ProgressiveStage\n Must be non-empty. Stages usually go coarse -> fine.\ninit_latent : jnp.ndarray or None\n Initial latent at the FIRST stage's design-region shape.\n If None, optimize() initialises to zeros.\ninterp_method : str\n Latent-upsample interpolation (\"linear\", \"nearest\", \"cubic\").\nverbose : bool\n Print per-stage progress banner.\nn_warmup : int\n Forwarded to each stage's ``optimize(..., n_warmup=...)`` call —\n see :func:`optimize`'s own ``n_warmup`` entry for the full\n behaviour (issue #40/#626): an approximation on non-uniform\n meshes, a fail-loud ``NotImplementedError`` on uniform ones.\n\nReturns\n-------\nProgressiveOptimizeResult\n\nNotes\n-----\nThe design variable basis is the per-stage latent (not a stage-\nindependent per-wavelength grid). ``jax.image.resize`` bridges\nstages, which is adequate when the mesh refinement is modest.\nFor dramatic resolution jumps, consider a dedicated per-wavelength\nbasis.", "kind": "function", "name": "rfx.progressive_optimize", "parameters": [ { "annotation": "Callable[[float], object]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": "DesignRegion", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "region" }, { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective" }, { "annotation": "list[ProgressiveStage]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "schedule" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "init_latent" }, { "annotation": "str", "default": "'linear'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "interp_method" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "verbose" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "emit_time_series" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "distributed" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#progressive_optimize", "returns": { "annotation": "ProgressiveOptimizeResult" }, "signature": "(sim_factory: 'Callable[[float], object]', region: 'DesignRegion', objective: 'Callable', schedule: 'list[ProgressiveStage]', *, init_latent: 'jnp.ndarray | None' = None, interp_method: 'str' = 'linear', verbose: 'bool' = True, skip_preflight: 'bool' = False, checkpoint_every: 'int | None' = None, emit_time_series: 'bool' = True, n_warmup: 'int' = 0, distributed: 'bool' = False) -> 'ProgressiveOptimizeResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize.py#L718", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a convergence study on an existing Simulation with dx scaling.\n\nCreates copies of *sim* at different cell sizes by scaling the base dx\nand re-running. This is a convenience wrapper around\n``convergence_study`` for quick checks.\n\nParameters\n----------\nsim : rfx.api.Simulation\n A fully configured simulation. Its ``_dx`` (or auto-computed dx)\n is used as the reference cell size scaled by each factor.\nmetric : str or callable\n ``\"resonance\"`` extracts the first resonance frequency.\n ``\"peak_field\"`` extracts the peak probe amplitude.\n A callable ``metric(Result) -> float`` is used directly.\ndx_factors : list of float or None\n Scaling factors applied to the base dx. Default ``[2.0, 1.5, 1.0, 0.75]``.\n Values > 1 mean coarser; < 1 mean finer.\nn_steps : int or None\n Forwarded to ``sim.run()``.\nuntil_decay : float or None\n Forwarded to ``sim.run()``.\nrun_kwargs : dict or None\n Additional keyword arguments forwarded to ``sim.run()``.\n\nReturns\n-------\nConvergenceResult", "kind": "function", "name": "rfx.quick_convergence", "parameters": [ { "annotation": "object", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "str | Callable", "default": "'resonance'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "metric" }, { "annotation": "list[float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dx_factors" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "until_decay" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#quick_convergence", "returns": { "annotation": "ConvergenceResult" }, "signature": "(sim: 'object', *, metric: 'str | Callable' = 'resonance', dx_factors: 'list[float] | None' = None, n_steps: 'int | None' = None, until_decay: 'float | None' = None, run_kwargs: 'dict | None' = None) -> 'ConvergenceResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/convergence.py#L358", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Normalized radiation pattern in dB.\n\nReturns (n_freqs, n_theta, n_phi) array.", "kind": "function", "name": "rfx.radiation_pattern", "parameters": [ { "annotation": "FarFieldResult", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#radiation_pattern", "returns": { "annotation": "np.ndarray" }, "signature": "(ff: 'FarFieldResult') -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/farfield.py#L1480", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Read S-parameters from a Touchstone file.\n\nThis legacy compatibility API returns a scalar reference impedance. If a\nTouchstone 2.0 file carries non-uniform per-port references, use\n:func:`read_touchstone_full` instead.\n\nParameters\n----------\nfilepath : str or Path\nlayout : str\n Auto-detect old unmarked rfx v1 exports; otherwise use standard order.\n An explicit layout overrides detection.\n\nReturns\n-------\ns_params : (n_ports, n_ports, n_freqs) complex array\nfreqs : (n_freqs,) float in Hz\nz0 : float reference impedance", "kind": "function", "name": "rfx.read_touchstone", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "filepath" }, { "annotation": "str", "default": "'auto'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "layout" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#read_touchstone", "returns": { "annotation": "tuple[np.ndarray, np.ndarray, float]" }, "signature": "(filepath: 'str | Path', *, layout: 'str' = 'auto') -> 'tuple[np.ndarray, np.ndarray, float]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L362", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Read S-parameters and Touchstone metadata.\n\nSupported subset:\n- S-parameters only\n- RI, MA, and DB numeric formats\n- Touchstone 1-style data blocks\n- Touchstone 2.0 metadata keywords used by rfx interop\n- Touchstone 2.0 information blocks preserved as raw lines\n- Full matrix data only\n\n``layout=\"auto\"`` detects legacy column-major order for unmarked rfx\nv1 exports with 3+ ports. Marked exports and external files use standard\norder. Two-port and v2 files are unaffected; explicit layouts override.", "kind": "function", "name": "rfx.read_touchstone_full", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "filepath" }, { "annotation": "str", "default": "'auto'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "layout" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#read_touchstone_full", "returns": { "annotation": "TouchstoneData" }, "signature": "(filepath: 'str | Path', *, layout: 'str' = 'auto') -> 'TouchstoneData'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L392", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "The one function that turns conductor geometry into PEC E edges.\n\nParameters\n----------\ncell_mask : (nx, ny, nz) bool array or None\n Primal-cell occupancy of every PEC VOLUME (Box / Sphere / Cylinder\n via ``sim.add``, and thick ``PolylineWire``). ``None`` when the run\n has no volume conductor.\nsheets : iterable of :class:`SheetSpec`\n PEC sheets (``add_thin_conductor`` with PEC conductivity).\nwires : iterable of :class:`WireSpec`\n PEC filaments.\nperiodic : (bool, bool, bool)\n The run's per-axis periodic flags (#689). Callers on a periodic\n lane MUST pass their own; the default is the non-periodic\n convention.\n\nReturns\n-------\n(Mx, My, Mz) boolean arrays, grid shape: True where that E component\nis zeroed. Consequences the contract test pins: a Box drawn\n``z_a -> z_b`` on node planes realizes walls at BOTH planes and shorts\nevery normal edge between them; a 1-cell Box is a filled slab with two\nfaces on every axis; a sheet is one plane with its normal edge live;\nthe rule is invariant under mirror and axis permutation.", "kind": "function", "name": "rfx.realized_pec_edge_masks", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cell_mask" }, { "annotation": null, "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sheets" }, { "annotation": null, "default": "()", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "wires" }, { "annotation": null, "default": "(False, False, False)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "periodic" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#realized_pec_edge_masks", "returns": { "annotation": null }, "signature": "(cell_mask, sheets=(), wires=(), periodic=(False, False, False))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/boundaries/pec.py#L643", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Sorted node-plane indices along ``axis`` where a tangential wall exists.\n\nA plane ``k`` counts when some E component tangential to ``axis`` (the\ntwo components other than ``axis``) is PEC on that plane, inside the\nselection:\n\n* ``region`` — a tuple of three slices over the grid; ``None`` is the\n whole grid. Any tangential edge whose index falls in the region.\n* ``ij`` — the two in-plane node indices of ONE column (in axis order,\n skipping ``axis``). A wall counts on the column when any tangential\n edge INCIDENT to the node ``(ij, k)`` is PEC, i.e. ``E_t`` at the\n node's own index or at the backward index along ``t`` — so a node on\n the hi rim of a footprint, whose incident edges are stored at\n ``i-1``, is found. The backward neighbour follows the run's #689\n convention: on a periodic (or length-1) in-plane axis the backward\n neighbour of index 0 is ``n-1``, so a wall on the seam node is\n found; on a non-periodic axis index 0 has no backward edge.\n\n``periodic`` is the run's per-axis flags; callers on a periodic lane\nMUST pass their own (the default is the non-periodic convention). It\nonly affects the ``ij=`` column form — ``region=`` already scans every\nstored index.\n\n``ij`` and ``region`` are exclusive. Consumers: preflight cavity /\nguide-width checks, cv15 ``assert_realized_stack``, MSL trace\ndetection, oracles.\n\nEVERY plane, not just the two faces. A body three cells thick has a\ntangential wall on all four of its node planes, because the interior\nis shorted too, so this returns four indices and not two. ``max -\nmin`` is therefore the body's OUTER span and over-reads a guide or a\ncavity bounded by thick walls: a 40-cell guide inside 3-cell walls\ngives ``[0, 1, 2, 3]`` and ``[43, 44, 45]``, and ``45 - 0`` is 45, not\n40. A consumer that wants the clear opening brackets the aperture\nbetween the hi plane of one wall group and the lo plane of the next\n(``_port_transverse_spans`` does, and reads 40).", "kind": "function", "name": "rfx.realized_wall_planes", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "edge_masks" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ij" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "region" }, { "annotation": null, "default": "(False, False, False)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "periodic" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#realized_wall_planes", "returns": { "annotation": null }, "signature": "(edge_masks, axis, *, ij=None, region=None, periodic=(False, False, False))", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/boundaries/pec.py#L696", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Render a concise human-readable artifact review report.", "kind": "function", "name": "rfx.render_artifact_markdown", "parameters": [ { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "report" } ], "reference_url": null, "returns": { "annotation": "str" }, "signature": "(report: 'dict[str, Any]') -> 'str'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L684", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Replay an S-matrix from a loaded :class:`PortVIDump`.", "kind": "function", "name": "rfx.replay_smatrix_from_port_vi_dump", "parameters": [ { "annotation": "PortVIDump", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dump" } ], "reference_url": null, "returns": { "annotation": "PortSMatrixObservable" }, "signature": "(dump: 'PortVIDump') -> 'PortSMatrixObservable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L939", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Replay an S-matrix from raw V/I phasors.\n\nThis is an independent post-processor for E3 evidence. It uses the\npower-wave split, role-selected per port to mirror the production\nlumped decomposer (issue #308):\n\n``a = (V + Z0 I) / (2 sqrt(Z0))`` (incident, at the DRIVEN port),\n``b = (V - Z0 I) / (2 sqrt(Z0))`` (reflected, at the DRIVEN port), and\n``b_recv = -(V + Z0 I) / (2 sqrt(Z0))`` (arriving, at a PASSIVE\nreceive port — the production receive channel ``(V_fdtd - Z0 I)``\nexpressed in this dump's into-DUT voltage convention ``V = -V_fdtd``;\nthe overall sign is pinned empirically by the DC falsifier on the\ncanonical thru, S21(DC) -> +1)\n\n``diagonal_frame`` selects the DRIVEN diagonal. The default,\n``\"port_branch\"``, is ``b/a`` on the stored ``(V, I)`` — the standard\npower-wave reflection for a pair that really is (voltage into the DUT,\ncurrent into the DUT), and this function's contract.\n``\"driven_terminal\"`` is ``(V_fdtd - Z0 I)/(V_fdtd + Z0 I)`` with\n``V_fdtd = -V``, for a dump whose stored voltage sign makes the pair\ninconsistent AT THE DRIVEN PORT while keeping the off-diagonal role\nchannel right — which is the case for rfx's own lumped-port dump since\n2026-09-21 (scripts/diagnostics/lumped_port_known_load_line.py; on that\nknown-load line ``b/a`` at a driven port reads 4.757 where the closed\nform is 0.333, the reciprocal of the physical reflection). Such a dump\nsays so in its metadata; see :func:`replay_smatrix_from_port_vi_dump`.\nThe off-diagonal role channel is unchanged by this switch.\n\nIn the ``\"driven_terminal\"`` frame the whole column shares ONE incident\nwave, the physical one at the driven port, so the diagonal and the\noff-diagonals have the same denominator. That is the wire family's\nwhole-port frame, which rfx's lumped lane now evaluates at one live cell,\nand it needs no channel beyond the stored V and I.\n\nwith current positive **into** the DUT by default. If the dump records\ncurrent positive out of the DUT, set ``current_convention=\"positive_out_of_dut\"``\nand the sign is flipped before wave decomposition.\n\nOptional reference-plane shifts are explicit metadata, not hidden magic:\n``reference_plane_offsets_m[i] > 0`` means the reported reference plane\nis farther into the DUT than the raw measurement plane in port ``i``'s\nlocal coordinate. With propagation constant ``gamma`` this applies\n``a_ref = a_raw exp(-gamma d)`` and\n``b_ref = b_raw exp(+gamma d)``.", "kind": "function", "name": "rfx.replay_smatrix_from_vi_dump", "parameters": [ { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "voltages" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "currents" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "Any", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_impedances" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_names" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "driven_port_indices" }, { "annotation": "str", "default": "'positive_into_dut'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_convention" }, { "annotation": "str", "default": "'port_branch'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "diagonal_frame" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_plane_offsets_m" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "propagation_constants" }, { "annotation": "str", "default": "'vi_dump_replay'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "source" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#replay_smatrix_from_vi_dump", "returns": { "annotation": "PortSMatrixObservable" }, "signature": "(voltages: 'Any', currents: 'Any', *, freqs: 'Any | None' = None, port_impedances: 'Any' = 50.0, port_names: 'Any | None' = None, driven_port_indices: 'Any | None' = None, current_convention: 'str' = 'positive_into_dut', diagonal_frame: 'str' = 'port_branch', reference_plane_offsets_m: 'Any | None' = None, propagation_constants: 'Any | None' = None, source: 'str' = 'vi_dump_replay') -> 'PortSMatrixObservable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L557", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Richardson extrapolation to estimate the grid-independent value.\n\nUses the three finest grid points to estimate both the converged value\nand the effective convergence order. Falls back to two-point\nextrapolation when only two values are available.\n\nParameters\n----------\nvalues : array-like\n Metric values at each cell size (must have >= 2 elements).\ndx_values : array-like\n Cell sizes corresponding to *values* (same length).\nexpected_order : float\n Initial guess for the convergence order (default 2 for Yee).\n\nReturns\n-------\n(extrapolated, order) : (float, float)\n Estimated grid-independent value and observed convergence order.\n\nNotes\n-----\nWhen three or more values are available the order *p* is estimated by\nsolving the ratio of successive differences:\n\n (f3 - f2) / (f2 - f1) = (h3^p - h2^p) / (h2^p - h1^p)\n\nwhere h = dx and f = metric. A Newton iteration refines *p* from the\ninitial guess. With only two values the *expected_order* is used\ndirectly.", "kind": "function", "name": "rfx.richardson_extrapolation", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "values" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx_values" }, { "annotation": "float", "default": "2.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "expected_order" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#richardson_extrapolation", "returns": { "annotation": "tuple[float, float]" }, "signature": "(values, dx_values, expected_order: 'float' = 2.0) -> 'tuple[float, float]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/convergence.py#L43", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a compiled FDTD simulation via ``jax.lax.scan``.\n\nParameters\n----------\ngrid : Grid\nmaterials : MaterialArrays\nn_steps : int\ngradient : {\"autodiff\", \"adjoint\"}\n Adjoint requires a uniform real-valued design box. It stores local\n DFTs instead of checkpoints; checkpoint options are unused.\n See the module docstring of ``rfx.adjoint``.\nboundary : \"pec\", \"cpml\", or \"upml\"\ncpml_axes : str or None: the grid's absorbing axes when omitted; subsets accepted\npec_axes : axes string or None\n Axes on which to enforce PEC after each update. If None, uses\n all non-periodic axes.\nperiodic : (bool, bool, bool) or None\n Per-axis periodic boundary flags. If None, defaults to\n ``(False, False, False)`` in 3D and ``(False, False, True)``\n in 2D modes.\ndebye : (DebyeCoeffs, DebyeState) tuple, or None\nlorentz : (LorentzCoeffs, LorentzState) tuple, or None\ntfsf : (TFSFConfig, TFSFState) tuple, or None\n Optional total-field/scattered-field plane-wave source. When\n provided, the 1D auxiliary FDTD is interleaved with the 3D Yee\n updates using the Taflove leapfrog ordering.\nsources : list of SourceSpec (precomputed waveforms)\nprobes : list of ProbeSpec (point time-series recorders)\ndft_planes : list of DFTPlaneProbe or None\n Optional running frequency-domain plane probes.\nwaveguide_ports : list of WaveguidePortConfig or None\n Optional waveguide-port source/probe configs.\nntff : NTFFBox or None\n If provided, accumulate near-to-far-field DFT on a Huygens box.\nsnapshot : SnapshotSpec or None\n If provided, record a frame after every ``snapshot.interval``-th\n step (``n_steps // interval`` frames; see ``SnapshotSpec``), with\n their positions and times in ``SimResult.snapshot_axes``. Recording\n does not change any other output: the time series, DFT and port\n accumulators and the final state are bit-identical to the same run\n without a snapshot. ``interval=1`` records inside the step body, as\n it always has; a larger interval runs the steps in blocks of\n ``interval`` (``lax.scan`` over blocks of an inner ``lax.scan`` over\n steps, plus a scan over the remaining ``n_steps % interval``) and\n records after each block, so the step body is the one a run without\n a snapshot compiles. The remainder scan is a second compile of the\n step body; a remainder of ONE step is instead joined with the last\n step of the last block into a two-step scan (a one-step scan is\n inlined by XLA and changed the last bit), leaving the rest of that\n block as a scan of ``interval - 1`` steps. With ``report_every`` a\n chunk that does not start on a multiple of the interval adds a short\n head scan, and each distinct piece length compiles once\n (``rfx.snapshots.plan_snapshot_pieces`` lays the pieces out). With\n ``checkpoint_segments`` the interval must divide the segment length\n ``n_steps // checkpoint_segments``.\ncheckpoint : bool\n If True, wrap the scan body with ``jax.checkpoint`` to\n trade compute for memory during reverse-mode AD. Reduces\n backward-pass memory from O(n_steps) to O(1) per step.\nreturn_state : bool\n If False, do not expose the final FDTD state in the result.\n This shrinks the differentiable output surface for optimisation.\nreport_every : int or None\n Issue #667. When set, emit one `` [PROGRESS] ...`` line to stdout\n every *N* steps: steps done / total, wall elapsed, implied rate and\n ETA. ``None`` (default) is OFF and runs the unchanged single-scan\n code path, so existing callers are byte-identical by construction.\n\n When set, the same compiled scan is driven from the host in\n ``report_every``-step chunks with ``carry`` threaded through, so the\n result is a continuation and not a re-solve; the DFT accumulators\n and every port / flux / monitor state live in that carry.\n Bit-exactness against ``report_every=None`` is locked by\n ``tests/unit/runners/test_run_progress_reporting.py``.\n\n Costs, measured rather than hidden: each report inserts one device\n synchronisation (without it the host would dispatch every chunk at\n once and print a fabricated rate), all full chunks share one XLA\n executable while a ragged final chunk compiles once more, and the\n per-chunk outputs are joined once at the end with a bounded-arity\n grouped concatenate (a flat one takes an argument per chunk, which\n cost 232 s at 22,500 chunks against 0.99 s grouped).\n\n Forward-only: it reads the host wall clock, so it raises under\n ``jax.jit``/``grad``/``vmap`` and is rejected together with\n ``checkpoint_segments``. The trace check inspects the carry, the\n per-step ``xs`` and the material / geometry arrays — the routes\n ``forward()`` and ``optimize()`` actually trace through — rather\n than asking JAX whether a trace is active, which its current API\n does not expose. A tracer reaching the scan body by some other\n closure alone would print trace-time lines; the computed values\n stay byte-identical either way.\nreport_label : str\n Short tag prefixed to each progress line, e.g. ``\"MSL drive p1\"``,\n so the per-drive solves of one ``compute_*_s_matrix`` call are\n distinguishable in a log. Ignored when ``report_every`` is None.\ndesign_box : DesignBoxSpec or None\n Issue #1179. One static box whose E update is redone from its own\n (usually traced) permittivity, leaving ``materials`` constant so the\n reverse-mode tape holds box-shaped arrays instead of grid-shaped\n ones. ``None`` (default) is the unchanged path.\n\n ``_resolve_design_box`` rejects, from what this function resolves:\n UPML, Debye/Lorentz, anisotropic eps, Kerr, ``stencil_order=4``, the\n Bloch path, a box reaching into the CPML absorber, and a box holding\n a source, magnetic source, lumped/wire S-param port or RLC cell or a\n surface-impedance sheet edge. It does NOT carry the checks that need\n the API object: the lane (non-uniform, distributed, ADI), the\n collision with ``eps_override`` / ``sigma_override`` /\n ``mu_r_override``, ``pec_occupancy_override``, a PASSIVE port (it\n leaves neither a source nor an accumulator here), and the promotion\n of ``materials.eps_r`` to the design dtype. Those are\n ``Simulation.forward``'s, in ``_resolve_design_box_override``; a\n caller reaching this function directly owns them.\ndesign_occupancy : DesignOccupancySpec or None\n Issue #1183. One static box whose PEC OCCUPANCY is the traced\n quantity, for the same reason and with the same effect on the tape:\n the ``1 - M`` scaling is redone on the box's window from the field\n before the grid-wide ``apply_pec_occupancy``, so what the backward\n pass keeps per step is window-shaped. ``None`` (default) is the\n unchanged path. The box's occupancy REPLACES ``pec_occupancy`` at\n the box cells; outside it, ``pec_occupancy`` is carried.\n\n ``_resolve_design_occupancy`` rejects a periodic axis, an empty box\n and a box off the grid. ``Simulation.forward`` owns the lane and the\n collision with ``design_eps_override``.\nstop_fn : callable or None\n Issue #1254 (``Simulation.run(..., until_identified=True)``). When\n given, the scan runs in chunks of ``stop_interval`` steps through\n :func:`rfx.progress.scan_with_progress`, the carry threaded through,\n and ``stop_fn(steps_done, peek)`` is called after each chunk;\n ``peek()`` returns the record so far as a namespace with\n ``time_series`` (``(steps_done, n_probes)``), ``wire_port_sparams``\n (the ``(spec, accumulators)`` pairs at that step, as this function\n returns them), ``grid`` and ``dt``. A true return ends the run\n there, and every output is the one a run of ``steps_done`` steps\n returns (the chunked scan is a continuation of the single one).\n Refused with a snapshot or ``checkpoint_segments``. ``None``\n (default) is the unchanged path.\nstop_interval : int\n Chunk length of the ``stop_fn`` loop (default 250). Ignored when\n ``stop_fn`` is None.\n\nReturns\n-------\nSimResult with final state, time series, and optional NTFF data.", "kind": "function", "name": "rfx.run", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "str", "default": "'pec'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_axes" }, { "annotation": "tuple[bool, bool, bool] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "periodic" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tfsf" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "_feature_tfsf" }, { "annotation": "list[SourceSpec] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sources" }, { "annotation": "list[ProbeSpec] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probes" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_planes" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "flux_monitors" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveguide_ports" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ntff" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_moments" }, { "annotation": "SnapshotSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "snapshot" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "str", "default": "'autodiff'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "gradient" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_eps" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps_smooth" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_mask" }, { "annotation": "object", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_sheets" }, { "annotation": "object", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_wires" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_occupancy" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_weights" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "wire_port_sparams" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lumped_port_sparams" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "wire_refplane_sparams" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lumped_rlc" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "kerr_chi3" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_dtype" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_state" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mag_sources" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stencil_order" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_every" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_label" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sheet_impedance" }, { "annotation": "DesignBoxSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_box" }, { "annotation": "DesignOccupancySpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_occupancy" }, { "annotation": "Callable | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stop_fn" }, { "annotation": "int", "default": "250", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stop_interval" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "record_dft" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#run", "returns": { "annotation": "SimResult" }, "signature": "(grid: 'Grid', materials: 'MaterialArrays', n_steps: 'int', *, boundary: 'str' = 'pec', cpml_axes: 'str | None' = None, pec_axes: 'str | None' = None, periodic: 'tuple[bool, bool, bool] | None' = None, debye: 'tuple | None' = None, lorentz: 'tuple | None' = None, tfsf: 'tuple | None' = None, _feature_tfsf: 'bool' = False, sources: 'list[SourceSpec] | None' = None, probes: 'list[ProbeSpec] | None' = None, dft_planes: 'list | None' = None, flux_monitors: 'list | None' = None, waveguide_ports: 'list | None' = None, ntff: 'object | None' = None, current_moments: 'object | None' = None, snapshot: 'SnapshotSpec | None' = None, checkpoint: 'bool' = False, gradient: 'str' = 'autodiff', checkpoint_segments: 'int | None' = None, aniso_eps: 'tuple | None' = None, aniso_inv_eps: 'tuple | None' = None, aniso_inv_eps_smooth: 'bool' = False, pec_mask: 'object | None' = None, pec_sheets: 'object' = (), pec_wires: 'object' = (), pec_edge_masks: 'object | None' = None, pec_occupancy: 'object | None' = None, conformal_weights: 'tuple | None' = None, wire_port_sparams: 'list | None' = None, lumped_port_sparams: 'list | None' = None, wire_refplane_sparams: 'list | None' = None, lumped_rlc: 'list | None' = None, kerr_chi3: 'jnp.ndarray | None' = None, field_dtype=None, return_state: 'bool' = True, mag_sources: 'list | None' = None, stencil_order: 'int' = 2, report_every: 'int | None' = None, report_label: 'str' = '', sheet_impedance: 'object | None' = None, design_box: 'DesignBoxSpec | None' = None, design_occupancy: 'DesignOccupancySpec | None' = None, stop_fn: 'Callable | None' = None, stop_interval: 'int' = 250, record_dft: 'bool' = False) -> 'SimResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L1968", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a 2D TMz ADI-FDTD simulation for *n_steps* timesteps.\n\nParameters\n----------\nez, hx, hy : (Nx, Ny) initial field arrays\neps_r : (Nx, Ny) relative permittivity\nsigma : (Nx, Ny) conductivity\ndt, dx, dy : timestep and cell sizes\nn_steps : number of full timesteps\nsources : list of (i, j, waveform_array) tuples.\nprobes : list of probe tuples.\nez_pec_mask : (Nx, Ny) bool array or None\n Reserved realized Ez mask (#931 §1.7); non-None is refused.\ncpml_params : ADICPMLParams2D or None\n CPML profile coefficients. When provided, CPML absorbing boundary\n is applied after each ADI step (operator-splitting).\ncpml_state : ADICPMLState2D or None\n Initial CPML auxiliary state. Required when cpml_params is set.\n\nReturns\n-------\nez, hx, hy : final field arrays\nprobe_data : (n_steps, n_probes) array or None", "kind": "function", "name": "rfx.run_adi_2d", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sources" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "probes" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez_pec_mask" }, { "annotation": "ADICPMLParams2D | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_params" }, { "annotation": "ADICPMLState2D | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "cpml_state" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ez: 'jnp.ndarray', hx: 'jnp.ndarray', hy: 'jnp.ndarray', eps_r: 'jnp.ndarray', sigma: 'jnp.ndarray', dt: 'float', dx: 'float', dy: 'float', n_steps: 'int', sources: 'list | None' = None, probes: 'list | None' = None, ez_pec_mask: 'jnp.ndarray | None' = None, cpml_params: 'ADICPMLParams2D | None' = None, cpml_state: 'ADICPMLState2D | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L686", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a 3D ADI-FDTD simulation for *n_steps* timesteps.\n\nParameters\n----------\nex, ey, ez, hx, hy, hz : (Nx, Ny, Nz) initial field arrays\neps_r : (Nx, Ny, Nz) relative permittivity\nsigma : (Nx, Ny, Nz) conductivity\ndt, dx, dy, dz : timestep and cell sizes\nn_steps : number of full timesteps\nsources : list of (i, j, k, component, waveform_array) tuples\nprobes : list of (i, j, k, component) tuples\npec_edge_masks : (Mx, My, Mz) bool arrays or None\n Reserved realized edge masks (#931 §1.7); non-None is refused.\n\nReturns\n-------\nex, ey, ez, hx, hy, hz : final field arrays\nprobe_data : (n_steps, n_probes) array or None", "kind": "function", "name": "rfx.run_adi_3d", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ex" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ey" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ez" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hx" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hy" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "hz" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_r" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sigma" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dy" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dz" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "sources" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "probes" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(ex: 'jnp.ndarray', ey: 'jnp.ndarray', ez: 'jnp.ndarray', hx: 'jnp.ndarray', hy: 'jnp.ndarray', hz: 'jnp.ndarray', eps_r: 'jnp.ndarray', sigma: 'jnp.ndarray', dt: 'float', dx: 'float', dy: 'float', dz: 'float', n_steps: 'int', sources: 'list | None' = None, probes: 'list | None' = None, pec_edge_masks: 'tuple | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L1084", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run simulations for all parameter combinations.\n\nParameters\n----------\nsim_factory : callable\n Function that takes keyword args from the sweep and returns\n a configured Simulation object (or any object with a .run() method).\nsweep : ParameterSweep\n Parameter sweep definition.\nrun_kwargs : dict or None\n Extra keyword arguments passed to sim.run().\n\nReturns\n-------\nlist of (params_dict, result) tuples", "kind": "function", "name": "rfx.run_batch", "parameters": [ { "annotation": "Callable[..., Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": "ParameterSweep", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sweep" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#run_batch", "returns": { "annotation": "list[tuple[dict, Any]]" }, "signature": "(sim_factory: 'Callable[..., Any]', sweep: 'ParameterSweep', *, run_kwargs: 'dict | None' = None) -> 'list[tuple[dict, Any]]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L530", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a sequential sweep with durable per-case provenance.\n\nThe runner records stable case ids, parameters, status, timings, metrics,\nand optional artifact paths. ``artifact_fn`` may return paths relative to\nthe case directory, paths relative to the output root, or absolute paths\ninside the output root.\nThe runner automatically fingerprints ``run_kwargs`` so changing run\nsettings (for example ``n_steps``) invalidates resume. Pass\n``run_fingerprint`` when simulation factory, metric semantics, or external\ninputs changed but ``run_kwargs`` did not. When ``resume=True``, a case is\nskipped only if the manifest record is completed, has the expected run\nfingerprint, contains at least one metric, and all declared artifact paths\nstill exist. With ``continue_on_error=True``, failed cases are recorded and\nlater cases continue; the default preserves the fail-fast behavior.", "kind": "function", "name": "rfx.run_batch_with_manifest", "parameters": [ { "annotation": "Callable[..., Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim_factory" }, { "annotation": "ParameterSweep", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sweep" }, { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "output_dir" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_kwargs" }, { "annotation": "Callable[[Any], dict[str, Any]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "metric_fn" }, { "annotation": "Callable[[Path, dict[str, Any], Any], dict[str, str | Path] | None] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "artifact_fn" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "resume" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "continue_on_error" }, { "annotation": "str", "default": "'manifest.json'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "manifest_name" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "run_fingerprint" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_environment" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#run_batch_with_manifest", "returns": { "annotation": "list[BatchCaseResult]" }, "signature": "(sim_factory: 'Callable[..., Any]', sweep: 'ParameterSweep', output_dir: 'str | Path', *, run_kwargs: 'dict | None' = None, metric_fn: 'Callable[[Any], dict[str, Any]] | None' = None, artifact_fn: 'Callable[[Path, dict[str, Any], Any], dict[str, str | Path] | None] | None' = None, resume: 'bool' = True, continue_on_error: 'bool' = False, manifest_name: 'str' = 'manifest.json', run_fingerprint: 'str | None' = None, include_environment: 'bool' = True) -> 'list[BatchCaseResult]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L355", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run non-uniform FDTD via jax.lax.scan.\n\nParameters\n----------\ncpml_axes : str or None: axes with absorber pads when omitted; subsets accepted\nsources : list of (i, j, k, component, waveform_array)\nprobes : list of (i, j, k, component)\nwire_ports : list of dict with keys:\n mid_i, mid_j, mid_k, component, impedance, waveform_array\ns_param_freqs : (n_freqs,) array for S-param DFT\ndebye : (DebyeCoeffs, DebyeState) or None\nlorentz : (LorentzCoeffs, LorentzState) or None\ndft_planes : list of DFTPlaneProbe or None\n Frequency-domain plane accumulators. The accumulation is\n identical to the uniform path (acc += field * exp(-j2pi f t) * dt);\n dt is scalar on both paths so no per-axis weighting is required.", "kind": "function", "name": "rfx.run_nonuniform", "parameters": [ { "annotation": "NonUniformGrid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_mask" }, { "annotation": null, "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_sheets" }, { "annotation": null, "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_wires" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_occupancy" }, { "annotation": "list", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sources" }, { "annotation": "list", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probes" }, { "annotation": "list", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "wire_ports" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s_param_freqs" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_faces" }, { "annotation": "set[str] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pmc_faces" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_planes" }, { "annotation": "tuple", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "rlc_metas" }, { "annotation": "tuple", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "rlc_states" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ntff_box" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ntff_data" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_moments" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveguide_ports" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tfsf" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "_feature_tfsf" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "flux_monitors" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "emit_time_series" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_eps" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sheet_impedance" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_box" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "record_dft" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#run_nonuniform", "returns": { "annotation": "dict" }, "signature": "(grid: 'NonUniformGrid', materials: 'MaterialArrays', n_steps: 'int', *, cpml_axes: 'str | None' = None, pec_mask=None, pec_sheets=(), pec_wires=(), pec_edge_masks=None, pec_occupancy=None, sources: 'list' = None, probes: 'list' = None, wire_ports: 'list' = None, s_param_freqs=None, debye: 'tuple | None' = None, lorentz: 'tuple | None' = None, pec_faces: 'set[str] | None' = None, pmc_faces: 'set[str] | None' = None, dft_planes: 'list | None' = None, rlc_metas: 'tuple' = (), rlc_states: 'tuple' = (), ntff_box=None, ntff_data=None, current_moments=None, waveguide_ports: 'list | None' = None, tfsf: 'tuple | None' = None, _feature_tfsf: 'bool' = False, flux_monitors: 'list | None' = None, checkpoint: 'bool' = False, emit_time_series: 'bool' = True, checkpoint_every: 'int | None' = None, n_warmup: 'int' = 0, aniso_eps: 'tuple | None' = None, sheet_impedance=None, design_box=None, record_dft: 'bool' = False) -> 'dict'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/nonuniform.py#L2837", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run simulation until field energy decays to *decay_by* of peak.\n\nRuns compiled scan chunks with host-side decay checks at the historical\nstep indices (0, check_interval, ...).\n\nParameters\n----------\ndecay_by : float\n Stop when |field|^2 < decay_by * peak|field|^2.\ncheck_interval : int\n Check decay every N steps.\nmin_steps : int\n Always run at least this many steps.\nmax_steps : int\n Hard upper limit on steps.\ndecay_energy_consecutive : int\n On **absorbing** boundaries (``cpml`` / ``upml``) the stop uses the\n total interior-domain energy criterion (issue #169). It fires only\n after the interior energy ``U`` has stayed below ``decay_by * peak_U``\n on this many *consecutive* checks. Default ``2`` (MANDATORY minimum):\n the interior energy of a guided geometry is not null-free, dipping\n through transient inter-packet minima that recover; a single below-\n threshold check can false-fire on such a dip, so ``>= 2`` is required\n to absorb the chatter. Has no effect on closed/PEC boundaries (which\n use the instantaneous point-field fallback).\nradiated_flux_box : tuple or None\n Opt-in (#388) RADIATED-FLUX stop for absorbing boundaries: a Huygens box\n ``((x_lo, y_lo, z_lo), (x_hi, y_hi, z_hi))`` in physical coordinates\n enclosing the structure (clear of the CPML). When set, the stop uses the\n outgoing Poynting flux through the box instead of the interior energy —\n a *radiation-settling* criterion that ignores non-radiating trapped\n energy (the static soft-source charge that FLOORS the energy criterion,\n and near-Nyquist grid buzz), because neither carries net radiated power.\n Appropriate for radiation / S-parameter measurements; the flux peak is\n tracked from the first check (the radiation peaks during the source\n drive). Default ``None`` keeps the interior-energy criterion, unchanged.\nflux_env_checks : int\n Number of recent checks whose ``|flux|`` max forms the envelope used by\n the radiated-flux stop, smoothing the 2f0 Poynting oscillation. Default 4.\nmonitor_component : str\n Field component to monitor (\"ez\", \"hy\", etc.). Used only by the\n closed/PEC point-field fallback stop.\nmonitor_position : tuple or None\n Physical position (x, y, z) to monitor. If None, use center of\n the domain.\ncheckpoint_segments : int or None\n **Not supported** on the decay path. ``run_until_decay`` uses a\n host-driven early stop, so scan-level gradient checkpointing does\n not apply. Passing a non-None value raises\n ``NotImplementedError``.\n\nNotes\n-----\n**Differences from** :func:`run`:\n\n* ``checkpoint_segments`` is not supported (raises ``NotImplementedError``\n when not ``None``).\n* ``snapshot`` records a frame after every ``snapshot.interval``-th step\n of the loop, as :func:`run` does (#1258): ``actual_steps // interval``\n frames, positions and times in ``SimResult.snapshot_axes``. Reading\n the frame does not touch the stepped state.\n* ``checkpoint`` (``jax.checkpoint`` gradient tape) is accepted but\n **silently ignored** — gradient checkpointing has no effect on the\n host-driven decay path.\n* Flux-monitor DFT accumulation uses a rectangular (no-window) weight\n instead of the streaming Hann window used by :func:`run`. Flux values\n from the two paths are therefore not numerically identical even for\n the same step count.\n\n.. note::\n\n **The stop criterion depends on the boundary (issue #169, RESOLVED for\n absorbing boundaries).**\n\n * **Absorbing boundaries (``cpml`` / ``upml``)** — the stop is gated on\n the **total interior-domain energy** ``U = sum(E^2 + H^2)`` over the\n non-CPML interior slice, declared decayed once ``U < decay_by * peak_U``\n on ``decay_energy_consecutive`` consecutive checks. Because it is a\n whole-domain energy, it does not pass through the per-cell\n interference nulls that the old single-cell point-field stopper hit\n between slow-tail wave packets, so it **is** suitable for flux /\n S-parameter / transmission measurements on guided / low-loss\n geometries. (On the cv03-class eps=12 guide it now stops at the\n flux-converged transmission within ~0.13%, vs the prior ~7% under-run\n of the point-field stop.) ``decay_energy_consecutive >= 2`` is\n mandatory because the interior energy is *not* null-free — it dips\n through transient inter-packet minima that recover, so a single\n below-threshold check can false-fire.\n\n * **Closed / PEC boundaries** — domain energy does not decay in a\n lossless closed cavity, so the stop falls back to the historical\n *instantaneous* squared field at the single ``monitor_component`` cell\n (``val_sq < decay_by * peak_sq``). This fallback retains the original\n limitation: it is a valid decay witness only for lossy / radiating\n structures with a clean ring-down envelope, and is **not** suitable\n for flux / S-parameter / transmission gating on guided / low-loss\n closed geometries — for those use a fixed ``n_steps`` via\n :func:`run`.\nreport_every : int or None\n Issue #667. When set, emit one `` [PROGRESS] ...`` line every *N*\n steps, at the first decay-chunk boundary at or past the interval,\n plus a final line at the actual stop step. ``None`` (default) is OFF.\n Reporting never changes the chunks or the decay-check cadence.\n The denominator is ``max_steps``, i.e. a CAP:\n the line marks it ``(cap)`` and the ETA is an upper bound, because a\n decay stop can fire at any check.\nreport_label : str\n Short tag prefixed to each progress line. Ignored when\n ``report_every`` is None.\n\nReturns\n-------\nSimResult", "kind": "function", "name": "rfx.run_until_decay", "parameters": [ { "annotation": "Grid", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" }, { "annotation": "float", "default": "0.001", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_by" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_interval" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "min_steps" }, { "annotation": "int", "default": "50000", "has_default": true, "kind": "KEYWORD_ONLY", "name": "max_steps" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_energy_consecutive" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "radiated_flux_box" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "flux_env_checks" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "monitor_component" }, { "annotation": "tuple[float, float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "monitor_position" }, { "annotation": "str", "default": "'pec'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "boundary" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_axes" }, { "annotation": "tuple[bool, bool, bool] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "periodic" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tfsf" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "_feature_tfsf" }, { "annotation": "list[SourceSpec] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sources" }, { "annotation": "list[ProbeSpec] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probes" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_planes" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "flux_monitors" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveguide_ports" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ntff" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "current_moments" }, { "annotation": "SnapshotSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "snapshot" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_eps" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "aniso_inv_eps_smooth" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_mask" }, { "annotation": "object", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_sheets" }, { "annotation": "object", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_wires" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_edge_masks" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_occupancy" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_weights" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "wire_port_sparams" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lumped_port_sparams" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lumped_rlc" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "kerr_chi3" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_dtype" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_state" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mag_sources" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "stencil_order" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_every" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_label" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sheet_impedance" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "record_dft" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#run_until_decay", "returns": { "annotation": "SimResult" }, "signature": "(grid: 'Grid', materials: 'MaterialArrays', *, decay_by: 'float' = 0.001, check_interval: 'int' = 50, min_steps: 'int' = 100, max_steps: 'int' = 50000, decay_energy_consecutive: 'int' = 2, radiated_flux_box: 'tuple | None' = None, flux_env_checks: 'int' = 4, monitor_component: 'str' = 'ez', monitor_position: 'tuple[float, float, float] | None' = None, boundary: 'str' = 'pec', cpml_axes: 'str | None' = None, pec_axes: 'str | None' = None, periodic: 'tuple[bool, bool, bool] | None' = None, debye: 'tuple | None' = None, lorentz: 'tuple | None' = None, tfsf: 'tuple | None' = None, _feature_tfsf: 'bool' = False, sources: 'list[SourceSpec] | None' = None, probes: 'list[ProbeSpec] | None' = None, dft_planes: 'list | None' = None, flux_monitors: 'list | None' = None, waveguide_ports: 'list | None' = None, ntff: 'object | None' = None, current_moments: 'object | None' = None, snapshot: 'SnapshotSpec | None' = None, checkpoint: 'bool' = False, aniso_eps: 'tuple | None' = None, aniso_inv_eps: 'tuple | None' = None, aniso_inv_eps_smooth: 'bool' = False, pec_mask: 'object | None' = None, pec_sheets: 'object' = (), pec_wires: 'object' = (), pec_edge_masks: 'object | None' = None, pec_occupancy: 'object | None' = None, conformal_weights: 'tuple | None' = None, wire_port_sparams: 'list | None' = None, lumped_port_sparams: 'list | None' = None, lumped_rlc: 'list | None' = None, kerr_chi3: 'jnp.ndarray | None' = None, field_dtype=None, return_state: 'bool' = True, mag_sources: 'list | None' = None, checkpoint_segments: 'int | None' = None, stencil_order: 'int' = 2, report_every: 'int | None' = None, report_label: 'str' = '', sheet_impedance: 'object | None' = None, record_dft: 'bool' = False) -> 'SimResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/simulation.py#L2785", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save standardized experiment metadata as JSON.\n\nAuto-collects: sim config, grid shape, timing, loss history.\n\nParameters\n----------\npath : str or Path\nsim : Simulation\nresult : Result, OptimizeResult, or TopologyResult\nextra : dict or None\n Additional metadata (GPU info, notes, etc.)", "kind": "function", "name": "rfx.save_experiment_report", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "extra" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_experiment_report", "returns": { "annotation": null }, "signature": "(path, sim, result, extra=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L941", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save FarFieldResult to HDF5.\n\nParameters\n----------\npath : str or Path\nff_result : FarFieldResult\nmetadata : dict or None", "kind": "function", "name": "rfx.save_far_field", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ff_result" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "metadata" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_far_field", "returns": { "annotation": null }, "signature": "(path, ff_result, metadata=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L802", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save field animation from simulation snapshots.\n\nParameters\n----------\nresult : rfx.Result or dict\n Simulation result with ``.snapshots`` attribute, or a raw\n snapshots dict mapping component names to arrays of shape\n ``(n_frames, nx, ny, nz)`` or ``(n_frames, nx, ny)``.\nfilename : str\n Output file path. Extension determines format:\n ``.gif`` uses PillowWriter, ``.mp4`` uses FFMpegWriter\n (falls back to GIF if ffmpeg is unavailable).\n If no recognised extension, ``.gif`` is appended.\ncomponent : str\n Field component to animate (default ``\"ez\"``).\nslice_axis : str\n Axis normal to the slice plane (``\"x\"``, ``\"y\"``, or ``\"z\"``).\n Only used when snapshot data is 3D per frame.\nslice_index : int or None\n Index along *slice_axis*. ``None`` selects the centre.\nfps : int\n Frames per second.\ncolormap : str\n Matplotlib colormap name.\nvmin, vmax : float or None\n Colour-scale limits. ``None`` computes symmetric auto-range\n from the data.\ndpi : int\n Resolution in dots per inch.\nfigsize : tuple\n Figure size in inches ``(width, height)``.\ninterval : int\n Frame stride — use every *interval*-th snapshot frame.\n Default 1 (every frame). This is a stride over the RECORDED frames,\n applied after the run, not ``SnapshotSpec.interval`` (which is in\n time steps): a run recorded every 10 steps animated with\n ``interval=3`` shows every 30th step.\n\nReturns\n-------\nstr\n Path to the saved animation file.\n\nRaises\n------\nValueError\n If *result* has no snapshots or the requested *component*\n is missing.\nImportError\n If matplotlib or Pillow are not installed.", "kind": "function", "name": "rfx.save_field_animation", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "filename" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "str", "default": "'z'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "slice_axis" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "slice_index" }, { "annotation": "int", "default": "15", "has_default": true, "kind": "KEYWORD_ONLY", "name": "fps" }, { "annotation": "str", "default": "'RdBu_r'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "colormap" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "vmin" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "vmax" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dpi" }, { "annotation": "tuple", "default": "(6, 5)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "figsize" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "interval" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_field_animation", "returns": { "annotation": null }, "signature": "(result, filename: 'str', *, component: 'str' = 'ez', slice_axis: 'str' = 'z', slice_index: 'int | None' = None, fps: 'int' = 15, colormap: 'str' = 'RdBu_r', vmin: 'float | None' = None, vmax: 'float | None' = None, dpi: 'int' = 100, figsize: 'tuple' = (6, 5), interval: 'int' = 1)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/animation.py#L45", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Export field data to VTK format for ParaView.\n\nParameters\n----------\nstate : FDTDState\ngrid : Grid\nfilename : str\n Output filename (without extension).\ncomponents : tuple of str\n Field components to export.\nscale : float\n Coordinate scale factor.\n\nReturns\n-------\nstr : path to the written file", "kind": "function", "name": "rfx.save_field_vtk", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "filename" }, { "annotation": "tuple[str, ...]", "default": "('ex', 'ey', 'ez', 'hx', 'hy', 'hz')", "has_default": true, "kind": "KEYWORD_ONLY", "name": "components" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_field_vtk", "returns": { "annotation": "str" }, "signature": "(state, grid, filename: 'str', *, components: 'tuple[str, ...]' = ('ex', 'ey', 'ez', 'hx', 'hy', 'hz'), scale: 'float' = 1000.0) -> 'str'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize3d.py#L437", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save material arrays to an HDF5 file.", "kind": "function", "name": "rfx.save_materials", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "MaterialArrays", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "materials" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(path: 'str | Path', materials: 'MaterialArrays') -> 'None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L231", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save OptimizeResult or TopologyResult to HDF5.\n\nParameters\n----------\npath : str or Path\nresult : OptimizeResult or TopologyResult\nmetadata : dict or None\n Extra metadata (grid shape, freq_max, etc.) stored as HDF5 attrs.\ninclude_latent : bool\n Save latent/density arrays (default True).\ninclude_density : bool\n Save projected density and PEC occupancy (default True).\ninclude_history : bool\n Save loss/beta history (default True).", "kind": "function", "name": "rfx.save_optimization_result", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "metadata" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_latent" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_density" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_history" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_optimization_result", "returns": { "annotation": null }, "signature": "(path, result, metadata=None, *, include_latent=True, include_density=True, include_history=True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L735", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save full optimization trajectory for meta-learning / warm-start.\n\nParameters\n----------\npath : str or Path\nhistory_callback_data : list of dict\n Each entry: {\"iter\": int, \"loss\": float, \"eps_design\": ndarray,\n \"s_params\": ndarray (optional)}", "kind": "function", "name": "rfx.save_optimization_trajectory", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "history_callback_data" } ], "reference_url": null, "returns": { "annotation": null }, "signature": "(path, history_callback_data)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L1076", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Write a compact ``.npz`` V/I dump for independent replay.", "kind": "function", "name": "rfx.save_port_vi_dump_npz", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "voltages" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "currents" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "Any", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_impedances" }, { "annotation": "PortDumpMetadata | Mapping[str, Any] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "metadata" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_names" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "driven_port_indices" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "production_smatrix" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_plane_offsets_m" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "propagation_constants" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(path: 'str | Path', *, voltages: 'Any', currents: 'Any', freqs: 'Any', port_impedances: 'Any' = 50.0, metadata: 'PortDumpMetadata | Mapping[str, Any] | None' = None, port_names: 'Any | None' = None, driven_port_indices: 'Any | None' = None, production_smatrix: 'Any | None' = None, reference_plane_offsets_m: 'Any | None' = None, propagation_constants: 'Any | None' = None) -> 'None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L772", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save a 3D screenshot of geometry (and optionally field).\n\nParameters\n----------\nsim : Simulation\nstate : FDTDState or None\n If provided, overlays field slices on geometry.\nfilename : str\n Output filename (without extension).\ncomponent : field component for overlay\ndpi : image resolution\nfigsize : figure size\nscale : coordinate scale\n\nReturns\n-------\nstr : path to saved image", "kind": "function", "name": "rfx.save_screenshot", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "str", "default": "'rfx_3d'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "filename" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "int", "default": "150", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dpi" }, { "annotation": "tuple[float, float]", "default": "(10, 8)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "figsize" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scale" } ], "reference_url": null, "returns": { "annotation": "str" }, "signature": "(sim, state=None, filename: 'str' = 'rfx_3d', *, component: 'str' = 'ez', dpi: 'int' = 150, figsize: 'tuple[float, float]' = (10, 8), scale: 'float' = 1000.0) -> 'str'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/visualize3d.py#L630", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save simulation input-output pair for surrogate model training.\n\nCreates an HDF5 file with selectable sections:\n- Input: simulation config and grid metadata\n- Output: time series, S-parameters\n- Fields: final 3D E/H snapshot (large, opt-in)\n\nParameters\n----------\npath : str or Path\nsim : Simulation\nresult : Result\ninclude_fields : bool\n Save full 3D E/H field arrays (default False — large).\ninclude_time_series : bool\n Save probe time series (default True).\ninclude_s_params : bool\n Save S-parameters and frequencies (default True).\ninclude_config : bool\n Save simulation config as input metadata (default True).", "kind": "function", "name": "rfx.save_simulation_dataset", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": null, "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_fields" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_time_series" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_s_params" }, { "annotation": null, "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_config" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_simulation_dataset", "returns": { "annotation": null }, "signature": "(path, sim, result, *, include_fields=False, include_time_series=True, include_s_params=True, include_config=True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L1006", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save field snapshots to an HDF5 file.\n\nParameters\n----------\npath : str or Path\nsnapshots : dict mapping component name to (n_frames, ...) array\ngrid : Grid or None\ndt : float or None\n Timestep for time-axis metadata. Also writes the attribute\n ``n_steps``, which (its historical name notwithstanding) is the\n number of FRAMES in the first array, and ``n_frames``, the same\n number under its right name.\naxes : dict[str, SnapshotAxes] or None\n ``Result.snapshot_axes`` (#1259). Stored per component under\n ``axes/`` -- the sample coordinates, the slice plane and\n the step count and time of every frame -- and returned by\n :func:`load_snapshots` as ``metadata[\"axes\"]``.", "kind": "function", "name": "rfx.save_snapshots", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "dict[str, jnp.ndarray]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshots" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "axes" } ], "reference_url": null, "returns": { "annotation": "None" }, "signature": "(path: 'str | Path', snapshots: 'dict[str, jnp.ndarray]', grid=None, dt: 'float | None' = None, axes: 'dict | None' = None) -> 'None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L98", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Save FDTD state to an HDF5 file.\n\nParameters\n----------\npath : str or Path\n Output file path (.h5).\nstate : FDTDState\n Field state to save.\ngrid : Grid or None\n If provided, grid metadata is stored as attributes.", "kind": "function", "name": "rfx.save_state", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "FDTDState", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#save_state", "returns": { "annotation": "None" }, "signature": "(path: 'str | Path', state: 'FDTDState', grid=None) -> 'None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/checkpoint.py#L33", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Select the best feasible point by one primary objective.\n\nReturns ``None`` when no point satisfies the epsilon constraints.", "kind": "function", "name": "rfx.select_epsilon_constrained", "parameters": [ { "annotation": "Sequence[Sequence[float]] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "primary_index" }, { "annotation": "Mapping[int, float]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "epsilons" }, { "annotation": "bool | Sequence[bool]", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "minimize" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "atol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#select_epsilon_constrained", "returns": { "annotation": "int | None" }, "signature": "(objectives: 'Sequence[Sequence[float]] | np.ndarray', *, primary_index: 'int', epsilons: 'Mapping[int, float]', minimize: 'bool | Sequence[bool]' = True, atol: 'float' = 0.0) -> 'int | None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L292", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Insert geometric transition cells where adjacent ratio exceeds max_ratio.\n\nPrevents numerical reflections at abrupt cell-size transitions in\nnon-uniform meshes. Inspired by OpenEMS SmoothMeshLines.\n\nParameters\n----------\ncells : array-like\n Cell sizes along the graded axis.\nmax_ratio : float\n Maximum allowed ratio between adjacent cells (default 1.3).\n Values 1.2-1.4 are typical for FDTD.\npreserve_regions : list of (start, end) index pairs, optional\n Input-index ranges (half-open) whose cell sizes must remain\n unchanged. Transition cells are inserted **outside** each\n preserved block. This is the canonical Meep/OpenEMS convention\n for thin PEC on a NU mesh — metal planes must land on cell\n boundaries with symmetric neighbouring cells, which is only\n guaranteed if the fine substrate block is preserved intact.\n\nReturns\n-------\nnp.ndarray\n Smoothed cell array with transition cells inserted.", "kind": "function", "name": "rfx.smooth_grading", "parameters": [ { "annotation": "list[float] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cells" }, { "annotation": "float", "default": "1.3", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "max_ratio" }, { "annotation": "list[tuple[int, int]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "preserve_regions" } ], "reference_url": null, "returns": { "annotation": "np.ndarray" }, "signature": "(cells: 'list[float] | np.ndarray', max_ratio: 'float' = 1.3, *, preserve_regions: 'list[tuple[int, int]] | None' = None) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/auto_config.py#L959", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Positions and times of the frames a run with ``snapshot`` records.\n\nNeeds no run: ``grid`` is the uniform grid the run steps on\n(``sim._build_grid()``, or ``result.grid`` afterwards), ``snapshot`` the\n``SnapshotSpec`` and ``n_steps`` the number of time steps. ``dt`` is the\nrun's time step; it defaults to ``grid.dt``, which is the step of every\nuniform run except ``stencil_order=4`` (whose step is derated, and whose\n``Result.snapshot_axes`` carries the real one). Returns\n``{component: SnapshotAxes}``; a run returns the same thing in\n``Result.snapshot_axes``.\n\nA ``SnapshotSpec`` with ``slice_axis`` set and ``slice_index=None``\nrecords the full field, as it always has; its axes say so\n(``slice_axis is None``).", "kind": "function", "name": "rfx.snapshot_axes", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "snapshot" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dt" } ], "reference_url": null, "returns": { "annotation": "dict[str, SnapshotAxes]" }, "signature": "(grid, snapshot, n_steps: 'int', *, dt: 'float | None' = None) -> 'dict[str, SnapshotAxes]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/snapshots.py#L230", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute TE and TM modes for a rectangular waveguide.\n\nEnumerates analytical modes sorted by cutoff frequency and returns the\nlowest ``n_modes`` that have cutoff below ``freq_max``.\n\nParameters\n----------\na, b : float\n Waveguide cross-section dimensions (metres). By convention ``a >= b``.\nfreq_max : float\n Maximum frequency in Hz. Only modes with cutoff below this value\n are included.\nn_modes : int\n Maximum number of modes to return.\n\nReturns\n-------\nlist of dict\n Each dict has keys: ``mode_type`` (``\"TE\"`` or ``\"TM\"``), ``m``, ``n``,\n ``f_cutoff``.", "kind": "function", "name": "rfx.solve_rectangular_modes", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "a" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "b" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_max" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_modes" } ], "reference_url": null, "returns": { "annotation": "list[dict]" }, "signature": "(a: 'float', b: 'float', freq_max: 'float', n_modes: 'int' = 3) -> 'list[dict]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L2662", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Solve for the lowest eigenmodes of a rectangular waveguide cross-section.\n\nParameters\n----------\na : float\n Waveguide width (metres), along the first transverse axis.\nb : float\n Waveguide height (metres), along the second transverse axis.\ndx : float\n Cell size (metres).\nfreqs : array_like, shape (n_freqs,)\n Frequency points at which to evaluate the propagation constant.\nn_modes : int\n Number of lowest-cutoff modes to return.\neps_cross : ndarray, shape (ny, nz), optional\n Relative permittivity on the cross-section grid. ``None`` means\n uniform vacuum (eps_r = 1).\nmu_cross : ndarray, shape (ny, nz), optional\n Relative permeability on the cross-section grid. ``None`` means\n uniform (mu_r = 1).\n\nReturns\n-------\nmodes : list[WaveguideMode]\n The ``n_modes`` lowest-cutoff eigenmodes, sorted by cutoff frequency.", "kind": "function", "name": "rfx.solve_waveguide_modes", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "a" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "b" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_modes" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "eps_cross" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "mu_cross" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#solve_waveguide_modes", "returns": { "annotation": "list[WaveguideMode]" }, "signature": "(a: 'float', b: 'float', dx: 'float', freqs: 'np.ndarray', n_modes: 'int' = 1, eps_cross: 'np.ndarray | None' = None, mu_cross: 'np.ndarray | None' = None) -> 'list[WaveguideMode]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/eigenmode.py#L593", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Weighted MSE loss between simulated and measured S-parameters.\n\nParameters\n----------\ns_sim, s_meas : (..., n_freqs) complex arrays\n S-parameter arrays (any leading shape, typically (n_ports, n_ports, n_freqs)).\nweight_mag : float\n Weight on magnitude error.\nweight_phase : float\n Weight on phase error (wrapped to [-pi, pi]).\n\nReturns\n-------\nScalar loss value.", "kind": "function", "name": "rfx.sparam_loss", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_sim" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_meas" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "weight_mag" }, { "annotation": "float", "default": "0.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "weight_phase" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#sparam_loss", "returns": { "annotation": "jnp.ndarray" }, "signature": "(s_sim: 'jnp.ndarray', s_meas: 'jnp.ndarray', *, weight_mag: 'float' = 1.0, weight_phase: 'float' = 0.1) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/differentiable_material_fit.py#L187", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Steer radiation toward *target_probe_idx* and away from *suppress_probe_idx*.\n\nUses a near-field probe array as a differentiable surrogate for\nfar-field beam steering. Place probes at different spatial positions\naround the antenna (e.g., above-left and above-right), then this\nobjective maximizes the power ratio between target and suppressed\nprobe.\n\nThis avoids NTFF DFT entirely and works reliably in float32.\n\nSetup example::\n\n # Probes at different angles in the near field\n sim.add_probe((x_center - 0.02, y_center, z_above), \"ez\") # probe 0: left\n sim.add_probe((x_center + 0.02, y_center, z_above), \"ez\") # probe 1: right\n\n # Steer toward probe 1 (right), suppress probe 0 (left)\n obj = steer_probe_array(target_probe_idx=1, suppress_probe_idx=0)\n\nParameters\n----------\ntarget_probe_idx : int\n Column index in ``result.time_series`` to maximize.\nsuppress_probe_idx : int\n Column index to suppress (default 0).\nlate_fraction : float\n Fraction of time series to use (late portion, after source decays).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.steer_probe_array", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "target_probe_idx" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "suppress_probe_idx" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "late_fraction" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#steer_probe_array", "returns": { "annotation": "Callable" }, "signature": "(target_probe_idx: 'int', suppress_probe_idx: 'int' = 0, *, late_fraction: 'float' = 0.5) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L581", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Remove a reference (incident) field from a flux monitor, field-level.\n\nThe two-run reference subtraction of\n``docs/agent/recipe-rt-measurement.mdx`` (critical detail (a)): pass the\nmonitor from the run WITH the scatterer and the monitor from the otherwise\nidentical run WITHOUT it, and call :func:`flux_spectrum` on the result to\nget the scattered flux.\n\nParameters\n----------\nsample : FluxMonitor\n Monitor from the run with the scatterer present.\nref : FluxMonitor\n Monitor from the reference run — same plane, same frequencies.\n\nReturns\n-------\nFluxMonitor\n ``sample`` with each of the four tangential DFT accumulators replaced\n by ``sample. - ref.``. Every other field (``freqs``,\n ``axis``, ``index``, ``dA``, ``total_steps``, ``window``,\n ``window_alpha``, ``lo1``/``hi1``/``lo2``/``hi2``) is carried over\n from ``sample`` unchanged.\n\nRaises\n------\nTypeError\n If either argument is not a ``FluxMonitor``.\nValueError\n If the four accumulators disagree in shape, or if any non-accumulator\n field differs. Nothing is broadcast: two monitors that do not describe\n the same plane and the same frequencies have no meaningful difference,\n and a silent broadcast would return a plausible-looking number instead\n of an error.\n\nNotes\n-----\nThe subtraction has to happen on the FIELDS, never on the fluxes. Poynting\nflux is bilinear in E and H, so writing the sample fields as incident plus\nscattered (``E_s = E_i + E_r``, ``H_s = H_i + H_r``) gives\n\n ``flux(sample) - flux(ref) = flux(scattered)\n + Re(E_i x H_r* + E_r x H_i*) dA``\n\nand those cross terms are the same order as the scattered flux itself —\nthey vanish only for a null scatterer. Maxwell's equations are linear, so\ndifferencing the accumulators first and forming the Poynting product\nafterwards is exact. ``flux_spectrum(sample) - flux_spectrum(ref)`` is not\nan approximation of this; it is a different quantity.\n\nTracer-safe: the subtraction is plain array arithmetic and stays on the AD\ntape, so ``jax.grad`` through\n``flux_spectrum(subtract_flux_monitors(...))`` works. Shape checks run on\ntracers too; the equality check on array-valued metadata is undecidable\nunder ``jit``/``grad`` and is skipped there.", "kind": "function", "name": "rfx.subtract_flux_monitors", "parameters": [ { "annotation": "FluxMonitor", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sample" }, { "annotation": "FluxMonitor", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "ref" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#subtract_flux_monitors", "returns": { "annotation": "FluxMonitor" }, "signature": "(sample: 'FluxMonitor', ref: 'FluxMonitor') -> 'FluxMonitor'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L990", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Suggest ``Box`` regions for SBP-SAT refinement based on error map.\n\nIdentifies connected regions where the error indicator exceeds\n*threshold* and returns axis-aligned bounding boxes for each region\nthat is at least *min_region_size* cells in every used dimension.\n\nParameters\n----------\nerror_map : ndarray, shape (Nx, Ny, Nz)\n Normalized error indicator (output of ``compute_error_indicator``).\ngrid : Grid or None\n If provided, box corners are in physical (metre) coordinates.\n Otherwise they are in cell-index coordinates.\nthreshold : float\n Cells with ``error_map > threshold`` are flagged (default 0.5).\nmin_region_size : int\n Minimum bounding-box extent in cells per axis to keep a region\n (default 4). Smaller regions are discarded as noise.\n\nReturns\n-------\nlist of Box\n Suggested refinement bounding boxes.", "kind": "function", "name": "rfx.suggest_refinement_regions", "parameters": [ { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "error_map" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "grid" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "threshold" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "min_region_size" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#suggest_refinement_regions", "returns": { "annotation": "list[Box]" }, "signature": "(error_map: 'np.ndarray', *, grid=None, threshold: 'float' = 0.5, min_region_size: 'int' = 4) -> 'list[Box]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/amr.py#L77", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return an inspectable status summary for a batch manifest.\n\n``manifest_or_path`` may be a manifest dictionary or a path to a manifest\nJSON file. The returned summary is detached from the input so callers can\nuse it for reports without mutating the manifest.", "kind": "function", "name": "rfx.summarize_batch_manifest", "parameters": [ { "annotation": "dict[str, Any] | str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "manifest_or_path" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#summarize_batch_manifest", "returns": { "annotation": "dict[str, Any]" }, "signature": "(manifest_or_path: 'dict[str, Any] | str | Path') -> 'dict[str, Any]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/batch.py#L175", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Minimize |Z_in − z_target|² at a specific frequency.\n\nComputes input impedance from S11: ``Z_in = Z0 * (1 + S11) / (1 − S11)``\nwhere Z0 = 50 Ω (standard reference impedance).\n\nParameters\n----------\nfreq : float\n Target frequency (Hz).\nz_target : float\n Desired input impedance (Ω).\n\nReturns\n-------\ncallable(Result) -> scalar (JAX-differentiable)", "kind": "function", "name": "rfx.target_impedance", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_target" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#target_impedance", "returns": { "annotation": "Callable" }, "signature": "(freq: 'float', z_target: 'float' = 50.0) -> 'Callable'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/optimize_objectives.py#L170", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Solve tridiagonal system A x = d using the Thomas algorithm.\n\nA has sub-diagonal *a*, main diagonal *b*, and super-diagonal *c*.\nAll inputs are 1-D arrays of length N. a[0] and c[N-1] are ignored.\n\nThe entire forward-elimination and back-substitution are expressed\nas ``jax.lax.scan`` so the function is JIT-compilable and\ndifferentiable (reverse-mode AD through the scan).\n\nParameters\n----------\na, b, c, d : (N,) float arrays\n Tridiagonal system coefficients and right-hand side.\n\nReturns\n-------\nx : (N,) float array\n Solution vector.", "kind": "function", "name": "rfx.thomas_solve", "parameters": [ { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "a" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "b" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "c" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "d" } ], "reference_url": null, "returns": { "annotation": "jnp.ndarray" }, "signature": "(a: 'jnp.ndarray', b: 'jnp.ndarray', c: 'jnp.ndarray', d: 'jnp.ndarray') -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/adi.py#L145", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run density-based topology optimization.\n\nOptimizes a continuous density field within the design region to\nminimize an objective function, using gradient information from\n``jax.value_and_grad`` through the full FDTD pipeline.\n\nUses ``optax.adam`` for the optimizer.\n\nParameters\n----------\nsim : Simulation\n Base simulation (the design region overrides eps_r in its box).\ndesign_region : TopologyDesignRegion\n Region and material specification.\nobjective : callable(Result) -> scalar\n Objective function to minimize. Must be JAX-differentiable\n through the simulation.\nn_iterations : int\n Number of optimization iterations.\nlearning_rate : float\n Learning rate for Adam optimizer.\nbeta_schedule : list of (iteration, beta) or None\n Schedule for increasing projection sharpness.\n Default: [(0, 1), (30, 4), (60, 16), (80, 64)]\ninit_density : array or None\n Initial density field. If None, initialized to 0.5 everywhere\n (uniform mixture of bg and fg materials).\nverbose : bool\n Print progress every 10 iterations.\n\nReturns\n-------\nTopologyResult\n Contains final density, permittivity, loss history, and beta history.", "kind": "function", "name": "rfx.topology_optimize", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "TopologyDesignRegion", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "design_region" }, { "annotation": "Callable", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objective" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_iterations" }, { "annotation": "float", "default": "0.01", "has_default": true, "kind": "KEYWORD_ONLY", "name": "learning_rate" }, { "annotation": "list[tuple[int, float]] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "beta_schedule" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "init_density" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "verbose" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#topology_optimize", "returns": { "annotation": "TopologyResult" }, "signature": "(sim, design_region: 'TopologyDesignRegion', objective: 'Callable', *, n_iterations: 'int' = 100, learning_rate: 'float' = 0.01, beta_schedule: 'list[tuple[int, float]] | None' = None, init_density: 'jnp.ndarray | None' = None, verbose: 'bool' = True, skip_preflight: 'bool' = False) -> 'TopologyResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/topology.py#L347", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Accumulate one timestep into the Floquet DFT.\n\nExtracts tangential fields at the port plane and applies running\nDFT at each frequency point.\n\nParameters\n----------\nacc : FloquetDFTAccumulator\n Current accumulator state.\nstate : FDTDState\n Current FDTD field state.\nport_index : int\n Grid index along the port normal axis.\naxis : int\n Normal axis (0=x, 1=y, 2=z).\nfreqs : (n_freqs,) array\n Frequencies for DFT.\ndt : float\n Timestep.\nstep : int\n Current timestep index.", "kind": "function", "name": "rfx.update_floquet_dft", "parameters": [ { "annotation": "FloquetDFTAccumulator", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "acc" }, { "annotation": "FDTDState", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port_index" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "axis" }, { "annotation": "jnp.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "step" } ], "reference_url": null, "returns": { "annotation": "FloquetDFTAccumulator" }, "signature": "(acc: 'FloquetDFTAccumulator', state: 'FDTDState', port_index: 'int', axis: 'int', freqs: 'jnp.ndarray', dt: 'float', step: 'int') -> 'FloquetDFTAccumulator'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/floquet.py#L223", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Accumulate one timestep of E and H tangential fields.", "kind": "function", "name": "rfx.update_flux_monitor", "parameters": [ { "annotation": "FluxMonitor", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "mon" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" } ], "reference_url": null, "returns": { "annotation": "FluxMonitor" }, "signature": "(mon: 'FluxMonitor', state, dt: 'float') -> 'FluxMonitor'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L820", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "", "kind": "function", "name": "rfx.update_waveguide_port_probe", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dx" } ], "reference_url": null, "returns": { "annotation": "WaveguidePortConfig" }, "signature": "(cfg: 'WaveguidePortConfig', state, dt: 'float', dx: 'float') -> 'WaveguidePortConfig'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1409", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Accumulate one timestep of V, I, V_inc, and V_port for a WirePort.\n\nCall this every timestep after update_e() / apply_pec() AND **after**\napply_wire_port() (issue #683, decided by measurement 2026-08-29):\nthe post-injection E is the true field level ``E^{n+1}`` of the\ndiscrete update, and only the post-injection V/I pair satisfies the\nknown-load circuit law at an excited port. The LUMPED family kept the\nearlier contract — sample before injection, issue #72 — until its own\nknown-load decision run\n(scripts/diagnostics/lumped_port_known_load_line.py, 2026-09-21)\nmeasured the same verdict there; ``update_sparam_probe`` samples in\nthis slot now too. The PRE-injection drive-sample\nreference channel is accumulated separately by\n``update_wire_drive_ref_probe`` (call it BEFORE apply_wire_port) —\nthe #308/#313 off-diagonal calibration is pinned against that sample\n(see ``decompose_wire_s_matrix`` and\ndocs/design_notes/issue683_decomposer_flip_predeclaration.md).\n\nV and I are measured at the LIVE-run midpoint cell; V_port is the\nwhole-gap sum over live cells (issue #764). V_inc uses the per-cell\nsource voltage (V_src / n_live, matching ``apply_wire_port``'s\nlive-cell injection — issue #318; ``n_live=None`` falls back to the\nall-cells count, the historical behaviour and the degenerate\nno-dead-cells case).", "kind": "function", "name": "rfx.update_wire_sparam_probe", "parameters": [ { "annotation": "SParamProbe", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "probe" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "dt" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_live" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": null, "returns": { "annotation": "SParamProbe" }, "signature": "(probe: 'SParamProbe', state, grid, port, dt: 'float', n_live: 'int | None' = None, pec_edge_masks=None) -> 'SParamProbe'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L1204", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return validation errors for an artifact report.\n\nThe validator is intentionally lightweight and dependency-free; callers can\ntreat any returned message as a report failure.", "kind": "function", "name": "rfx.validate_artifact_report", "parameters": [ { "annotation": "dict[str, Any]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "report" }, { "annotation": "str | Path | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bundle_root" } ], "reference_url": null, "returns": { "annotation": "list[str]" }, "signature": "(report: 'dict[str, Any]', *, bundle_root: 'str | Path | None' = None) -> 'list[str]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/artifacts.py#L756", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Validate schema and selected invariants for an RF port observable.\n\nThresholds are caller-controlled. Defaults are intentionally strict for\nsynthetic/unit checks; integration tests may pass looser tolerances that\nmatch their validated physics envelope.", "kind": "function", "name": "rfx.validate_port_smatrix", "parameters": [ { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "obj" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s_params" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "Any | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_names" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "source" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_passivity" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "passivity_limit" }, { "annotation": "float", "default": "1e-09", "has_default": true, "kind": "KEYWORD_ONLY", "name": "passivity_tol" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_reciprocity" }, { "annotation": "float", "default": "1e-09", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reciprocity_atol" }, { "annotation": "float", "default": "1e-06", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reciprocity_rtol" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "require_positive_freqs" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "require_strictly_increasing_freqs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#validate_port_smatrix", "returns": { "annotation": "PortValidationReport" }, "signature": "(obj: 'Any | None' = None, *, s_params: 'Any | None' = None, freqs: 'Any | None' = None, port_names: 'Any | None' = None, source: 'str | None' = None, check_passivity: 'bool' = True, passivity_limit: 'float' = 1.0, passivity_tol: 'float' = 1e-09, check_reciprocity: 'bool' = False, reciprocity_atol: 'float' = 1e-09, reciprocity_rtol: 'float' = 1e-06, require_positive_freqs: 'bool' = True, require_strictly_increasing_freqs: 'bool' = True) -> 'PortValidationReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/validation.py#L341", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Batch-evaluate multiple material parameter values using ``jax.vmap``.\n\nOnly works for material parameters (``eps_r``, ``sigma``, ``mu_r``)\nwhere the grid shape stays constant. For geometry sweeps, use\n``parametric_sweep()``.\n\nParameters\n----------\nsim : Simulation\n Base simulation (all geometry already added).\nparam_name : str\n Material parameter to sweep: ``\"eps_r\"``, ``\"sigma\"``, ``\"mu_r\"``,\n or a material-specific name like ``\"substrate.eps_r\"``.\nparam_values : array-like, shape (n_batch,)\n Values to evaluate.\nn_steps : int or None\n Timesteps. If None, auto-computed from *num_periods*.\nnum_periods : float\n Periods at freq_max for auto timestep count (default 20).\nreturn_fields : bool\n Must be False (the default). ``return_fields=True`` was documented\n here since this function's introduction but never implemented —\n neither the fast path nor the sequential fallback ever populated\n ``VmapSweepResult.final_fields``, so it silently returned ``None``\n instead of the promised snapshot. Passing ``True`` now raises\n ``ValueError`` (fail loud beats silent ``None``, #578). Use\n ``sim.run()``/``sim.forward()`` for a final-field snapshot of one\n configuration, or ``parametric_sweep()`` for full per-value\n ``Result`` objects across a swept parameter.\n\nReturns\n-------\nVmapSweepResult\n Result with ``.time_series`` of shape\n ``(n_batch, n_steps, n_probes)``, ``.dft_planes`` (dict of\n ``(n_batch, n_freqs, n1, n2)`` complex arrays keyed by\n ``add_dft_plane_probe`` name, or ``None`` if no plane was\n registered), and ``.param_values``.\n\nNotes\n-----\nThe entire FDTD time loop is vmapped so all simulations execute in a\nsingle fused GPU kernel. Memory scales as\n``n_batch * grid_size + n_batch * sum(n_freqs_p * n1_p * n2_p for each\nregistered DFT plane p)`` (complex accumulators; no remat on this\npath). For large grids/plane counts, reduce batch size or plane\nfrequency count to avoid OOM.\n\nFeatures supported in vmap path: PEC boundaries, CPML absorbing\nboundaries, soft sources (incl. ``amplitude_kind='current'``, #571),\npoint probes, and DFT plane probes (``add_dft_plane_probe``, #578).\nLumped ports, MSL/coaxial/floquet ports, TFSF, dispersion, waveguide\nports, flux monitors, and NTFF are **not** supported in the vmap fast\npath and trigger a sequential fallback. As of #578 that fallback also\npopulates ``.dft_planes`` (by stacking each swept value's\n``Result.dft_planes`` accumulators), so registering a DFT plane never\nsilently loses data on either path — it is only the FAST path that is\nconditional on eligibility, not the DFT-plane *output*.\n\nTFSF sweeps — angle batching is intentionally out of scope, not just\nunimplemented: it is a structural mismatch with this function's\nmaterial-only batching model, not a missing feature. The TFSF incident\nfield is itself an auxiliary FDTD solution advanced *inside* the scan\n(not closed-form); Method B's auxiliary-grid size is angle-dependent\n(a batch of angles would need a batch of scan shapes, which\n``jax.vmap`` cannot express); and the oblique 2D-aux Bloch path\nconcretizes its transverse phase factors from ``angle_deg`` at trace\ntime (rfx/sources/tfsf_2d.py). More basically, rfx cannot even\n*express* a general incidence triple ``(theta, phi, psi)`` today — only\n``angle_deg`` + a binary ``direction`` + a two-way ``polarization``\nchoice — so there is no batchable angle parameter to expose in the\nfirst place. Route illumination/angle sweeps to ``parametric_sweep()``\ninstead: it already returns full ``Result`` objects including\n``dft_planes`` for each swept value. Caveat there too: oblique-Bloch\nTFSF (``angle_deg != 0``, ``method='bloch'``, the default) combined\nwith DFT planes/flux monitors/NTFF raises ``NotImplementedError`` by\ndesign (rfx/simulation.py:728-745) because the accumulated envelope is\nnot the physical spectrum — DFT-plane tensors from a TFSF-illuminated\n``parametric_sweep`` are obtainable only at normal incidence\n(``angle_deg=0``) or with ``method='methodB'`` (open-domain, real\nfields). A MATERIAL sweep on a sim carrying a FIXED (non-swept) TFSF\nsource still benefits from #578: it takes this function's sequential\nfallback (TFSF is not fast-path-eligible) but that fallback now\ncarries ``dft_planes`` through, so per-material DFT tensors at fixed\nincidence ARE obtainable via ``vmap_material_sweep`` today.\n\nPoint-frequency-domain probes are not a separate case here: rfx has no\npublic builder for a point DFT probe (only plane DFT probes and flux\nmonitors), and point *time series* — the actual point-probe primitive\n— are already fully batched via ``add_probe`` + ``.time_series`` on\nboth paths.", "kind": "function", "name": "rfx.vmap_material_sweep", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "sim" }, { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_name" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "param_values" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_fields" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#vmap_material_sweep", "returns": { "annotation": "VmapSweepResult" }, "signature": "(sim, param_name: 'str', param_values, *, n_steps: 'int | None' = None, num_periods: 'float' = 20.0, return_fields: 'bool' = False) -> 'VmapSweepResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/vmap_sweep.py#L847", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Physical source/reference/probe positions along the port normal axis.\n\nWhen `cfg` comes from `rfx.api.Simulation`, these are domain-relative\nphysical coordinates along the active port-normal axis. For lower-level\nmanual setups without `x_position`,\nthey fall back to the padded-grid coordinate origin.", "kind": "function", "name": "rfx.waveguide_plane_positions", "parameters": [ { "annotation": "WaveguidePortConfig", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "cfg" } ], "reference_url": null, "returns": { "annotation": "dict[str, float]" }, "signature": "(cfg: 'WaveguidePortConfig') -> 'dict[str, float]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sources/waveguide_port.py#L1587", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return lower-is-better weighted scalarization scores.\n\nMaximization objectives are sign-flipped before scoring. When ``normalize``\nis true, each oriented objective is min-max normalized; constant objectives\ncontribute zero after normalization.", "kind": "function", "name": "rfx.weighted_scalarization", "parameters": [ { "annotation": "Sequence[Sequence[float]] | np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "objectives" }, { "annotation": "Sequence[float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "weights" }, { "annotation": "bool | Sequence[bool]", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "minimize" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "normalize" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#weighted_scalarization", "returns": { "annotation": "np.ndarray" }, "signature": "(objectives: 'Sequence[Sequence[float]] | np.ndarray', weights: 'Sequence[float]', *, minimize: 'bool | Sequence[bool]' = True, normalize: 'bool' = False) -> 'np.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/pareto.py#L224", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Current through a WirePort via Ampere's law at the LIVE-run midpoint.\n\nUses the H-field loop integral at the center cell of the LIVE wire run\n(issue #764; with no dead cells this is the historical all-extent\nmidpoint), the same :func:`_ampere_loop` :func:`port_current` uses.\nOut-of-domain H is ZERO (#692) — see :func:`_bwd_h` for the rule and\nfor the two axis kinds that keep the wrap.\n\nParameters\n----------\nstate : FDTDState\ngrid : Grid\nport : WirePort\nperiodic : (bool, bool, bool)\n Per-axis periodic flags for the run; default non-periodic.\npec_edge_masks : realized PEC edge masks (Mx, My, Mz) for the #318 live split\n\nReturns\n-------\nfloat scalar", "kind": "function", "name": "rfx.wire_port_current", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": null, "default": "(False, False, False)", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "periodic" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#wire_port_current", "returns": { "annotation": "jnp.ndarray" }, "signature": "(state, grid, port, periodic=(False, False, False), pec_edge_masks=None) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L1140", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Voltage at the WirePort LIVE-run midpoint cell.\n\nUses a single-cell measurement at the live-run midpoint (same location\nas wire_port_current) for balanced V/I wave decomposition. The midpoint\nis that of the LIVE run (issue #764; ``pec_edge_masks=None`` or no dead cells\nis bit-identical to the historical all-extent midpoint).\n\nParameters\n----------\nstate : FDTDState\ngrid : Grid\nport : WirePort\npec_edge_masks : realized PEC edge masks (Mx, My, Mz) for the #318 live split\n\nReturns\n-------\nfloat scalar", "kind": "function", "name": "rfx.wire_port_voltage", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "state" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "port" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "pec_edge_masks" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#wire_port_voltage", "returns": { "annotation": "jnp.ndarray" }, "signature": "(state, grid, port, pec_edge_masks=None) -> 'jnp.ndarray'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/probes/probes.py#L1100", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Write S-parameters to a Touchstone file.\n\nParameters\n----------\nfilepath : str or Path\n Output file (extension determines port count: .s1p, .s2p, etc.)\ns_params : (n_ports, n_ports, n_freqs) complex array\nfreqs : (n_freqs,) float in Hz\nz0 : reference impedance (ohm)\nfreq_unit : \"Hz\", \"kHz\", \"MHz\", or \"GHz\"\nfmt : \"RI\" (real/imag), \"MA\" (mag/angle), or \"DB\" (dB/angle)\ncomments : optional comment lines\nversion : \"1.0\" or \"2.0\"\n ``\"1.0\"`` preserves the historical rfx writer shape. ``\"2.0\"``\n writes Touchstone 2.0 metadata keywords for the supported S-parameter\n subset.\nlayout : \"legacy-rfx\", \"standard\", or None\n Multi-port order. ``None`` means standard layout for both\n Touchstone 1.0 and 2.0 output.\n The legacy rfx layout is column-major for all port counts. The\n standard layout is row-major for 3+ ports. Two-port standard order is\n controlled by ``two_port_order``.\nport_z0 : array-like or None\n Optional per-port reference impedances. Requires ``version=\"2.0\"``\n when non-uniform.\nmatrix_format : str\n Touchstone 2.0 matrix format. Only ``\"Full\"`` is supported.\ntwo_port_order : \"21_12\" or \"12_21\"\n Explicit 2-port data order for standard Touchstone 2.0 files.\ninformation : dict, list, tuple, or None\n Optional Touchstone 2.0 information block. Dicts are written as\n sorted ``\"key value\"`` lines; sequences are written verbatim.", "kind": "function", "name": "rfx.write_touchstone", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "filepath" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "s_params" }, { "annotation": "np.ndarray", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "z0" }, { "annotation": "str", "default": "'GHz'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freq_unit" }, { "annotation": "str", "default": "'RI'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "fmt" }, { "annotation": "list[str] | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "comments" }, { "annotation": "str", "default": "'1.0'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "version" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "layout" }, { "annotation": "np.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_z0" }, { "annotation": "str", "default": "'Full'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "matrix_format" }, { "annotation": "str", "default": "'21_12'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "two_port_order" }, { "annotation": "dict[str, object] | list[str] | tuple[str, ...] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "information" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#write_touchstone", "returns": { "annotation": "None" }, "signature": "(filepath: 'str | Path', s_params: 'np.ndarray', freqs: 'np.ndarray', z0: 'float' = 50.0, freq_unit: 'str' = 'GHz', fmt: 'str' = 'RI', comments: 'list[str] | None' = None, *, version: 'str' = '1.0', layout: 'str | None' = None, port_z0: 'np.ndarray | None' = None, matrix_format: 'str' = 'Full', two_port_order: 'str' = '21_12', information: 'dict[str, object] | list[str] | tuple[str, ...] | None' = None) -> 'None'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/io.py#L202", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a fail-closed compiler-memory certificate for one executable.\n\nThis method accepts an already-compiled JAX object and reads only its\n``memory_analysis()`` output. It does not compile callables, run FDTD,\nprofile runtime memory, or convert static memory plans into guarantees.\nGreen statuses are bounded to the supplied compiled object and complete\nexact-scope metadata.", "kind": "method", "name": "rfx.Simulation.ad_memory_compiled_certificate", "parameters": [ { "annotation": "object", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "compiled" }, { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "float", "default": "0.85", "has_default": true, "kind": "KEYWORD_ONLY", "name": "target_fraction" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "precision" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "input_signature" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "static_signature" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "compiled_object_id" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "runner_or_objective" }, { "annotation": "ADMemoryPreflightReport | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "preflight" }, { "annotation": "Mapping[str, object] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scope_context" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.ad_memory_compiled_certificate", "returns": { "annotation": "ADCompiledMemoryCertificate" }, "signature": "(self, compiled: 'object', *, n_steps: 'int', available_memory_gb: 'float', target_fraction: 'float' = 0.85, checkpoint_every: 'int | None' = None, checkpoint_segments: 'int | None' = None, n_warmup: 'int' = 0, precision: 'str | None' = None, input_signature: 'object | None' = None, static_signature: 'object | None' = None, compiled_object_id: 'str | None' = None, runner_or_objective: 'str | None' = None, preflight: 'ADMemoryPreflightReport | None' = None, scope_context: 'Mapping[str, object] | None' = None) -> 'ADCompiledMemoryCertificate'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_ad_memory.py#L1079", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a one-call AD-memory preflight planning artifact.\n\nThe report composes existing static memory planning, static\nexplainability, optional mesh advisories, and optional trace-time JAX\nsaved-residual diagnostics. It does not run FDTD and does not upgrade\nstatic planning evidence into runtime memory proof.", "kind": "method", "name": "rfx.Simulation.ad_memory_preflight", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_memory_gb" }, { "annotation": "float", "default": "0.85", "has_default": true, "kind": "KEYWORD_ONLY", "name": "target_fraction" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "float", "default": "1.3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "safety_factor" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_mesh_report" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_ntff" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_resolution" }, { "annotation": "Callable[..., Any] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_fun" }, { "annotation": "tuple[Any, ...]", "default": "()", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_args" }, { "annotation": "Mapping[str, Any] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_kwargs" }, { "annotation": "int", "default": "10", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_top_n" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_workflow" }, { "annotation": "Mapping[str, object] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "residual_context" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.ad_memory_preflight", "returns": { "annotation": "ADMemoryPreflightReport" }, "signature": "(self, n_steps: 'int', available_memory_gb: 'float', *, target_fraction: 'float' = 0.85, n_warmup: 'int' = 0, safety_factor: 'float' = 1.3, include_mesh_report: 'bool' = True, check_ntff: 'bool' = True, check_resolution: 'bool' = True, residual_fun: 'Callable[..., Any] | None' = None, residual_args: 'tuple[Any, ...]' = (), residual_kwargs: 'Mapping[str, Any] | None' = None, residual_top_n: 'int' = 10, residual_workflow: 'str | None' = None, residual_context: 'Mapping[str, object] | None' = None) -> 'ADMemoryPreflightReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_ad_memory.py#L870", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a geometric shape filled with a named material.\n\nParameters\n----------\nshape : Shape\nmaterial : str\n Registered or library material name.\n\nNotes\n-----\nA PEC shape is a VOLUME under the lattice ownership contract\n(#931): its primal cells are sampled at cell centres and every E\nedge incident to an occupied cell is shorted, so a Box drawn\n``z_a -> z_b`` on node planes realizes walls at BOTH planes with\nrealized thickness = drawn thickness. A PEC Box with exactly one\nzero-extent axis (``lo == hi``) is a SHEET declaration, realized\nexactly as :meth:`add_thin_conductor` would realize it. A PEC Box\nthinner than one local cell (but not zero) is refused at\nassembly; so is any PEC shape that rasterizes to zero cells.\nThere is no per-entry realization knob.", "kind": "method", "name": "rfx.Simulation.add", "parameters": [ { "annotation": "Shape", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "shape" }, { "annotation": "str", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "material" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add", "returns": { "annotation": "'Simulation'" }, "signature": "(self, shape: 'Shape', *, material: 'str') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L879", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add an SMA-style coaxial probe port.\n\nParameters\n----------\nposition : (x, y, z) — center of port on cavity wall (metres)\nface : \"top\", \"bottom\", \"front\", \"back\", \"left\", \"right\"\npin_length : float — pin protrusion into cavity (default 5mm)\npin_radius : float — center pin radius (default 0.635mm, SMA)\nouter_radius : float — outer conductor radius (default 2.055mm)\nimpedance : float — port impedance (default 50 ohm)\nwaveform : excitation pulse (default GaussianPulse at freq_max/2)", "kind": "method", "name": "rfx.Simulation.add_coaxial_port", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'top'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "face" }, { "annotation": "float", "default": "0.005", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pin_length" }, { "annotation": "float", "default": "0.000635", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pin_radius" }, { "annotation": "float", "default": "0.002055", "has_default": true, "kind": "KEYWORD_ONLY", "name": "outer_radius" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "impedance" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "terminates" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_coaxial_port", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', face: 'str' = 'top', *, pin_length: 'float' = 0.005, pin_radius: 'float' = 0.000635, outer_radius: 'float' = 0.002055, impedance: 'float' = 50.0, waveform=None, terminates=None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1118", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Accumulate the structure's own current as block moments, in-loop.\n\nThe radiation of a structure is what the current in it radiates. On\nthe Yee lattice that current is an identity the solver already\nenforces — ``J = curl_h H - eps0 dE/dt`` at every electric-field edge\n— so it can be read off the fields the step is holding, with nothing\nmodelled and nothing fitted. This monitor sums it over the slab\nbetween ``corner_lo`` and ``corner_hi`` into a few numbers per\nin-plane block (the total current moment and its first two spatial\nmoments about the block's own centre) and DFTs those, instead of\naccumulating tangential E and H over a Huygens surface.\n\nParameters\n----------\ncorner_lo, corner_hi : (x, y, z) in metres\n Opposite corners of the slab, in the same frame as\n :meth:`add_ntff_box`. The z range picks the node planes; the\n whole thickness goes into one block.\nblock_size : float\n In-plane block side in metres, rounded to a whole number of\n cells. The realized side is what the monitor reports.\nfreqs : array\n Frequencies (Hz).\norder : int\n 2 (the only accepted value) keeps P, Q and T — 30 numbers per\n block. Lower orders are refused; the low-level\n ``rfx.current_moments.build_current_moment_monitor`` keeps them.\n\nNotes\n-----\nmargin_cells : int or (mx, my, mz)\n Extra cells around the declared corners.\noff_cells : int\n Shift of the in-plane partition origin, in cells. 0 and half a\n block are the two the block rule was measured with.\n\nNotes\n-----\nThe slab must lie in the interior: inside the absorber the E update\nis not Ampere's law, so a current read there is the absorber's\nfiction. Periodic/Bloch axes, TFSF sources, ``stencil_order=4``, a\ngraded or dx != dy in-plane mesh, a traced mesh profile, and every\nlane whose scan body does not accumulate the monitor are refused\nrather than approximated. So is a model the pattern would silently\nleave out: magnetic material (``mu_r != 1``), a PEC or PMC domain\nface, a waveguide, coaxial or Floquet port, a microstrip port with\n``mode=\"eigenmode\"``, and any dielectric, conductor, dispersive cell,\nport, lumped element or source that is not inside the slab (its\noutermost edge layer counts as outside).\n\nThe named arguments here are the whole public surface. The low-level\nbuilder additionally takes deliberately wrong metrics, centres, curl\nsigns and time stamps so the mutation harness can measure what the\ndeclared checks catch; those never reach a user's declaration.", "kind": "method", "name": "rfx.Simulation.add_current_moment_monitor", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "block_size" }, { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "order" }, { "annotation": null, "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "margin_cells" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "off_cells" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_current_moment_monitor", "returns": { "annotation": "'Simulation'" }, "signature": "(self, corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]', block_size: 'float', freqs, order: 'int' = 2, margin_cells=0, off_cells: 'int' = 0) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2776", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a frequency-domain 2D plane probe.\n\nParameters\n----------\naxis : \"x\", \"y\", or \"z\"\n Plane normal axis.\ncoordinate : float\n Physical coordinate in metres along the selected axis.\ncomponent : field component name\n One of ex/ey/ez/hx/hy/hz.\nfreqs : array or None\n Probe frequencies in Hz. Default: linspace(freq_max/10, freq_max, n_freqs).\nn_freqs : int\n Number of frequencies if freqs is None.\nregion : tuple or None\n Half-open transverse array-index crop (lo1, hi1, lo2, hi2).\n A 1 by 1 crop is a point DFT at that Yee component.\nname : str or None\n Optional result key.", "kind": "method", "name": "rfx.Simulation.add_dft_plane_probe", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "axis" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "coordinate" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "component" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" }, { "annotation": "tuple[int, int, int, int] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "region" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_dft_plane_probe", "returns": { "annotation": "'Simulation'" }, "signature": "(self, *, axis: 'str', coordinate: 'float', component: 'str' = 'ez', freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 50, name: 'str | None' = None, region: 'tuple[int, int, int, int] | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2646", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a Floquet port for periodic structure / phased array analysis.\n\nThe Floquet port injects a plane wave at the given scan angle\nand extracts Floquet mode amplitudes (S-parameters) from the\nunit cell response. Requires periodic BC on the two axes\nperpendicular to the port normal.\n\nParameters\n----------\nposition : float\n Physical coordinate along the port normal axis (metres).\naxis : str\n Port normal axis: ``\"x\"``, ``\"y\"``, or ``\"z\"``.\nscan_theta : float\n Scan angle theta from broadside (degrees). Default 0.\nscan_phi : float\n Scan angle phi in the transverse plane (degrees). Default 0.\npolarization : str\n ``\"te\"`` or ``\"tm\"``. Default ``\"te\"``.\nn_modes : int\n Number of Floquet modes to extract (default 1 = specular).\nfreqs : array or None\n Analysis frequencies. Auto-generated if None.\nn_freqs : int\n Number of frequency points when ``freqs`` is None.\nf0 : float or None\n Source center frequency. Default: ``freq_max / 2``.\nbandwidth : float\n Source fractional bandwidth. Default 0.5.\namplitude : float\n Source amplitude. Default 1.0.\nname : str or None\n Optional name for the port. Auto-generated if None.", "kind": "method", "name": "rfx.Simulation.add_floquet_port", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'z'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "axis" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scan_theta" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "scan_phi" }, { "annotation": "str", "default": "'te'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polarization" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_modes" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_floquet_port", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'float', *, axis: 'str' = 'z', scan_theta: 'float' = 0.0, scan_phi: 'float' = 0.0, polarization: 'str' = 'te', n_modes: 'int' = 1, freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 50, f0: 'float | None' = None, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, name: 'str | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2493", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a Poynting flux monitor on a plane (Meep flux-region equivalent).\n\nAccumulates frequency-domain E and H tangential components to\ncompute ``integral Re(E x H*) . n_hat dA`` at each frequency.\n\nParameters\n----------\naxis : \"x\", \"y\", or \"z\"\n Plane normal axis.\ncoordinate : float\n Physical coordinate in metres along the selected axis.\nfreqs : array or None\n Monitor frequencies in Hz.\nn_freqs : int\n Number of frequencies if freqs is None.\nsize : (float, float) or None\n Positive finite extents in the two tangential directions. A finite\n window snaps to cell edges, clamps to the physical interior with\n a warning on any clamp, and excludes CPML/bounding-node slots.\n ``None`` means the full allocated plane (legacy behaviour).\ncenter : (float, float) or None\n Physical centre of the flux region in the two tangential\n directions. ``None`` defaults to the declared domain midpoint\n on uniform grids and the realized interior midpoint on graded grids.\n For example, for an x-normal monitor the two tangential\n axes are (y, z). Exactly two finite values are required.\n Preflight reports finite requested/realized bounds in metres\n through ``report.flux_regions``.\nname : str or None\n Result key. Default: ``flux_{axis}_{idx}``.", "kind": "method", "name": "rfx.Simulation.add_flux_monitor", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "axis" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "coordinate" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "size" }, { "annotation": "tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "center" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" }, { "annotation": "str", "default": "'rect'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_window" }, { "annotation": "float", "default": "0.25", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dft_window_alpha" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_flux_monitor", "returns": { "annotation": "'Simulation'" }, "signature": "(self, *, axis: 'str', coordinate: 'float', freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 50, size: 'tuple[float, float] | None' = None, center: 'tuple[float, float] | None' = None, name: 'str | None' = None, dft_window: 'str' = 'rect', dft_window_alpha: 'float' = 0.25) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2680", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a lumped RLC element at a single cell.\n\nThe element is modelled via Auxiliary Differential Equations\n(ADE) that are updated each timestep alongside the standard\nYee update. Any combination of R, L, C is valid (set unused\ncomponents to 0).\n\nParameters\n----------\nposition : (x, y, z) in metres\ncomponent : \"ex\", \"ey\", or \"ez\"\nR : float\n Resistance in ohms (default 0).\nL : float\n Inductance in henries (default 0).\nC : float\n Capacitance in farads (default 0).\ntopology : \"series\" or \"parallel\"\n\nNotes\n-----\nFor series topology with a single component (e.g., pure L with\nR=0 and C=0), the element is handled via material folding, not\nthe full series ADE current tracker. To ensure the series ADE\npath is used, specify at least two non-zero components.", "kind": "method", "name": "rfx.Simulation.add_lumped_rlc", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "R" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "L" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "C" }, { "annotation": "str", "default": "'series'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "topology" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_lumped_rlc", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', component: 'str' = 'ez', *, R: 'float' = 0.0, L: 'float' = 0.0, C: 'float' = 0.0, topology: 'str' = 'series') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1960", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Register a named material.\n\nParameters\n----------\nchi3 : float\n Third-order (Kerr) susceptibility in m^2/V^2. When\n non-zero, an ADE correction is applied after each E-field\n update inside the scan body.", "kind": "method", "name": "rfx.Simulation.add_material", "parameters": [ { "annotation": "str", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "name" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mu_r" }, { "annotation": "list[DebyePole] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "debye_poles" }, { "annotation": "list[LorentzPole] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lorentz_poles" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "chi3" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_material", "returns": { "annotation": "'Simulation'" }, "signature": "(self, name: 'str', *, eps_r: 'float' = 1.0, sigma: 'float' = 0.0, mu_r: 'float' = 1.0, debye_poles: 'list[DebyePole] | None' = None, lorentz_poles: 'list[LorentzPole] | None' = None, chi3: 'float' = 0.0) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L831", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a microstrip-line (MSL) port spanning the full trace cross-section.\n\nUnlike :meth:`add_port` with ``extent=...`` (a one-cell-transverse\nwire port), this port covers the full ``width × height``\ncross-section under the trace and uses 3-probe numerical\nde-embedding to extract β and Z0 empirically downstream of the\nfeed plane.\n\nParameters\n----------\nposition : (x, y, z_lo)\n Physical feed-plane point. The coordinate on the PROPAGATION\n axis (named by ``direction``) is the feed plane; the\n coordinate on the other in-board axis is the trace centre;\n ``z`` is the substrate bottom. So a ``\"+x\"`` port reads it as\n ``(x_feed, y_centre, z_lo)`` and a ``\"+y\"`` port as\n ``(x_centre, y_feed, z_lo)``.\nwidth : float\n Trace width in metres, spanning the in-board axis that is NOT\n the propagation axis (y for an x-directed port, x for a\n y-directed one).\nheight : float\n Substrate thickness in metres — always the z extent, because\n the substrate normal is fixed to z (see ``direction``).\ndirection : str\n One of ``\"+x\"``, ``\"-x\"``, ``\"+y\"``, ``\"-y\"`` — the direction\n the launched wave propagates. The board lies in the xy-plane\n and the substrate normal is always z, so the feed may run\n along either in-board axis (issue #661: a CAD-imported board\n does not get to choose its orientation).\n\n ``\"+z\"`` / ``\"-z\"`` are REJECTED with a clear error rather\n than supported: a z-propagating microstrip needs its\n substrate normal along x or y, which ``position`` + scalar\n ``height`` cannot express, and which the Laplace mode solve,\n the ``\"ez\"`` source component, the modal voltage\n ``V = Σ Ez·dz`` and the trace-conductor PEC scan all assume.\n Accepting it would return a z-normal answer for a board that\n is not oriented that way.\n\n ``mode=\"eigenmode\"`` remains ``\"+x\"``/``\"-x\"`` only.\nimpedance : float\n Target Z0 in ohms (default 50). Used for the σ distribution.\nwaveform : GaussianPulse or callable, optional\n Excitation waveform. Defaults to a band-limited Gaussian\n centred at ``freq_max/2``. Ignored when ``excite=False``.\nexcite : bool\n ``True`` → resistive termination + active source; ``False``\n → passive matched termination only.\nn_probe_offset : int, optional\n Distance (cells) from the feed plane to the first probe plane.\n Automatic offset and spacing counts are recomputed at driver time\n in the cells under the port, including graded runways, uniform\n ``dy_profile`` different from ``dx``, and auto meshes. A ladder\n crossing a grading ramp retains counts based on scalar ``dx``.\n When ``None``, bound to the LARGER of two near-field clearances:\n (a) the wavelength reactive far-field (issue #80 Fix B),\n ``round(0.5 * lam_min_eff / (2*pi) / dx)`` with\n ``lam_min_eff = c / freq_max / sqrt(eps_r_sub_estimate)``; and\n (b) the source FRINGING transient ``round(5 * h_sub / dx)``,\n which decays over a few substrate thicknesses (``h_sub`` = the\n port ``height``), NOT over λ. For a thin high-εr substrate (b)\n dominates: clearing only (a) leaves probe 0 inside the fringing\n transient and corrupts the V·I-split S11 of a high-Q resonant\n load (issue #80 patch: |S11|=8.94/1.11 → passive ~0.99 once\n cleared). These two terms are only the UPSTREAM (lower) edge:\n at ``compute_msl_s_matrix`` time the auto default additionally\n solves the DOWNSTREAM constraint (issue #469) — the deepest\n probe must stay ≥ λ_g/4 (at ``freq_max``) clear of the nearest\n reflector — picking the midpoint of the compliant interval\n when a reflector bounds it, keeping the upstream edge when\n none does, and warning loudly when the interval is empty (the\n feed line is too short for a clean N-probe measurement).\n Pass an explicit value to override (explicit values are never\n adjusted); ``< 5*h_sub/dx`` triggers a preflight near-field\n warning.\nn_probe_spacing : int, optional\n Distance (cells) between consecutive probe planes. Automatic\n counts use the same driver-time runway recount as the offset.\n When ``None``,\n bound so the total N-probe array span stays ~``lam_min_eff/8``\n independent of ``n_probes``:\n ``round(lam_min_eff / 8 / (n_probes - 1) / dx)``. For\n ``n_probes=3`` this is exactly ``lam_min_eff/16`` (issue #80\n Fix B). Shrinking the adjacent spacing as ``n_probes`` grows\n keeps the probe array from running off short lines.\n\n An AUTO spacing is additionally WIDENED at driver time\n (issue #681): ``compute_msl_s_matrix`` /\n ``compute_mixed_s_matrix`` re-solve it toward a total span of\n ``(n_probes−1)·λ_g(f_max)/4`` (λ_g from the HJ ε_eff), capped\n by the downstream-reflector interval and the absorbing\n boundary — a ~0.1·λ_g span leaves the β fit noise-fragile\n (measured: median β error 5.5% at 0.10 λ_g vs 0.8% at\n 0.30 λ_g under 1% probe noise). An explicit value is never\n touched.\nn_probes : int\n Number of equally-spaced voltage probe planes registered for\n the N-probe least-squares wave-decomposition extractor (issue\n #80 Fix C). Probe ``n`` sits at ``offset + n*spacing`` cells\n from the feed plane. ``N >= 3`` is required; the default 5\n over-determines the 2-unknown ``(alpha, gamma)`` fit, which\n removes the 3-probe quadratic's q→1 singularity. The current\n probe at probe 0 is always recorded for the absolute Z0.\nname : str, optional\n Port label used in result dicts. Auto-generated when omitted.\neps_r_sub : float, optional\n Substrate relative permittivity. Used both for the eigenmode\n source and as ``eps_r_sub_estimate`` for the wavelength-bound\n probe-placement defaults (issue #80 Fix B). When ``None`` the\n estimate is resolved from the dielectric geometry already\n registered under the port (a shape whose bounding box contains\n the substrate mid-point and whose material has ``eps_r > 1``);\n if no such dielectric is found it falls back to 1.0, which is\n conservative (largest ``lam_min_eff`` → largest offset).", "kind": "method", "name": "rfx.Simulation.add_msl_port", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "width" }, { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "height" }, { "annotation": "str", "default": "'+x'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "direction" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "impedance" }, { "annotation": "GaussianPulse | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "excite" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_probe_offset" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_probe_spacing" }, { "annotation": "int", "default": "5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_probes" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" }, { "annotation": "str", "default": "'laplace'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r_sub" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "terminates" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_msl_port", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', *, width: 'float', height: 'float', direction: 'str' = '+x', impedance: 'float' = 50.0, waveform: 'GaussianPulse | None' = None, excite: 'bool' = True, n_probe_offset: 'int | None' = None, n_probe_spacing: 'int | None' = None, n_probes: 'int' = 5, name: 'str | None' = None, mode: 'str' = 'laplace', eps_r_sub: 'float | None' = None, terminates=None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1642", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a near-to-far-field transform box for radiation patterns.\n\nParameters\n----------\ncorner_lo, corner_hi : (x, y, z) in metres\n Opposite corners of the Huygens box.\nfreqs : array or None\n Frequencies (Hz). Default: n_freqs points from freq_max/10\n to freq_max.\nn_freqs : int\n Number of frequencies if freqs is None.", "kind": "method", "name": "rfx.Simulation.add_ntff_box", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_lo" }, { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "corner_hi" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_freqs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_ntff_box", "returns": { "annotation": "'Simulation'" }, "signature": "(self, corner_lo: 'tuple[float, float, float]', corner_hi: 'tuple[float, float, float]', freqs=None, n_freqs: 'int' = 50) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2752", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Declare a thin PEC conductor by NODE INDICES instead of metres.\n\n``add_thin_conductor`` draws metal in metres, and the grid then\ndecides which node lines that reaches. This draws it on the node\nlines directly: the conductor occupies node ``plane_index`` along\n``normal_axis`` and the inclusive node ranges ``i_range`` /\n``j_range`` on the other two axes, in increasing axis order — for\nthe default ``normal_axis=2`` that is ``i_range`` on x and\n``j_range`` on y.\n\nIndices are INTERIOR (unpadded) node indices: interior node ``i``\nsits at ``i * dx`` from the domain origin on a uniform mesh, and is\nthe ``i``-th interior node on a graded one. Absorber padding is\nadded when the sheet is realized.\n\nWhy it exists: the conductor's PHYSICAL size is then whatever the\ncells between those nodes add up to, so stretching the cells makes\nthe metal longer without moving it off the lattice and without any\nsub-cell metal. That is what lets ``jax.grad`` reach a patch edge\nthrough ``dx_profile`` / ``dy_profile`` / ``dz_profile`` — a metric\nsheet on a mesh that is a JAX tracer is still refused, because its\ncorners cannot be read off a traced node line.\n\nThe declaration is mesh-independent by construction, so the same\ncall gives the same footprint on the uniform and non-uniform lanes,\ntraced or not. A range spanning a single node line is refused: one\nnode line carries no E edge, so the metal would carry no current.\n\nOnly the lossless PEC sheet is supported (``sigma_bulk >= 1e6``,\n``surface_impedance_f0`` unset); ``thickness`` and ``eps_r`` are\naccepted for signature compatibility with\n:meth:`add_thin_conductor` and are not read, exactly as they are\nnot read there for a metal.", "kind": "method", "name": "rfx.Simulation.add_pinned_sheet", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "plane_index" }, { "annotation": "tuple[int, int]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "i_range" }, { "annotation": "tuple[int, int]", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "j_range" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "normal_axis" }, { "annotation": "float", "default": "58000000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma_bulk" }, { "annotation": "float", "default": "3.5e-05", "has_default": true, "kind": "KEYWORD_ONLY", "name": "thickness" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "surface_impedance_f0" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_pinned_sheet", "returns": { "annotation": "'Simulation'" }, "signature": "(self, *, plane_index: 'int', i_range: 'tuple[int, int]', j_range: 'tuple[int, int]', normal_axis: 'int' = 2, sigma_bulk: 'float' = 58000000.0, thickness: 'float' = 3.5e-05, eps_r: 'float' = 1.0, surface_impedance_f0: 'float | None' = None, name: 'str | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1418", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a polarized point source.\n\nParameters\n----------\nposition : (x, y, z) in metres\npolarization : str or tuple\n - \"ez\", \"ex\", \"ey\" — linear single-component\n - \"circular\" or \"rhcp\" — accepted complex-component shortcut;\n time-domain quadrature is not independently verified\n - \"lhcp\" — accepted complex-component shortcut; same limitation\n - (Ex, Ey) tuple — normalized component weights; real tuples are\n the documented linear-polarization scope\n - \"slant45\" — 45° linear (Ex = Ey)\nwaveform : excitation pulse (default: GaussianPulse)\namplitude_kind : 'field' | 'current' | None\n Threaded through to every internal :meth:`add_source` call —\n see ``add_source`` for the semantics. ``None`` resolves to\n ``'current'`` and warns once per simulation; pass the kind explicitly\n to silence the warning.", "kind": "method", "name": "rfx.Simulation.add_polarized_source", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str | tuple", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polarization" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude_kind" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_polarized_source", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', *, polarization: 'str | tuple' = 'ez', waveform=None, amplitude_kind: 'str | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1009", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a lumped port (single-cell) or wire port (multi-cell).\n\nParameters\n----------\nposition : (x, y, z) in metres\ncomponent : \"ex\", \"ey\", or \"ez\"\nimpedance : port impedance in ohms (default 50)\nwaveform : excitation pulse (default: GaussianPulse at freq_max/2).\n Ignored when ``excite=False``.\nextent : float or None\n When provided, the port spans from *position* along the port\n axis by this distance (metres), creating a multi-cell WirePort.\n For example ``component=\"ez\", extent=0.0015`` spans the port\n from ``z`` to ``z + 0.0015``.\nradius : float or None\n Opt-in thin-probe radius in metres (requires ``extent``).\n ``None`` preserves the legacy filament, whose effective radius\n is approximately 0.20 times the transverse cell size. The\n local self-field model requires a square, locally uniform\n transverse mesh, uniform spacing along the pin, and radius\n <= 0.2 times the transverse spacing. Supported\n on single-device, nondispersive 3-D second-order Yee run/forward;\n unsupported solvers and material updates raise before stepping.\nexcite : bool (default True)\n When True the port has BOTH a resistive termination AND a\n time-domain source (legacy behaviour).\n When False the port is a passive matched load only — no\n source, just the σ=1/(Z0·A) resistive termination.\n Passive ports are required for multi-port S-parameter\n extraction: excite one port at a time and probe V/I at the\n others to fill off-diagonal entries of the S matrix.\ndirection : {\"+x\", \"-x\", \"+y\", \"-y\"} or None\n Outward-normal direction of the port (from the port cell\n into the external world). Used by the S-matrix post-\n processing to orient the V/I → (incoming, outgoing) wave\n decomposition. When None, the runner auto-detects from the\n port's position (closest boundary face).\nreference_plane_cells : int or None\n Opt-in reference-plane port waves for the wire-port S-matrix\n OFF-diagonal extraction (issue #313). When set to an integer\n N >= 1, ``run(compute_s_params=True)`` registers TWO line\n V/I reference planes for this port at N and 2N cells\n outboard (into the DUT along the line axis, i.e. opposite\n ``direction``): gap-voltage line integrals at integer Yee\n planes plus dual adjacent Ampere loops around the PEC signal\n trace, accumulated in the production scan. Off-diagonal\n ``S[i, j]`` entries whose ports BOTH opt in are then computed\n from the plane waves — forward/backward split with the\n MEASURED two-plane line impedance\n ``Zc^2 = (V1^2 - V2^2)/(I1^2 - I2^2)`` (never the nominal\n port impedance) and phase-only de-embedding to the port plane\n with the MEASURED per-bin beta from the same two planes.\n The Phase-0 closed-box flux referee showed the port-cell wave\n pair does not conserve power (the port plane is near-field\n dominated) while the plane waves close the power budget at\n all bins; the plane path removes the drive-side |S21|\n deflation kappa(f) = 1.49-1.86 of issue #313.\n ``None`` (default) keeps the shipped port-cell behaviour,\n byte-identical. The DIAGONAL ``S_jj`` always stays on the\n byte-frozen legacy path either way, so ``forward()`` /\n 1-port S11 results are unaffected. Requires a wire port\n (``extent=``) with an explicit ``direction`` transverse to\n the port component, a PEC signal trace uniform across both\n planes, and the uniform-mesh ``run()`` lane: the\n non-uniform and subgridded lanes raise\n ``NotImplementedError`` with the opt-in set, and the\n distributed lane does not support ``compute_s_params`` at\n all (it warns that the kwarg is unsupported and ignores\n it).\n\n Choosing N: place BOTH planes (N and 2N cells) roughly >= 10\n cells from every port so the two-plane Zc/beta measurement\n sits outside the port near-fields — the Phase-0\n pre-registration rule. Measured on the canonical 16 mm thru\n (dx = 0.5 mm, gap-trimmed V, 2026-07-10 battery): N=3 planes\n read beta/(w/c) = 1.16-1.20 and Zc = 52-53 ohm with Im/Re up\n to 8.2% (near-field contaminated; |S21| closed-box-referee\n residual -3.1% at 7 GHz, row energy |S11|^2+|S21|^2 up to\n 1.019), while N=10 planes read the clean mid-line\n beta/(w/c) = 1.046-1.059 and Zc = 47.9-48.6 ohm (Im/Re <=\n 1.2%) and closed the closed-box referee within 0.9% at all\n bins.", "kind": "method", "name": "rfx.Simulation.add_port", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": "float", "default": "50.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "impedance" }, { "annotation": "GaussianPulse | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "extent" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "radius" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "excite" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "direction" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_plane_cells" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "terminates" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_port", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', component: 'str' = 'ez', *, impedance: 'float' = 50.0, waveform: 'GaussianPulse | None' = None, extent: 'float | None' = None, radius: 'float | None' = None, excite: 'bool' = True, direction: 'str | None' = None, reference_plane_cells: 'int | None' = None, terminates=None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1475", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a point field probe.", "kind": "method", "name": "rfx.Simulation.add_probe", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_probe", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', component: 'str' = 'ez') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2613", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a z-axis refinement region for SBP-SAT subgridding.\n\nRefinement acts only through ``run()`` on a uniform mesh. Other\nsolve entry points, including ``forward()`` and optimization, refuse it.\n\nThe experimental runner covers the specified z-range across the\nfull x/y interior at ``dx_fine = dx_coarse / ratio``. ``xy_margin``\nenables an experimental research-only local x/y window whose fine\nregion is inset from the physical x/y boundaries by that distance.\n\nParameters\n----------\nz_range : (z_lo, z_hi) in metres\n Physical z-range for the fine region.\nratio : int\n Refinement ratio (fine cells per coarse cell). Default 4.\nxy_margin : float or None\n Experimental x/y inset in metres. ``None`` keeps the full x/y\n interior. A finite non-negative value creates a local window\n spanning ``[xy_margin, Lx - xy_margin]`` and\n ``[xy_margin, Ly - xy_margin]``. Production validation still\n rejects this lane until waveform gates and crossval pass.\ntau : float\n SAT penalty coefficient (default 0.5). Higher values give\n stronger coupling but more dissipation.\nvalidation : {\"production\", \"research\", \"off\"}\n Production refuses the unstable, unverified subgridded lane before\n stepping (#1465). An empty PEC cavity's first resonance is 8 % high\n and its field grows. Use dx/dy/dz profiles for local resolution.\n Explicit ``\"research\"`` or ``\"off\"`` runs with a warning; neither\n mode establishes physics support.\ntopology : {\"overlap_z_slab\", \"stage2_disjoint_3d\"}\n Internal topology selector. ``\"overlap_z_slab\"`` is the current\n public runner. ``\"stage2_disjoint_3d\"`` records the selected\n centered/two-interface integration lane but remains a research-only\n contract until its public runner wiring and waveform gates pass.", "kind": "method", "name": "rfx.Simulation.add_refinement", "parameters": [ { "annotation": "tuple[float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "z_range" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ratio" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "xy_margin" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "tau" }, { "annotation": "str", "default": "'production'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "validation" }, { "annotation": "str", "default": "'overlap_z_slab'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "topology" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_refinement", "returns": { "annotation": "'Simulation'" }, "signature": "(self, z_range: 'tuple[float, float]', *, ratio: 'int' = 4, xy_margin: 'float | None' = None, tau: 'float' = 0.5, validation: 'str' = 'production', topology: 'str' = 'overlap_z_slab') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L678", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a soft point source (no impedance loading).\n\nUnlike ``add_port()``, this does NOT add a resistive load.\nIdeal for resonance characterization where port loading would\ndamp the cavity response.\n\nUses a differentiated ``GaussianPulse`` by default (near-zero DC\ncontent, ~1e-4). This prevents static charge accumulation on PEC\nsurfaces.\n\nParameters\n----------\nposition : (x, y, z) in metres\ncomponent : \"ex\", \"ey\", or \"ez\"\nwaveform : excitation pulse\n (default: ``GaussianPulse(f0=freq_max/2, bandwidth=0.8)``)\namplitude_kind : 'field' | 'current' | None\n What the waveform amplitude MEANS — issue #571. Boundary- and\n mesh-independent once explicit:\n\n - ``'current'``: the amplitude is a current moment I(t) in A·m,\n realized as ``E += Cb * I / dV`` on every path and boundary\n (Yee ``Cb = (dt/eps)/(1 + sigma*dt/(2*eps))``; ADI refuses\n ``'current'`` and requires explicit ``'field'``,\n ``dV`` = local cell volume). Resolution-independent injected\n power; Meep's convention; the declaration default.\n - ``'field'``: the amplitude is a raw E-field increment per\n step, ``E += w(t)`` on every path and boundary.\n\n Cell-volume convention: ``dV = dx * dy * dz`` at the source\n cell; a 2D grid is treated as ONE CELL DEEP (``dz`` one cell,\n duck-typed to ``dx``), so ``dV = dx**3`` on a cubic 2D grid,\n not the per-unit-length ``dx**2``\n (``rfx/api/_source_semantics.py``). On a non-uniform mesh\n ``dV`` is the E node's control volume — the primal per-cell\n width on the component's own axis and the DUAL spacing\n ``(d[k-1]+d[k])/2`` on the two transverse axes (issue #672);\n the two coincide on a uniform profile.\n\n ``None`` means ``'current'`` (E += Cb*I/dV, I is a current moment in A·m)\n on every path and emits one\n :class:`DeprecationWarning` per Simulation. Pass the kind\n explicitly to silence it.\n\n The open-boundary + ``subpixel_smoothing`` cross-path residual\n (0.18 % amplitude, issue #582) is a solver defect independent\n of this parameter.", "kind": "method", "name": "rfx.Simulation.add_source", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "component" }, { "annotation": null, "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude_kind" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_source", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]', component: 'str' = 'ez', *, waveform=None, amplitude_kind: 'str | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L927", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a normal-incidence plane-wave TFSF source.\n\nCurrent scope is intentionally narrow: x-directed propagation,\n``ez``/``ey`` polarization, 3D mode, and CPML boundaries. For\noblique incidence, only the single transverse-axis plane implied\nby the chosen polarization is supported.\n\nParameters\n----------\nclosed_box : bool\n Use a finite six-face total-field box with CPML on all three\n axes. Normal incidence, uniform 3D Yee only. The default keeps\n the historical x slab with periodic y/z. Read the realized\n inclusive node bounds with :meth:`tfsf_box_indices`.\nwaveform : {\"differentiated_gaussian\", \"modulated_gaussian\", \"continuous_wave\"}\n Pulse shape injected into the 1D auxiliary grid. (``continuous_wave``\n is only supported at normal incidence — ``angle_deg == 0``.)\n\n ``differentiated_gaussian`` (default, legacy rfx): baseband\n pulse with no carrier, DC-free, spectrum peaks near\n ``f0·bandwidth``. Good for broadband measurements but\n spectrum extends well below ``f0``.\n\n ``continuous_wave``: a single-frequency sinusoid at ``f0`` with a\n raised-cosine turn-on (~8 periods), then constant amplitude. Use for\n steady-state / narrowband measurements that need a well-defined\n time-average ``⟨E²⟩ = A²/2`` (e.g. the quantitative Kerr SPM oracle,\n #446). Not for broadband S-parameters — it excites only ``f0``.\n\n ``modulated_gaussian``: carrier-modulated Gaussian matching\n Meep's ``GaussianSource(frequency=f0, fwidth=f0·bandwidth)``.\n Spectrum is a Gaussian centered at ``f0`` with 1/e\n half-width ``f0·bandwidth``. Use this for matched rfx-vs-Meep\n crossval comparisons.\n\n A ``CustomWaveform`` may supply a fixed, JAX-compatible real\n scalar function of time, multiplied by ``amplitude``. It is\n added to the auxiliary E node at ``t=n*dt``; it is not the\n launched E amplitude. Normal incidence only; use a fixed\n record length (``until_decay`` has no source-off contract).\n These new source inputs support ordinary ``forward`` and its\n internal checkpoints. External JAX transformations, including\n grad/value_and_grad/JVP/vmap/jit/checkpoint/scan, are refused:\n transformed scattered-field traces do not meet the cross-trace bar.\nmethod : {\"bloch\", \"methodB\"}\n Oblique-incidence engine (ignored for ``angle_deg=0``, which always\n uses the normal 1D-aux path). ``\"bloch\"`` (default) is the narrowband\n complex-Bloch 2D-aux path (fields go complex64; frequency-domain\n monitors are not transform-aware — see ``tfsf_2d.py``). ``\"methodB\"``\n is the open-domain oblique path (real ``float32``, 1D-aux-along-k̂ +\n 4-edge box): the transverse axis becomes OPEN/CPML, z stays thin\n periodic (2.5-D, z-invariant far field), and NTFF/DFT/flux monitors\n read physical fields. ``\"methodB\"`` currently requires\n ``polarization='ez'`` and a single-device uniform grid.", "kind": "method", "name": "rfx.Simulation.add_tfsf_source", "parameters": [ { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "margin" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "polarization" }, { "annotation": "str", "default": "'+x'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "direction" }, { "annotation": "float", "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "angle_deg" }, { "annotation": "object", "default": "'differentiated_gaussian'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "str", "default": "'bloch'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "method" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "closed_box" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_tfsf_source", "returns": { "annotation": "'Simulation'" }, "signature": "(self, *, f0: 'float | None' = None, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, margin: 'int' = 3, polarization: 'str' = 'ez', direction: 'str' = '+x', angle_deg: 'float' = 0.0, waveform: 'object' = 'differentiated_gaussian', method: 'str' = 'bloch', closed_box: 'bool' = False) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2026", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a thin conductor with subcell correction.\n\nParameters\n----------\nshape : Shape\n Geometric region of the conductor.\nsigma_bulk : float\n Bulk conductivity (S/m). Default: copper (5.8e7).\n\n **This single value decides the model.** At or above 1e6 S/m the\n shape becomes a PEC sheet and ``thickness`` and ``eps_r`` are\n never read (:func:`rfx.materials.thin_conductor.apply_thin_conductor`\n returns the material arrays untouched and only ORs the mask). Below\n 1e6 S/m the shape becomes a lossy sheet whose conductivity is\n ``sigma_bulk * thickness / d_norm``, where ``thickness`` IS\n load-bearing and ``d_norm`` is the local sheet-normal spacing\n (see ``surface_impedance_f0`` below for the graded-mesh case).\n Every real metal — copper 5.8e7, aluminium 3.5e7, even stainless\n steel 1.4e6 — is on the PEC side, so by default\n (``surface_impedance_f0`` unset) for metals this call models a\n lossless perfect sheet and nothing else. Pass\n ``surface_impedance_f0`` to opt in to band-centre Leontovich\n conductor loss instead (see below).\nthickness : float\n Physical thickness (metres). Default: 35 µm (1 oz copper).\n **Only used on the lossy path** (``sigma_bulk < 1e6``); ignored\n entirely for metals — see ``sigma_bulk`` above.\neps_r : float\n Relative permittivity (default 1.0). Lossy path only, same as\n ``thickness``.\nsurface_impedance_f0 : float or None\n Opt-in band-centre Leontovich surface-impedance loss\n (issue #669). Default ``None`` = exact legacy behaviour on every\n path. When set to a positive frequency (Hz), the sheet — for ANY\n ``sigma_bulk > 0``, metals included — is modelled as a resistive\n sheet of sheet resistance ``Rs0 = sqrt(pi*f0*mu0/sigma_bulk)``\n (the thick-conductor surface resistance at ``f0``), realized\n NODE-THIN (#677): a per-step operator applies an exact\n exponential-stepping resistive update ``E = A*E + B*curlH``\n with sheet conductivity ``sigma_sheet = (1/Rs0)/d_norm`` on\n exactly the tangential E edges a PEC sheet on the same cells\n would zero — so toggling ``surface_impedance_f0`` on a metal\n changes LOSS, never the conductor's surface position (before\n #677 the sheet folded into ``materials.sigma`` as a full-cell\n slab, moving resonances by geometry). ``d_norm`` is the local\n spacing normal to the sheet: the cell size on a uniform grid,\n and on a graded one the E-node DUAL spacing ``(d[k-1]+d[k])/2``\n (#671). Both the uniform and the non-uniform (``dz_profile``)\n ``run()``/S-parameter lanes apply the operator; lanes that do\n not (distributed, subgridded, ADI, UPML, dispersive-overlap,\n multimode-waveguide, MSL-junction/mixed, optimize/topology\n drivers) refuse f0 sheets loudly rather than silently dropping\n them; ``compute_msl_s_matrix`` applies the sheet through its\n ``run()``/``forward()`` device dispatches (#679). The sheet\n contributes NO PEC cells and no ``materials.sigma``/``eps_r``\n entries.\n\n **Consequence for material inspection (#695): an f0 sheet is\n INVISIBLE to the assembled arrays.** It is absent from\n ``pec_mask`` and it adds nothing to ``materials.sigma``, so a\n conductor test written the obvious way --\n ``pec_mask | (sigma > 1e3)`` -- finds no metal at all on a\n board whose traces are all f0 sheets, and a connectivity\n check built on it reports a perfectly healthy model as\n disconnected. Use :meth:`Simulation.conductor_mask`, which\n returns ``pec_mask | (sigma > threshold) | union(f0 sheet\n cell masks)`` -- the whole conductor footprint in one\n spelling, on the grid the run will actually use. The runtime\n edge masks (``mask_ex/ey/ez``) live on the\n ``SheetImpedanceCtx`` the runners build; the accessor returns\n the CELL footprint, which is what an occupancy or\n connectivity check wants.\n\n Model scope (be precise about what you get):\n\n - **Magnitude loss only.** The reactive part ``Xs = Rs``\n (internal inductance) is NOT modelled, so resonances read\n slightly high in frequency.\n - **Frequency-flat within a run**: ``Rs`` is frozen at ``f0``\n with relative band error ``|sqrt(f/f0) - 1|`` (about +-11%\n across an 8-12 GHz band centred at 10 GHz).\n - **Thick-conductor model**: valid for ``thickness >= ~3``\n skin depths at ``f0``. For thin films the DC path (omit this\n kwarg, ``sigma_bulk < 1e6``) is the correct model;\n ``thickness`` deliberately does NOT enter ``sigma_eff`` in f0\n mode (Leontovich loss is thickness-independent).\n - **Transmission leakage** ``(2*Rs/eta0)**2`` makes the sheet\n unusable for shielding-effectiveness claims beyond ~60 dB.\n (Validated against the closed form ``T = 2Rs/(2Rs+eta0)``\n to within a few percent, frequency-flat —\n tests/oracle/test_leontovich_alpha_oracle.py.)\n - The operator touches TANGENTIAL sheet edges only; the\n sheet-normal E component is never loaded (#677 removed the\n pre-existing isotropic-fold caveat).\n - ``f0`` and ``sigma_bulk`` are differentiable DoFs in f0 mode\n (closed forms ``d(sigma_sheet)/df0 = -sigma_sheet/(2*f0)``,\n ``d(sigma_sheet)/d(sigma_bulk) =\n +sigma_sheet/(2*sigma_bulk)``). Geometry (the rasterized\n mask) stays non-differentiable. Traced values skip the\n concrete-value validation below.\n\n Sheet shapes (issue #674): ANY shape implementing\n ``mask_on_coords`` and ``bounding_box`` may carry a\n surface-impedance sheet — a patterned ground plane with\n clearance holes, a meandered arm, an imported CAD outline\n (:class:`~rfx.geometry.mesh_import.MeshShape`), a disc, a\n strip. The realization is per occupied cell, so a hole is\n simply a cell the operator never touches. What is NOT supported\n is a body with HEIGHT: the sheet must rasterize to exactly ONE\n cell layer along its normal, because ``sigma_sheet`` is the\n conductance of a single E node. A 3-D solid, a bent/L-shaped sheet, or a slab\n thicker than a cell raises ``ValueError`` when the grid is\n built — folding such a body per cell would multiply the sheet\n conductance by the layer count while still reporting ``Rs0``.\n A sheet that rasterizes to ZERO cells raises too: a sub-cell\n mesh slab registers only where a grid node falls inside it, and\n silently vaporized metal is the #369 class. (A ``Box`` drawn\n with equal lo/hi on its normal axis snaps to the nearest node by\n construction, so it always satisfies both.)\n\n Validation at add time (concrete values only): ``f0 <= 0`` and\n ``sigma_bulk <= 0`` with ``f0`` set each raise ``ValueError``,\n as does a shape with no ``mask_on_coords`` or no bounding box.\n The rasterized one-layer and non-empty checks need the grid, so\n they raise at build time, on BOTH lanes (the legacy DC path\n also refuses non-Box shapes on a non-uniform mesh).\n\nNotes\n-----\nA PEC sheet occupying ONE cell is modelled as a surface, not as a\nconductor of that cell's thickness: :func:`rfx.boundaries.pec.apply_pec_mask`\nzeroes a tangential E component only where the mask has a neighbour\nalong that component's axis, so the normal component survives as\nsurface charge. Stamping the same conductor TWO cells thick therefore\nchanges the model rather than the thickness. Measured on an MSL thru at\ndx = 84.67 µm: one cell gives Re(Z0) = 44.1 Ω and two cells 41.9 Ω.\nReproduce with\n``scripts/diagnostics/thin_conductor_cell_thickness_probe.py``.\n\nNote this pair no longer *proves* the model change on its own. Until\nissue #511 was fixed the one-cell reading was 38.8 Ω, so the thicker\nstamp appeared to read the HIGHER impedance — backwards for a\nfringing-capacitance effect, which is how the model change was first\nargued. That inversion was an extractor artifact: the modal voltage\nsummed one Ez edge too many, and a two-cell stamp happens to mask that\nedge, so only the one-cell number was biased. With both corrected the\nordering is the ordinary one (thicker → lower Z0) and the 2.25 Ω step\nis consistent with either a model change or a genuine thickness\neffect. The model change is still real — it follows from\n``apply_pec_mask`` directly — but this measurement no longer\ndiscriminates between the two.\n\nConductor LOSS is therefore unavailable for metals through this API.\nOn the lanes this repo gates that is a small omission — copper loss on\na 10 mm 50 Ω microstrip is 0.04-0.05 dB at 3-4.5 GHz against a 0.45 dB\ngate budget, and the metal is 26-36 skin depths thick so its geometry\nis electromagnetically a half-space — but it is a real limit for\nanything whose loss budget IS the conductor, e.g. resonator Q.", "kind": "method", "name": "rfx.Simulation.add_thin_conductor", "parameters": [ { "annotation": "Shape", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "shape" }, { "annotation": "float", "default": "58000000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma_bulk" }, { "annotation": "float", "default": "3.5e-05", "has_default": true, "kind": "KEYWORD_ONLY", "name": "thickness" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "surface_impedance_f0" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_thin_conductor", "returns": { "annotation": "'Simulation'" }, "signature": "(self, shape: 'Shape', *, sigma_bulk: 'float' = 58000000.0, thickness: 'float' = 3.5e-05, eps_r: 'float' = 1.0, surface_impedance_f0: 'float | None' = None) -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L1162", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a vector probe that records ALL 6 field components.\n\nRecords Ex, Ey, Ez, Hx, Hy, Hz at the same position.\nResults accessible via result.time_series columns [0..5].", "kind": "method", "name": "rfx.Simulation.add_vector_probe", "parameters": [ { "annotation": "tuple[float, float, float]", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "position" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_vector_probe", "returns": { "annotation": "'Simulation'" }, "signature": "(self, position: 'tuple[float, float, float]') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2624", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Add a rectangular waveguide port.\n\n`x_position` is interpreted along the selected port-normal axis from\n`direction`. For example, `direction='-y'` uses `x_position` as the\nphysical y-coordinate of the port plane.\n\nCurrent scope supports axis-normal boundary ports using rectangular\napertures, with `boundary='cpml'` and `mode='3d'`.\n\nCalibration options:\n- `reference_plane` / `probe_plane`: explicit reported planes in\n physical coordinates along the port normal axis\n- `calibration_preset='source_to_probe'`: auto-report `S11` at the\n snapped source plane and `S21` from source to the snapped probe plane\n- `calibration_preset=None` or `'measured'`: use the snapped stored\n reference/probe planes directly\n\nSampling still occurs on the nearest snapped grid planes, and the\nresult metadata reports those actual measurement planes explicitly.\n\n``waveform`` selects the source pulse shape. Default\n``\"modulated_gaussian\"`` is the Meep-style bandpass pulse — no\nsub-cutoff DC content, so the in-band TFSF filter collapses to\nidentity, reducing directional leakage in the H+E injection pair.\n``\"differentiated_gaussian\"`` matches historical (legacy) rfx behaviour.\nPreliminary measurement shows directionality backward/forward\nratio 13.3 % → 8.2 % for a WR-90 at f₀=10 GHz; further gains\nawait the discrete-eigenmode profile work (P3).", "kind": "method", "name": "rfx.Simulation.add_waveguide_port", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "x_position" }, { "annotation": "tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "x_range" }, { "annotation": "tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "y_range" }, { "annotation": "tuple[float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "z_range" }, { "annotation": "tuple[int, int]", "default": "(1, 0)", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode" }, { "annotation": "str", "default": "'TE'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode_type" }, { "annotation": "str", "default": "'+x'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "direction" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "f0" }, { "annotation": "float", "default": "0.5", "has_default": true, "kind": "KEYWORD_ONLY", "name": "bandwidth" }, { "annotation": "float", "default": "1.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "amplitude" }, { "annotation": "int", "default": "10", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_offset" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ref_offset" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "calibration_preset" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reference_plane" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_plane" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "name" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_modes" }, { "annotation": "str", "default": "'modulated_gaussian'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "waveform" }, { "annotation": "str", "default": "'discrete'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode_profile" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.add_waveguide_port", "returns": { "annotation": "'Simulation'" }, "signature": "(self, x_position: 'float', *, x_range: 'tuple[float, float] | None' = None, y_range: 'tuple[float, float] | None' = None, z_range: 'tuple[float, float] | None' = None, mode: 'tuple[int, int]' = (1, 0), mode_type: 'str' = 'TE', direction: 'str' = '+x', freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 50, f0: 'float | None' = None, bandwidth: 'float' = 0.5, amplitude: 'float' = 1.0, probe_offset: 'int' = 10, ref_offset: 'int' = 3, calibration_preset: 'str | None' = None, reference_plane: 'float | None' = None, probe_plane: 'float | None' = None, name: 'str | None' = None, n_modes: 'int' = 1, waveform: 'str' = 'modulated_gaussian', mode_profile: 'str' = 'discrete') -> \"'Simulation'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2211", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a runtime artifact report dict for this simulation.", "kind": "method", "name": "rfx.Simulation.artifact_report", "parameters": [ { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.artifact_report", "returns": { "annotation": null }, "signature": "(self, result=None, **kwargs: 'Any')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_artifacts.py#L36", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return the B1 face declaration with the current feature requirements.\n\nNo runner consumes this descriptor in B1. ``rcs=True`` collects the\nRCS requirement for a caller preparing that operation.", "kind": "method", "name": "rfx.Simulation.boundary_model", "parameters": [ { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "rcs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.boundary_model", "returns": { "annotation": null }, "signature": "(self, *, rcs: 'bool' = False)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2480", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "EXPERIMENTAL coax<->microstrip transition 2-port S-parameters (issue #489 leg 4).\n\n.. warning::\n **EXPERIMENTAL — not in the validated set**\n (``docs/guides/sparameter_support_matrix.md`` / ``.json``). One\n pre-declared fixture has been run against this method; see that\n fixture's own predeclaration\n (``tests/unit/sparams/test_coax_msl_transition.py``) for the measured\n envelope. NOT_TRACEABLE (see :class:`~rfx.api._spec.\n CoaxMSLTransitionResult`'s class docstring for the full honesty\n contract, including why the MSL side is extracted via the coax\n matrix-pencil fit rather than the diagnostic-only N-probe fit\n #488 uses). Since issue #838 this lane REFUSES by default: a\n non-passive extracted S raises ``ValueError`` unless the caller\n passes ``strict_passivity=False``, which returns the diagnostic\n matrix with a ``UserWarning`` instead.\n\nGeneralizes issue #488's mixed lumped/wire<->MSL assembler\n(:meth:`compute_mixed_s_matrix`) to a coax<->MSL pair by combining,\nUNCHANGED, the less-invasive half of each family's own validated\nmachinery instead of writing a new geometry-specific extractor:\n\n* The **coax side** is built exactly like :meth:`compute_coaxial_two_port`'s\n own single-ended stub (CPML, TEM TFSF source, matched annular-\n resistor feed, then a probe array), reusing\n :func:`~rfx.sources.coaxial_port.stamp_coaxial_line`,\n :func:`~rfx.sources.coaxial_port.stamp_coaxial_annular_resistor`,\n and :func:`~rfx.sources.coaxial_port.build_coaxial_tem_plane_source_specs`\n verbatim — but only ONE end (this method has no second coax port).\n* The **MSL side** is consumed exactly like :meth:`compute_mixed_s_matrix`\n consumes its MSL ports: the caller registers arbitrary DUT\n geometry (substrate, trace, ground plane, and — unique to this\n transition — the ground-plane clearance hole and the vertical\n pin-to-trace post that connects the two families) via the\n ordinary ``sim.add(Box(...)/Cylinder(...), material=...)`` API,\n and this method reuses :func:`~rfx.sources.msl_port.compute_msl_mode_profile`,\n :func:`~rfx.sources.msl_port.setup_msl_port`, and\n :func:`~rfx.sources.msl_port.make_msl_port_sources` verbatim for\n the MSL port's own termination/excitation.\n\nThis method does NOT build the junction geometry itself (the ground\nplane, its clearance hole, or the pin-to-trace post) — those are\nDUT-specific and belong to the caller's own registered geometry,\nexactly as :meth:`compute_mixed_s_matrix` never builds its own\nsubstrate/trace. What this method DOES fix, by construction, is\nWHERE each port's own S-parameter reference plane sits: both are\nplaced AT the physical launch discontinuity (see ``junction_x``\nbelow and ``port.position[2]`` on the registered\n:meth:`add_coaxial_port`), specifically to minimize the\npre-declared \"reference-plane mismatch\" failure mode (the coax's\naxial z-feed-plane convention has no direct analogue in the MSL's\nalong-trace x reference plane — these are different geometric axes\nentirely).\n\nRegistration contract\n----------------------\nExactly one :meth:`add_coaxial_port` (``face='bottom'`` — the\nphysical convention this method assumes: the coax stub is built\nFROM the domain's low-z CPML face UP TO ``position[2]`` (rounded to\nthe nearest grid z-node, half-cell ties to the lower node under\nthe conductor-plane convention), where ``position[0], position[1]`` is the coax\naxis centre (x, y) and ``position[2]`` is the physical height of\nthe caller's OWN registered ground-plane conductor — i.e. this is\nthe ONE parameter that ties this method's auto-built coax stub to\nthe caller's own junction geometry; get it wrong and the pin will\neither dangle in a gap or overlap the caller's own PEC). Exactly\none :meth:`add_msl_port`, whose ``position[2]`` (substrate bottom /\nground height) MUST equal the coax port's ``position[2]`` to within\none grid cell — both refer to the SAME physical ground plane. No\nother ports (lumped/wire/waveguide/Floquet), no TFSF, no lumped\nRLC, no pre-registered probes/DFT planes/flux monitors/NTFF (this\nmethod builds its own). ``self._geometry`` must be non-empty (the\ncaller's substrate/trace/ground-plane/pin-post Boxes and\nCylinders). The MSL source interval must meet its realized conductor\nsurfaces. The auto-built stub stops below the junction node and\npreserves the caller's materials at and above it. These checks do\nnot certify the junction's connectivity or its modal accuracy.\nSame solver/precision/boundary contract as\n:meth:`compute_coaxial_two_port` (float32, 3D uniform Yee,\n``boundary='cpml'`` with positive CPML on all six faces, absorption on\nall three axes): the coax's own far end needs an absorbing z face\nexactly like the coax lane, the MSL trace radiates in x/y too,\nand the caller's own ground plane is an INTERNAL stamped/registered\nPEC layer rather than the domain's z boundary — this is also WHY\nthis method cannot reuse a PEC ``z_lo`` domain boundary as the MSL\nground reference the way :meth:`compute_mixed_s_matrix`'s\n``magnitude_channel=\"flux\"`` fixtures do (that would conflict with\nthe coax's own need for an absorbing z_lo face).\n\nTwo-drive extraction (never a naive single-ratio)\n---------------------------------------------------\nDrives the coax source, then the MSL source, in two separate FDTD\nruns (never assuming the non-driven port sees zero incident wave —\nthe terminator-floor problem :meth:`compute_coaxial_two_port`\nalready solved for symmetric coax applies here too, and likely\nworse, since the coax feed resistor and the MSL Hammerstad-Jensen\ntermination have no reason to share a termination quality). Each\nport's own forward/backward wave amplitudes are recovered from its\nown probe ladder via :func:`~rfx.sources.coaxial_port.\ncoaxial_line_reflection_from_plane_voltages` (Z0-free matrix-pencil\nfit — see :class:`~rfx.api._spec.CoaxMSLTransitionResult` for why\nthis is used for the MSL side too, not the lane's own N-probe fit),\nconverted to POWER waves via each port's own analytic reference\nimpedance, and assembled by\n:func:`~rfx.sources.coaxial_port.solve_two_port_from_wave_amplitudes`\n(the same generic two-drive solve :meth:`compute_coaxial_two_port`\nuses). See :func:`_assemble_coax_msl_transition_from_voltages` for\nthe full pure-assembly derivation.\n\nParameters\n----------\njunction_x : float\n Physical x-coordinate (metres) of the coax-to-trace launch\n discontinuity — the MSL side's own S-parameter reference plane.\n Must match wherever the caller's own registered pin-to-trace\n post / trace Box actually begins; this method does not infer it\n from geometry (mirrors the coax side's own reference plane\n being the registered port's ``position[2]``, not inferred).\neps_r_sub : float, optional\n Substrate relative permittivity. If ``None``, taken from the\n registered :meth:`add_msl_port`'s own ``eps_r_sub`` (which must\n then be set explicitly — this method does not attempt the\n geometry-bounding-box auto-detection :meth:`add_msl_port`\n itself offers, to keep the eps anchor unambiguous for the\n Hammerstad-Jensen Z0 used in the power-wave normalization).\nprobe_count, probe_start_cells, probe_spacing_cells : int\n The COAX side's own probe array (mirrors\n :meth:`compute_coaxial_two_port`'s identically-named\n parameters — this method's coax stub is short by\n construction, between the near-source feed and the junction,\n so these three rarely need to grow).\nmsl_probe_count, msl_probe_start_cells, msl_probe_spacing_cells : int, optional\n The MSL side's OWN probe array, independent of the coax\n parameters above (added issue #489 leg 4 attempt 2 — the two\n families' probe ladders were coupled through one shared set\n of parameters through attempt 1, which is fine when both\n ladders are short but breaks as soon as the MSL side needs a\n ladder spanning a meaningful fraction of a guided wavelength,\n since the coax stub's own short z-extent cannot host the same\n span). Each defaults to ``None``, meaning \"use the\n correspondingly-named coax parameter\" — this preserves\n attempt 1's exact behavior (and its committed fixture's\n numbers) when left unset.\n\n NEAR-FIELD STANDOFF (issue #823) — the one constraint these\n three are NOT free of. Every probe must clear BOTH ends the\n ladder is referred to (the MSL port's own feed plane AND the\n reference plane at ``junction_x``) by at least\n ``max(3, round(5*h_sub/dx))`` cells. Both are launch\n discontinuities, and within a few substrate thicknesses of one\n the field is not the guided mode yet, so a matrix-pencil fit\n that includes such a probe reports the LADDER's error as the\n field's: on the settled attempt-3 run (VESSL 369367257533) a\n single probe 0.4 mm = 1.33*h_sub from the feed dragged the\n full-ladder residual from 3.7e-3 to 0.342, and this lane spent\n three attempts attributing that to junction physics. The\n threshold is the repo's EXISTING issue-#80 Fix B constant —\n see :func:`rfx.api._preflight.msl_source_near_field_standoff_cells`\n for the derivation that licenses reusing it here, and for the\n W/h limitation it carries. Preflight cannot enforce it on this\n lane (these are METHOD arguments and never reach the\n registered ``_MSLPortEntry``), so this method evaluates the\n same predicate on its own REALIZED ladder and emits a\n ``UserWarning`` naming the offending probes. REPORT-ONLY:\n nothing is refused. Read it together with\n ``result.ladder_split_gamma_dev`` /\n ``result.ladder_split_reflection_decades`` (computed when\n ``return_ladder_voltages=True``, ``None`` otherwise), which say\n whether the ladder actually disagrees with itself.\nstrict_passivity : bool, default ``True``\n Default ``True``: this lane REFUSES a non-passive extracted S,\n raising ``ValueError`` from the shared guard\n (:func:`_warn_if_nonpassive_smatrix` via\n :func:`_finalize_sparam_result`) instead of returning the matrix.\n Pass ``strict_passivity=False`` to get the diagnostic matrix back\n with a ``UserWarning`` instead of the raise. The default is\n ``True`` here and ``False`` on the single-family coax two-port lane\n (:meth:`compute_coaxial_two_port`), which is unaffected by this\n (issue #838, PI decision 2026-09-20).\n\n``extra_flux_monitors`` (issue #589 flux-adjudication instrument):\nan ENERGY-WITNESS channel, not an extractor change. Pass the entry\nobjects ``Simulation.add_flux_monitor`` registers (build them on a\nscratch ``Simulation`` with the same domain and hand over its\n``._flux_monitors``); each internal drive run then accumulates the\nrequested Poynting-flux planes, and per-drive spectra come back\nname-keyed on ``result.flux_monitors``\n(``{\"coax\"|\"msl\": {monitor_name: (n_monitor_freqs,) float64}}``,\nnet flux, positive = +axis). The S-parameter math is untouched —\nthe non-perturbation witness (S bit-identical with and without\nmonitors) is gated in\n``tests/unit/sparams/test_coax_msl_transition.py::test_extra_flux_monitors_do_not_perturb_s``.\nThe registered-monitor guard is unchanged: monitors registered ON\nthis sim still raise, because this method builds its own probes.\n\nUnless ``skip_preflight=True``, the shared sheet-size verdict runs\nbefore stepping: ``snap=\"strict\"`` blocks an off-size sheet and\n``snap=\"declared\"`` warns. Other preflight families are not run here.\n\n``return_ladder_voltages`` (issue #589 label-independent ladder dump):\na second read-only channel, additive in exactly the same sense. When\n``True``, the RAW per-probe modal voltages this method already\ncomputed for both drives are attached to\n``result.ladder_voltages`` (``None`` otherwise) so the ladders can be\nre-read OFFLINE — adjacent-pair phase slope (which way the dominant\nwave travels), standing-wave ratio, subset matrix-pencil fits —\nwithout a second FDTD run and without trusting any incident/outgoing\nLABEL. The dict is documented field-by-field on\n:class:`~rfx.api._spec.CoaxMSLTransitionResult`. It is built from\n``.copy()`` of arrays that are complete before, and consumed by,\n:func:`_assemble_coax_msl_transition_from_voltages`, so every\nS-parameter number is bit-identical with the option off or on —\ngated by ``tests/unit/sparams/test_coax_msl_transition_ladder_dump.py::\ntest_return_ladder_voltages_does_not_perturb_s`` (byte-identity A/B,\nthe same discipline as the flux witness above; the round-trip\nassertion there also proves the dump IS what the assembler consumed).\nThe same flag switches on the issue-#823 LADDER SELF-CONSISTENCY\nWITNESS, ``result.ladder_split_gamma_dev`` /\n``result.ladder_split_reflection_decades`` (``None`` when the flag\nis off): a disjoint-half refit of each ladder, i.e. a Python loop of\n2 drives x n_freqs x 2 matrix pencils per ladder over exactly the\narrays the dump exposes. It is computed AFTER the assembler from\nthose arrays and moves no S-parameter number; it is opt-in so that\na default call pays for no extra pencil solves. Documented\nfield-by-field on :class:`~rfx.api._spec.CoaxMSLTransitionResult`.\n\nReturns\n-------\nCoaxMSLTransitionResult", "kind": "method", "name": "rfx.Simulation.compute_coax_msl_transition", "parameters": [ { "annotation": "float", "default": null, "has_default": false, "kind": "KEYWORD_ONLY", "name": "junction_x" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_r_sub" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "30.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "'jnp.ndarray | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "11", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "float", "default": "10000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_scale" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_count" }, { "annotation": "int", "default": "6", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_start_cells" }, { "annotation": "int", "default": "3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_spacing_cells" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "msl_probe_count" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "msl_probe_start_cells" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "msl_probe_spacing_cells" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "feed_impedance" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cond_warn" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict_passivity" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "'list | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "extra_flux_monitors" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_ladder_voltages" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_coax_msl_transition", "returns": { "annotation": "'CoaxMSLTransitionResult'" }, "signature": "(self, *, junction_x: 'float', eps_r_sub: 'float | None' = None, n_steps: 'int | None' = None, num_periods: 'float' = 30.0, freqs: \"'jnp.ndarray | None'\" = None, n_freqs: 'int' = 11, field_scale: 'float' = 10000.0, probe_count: 'int' = 8, probe_start_cells: 'int' = 6, probe_spacing_cells: 'int' = 3, msl_probe_count: 'int | None' = None, msl_probe_start_cells: 'int | None' = None, msl_probe_spacing_cells: 'int | None' = None, feed_impedance: 'float | None' = None, cond_warn: 'float' = 1000.0, strict_passivity: 'bool' = True, skip_preflight: 'bool' = False, extra_flux_monitors: \"'list | None'\" = None, return_ladder_voltages: 'bool' = False) -> \"'CoaxMSLTransitionResult'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/coax.py#L1125", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "One-port coaxial reflection on a real transmission line (broad-E5).\n\nBuilds a coextensive coax line (face='top', pin along -z) terminated in a\nmatched resistive feed near the +z boundary, drives a TEM TFSF source one\ncell below the feed, and reflects off a calibration ``termination`` at the\n-z end: ``\"short\"`` (Γ=-1), ``\"open\"`` (Γ=+1), or ``\"matched\"`` (Γ→0).\nWith ``termination=\"matched\"`` and ``dut_impedance=R`` the DUT is instead a\nknown resistive load (analytic ``Γ=(R-Z0)/(R+Z0)``) — used by the broad-E5\nenvelope to test non-trivial reflection magnitudes against exact truth.\nThe reflection is read from the modal voltage ``V(z)=∫E_r dr`` sampled at\n``probe_count`` equally spaced planes and a matrix-pencil estimate of the\ncomplex propagation constant (β self-measured, Z0-free).\n\nUnlike the single-plane coaxial lane removed in #1212 (V/I in a hardcoded\nclosed PEC box — non-physical |S11|>1), this uses an absorbing CPML feed\nso a real line exists. **Resolution recipe**: keep ≥~4 cells across the\n(outer-inner) annulus (raise ``freq_max`` to shrink ``dx``); the result\n``status`` reports ``\"under_resolved\"`` below ~3.5 cells.\n\nThe conductors deliberately stop ~2 cells short of the +z PML — running\nPEC into CPML is numerically unstable.\n\nThe line sits in open space: the run absorbs on all three axes\n(``cpml_axes=None`` reads the grid; all three axes are required), so what\nleaves the line's unshielded ends — the open termination, and the pin and\nshell ending one cell past the matched feed — is absorbed as it would\nradiate from a cable. ``cpml_axes=\"z\"`` is refused: it left the lateral\npads as vacuum backed by the PEC grid faces, a closed metal can that held\nthat field, and the open's |S11| rose above 1 and grew with the record\n(issue 1218).\n\nThe enclosing :class:`Simulation` must use float32 precision and the\nthree-dimensional, second-order uniform Yee solver with\n``boundary=\"cpml\"`` and ``cpml_layers > 0``. Unsupported precision,\nsolver, grid, boundary, TFSF, and refinement settings raise before the\ngrid is built. The run requires positive CPML thickness on all six faces\nand no periodic-axis override, and the line's conductors must keep at\nleast one whole cell from every lateral absorber (the stamper refuses a\nline without that room).\n\nThis method constructs its own coaxial line, TEM source, DFT planes, and\ntermination. Do not add separate geometry, thin conductors, lumped RLC\nelements, probes or field monitors, or NTFF boxes; those registrations\nare rejected rather than ignored. Use the documented :class:`Simulation`, port, and method\narguments instead.\n\nThe registered coaxial port supplies its x/y centre, ``face``, inner\nand outer radii, and excitation waveform. The method derives its axial\nlayout internally, so the port's z coordinate and ``pin_length`` do not\nplace the line, and the port's ``impedance`` does not set either load.\nUse ``feed_impedance`` for the feed and ``dut_impedance`` only with\n``termination=\"matched\"``. ``probe_count`` must be an integer of at\nleast three, and every requested plane must fit between the DUT and\nsource; otherwise the method raises before starting the FDTD run.\n\nDifferentiable (``eps_scale``)\n------------------------------\nPass ``eps_scale`` (a scalar or ``(nx, ny, nz)`` ``jnp`` array) to make\nthe reflection differentiable w.r.t. the dielectric under ``jax.grad``.\nIt MULTIPLIES the stamped ``eps_r`` (``eps_r <- eps_r * eps_scale``),\napplied AFTER the numpy conductor/dielectric stamps so the fixed geometry\n(PTFE fill in ``eps_r``, PEC pin/shell in ``sigma``) is preserved and only\nmodulated — a well-conditioned design channel (unlike replacing the fill\nwith air). When provided, the field→voltage→reflection assembly runs on\nthe ``jax.numpy`` path (``coaxial_line_plane_voltage_jnp`` + the traced\nextractor) so the gradient flows design → FDTD → DFT planes → Γ. With\n``eps_scale=None`` the result is byte-identical to the validated numpy\npath. The AD↔FD gate is ``tests/unit/autodiff/test_coax_end_to_end_ad.py``.", "kind": "method", "name": "rfx.Simulation.compute_coaxial_line_reflection", "parameters": [ { "annotation": "str", "default": "'short'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "termination" }, { "annotation": "int", "default": "6000", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "11", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "float", "default": "10000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_scale" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dut_offset_cells" }, { "annotation": "int", "default": "12", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_count" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_start_cells" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_spacing_cells" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "feed_impedance" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "dut_impedance" }, { "annotation": "'jnp.ndarray | float | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_scale" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_coaxial_line_reflection", "returns": { "annotation": "'CoaxialLineReflectionResult'" }, "signature": "(self, *, termination: 'str' = 'short', n_steps: 'int' = 6000, freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 11, field_scale: 'float' = 10000.0, cpml_axes: 'str | None' = None, dut_offset_cells: 'int' = 4, probe_count: 'int' = 12, probe_start_cells: 'int' = 8, probe_spacing_cells: 'int' = 4, feed_impedance: 'float | None' = None, dut_impedance: 'float | None' = None, eps_scale: \"'jnp.ndarray | float | None'\" = None) -> \"'CoaxialLineReflectionResult'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/coax.py#L118", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Two-drive coaxial 2-port S-parameters (#489 stage 2) — VALIDATED WITH SCOPE.\n\n.. note::\n **VALIDATED WITH SCOPE, not EXPERIMENTAL** (issue #489, PI\n decision 2026-08-06 —\n ``docs/guides/sparameter_support_matrix.md``, the S-parameter\n family companion where this row lives). Covered: the two-port\n through-line class on this single coax geometry family, bracketed\n by an external openEMS referee (crossval 21) on ``|S21|`` and,\n via the port's own measured ``beta``, phase; a mesh-refinement\n convergence witness (``p ~= 1.5``); an end-to-end ``eps_scale``\n AD gate (``GRAD_SAFE``); and this method's own measured\n reciprocity/``cond(A)``. NOT covered: every DUT this method can\n currently gate against is azimuthally symmetric (TM0n only) —\n transition discontinuities that excite TE11 are still outside\n this evidence (see :meth:`compute_coax_msl_transition`, which\n stays EXPERIMENTAL, diagnostic-only), nor does the evidence\n generalize to other coax geometry families. See the class\n docstring on the returned :class:`CoaxialTwoPortResult` for the\n full evidence chain and scope statement.\n\nBuilds ONE through coax line spanning the z axis with a matched\nannular-resistor feed near EACH z end (mirroring the validated\n1-port :meth:`compute_coaxial_line_reflection` layout at both ends:\neach feed sits between that end's own TEM TFSF source and that end's\nown CPML, i.e. strictly on the scattered-only side of that drive's\nTFSF boundary — never in the path of that drive's own launched\nwave), then drives each end's source in turn (two separate FDTD\nruns). A probe array of ``probe_count`` equally spaced planes near\neach end recovers that array's local two-wave decomposition\n(matrix-pencil, Z0-free, same machinery as the 1-port method); the\nforward/back amplitudes are evaluated at each port's OWN reference\nplane (its feed's axial position) and assembled into a full 2x2\nS-matrix via :func:`rfx.sources.coaxial_port.\nsolve_two_port_from_wave_amplitudes` — the two-drive solve that does\nNOT assume the non-driven port sees zero incident wave (unlike the\nnaive ``S[j,i] = b_j/a_i`` ratio, which has a hard terminator-\nreflection floor on a through line; see that function's docstring\nand ``docs/research_notes/20260729_i489_coax_two_port_design.md``).\n\nPort 1 is the +z end (mirrors the 1-port fixture's own ``face='top'``\norientation); port 2 is the -z end (mirror image, ``face='bottom'``).\nBoth drives share the SAME registered ``add_coaxial_port(...)``\ngeometry (x/y centre, pin/outer radii) and excitation waveform; the\nregistered port's own ``position``/``face``/``pin_length`` do not\nplace either end of the line (mirrors the 1-port method's own\ncontract). Requires ``port.face == 'top'`` (arbitrary but consistent\nwith the 1-port method; the value is not otherwise used to orient\nthis method's own internally-built fixture).\n\nUnlike the 1-port method, the returned result is routed through\n:func:`_finalize_sparam_result` (which runs the passivity/finiteness\nself-check via :func:`_warn_if_nonpassive_smatrix`) before being\nreturned — the 1-port ``CoaxialLineReflectionResult`` bypasses that\ncheck (design-note incidental defect 3); this result does not.\n\nThis method constructs its own coaxial line, TEM sources, DFT\nplanes, and feeds. Do not add separate geometry, thin conductors,\nlumped RLC elements, probes or field monitors, NTFF boxes, or TFSF\nsources; those registrations are rejected rather than ignored.\n\nSame solver/precision/boundary contract as\n:meth:`compute_coaxial_line_reflection` (float32, 3D uniform Yee,\n``boundary='cpml'`` with positive CPML thickness on all six faces,\n``cpml_axes='xyz'``, no periodic axes, no non-uniform mesh, no\nrefinement). The run absorbs on all three axes: the line's two ends,\none cell past each feed, are unshielded, and with absorbers on z only\nthe lateral pads were a closed PEC can that held the field leaving them\n(issue 1218). ``cpml_axes='z'`` is refused.\n\nDifferentiable (``eps_scale``, #489 leg 3)\n-------------------------------------------\nPass ``eps_scale`` (a scalar or ``(nx, ny, nz)`` ``jnp`` array) to make\nthe S-matrix differentiable w.r.t. the dielectric under ``jax.grad`` —\nsame name, semantics, and MULTIPLIES-the-stamped-``eps_r`` design as\nthe 1-port :meth:`compute_coaxial_line_reflection`'s own ``eps_scale``\n(``eps_r <- eps_r * eps_scale``, applied once, after both feed stamps,\nso it reaches BOTH drives' FDTD runs — the through line has no DUT\nbreak to scope it to). When provided, both drives route their\nvoltage extraction through :func:`rfx.sources.coaxial_port.\ncoaxial_line_plane_voltage_jnp` (the same differentiable twin the\n1-port path uses) instead of the concrete\n:func:`~rfx.sources.coaxial_port.coaxial_line_plane_voltage`, and the\nassembly (:func:`_assemble_coaxial_two_port_from_voltages`) and the\ntwo-drive solve (:func:`~rfx.sources.coaxial_port.\nsolve_two_port_from_wave_amplitudes`) both dispatch to their own jnp\ncores. With ``eps_scale=None`` the result is byte-identical to the\nvalidated numpy path (dual-path design, not a rewrite — mirrors the\n1-port method's own contract). The per-drive ring-down ``settling_db``\nwitness needs a concrete time series and is skipped on this path\n(stays ``nan``, same reasoning as the 1-port method's own\n\"can't Python-branch on a tracer\" note on its ``rec_resid``\ncontamination check); ``status`` is therefore ``\"under_resolved\"`` or\n``\"differentiable\"`` here, never ``\"contaminated\"``/``\"passed\"``.\n``cond_warn`` is also silently INERT on this path: the ill-\nconditioning warning it controls is Python control flow keyed on a\nconcrete ``cond(A)`` value\n(:func:`rfx.sources.coaxial_port.solve_two_port_from_wave_amplitudes`'s\nNumPy branch), which the traced jnp core\n(``_solve_two_port_from_wave_amplitudes_jnp``) cannot evaluate and\ndoes not attempt to — this mirrors the ``settling_db``/``status``\nlosses above (same \"can't Python-branch on a tracer\" reason), not a\nseparate defect; ``cond_a`` is still RETURNED (as a tracer), so a\ncaller can inspect it after concretizing the result if degeneracy\nmatters to them. The AD gate is ``tests/unit/autodiff/test_coax_two_port_ad.py``.\n\n``extra_flux_monitors`` (issue #589 flux-adjudication instrument):\nan ENERGY-WITNESS channel, not an extractor change. Pass the entry\nobjects ``Simulation.add_flux_monitor`` registers (build them on a\nscratch ``Simulation`` with the same domain and hand over its\n``._flux_monitors``); each internal drive run then accumulates the\nrequested Poynting-flux planes, and per-drive spectra come back\nname-keyed on ``result.flux_monitors``\n(``{port_name: {monitor_name: (n_monitor_freqs,) float64}}``, net\nflux, positive = +axis). The S-parameter math is untouched — the\nnon-perturbation witness (S bit-identical with and without\nmonitors) is gated in\n``tests/unit/sparams/test_coax_msl_transition.py::test_extra_flux_monitors_do_not_perturb_s``.\nThe registered-monitor guard is unchanged: monitors registered ON\nthis sim still raise, because this method builds its own probes.", "kind": "method", "name": "rfx.Simulation.compute_coaxial_two_port", "parameters": [ { "annotation": "int", "default": "6000", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "11", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "float", "default": "10000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "field_scale" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cpml_axes" }, { "annotation": "int", "default": "12", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_count" }, { "annotation": "int", "default": "8", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_start_cells" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "probe_spacing_cells" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "feed_impedance" }, { "annotation": "float", "default": "1000.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "cond_warn" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict_passivity" }, { "annotation": "'jnp.ndarray | float | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_scale" }, { "annotation": "'list | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "extra_flux_monitors" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_coaxial_two_port", "returns": { "annotation": "'CoaxialTwoPortResult'" }, "signature": "(self, *, n_steps: 'int' = 6000, freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 11, field_scale: 'float' = 10000.0, cpml_axes: 'str | None' = None, probe_count: 'int' = 12, probe_start_cells: 'int' = 8, probe_spacing_cells: 'int' = 4, feed_impedance: 'float | None' = None, cond_warn: 'float' = 1000.0, strict_passivity: 'bool' = False, eps_scale: \"'jnp.ndarray | float | None'\" = None, extra_flux_monitors: \"'list | None'\" = None) -> \"'CoaxialTwoPortResult'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/coax.py#L540", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Mixed-family S-matrix: lumped/wire ports + MSL ports (issue #488).\n\nEnd-to-end S-parameters on ONE structure carrying two port\nfamilies — the first supported pair is a homogeneous lumped OR\nwire set (``add_port``) together with MSL ports (``add_msl_port``),\ne.g. a vertical probe feed launching onto a microstrip line.\n\nEach port is driven in turn (lumped/wire ports first, then MSL\nports, registration order within each family); the non-driven\nlumped/wire ports remain physical matched resistor loads and the\nnon-driven MSL ports are passive probe columns. Extraction reuses\nthe validated per-family wave machinery unchanged and combines the\nwaves in the **Kurokawa power-wave convention** (each wave divided\nby ``sqrt(Re Z0)`` of its own port) — with unequal reference\nimpedances across families a pseudo-wave ratio would be off by\n``sqrt(Z_j/Z_i)`` (issue #460); reciprocity of a reciprocal\nstructure is the committed internal falsifier for this choice.\n\nMAGNITUDE CHANNEL (``magnitude_channel``, default ``\"flux\"``):\nthe #488 falsifier battery + an independent Poynting-flux referee\nmeasured the port-cell V*I accounting undercounting delivered\npower ~3x at a wire probe feed (the OPEN issue-#313 class) and\nthe analytic Hammerstad-Jensen Z0 anchor diverging from the\nmeasured line ratio on an interface-aligned mesh. Off-diagonal\nMAGNITUDES are therefore taken from Poynting flux by default:\nauto-registered surfaces (a closed 5-face box around each\nlumped/wire port over the z-lo ground; a full cross-section plane\nat each MSL port's probe-0 x) give per-drive net powers, and\n\n |S_ij|^2 = P_arrive,i / (P_net,j / (1 - |S_jj|^2))\n\nwhere ``S_jj`` is the per-family diagonal supplying the reflection\ncorrection; no Z0 anchor enters the magnitude. Off-diagonal PHASE\nstill comes from the wave channel (see below).\n``magnitude_channel=\"wave\"`` keeps the raw power-wave magnitudes\n(diagnostic; carries the #313 deflation at lumped/wire ports).\n\nHONESTY NOTES (read before quoting numbers):\n\n* **Neither diagonal is verified on this lane, and the returned\n diagonal is not always the measured one.** Two separate\n findings: (a) the wire port-cell V*I accounting was measured\n undercounting delivered power ~3x against an independent\n Poynting referee (the open issue #313 reaching the diagonal at\n a near-field-dominated vertical probe), and on an end-fed\n fixture the MSL probe plane's local ``V/I`` was ~591 ohm and\n strongly reactive while the reported ``|S22|`` was 0.03 — those\n cannot both be right. (b) With ``enforce_passivity=True`` (the\n default), ``_project_passive`` is a JOINT SVD clip: when any\n entry is non-passive it rewrites others as a side effect.\n Measured on the committed test fixture, the shipped MSL\n diagonal came out ~4x its unprojected value. So ``result.S``'s\n diagonal is a projected quantity, not a raw per-family\n measurement — read ``S_raw`` and ``passivity_correction`` for\n what was actually measured, and treat any diagonal-derived\n conclusion accordingly.\n\n* The flux magnitudes inherit a flux-accounting envelope (box\n leakage + finite DFT; the Phase-0 referee class measured ~1.3%\n on the canonical thru) and an ill-conditioning guard: when\n ``1 - |S_jj|^2`` is small (near-total reflection at the driven\n port) the normalization is unreliable and a warning names the\n column.\n* **A per-column power sum near 1 is NOT evidence on this\n channel.** Substituting the definition gives\n ``sum_i |S_ij|^2 = |S_jj|^2 + (P_arr/P_net)(1 - |S_jj|^2)``,\n which is identically 1 whenever the arriving power equals the\n net launched power — for ANY value of the diagonal. The flux\n normalization makes passivity an identity, not a measurement,\n so do not quote column power as a passivity check here (it\n still detects power GAIN, i.e. ``P_arr > P_net``). The\n independent internal check on this channel is RECIPROCITY:\n ``S_ij`` and ``S_ji`` come from different runs with different\n normalizations, so their agreement is real evidence. It runs\n automatically on every extraction (see ``reciprocity_tol``),\n audits the RAW matrix, and is the check that a wrong diagonal\n trips.\n* With ``magnitude_channel=\"wave\"``, off-diagonal magnitudes that\n RECEIVE at a lumped/wire port cell inherit the issue-#313\n near-field deflation of the default port-cell waves. The\n returned ``s21_power_witness`` cross-checks the MSL-receiving\n direction against a delivered-power normalization; quote it\n alongside ``|S|``.\n* Cross-family off-diagonal PHASE mixes two reference-plane\n conventions (port cell vs de-embedded MSL probe plane) and a\n component-mixing ±1 (probes.py sign-convention fence);\n magnitude is the validated observable.\n* ``settling_db`` is the ring-down witness (above −40 dB =\n truncation suspect); preflight output is part of the result.\n\nv1 restrictions (loud ``NotImplementedError``): uniform mesh only,\nno waveguide/Floquet/coax/TFSF registrations, no bare sources or\n0-ohm ports (they would fire in every drive run), no\n``reference_plane_cells`` wire ports, no mixed lumped+wire set\n(same fence as the production scan driver), imperative only (no\n``eps_override`` AD channel). The default ``\"flux\"`` channel adds\ntwo more, because the per-port flux box omits its bottom face and\ntreats the port extent as a height: a **PEC ``z_lo`` boundary**\nand **vertical (``component=\"ez\"``) lumped/wire ports** are\nrequired. ``magnitude_channel=\"wave\"`` makes neither assumption.\n\nParameters\n----------\nreciprocity_tol : float, default 0.06\n Relative ``|S_ij|`` vs ``|S_ji|`` disagreement above which the\n reciprocity witness warns. Deliberately set BELOW the 9%\n residual measured on this lane's own reference fixture, so\n that fixture warns rather than passing silently: a tolerance\n above the known residual would document the check and never\n fire it.\n\nReturns\n-------\nMixedSMatrixResult", "kind": "method", "name": "rfx.Simulation.compute_mixed_s_matrix", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "40.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "'jnp.ndarray | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict_extractor" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "enforce_passivity" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "return_diagnostics" }, { "annotation": "str", "default": "'flux'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "magnitude_channel" }, { "annotation": "float", "default": "0.06", "has_default": true, "kind": "KEYWORD_ONLY", "name": "reciprocity_tol" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_mixed_s_matrix", "returns": { "annotation": "'MixedSMatrixResult'" }, "signature": "(self, *, n_steps: 'int | None' = None, num_periods: 'float' = 40.0, freqs: \"'jnp.ndarray | None'\" = None, n_freqs: 'int' = 100, strict_extractor: 'bool' = False, enforce_passivity: 'bool' = True, skip_preflight: 'bool' = False, return_diagnostics: 'bool' = False, magnitude_channel: 'str' = 'flux', reciprocity_tol: 'float' = 0.06) -> \"'MixedSMatrixResult'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/mixed.py#L66", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute MSL S from probe-plane V/I with fitted line diagnostics.\n\nReturned S uses power waves for the positive real per-port analytic\nreferences: a=(V+R*I)/(2*sqrt(R)), b=(V-R*I)/(2*sqrt(R)).\n``reference_impedances`` records those R values separately from the\nfitted ``Z0`` and source/load resistances. For unequal references,\ntransmission S differs from the legacy voltage ratio by\nsqrt(R_input/R_output); equal-reference results are unchanged.\n\n``S`` is the RAW extracted S-matrix on every channel — concrete,\n``eps_override``, traced — and the default ``enforce_passivity=False``\nis what makes that one statement instead of three. The projection\nbelow cannot run under tracing or on the ``eps_override`` channel (it\nwould zero the gradient wherever the clip bites), so while it was the\ndefault the S a caller measured and the S ``jax.grad`` differentiated\nwere different functions wherever it bit. One function, chosen to be\nthe measured one (PI decision, 2026-09-21; the contract is\n``docs/design_notes/chain_closure_contract.md``).\n\nA raw S may exceed the passive bound, and the result says so rather\nthan hiding it: ``sigma_max_excess[k] = max(sigma_max(S(f_k)) - 1, 0)``\nis filled on every concrete call (``None`` only under tracing), and a\nwarning names the bin count and the worst ``sigma_max`` whenever any\nbin exceeds 0. A passive structure cannot scatter more power than it\nreceives, so such a bin is a measurement artifact — the usual causes\nare a record that ended before the structure rang down and a mesh too\ncoarse for the geometry (``settling_db`` and ``reliable`` say which).\n\n``enforce_passivity=True`` opts back into the post-process: the\nassembled S(f) is projected onto the passive set per frequency\n(singular values clipped to 1 — the nearest matrix in spectral norm\nwith ``||S||_2 <= 1``), the unprojected matrix is kept in ``S_raw``,\nthe per-bin clip amount in ``passivity_correction``, and a warning\nnames the touched bins. It is constraint enforcement, not a physics\nfix, and it is NOT small where the raw extraction is bad: on a thru\nfixture whose raw sigma_max ran 1.19-1.91, projecting moved |S21|\n1.000 -> 0.61-0.72 and rotated its phase by up to 17 degrees, while\n``Z0`` and ``beta`` stay raw. Never quote projected values as physics\nwhere ``passivity_correction`` is large.\n\nEXEMPTION (unchanged): even with ``enforce_passivity=True`` no\nprojection is applied under tracing or on the ``eps_override``\nchannel (traced or concrete), so that finite-difference and\n``jax.grad`` objectives see the same function; ``S`` is then the raw\nextraction with ``S_raw``/``passivity_correction`` absent and no\nprojection warning. ``sigma_max_excess`` is still filled on the\nconcrete ``eps_override`` channel, so the bound violation stays\nvisible there (measured sigma_max 1.18 on a coarse thru).\n\nSurface-impedance sheets (``add_thin_conductor(...,\nsurface_impedance_f0=...)``) are supported on this lane (#677/#679):\nthe sheet is realized node-thin by the per-step operator inside the\n``run()``/``forward()`` device dispatches — no lane-level ctx is\nbuilt here. Combination refusals fire downstream at whichever lane\nentry the call actually reaches, and the two channels carry their\nOWN copies: on ``run()`` the dispersive-substrate and\n``boundary='upml'`` refusals come from ``run_uniform`` with run-lane\nwording, while the ``forward()`` / ``eps_override`` channel never\nenters ``run_uniform`` and raises instead from the forward-lane\nentry in ``rfx/api/_execute.py``, naming that lane. #679 added the\n``upml`` half there: before it, an ``eps_override`` call on a\n``boundary='upml'`` sim silently ran the very combination ``run()``\nrefuses (the sheet operator overwriting UPML's split-field E update\nat its edges). ADI refuses on both channels through the shared\n``refuse_f0_sheets`` helper; the subgridded and distributed lanes\ncarry their own call sites at whichever entry reaches them —\n``FENCE_REGISTRY`` in ``tests/unit/materials/test_sheet_impedance.py`` is the\nauthoritative per-lane list, AST-guarded against drift.\n``subpixel_smoothing`` / ``conformal_pec`` are ``run()``-only\nkeywords, so that combination is unreachable on the ``eps_override``\nchannel rather than refused there.\nThe TRACE must remain PEC: an f0 sheet realizes no PEC edge, and\nthe closed Ampere-loop current and the V span anchor on the\nrealized PEC wall planes (#931 §1.9 — a PEC trace may be a volume\nBox or a sheet; both are found). The Hammerstad-Jensen beta/Z0 anchors\nand the real-beta N-probe fit assume a lossless line, so a sheet\nlying INSIDE a probed span adds per-length loss the fit cannot\nrepresent — reported ``Z0``/``q`` shift (the Z0 honesty guard may\nwarn) while the V-I production S stays valid. A non-z-normal sheet\n(x/y-normal) carries Ez in its tangential edge set: crossing the\nfeed plane or the V-integration column it legitimately modifies the\nmeasured/launched Ez — place sheets clear of feed and probe planes.\n\nFor each registered MSL port, runs one FDTD simulation with that\nport driven and the others passive. The passive ports are NOT\nassumed matched — ``|a_passive/a_driven| = 0.243-0.248`` at the\nshipped R = 50 Ω (0.19-0.93 across terminations), re-measured on\ncurrent main 2026-08-30 (#524, VESSL 369367257265, PR #799; the\nJuly figure quoted here before was 0.07-0.51) — so the S-matrix is\nrecovered by solving the\nfull wave system ``S = B·A⁻¹`` over all drives rather than by the\nper-column ratio ``b_j/a_d`` (issue #507; the ratio reported the far\nport's echo as the structure's own reflection). At each port\n``n_probes`` downstream DFT plane probes record Ez and the first\nprobe also records the transverse H components for a closed\nAmpere-loop current. Production S is formed from this first-plane\nV/I and the analytic Hammerstad-Jensen reference impedance. The\nN-probe least-squares fit of\n``V_n = α e^{-jβx_n} + γ e^{+jβx_n}`` supplies only the reported\nbeta/Z0 diagnostics. Those fitted values do not enter S. S is\nreferenced to each first probe plane, without translation back to\nthe physical feed planes. The two bracketing H planes are linearly\ninterpolated to the E-node using their physical coordinates, then\nthe leapfrog temporal offset is corrected. Comparing different\nobservation offsets still requires accounting for reference planes\nand impedances. ``probe_clearance`` reports the separate downstream\nlayout recommendation; it is not a signal or accuracy score.\n\nParameters\n----------\nn_steps : int or None\n Timesteps per FDTD run. ``None`` → auto from ``num_periods``.\nnum_periods : float\n Source-period multiples used to derive ``n_steps`` when not\n provided. Default 40 (MSL transients are slow to drain).\nfreqs : array, optional\n Frequency grid. Defaults to\n ``linspace(freq_max / 10, freq_max, n_freqs)``.\nn_freqs : int\n Number of frequencies if ``freqs`` is None.\nraw_3probe_dump_path : str or None\n Optional ``.npz`` path. When provided, write the real\n simulation-derived N-probe voltage/current phasors used by the\n extractor, together with the production power-wave S-matrix, so the\n de-embedding can be independently checked without rerunning\n FDTD. The dump schema is ``rfx.msl_nprobe_dump`` v4: it explicitly\n records the power-wave convention and actual reference impedances.\n Legacy v3 records use voltage waves. ``raw_v`` has shape\n ``(n_driven, n_ports, n_probes_max, n_freqs)``.\n ``scripts/diagnostics/replay_msl_3probe_dump.py`` is SUPERSEDED\n for modern dumps (it expects the retired 3-probe/single-ratio\n v1 schema). Use ``rfx.validation.load_port_vi_dump_npz`` and\n ``replay_smatrix_from_port_vi_dump`` for independent S replay.\nstrict_extractor : bool\n Honesty guard for the de-embedding (issue #80 Fix A). After\n extraction, the per-frequency ``|q|`` and extracted ``Z0``\n are validated against physical bounds (``|q| <= 1`` for a passive\n line; extracted ``Z0`` within 10 % of the analytic\n Hammerstad-Jensen value). When ``False`` (default) a violation\n raises a loud :func:`warnings.warn`; when ``True`` it raises\n :class:`ValueError` instead. With the N-probe extractor (Fix C)\n ``|q|`` and ``Z0`` should be healthy so this rarely fires — it\n is the safety net for pathological geometries.\nenforce_passivity : bool\n Opt into the passivity projection as a post-process. ``False``\n (default) returns the raw extracted ``S``; see the section above\n for what each setting costs and which channels the projection can\n reach. Changed from ``True`` on 2026-09-21.\ncheckpoint_segments : int or None\n Gradient-checkpointing segment count for the reverse-mode AD tape on\n the **uniform** mesh (the standard MSL path), forwarded to\n :meth:`forward` (only active on the differentiable ``eps_override``\n channel). Must DIVIDE the auto-computed ``n_steps`` exactly — padding\n is rejected because it would shift the DFT accumulator windows.\n Choose the divisor nearest ``sqrt(n_steps)`` so backward memory scales\n ~``sqrt(n_steps)*carry`` instead of ``n_steps*carry`` — required for\n converged ``num_periods>=20`` AD that otherwise OOMs (G-AD-CHECKPOINT).\n Default ``None`` leaves forward-only runs and small-period AD unchanged.\ncheckpoint_every : int or None\n Non-uniform-mesh counterpart of ``checkpoint_segments`` (chunk size,\n not segment count; issue #73). Forwarded to :meth:`forward`; raises\n ``NotImplementedError`` on the uniform path — use\n ``checkpoint_segments`` there.\nreport_every : int or None\n Issue #667 — progress reporting for long solves. Forwarded to\n each per-drive :meth:`run` call, tagged ``MSL drive pI/N`` so\n the drives are distinguishable in a log. ``None`` (default) is\n OFF and leaves the solve byte-identical. The measured case this\n exists for: a 42.15 M-cell / 225,000-step call whose last log\n line was written at second 0 and was still the last line 4 h\n 10 min later, with no way to tell slow from wedged. Ignored\n (with a warning) on the differentiable ``eps_override``\n channel, which routes through the traced :meth:`forward`.\n\nReturns\n-------\nMSLSMatrixResult", "kind": "method", "name": "rfx.Simulation.compute_msl_s_matrix", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "40.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "freqs" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_freqs" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "raw_3probe_dump_path" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict_extractor" }, { "annotation": "'jnp.ndarray | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_override" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "enforce_passivity" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_every" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_msl_s_matrix", "returns": { "annotation": "'MSLSMatrixResult'" }, "signature": "(self, *, n_steps: 'int | None' = None, num_periods: 'float' = 40.0, freqs: 'jnp.ndarray | None' = None, n_freqs: 'int' = 100, raw_3probe_dump_path: 'str | None' = None, strict_extractor: 'bool' = False, eps_override: \"'jnp.ndarray | None'\" = None, checkpoint_every: 'int | None' = None, checkpoint_segments: 'int | None' = None, enforce_passivity: 'bool' = False, report_every: 'int | None' = None) -> \"'MSLSMatrixResult'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/msl.py#L58", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute S-parameters on whichever lane this simulation's ports select.\n\nA single entry point over the per-family calculators. It inspects the\nregistrations, chooses exactly one delegate, and forwards ``**kwargs``\nto it UNCHANGED -- no default is invented here, so the delegate's\nsignature, defaults, preconditions, warnings and return type are exactly\nwhat you would get calling it directly.\n\nDispatch table\n--------------\n\n=================================== ========================================== ================================\nRegistered Delegate Returns\n=================================== ========================================== ================================\nwaveguide ports only ``compute_waveguide_s_matrix`` ``WaveguideSMatrixResult``\nMSL ports only ``compute_msl_s_matrix`` ``MSLSMatrixResult``\n1 coaxial port only ``compute_coaxial_line_reflection`` **or** ``CoaxialLineReflectionResult``\n ``compute_coaxial_two_port`` -- ambiguous, or ``CoaxialTwoPortResult``\n pass ``lane=``\n1 coaxial + 1 MSL ``compute_coax_msl_transition`` ``CoaxMSLTransitionResult``\nlumped/wire (``add_port``) + MSL ``compute_mixed_s_matrix`` ``MixedSMatrixResult``\nlumped/wire only ``NotImplementedError`` -- the run lane (``Result.s_params``)\nnothing ``ValueError`` --\nanything else ``NotImplementedError`` --\n=================================== ========================================== ================================\n\nThe lumped/wire family deliberately raises rather than calling ``run()``\nfor you: that lane returns a ``Result`` (not an S-matrix result type),\nand ``n_steps`` has no default there, so quietly substituting one would\nbe inventing exactly the kind of default this dispatcher refuses to\ninvent. Run it yourself::\n\n res = sim.run(n_steps=..., compute_s_params=True)\n res.s_params\n\nParameters\n----------\nlane : str or None\n Explicit lane name (see :meth:`s_matrix_lane`). Consumed here, never\n forwarded. Required for a single coaxial port, where\n ``compute_coaxial_line_reflection`` and ``compute_coaxial_two_port``\n share one registration footprint; optional elsewhere, where it is\n checked against the registrations rather than overriding them.\n**kwargs\n Forwarded verbatim to the chosen delegate.\n\nReturns\n-------\nWhatever the chosen delegate returns -- see the table.\n\nRaises\n------\nValueError\n No ports registered, or ``lane=`` contradicts the registrations.\n Also raised by the chosen lane itself: ``compute_coax_msl_transition``\n (1 coaxial + 1 MSL) refuses a non-passive extracted S by default and\n is the only lane in the table that does — forward\n ``strict_passivity=False`` through ``**kwargs`` to get the diagnostic\n matrix with a warning instead (issue #838).\nNotImplementedError\n Lumped/wire-only (use the run lane), a single coaxial port with no\n ``lane=``, or a combination of port families no calculator covers.\nTypeError\n An unrecognised keyword argument. ``**kwargs`` swallows it here, so\n the message names the DELEGATE that rejected it --\n ``Simulation.compute_waveguide_s_matrix() got an unexpected keyword\n argument 'foo'`` -- which also tells you which lane was chosen.\n\nNotes\n-----\nPreflight behaviour is inherited from the chosen lane and is not uniform\nacross the table: ``compute_msl_s_matrix`` and ``compute_mixed_s_matrix``\nrun preflight automatically, the waveguide and coaxial lanes do not. See\neach delegate's row in\n``tests/unit/preflight/test_preflight_advisory_emission_contract.py``.\n\nSee Also\n--------\ns_matrix_lane : the same choice, without running anything.", "kind": "method", "name": "rfx.Simulation.compute_s_matrix", "parameters": [ { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lane" }, { "annotation": null, "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_s_matrix", "returns": { "annotation": null }, "signature": "(self, *, lane: 'str | None' = None, **kwargs)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/dispatch.py#L350", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Compute a theoretically clean axis-normal boundary-aperture waveguide S-matrix.\n\nRequires ``solver=\"yee\"``. On a uniform mesh, ``precision`` selects\nfield storage for every device and reference run, as on ``run()``.\nA non-uniform mesh supports only ``precision=\"float32\"``.\n\nParameters\n----------\nnum_periods : float\n Length of the FDTD run (in source-period multiples) used to\n derive ``n_steps`` when ``n_steps`` is not given. The\n spectra are computed POST-SCAN from the recorded modal V/I\n time series via a rectangular full-record DFT (matching\n OpenEMS's ``utilities.DFT_time2freq``); ``num_periods``\n therefore governs both the CPML drain horizon AND the DFT\n integration window. Phase 2 cleanup (2026-04-25) removed\n the legacy ``num_periods_dft`` early-gate knob — the rect\n full-record DFT is finite-energy on the recorded transient\n so no gating is needed even on strong reflectors.\nnormalize : bool or \"flux\"\n Controls the S-parameter extraction algorithm:\n\n ``False`` (default) — modal V/I decomposition, no reference\n run. Magnitude includes Yee impedance mismatch\n (Z_TE_num/Z_TE_exact ≈ 3 % at dx/λ = 0.07). Use for\n |S11| of strong reflectors (PEC short, high-Q resonators)\n where this error is smaller than the ±10–20 % round-trip\n dispersion error introduced by ``normalize=True``. On the\n differentiable chain: a traced ``eps_override`` /\n ``sigma_override`` flows through it.\n\n ``True`` — two-run modal normalization. Cancels one-way\n Yee dispersion for **transmission** (off-diagonal) by\n dividing device outgoing waves by reference outgoing waves\n at the same port. **Does not** cancel dispersion for\n reflection (round-trip vs one-way path mismatch); use\n ``normalize=False`` or ``normalize=\"flux\"`` for S11 of\n strong reflectors. Host-assembled and **outside the\n differentiable chain**: a traced ``eps_override`` /\n ``sigma_override`` (``jax.grad``, ``jax.jit``) raises\n ``NotImplementedError`` at this call, before any FDTD run;\n a concrete override still runs forward.\n\n ``\"flux\"`` — hybrid power-flux extraction. Magnitude from\n Poynting-vector DFT (|S|² = P_flux / P_inc), phase from\n modal V/I. Corrects both the Z_TE impedance-mismatch error\n in S11 and the round-trip dispersion error in the\n ``normalize=True`` diagonal formula. Costs 2 × N_ports\n FDTD runs (same as ``normalize=True``). On the\n differentiable chain like ``False``. On the uniform lane the\n result promotes field, frequency, and JAX default float precision,\n like ``False``: complex64 with x64 off and at least complex128 with\n x64 on, including explicit float32 frequencies and float32/mixed fields.\n Modal records retain at least the frequency and default float precision.\n The non-uniform lane's result follows the ``freqs`` precision:\n complex64 by default, complex128 under ``JAX_ENABLE_X64``.\n\n **Reference impedance.** On ``False`` and ``True`` each\n S_ij is the modal voltage-wave ratio ``b_i / a_j``, where\n the waves at a port are decomposed with that port's OWN\n discrete modal impedance (Yee-discrete Z_TE or Z_TM from\n the port's cutoff and cell size); no ``sqrt(Z_i / Z_j)``\n renormalization is applied. ``\"flux\"`` takes |S_ij| from\n the power ratio and its phase from the same modal waves.\n The returned matrix therefore equals a power-wave S only\n when every port shares one cross-section and mode — the\n validated scope (straight guides and same-guide junctions).\n Ports with dissimilar cross-sections are outside it.\n\n **Multimode.** ``n_modes > 1`` on any port is assembled on\n the host for every ``normalize`` value and is outside the\n differentiable chain; ``eps_override`` / ``sigma_override``\n differentiation is single-mode only.\ncheckpoint_segments : int or None\n Segmented gradient checkpointing for the **uniform** waveguide\n AD path (issue #73 / PR #125). Splits the ``n_steps`` scan\n into ``K`` segments that are rematerialised via\n ``jax.checkpoint`` during the backward pass, reducing peak\n reverse-mode memory from O(n_steps·|carry|) to\n O((K + n_steps/K)·|carry|) (≈ O(√n_steps·|carry|) at the\n optimal K ≈ √n_steps, at ≈ 2× backward compute cost).\n ``K`` is forwarded to ``rfx.simulation.run`` with\n ``checkpoint=True``; ``K`` MUST exactly divide the\n auto-computed ``n_steps`` (the runner rejects non-divisors —\n choose the nearest divisor of √n_steps; padding is rejected\n because it would shift the V/I DFT windows). Default\n ``None`` is byte-identical to the pre-checkpoint scan.\n\n On a NON-uniform mesh (``dx_profile`` / ``dy_profile`` /\n ``dz_profile``, issue #73) ``checkpoint_segments=K`` is now supported: ``K`` is\n translated to the NU runner's ``checkpoint_every`` chunk size — the\n divisor of ``n_steps`` nearest to ``n_steps/K`` — and applied to the\n *device* run only (the vacuum reference is constant in the design\n variable). The chunk MUST divide ``n_steps`` (same as the uniform\n path): a non-divisor chunk would let the NU runner's zero-padding add\n spurious ring-down steps to the carry-accumulated flux DFT and shift\n the S-matrix. With an exact divisor the result is forward-IDENTICAL\n and the ≈O(√n_steps) tape reduction is realised under ``jax.grad``\n with ``normalize='flux'`` + an ``eps_override`` / ``sigma_override``\n design variable.\nport_reference_sims : list[Simulation] or None\n Per-driven-port matched-straight-guide reference simulations for\n **interior-PEC multi-port** structures (T-junctions, branches,\n septa). ``port_reference_sims[i]`` is a ``Simulation`` describing\n the STRAIGHT continuation of driven port ``i``'s guide with **no\n junction** — same domain / ``dx`` / boundary, geometry = port\n ``i``'s guide walls extended straight through. Only valid with\n ``normalize='flux'`` (raises otherwise); single-mode ports only;\n uniform mesh only; not combinable with ``eps_override`` /\n ``sigma_override``.\n\n **Multi-port junctions (port_reference_sims).** The default flux\n path references incident power ``P_inc`` to a single shared VACUUM\n run (empty domain, no interior PEC). For a straight guide the walls\n come from ``pec_axes`` so that vacuum reference already carries the\n guided ``P_inc`` correctly. For a junction the interior PEC septum /\n branch is stripped from the vacuum reference, which then radiates\n into free space: ``P_inc`` is mis-normalized and every ``|S|``\n inflates hard (non-passive; ``normalize=True`` gave max|S|~230,\n ``normalize='flux'`` gave max|S|~9.8, |S11|~1.9 on the verified\n compact 3-port T-junction). Passing ``port_reference_sims[i]`` = the\n matched straight guide for driven arm ``i`` moves ``P_inc`` toward\n the true single-mode guided incident power (PEC-folded identically\n to the device run).\n\n **Far-port discipline (required for a physical S-matrix).** This\n plumbing is NECESSARY but NOT SUFFICIENT. A physical junction\n S-matrix additionally requires: (1) each port's probe plane placed\n >= 5 evanescent decay lengths of the next higher mode away from the\n junction; (2) CPML thickness >= ~0.5 guide wavelengths at band\n centre; (3) a converged mesh. On far-port geometry (arms 90/90/70 mm,\n 48 mm CPML, dx 1.0/0.667 mm) the matched-reference flux path reaches\n passivity 1.006/1.002, reciprocity 0.001, mesh-convergence 0.0297\n and 0.087 vs MEEP (r2000, cross-device). On COMPACT geometry the\n matched reference fixes |S11| (1.86 → 0.49, physical) but the overall\n matrix stays non-physical (residual max|S|~3.9); the two in-method\n advisories (probe clearance, CPML thickness) warn when the far-port\n discipline is not met.\n\n The absorber half of that discipline is checked on **every**\n uniform path, not just this one: an in-method advisory (issue\n #494) fires whenever the absorber on a port's propagation axis is\n thinner than ``0.5 * lambda_g`` at the **lowest** measured\n frequency, which is where ``lambda_g`` is longest and the\n ``cpml_layers=16`` default weakest. It is checked in-method\n because the functional entry points run no ``sim.preflight()``.\n Treat ``0.5 * lambda_g`` as a floor, not a target: at the WR-90\n band edge the measured residual ``|S11|`` ripple was 0.0706 at\n 0.30 ``lambda_g``, 0.0366 at 0.50 and 0.0093 at 0.75, so a\n 0.5-``lambda_g`` absorber can still set the accuracy envelope\n instead of discretization. The advisory is silent on a\n non-uniform mesh (``cpml_layers * dx`` is ambiguous under a\n graded profile) and on a band that starts at or below cutoff\n (``lambda_g`` is undefined there; the ``port_freqs_below_cutoff``\n preflight owns that case).\n\n This enables junction measurements UNDER the documented\n discipline; it does NOT make arbitrary compact junctions\n valid. Consult ``docs/guides/sparameter_support_matrix.md`` for\n the current waveguide evidence and scope.", "kind": "method", "name": "rfx.Simulation.compute_waveguide_s_matrix", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "bool | str", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "normalize" }, { "annotation": "bool | str", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "subpixel_smoothing" }, { "annotation": "'jnp.ndarray | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_override" }, { "annotation": "'jnp.ndarray | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma_override" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict_passivity" }, { "annotation": "'list[Simulation] | None'", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_reference_sims" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.compute_waveguide_s_matrix", "returns": { "annotation": "WaveguideSMatrixResult" }, "signature": "(self, *, n_steps: 'int | None' = None, num_periods: 'float' = 20.0, normalize: 'bool | str' = False, subpixel_smoothing: 'bool | str' = False, eps_override: \"'jnp.ndarray | None'\" = None, sigma_override: \"'jnp.ndarray | None'\" = None, checkpoint_segments: 'int | None' = None, strict_passivity: 'bool' = False, port_reference_sims: \"'list[Simulation] | None'\" = None) -> 'WaveguideSMatrixResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/waveguide.py#L73", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return the FULL conductor cell footprint of this simulation.\n\nSince #677 a surface-impedance (``surface_impedance_f0``) thin\nconductor is a node-thin per-step operator: it touches neither\n``pec_mask`` nor ``materials.sigma``, so the obvious hand-written\nconductor test ``pec_mask | (sigma > 1e3)`` finds NOTHING for a\nboard whose every trace is an f0 sheet and reports a healthy\nmodel as disconnected. There are now three places a conductor\ncan live, and this accessor is the one spelling that covers all\nthree::\n\n pec_mask | (sigma > sigma_threshold) | union(f0 sheet masks)\n\nParameters\n----------\ngrid : Grid or NonUniformGrid or None\n Grid to rasterize against. ``None`` (default) builds the\n grid this simulation would actually run on -- the non-uniform\n grid when any of ``dx_profile`` / ``dy_profile`` /\n ``dz_profile`` is set, the uniform grid otherwise -- so the\n returned mask has the shape of the real run's arrays.\nsigma_threshold : float or None\n Conductivity (S/m) at or above which a cell counts as\n conductor. Default :attr:`CONDUCTOR_SIGMA_THRESHOLD`\n (``1e3``). The comparison is strict ``>``, matching the\n ``sigma > 1e3`` spelling this replaces.\n\nReturns\n-------\njnp.ndarray\n Boolean array of ``grid.shape``. All-False when the model\n has no conductor at all.\n\nNotes\n-----\nThe f0 contribution is the sheet's rasterized CELL mask (the\none-layer footprint ``apply_pec_mask`` would zero for the same\nshape), not the tangential EDGE masks the runtime operator\napplies. Cell footprint is what a connectivity / occupancy check\nwants; the edge masks live on ``SheetImpedanceCtx``.", "kind": "method", "name": "rfx.Simulation.conductor_mask", "parameters": [ { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "grid" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma_threshold" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.conductor_mask", "returns": { "annotation": null }, "signature": "(self, grid=None, *, sigma_threshold: 'float | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_compile.py#L172", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return ``(shape, NamedSharding)`` for distributed forward designs.\n\nThe global shape is ``(nx_padded, ny, nz)`` with no ghosts, where\n``nx_padded`` rounds the NU grid's x extent up to a multiple of the\ndevice count. Sharding is ``P(\"x\")`` on the ordered ``devices``\n(default: all global JAX devices). Every process must use the same\nlist. Construct large designs with ``jax.make_array_from_callback``\nor ``jax.make_array_from_single_device_arrays`` using this layout;\nno whole-domain device allocation is necessary. Forward ignores\nalignment-pad values, and their returned gradients are zero.", "kind": "method", "name": "rfx.Simulation.distributed_override_layout", "parameters": [ { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "devices" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.distributed_override_layout", "returns": { "annotation": null }, "signature": "(self, devices=None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_execute.py#L2413", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Estimate reverse-mode AD memory for this simulation.\n\nReturns a static-estimate AD_MemoryEstimate with forward,\ncheckpointed-AD, and non-checkpointed-AD sizes in GB, plus a\nbest-effort warning if estimated AD memory exceeds 85% of available\nVRAM. This artifact is planning evidence, not a certificate of peak\nruntime memory.\n\nWhen ``checkpoint_every`` is provided, the returned\n``ad_segmented_gb`` reflects the non-uniform segmented scan-of-scan\nchunk-size path from issue #31. When ``checkpoint_segments`` is\nprovided, it reflects the uniform segmented-scan segment-count path\nfrom issue #73.\n\nThe segmented model (issue #277) counts BOTH terms of the\nrematerialized backward pass:\n\n* segment-boundary storage — carry + cotangent per active segment,\n ``2 * active_segments * field_bytes``;\n* the live-segment rematerialization tape — the backward pass\n replays one segment at a time, so that segment's per-step field\n tape (``n_steps // checkpoint_segments`` steps on the uniform\n path, ``checkpoint_every`` steps on the chunked path) is resident\n on top of the boundary storage. The non-uniform runner pads the\n trailing chunk with zero source to a full chunk, so the full\n chunk length is the correct live-tape size; both live terms are\n capped at the active (post-warmup) step count.\n\nThe segmented estimate is therefore minimized when the two terms\nbalance, near ``sqrt(2 * n_steps)`` steps per segment — NOT by\npushing the segment count to either extreme. Use\n:meth:`plan_ad_memory` to pick a balanced knob for a budget.\n``n_warmup`` must be an integer with\n``0 <= n_warmup < n_steps`` and reduces reported reverse-mode tape\ntime. The legacy\n``ad_checkpointed_gb`` field keeps its old (optimistic) heuristic\nfor backwards compatibility; it\nis NOT accurate for FDTD on the non-uniform path — see the\nclass docstring.", "kind": "method", "name": "rfx.Simulation.estimate_ad_memory", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.estimate_ad_memory", "returns": { "annotation": "'AD_MemoryEstimate'" }, "signature": "(self, n_steps: 'int', *, available_memory_gb: 'float | None' = None, checkpoint_every: 'int | None' = None, checkpoint_segments: 'int | None' = None, n_warmup: 'int' = 0) -> \"'AD_MemoryEstimate'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_ad_memory.py#L174", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Explain the static reverse-mode AD memory estimate.\n\nThis method uses the same conservative accounting as\n:meth:`estimate_ad_memory`, then decomposes the selected AD memory\nnumber into named contributors. It is meant to answer \"what is making\nthis AD run large?\" without claiming profiler evidence or a runtime\npeak bound.", "kind": "method", "name": "rfx.Simulation.explain_ad_memory", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.explain_ad_memory", "returns": { "annotation": "ADMemoryExplainabilityReport" }, "signature": "(self, n_steps: 'int', *, available_memory_gb: 'float | None' = None, checkpoint_every: 'int | None' = None, checkpoint_segments: 'int | None' = None, n_warmup: 'int' = 0) -> 'ADMemoryExplainabilityReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_ad_memory.py#L389", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Write a runtime artifact bundle and return ``ArtifactBundle``.", "kind": "method", "name": "rfx.Simulation.export_artifact_bundle", "parameters": [ { "annotation": "str | Path", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "result" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.export_artifact_bundle", "returns": { "annotation": null }, "signature": "(self, path: 'str | Path', result=None, **kwargs: 'Any')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_artifacts.py#L43", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return or write the native runtime scene artifact.\n\n``path=None`` returns a JSON-serializable dict. Otherwise the scene is\nwritten as indented JSON and the output :class:`~pathlib.Path` is\nreturned.", "kind": "method", "name": "rfx.Simulation.export_scene", "parameters": [ { "annotation": "str | Path | None", "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "path" }, { "annotation": "Any", "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.export_scene", "returns": { "annotation": null }, "signature": "(self, path: 'str | Path | None' = None, **kwargs: 'Any')", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_artifacts.py#L18", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Input-fidelity audit: declared vs solved, per entity, in input\nunits — run BEFORE any solve. See :func:`rfx.fidelity.fidelity_report`\n(design rule: never predicts result-side impact; rasterization,\nrealization class and materialization only).", "kind": "method", "name": "rfx.Simulation.fidelity_report", "parameters": [ { "annotation": "bool", "default": "True", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "print_report" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.fidelity_report", "returns": { "annotation": null }, "signature": "(self, print_report: 'bool' = True)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L917", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run a minimal differentiable forward simulation.\n\nThis path is designed for ``jax.grad`` / ``jax.value_and_grad`` and\nintentionally returns only the observables needed by differentiable\nobjectives instead of the broader stateful :meth:`run` result.\n\nParameters\n----------\ngradient : {\"autodiff\", \"adjoint\"}\n Opt-in settled-spectrum reciprocity design eps adjoint.\n Design sigma overrides are refused (#1424): on lossless design cells the conductivity gradient has no settled value in a finite record\n (a static sensitivity remains although the field decays); this adjoint returns settled-spectrum gradients only. Fixed lossy materials are allowed.\n Stores design-edge DFTs and runs a second ordinary forward.\n ``ForwardResult.adjoint_settling`` reads the primal design-edge max|E| over the last period of the lowest bin, capped at the record length, divided by the record maximum.\n Above about 1e-2 means unsettled; small proves nothing: it follows the strongest field and says nothing about the adjoint record.\n Use ``gradient_record_length_witness`` to witness an adjoint gradient.\n Uniform Yee design_box only; unsupported paths raise. Checkpoint\n options are unused by the adjoint (its storage does not depend on them).\neps_override : jnp.ndarray or None\n Replacement permittivity array with shape ``grid.shape``.\n With ``distributed=True``, eps/sigma/occupancy overrides also accept\n x-sharded global arrays from :meth:`distributed_override_layout`.\n That form is required across processes; gradients keep its sharding.\n Use :meth:`shard_distributed_override` for a concrete local initializer.\nsigma_override : jnp.ndarray or None\n Replacement conductivity array with shape ``grid.shape``.\nmu_r_override : jnp.ndarray or None\n Replacement relative permeability array with shape ``grid.shape``.\n Differentiable (the H-update coefficient is ``dt/(mu_r*MU_0*dx)``), so\n ``jax.grad`` flows w.r.t. a magnetic-material design variable (ferrite /\n magnetic-RAM inverse design). Uniform single-device lane only; a\n non-uniform mesh or ``distributed=True`` raises (it would otherwise be\n silently dropped — a zero-gradient no-op).\ndesign_box : (corner_lo, corner_hi) or a DesignRegion, or None\n Issue #1179. Bounding box, in metres, of a design region whose\n permittivity is handed in separately as *design_eps_override*\n instead of being written into a whole-grid ``eps_override``.\n Accepts a ``(corner_lo, corner_hi)`` pair or any object carrying\n ``corner_lo`` / ``corner_hi`` (``DesignRegion``,\n ``TopologyDesignRegion``). Corners resolve to cells the way\n ``topology_optimize`` resolves them — ``grid.position_to_index``\n on each corner, both ends INCLUSIVE — and the realized cell\n counts, not the declared extent, are what\n *design_eps_override* must match. One difference: a corner\n outside the interior is CLAMPED by ``topology_optimize`` and\n RAISES here, so a region that reaches into the absorber is a\n smaller design region there and an error on this path.\n\n What it buys: the Yee E update is linear in the fields, so the\n backward pass needs the primal field only where a coefficient is\n a design variable. With the grid-wide coefficients left constant\n and only this box recomputed from the traced permittivity,\n reverse-mode AD stores box-shaped arrays per timestep where\n ``eps_override`` stores grid-shaped ones. The gradient is the\n same gradient (measured to 2.5e-14 relative in float64 against\n ``eps_override`` on a 57x57x41 open-domain fixture); this is a\n change of formulation, not an approximation, and it needs\n neither ``checkpoint_segments`` nor any recompute.\n\n **Pass ``checkpoint=False`` with it.** ``checkpoint=True`` (this\n method's default) remats every step, which saves the scan CARRY\n — the six grid-sized field arrays — once per step no matter what\n the coefficients are. Measured on a 23x21x19 grid over 80 steps\n with a 3x3x3 box: 0.59 MB of residuals at ``checkpoint=False``\n against 26.2 MB at ``checkpoint=True``. The box removes the\n coefficient term; only turning the per-step remat off removes\n the carry term with it.\n\n The GRADED MESH carries it too (#1183): the corners resolve\n against the non-uniform grid's own cell edges and the box redo\n uses the graded curl, so a thin substrate meshed with a\n ``dz_profile`` gets the same box-shaped tape. On that lane a\n waveguide port, an MSL port and ``until_decay`` raise — the\n first two write their own field or ``materials`` across a whole\n plane from the background permittivity.\n\n Fenced, not degraded — for a design PERMITTIVITY\n (*design_eps_override*): ``distributed=True``,\n ``solver='adi'``, ``boundary='upml'``, Debye/Lorentz\n dispersion, Kerr, subpixel/anisotropic permittivity,\n ``pec_occupancy_override``, ``stencil_order=4``, the oblique\n Bloch path, combining with ``eps_override`` / ``sigma_override``\n / ``mu_r_override``, a box that reaches into the CPML absorber,\n and a box holding a source, port, lumped-RLC or\n surface-impedance-sheet cell all RAISE (a lumped or wire port\n may stay inside with *design_box_holds_ports*). Each of those either\n computes E by some other rule inside the box or reads the\n background permittivity at a box cell, and a silently dropped\n design variable is a zero gradient that reads like convergence.\n A design OCCUPANCY has its own, shorter list — see\n *design_occupancy_override*; in particular it does combine with\n ``eps_override`` and with ``pec_occupancy_override``, because\n it reads no material array.\ndesign_eps_override : jnp.ndarray or None\n Relative permittivity at the *design_box* cells, shaped like the\n realized box. Usually the traced quantity. Required with\n *design_box* unless *design_occupancy_override* is given\n instead, and rejected without a box.\ndesign_sigma_override : jnp.ndarray, 3-tuple of them, or None\n Conductivity at the *design_box* cells, same shape. ``None``\n (default) keeps the run's own conductivity there, so a lossy\n background inside the box is carried exactly rather than\n silently replaced by a lossless one. A 3-tuple\n ``(sigma_x, sigma_y, sigma_z)`` gives each E component its own\n conductivity — what a conducting SHEET needs, whose current runs\n along its two in-plane edges only. See\n :class:`~rfx.simulation.DesignBoxSpec`.\ndesign_occupancy_override : jnp.ndarray or None\n Issue #1183. Relaxed-conductor occupancy in ``[0, 1]`` at the\n *design_box* cells — metal-shape design (a notch stub, topology\n optimisation) rather than a dielectric one. It REPLACES\n ``pec_occupancy_override`` at those cells and carries it\n everywhere else, and the gradient is the same gradient\n ``pec_occupancy_override`` gives with the same values written\n into it.\n\n What it buys is the same trade: ``apply_pec_occupancy`` scales\n every E component by ``1 - M``, so a traced whole-grid occupancy\n makes the backward pass keep three GRID-sized primal E arrays\n per timestep. Confined to a box, the arrays it keeps cover the\n box plus one cell — the reach of the incident-cell rule — and\n ``1 - M`` itself is built once outside the time loop, because an\n occupancy is a design variable and not a field. Pass\n ``checkpoint=False`` with it, for the reason above.\n\n Uniform single-device Yee lane only; a graded mesh,\n ``distributed=True`` and ``solver='adi'`` raise. So do a\n periodic axis (the incident rule wraps across the seam, so the\n box's window is no longer the whole set of cells its occupancy\n can move), combining it with *design_eps_override* in one call,\n a box covering a cell the port setup CLEARS the occupancy at\n (the port cell, its six face neighbours, an MSL port's in-plane\n diagonal owners), and the Kottke occupancy lane\n (``RFX_PEC_OCC_KOTTKE=1``), where the occupancy becomes an\n inverse-eps tensor inside the E update that the box's values\n never reach.\ndesign_box_holds_ports : bool\n Let a permittivity *design_box* contain lumped and wire ports\n (default ``False``: a box holding a port raises). A port is a\n device on its edges — a 50 ohm load and a drive built from the\n drawn materials before the time loop — so each edge a port drives\n or loads inside the box's update window keeps the coefficients\n the drawn materials give it, for the update and the drive alike:\n the design values do not reach it, their derivative through it is\n exactly zero, and a box holding a port with the background\n written into it gives the run without the box. Holding keeps the\n DRAWN material in the port's feed gap, so the modelled structure\n differs from the same design written as a whole-grid\n ``eps_override`` by that gap. Passive ports (``excite=False``)\n are held too. The other edges of the port's cells stay design\n variables; at a port's cell a design value is the cell's volume\n material. The held edges come back as\n ``ForwardResult.design_box_held_edges``, ``(axis, i, j, k)`` with\n axis 0, 1, 2 for Ex, Ey, Ez. A soft source (even on a port's\n edge), a magnetic source and a lumped RLC element in the box\n still raise; an MSL port's termination is not held.\npec_mask_override : jnp.ndarray or None\n Additional hard PEC mask to merge with geometry-defined PEC.\npec_occupancy_override : jnp.ndarray or None\n Relaxed conductor occupancy field in ``[0, 1]`` for\n differentiable PEC-style optimisation.\nn_steps : int or None\n Number of timesteps. If None, auto-computed from *num_periods*.\nnum_periods : float\n Number of periods at freq_max for auto step count.\ncheckpoint : bool\n Enable gradient checkpointing (default True).\ncheckpoint_segments : int or None\n If set, route the uniform single-device forward through the\n segmented-checkpoint path (issue #73), which trades ≈2x compute\n for ≈sqrt(n_steps) reverse-mode memory. Must divide *n_steps*\n exactly (padding is rejected so DFT accumulator windows do not\n shift). ``None`` (default) keeps the legacy per-step\n ``jax.checkpoint`` behaviour. Currently wired only on the\n uniform single-device path; non-uniform meshes and\n ``distributed=True`` raise ``NotImplementedError`` (use\n *checkpoint_every* on the non-uniform path instead).\nemit_time_series : bool\n Emit the probe time series in the returned ``ForwardResult``\n (default True). ``emit_time_series=False`` skips the time-series\n buffers and is currently only supported on the non-uniform\n forward path; on the uniform path it raises\n ``NotImplementedError`` (frequency-domain objectives such as NTFF\n and S-params still emit the series there).\ncheckpoint_every : int or None\n Non-uniform-mesh counterpart of *checkpoint_segments* (a chunk\n size, not a segment count; issue #73). When set to a positive\n integer ``K``, the non-uniform scan is run as a scan-of-scan that\n remats every ``K`` steps for ≈sqrt(n_steps) memory. Currently\n only supported on the non-uniform forward path; on the uniform\n path it raises ``NotImplementedError`` (use *checkpoint_segments*\n there). ``None`` (default) leaves forward-only runs unchanged.\nn_warmup : int\n Number of leading timesteps to run with the carry\n ``stop_gradient``'d so reverse-mode AD builds no tape for the\n initial transient (issue #40). Only the trailing\n ``n_steps - n_warmup`` steps participate in autodiff. Must\n satisfy ``n_warmup < n_steps``. Default ``0`` (all steps\n differentiated).\n\n The truncation error DEPENDS ON DISTANCE FROM THE SOURCE TO THE\n DESIGN REGION — it is not simply \"an approximation\" that always\n costs accuracy (an earlier version of this docstring implied the\n error applies unconditionally; that was an overgeneralization\n from a single, worst-case fixture — see below). Severing the\n carry severs every gradient path through steps ``< n_warmup``,\n but only steps during which the WAVEFRONT HAS ALREADY REACHED\n the design region carry any such path to sever; before the\n wavefront arrives the field there is ~0, so severing those\n steps discards ~nothing and the gradient is (near-)exact.\n Compute a safe bound yourself::\n\n K_safe ~= floor(min_distance(source, design_region) / (C0 * dt))\n\n (``min_distance`` is the minimum over EVERY active source AND\n over each source's own spatial extent, not just its nominal\n position — a TFSF plane-wave source illuminates from an\n entire box face, not a point; grid steps for the wavefront to\n reach the closest design cell, ``C0`` = vacuum lightspeed,\n ``dt`` = ``sim._build_grid().dt`` /\n ``sim._build_nonuniform_grid().dt`` — a conservative floor valid\n for any slower propagation). ``n_warmup <= K_safe`` stays\n within this repo's ~1.5% AD-vs-FD noise floor (near-exact,\n <0.1%, well below ``K_safe``); well beyond ``K_safe``, error\n grows further and can reach the full gradient magnitude by\n the time ``n_warmup`` reaches the loss window. Two measured\n regimes (issue #626 part 2 / addendum, both vs an independent\n central-FD oracle): a NEAR-SOURCE placement (design cell ~3\n cells from the source, so ``K_safe ~ 0``) shows error growing\n smoothly from a ~1.5% noise floor up to 58% at the\n loss-window boundary itself, and EXACTLY zero (gradient fully\n vanished) once ``n_warmup`` extends far enough into the loss\n window (``tests/unit/autodiff/test_n_warmup.py::\n test_warmup_truncation_error_grows_with_k``); a\n FAR-FROM-SOURCE placement (design cell 62 cells from the\n source, ``K_safe=108`` measured from the grid's own ``dt``)\n shows AD matching the ``n_warmup=0`` FD oracle to <0.01%\n through ``K_safe``-20, then growing SMOOTHLY (not a sharp\n cliff) as ``n_warmup`` approaches ``K_safe`` -- 0.26% at\n ``K_safe``-4, 0.60% at ``K_safe``-2, 1.19% AT ``K_safe``\n itself (still inside the noise floor above) -- continuing to\n grow past it toward 75% by ``K_safe`` + 92 —\n ``scripts/diagnostics/i626_n_warmup_wavefront_locality.py``\n (finely sampled around ``K_safe``; an earlier version of this\n docstring, read from a coarser sweep that skipped every point\n near the boundary, overstated the transition as a sharp\n cliff \"exactly at K_safe\"). The near-source curve above is\n the WORST case, not the general\n case: use ``K_safe`` to decide whether YOUR source/design\n placement is in the exact or the truncated regime before\n assuming ``n_warmup`` costs accuracy. Forward (non-AD) output\n is exactly ``n_warmup``-invariant (bit-identical) in every\n placement measured; only the gradient is affected. Currently\n only supported on the non-uniform / distributed-non-uniform\n forward paths; on the uniform single-device lane it raises\n ``NotImplementedError`` (issue #626 — previously silently\n accepted and ignored, worse than an error). Use\n *checkpoint_segments* for uniform-lane reverse-mode memory\n relief instead — it is exact regardless of placement, at the\n cost of recompute rather than gradient accuracy.\nskip_preflight : bool\n Skip the consolidated :meth:`preflight` validation suite that\n normally runs before the forward simulation (default False).\n Use only when preflight has already been run by the caller\n (e.g. :func:`rfx.optimize` runs it once at entry) or to bypass a\n known-spurious warning on a deliberate configuration.\ndistributed : bool, optional\n **Opt-in, unstable, pending GPU evidence (issue #44).** When\n ``True`` and a non-uniform mesh is configured, route the\n differentiable forward through the sharded NU runner\n (``rfx.runners.distributed_nu.run_nonuniform_distributed_pec``)\n using a 1-D x-slab decomposition across ``devices``. Defaults\n to ``False`` (single-device path, no behaviour change). In\n v1.6.2 the distributed forward path is **NU-only** (DP3): a\n uniform mesh raises ``NotImplementedError``. TFSF sources\n and waveguide ports are unsupported on this path and raise\n ``NotImplementedError`` at preflight.\ndevices : list of jax.Device or None, optional\n Devices for the distributed run. When ``distributed=True``\n and ``devices=None``, defaults to ``jax.devices()``. When\n an explicit list is supplied, every device must already exist\n in ``jax.devices()`` (otherwise ``ValueError``). Passing\n ``devices=`` *without* ``distributed=True`` raises\n ``ValueError`` — there is no silent activation of the\n distributed lane.\nexchange_interval : int, optional\n Ghost-cell exchange interval for the distributed runner\n (default ``1``). Only ``1`` is currently supported by\n ``run_nonuniform_distributed_pec``; other values are\n forward-compatible reservations and will raise inside the\n runner.\nport_s11_freqs : array-like or None\n Frequencies (Hz) at which to accumulate per-port V/I DFTs inside\n the JIT scan body so that ``ForwardResult.s_params`` is populated\n with wave-decomposition |S11| values for lumped/wire ports\n (issue #72) — the AD-traceable counterpart of\n ``run(compute_s_params=True)``. Required by the\n :func:`minimize_s11_at_freq_wave_decomp` objective. Currently\n supported on uniform and graded single-device paths;\n ``distributed=True`` raises ``NotImplementedError``.\nrlc_values_override : dict or None\n Differentiable-value injection for lumped RLC elements added with\n :meth:`add_lumped_rlc` (WP 4-E). ``LumpedRLCSpec`` stores plain\n floats, so a component value can only enter the AD tape as a tracer\n through this override. Maps a 0-based element index (registration\n order over :meth:`add_lumped_rlc` calls) to a dict with any of the\n keys ``\"R\"`` / ``\"L\"`` / ``\"C\"`` whose values replace the\n registered floats — e.g.\n ``forward(rlc_values_override={0: {\"R\": R, \"C\": C}}, ...)`` makes R\n and C of the first RLC element differentiable. A missing element\n index or key falls back to the registered spec float. ``None``\n (default) uses the registered floats for every element. Only wired\n on the uniform single-device path. NOTE: on this path a registered\n lumped RLC element now correctly affects ``forward()`` even without\n an override — previously it was a silent no-op.\n Uniform-path only; the non-uniform / distributed lanes do not\n iterate ``self._lumped_rlc`` in ``forward()``.\nringdown : rfx.ringdown.RingdownSpec or None\n Issue #1254. Complete the wire-port S-parameters of a record cut\n while the structure still rings, inside the differentiable\n program: ``ForwardResult.ringdown.s_params`` is the completion\n ``run(ringdown=...)`` gives of the same record (the poles of the\n port voltage and current identified on ``[window_start T, T]``,\n the unrecorded tail of each spectrum added in closed form), and\n ``jax.grad`` through it differentiates the infinite-record\n spectrum (the poles by the frozen Gauss-Newton implicit\n derivative, the residues re-fitted), not the cut record.\n ``.s_params_long`` is the completion from the window that starts\n twice as early; the gradient through it, against the gradient\n through ``.s_params``, is the gradient's witness\n (:func:`rfx.ringdown.gradient_witness`). ``.report`` holds the\n checks of the value (W0, W1, WE and the rest, as ``run()``'s),\n computed on the host from a concrete result and ``None`` while\n traced. Wire ports only (``add_port(..., extent=...)``); on the\n uniform lane one port and ``port_s11_freqs=`` are needed (the\n bins), on the graded lane the completion uses the lane's own\n bins. Everything ``run(ringdown=...)`` refuses is refused, and\n so are ``distributed=True`` and ``emit_time_series=False``.\n ``None`` (default) leaves every output and the traced program as\n they were.\n\n**_removed_kwargs\n Rejection shim for removed keywords, providing migration errors;\n it does not accept additional simulation options.\n\nReturns\n-------\nForwardResult\n Minimal differentiable observables (time series and optional NTFF).\n ``settling_db`` and ``settling_witness`` score retained user-probe\n records on the concrete result using the run() diagnostic and\n underflow floor. They are host diagnostics, unavailable during\n tracing, and can be read on concrete records outside the jitted\n objective. Other result fields keep their existing JIT\n restrictions, including the host Grid object. Absent\n records yield None rather than a passing value. Use\n ``settling_verdict(result.settling_db)`` for the shared -40 dB bar.\n\nNotes\n-----\n``forward()`` refuses refinement: it has no subgridded solve.\n``forward()`` can be called inside ``jax.jit``, so an optimisation\nstep compiles once: ``step = jax.jit(jax.value_and_grad(loss))``\ncompiles on its first call and reuses the program afterwards, while\nan un-jitted ``jax.value_and_grad(loss)`` compiles the whole solve\nagain on every call (#1225). Under an outer ``jax.jit`` (single\ndevice), the set-up built from the model alone is evaluated while\ntracing and the time stepping is compiled into the caller's program\n(#1367, #1354), so a function with no traced input compiles too. The\nset-up's arrays become constants of that program: the first call\ncosts a plain call's set-up on top of the compile, and the compiled\nprogram holds those arrays for as long as JAX caches it. The loop\ncompiles over operands XLA cannot read, as in a plain call; what is\ncomputed from a traced input before the loop (a port's drive from a\ntraced permittivity, #1320) is compiled with the caller's program,\nso the jitted value and gradient agree with a plain call to float32\nrounding, not necessarily bit for bit.", "kind": "method", "name": "rfx.Simulation.forward", "parameters": [ { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "eps_override" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sigma_override" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mu_r_override" }, { "annotation": "tuple | object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_box" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_eps_override" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_sigma_override" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_occupancy_override" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "design_box_holds_ports" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_mask_override" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pec_occupancy_override" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "str", "default": "'autodiff'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "gradient" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "emit_time_series" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "distributed" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "devices" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "exchange_interval" }, { "annotation": "object | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "port_s11_freqs" }, { "annotation": "dict | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "rlc_values_override" }, { "annotation": "RingdownSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ringdown" }, { "annotation": null, "default": null, "has_default": false, "kind": "VAR_KEYWORD", "name": "_removed_kwargs" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.forward", "returns": { "annotation": "ForwardResult" }, "signature": "(self, *, eps_override: 'jnp.ndarray | None' = None, sigma_override: 'jnp.ndarray | None' = None, mu_r_override: 'jnp.ndarray | None' = None, design_box: 'tuple | object | None' = None, design_eps_override: 'jnp.ndarray | None' = None, design_sigma_override: 'jnp.ndarray | None' = None, design_occupancy_override: 'jnp.ndarray | None' = None, design_box_holds_ports: 'bool' = False, pec_mask_override: 'jnp.ndarray | None' = None, pec_occupancy_override: 'jnp.ndarray | None' = None, n_steps: 'int | None' = None, num_periods: 'float' = 20.0, checkpoint: 'bool' = True, gradient: 'str' = 'autodiff', checkpoint_segments: 'int | None' = None, emit_time_series: 'bool' = True, checkpoint_every: 'int | None' = None, n_warmup: 'int' = 0, skip_preflight: 'bool' = False, distributed: 'bool' = False, devices: 'list | None' = None, exchange_interval: 'int' = 1, port_s11_freqs: 'object | None' = None, rlc_values_override: 'dict | None' = None, ringdown: 'RingdownSpec | None' = None, **_removed_kwargs) -> 'ForwardResult'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_execute.py#L3128", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Finalize mesh spacing/profiles and extent, returning the selected grid.\n\nCall after adding mesh-driving materials/geometry and before placing\nlattice-aligned conductors. Later geometry cannot refine this mesh;\nunresolved features still raise under the normal conductor contract.\nRepeated calls preserve the same mesh. Build a new Simulation to remesh.\n\nGrid previews (including preflight) alone do not finalize the mesh.\nRegister boundary conditions and ports before retaining grid indices:\nport registration may change padding, though physical node positions\nin the domain stay fixed. Caller declarations remain available unchanged.", "kind": "method", "name": "rfx.Simulation.freeze_mesh", "parameters": [], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.freeze_mesh", "returns": { "annotation": null }, "signature": "(self)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2862", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return a consolidated mesh-quality and memory-planning report.\n\nThe report is intentionally advisory: it reuses ``preflight()``\nfor physics/geometry warnings, reuses ``estimate_ad_memory()``\nwhen ``n_steps`` is provided, and adds a uniform-fine comparator\nthat estimates how many cells a globally fine mesh would need if\nit used the minimum cell size present in any non-uniform profile.\n\nThis is the Stage-1 production-near \"subgrid-like\" planning\nsurface: it helps users decide whether existing non-uniform mesh\nplus segmented checkpointing is enough before attempting\nresearch-only true subgridding.\n\n``checkpoint_every`` and ``checkpoint_segments`` are forwarded to the\nsame AD estimator used by :meth:`plan_ad_memory`; they are mutually\nexclusive. ``n_warmup`` is forwarded as reverse-mode tape metadata\nonly, matching ``estimate_ad_memory``.", "kind": "method", "name": "rfx.Simulation.mesh_intelligence_report", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_segments" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_ntff" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_resolution" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.mesh_intelligence_report", "returns": { "annotation": "MeshIntelligenceReport" }, "signature": "(self, *, n_steps: 'int | None' = None, checkpoint_every: 'int | None' = None, checkpoint_segments: 'int | None' = None, available_memory_gb: 'float | None' = None, n_warmup: 'int' = 0, check_ntff: 'bool' = True, check_resolution: 'bool' = True) -> 'MeshIntelligenceReport'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2877", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Choose a segmented-AD memory plan for a memory budget.\n\nThe planner reuses :meth:`estimate_ad_memory` and returns a\ncalibrated conservative planning artifact rather than mutating the\nsimulation or certifying runtime peak memory. If ordinary reverse-mode\nAD already fits under ``target_fraction * available_memory_gb``, both\ncheckpoint knobs are ``None``. Otherwise it returns a segmented\ncandidate: ``checkpoint_every`` for non-uniform grids or\n``checkpoint_segments`` for uniform grids. Only wire the candidate when\n``segmented_fits`` is true; a non-fitting plan keeps the least-memory\ncandidate as diagnostics.\n``n_warmup`` must be an integer with ``0 <= n_warmup < n_steps`` and\nreduces active reverse-mode time. Raw estimates must also fit after\nmultiplying by ``safety_factor`` before fit flags are set, so\nnear-boundary plans stay conservative.", "kind": "method", "name": "rfx.Simulation.plan_ad_memory", "parameters": [ { "annotation": "int", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "n_steps" }, { "annotation": "float", "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "available_memory_gb" }, { "annotation": "float", "default": "0.85", "has_default": true, "kind": "KEYWORD_ONLY", "name": "target_fraction" }, { "annotation": "int", "default": "0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_warmup" }, { "annotation": "float", "default": "1.3", "has_default": true, "kind": "KEYWORD_ONLY", "name": "safety_factor" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.plan_ad_memory", "returns": { "annotation": "ADMemoryPlan" }, "signature": "(self, n_steps: 'int', available_memory_gb: 'float', *, target_fraction: 'float' = 0.85, n_warmup: 'int' = 0, safety_factor: 'float' = 1.3) -> 'ADMemoryPlan'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_ad_memory.py#L621", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return an advisory mesh plan for this configured simulation.", "kind": "method", "name": "rfx.Simulation.plan_mesh", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint_every" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "sparameter_calculator" }, { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "artifact_root" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.plan_mesh", "returns": { "annotation": "MeshPlan" }, "signature": "(self, *, n_steps: 'int | None' = None, checkpoint_every: 'int | None' = None, available_memory_gb: 'float | None' = None, sparameter_calculator: 'str | None' = None, artifact_root: 'str | None' = None) -> 'MeshPlan'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L3043", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run all pre-simulation checks and return warnings.\n\nResolves and caches the mesh from the current static declaration,\nwithout changing declared dx/domain/profiles. Auto-mesh selection is\nemitted as a UserWarning, separately from validation findings.\n\nParameters\n----------\nstrict : bool\n If True, raise ValueError on the first issue instead of\n collecting warnings.\ncheck_ntff : bool or \"advisory\"\n ``True`` (default): run the full NTFF check family (PEC-overlap\n hard error + λ/4 / λ/2 near-field gap advisories + the\n sub-wavelength ground-plane pattern advisory, issue #334).\n ``\"advisory\"``: run only the advisories — the tier ``run()``\n uses, because the λ/4 and small-ground-plane warnings are\n physics-relevant to any far-field computation while the\n PEC-overlap hard error remains an inverse-design gate\n (issue #303).\n ``False``: skip the family entirely.\ncheck_resolution : bool\n Run the tightened resolution check (existing _validate_mesh_quality\n uses per-material thresholds already — this flag kept for\n symmetry and future tightening). Default True.\ncheck_ad_memory : bool\n Run AD memory estimate and warn if > 85% of available VRAM.\n Requires n_steps_for_memory. Default False (diagnostic only).\nn_steps_for_memory : int or None\n Step count for AD memory sizing. Required when check_ad_memory.\navailable_memory_gb : float or None\n Override VRAM detection. If None, best-effort via JAX devices.\n\nReturns\n-------\nPreflightReport\n A ``list`` subclass of :class:`PreflightIssue` (each a ``str``\n subclass), back-compatible with the legacy ``list[str]`` return.\n Empty if no issues found. Finite flux-window geometry is recorded\n separately in ``flux_regions``, including for issue-free reports.", "kind": "method", "name": "rfx.Simulation.preflight", "parameters": [ { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict" }, { "annotation": "bool | str", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_ntff" }, { "annotation": "bool", "default": "True", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_resolution" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "check_ad_memory" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps_for_memory" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "available_memory_gb" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.preflight", "returns": { "annotation": "'PreflightReport'" }, "signature": "(self, *, strict: 'bool' = False, check_ntff: 'bool | str' = True, check_resolution: 'bool' = True, check_ad_memory: 'bool' = False, n_steps_for_memory: 'int | None' = None, available_memory_gb: 'float | None' = None) -> \"'PreflightReport'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_preflight.py#L869", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Preflight the selected S-parameter calculator without running FDTD.\n\nThis is a routing/contract check for the port-family-specific\nS-parameter APIs. It answers \"which calculator should this simulation\nuse?\" before an expensive run starts:\n\n- ``calculator=\"run\"`` checks ``run(compute_s_params=True)`` for\n lumped/wire ``add_port(...)`` families.\n- ``calculator=\"forward\"`` checks ``forward(port_s11_freqs=...)`` for\n uniform single-device S11 vectors.\n- ``calculator=\"msl\"`` checks ``compute_msl_s_matrix(...)``.\n- ``calculator=\"waveguide\"`` checks ``compute_waveguide_s_matrix(...)``.\n\nParameters\n----------\ncalculator:\n One of ``\"run\"``, ``\"forward\"``, ``\"msl\"``, or ``\"waveguide\"``\n (the corresponding method names are accepted as aliases).\nstrict:\n If True, escalate ERROR-severity findings to a raise: collect\n everything, then raise a single ``ValueError`` listing the errors\n (aggregate-then-raise). The underlying ``NotImplementedError`` is\n recorded as an error-severity issue and re-surfaced as part of that\n aggregated ``ValueError`` (its exact type is not preserved).\n\n Errors only, not \"any issue\": the waveguide setup audits report\n advisory and informational findings on a perfectly valid routing,\n and a healthy two-port guide ALWAYS carries the informational\n E-plane note, so escalating on emptiness would make\n ``strict=True`` raise on every correct waveguide setup. Advisories\n are still returned in the report and printed; read them there.\n (This differs from ``preflight(strict=True)``, whose report has no\n informational tier.)\nnormalize:\n Waveguide non-uniform preflight uses this to mirror\n ``compute_waveguide_s_matrix(normalize=...)``. ``None`` means the\n method default, currently ``False``.\ninclude_general:\n If True, append the ordinary geometry/material ``preflight()``\n issues after the S-parameter routing check.\n\nReturns\n-------\nPreflightReport\n A ``list`` subclass of :class:`PreflightIssue` (back-compatible with\n the historical ``list[str]``). Carries no ERROR-severity issue when\n the selected calculator is valid for the registered port families —\n read ``report.ok`` / ``report.errors`` rather than emptiness.\n ``calculator=\"waveguide\"`` additionally runs the three setup\n audits (:meth:`_validate_cfg_record_vs_far_boundary`,\n :meth:`_validate_cfg_port_index_mirror_covariance` and\n :meth:`_validate_cfg_layout_from_band_low_edge`), which report\n advisory and informational findings on a perfectly valid routing —\n a healthy two-port guide always carries at least the known\n E-plane-offset note. Those audits are evaluated at\n ``compute_waveguide_s_matrix``'s own default ``num_periods``\n (:data:`WAVEGUIDE_DEFAULT_NUM_PERIODS`); the record-length message\n names the ``num_periods`` that clears the threshold, which does not\n depend on the value it was evaluated at.", "kind": "method", "name": "rfx.Simulation.preflight_sparameters", "parameters": [ { "annotation": "str", "default": "'run'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "calculator" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "strict" }, { "annotation": "bool | str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "normalize" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "include_general" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.preflight_sparameters", "returns": { "annotation": "'PreflightReport'" }, "signature": "(self, *, calculator: 'str' = 'run', strict: 'bool' = False, normalize: 'bool | str | None' = None, include_general: 'bool' = False) -> \"'PreflightReport'\"", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_preflight.py#L928", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return the immutable host record of this configuration's built geometry.\n\nBuild only: entities, solved sheet spans, signed face residuals in\nmetres, domain padding, and driven port edges. Dense diagnostic arrays\nare built on request here. ``run()`` attaches a compact record built\nindependently from its own assembly as ``Result.realized_geometry``.", "kind": "method", "name": "rfx.Simulation.realized_geometry", "parameters": [], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.realized_geometry", "returns": { "annotation": null }, "signature": "(self)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L906", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Run the simulation.\n\nParameters\n----------\nn_steps : int or None\n Number of timesteps. If None, auto-computed from num_periods.\nnum_periods : float\n Number of periods at freq_max for auto timestep count.\ncheckpoint : bool\n Enable gradient checkpointing for reverse-mode AD.\ncompute_s_params : bool or None\n Compute S-parameter matrix. Default: True when ports exist.\ns_param_freqs : array or None\n Frequencies for S-parameters. Default: 50 points from\n freq_max/10 to freq_max.\ns_param_n_steps : int or None\n Timesteps for S-parameter simulation (may need more than\n the main simulation for frequency resolution).\nuntil_decay : float or None\n When provided, overrides *n_steps* and runs until field\n energy decays to this fraction of peak. E.g. ``1e-3``.\n **Boundary-dependent stop (issue #169, RESOLVED for absorbing\n boundaries):** On **absorbing** boundaries (``cpml`` / ``upml``)\n the stop now uses the **total interior-domain energy**\n ``U = sum(E^2 + H^2)`` over the non-CPML interior — a whole-domain\n quantity that does not pass through the per-cell interference nulls\n of the old single-cell point-field stop, so it **is** suitable for\n flux / S-parameter / transmission measurements on guided / low-loss\n geometries (#169 resolved). On **closed / PEC** boundaries domain\n energy does not decay, so the stop falls back to the historical\n *instantaneous* single-cell field; that fallback keeps the original\n limitation (valid only for lossy / radiating ring-down, not flux /\n S-param / transmission gating on guided / low-loss closed geometries\n — use a fixed ``n_steps`` there, see the\n :func:`rfx.simulation.run_until_decay` note).\n **Non-uniform (dx/dy/dz-profile) meshes (issue #383):** the same\n interior-energy stop runs on absorbing (``cpml``/``upml``)\n boundaries via a chunked host loop over the NU scan step\n (dV-weighted energy — per-cell ``dx*dy*dz`` — so graded cells\n are weighted faithfully). Closed-boundary NU sims refuse\n ``until_decay`` (no point-field fallback on the NU lane).\n On the NU decay path all step-sized buffers are allocated at\n ``decay_max_steps`` and flux monitors must keep the default\n rectangular DFT window. (The non-uniform runner additionally\n rejects its internal ``checkpoint_every`` segmentation option\n when a decay stop is requested; that option belongs to the\n ``forward()`` lane and is not reachable through ``run()``.)\n **DC floor (issue #388):** a soft-source waveform with net DC\n content deposits a static end-charge whose self-energy floors\n the interior-energy criterion; ``run()`` warns quantitatively\n when a planned soft-source waveform's relative DC exceeds 1e-3\n (raise the ``GaussianPulse`` cutoff, narrow a\n ``ModulatedGaussian`` to bandwidth <= 0.4, or use a fixed\n ``n_steps``). This advisory does NOT catch low-rel_DC floors\n amplified by thin source cells (the #388 patch class measured\n the floor at rel_DC ~6e-5) — see issue #388.\ndecay_check_interval : int\n Check decay every N steps (default 50).\ndecay_min_steps : int\n Always run at least this many steps (default 100).\ndecay_max_steps : int\n Hard upper limit on steps (default 50000).\ndecay_energy_consecutive : int\n Absorbing-boundary only: number of consecutive sub-threshold\n interior-energy checks required before stopping (default ``2``;\n ``>= 2`` mandatory — the interior energy is not null-free and a\n single check can false-fire on a transient inter-packet dip).\nradiated_flux_box : tuple or None\n Physical lower/upper corners of a closed box enclosing the radiator,\n clear of CPML. Selects outgoing-flux decay instead of interior-energy\n decay on absorbing boundaries; None keeps the energy criterion.\nflux_env_checks : int\n Number of recent checks whose maximum absolute flux forms the\n radiated-flux envelope (default 4).\nsnapshot : SnapshotSpec or None\n Field snapshot schedule and selection; None disables snapshots.\nsubpixel_smoothing : bool or str\n Material-interface smoothing rule; False disables smoothing.\n True enables dielectric smoothing; \"kottke_pec\" selects the\n unified PEC occupancy rule on supported lanes.\nskip_preflight : bool\n Skip advisory preflight checks. Runtime admission guards still apply.\ndecay_monitor_component : str\n Field component to monitor (default ``\"ez\"``). Used only by the\n closed/PEC point-field fallback stop.\ndecay_monitor_position : tuple or None\n Physical position to monitor. If None, use domain center.\nconformal_pec : bool\n Enable Dey-Mittra conformal PEC for second-order accuracy\n on curved PEC surfaces. Default False (staircase PEC).\nconformal_min_weight : float\n Minimum conformal weight for CFL stability clamping.\n Default 0.1. Recommended range: 0.05-0.3.\ndevices : list of jax.Device or None\n When a list with len > 1 is provided, run the simulation\n distributed across those devices using 1D slab decomposition\n along the x-axis via ``shard_map``. Supported combinations are\n listed in ``docs/guides/support_matrix.md``.\nexchange_interval : int, optional\n Ghost exchange interval in timesteps; only integer 1 is supported.\nreport_every : int or None\n Issue #667 — progress reporting for long solves. When set,\n print one `` [PROGRESS] ...`` line every *N* timesteps giving\n steps done / total, wall elapsed, implied rate and ETA, on the\n same stdout channel as preflight so a redirected job log\n captures it. ``None`` (default) is OFF and leaves the solve on\n its unchanged code path, so nothing moves for existing callers.\n\n Supported on the **uniform lane only** (both the fixed\n ``n_steps`` scan and ``until_decay``); the distributed,\n non-uniform, ADI and subgridded lanes warn and drop it rather\n than silently producing no output. It is forward-only and\n raises under ``jax.jit``/``grad``/``vmap`` (the check inspects\n the carry, the per-step inputs and the material / geometry\n arrays — the routes ``forward()``/``optimize()`` trace through).\n\n On the fixed-``n_steps`` scan the reporting turns the single\n compiled scan into ``ceil(n_steps / report_every)`` calls to\n the SAME compiled scan with ``carry`` threaded through — a\n continuation, not a re-solve, and bit-exact against\n ``report_every=None`` (locked by\n ``tests/unit/runners/test_run_progress_reporting.py``).\n\n Each report costs one device synchronisation plus one print.\n On a 118k-cell CPU fixture that cost was **not resolvable above\n the measurement noise** at any cadence tried: a paired\n off-vs-off self-control read -4.8% [-9.3, -0.9], and every\n cadence from 2000 down to 25 landed inside that floor. The one\n clean figure is +0.7-0.8% for a single-chunk run, bounding the\n fixed per-report cost. So choose ``report_every`` for a useful\n reporting interval, not to minimise an overhead this benchmark\n could not detect; only the direction (finer cadence costs more)\n is established. None of this speaks to the large-grid GPU\n regime, which was not measured.\nreport_label : str\n Short tag prefixed to each progress line (e.g. ``\"drive p1\"``).\n Ignored when ``report_every`` is None.\nringdown : rfx.ringdown.RingdownSpec or None\n Issue #1254 — complete the wire-port S-parameters of a record\n cut while the structure still rings. The slow poles are\n identified on ``[window_start * T, T]`` of the port voltage and\n current (the source must be off there) and the unrecorded tail\n of each spectrum is added in closed form. The result is\n ``Result.ringdown`` (``.s_params`` on the bins of\n ``Result.s_params``, ``.report`` with the window, the poles and\n the witnesses: ``WE`` when available (otherwise ``W2``), no growing\n pole, passivity, source off). Every other output is the one the\n same run gives without ``ringdown=``. Wire ports\n (``add_port(..., extent=...)``) on the uniform (one port) and\n graded-mesh lanes, fixed record length; other ports, TFSF, Kerr,\n ``devices=`` and ``until_decay`` are refused with the reason.\nuntil_identified : bool\n Issue #1254 — with ``ringdown=``, end the run once the completion\n is witnessed instead of at ``n_steps``, which becomes the longest\n record allowed. The record is checked on a geometric schedule\n (every check at least 1.25x the record of the last); the run\n stops at the first check where every source is off over\n ``[T/4, T]``, the error witness ``WE`` is within ``witness_tol``\n there and at the check before, the record is at least half the\n amplitude decay time ``Q / (pi f)`` of the slowest mode whose own\n unrecorded tail moves the completed S by ``witness_tol`` (a static\n field left in a closed box is left out; the largest such decay\n time over the checks the two-in-a-row rule rests on), and the\n completion reads passive with no growing pole. The result is the\n one ``run(n_steps=T, ringdown=...)`` returns for the stopping\n record ``T``, with the stop report (every check's record, ``WE``,\n the pole that set the floor, the conditions and the check's wall\n time) in ``Result.ringdown.stop``. Each check identifies the\n record twice (0.1-3 s on a CPU for the test cavity); on a small\n model that costs more than the steps it saves. A weakly coupled\n high-Q mode holds the floor for half its own decay time, which\n can be longer than ``n_steps``. When no check\n stops the run, the whole ``n_steps`` record is completed and the\n report names the condition that failed. Refused without\n ``ringdown=``, with ``until_decay``, ``snapshot=``, DFT planes\n and flux monitors.\n\nReturns\n-------\nResult", "kind": "method", "name": "rfx.Simulation.run", "parameters": [ { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "n_steps" }, { "annotation": "float", "default": "20.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "num_periods" }, { "annotation": "float | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "until_decay" }, { "annotation": "int", "default": "50", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_check_interval" }, { "annotation": "int", "default": "100", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_min_steps" }, { "annotation": "int", "default": "50000", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_max_steps" }, { "annotation": "int", "default": "2", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_energy_consecutive" }, { "annotation": "tuple | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "radiated_flux_box" }, { "annotation": "int", "default": "4", "has_default": true, "kind": "KEYWORD_ONLY", "name": "flux_env_checks" }, { "annotation": "str", "default": "'ez'", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_monitor_component" }, { "annotation": "tuple[float, float, float] | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "decay_monitor_position" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "checkpoint" }, { "annotation": "bool | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "compute_s_params" }, { "annotation": "jnp.ndarray | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s_param_freqs" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "s_param_n_steps" }, { "annotation": "SnapshotSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "snapshot" }, { "annotation": "bool | str", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "subpixel_smoothing" }, { "annotation": "bool | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_pec" }, { "annotation": "float", "default": "0.1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "conformal_min_weight" }, { "annotation": "list | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "devices" }, { "annotation": "int", "default": "1", "has_default": true, "kind": "KEYWORD_ONLY", "name": "exchange_interval" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "skip_preflight" }, { "annotation": "int | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_every" }, { "annotation": "str", "default": "''", "has_default": true, "kind": "KEYWORD_ONLY", "name": "report_label" }, { "annotation": "RingdownSpec | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "ringdown" }, { "annotation": "bool", "default": "False", "has_default": true, "kind": "KEYWORD_ONLY", "name": "until_identified" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.run", "returns": { "annotation": "Result" }, "signature": "(self, *, n_steps: 'int | None' = None, num_periods: 'float' = 20.0, until_decay: 'float | None' = None, decay_check_interval: 'int' = 50, decay_min_steps: 'int' = 100, decay_max_steps: 'int' = 50000, decay_energy_consecutive: 'int' = 2, radiated_flux_box: 'tuple | None' = None, flux_env_checks: 'int' = 4, decay_monitor_component: 'str' = 'ez', decay_monitor_position: 'tuple[float, float, float] | None' = None, checkpoint: 'bool' = False, compute_s_params: 'bool | None' = None, s_param_freqs: 'jnp.ndarray | None' = None, s_param_n_steps: 'int | None' = None, snapshot: 'SnapshotSpec | None' = None, subpixel_smoothing: 'bool | str' = False, conformal_pec: 'bool | None' = None, conformal_min_weight: 'float' = 0.1, devices: 'list | None' = None, exchange_interval: 'int' = 1, skip_preflight: 'bool' = False, report_every: 'int | None' = None, report_label: 'str' = '', ringdown: 'RingdownSpec | None' = None, until_identified: 'bool' = False) -> 'Result'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_execute.py#L3930", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Which S-matrix lane this simulation's registrations select.\n\nRuns no FDTD and touches no grid: it reads the port registries only, so\nit is cheap to call on a half-built ``Simulation`` and it is what the\ndispatch table's tests assert against.\n\nParameters\n----------\nlane : str or None\n Optional explicit lane name, one of the ``compute_*`` names below or\n ``\"run(compute_s_params=True)\"``. Required on the single-coaxial-port\n row, where two lanes share one registration footprint (see the module\n docstring). On every other row it is checked against the lane the\n registrations determine and raises ``ValueError`` if it disagrees --\n it can select a lane, never override the physics fence.\n\nReturns\n-------\nstr\n The delegate's method name, e.g. ``\"compute_waveguide_s_matrix\"``, or\n the literal ``\"run(compute_s_params=True)\"`` for the lumped/wire\n family, which has no ``compute_*`` method.\n\nRaises\n------\nValueError\n No ports registered at all (the message lists the ``add_*_port``\n builders), or a ``lane=`` that contradicts the registrations.\nNotImplementedError\n A single coaxial port (ambiguous -- pass ``lane=``), or any\n combination of families no calculator covers. The message names the\n registered families with their counts.\n\nExamples\n--------\n>>> sim.add_waveguide_port(...); sim.add_waveguide_port(...)\n>>> sim.s_matrix_lane()\n'compute_waveguide_s_matrix'", "kind": "method", "name": "rfx.Simulation.s_matrix_lane", "parameters": [ { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "lane" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.s_matrix_lane", "returns": { "annotation": "str" }, "signature": "(self, *, lane: 'str | None' = None) -> 'str'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/sparams/dispatch.py#L282", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Place a concrete local whole-domain design in the forward layout.\n\nThis convenience initializer copies addressable x slabs from a host\narray; it is not an autodiff operation. Differentiate forward with\nrespect to the returned global array. For designs too large for one\nhost, construct shards directly using ``distributed_override_layout``.\nOn multiple processes each caller supplies the same concrete array.", "kind": "method", "name": "rfx.Simulation.shard_distributed_override", "parameters": [ { "annotation": null, "default": null, "has_default": false, "kind": "POSITIONAL_OR_KEYWORD", "name": "array" }, { "annotation": null, "default": "None", "has_default": true, "kind": "POSITIONAL_OR_KEYWORD", "name": "devices" }, { "annotation": null, "default": "0.0", "has_default": true, "kind": "KEYWORD_ONLY", "name": "pad_value" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.shard_distributed_override", "returns": { "annotation": null }, "signature": "(self, array, devices=None, *, pad_value=0.0)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/_execute.py#L2436", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Realized inclusive total-field node bounds on the padded grid.\n\nThe normal slab returns x only; ``closed_box=True`` returns x/y/z.\nNTFF cell-centre interpolation must clear these bounds, including\nthe adjacent Yee samples (the NTFF placement check enforces this).", "kind": "method", "name": "rfx.Simulation.tfsf_box_indices", "parameters": [], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.tfsf_box_indices", "returns": { "annotation": "dict[str, tuple[int, int]]" }, "signature": "(self) -> 'dict[str, tuple[int, int]]'", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L2188", "support_url": "https://remilab.ai/rfx/support/" }, { "docstring": "Return the production-envelope validation report for subgridding.\n\nEvery mode reports the subgridded lane as unsupported because it is\nunstable and unverified (#1465). Experimental envelope checks remain\navailable for research diagnostics; opting in does not confer support.", "kind": "method", "name": "rfx.Simulation.validate_subgrid", "parameters": [ { "annotation": "str | None", "default": "None", "has_default": true, "kind": "KEYWORD_ONLY", "name": "mode" } ], "reference_url": "https://remilab.ai/rfx/api/generated/rfx.html#Simulation.validate_subgrid", "returns": { "annotation": null }, "signature": "(self, *, mode: 'str | None' = None)", "source_url": "https://github.com/bk-squared/rfx/blob/2c32b7cf79b796fae825bfa08fc73d9914e61723/rfx/api/__init__.py#L790", "support_url": "https://remilab.ai/rfx/support/" } ] }