Theory Learn Software Research

On this page

TNFR

Resonant Fractal Nature Theory — a mathematical framework for coherent patterns on graph-coupled networks.

About

Project history
Editorial policy
Contact

Resources

GitHub
PyPI
DOI · Zenodo

Legal

MIT License
Citation

© 2026 TNFR project — MIT licensed.DOI 10.5281/zenodo.17602860

PHYSICS_VERIFICATION.md

API_CONTRACTS.md CANONICAL_OZ_SEQUENCES.md EMPIRICAL_CONFRONTATION_EEG.md README.md STRUCTURAL_FIELDS_TETRAD.md STRUCTURAL_INTERFACE_THEORY.md

APPLIED_STRUCTURAL_ANALYSIS.md CATALOG_TYPE_HYGIENE_PROGRAMME.md DISSIPATIVE_AND_OPEN_SYSTEMS.md EMERGENT_ONTOLOGY.md EXTENDED_FIELDS_AND_DERIVED_QUANTITIES.md FUNDAMENTAL_THEORY.md GAUGE_SYMMETRY_AND_UNIFICATION.md GLOSSARY.md MATHEMATICAL_DYNAMICS_BASIS.md MINIMAL_STRUCTURAL_DEGREES.md NUCLEUS_A_PRIME_LADDER_ATLAS.md NUCLEUS_B_EQUIVARIANCE_OBSTRUCTIONS.md PHYSICAL_REGIME_CORRESPONDENCES.md README.md REMESH_INFINITY_DERIVATION.md STRUCTURAL_CONSERVATION_THEOREM.md STRUCTURAL_OPERATORS.md STRUCTURAL_STABILITY_AND_DYNAMICS.md TNFR_BSD_RESEARCH_NOTES.md TNFR_HODGE_RESEARCH_NOTES.md TNFR_NAVIER_STOKES_RESEARCH_NOTES.md TNFR_NUMBER_THEORY.md TNFR_P_VS_NP_RESEARCH_NOTES.md TNFR_RIEMANN_RESEARCH_NOTES.md TNFR_VARIATIONAL_PRINCIPLE.md TNFR_YANG_MILLS_RESEARCH_NOTES.md TNFR.pdf UNIFIED_GRAMMAR_RULES.md

factorization-lab

analyze_patterns.py certificate_manifest.py

benchmark_analysis.py benchmark_expansion_suite.py full_spectrum_factorization.py paley_gap_extended.py paley_gap_smoke.py test_benchmark_suite.py

experiment_contexts

exp_0b1663cd19b7.json exp_0bf0054b7474.json exp_75a4c8ca616a.json exp_848ee0fd1857.json exp_f6fe00562193.json exp_fdf3da424e1e.json

failure_telemetry_batch.py feedback_integration_demo.py integration_demo_snapshots.db seed_management_integration_demo.py snapshot_integration_demo.py trajectory_143.json trajectory_77.json trajectory_89.json trajectory_91.json trajectory_97.json

FACTORING_PLAYBOOK.md FALSE_POSITIVE_TEST_SUITE.md OPERATOR_CERTIFICATES.md ROADMAP.md SPECTRAL_ROUTE.md

experiment_contexts

exp_cebe1d9e7d8e.json

spectral_history.ipynb

run_false_positive_tests.py

run_false_positive_test_suite.py test_cli.py test_false_positive_methodology.py test_false_positive_verifier.py test_feedback_integration.py test_partitioning.py test_seed_management.py test_self_opt_support.py test_snapshot_system.py test_spectral_paley.py test_verification_robustness.py

tnfr_factorization

__init__.py api.py cli.py failure_telemetry.py feedback_adapter.py feedback_integration.py partitioning.py self_opt_support.py spectral_paley.py

demo_snapshots.db LICENSE_SNAPSHOT.md PACKAGE_SUMMARY.md README.md seed_management.py snapshot_system.py test_certificate_hashing.py test_installation.py verification_trajectory_77.json

