pycba-tools 0.1.0__tar.gz

pycba_tools-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pycba_tools-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: pycba-tools
+Version: 0.1.0
+Summary: pycba-tools: Serialization and bulk results extraction for pycba continuous beam models, interchangeable with pynite-tools.
+Author-email: Connor Ferster <connor@structuralpython.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pycba>=1.0.2
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: deepmerge>=2.0
+Project-URL: Source, https://github.com/StructuralPython/pycba-tools
+
+# pycba-tools
+
+> Super-charge your pycba workflows (and swap them with Pynite)
+
+[pycba](https://github.com/ccaprani/pycba) is a fast, accurate continuous beam analysis library.
+The tools in this package give pycba the model-level features that
+[pynite-tools](https://github.com/StructuralPython/pynite-tools) gives PyniteFEA: named load
+cases and load combinations, JSON serialization of analysis-ready models, and bulk export of
+structured results.
+
+The public API mirrors pynite-tools: the same function names, the same signatures, and **the same
+result trees, with the same names and sign conventions**. Code written against pynite-tools can
+switch to pycba-tools for continuous beams by changing the import.
+
+Modules included:
+
+- `model`: `CBAModel`, a pycba beam with named load cases, load combinations and named nodes,
+  and Pynite-shaped result views (`model.nodes`, `model.members`)
+- `reports`: Quickly export node and member results in structured dictionaries
+- `serialize`: Export and import `CBAModel` objects to JSON
+- `combos`: Convenience function for bulk-adding load combinations to `CBAModel` objects
+
+## Installation
+
+```
+pip install pycba-tools
+```
+
+## Dependencies
+
+- Python >= 3.11
+- `pycba` >= 1.0.2
+- `numpy` >= 2.0.0
+- `deepmerge` >= 2.0.0
+- `pydantic` >= 2.0.0
+
+## Examples: `model`
+
+pycba's `BeamAnalysis` analyses a single load matrix. `CBAModel` holds the beam definition, any
+number of named load cases (stored as ordinary pycba load matrix rows) and load combinations,
+and analyses every combination.
+
+```python
+import pycba_tools as pt
+
+model = pt.CBAModel(
+    L=[4.0, 6.0, 2.5],                          # span lengths
+    EI=30e3,                                    # one value, or one per span
+    supports=["pin", "roller", "roller", "free"],  # or a raw pycba R vector
+    name="B1",                                  # member name used in result trees
+    # node_names=["N0", "N1", "N2", "N3"],      # default
+    # node_locations=[0.0, 4.0, 10.0, 12.5],    # optional, instead of L
+    # eletype=["FF", "FF", "FF"], D=[...], GAv=..., kf=...   # all pycba options
+)
+
+# Loads use pycba's convention: positive is downward, moments positive counter-clockwise.
+# Global-coordinate helpers split loads at the nodes into pycba load matrix rows...
+model.add_distributed_load(5.0, 5.0, case="D")             # full length
+model.add_distributed_load(2.0, 6.0, 2.0, 9.0, case="L")   # trapezoidal, x1 to x2
+model.add_point_load(10.0, 7.0, case="D")
+model.add_moment_load(3.0, 7.0, case="D")
+# ...or add raw pycba rows (1-based span number)
+model.add_load([3, 2, 6.0, 2.5], case="L")
+
+model.add_load_combo("1.25D+1.5L", {"D": 1.25, "L": 1.5})
+model.add_load_combo("D+L", {"D": 1.0, "L": 1.0})
+
+model.analyze()
+
+# Pynite-style results...
+model.nodes["N1"].RxnFY["1.25D+1.5L"]
+model.members["B1"].max_moment("Mz", "D+L")
+
+# ...and the pycba BeamAnalysis of every combination, for pycba's own tools
+model.analyses["D+L"].plot_results()
+```
+
+Existing pycba objects convert both ways:
+
+```python
+from pycba import BeamAnalysis
+
+ba = BeamAnalysis([5.0, 5.0], 30e3, supports=["fixed", "roller", "roller"], LM=[[1, 1, 2.0]])
+model = pt.CBAModel.from_beam_analysis(ba, case="D")   # the load matrix becomes case "D"
+combo_ba = model.to_beam_analysis(combo_name="1.25D+1.5L")  # a fresh BeamAnalysis
+```
+
+### Sign conventions
+
+Inputs use pycba's conventions. The result views and every `reports` function use Pynite's
+conventions for a member along global X loaded in Y, so result trees can be swapped:
+
+| Pynite name   | pycba            | Relationship             |
+|---------------|------------------|--------------------------|
+| `RxnFY`       | vertical reaction | same sign (up positive) |
+| `RxnMZ`       | moment reaction  | same sign (CCW positive) |
+| `DY`, `RZ`    | nodal displacement, rotation | same sign    |
+| `Fy` (shear)  | `V`              | same sign                |
+| `Mz` (moment) | `M`              | `Mz = -M`                |
+| `dy`          | `D`              | same sign                |
+
+A Pynite `Fy` load of `-w` (downward) is a pycba load of `+w`. pycba is a planar beam solver, so
+the axial, torsional and out-of-plane results are always zero and are dropped from result trees
+exactly as pynite-tools drops all-zero results.
+
+## Examples: `reports`
+
+```python
+import pycba_tools as pr
+
+model = pr.CBAModel(...) # Build and analyze your model here
+
+# All the below functions optionally take a list of load combos
+# and a results_key, exactly as in pynite-tools.
+
+reactions = pr.extract_node_reactions(model)
+node_displacements = pr.extract_node_displacements(model)
+force_arrays = pr.extract_member_arrays(model, n_points=1000)
+forces_minmax = pr.extract_member_envelopes(model)
+forces_minmax_spans = pr.extract_span_envelopes(model)
+forces_at_locations = pr.extract_member_actions_by_location(
+    model,
+    force_extraction_locations={"B1": [0, 2.0, 3.6]},
+)
+forces_at_location_ratios = pr.extract_member_actions_by_location(
+    model,
+    force_extraction_ratios={"B1": [0.25, 0.5, 0.75]},
+    by_span=True,
+)
+merged_tree = pr.merge_result_trees([force_arrays, forces_minmax, forces_at_locations])
+```
+
+pycba results are evaluated at `npts` stations per span (default 500, set on `CBAModel` or
+`analyze(npts=...)`) and interpolated between them; stations are added either side of every
+concentrated load so shear and moment jumps are captured.
+
+## Examples: `serialize`
+
+```python
+import pycba_tools as ps
+
+## Dumping/serializing functions
+with open('model.json', 'w') as file:
+    ps.dump(model, file)
+json_str = ps.dumps(model)
+json_dict = ps.dump_dict(model)
+ps.to_json(model, "model.json")
+
+## Loading/de-serializing functions
+with open('model.json', 'r') as file:
+    remodel = ps.load(file)
+remodel = ps.loads(json_str)
+remodel = ps.load_dict(json_dict)
+remodel = ps.from_json("model.json")
+
+remodel.analyze()
+```
+
+A pycba `BeamAnalysis` can also be passed to the dump functions; its load matrix is stored as load
+case `"Case 1"`.
+
+### What gets serialized
+
+The JSON contains the model's *input* data: the member name, node names and locations, spans,
+`EI`, the restraint vector `R` (supports and springs), element types, prescribed displacements,
+`GAv` and `kf`, the number of evaluation points, load cases (as pycba load matrix rows) and load
+combinations. It is tagged `"backend": "pycba"`.
+
+Analysis results are not serialized: re-run the analysis after loading. Non-prismatic
+(`SectionEI`) members are not supported yet.
+
+## Examples: `combos`
+
+```python
+import json
+import pycba_tools as pc
+
+with open("load_combo_library/current_combos.json", 'r') as file:
+    load_combos = json.load(file)
+
+pc.model_add_combos(load_combos, model)                      # in place
+model = pc.model_add_combos(load_combos, model, as_copy=True)  # on a copy
+```
+
+## Using pycba-tools in place of Pynite in loadtracer
+
+loadtracer's frame model only needs a model it can build, analyse, read support reactions from
+and serialize. `CBAModel` provides `load_combos`, `analyze_linear()` and nodes with `X` and
+`RxnFX`...`RxnMZ`, so loadtracer's `get_support_reactions` works unchanged, and `pycba_tools`
+provides the `dump`/`dump_dict`/`load`/`load_dict`/`from_json` functions that `PyniteFrame` calls.
+The only new code is the model builder:
+
+```python
+import pycba_tools as pt
+
+def build_pycba_frame_model(pm: dict, EI: float = 1.0) -> pt.CBAModel:
+    nodes = get_node_locations(pm)  # loadtracer's helper
+    R = []
+    for _, constraints in nodes:
+        constraints = constraints or [0] * 6
+        R.extend([-1 if constraints[1] else 0, -1 if constraints[5] else 0])
+    model = pt.CBAModel(
+        node_locations=[location for location, _ in nodes],
+        EI=EI,
+        R=R,
+        name=pm["element_attributes"]["tag"],
+    )
+    load_cases = set()
+    for dist_load in pm["loads"]["distributed_loads"]:
+        for e in dist_load.get("expanded", []):
+            if e["dir"] not in ("Fy", "FY"):
+                raise ValueError(f"pycba cannot model distributed loads in '{e['dir']}'.")
+            load_cases.add(e["case"])
+            # loadtracer uses Pynite's sign convention: negate transverse loads
+            model.add_distributed_load(
+                -e["start_magnitude"], -e["end_magnitude"], e["start_loc"], e["end_loc"], case=e["case"]
+            )
+    for point_load in pm["loads"]["point_loads"]:
+        for e in point_load.get("expanded", []):
+            load_cases.add(e["case"])
+            if e["dir"] in ("Fy", "FY"):
+                model.add_point_load(-e["magnitude"], e["location"], case=e["case"])
+            elif e["dir"] in ("Mz", "MZ"):
+                model.add_moment_load(e["magnitude"], e["location"], case=e["case"])
+            else:
+                raise ValueError(f"pycba cannot model point loads in '{e['dir']}'.")
+    for load_case in sorted(load_cases):
+        model.add_load_combo(name=load_case, factors={load_case: 1.0})
+    return model
+```
+
+`tests/test_loadtracer_contract.py` runs loadtracer's own `get_support_reactions` against this
+builder and against loadtracer's Pynite builder and checks they agree.
+
+pycba models in-plane bending only: gravity (`Fy`/`FY`) loads and `Mz` moments. In-plane
+(`Fx`) and out-of-plane (`Fz`) loads on beams are rejected rather than silently dropped.
+
+## Testing
+
+```
+uv sync
+uv run pytest
+```
+
+The test suite includes parity tests that analyse the same beams with PyniteFEA + pynite-tools and
+with pycba + pycba-tools and compare the result trees.
+
+## License
+
+pycba-tools is licensed under the Apache License 2.0. Note that it depends on pycba, which is
+licensed under the AGPL-3.0-or-later.
+