{"id":7475,"library":"openseespy","title":"OpenSeesPy","description":"OpenSeesPy is a Python 3 interpreter for the Open System for Earthquake Engineering Simulation (OpenSees), a powerful software framework for finite element analysis. It provides robust capabilities for structural analysis, including linear, nonlinear, static, and dynamic analysis of structures. Currently at version 3.8.0.0, the library is actively developed with frequent updates and releases.","status":"active","version":"3.8.0.0","language":"en","source_language":"en","source_url":"https://github.com/zhuminjie/openseespy","tags":["structural analysis","finite element method","earthquake engineering","civil engineering","simulation","numerical analysis"],"install":[{"cmd":"pip install openseespy","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Required Python interpreter version","package":"python","optional":false}],"imports":[{"note":"The core OpenSees commands are exposed through the 'opensees' submodule. It's common practice to alias it as 'ops' for brevity.","wrong":"import openseespy","symbol":"ops","correct":"import openseespy.opensees as ops"},{"note":"For plotting and post-processing functionalities, import from the 'postprocessing.Get_Rendering' submodule, often aliased as 'opsplt'.","symbol":"opsplt","correct":"import openseespy.postprocessing.Get_Rendering as opsplt"}],"quickstart":{"code":"import openseespy.opensees as ops\n\n# 1. Start a new model\nops.wipe()\nops.model('basic', '-ndm', 2, '-ndf', 3)\n\n# 2. Define nodes\nops.node(1, 0.0, 0.0)\nops.node(2, 100.0, 0.0)\nops.node(3, 0.0, 100.0)\n\n# 3. Set boundary conditions\nops.fix(1, 1, 1, 1) # Node 1: Fixed in x, y, and rotation\nops.fix(2, 0, 1, 0) # Node 2: Fixed in y\n\n# 4. Define material\n# uniaxialMaterial('Elastic', matTag, E)\nops.uniaxialMaterial('Elastic', 1, 200000.0) # Steel, E in appropriate units\n\n# 5. Define elements (e.g., truss element)\n# element('truss', eleTag, iNode, jNode, A, matTag)\nops.element('truss', 1, 1, 3, 10.0, 1)\nops.element('truss', 2, 2, 3, 10.0, 1)\n\n# 6. Define loads\n# Create a time series (constant load factor)\nops.timeSeries('Constant', 1)\n# Create a plain load pattern\nops.pattern('Plain', 1, 1)\n# Apply nodal load (Node 3: -10kN in y-direction)\nops.load(3, 0.0, -10.0, 0.0)\n\n# 7. Setup analysis\nops.constraints('Plain')\nops.numberer('RCM')\nops.system('BandSPD')\nops.test('NormDispIncr', 1e-6, 10)\nops.algorithm('Linear')\nops.integrator('LoadControl', 0.1)\nops.analysis('Static')\n\n# 8. Perform analysis\nops.analyze(10)\n\n# 9. Get results (example: node 3 displacement)\ndisp_y = ops.nodeDisp(3, 2)\nprint(f\"Vertical displacement at node 3: {disp_y:.4f}\")\n\nops.wipe() # Clear the model from memory","lang":"python","description":"This quickstart demonstrates a basic 2D truss analysis: defining nodes, boundary conditions, material, elements, applying a static load, running a static analysis, and retrieving nodal displacement. It includes best practices like `ops.wipe()` for model isolation."},"warnings":[{"fix":"Ensure your Python environment is 3.10 or higher. Use `python --version` to check and create a new environment with `conda create -n openseespy_env python=3.10` or similar if needed.","message":"OpenSeesPy requires Python 3.10 or newer. Installing with older Python versions (e.g., Python 3.6, which was previously supported) will lead to installation or runtime failures.","severity":"breaking","affected_versions":"<3.8.0.0 (previous versions often supported older Python 3.x)"},{"fix":"Contact Dr. Minjie Zhu (zhum@oregonstate.edu) for commercial licensing details if your use case falls under commercial redistribution.","message":"Commercial redistribution or use in commercial applications/cloud services requires a specific license, similar to OpenSees. The PyPI package is free for research, education, and internal use.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the expected input types in the documentation for specific commands. Explicitly cast variables, especially numeric ones, if type-related errors occur.","message":"OpenSeesPy commands are sensitive to Python data types. Explicit casting (e.g., `float()`) may be necessary where an `int` might implicitly be used but a `float` is expected by the underlying OpenSees C++ routines, leading to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap critical OpenSees analysis or model-building commands in `try-except OpenSeesError` blocks to gracefully handle failures. The error message will often direct you to the standard error (stderr) for more detailed diagnostics.","message":"Many internal OpenSees errors are caught and re-raised as Python `OpenSeesError` exceptions. If not handled, these will terminate your script, making it difficult to debug or implement robust iterative analyses.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always start your OpenSeesPy script with `ops.wipe()` to ensure a clean model state.","message":"It is crucial to call `ops.wipe()` at the beginning of any new model definition script or before starting a new analysis in the same session. Failing to do so can lead to residual model data from previous runs, causing incorrect or unexpected results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `openseespy` is installed in your current environment: `pip install openseespy`. If using virtual environments (conda, venv), activate the correct environment before installation and running.","cause":"The openseespy package is either not installed or not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'openseespy.opensees'"},{"fix":"Call `ops.wipe()` at the beginning of your script or before defining a new model to clear any previous definitions. Ensure unique tags for all model components.","cause":"Attempting to create an element (or node, material, etc.) with a tag (ID) that has already been used in the current model. This often happens when re-running parts of a script or iterating without clearing the model.","error":"OpenSeesError: domain.cpp:166:setElement(): WARNING element tag 1 already exists - will be ignored."},{"fix":"Consult the OpenSeesPy documentation for the specific command to verify the required arguments and their order. Pay close attention to optional arguments and flags.","cause":"An OpenSeesPy command was called without providing all the necessary arguments, or arguments are in the wrong order.","error":"OpenSeesError: (some command) - missing a required argument (some_argument)"},{"fix":"Review your model for instabilities (e.g., zero stiffness, incorrect boundary conditions, very large loads). Try adjusting analysis parameters such as the `test` command's tolerance or number of iterations, or the `integrator`'s load increment. Consider using different `algorithm` or `system` commands.","cause":"The numerical solver failed to find a converged solution within the specified number of iterations, often due to highly nonlinear behavior, numerical instability, or an ill-posed model.","error":"OpenSeesError: StaticAnalysis::analyze() - the Newton-Raphson algorithm failed to converge in 10 iterations"}]}