analyze_tetrad_universality.py b0star_alpha_canonical_product_graphs.py benchmark_optimization_tracks.py benchmark_utils.py boundary_vibration.py bridge_primes_riemann.py chiral_involution.py cli_utils.py coherence_projector_sense_index.py commutant_bridge.py composition_arithmetic.py confinement_zones_test.py conservation_law_validation.py directed_paley_bridge.py emergent_arithmetic_pulse.py emergent_atom_dynamics.py emergent_atomic_shells.py emergent_base_dimension.py emergent_dimension_dynamics.py emergent_fractal_pulse.py emergent_fractal_simplex_dimension.py emergent_integers_symmetry.py emergent_musical_nfr.py emergent_nfr_geometry.py emergent_nfr_where.py emergent_rationals.py emergent_rhythm.py emergent_screening.py emergent_shell_cardinals.py emergent_shell_ordering.py emergent_simplex_dimension.py emergent_substrate_symmetry.py equivariance_wall.py external_phase_gate_validation.py field_methods_battery.py golden_residue_remesh_bridge.py integrated_force_regime_study.py inverse_spectrum_to_symmetry.py k_phi_safety_demo.py kuramoto_farey_bridge.py missing_piece_bridge.py multichannel_interface_benchmark.py navier_stokes_recipe_bridge.py nodal_propagator_residue_bridge.py ns_moment_hierarchy_cascade.py operational_irreducibility.py paley_bridge.py phase_curvature_investigation.py phase_wall.py phi_s_confinement_investigation.py primes_as_consequence.py pulse_phase_coherence_budget.py README.md remesh_infinity_riemann_baseline.py remesh_infinity_riemann_composed.py remesh_infinity_riemann_modified_graph.py remesh_infinity_riemann_operator.py remesh_infinity_riemann_spectral_basis.py remesh_infinity_riemann_spectral_robustness.py remesh_infinity_riemann_spectral.py residue_phase_vs_riemann.py structural_interface_benchmark.py temporal_interface_benchmark.py tetrad_results_aggregate.py u2_destabilization_irreversibility.py universality_clusters.py xi_c_fast_experiment.py

comprehensive_benchmark.py

ADVANCED_INTEGRATION.md mathematical_foundation.md performance_analysis.md

advanced_examples.py basic_usage.py

__init__.py __main__.py advanced_cli.py advanced_core.py cli.py constants.py core.py optimized.py

MANIFEST.in PACKAGE_SUMMARY.md README.md RELEASE_NOTES_v1.0.md setup.py test_installation.py

__init__.py test_conservation_laws.py test_delta_nfr_computation_paths.py test_delta_nfr.py test_dispersion_coherence_sign_invariance.py test_emergent_constants_guard.py test_lyapunov_operators.py test_nodal_equation.py test_structural_triad.py

replay_manifests

_manifest_summary.json _manifest.json _partition_files.txt.gz

self_opt_validation

integration.json

self_optimization

test_run_p0.json test_run_p1.json

_manifest_summary.json _manifest.json

test_pattern_discovery_manifest.py test_self_optimization_engine.py

__init__.py test_autodiff.py test_backends.py test_dissipative_dynamics.py test_epi.py test_factory_patterns.py test_metrics.py test_navier_stokes_refounded.py test_number_theory_canonical.py test_operators.py test_residue_networks.py test_riemann_nodal_pulse.py test_riemann_pulse_coherence.py test_spaces.py test_transforms.py test_validator.py

test_canonical_operators_modern.py test_grammar_canon.py test_grammar_canonical_consistency.py test_grammar_dynamics.py test_operator_contracts.py test_operator_strategies.py

test_fractal_partition_manifest.py

test_conservation_gauge_unification.py test_dissipative_conservation.py test_emergent_chemistry.py test_field_cache_invalidation.py test_gauge.py test_phase_transition.py test_signatures.py test_spectral_conservation.py test_structural_diffusion.py test_structural_integrity.py test_symplectic_substrate.py test_tetrad_bounds.py test_variational.py test_yang_mills_closure.py test_yang_mills_derivability.py test_yang_mills_scaling.py test_yang_mills_structural_gap.py test_yang_mills_u6_sweep.py

test_run_self_opt_validation.py test_run_self_optimization.py

__init__.py test_simple_advanced.py

__init__.py conftest.py README.md test_breast_cancer_phase_gate_demo.py test_classical_mechanics.py test_distributed_fft.py test_external_phase_gate_validation.py test_factorization_entrypoint.py test_multichannel_interface.py test_nodal_optimizer.py test_phase_gate_api.py test_replay_register_manifest.py test_signal_confrontation.py test_structural_interface_api.py test_structural_interface_baselines.py test_structural_interface_benchmark.py test_temporal_interface.py test_vectorized_coherence_length_regression.py test_wine_quality_phase_gate_demo.py utils.py

01_hello_world.py 02_musical_resonance.py 03_network_formation.py 04_operator_sequences.py 05_coherence_evolution.py 06_network_topologies.py 07_phase_transitions.py 08_emergent_phenomena.py 09_visualization_suite.py 10_simplified_sdk_showcase.py

02_physics_regimes

11_classical_limit_comparison.py 115_operator_contract_audit.py 12_classical_mechanics_demo.py 13_quantum_mechanics_demo.py 14_uncertainty_and_interference.py 15_train_crossing_demo.py 17_conservation_law_demo.py 26_gauge_structure_demo.py 27_variational_principle_demo.py 28_dissipative_systems_demo.py 29_lyapunov_stability_demo.py 30_self_optimization_demo.py 31_mathematical_constants_basis.py 33_complex_field_unification.py 34_conservation_protocol_suite.py 35_tetrad_irreducibility.py 36_grammar_violation_detector.py 37_operator_tetrad_synergy.py 38_grammar_energy_landscape.py 39_nodal_equation_decomposition.py

03_riemann_zeta

157_nodal_pulse_phase_attack.py 41_von_mangoldt_zeta_demo.py 42_riemann_zeros_as_resonances.py 43_prime_ladder_hamiltonian_demo.py 44_weil_explicit_formula_demo.py 45_li_keiper_demo.py 46_weil_tnfr_positivity_demo.py 47_alpha_sweep_demo.py 48_admissible_family_sweep_demo.py 49_nodeaware_gauge_sweep_demo.py 50_uniform_coercivity_demo.py 51_adaptive_coercivity_demo.py 52_paley_gap_coercivity_demo.py 53_lyapunov_spectral_positivity_demo.py 54_hilbert_polya_demo.py 55_structural_zero_density_demo.py 56_spectral_emergence_demo.py 57_admissible_rescaling_demo.py 58_oscillatory_correction_demo.py

04_riemann_L_twisted

59_dirichlet_l_function_demo.py 60_dirichlet_l_continuation_demo.py 61_dirichlet_l_hamiltonian_demo.py 62_dirichlet_weil_explicit_formula_demo.py 63_dirichlet_li_keiper_demo.py 64_twisted_weil_positivity_demo.py 65_twisted_alpha_sweep_demo.py 66_twisted_admissible_family_sweep_demo.py 67_twisted_nodeaware_gauge_sweep_demo.py 68_twisted_hermite_family_demo.py 69_twisted_coercivity_uniform_demo.py 70_twisted_paley_gap_coercivity_demo.py 71_twisted_lyapunov_spectral_demo.py 72_twisted_hilbert_polya_demo.py 73_twisted_structural_zero_density_demo.py 74_twisted_spectral_emergence_demo.py 75_twisted_admissible_rescaling_demo.py 76_twisted_oscillatory_correction_demo.py

05_type_hygiene

77_remesh_infinity_residue_split_demo.py 78_nuf_type_signature_demo.py 79_epi_type_signature_demo.py 80_phi_type_signature_demo.py 81_dnfr_type_signature_demo.py 82_remesh_window_type_signature_demo.py 83_delta_phi_max_type_signature_demo.py 84_coupling_weights_type_signature_demo.py 85_tetrad_closure_signature_demo.py 86_currents_closure_signature_demo.py 87_aggregates_closure_signature_demo.py 88_urules_consistency_signature_demo.py 89_operator_catalog_discipline_signature_demo.py

06_navier_stokes

158_navier_stokes_two_face_refounded.py

07_number_theory

100_prime_families_orbits.py 101_numbers_as_coupled_network.py 102_nodal_flow_primes_equilibria.py 116_nuf_emergent_prime_visibility.py 146_primality_grammatical_inertness.py 147_numbers_as_free_monoid_words.py 148_capacity_arm_carries_von_mangoldt.py 149_p14_is_the_capacity_arm_operator.py 153_structural_frequency_rank_cyclotomy.py 40_arithmetic_number_theory.py 94_generative_number_construction.py 95_primes_from_spectral_waves.py 96_spectral_vibration_of_coherence.py 97_goldbach_additive_multiplicative.py emergent_chemistry_particles_demo.py

08_emergent_geometry

103_emergent_substrate_meets_riemann.py 106_per_node_polarization_geometry.py 107_orthogonal_structure_emergent_geometry.py 108_emergent_field_generating_structure.py 112_structure_predicts_coherence_flow.py 113_overdamped_projection_bridge.py 114_substrate_conserved_quantities.py 117_emergent_geometry_residue_graph.py 118_emergent_vs_classical_operator.py 119_phase_sector_directed_residue.py 120_symmetry_wall_substrate_vs_spectrum.py 121_canonical_symmetry_break_negative.py 122_factorization_phase_sector.py 123_symmetry_sector_decomposition.py 124_emergent_metric_fractal_consistency.py 125_node_is_the_emergent_substrate.py 126_two_layers_base_fiber.py 127_base_is_emergent_not_imposed.py 128_base_substrate_coemergence.py 129_spectral_gap_base_fiber_clock.py 130_operators_break_substrate_charges.py 131_coemergent_loop_convergence.py 132_geometric_phase_holonomy.py 133_psi_topological_defects.py 134_spectral_dimension_heat_kernel.py 135_arrow_of_time_h_theorem.py 136_heat_kernel_coefficients.py 137_synchronization_transition.py 138_structure_frequency_synchronization.py 139_grammar_formal_language.py 140_grammar_automaton.py 141_grammar_rule_decomposition.py 142_grammar_operator_quotient.py 143_glyphic_function_sublanguage.py 144_branching_combinator.py 145_syntactic_monoid_starfree.py 150_emergent_grammatical_pattern_parry.py 151_grammar_in_emergent_geometry.py 152_operator_contract_tetrahedron.py 154_conductor_annotated_qr_spectrum.py 155_ontological_position_of_numbers.py 156_emergence_directness_law.py 98_emergent_symplectic_substrate.py 99_structural_diffusion.py unified_fields_showcase.py

109_p_vs_np_coherence_synthesis.py 110_bsd_rank_structural_pressure.py 111_hodge_discrete_and_honest_gap.py

10_applications

159_empirical_confrontation_pipeline.py 90_phase_gate_monitor_demo.py 91_breast_cancer_phase_gate_demo.py 92_wine_quality_phase_gate_demo.py 93_structural_interface_demo.py pytorch_cuda_demo.py

__init__.py register_manifest.py

__init__.py README.md rebuild_failure_manifest.py run_reproducible_benchmarks.py run_self_opt_validation.py run_self_optimization.py tnfr_is_prime.py validate_conservation_law.py verify_internal_references.py

__init__.py evaluation.py

__init__.py jax_backend.py numpy_backend.py optimized_numpy.py README.md torch_backend.py

__init__.py __init__.pyi arguments.py arguments.pyi execution.py execution.pyi interactive_validator.py README.md utils.py utils.pyi

__init__.py dataclass.py jsonschema_stub.py matplotlib_stub.py numpy_stub.py README.md

__init__.py __init__.pyi constants.py constants.pyi defaults_core.py defaults_init.py defaults_metric.py defaults.py feature_flags.py feature_flags.pyi glyph_constants.py operator_names.py operator_names.pyi physics_derivation.py precision_modes.py presets.py presets.pyi README.md security.py thresholds.py tnfr_config.py

__init__.py __init__.pyi aliases.py aliases.pyi canonical.py metric.py metric.pyi operational.py

__init__.py container.py default_implementations.py exceptions.py interfaces.py README.md

__init__.py __init__.pyi adaptation.py adaptation.pyi adaptive_sequences.py adaptive_sequences.pyi adelic.py advanced_cache_optimizer.py advanced_fft_arithmetic.py aliases.py aliases.pyi bifurcation.py cache_aware_fft_engine.py canonical.py canonical.pyi computational_hub.py coordination.py coordination.pyi distributed_fft.py dnfr.py dnfr.pyi dynamic_limits.py emergent_centralization.py emergent_integration_engine.py feedback.py feedback.pyi fft_backend.py fft_cache_coordinator.py fft_dispatchers.py fft_engine.py fft_workers.py fused_dnfr.py homeostasis.py homeostasis.pyi integrators.py integrators.pyi learning.py learning.pyi metabolism.py multi_modal_cache.py nbody_tnfr.py nbody.py nodal_optimizer.py optimization_orchestrator.py propagation.py README.md runtime.py runtime.pyi sampling.py sampling.pyi selectors.py selectors.pyi self_optimizing_engine.py spectral_structural_fusion.py structural_cache.py structural_clip.py symplectic.py unified_backend.py unified_mathematical_cache_orchestrator.py

__init__.py fft_engine.py unified_fft_engine.py unified_gpu_system.py

__init__.py canonical.py operational.py

__init__.py emergent_integration.py

pattern_discovery

__init__.py mathematical_patterns.py multi_modal_cache.py

self_optimization

__init__.py engine.py

__init__.py README.md

__init__.py contextual.py

__init__.py fields_symbolic.py grammar_validators.py optimizer.py README.md symbolic.py

__init__.py backend.py backend.pyi dynamics.py dynamics.pyi epi.py epi.pyi generators.py generators.pyi liouville.py metrics.py metrics.pyi number_theory.py operators_factory.py operators_factory.pyi operators.py operators.pyi optimized_primality.py projection.py projection.pyi README.md runtime.py runtime.pyi spaces.py spaces.pyi spectral.py transforms.py transforms.pyi unified_cache.py unified_numerical.py zeta.py

__init__.py __init__.pyi buffer_cache.py buffer_cache.pyi cache_utils.py coherence.py coherence.pyi common.py common.pyi core.py core.pyi diagnosis.py diagnosis.pyi emergence.py export.py export.pyi glyph_timing.py glyph_timing.pyi learning_metrics.py learning_metrics.pyi local_coherence.py phase_coherence.py phase_compatibility.py README.md reporting.py reporting.pyi sense_index.py sense_index.pyi telemetry.py tetrad.py trig_cache.py trig_cache.pyi trig.py trig.pyi

__init__.py hierarchical.py README.md

__init__.py conservative_face.py operator.py

network_analysis

__init__.py source_detection.py

__init__.py mutation.py

__init__.py coherence.py dissonance.py emission.py mutation.py reception.py resonance.py

__init__.py defaults.py gpu_strategies.py strategy.py

__init__.py __init__.pyi algebra.py canonical_patterns.py cascade.py coherence.py contraction.py coupling.py cycle_detection.py definitions_base.py definitions.py definitions.pyi dissonance.py emission.py expansion.py grammar_application.py grammar_canon.py grammar_context.py grammar_core.py grammar_dynamics.py grammar_error_factory.py grammar_memoization.py grammar_patterns.py grammar_telemetry.py grammar_types.py grammar_u6.py grammar_validate.py grammar.py grammar.pyi hamiltonian.py health_analyzer.py introspection.py jitter.py jitter.pyi lifecycle.py metabolism.py metrics_basic.py metrics_core.py metrics_network.py metrics_structural.py metrics_u6.py metrics.py mutation.py nodal_equation.py operator_contracts.py pattern_detection.py patterns.py README.md reception.py recursivity.py registry.py registry.pyi remesh.py remesh.pyi resonance.py self_organization.py silence.py structural_units.py transition.py

__init__.py auto_scaler.py distributed.py engine.py monitoring.py partitioner.py README.md

__init__.py _helpers.py calibration.py canonical.py cell.py classical_mechanics.py conservation_gauge_unification.py conservation.py dissipative_conservation.py emergent_chemistry.py emergent_particles.py extended.py fields.py gauge.py integrity.py interactions.py life.py lyapunov.py patterns.py phase_transition.py quantum_mechanics.py README.md signatures.py spectral_conservation.py spectral_metrics.py structural_diffusion.py symplectic_substrate.py telemetry.py unified.py variational.py vectorized_ops.py

__init__.py cookbook.py README.md

__init__.py admissible_family_sweep.py admissible_rescaling.py aggregates_closure_signature.py alpha_sweep.py analytic_continuation_dirichlet.py analytic_continuation.py coercivity_uniform.py coupling_weights_type_signature.py currents_closure_signature.py delta_phi_max_type_signature.py dirichlet_l.py dnfr_type_signature.py epi_type_signature.py hilbert_polya.py li_keiper.py lyapunov_spectral_positivity.py nodal_pulse.py nodeaware_gauge_sweep.py nuf_type_signature.py operator_catalog_discipline_signature.py operator.py oscillatory_correction.py paley_gap_coercivity.py phi_type_signature.py prime_ladder_hamiltonian.py pulse_coherence.py remesh_infinity_residue_split.py remesh_window_type_signature.py spectral_emergence.py structural_zero_density.py telemetry.py tetrad_closure_signature.py twisted_admissible_family_sweep.py twisted_admissible_rescaling.py twisted_alpha_sweep.py twisted_coercivity_uniform.py twisted_hermite_family.py twisted_hilbert_polya.py twisted_li_keiper.py twisted_lyapunov_spectral_positivity.py twisted_nodeaware_gauge_sweep.py twisted_oscillatory_correction.py twisted_paley_gap_coercivity.py twisted_prime_ladder_hamiltonian.py twisted_spectral_emergence.py twisted_structural_zero_density.py twisted_weil_explicit_formula.py twisted_weil_positivity.py urules_consistency_signature.py von_mangoldt.py weil_explicit_formula.py weil_positivity.py

__init__.py grammar.json README.md

__init__.py __init__.pyi adaptive_system.py adaptive_system.pyi builders.py builders.pyi fluent.py fluent.pyi README.md self_opt.py simple.py templates.py templates.pyi utils.py

__init__.py crypto.py database.py README.md subprocess.py validation.py

__init__.py patterns.py README.md

__init__.py orchestrator.py README.md

__init__.py README.md representations.py

__init__.py cache_metrics.py cache_metrics.pyi constants.py nu_f.py nu_f.pyi README.md unified_telemetry_system.py verbosity.py verbosity.pyi

__init__.py domain_templates.py README.md sequence_generator.py tnfr_is_prime_cli_optimized.py tnfr_is_prime_cli.py

__init__.py asymmetry.py README.md

cache_layers.py cache.py cache.pyi callbacks.py callbacks.pyi chunks.py chunks.pyi data.py data.pyi fast_diameter.py graph.py graph.pyi init.py init.pyi io.py io.pyi numeric.py numeric.pyi README.md topology.py unified_cache.py

__init__.py __init__.pyi aggregator.py base.py compatibility.py compatibility.pyi config.py graph.py graph.pyi health.py input_validation.py interface_baselines.py invariants.py multichannel_interface.py phase_gate.py README.md rules.py rules.pyi runtime.py runtime.pyi sequence_validator.py signal_confrontation.py soft_filters.py soft_filters.pyi spectral.py spectral.pyi structural_interface.py temporal_interface.py unified_validation_system.py validator.py window.py window.pyi

__init__.py cascade_viz.py hierarchy.py README.md sequence_plotter.py

__init__.py closure.py derivability.py scaling.py structural_gap.py u6_sweep.py

__init__.py __init__.pyi _compat.py _version.py _version.pyi alias.py alias.pyi backend_config.py cache.py cache.pyi execution.py execution.pyi flatten.py flatten.pyi gamma.py gamma.pyi glyph_history.py glyph_history.pyi glyph_runtime.py glyph_runtime.pyi immutable.py immutable.pyi initialization.py initialization.pyi io.py io.pyi locking.py locking.pyi node.py node.pyi observers.py observers.pyi ontosim.py ontosim.pyi py.typed rng.py rng.pyi secure_config.py selector.py selector.pyi sense.py sense.pyi structural.py structural.pyi tokens.py tokens.pyi trace.py trace.pyi types.py types.pyi units.py units.pyi

tetrad_evaluator.py

.pre-commit-config.yaml .semgrep.yaml .zenodo.json ARCHITECTURE.md bandit.yaml CHANGELOG.md CITATION.cff CONTRIBUTING.md EMERGENT_CANON_AUDIT.md EMERGENT_DERIVATION_PLAN.md LICENSE.md Makefile MANIFEST.in pyproject.toml pyrightconfig.json PYTORCH_CUDA_INTEGRATION.md README.md SECURITY.md TESTING.md TNFR_Website_Content_Brief.md

FILE: src/tnfr/security/README.md

README.md

TNFR Security — Canonical Module Hub (Single Source of Truth)

English-only hub for security constraints and checks.

Canonical policies and invariants: AGENTS.md
Grammar: UNIFIED_GRAMMAR_RULES.md

Scope

Safe file/path handling, permission checks, and sandbox helpers