pyBmodes

User guide

  • Installation
    • From PyPI
    • From source (editable)
    • Optional extras
    • Windows + conda quickstart
    • Updating to a new release
      • Inside a conda environment
    • Verifying the install
    • IDE setup
      • VS Code
      • PyCharm
    • Common errors
      • ModuleNotFoundError: No module named 'pybmodes'
      • UserWarning: matplotlib is required for plot_campbell
      • KeyError: 'floating_platform' (WindIO yaml)
      • FileNotFoundError: ... external/OpenFAST_files/...
      • MemoryError or eigensolver hangs on large towers
    • Uninstalling
  • Quickstart
    • Solving a synthetic tower
    • Reading an OpenFAST ElastoDyn deck
    • Monopile decks with SubDyn
      • Soft monopile via closed-form mudline springs
    • Floating decks with mooring + hydro
    • Campbell diagrams
    • WISDEM / WindIO one-click
    • Mode-by-mode comparison (MAC)
    • Pre-solve sanity checks
    • Common patterns
      • Loop over an entire directory of decks
      • Persist and reload a result
      • Vendor the bundled examples out of the wheel
    • What’s next
  • Theory
    • The structural model
      • Discrete eigenproblem
      • Element matrices
      • Sign convention + normalisation
    • Boundary conditions
      • Platform-attached frame (hub_conn = 2)
    • ElastoDyn-compatible polynomial ansatz
      • Floating-deck polynomials use the cantilever basis
      • Torsion-contamination filter
      • Improved Direct Method (root rigid-body subtraction)
    • Solver dispatch
    • Pre-solve sanity checks
    • Mooring + hydrodynamics
      • Quasi-static elastic catenary
      • WAMIT / HydroDyn
    • Citable references
  • Data sources
    • Supported input formats
    • BModes .bmi — the canonical input
    • OpenFAST ElastoDyn — the industry path
    • OpenFAST SubDyn — monopile pile geometry
    • WAMIT / HydroDyn output
    • OpenFAST MoorDyn — both layouts
    • WISDEM / WindIO ontology
      • Tubular tower / monopile
      • Composite blade
      • Floating substructure
    • BModes .out — the reference output format
    • Bundled examples (ship in every wheel)
      • src/pybmodes/_examples/sample_inputs/
      • src/pybmodes/_examples/reference_decks/
    • Local-only upstream data (external/)
    • Independence stance
  • Coordinate systems, origins & datums
    • The one origin: the tower base
    • Rigid-body DOF order
    • Boundary conditions (hub_conn)
    • Tower-top / RNA mass (tip_mass)
    • Per-case conventions
      • Land-based tower
      • Monopile (fixed-bottom)
      • Floating platform
      • Blade (rotating)
    • Worked example: OC3 Hywind (validated)
    • Common pitfalls
  • Units & conventions
    • Quantities & units
    • Conversion tables for common units
    • Mode-shape normalisation
    • DOF order
    • Polynomial coefficients
    • Frame conventions
      • Tower base frame
      • Blade root frame
      • Section centre-of-mass offsets
      • Twist auto-detection (WindIO)
    • Common pitfalls
      • Mixing ω and f
      • Confusing OpenFAST’s two coordinate systems
      • Forgetting the rotor mass on a tower deck
      • Treating the polynomial-fit ratio as an absolute error
  • Limitations
    • Polynomial representation limits
      • The IEA-15-UMaine TwSSM2Sh block
      • Hybrid bending + twist modes
      • Free-free floating polynomials
    • Floating-platform fidelity
    • Mooring physics
    • Numerical scope
    • Specific edge cases the validation matrix surfaces
      • NREL 5MW r-test polynomial drift
      • OC3 Hywind asymmetric platform support
      • Pitch / roll coupling on IEA-15 UMaineSemi
      • NREL 5MW monopile soil compliance
    • What this is not
    • When to reach for a different tool
  • Validation matrix
    • Mechanical audit
    • Tracks
      • Track A — frequency accuracy
      • Track B — coefficient consistency
      • Track C — supporting pipeline
    • What “self-contained” means
    • The full matrix
      • pyBmodes validation matrix
  • Changelog
    • Versioning policy
    • How to find what changed for a specific name
    • The full history
      • Changelog

Reference

  • API reference
    • High-level models
      • RotatingBlade
      • Tower
      • ModalResult
    • Input / output
      • Parse errors (common across every pybmodes.io.* reader)
      • BModes .bmi
      • ElastoDyn deck reader
      • SubDyn reader
      • WAMIT / HydroDyn reader
      • BModes .out output
      • WindIO ontology — tubular tower / monopile
      • WindIO ontology — composite blade
      • WindIO ontology — floating substructure
      • Geometry & section properties
    • Polynomial fitting + ElastoDyn helpers
      • PolyFitResult
      • fit_mode_shape()
      • BladeElastoDynParams
      • TowerElastoDynParams
      • TowerFamilyMemberReport
      • TowerSelectionReport
      • compute_blade_params()
      • compute_tower_params()
      • compute_tower_params_report()
      • CoeffBlockResult
      • ValidationResult
      • validate_dat_coefficients()
      • patch_dat()
      • FloatingFrequencyGap
      • report_floating_frequency_gap()
    • Campbell
      • Module layout
      • Public API
      • CampbellResult
      • campbell_sweep()
      • plot_campbell()
    • Modal Assurance Criterion
      • ModeComparison
      • compare_modes()
      • mac_matrix()
      • plot_mac()
      • shape_to_vector()
    • Pre-solve sanity checks
      • ModelValidationError
      • ModelWarning
      • apply_findings()
      • check_model()
    • Numerical options
      • CheckOptions
      • FitOptions
      • SolverOptions
    • Report generation
      • generate_report()
    • Mooring
      • Module layout
      • Scope
      • Coordinate / unit conventions
      • Line
      • LineType
      • MooringSystem
      • Point
    • Soil-pile interaction
      • MudlineFoundation
    • Plot helpers ([plots] extra)
      • apply_style()
      • bir_mode_shape_plot()
      • bir_mode_shape_subplot()
      • blade_fit_pairs()
      • jonswap_spectrum()
      • kaimal_spectrum()
      • plot_environmental_spectra()
      • plot_fit_quality()
      • plot_mode_shapes()
      • tower_fit_pairs()
    • Workflows (library-callable CLI subcommands)
      • Background
      • Result-dataclass pattern
      • Exception handling
      • BatchResult
      • CampbellWorkflowResult
      • ExamplesResult
      • PatchResult
      • ReportResult
      • ValidateResult
      • WindioDiscovery
      • WindioResult
      • WorkflowResult
      • discover_windio_inputs()
      • run_batch()
      • run_campbell()
      • run_examples_copy()
      • run_patch()
      • run_report()
      • run_validate()
      • run_windio()
      • WorkflowResult
      • ValidateResult
      • run_validate()
      • ExamplesResult
      • run_examples_copy()
      • PatchResult
      • run_patch()
      • ReportResult
      • run_report()
      • BatchResult
      • find_elastodyn_main_dats()
      • run_batch()
      • CampbellWorkflowResult
      • run_campbell()
      • WindioDiscovery
      • WindioResult
      • discover_windio_inputs()
      • run_windio()
    • CLI
      • main()
  • API contract
    • Versioning policy
    • Deprecation policy
    • Stable public names
      • Model constructors
      • Results + serialisation
      • Solvers + sweeps
      • Polynomial fitting + validation
      • Floating coupled-vs-cantilever diagnostic
      • Soil-pile interaction
      • Pre-solve sanity + comparison
      • Numerical options (1.x architecture refactor — Phase 1)
      • Reports
      • Workflows (Phase 2 of the 1.x architecture refactor)
      • Mooring + hydro
      • I/O
      • Plot helpers ([plots] extra)
      • CLI subcommands
    • Stability tiers
      • Public + stable
      • Public but experimental
      • Internal (underscore-prefixed)
    • Runtime dependency contract
    • How to track changes

Developer guide

  • Contributing
    • Who this is for
    • Scope of welcome contributions
    • The contribution guide
      • Contributing to pyBmodes
  • Release checklist
    • 0. Prerequisites
    • 1. Default test suite (self-contained, no external data)
    • 2. Integration test suite (needs local OpenFAST + BModes decks)
    • 3. Linting + type checking
    • 4. Sample-input verifier
    • 4.5. Validation-matrix audit
    • 5. Reference-deck regeneration + validator
    • 6. Walkthrough notebook smoke-check
    • 7. Case scripts (optional — produce PNGs under outputs/)
    • 8. Version + CHANGELOG promotion
    • 9. Tag + push
    • 10. PyPI publish (automatic, but verify)
    • 11. GitHub Release
    • 11. Post-release sanity
  • Deployment
    • Where the site lives
    • One-time setup (maintainer)
    • What to do when a build fails
    • Versioning + the docs site
    • Custom domain (optional)
pyBmodes
  • Search

© Copyright 2024-2026, Jae Hoon Seo, Marine Structural Mechanics and Integrity Lab (SMI Lab), Inha University.

Built with Sphinx using a theme provided by Read the Docs.