API Reference
This section provides complete API documentation for all public modules and classes in the analytic-continuation package.
Main Package
analytic_continuation - Coordinate transforms and Laurent series pipeline utilities.
Provides screen/logical space transformations for complex analysis visualizations, and implements the Laurent/Schwarz-reflection analytic continuation pipeline.
- class analytic_continuation.SpaceAdapter[source]
Bases:
objectTransforms coordinates between screen space and logical (complex plane) space.
- Screen space:
Origin at top-left
X increases rightward
Y increases downward
Units are pixels
- Logical space:
Complex plane
X is the real axis
Y is the imaginary axis (increases upward)
Units are mathematical units
- Parameters:
params (
Optional[TransformParams])
- __init__(params=None)[source]
Initialize the space adapter.
- Parameters:
params (TransformParams, optional) – Transform parameters. If None, uses identity transform.
- screen_to_logical(screen_x, screen_y)[source]
Transform a point from screen space to logical space.
- logical_to_screen(logical_x, logical_y)[source]
Transform a point from logical space to screen space.
- transform_points_to_logical(points)[source]
Transform a list of points from screen to logical space.
- transform_points_to_screen(points)[source]
Transform a list of points from logical to screen space.
- transform_spline_export_to_logical(export)[source]
Transform a full SplineExport from screen to logical space.
Transforms all point arrays (controlPoints, spline, adaptivePolyline). Also scales the parameters.minDistance accordingly.
- Parameters:
export (
SplineExport)- Return type:
- screen_distance_to_logical(screen_distance)[source]
Convert a distance from screen units to logical units.
For non-uniform scaling, uses the geometric mean of scale factors.
- logical_distance_to_screen(logical_distance)[source]
Convert a distance from logical units to screen units.
For non-uniform scaling, uses the geometric mean of scale factors.
- with_params(**kwargs)[source]
Create a new SpaceAdapter with modified parameters.
- Parameters:
**kwargs – Parameters to override (offset_x, offset_y, scale_x, scale_y)
- Returns:
New adapter with modified parameters
- Return type:
- zoom(factor, center_screen=None)[source]
Create a new adapter with zoomed view.
- Parameters:
- Return type:
- pan(delta_screen_x, delta_screen_y)[source]
Create a new adapter with panned view.
- Parameters:
- Return type:
- class analytic_continuation.TransformParams[source]
Bases:
objectParameters defining the screen-to-logical coordinate transformation.
Screen space: origin at top-left, Y increases downward, pixel units Logical space: complex plane, Y increases upward, mathematical units
- The transform is:
logical_x = (screen_x - offset_x) / scale_x logical_y = (offset_y - screen_y) / scale_y (note Y flip)
- Or equivalently:
screen_x = logical_x * scale_x + offset_x screen_y = offset_y - logical_y * scale_y
- classmethod from_view_bounds(screen_width, screen_height, logical_x_range, logical_y_range, uniform=True)[source]
Create transform params from screen dimensions and logical view bounds.
- Parameters:
screen_width (float) – Screen dimensions in pixels
screen_height (float) – Screen dimensions in pixels
logical_x_range (tuple) – (x_min, x_max) in logical coordinates
logical_y_range (tuple) – (y_min, y_max) in logical coordinates
uniform (bool) – If True, use the same scale for both axes (may add margins)
- Return type:
- class analytic_continuation.Point[source]
Bases:
objectA 2D point, used for both screen and logical coordinates.
- class analytic_continuation.Spline[source]
Bases:
objectA sequence of points forming a spline or polyline.
- class analytic_continuation.SplineExport[source]
Bases:
objectFull spline export structure matching the React frontend format.
Contains control points, interpolated spline, and adaptive polyline.
- Parameters:
- parameters: SplineParameters
- __init__(version, timestamp, closed, parameters, controlPoints, spline=<factory>, adaptivePolyline=<factory>, stats=None)
- class analytic_continuation.LaurentMap[source]
Bases:
objectLaurent series map φ(ζ) = a₀ + Σₙ aₙζⁿ + Σₙ bₙζ⁻ⁿ
Maps the unit circle to the curve boundary.
- class analytic_continuation.Complex[source]
Bases:
objectComplex number representation matching the schema.
- class analytic_continuation.Singularity[source]
Bases:
objectA zero or pole with location and multiplicity.
- class analytic_continuation.MeromorphicBuilder[source]
Bases:
objectBuilder class for constructing meromorphic functions interactively.
Integrates with SpaceAdapter for coordinate transforms.
- zeros: List[Singularity]
- poles: List[Singularity]
- add_zero(x, y, multiplicity=1)[source]
Add a zero at (x, y) in logical coordinates.
- Parameters:
- Return type:
- add_pole(x, y, multiplicity=1)[source]
Add a pole at (x, y) in logical coordinates.
- Parameters:
- Return type:
- add_zero_from_screen(screen_x, screen_y, adapter, multiplicity=1)[source]
Add a zero from screen coordinates, transforming via adapter.
- add_pole_from_screen(screen_x, screen_y, adapter, multiplicity=1)[source]
Add a pole from screen coordinates, transforming via adapter.
- analytic_continuation.build_meromorphic_expression(zeros, poles, normalize=False)[source]
Build a sympy-compatible expression for a meromorphic function.
- Parameters:
zeros (List[Singularity]) – List of zeros with locations and multiplicities
poles (List[Singularity]) – List of poles with locations and multiplicities
normalize (bool) – If True, add a leading coefficient to normalize (not yet implemented)
- Returns:
Expression string like “(z-1)*(z+1)/((z-i)*(z+i))”
- Return type:
Examples
>>> build_meromorphic_expression( ... zeros=[Singularity(1, 0), Singularity(-1, 0)], ... poles=[Singularity(0, 1), Singularity(0, -1)] ... ) '(z-1)*(z+1)/((z-i)*(z+i))'
- analytic_continuation.meromorphic_from_points(zeros, poles, zero_multiplicities=None, pole_multiplicities=None)[source]
Convenience function to build expression directly from Point lists.
- Parameters:
- Returns:
Sympy-compatible expression
- Return type:
- class analytic_continuation.LaurentFitConfig[source]
Bases:
objectConfiguration for Laurent map fitting.
- Parameters:
N_min (
int)N_max (
int)m_samples (
int)lambda_init (
float)lambda_increase_factor (
float)max_lambda_tries (
int)reparam_iters (
int)theta_search_grid (
int)theta_refine_iters (
int)fit_tol_max_factor (
float)prefer_smallest_N (
bool)rho_in (
float)rho_out (
float)check_theta_grid (
int)min_abs_deriv_factor (
float)min_sep_factor (
float)poly_eps_factor (
float)
- classmethod from_pipeline_config(cfg)[source]
Create from pipeline_config.json structure.
- Parameters:
cfg (
dict)- Return type:
- __init__(N_min=6, N_max=64, m_samples=2048, lambda_init=1e-06, lambda_increase_factor=10.0, max_lambda_tries=6, reparam_iters=2, theta_search_grid=2048, theta_refine_iters=3, fit_tol_max_factor=0.002, prefer_smallest_N=True, rho_in=0.97, rho_out=1.03, check_theta_grid=4096, min_abs_deriv_factor=1e-08, min_sep_factor=1e-05, poly_eps_factor=0.0005)
- Parameters:
N_min (
int)N_max (
int)m_samples (
int)lambda_init (
float)lambda_increase_factor (
float)max_lambda_tries (
int)reparam_iters (
int)theta_search_grid (
int)theta_refine_iters (
int)fit_tol_max_factor (
float)prefer_smallest_N (
bool)rho_in (
float)rho_out (
float)check_theta_grid (
int)min_abs_deriv_factor (
float)min_sep_factor (
float)poly_eps_factor (
float)
- Return type:
None
- class analytic_continuation.LaurentMapResult[source]
Bases:
objectResult of Laurent map evaluation.
- classmethod from_laurent_map(lm)[source]
Create from serializable LaurentMap type.
- Parameters:
lm (
LaurentMap)- Return type:
- class analytic_continuation.FitResult[source]
Bases:
objectResult of fitting a Laurent map.
- Parameters:
- laurent_map: LaurentMapResult | None = None
- __init__(ok, failure_reason=None, curve_scale=0.0, polyline_used=<factory>, laurent_map=None, fit_max_err=inf, fit_rms_err=inf, simple_on_unit_circle=False, min_abs_deriv_unit=0.0, min_sep_unit=0.0, min_sep_in=0.0, min_sep_out=0.0)
- Parameters:
- Return type:
None
- analytic_continuation.fit_laurent_map(export, cfg=None)[source]
Fit a Laurent map to a SplineExport curve.
This is the main entry point for Stage 3.
- Parameters:
export (SplineExport) – The input curve data
cfg (LaurentFitConfig, optional) – Configuration parameters
- Returns:
The fitting result including the Laurent map if successful
- Return type:
- analytic_continuation.load_polyline_from_export(export, field_name='adaptivePolyline', drop_duplicate_terminal=True)[source]
Load polyline from SplineExport, converting to complex.
- Parameters:
export (SplineExport) – The spline export data
field_name (str) – Which field to use: ‘adaptivePolyline’, ‘spline’, or ‘controlPoints’
drop_duplicate_terminal (bool) – If True, remove trailing points that duplicate the first point
- Returns:
The polyline as complex numbers
- Return type:
List[complex]
- analytic_continuation.estimate_diameter(poly)[source]
Estimate curve diameter as max pairwise distance.
- class analytic_continuation.HolomorphicCheckConfig[source]
Bases:
objectConfiguration for pole checking (Stage 4).
- Parameters:
- class analytic_continuation.InvertConfig[source]
Bases:
objectConfiguration for map inversion (Stage 5).
- Parameters:
- __init__(theta_grid=256, seed_radii=<factory>, max_iters=40, tol_abs_factor=1e-10, tol_rel_factor=1e-10, damping=True, max_backtracks=12)
- class analytic_continuation.HolomorphicCheckResult[source]
Bases:
objectResult of checking if f is holomorphic on annulus image.
- Parameters:
- __init__(ok, min_pole_distance, closest_pole=None, failure_reason=None, updated_rho_in=None, updated_rho_out=None)
- class analytic_continuation.CompositionResult[source]
Bases:
objectResult of computing the composition.
- Parameters:
- analytic_continuation.check_f_holomorphic_on_annulus(poles, lmap, curve_scale, min_distance_param, cfg=None)[source]
Stage 4: Check that f’s poles are sufficiently far from the annulus image.
- Parameters:
poles (List[Pole]) – The poles of the meromorphic function f
lmap (LaurentMapResult) – The fitted Laurent map
curve_scale (float) – The diameter of the curve (for scaling)
min_distance_param (float) – The minDistance parameter from SplineExport (for pole margin)
cfg (HolomorphicCheckConfig, optional) – Configuration
- Return type:
- analytic_continuation.invert_z(z_query, lmap, curve_scale, cfg=None)[source]
Stage 5: Invert z(ζ) = z_query using multi-start Newton iteration.
- Parameters:
z_query (complex) – The point to invert
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – The diameter of the curve (for tolerance scaling)
cfg (InvertConfig, optional) – Configuration
- Return type:
- analytic_continuation.compute_composition(z_query, f, lmap, curve_scale, invert_cfg=None)[source]
Stage 6: Compute A(f(B(z_query))) using the shared parameterization shortcut.
- Because reflections A and B are defined via the shared parameter ζ:
B(z(ζ)) = z(1/conj(ζ)) A(w(ζ)) = w(1/conj(ζ)) where w(ζ) = f(z(ζ))
- The composition simplifies:
A(f(B(z(ζ)))) = f(z(ζ))
So we just need to: 1. Invert z_query to find ζ 2. Return f(z(ζ)) = f(z_query) if ζ is on the unit circle
- Parameters:
z_query (complex) – The query point
f (Callable[[complex], complex]) – The meromorphic function to evaluate
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – The diameter of the curve
invert_cfg (InvertConfig, optional) – Configuration for inversion
- Return type:
- analytic_continuation.compute_continuation_grid(f, lmap, curve_scale, x_range, y_range, resolution, invert_cfg=None)[source]
Compute the analytic continuation of f on a grid.
Returns both the computed values and a mask indicating which points converged.
- Parameters:
f (Callable) – The meromorphic function
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – Curve diameter for tolerance scaling
resolution (int) – Number of grid points per axis
invert_cfg (InvertConfig, optional) – Inversion configuration
- Return type:
- Returns:
values (np.ndarray) – Complex array of shape (resolution, resolution) with computed values
converged (np.ndarray) – Boolean array indicating which points converged
- class analytic_continuation.PipelineLogger[source]
Bases:
objectLogger for the analytic continuation pipeline.
Provides: - Structured logging to console/file - SQLite persistence for session recovery - Progress tracking for UI updates
- register_progress_callback(callback)[source]
Register a callback for progress updates.
- Parameters:
callback (
callable)
- unregister_progress_callback(callback)[source]
Unregister a progress callback.
- Parameters:
callback (
callable)
- static compute_input_hash(expression=None, curve_data=None, zeros=None, poles=None)[source]
Compute a hash of the input parameters for session matching.
This allows finding previous sessions with identical inputs for potential resumption.
- find_resumable_session(expression=None, curve_data=None, zeros=None, poles=None)[source]
Find a previous session with matching inputs that can be resumed.
Returns session info including what stages were completed, or None if no matching session exists.
- start_session(expression=None, curve_data=None, zeros=None, poles=None)[source]
Start a new pipeline session.
- update_session_stage(stage, session_id=None)[source]
Update the last completed stage for a session.
- get_session(session_id)[source]
Retrieve a session by ID.
- Parameters:
session_id (
str)- Return type:
- start_task(task_id, name, session_id=None)[source]
Start tracking a new task.
- Parameters:
- Return type:
- update_task(task_id, progress=None, message=None, metadata=None, session_id=None)[source]
Update task progress.
- complete_task(task_id, success=True, error=None, metadata=None, session_id=None)[source]
Mark a task as completed or failed.
- cache_computation(cache_key, stage, data, session_id=None)[source]
Cache intermediate computation results for recovery.
- end_session(success=True, result=None, error=None, session_id=None)[source]
End the current session.
- class analytic_continuation.TaskStatus[source]
-
Status of a pipeline task.
- PENDING = 'pending'
- IN_PROGRESS = 'in_progress'
- COMPLETED = 'completed'
- FAILED = 'failed'
- SKIPPED = 'skipped'
- __new__(value)
- class analytic_continuation.TaskProgress[source]
Bases:
objectProgress information for a single task.
- Parameters:
- status: TaskStatus = 'pending'
- __init__(task_id, name, status=TaskStatus.PENDING, progress=0.0, message='', started_at=None, completed_at=None, error=None, metadata=<factory>)
- class analytic_continuation.PipelineSession[source]
Bases:
objectRepresents a complete pipeline execution session.
- Parameters:
- tasks: List[TaskProgress]
- status: TaskStatus = 'pending'
- __init__(session_id, created_at, expression=None, curve_data=None, zeros=<factory>, poles=<factory>, tasks=<factory>, result=None, status=TaskStatus.PENDING)
- class analytic_continuation.ProgressTracker[source]
Bases:
objectTracks progress through the analytic continuation pipeline.
Provides: - Stage-by-stage progress tracking - Real-time updates via callbacks or SSE - Checklist-style UI output
- async update_stage(stage_id, progress=None, message=None, substeps_done=None)[source]
Update stage progress.
- async complete_stage(stage_id, success=True, error=None, message=None)[source]
Complete a pipeline stage.
- sync_start_stage(stage_id, substeps_total=0, message='')[source]
Synchronous version of start_stage for non-async contexts.
- class analytic_continuation.StageInfo[source]
Bases:
objectInformation about a pipeline stage.
- Parameters:
- status: TaskStatus = 'pending'
- __init__(id, name, description, status=TaskStatus.PENDING, progress=0.0, message='', substeps_total=0, substeps_done=0, started_at=None, completed_at=None, error=None)
- analytic_continuation.format_cli_progress(tracker)[source]
Format progress as CLI-style checklist output.
Example output: ┌─────────────────────────────────────────────────┐ │ Analytic Continuation Pipeline │ ├─────────────────────────────────────────────────┤ │ ✓ Validate Input [████████████] 100% │ │ ✓ Load Curve [████████████] 100% │ │ ● Fit Laurent Map [████████░░░░] 67% │ │ Fitting N=24… │ │ ○ Check Holomorphic [░░░░░░░░░░░░] 0% │ │ ○ Prepare Render [░░░░░░░░░░░░] 0% │ │ ○ Render [░░░░░░░░░░░░] 0% │ └─────────────────────────────────────────────────┘
- Parameters:
tracker (
ProgressTracker)- Return type:
- class analytic_continuation.CesaroRepresentation[source]
Bases:
objectCesàro intrinsic form: κ(s) - curvature as function of arc length.
- arc_lengths
Cumulative arc length values s[i] at sample points
- Type:
np.ndarray
- curvatures
Curvature κ(s[i]) at each sample point
- Type:
np.ndarray
- class analytic_continuation.WhewellRepresentation[source]
Bases:
objectWhewell intrinsic form: φ(s) - tangent angle as function of arc length.
The tangent angle φ(s) = ∫₀ˢ κ(t) dt + φ₀
- arc_lengths
Cumulative arc length values
- Type:
np.ndarray
- tangent_angles
Tangent angle φ(s[i]) at each sample point (radians)
- Type:
np.ndarray
- winding_number
φ(L) - φ(0) = 2π·n for winding number n (should be 2π for simple curves)
- Type:
- Parameters:
- class analytic_continuation.LogBijectionData[source]
Bases:
objectNatural log of the bijection z(ζ), storing both the original Laurent coefficients and derived intrinsic representations.
- Taking log linearizes the multiplicative structure:
log(z(ζ)) = log|z| + i·arg(z)
- The derivative relationship:
d/dζ[log(z(ζ))] = z’(ζ)/z(ζ)
- Parameters:
- __init__(laurent_N, laurent_a0, laurent_a, laurent_b, curve_scale, theta_samples, log_z_samples, z_samples, log_derivative_samples)
- class analytic_continuation.ComplexityEstimates[source]
Bases:
objectComputational complexity estimates derived from intrinsic curve analysis.
These predict the relative difficulty of: - Inverting z(ζ) = z_query (finding ζ given z) - Evaluating the continuation at many points - Achieving a target accuracy
- Parameters:
total_curvature (
float)curvature_variation (
float)max_curvature (
float)mean_curvature (
float)curvature_std (
float)winding_number (
float)total_arc_length (
float)log_deriv_variation (
float)arg_deriv_variation (
float)min_jacobian (
float)max_jacobian (
float)jacobian_ratio (
float)inversion_difficulty (
float)sampling_density_factor (
float)newton_convergence_factor (
float)
- __init__(total_curvature, curvature_variation, max_curvature, mean_curvature, curvature_std, winding_number, total_arc_length, log_deriv_variation, arg_deriv_variation, min_jacobian, max_jacobian, jacobian_ratio, inversion_difficulty, sampling_density_factor, newton_convergence_factor)
- Parameters:
total_curvature (
float)curvature_variation (
float)max_curvature (
float)mean_curvature (
float)curvature_std (
float)winding_number (
float)total_arc_length (
float)log_deriv_variation (
float)arg_deriv_variation (
float)min_jacobian (
float)max_jacobian (
float)jacobian_ratio (
float)inversion_difficulty (
float)sampling_density_factor (
float)newton_convergence_factor (
float)
- Return type:
None
- class analytic_continuation.IntrinsicCurveAnalysis[source]
Bases:
objectComplete intrinsic curve analysis of a bijection.
Bundles together: - Log bijection data - Cesàro representation - Whewell representation - Complexity estimates
- Parameters:
log_data (
LogBijectionData)cesaro (
CesaroRepresentation)whewell (
WhewellRepresentation)complexity (
ComplexityEstimates)
- log_data: LogBijectionData
- cesaro: CesaroRepresentation
- whewell: WhewellRepresentation
- complexity: ComplexityEstimates
- __init__(log_data, cesaro, whewell, complexity)
- Parameters:
log_data (
LogBijectionData)cesaro (
CesaroRepresentation)whewell (
WhewellRepresentation)complexity (
ComplexityEstimates)
- Return type:
None
- analytic_continuation.analyze_bijection(lmap, curve_scale, samples=4096)[source]
Perform complete intrinsic curve analysis of a Laurent bijection.
This is the main entry point for complexity estimation.
- Parameters:
lmap (LaurentMapResult) – The fitted Laurent map z(ζ)
curve_scale (float) – The diameter/scale of the curve
samples (int) – Number of samples for analysis
- Returns:
Complete analysis including Cesàro, Whewell, and complexity estimates
- Return type:
Example
>>> from analytic_continuation.laurent import fit_laurent_map >>> from analytic_continuation.intrinsic_curve import analyze_bijection >>> >>> # After fitting a Laurent map >>> result = fit_laurent_map(spline_export) >>> if result.ok: ... analysis = analyze_bijection(result.laurent_map, result.curve_scale) ... print(analysis.summary()) ... ... # Use complexity estimates to tune parameters ... if analysis.complexity.inversion_difficulty > 2.0: ... # Increase Newton iterations ... pass
- analytic_continuation.compute_log_bijection(lmap, curve_scale, samples=4096)[source]
Compute the natural log of the bijection z(ζ) on the unit circle.
Uses continuous branch selection for log(z) to avoid discontinuities.
- Parameters:
lmap (LaurentMapResult) – The fitted Laurent map
curve_scale (float) – The diameter/scale of the curve
samples (int) – Number of samples on the unit circle
- Returns:
The log-transformed bijection data
- Return type:
- analytic_continuation.compute_cesaro_form(log_data)[source]
Convert log bijection data to Cesàro form κ(s).
where z’ = dz/dθ.
- Parameters:
log_data (LogBijectionData) – The log-transformed bijection data
- Returns:
The Cesàro (curvature) representation
- Return type:
- analytic_continuation.compute_whewell_form(cesaro, initial_angle=0.0)[source]
Convert Cesàro form to Whewell form φ(s) by integration.
φ(s) = φ₀ + ∫₀ˢ κ(t) dt
- Parameters:
cesaro (CesaroRepresentation) – The Cesàro (curvature) representation
initial_angle (float) – Initial tangent angle φ(0)
- Returns:
The Whewell (tangent angle) representation
- Return type:
- analytic_continuation.estimate_complexity(log_data, cesaro, whewell)[source]
Compute complexity estimates from intrinsic curve representations.
The estimates predict computational costs for: - Newton iteration for inversion - Sampling density requirements - Overall pipeline complexity
- Parameters:
log_data (LogBijectionData) – The log-transformed bijection
cesaro (CesaroRepresentation) – The Cesàro representation
whewell (WhewellRepresentation) – The Whewell representation
- Returns:
The complexity analysis results
- Return type:
- analytic_continuation.suggest_inversion_config(complexity, base_theta_grid=256, base_max_iters=40)[source]
Suggest inversion configuration based on complexity analysis.
- Parameters:
complexity (ComplexityEstimates) – The complexity analysis
base_theta_grid (int) – Base number of theta samples
base_max_iters (int) – Base max Newton iterations
- Returns:
Suggested InvertConfig parameters
- Return type:
- class analytic_continuation.ContourPreCheckResult[source]
Bases:
objectResult of quick pre-check on a raw user-drawn contour.
This is a fast “fail early” gate before expensive Laurent fitting.
- Parameters:
ok (
bool)proceed (
bool)is_closed (
bool)is_simple (
bool)has_sufficient_points (
bool)has_reasonable_aspect (
bool)has_reasonable_curvature (
bool)num_points (
int)perimeter (
float)aspect_ratio (
float)estimated_diameter (
float)min_segment_length (
float)max_segment_length (
float)max_turning_angle (
float)estimated_difficulty (
str)
- __init__(ok, proceed, is_closed, is_simple, has_sufficient_points, has_reasonable_aspect, has_reasonable_curvature, num_points, perimeter, bounding_box, aspect_ratio, estimated_diameter, min_segment_length, max_segment_length, max_turning_angle, warnings, errors, estimated_difficulty, estimated_fit_time_seconds=None)
- Parameters:
ok (
bool)proceed (
bool)is_closed (
bool)is_simple (
bool)has_sufficient_points (
bool)has_reasonable_aspect (
bool)has_reasonable_curvature (
bool)num_points (
int)perimeter (
float)aspect_ratio (
float)estimated_diameter (
float)min_segment_length (
float)max_segment_length (
float)max_turning_angle (
float)estimated_difficulty (
str)
- Return type:
None
- analytic_continuation.precheck_contour(points, closed=True, min_points=8, max_aspect_ratio=20.0, max_turning_angle_deg=170.0, min_segment_ratio=0.001)[source]
Quick pre-check on a raw user-drawn contour before Laurent fitting.
This is a fast “fail early” gate at Stage 1 to catch obviously bad contours before wasting time on expensive computations.
- Parameters:
points (List[Tuple[float, float]]) – The contour points (x, y) from user input or adaptive polyline
closed (bool) – Whether the contour should be treated as closed
min_points (int) – Minimum number of points required
max_aspect_ratio (float) – Maximum allowed aspect ratio (rejects very thin curves)
max_turning_angle_deg (float) – Maximum turning angle in degrees (rejects near-cusps)
min_segment_ratio (float) – Minimum segment length as fraction of perimeter
- Returns:
Pre-check results with pass/fail and diagnostics
- Return type:
- analytic_continuation.precheck_contour_from_spline_export(control_points, adaptive_polyline=None, closed=True)[source]
Pre-check a contour from SplineExport data.
Uses adaptive polyline if available (more accurate), otherwise control points.
- analytic_continuation.get_schema(name)[source]
Load a JSON schema by name.
- Parameters:
name (
str) – Schema name (e.g., ‘types’, ‘function_contracts’) The .json extension is optional.- Return type:
- Returns:
The parsed JSON schema as a dictionary
- Raises:
SchemaNotFoundError – If the schema is not found
Examples
>>> types_schema = get_schema('types') >>> contracts = get_schema('function_contracts')
- analytic_continuation.get_config(name)[source]
Load a configuration file by name.
- Parameters:
name (
str) – Config name (e.g., ‘pipeline_config’) The .json extension is optional.- Return type:
- Returns:
The parsed configuration as a dictionary
- Raises:
SchemaNotFoundError – If the config is not found
Examples
>>> config = get_config('pipeline_config') >>> print(config['pipeline'])
- analytic_continuation.get_example(name)[source]
Load an example file by name.
- Parameters:
name (
str) – Example name (e.g., ‘spline_export.sample’) The .json extension is optional.- Return type:
- Returns:
The parsed example data as a dictionary
- Raises:
SchemaNotFoundError – If the example is not found
Examples
>>> spline_data = get_example('spline_export.sample') >>> print(spline_data['version'])
- analytic_continuation.validate(data, schema_name)[source]
Validate data against a named schema.
This function requires the optional jsonschema dependency. Install with: pip install analytic-continuation[validation]
Note: The schemas in this package are type definitions rather than JSON Schema format. This function performs structural validation by checking that required keys exist in the data.
- Parameters:
- Return type:
- Returns:
True if validation passes
- Raises:
ValidationError – If validation fails
ImportError – If jsonschema is not installed
SchemaNotFoundError – If the schema is not found
Examples
>>> from analytic_continuation.schemas import validate >>> validate({'re': 1.0, 'im': 2.0}, 'types') # validates Complex type
Types Module
Core type definitions used throughout the package.
Type definitions for analytic continuation package.
Matches the schemas defined in laurent_pipeline_bundle/schemas/types.json
- class analytic_continuation.types.Point[source]
Bases:
objectA 2D point, used for both screen and logical coordinates.
- class analytic_continuation.types.Spline[source]
Bases:
objectA sequence of points forming a spline or polyline.
- class analytic_continuation.types.SplineParameters[source]
Bases:
objectParameters from a SplineExport.
- class analytic_continuation.types.SplineExport[source]
Bases:
objectFull spline export structure matching the React frontend format.
Contains control points, interpolated spline, and adaptive polyline.
- Parameters:
- parameters: SplineParameters
- __init__(version, timestamp, closed, parameters, controlPoints, spline=<factory>, adaptivePolyline=<factory>, stats=None)
- class analytic_continuation.types.Complex[source]
Bases:
objectComplex number representation matching the schema.
Space Adapter Module
Coordinate transformation utilities.
Space adapter for transforming between screen and logical (complex plane) coordinates.
The adapter handles: - Offset (translation) - Scale (uniform or non-uniform) - Y-axis flip (screen Y increases downward, logical Y increases upward)
- class analytic_continuation.space_adapter.TransformParams[source]
Bases:
objectParameters defining the screen-to-logical coordinate transformation.
Screen space: origin at top-left, Y increases downward, pixel units Logical space: complex plane, Y increases upward, mathematical units
- The transform is:
logical_x = (screen_x - offset_x) / scale_x logical_y = (offset_y - screen_y) / scale_y (note Y flip)
- Or equivalently:
screen_x = logical_x * scale_x + offset_x screen_y = offset_y - logical_y * scale_y
- classmethod from_view_bounds(screen_width, screen_height, logical_x_range, logical_y_range, uniform=True)[source]
Create transform params from screen dimensions and logical view bounds.
- Parameters:
screen_width (float) – Screen dimensions in pixels
screen_height (float) – Screen dimensions in pixels
logical_x_range (tuple) – (x_min, x_max) in logical coordinates
logical_y_range (tuple) – (y_min, y_max) in logical coordinates
uniform (bool) – If True, use the same scale for both axes (may add margins)
- Return type:
- class analytic_continuation.space_adapter.SpaceAdapter[source]
Bases:
objectTransforms coordinates between screen space and logical (complex plane) space.
- Screen space:
Origin at top-left
X increases rightward
Y increases downward
Units are pixels
- Logical space:
Complex plane
X is the real axis
Y is the imaginary axis (increases upward)
Units are mathematical units
- Parameters:
params (
Optional[TransformParams])
- __init__(params=None)[source]
Initialize the space adapter.
- Parameters:
params (TransformParams, optional) – Transform parameters. If None, uses identity transform.
- screen_to_logical(screen_x, screen_y)[source]
Transform a point from screen space to logical space.
- logical_to_screen(logical_x, logical_y)[source]
Transform a point from logical space to screen space.
- transform_points_to_logical(points)[source]
Transform a list of points from screen to logical space.
- transform_points_to_screen(points)[source]
Transform a list of points from logical to screen space.
- transform_spline_export_to_logical(export)[source]
Transform a full SplineExport from screen to logical space.
Transforms all point arrays (controlPoints, spline, adaptivePolyline). Also scales the parameters.minDistance accordingly.
- Parameters:
export (
SplineExport)- Return type:
- screen_distance_to_logical(screen_distance)[source]
Convert a distance from screen units to logical units.
For non-uniform scaling, uses the geometric mean of scale factors.
- logical_distance_to_screen(logical_distance)[source]
Convert a distance from logical units to screen units.
For non-uniform scaling, uses the geometric mean of scale factors.
- with_params(**kwargs)[source]
Create a new SpaceAdapter with modified parameters.
- Parameters:
**kwargs – Parameters to override (offset_x, offset_y, scale_x, scale_y)
- Returns:
New adapter with modified parameters
- Return type:
- zoom(factor, center_screen=None)[source]
Create a new adapter with zoomed view.
- Parameters:
- Return type:
- pan(delta_screen_x, delta_screen_y)[source]
Create a new adapter with panned view.
- Parameters:
- Return type:
Laurent Module
Laurent series fitting and evaluation.
Laurent map fitting and evaluation for analytic continuation.
Implements Stage 3 of the pipeline: fitting z(ζ) so that the unit circle maps to approximate a Jordan curve.
- class analytic_continuation.laurent.LaurentFitConfig[source]
Bases:
objectConfiguration for Laurent map fitting.
- Parameters:
N_min (
int)N_max (
int)m_samples (
int)lambda_init (
float)lambda_increase_factor (
float)max_lambda_tries (
int)reparam_iters (
int)theta_search_grid (
int)theta_refine_iters (
int)fit_tol_max_factor (
float)prefer_smallest_N (
bool)rho_in (
float)rho_out (
float)check_theta_grid (
int)min_abs_deriv_factor (
float)min_sep_factor (
float)poly_eps_factor (
float)
- classmethod from_pipeline_config(cfg)[source]
Create from pipeline_config.json structure.
- Parameters:
cfg (
dict)- Return type:
- __init__(N_min=6, N_max=64, m_samples=2048, lambda_init=1e-06, lambda_increase_factor=10.0, max_lambda_tries=6, reparam_iters=2, theta_search_grid=2048, theta_refine_iters=3, fit_tol_max_factor=0.002, prefer_smallest_N=True, rho_in=0.97, rho_out=1.03, check_theta_grid=4096, min_abs_deriv_factor=1e-08, min_sep_factor=1e-05, poly_eps_factor=0.0005)
- Parameters:
N_min (
int)N_max (
int)m_samples (
int)lambda_init (
float)lambda_increase_factor (
float)max_lambda_tries (
int)reparam_iters (
int)theta_search_grid (
int)theta_refine_iters (
int)fit_tol_max_factor (
float)prefer_smallest_N (
bool)rho_in (
float)rho_out (
float)check_theta_grid (
int)min_abs_deriv_factor (
float)min_sep_factor (
float)poly_eps_factor (
float)
- Return type:
None
- class analytic_continuation.laurent.LaurentMapResult[source]
Bases:
objectResult of Laurent map evaluation.
- classmethod from_laurent_map(lm)[source]
Create from serializable LaurentMap type.
- Parameters:
lm (
LaurentMap)- Return type:
- class analytic_continuation.laurent.FitResult[source]
Bases:
objectResult of fitting a Laurent map.
- Parameters:
- laurent_map: LaurentMapResult | None = None
- __init__(ok, failure_reason=None, curve_scale=0.0, polyline_used=<factory>, laurent_map=None, fit_max_err=inf, fit_rms_err=inf, simple_on_unit_circle=False, min_abs_deriv_unit=0.0, min_sep_unit=0.0, min_sep_in=0.0, min_sep_out=0.0)
- Parameters:
- Return type:
None
- analytic_continuation.laurent.load_polyline_from_export(export, field_name='adaptivePolyline', drop_duplicate_terminal=True)[source]
Load polyline from SplineExport, converting to complex.
- Parameters:
export (SplineExport) – The spline export data
field_name (str) – Which field to use: ‘adaptivePolyline’, ‘spline’, or ‘controlPoints’
drop_duplicate_terminal (bool) – If True, remove trailing points that duplicate the first point
- Returns:
The polyline as complex numbers
- Return type:
List[complex]
- analytic_continuation.laurent.estimate_diameter(poly)[source]
Estimate curve diameter as max pairwise distance.
- analytic_continuation.laurent.resample_closed_polyline(poly, m)[source]
Resample a closed polyline by arc length to m points.
Returns array of m complex points, uniformly spaced by arc length.
- analytic_continuation.laurent.build_laurent_matrix(thetas, N)[source]
Build the design matrix for Laurent fitting.
For m sample points and degree N, produces m x (1 + 2N) complex matrix. Column 0: constant term (1) Columns 1..N: positive powers ζ^1, …, ζ^N Columns N+1..2N: negative powers ζ^{-1}, …, ζ^{-N}
- analytic_continuation.laurent.solve_tikhonov(A, y, N, lam)[source]
Solve regularized least squares with Tikhonov penalty.
Penalty weights: k^2 on coefficients a_k, b_k (k=1..N), no penalty on a0.
Uses real-valued formulation: stack real and imaginary parts.
- analytic_continuation.laurent.check_polyline_simple(poly, eps)[source]
Check if a closed polyline is simple (non-self-intersecting).
Uses segment-segment intersection test with tolerance.
- analytic_continuation.laurent.check_laurent_map(lmap, rho_in, rho_out, theta_grid, min_abs_deriv, min_sep, poly_eps)[source]
Check Laurent map quality on the annulus.
Returns dict with: - simple_on_unit_circle: bool - min_abs_deriv_unit: float - min_sep_unit, min_sep_in, min_sep_out: float - ok: bool
- analytic_continuation.laurent.reparam_closest_theta(lmap, targets, theta_grid, refine_iters)[source]
Reparameterize by finding closest theta for each target point.
For each target z, find θ minimizing |z(e^{iθ}) - z|.
- Parameters:
lmap (
LaurentMapResult)targets (
ndarray)theta_grid (
int)refine_iters (
int)
- Return type:
- analytic_continuation.laurent.fit_laurent_map(export, cfg=None)[source]
Fit a Laurent map to a SplineExport curve.
This is the main entry point for Stage 3.
- Parameters:
export (SplineExport) – The input curve data
cfg (LaurentFitConfig, optional) – Configuration parameters
- Returns:
The fitting result including the Laurent map if successful
- Return type:
Meromorphic Module
Meromorphic function construction from zeros and poles.
Meromorphic function construction from zeros and poles.
Converts lists of zeros/poles (with optional multiplicities) to mathematical expressions parseable by py_domaincolor/sympy.
- class analytic_continuation.meromorphic.Singularity[source]
Bases:
objectA zero or pole with location and multiplicity.
- analytic_continuation.meromorphic.build_meromorphic_expression(zeros, poles, normalize=False)[source]
Build a sympy-compatible expression for a meromorphic function.
- Parameters:
zeros (List[Singularity]) – List of zeros with locations and multiplicities
poles (List[Singularity]) – List of poles with locations and multiplicities
normalize (bool) – If True, add a leading coefficient to normalize (not yet implemented)
- Returns:
Expression string like “(z-1)*(z+1)/((z-i)*(z+i))”
- Return type:
Examples
>>> build_meromorphic_expression( ... zeros=[Singularity(1, 0), Singularity(-1, 0)], ... poles=[Singularity(0, 1), Singularity(0, -1)] ... ) '(z-1)*(z+1)/((z-i)*(z+i))'
- analytic_continuation.meromorphic.meromorphic_from_points(zeros, poles, zero_multiplicities=None, pole_multiplicities=None)[source]
Convenience function to build expression directly from Point lists.
- Parameters:
- Returns:
Sympy-compatible expression
- Return type:
- class analytic_continuation.meromorphic.MeromorphicBuilder[source]
Bases:
objectBuilder class for constructing meromorphic functions interactively.
Integrates with SpaceAdapter for coordinate transforms.
- zeros: List[Singularity]
- poles: List[Singularity]
- add_zero(x, y, multiplicity=1)[source]
Add a zero at (x, y) in logical coordinates.
- Parameters:
- Return type:
- add_pole(x, y, multiplicity=1)[source]
Add a pole at (x, y) in logical coordinates.
- Parameters:
- Return type:
- add_zero_from_screen(screen_x, screen_y, adapter, multiplicity=1)[source]
Add a zero from screen coordinates, transforming via adapter.
- add_pole_from_screen(screen_x, screen_y, adapter, multiplicity=1)[source]
Add a pole from screen coordinates, transforming via adapter.
Continuation Module
Analytic continuation pipeline utilities.
Analytic continuation pipeline: Stages 4-6.
Stage 4: Check that f’s poles are outside the annulus image Stage 5: Invert z(ζ) = z_query to find ζ Stage 6: Compute the composition A(f(B(z))) via shared parameterization
- class analytic_continuation.continuation.Pole[source]
Bases:
objectA pole of the meromorphic function f.
- class analytic_continuation.continuation.HolomorphicCheckConfig[source]
Bases:
objectConfiguration for pole checking (Stage 4).
- Parameters:
- class analytic_continuation.continuation.InvertConfig[source]
Bases:
objectConfiguration for map inversion (Stage 5).
- Parameters:
- __init__(theta_grid=256, seed_radii=<factory>, max_iters=40, tol_abs_factor=1e-10, tol_rel_factor=1e-10, damping=True, max_backtracks=12)
- class analytic_continuation.continuation.HolomorphicCheckResult[source]
Bases:
objectResult of checking if f is holomorphic on annulus image.
- Parameters:
- __init__(ok, min_pole_distance, closest_pole=None, failure_reason=None, updated_rho_in=None, updated_rho_out=None)
- class analytic_continuation.continuation.InvertResult[source]
Bases:
objectResult of inverting z(ζ) = z_query.
- class analytic_continuation.continuation.CompositionResult[source]
Bases:
objectResult of computing the composition.
- Parameters:
- analytic_continuation.continuation.check_f_holomorphic_on_annulus(poles, lmap, curve_scale, min_distance_param, cfg=None)[source]
Stage 4: Check that f’s poles are sufficiently far from the annulus image.
- Parameters:
poles (List[Pole]) – The poles of the meromorphic function f
lmap (LaurentMapResult) – The fitted Laurent map
curve_scale (float) – The diameter of the curve (for scaling)
min_distance_param (float) – The minDistance parameter from SplineExport (for pole margin)
cfg (HolomorphicCheckConfig, optional) – Configuration
- Return type:
- analytic_continuation.continuation.invert_z(z_query, lmap, curve_scale, cfg=None)[source]
Stage 5: Invert z(ζ) = z_query using multi-start Newton iteration.
- Parameters:
z_query (complex) – The point to invert
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – The diameter of the curve (for tolerance scaling)
cfg (InvertConfig, optional) – Configuration
- Return type:
- analytic_continuation.continuation.compute_composition(z_query, f, lmap, curve_scale, invert_cfg=None)[source]
Stage 6: Compute A(f(B(z_query))) using the shared parameterization shortcut.
- Because reflections A and B are defined via the shared parameter ζ:
B(z(ζ)) = z(1/conj(ζ)) A(w(ζ)) = w(1/conj(ζ)) where w(ζ) = f(z(ζ))
- The composition simplifies:
A(f(B(z(ζ)))) = f(z(ζ))
So we just need to: 1. Invert z_query to find ζ 2. Return f(z(ζ)) = f(z_query) if ζ is on the unit circle
- Parameters:
z_query (complex) – The query point
f (Callable[[complex], complex]) – The meromorphic function to evaluate
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – The diameter of the curve
invert_cfg (InvertConfig, optional) – Configuration for inversion
- Return type:
- analytic_continuation.continuation.compute_continuation_grid(f, lmap, curve_scale, x_range, y_range, resolution, invert_cfg=None)[source]
Compute the analytic continuation of f on a grid.
Returns both the computed values and a mask indicating which points converged.
- Parameters:
f (Callable) – The meromorphic function
lmap (LaurentMapResult) – The Laurent map
curve_scale (float) – Curve diameter for tolerance scaling
resolution (int) – Number of grid points per axis
invert_cfg (InvertConfig, optional) – Inversion configuration
- Return type:
- Returns:
values (np.ndarray) – Complex array of shape (resolution, resolution) with computed values
converged (np.ndarray) – Boolean array indicating which points converged
Intrinsic Curve Module
Intrinsic curve analysis using Cesaro and Whewell representations.
Intrinsic curve representations for complexity estimation.
Stores the natural log of the approximate bijection z(ζ) and converts to: - Cesàro form: κ(s) - curvature as function of arc length - Whewell form: φ(s) - tangent angle as function of arc length
These intrinsic representations enable better estimates of computational complexity for the actual bijection work (inversion, evaluation).
Theory
For a conformal map z(ζ) from the unit disk, the composition with log linearizes the multiplicative structure:
w(ζ) = log(z(ζ))
On the unit circle ζ = e^{iθ}, the curve γ(θ) = z(e^{iθ}) has:
Tangent: T(θ) = z’(e^{iθ}) · i·e^{iθ} / |z'(e^{iθ})| Curvature: κ(θ) = Im[z’’(ζ) / z’(ζ)] / |z'(ζ)| on |ζ|=1 Arc length: s(θ) = ∫₀^θ |z'(e^{it})| dt
Complexity Indicators
Total curvature: ∫|κ(s)|ds - measures total “bending”
Curvature variation: ∫|κ’(s)|ds - measures complexity of shape
Winding number: (1/2π)∫κ(s)ds = 1 for simple closed curves
Curvature peaks: max|κ(s)| - tight turns require finer sampling
Log-derivative oscillation: variation of arg(z’(ζ)) on |ζ|=1
- class analytic_continuation.intrinsic_curve.CesaroRepresentation[source]
Bases:
objectCesàro intrinsic form: κ(s) - curvature as function of arc length.
- arc_lengths
Cumulative arc length values s[i] at sample points
- Type:
np.ndarray
- curvatures
Curvature κ(s[i]) at each sample point
- Type:
np.ndarray
- class analytic_continuation.intrinsic_curve.WhewellRepresentation[source]
Bases:
objectWhewell intrinsic form: φ(s) - tangent angle as function of arc length.
The tangent angle φ(s) = ∫₀ˢ κ(t) dt + φ₀
- arc_lengths
Cumulative arc length values
- Type:
np.ndarray
- tangent_angles
Tangent angle φ(s[i]) at each sample point (radians)
- Type:
np.ndarray
- winding_number
φ(L) - φ(0) = 2π·n for winding number n (should be 2π for simple curves)
- Type:
- Parameters:
- class analytic_continuation.intrinsic_curve.LogBijectionData[source]
Bases:
objectNatural log of the bijection z(ζ), storing both the original Laurent coefficients and derived intrinsic representations.
- Taking log linearizes the multiplicative structure:
log(z(ζ)) = log|z| + i·arg(z)
- The derivative relationship:
d/dζ[log(z(ζ))] = z’(ζ)/z(ζ)
- Parameters:
- __init__(laurent_N, laurent_a0, laurent_a, laurent_b, curve_scale, theta_samples, log_z_samples, z_samples, log_derivative_samples)
- class analytic_continuation.intrinsic_curve.ComplexityEstimates[source]
Bases:
objectComputational complexity estimates derived from intrinsic curve analysis.
These predict the relative difficulty of: - Inverting z(ζ) = z_query (finding ζ given z) - Evaluating the continuation at many points - Achieving a target accuracy
- Parameters:
total_curvature (
float)curvature_variation (
float)max_curvature (
float)mean_curvature (
float)curvature_std (
float)winding_number (
float)total_arc_length (
float)log_deriv_variation (
float)arg_deriv_variation (
float)min_jacobian (
float)max_jacobian (
float)jacobian_ratio (
float)inversion_difficulty (
float)sampling_density_factor (
float)newton_convergence_factor (
float)
- __init__(total_curvature, curvature_variation, max_curvature, mean_curvature, curvature_std, winding_number, total_arc_length, log_deriv_variation, arg_deriv_variation, min_jacobian, max_jacobian, jacobian_ratio, inversion_difficulty, sampling_density_factor, newton_convergence_factor)
- Parameters:
total_curvature (
float)curvature_variation (
float)max_curvature (
float)mean_curvature (
float)curvature_std (
float)winding_number (
float)total_arc_length (
float)log_deriv_variation (
float)arg_deriv_variation (
float)min_jacobian (
float)max_jacobian (
float)jacobian_ratio (
float)inversion_difficulty (
float)sampling_density_factor (
float)newton_convergence_factor (
float)
- Return type:
None
- analytic_continuation.intrinsic_curve.compute_log_bijection(lmap, curve_scale, samples=4096)[source]
Compute the natural log of the bijection z(ζ) on the unit circle.
Uses continuous branch selection for log(z) to avoid discontinuities.
- Parameters:
lmap (LaurentMapResult) – The fitted Laurent map
curve_scale (float) – The diameter/scale of the curve
samples (int) – Number of samples on the unit circle
- Returns:
The log-transformed bijection data
- Return type:
- analytic_continuation.intrinsic_curve.compute_cesaro_form(log_data)[source]
Convert log bijection data to Cesàro form κ(s).
where z’ = dz/dθ.
- Parameters:
log_data (LogBijectionData) – The log-transformed bijection data
- Returns:
The Cesàro (curvature) representation
- Return type:
- analytic_continuation.intrinsic_curve.compute_whewell_form(cesaro, initial_angle=0.0)[source]
Convert Cesàro form to Whewell form φ(s) by integration.
φ(s) = φ₀ + ∫₀ˢ κ(t) dt
- Parameters:
cesaro (CesaroRepresentation) – The Cesàro (curvature) representation
initial_angle (float) – Initial tangent angle φ(0)
- Returns:
The Whewell (tangent angle) representation
- Return type:
- analytic_continuation.intrinsic_curve.estimate_complexity(log_data, cesaro, whewell)[source]
Compute complexity estimates from intrinsic curve representations.
The estimates predict computational costs for: - Newton iteration for inversion - Sampling density requirements - Overall pipeline complexity
- Parameters:
log_data (LogBijectionData) – The log-transformed bijection
cesaro (CesaroRepresentation) – The Cesàro representation
whewell (WhewellRepresentation) – The Whewell representation
- Returns:
The complexity analysis results
- Return type:
- class analytic_continuation.intrinsic_curve.IntrinsicCurveAnalysis[source]
Bases:
objectComplete intrinsic curve analysis of a bijection.
Bundles together: - Log bijection data - Cesàro representation - Whewell representation - Complexity estimates
- Parameters:
log_data (
LogBijectionData)cesaro (
CesaroRepresentation)whewell (
WhewellRepresentation)complexity (
ComplexityEstimates)
- log_data: LogBijectionData
- cesaro: CesaroRepresentation
- whewell: WhewellRepresentation
- complexity: ComplexityEstimates
- __init__(log_data, cesaro, whewell, complexity)
- Parameters:
log_data (
LogBijectionData)cesaro (
CesaroRepresentation)whewell (
WhewellRepresentation)complexity (
ComplexityEstimates)
- Return type:
None
- analytic_continuation.intrinsic_curve.analyze_bijection(lmap, curve_scale, samples=4096)[source]
Perform complete intrinsic curve analysis of a Laurent bijection.
This is the main entry point for complexity estimation.
- Parameters:
lmap (LaurentMapResult) – The fitted Laurent map z(ζ)
curve_scale (float) – The diameter/scale of the curve
samples (int) – Number of samples for analysis
- Returns:
Complete analysis including Cesàro, Whewell, and complexity estimates
- Return type:
Example
>>> from analytic_continuation.laurent import fit_laurent_map >>> from analytic_continuation.intrinsic_curve import analyze_bijection >>> >>> # After fitting a Laurent map >>> result = fit_laurent_map(spline_export) >>> if result.ok: ... analysis = analyze_bijection(result.laurent_map, result.curve_scale) ... print(analysis.summary()) ... ... # Use complexity estimates to tune parameters ... if analysis.complexity.inversion_difficulty > 2.0: ... # Increase Newton iterations ... pass
- analytic_continuation.intrinsic_curve.suggest_inversion_config(complexity, base_theta_grid=256, base_max_iters=40)[source]
Suggest inversion configuration based on complexity analysis.
- Parameters:
complexity (ComplexityEstimates) – The complexity analysis
base_theta_grid (int) – Base number of theta samples
base_max_iters (int) – Base max Newton iterations
- Returns:
Suggested InvertConfig parameters
- Return type:
- class analytic_continuation.intrinsic_curve.ContourPreCheckResult[source]
Bases:
objectResult of quick pre-check on a raw user-drawn contour.
This is a fast “fail early” gate before expensive Laurent fitting.
- Parameters:
ok (
bool)proceed (
bool)is_closed (
bool)is_simple (
bool)has_sufficient_points (
bool)has_reasonable_aspect (
bool)has_reasonable_curvature (
bool)num_points (
int)perimeter (
float)aspect_ratio (
float)estimated_diameter (
float)min_segment_length (
float)max_segment_length (
float)max_turning_angle (
float)estimated_difficulty (
str)
- __init__(ok, proceed, is_closed, is_simple, has_sufficient_points, has_reasonable_aspect, has_reasonable_curvature, num_points, perimeter, bounding_box, aspect_ratio, estimated_diameter, min_segment_length, max_segment_length, max_turning_angle, warnings, errors, estimated_difficulty, estimated_fit_time_seconds=None)
- Parameters:
ok (
bool)proceed (
bool)is_closed (
bool)is_simple (
bool)has_sufficient_points (
bool)has_reasonable_aspect (
bool)has_reasonable_curvature (
bool)num_points (
int)perimeter (
float)aspect_ratio (
float)estimated_diameter (
float)min_segment_length (
float)max_segment_length (
float)max_turning_angle (
float)estimated_difficulty (
str)
- Return type:
None
- analytic_continuation.intrinsic_curve.precheck_contour(points, closed=True, min_points=8, max_aspect_ratio=20.0, max_turning_angle_deg=170.0, min_segment_ratio=0.001)[source]
Quick pre-check on a raw user-drawn contour before Laurent fitting.
This is a fast “fail early” gate at Stage 1 to catch obviously bad contours before wasting time on expensive computations.
- Parameters:
points (List[Tuple[float, float]]) – The contour points (x, y) from user input or adaptive polyline
closed (bool) – Whether the contour should be treated as closed
min_points (int) – Minimum number of points required
max_aspect_ratio (float) – Maximum allowed aspect ratio (rejects very thin curves)
max_turning_angle_deg (float) – Maximum turning angle in degrees (rejects near-cusps)
min_segment_ratio (float) – Minimum segment length as fraction of perimeter
- Returns:
Pre-check results with pass/fail and diagnostics
- Return type:
Logging Config Module
Pipeline logging infrastructure.
Logging configuration for the analytic continuation pipeline.
Provides structured logging with optional SQLite persistence for recovery and debugging long-running computations.
- class analytic_continuation.logging_config.TaskStatus[source]
-
Status of a pipeline task.
- PENDING = 'pending'
- IN_PROGRESS = 'in_progress'
- COMPLETED = 'completed'
- FAILED = 'failed'
- SKIPPED = 'skipped'
- __new__(value)
- class analytic_continuation.logging_config.TaskProgress[source]
Bases:
objectProgress information for a single task.
- Parameters:
- status: TaskStatus = 'pending'
- __init__(task_id, name, status=TaskStatus.PENDING, progress=0.0, message='', started_at=None, completed_at=None, error=None, metadata=<factory>)
- class analytic_continuation.logging_config.PipelineSession[source]
Bases:
objectRepresents a complete pipeline execution session.
- Parameters:
- tasks: List[TaskProgress]
- status: TaskStatus = 'pending'
- __init__(session_id, created_at, expression=None, curve_data=None, zeros=<factory>, poles=<factory>, tasks=<factory>, result=None, status=TaskStatus.PENDING)
- class analytic_continuation.logging_config.PipelineLogger[source]
Bases:
objectLogger for the analytic continuation pipeline.
Provides: - Structured logging to console/file - SQLite persistence for session recovery - Progress tracking for UI updates
- register_progress_callback(callback)[source]
Register a callback for progress updates.
- Parameters:
callback (
callable)
- unregister_progress_callback(callback)[source]
Unregister a progress callback.
- Parameters:
callback (
callable)
- static compute_input_hash(expression=None, curve_data=None, zeros=None, poles=None)[source]
Compute a hash of the input parameters for session matching.
This allows finding previous sessions with identical inputs for potential resumption.
- find_resumable_session(expression=None, curve_data=None, zeros=None, poles=None)[source]
Find a previous session with matching inputs that can be resumed.
Returns session info including what stages were completed, or None if no matching session exists.
- start_session(expression=None, curve_data=None, zeros=None, poles=None)[source]
Start a new pipeline session.
- update_session_stage(stage, session_id=None)[source]
Update the last completed stage for a session.
- get_session(session_id)[source]
Retrieve a session by ID.
- Parameters:
session_id (
str)- Return type:
- start_task(task_id, name, session_id=None)[source]
Start tracking a new task.
- Parameters:
- Return type:
- update_task(task_id, progress=None, message=None, metadata=None, session_id=None)[source]
Update task progress.
- complete_task(task_id, success=True, error=None, metadata=None, session_id=None)[source]
Mark a task as completed or failed.
- cache_computation(cache_key, stage, data, session_id=None)[source]
Cache intermediate computation results for recovery.
- end_session(success=True, result=None, error=None, session_id=None)[source]
End the current session.
Progress Module
Progress tracking for pipeline stages.
Progress tracking for the analytic continuation pipeline.
Provides real-time progress updates via Server-Sent Events (SSE) and progress state management for UI display.
- class analytic_continuation.progress.StageInfo[source]
Bases:
objectInformation about a pipeline stage.
- Parameters:
- status: TaskStatus = 'pending'
- __init__(id, name, description, status=TaskStatus.PENDING, progress=0.0, message='', substeps_total=0, substeps_done=0, started_at=None, completed_at=None, error=None)
- class analytic_continuation.progress.ProgressTracker[source]
Bases:
objectTracks progress through the analytic continuation pipeline.
Provides: - Stage-by-stage progress tracking - Real-time updates via callbacks or SSE - Checklist-style UI output
- async update_stage(stage_id, progress=None, message=None, substeps_done=None)[source]
Update stage progress.
- async complete_stage(stage_id, success=True, error=None, message=None)[source]
Complete a pipeline stage.
- sync_start_stage(stage_id, substeps_total=0, message='')[source]
Synchronous version of start_stage for non-async contexts.
- analytic_continuation.progress.format_cli_progress(tracker)[source]
Format progress as CLI-style checklist output.
Example output: ┌─────────────────────────────────────────────────┐ │ Analytic Continuation Pipeline │ ├─────────────────────────────────────────────────┤ │ ✓ Validate Input [████████████] 100% │ │ ✓ Load Curve [████████████] 100% │ │ ● Fit Laurent Map [████████░░░░] 67% │ │ Fitting N=24… │ │ ○ Check Holomorphic [░░░░░░░░░░░░] 0% │ │ ○ Prepare Render [░░░░░░░░░░░░] 0% │ │ ○ Render [░░░░░░░░░░░░] 0% │ └─────────────────────────────────────────────────┘
- Parameters:
tracker (
ProgressTracker)- Return type: