Please update PR #320 in repository JWock82/Pynite by addressing the review concerns in the current changes for the instability-detection implementation.

Context:

• The current PR introduces _solve_unknown_disp to detect global instability by checking finiteness and the solution residual after solving K11 @ x = rhs.
• The current implementation still uses broad except: handlers around the call sites and suppresses all warnings around spsolve.
• The current implementation may also under-handle the rhs == 0 edge case.

Required changes:

1. Replace broad bare except: handlers in the modified analysis paths with narrower, intentional exception handling that preserves unexpected errors instead of always converting them into the generic singular-matrix message.
2. Narrow the sparse warning suppression so it suppresses only the intended singular/rank-related warning from SciPy, not all warnings.
3. Review and improve handling of the rhs == 0 / zero-load edge case in _solve_unknown_disp so the instability detection is more principled and does not silently skip an important singular case.
4. Update or add tests as needed to cover the changed behavior.
5. Keep the fix scoped to this PR’s purpose: instability detection and related error handling/readability improvements.

Please make the minimal, reviewable change set needed to address these points and open a pull request with the fixes.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Explain these changes.

Assistant: This PR makes PyNite detect a broader class of unstable models by checking the solution residual after solving for displacements, instead of relying only on obvious singular-matrix failures.

In a nutshell

Before this change, analysis could miss some global instability cases: the stiffness matrix might be rank-deficient even though its diagonal entries look fine, and the solver could return NaN or even plausible-looking but wrong numbers. This PR adds a shared helper, _solve_unknown_disp, that solves the system and then verifies the result by checking whether K11 @ x actually matches the right-hand side. If not, it raises the usual “structure is unstable” exception.

What changed

1. New _solve_unknown_disp(...) helper

A new function centralizes solving:

• supports both sparse (scipy.sparse.linalg.spsolve) and dense (numpy.linalg.solve) paths
• optionally performs a post-solve stability check
• raises a consistent instability exception using _SINGULAR_MSG

Its key idea is:

• solve K11 @ x = rhs
• compute whether the solution is valid by checking:
  • all values in x are finite
  • residual is small: ||K11 @ x - rhs|| <= tol * ||rhs||

If either fails, the matrix is treated as singular/unstable.

2. Global instability is now detected more reliably

The docstring explains the motivation well:

• _check_stability(...) only catches cases with zero diagonal stiffness
• it does not catch mechanisms where the full matrix is singular despite nonzero diagonals
• examples:
  • internal hinge/release mechanisms
  • insufficient supports / rigid-body motion

This PR addresses those cases using the residual test.

3. Sparse solver warnings are suppressed and replaced with a clearer error path

For sparse solves:

• spsolve may emit a MatrixRankWarning
• the code now suppresses that warning with warnings.catch_warnings()
• instead of letting the warning leak through, it validates the result and raises a clear exception if unstable

That gives users a more consistent API-level failure.

4. _first_order(...) now uses the helper

Previously _first_order solved directly:

• sparse path: spsolve(...)
• dense path: solve(...)

Now it:

• computes rhs first
• calls _solve_unknown_disp(K11, rhs, sparse, check_stability)

So the first-order analysis path gets the new global-instability detection automatically.

5. Imports updated

New imports support the helper:

• warnings
• asarray, isfinite from NumPy
• norm from numpy.linalg

Why this matters

This is mainly a correctness and safety fix.

Without it, users could get:

• NaN displacement results, or worse
• finite but incorrect results from an unstable model

With this change, PyNite is more likely to fail fast with an explicit instability error instead of silently continuing with invalid analysis results.

Behavior impact

Practically:

• stable models should behave the same
• unstable or globally singular models are more likely to raise an exception consistently
• models that previously “solved” but produced garbage may now correctly fail

One subtle detail

The residual check only triggers when:

• check_stability=True, and
• either solution entries are non-finite, or
• residual is too large relative to ||rhs||

So this adds protection without changing the bare-solver path when stability checking ...