engforge 0.3.0__tar.gz

engforge-0.3.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Ottermatics LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

engforge-0.3.0/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.4
+Name: engforge
+Version: 0.3.0
+Summary: The Engineer's Framework
+Author-email: Kevin Russell <olly@ottermatics.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Ottermatics/engforge
+Project-URL: Repository, https://github.com/Ottermatics/engforge
+Project-URL: Documentation, https://ottermatics.github.io/engforge/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs~=23.2.0
+Requires-Dist: arrow
+Requires-Dist: deepdiff>=6.3.1
+Requires-Dist: numpy==1.24.3
+Requires-Dist: scipy
+Requires-Dist: matplotlib~=3.8.1
+Requires-Dist: jupyter
+Requires-Dist: pandas
+Requires-Dist: scikit-learn~=1.3.2
+Requires-Dist: seaborn
+Requires-Dist: tabulate
+Requires-Dist: networkx-query==1.0.1
+Requires-Dist: networkx>=2.5.1
+Requires-Dist: black~=24.8.0
+Requires-Dist: randomname~=0.2.1
+Requires-Dist: termcolor
+Requires-Dist: pyee
+Requires-Dist: methodtools~=0.4.7
+Requires-Dist: tomli>=1.2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: jinja2>=2.11.3; extra == "dev"
+Requires-Dist: sphinx>=3.2.1; extra == "dev"
+Requires-Dist: recommonmark>=0.6.0; extra == "dev"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
+Provides-Extra: eng
+Requires-Dist: control; extra == "eng"
+Requires-Dist: fluids; extra == "eng"
+Requires-Dist: CoolProp; extra == "eng"
+Requires-Dist: sectionproperties~=3.1.2; extra == "eng"
+Requires-Dist: PyniteFEA>=1.2.0; extra == "eng"
+Provides-Extra: database
+Requires-Dist: SQLAlchemy~=1.3.17; extra == "database"
+Requires-Dist: SQLAlchemy-Utils; extra == "database"
+Requires-Dist: psycopg2-binary; extra == "database"
+Requires-Dist: diskcache>=5.6.1; extra == "database"
+Requires-Dist: sqlalchemy-batch-inserts; extra == "database"
+Provides-Extra: google
+Requires-Dist: expiringdict~=1.2.2; extra == "google"
+Requires-Dist: pygsheets==2.0.4; extra == "google"
+Requires-Dist: pydrive2==1.8.1; extra == "google"
+Provides-Extra: cloud
+Requires-Dist: boto3; extra == "cloud"
+Provides-Extra: distributed
+Requires-Dist: ray[default]~=2.35.0; extra == "distributed"
+Requires-Dist: ray[tune]~=2.35.0; extra == "distributed"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
+Requires-Dist: toml~=0.10.2; extra == "docs"
+Provides-Extra: all
+Requires-Dist: engforge[cloud,database,dev,distributed,docs,eng,google]; extra == "all"
+Dynamic: license-file
+
+[![build](https://github.com/Ottermatics/engforge/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/Ottermatics/engforge/actions/workflows/build.yml)
+[![docs](https://github.com/Ottermatics/engforge/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/Ottermatics/engforge/actions/workflows/docs.yml)
+# EngForge
+A library to tabulate information from complex systems with various ways to store data and act as glue code for complex systems & engineering problems.
+
+### Installation
+```bash
+pip install git+https://github.com/Ottermatics/engforge.git
+```
+
+### Core Functions
+1. Tabulation Of Complex Systems
+2. Modular Post Processing (dataframes)
+3. Exploratory Analysis (ipython + functions / docs)
+4. Workflows for core engineering problemes (structures + cost, thermal+fluids solve)
+
+### MVP Features (WIP)
+1. Tabulation, use `attrs.field` and `system_property` to capture `y=f(x)` where `fields` are the state from which `system_property` derives results [Done]
+2. Dynamic Programing ensures work is only done when new data is available with `cached_system_property`. [Done]
+3. Quick Calculation provided by direct cached references to attribues and properties [Done]
+4. Solver based on `NPSS` strategy of balances and integrators [Done]
+5. Reporting to google sheets, csv and excel.
+
+### Systems & Analysis
+Systems record data from components, and can execute a solver via the `run(**parameter_iterables)` command. Via a system's run command its state and internal component's & systems state can be altered in an outer product fashion, ie all combinations of inputs will be run. At the start of a run the systems & its components state is recorded and reset by default using `Ref` instances so that way multiple systems can use the same component. Its possible reference loops may occcur so its generally preferred to create components per system, however for coupled systems this is often desireable to converge on a solution.
+
+By default the system calls a `default_solver()` method in its `execute()` function. A solver aims to drive its dependent parameter to zero by changing the independent parameters to zero, however it may adjust multiple parameters to meet multiple targets in more complex applications. For custom System behavior or to invoke custom solvers this method may be overriden. 
+
+To use the default solver & constraints 
+```python
+@forge
+SolverSystem(System):
+    sol2 = Solver.define("dep", "indep")
+    sol2.add_constraint("max", limit_max) #indep should never go above this value (or function)
+    sol2.add_constraint("min", 0) #indep should never go below zero
+```
+
+`Analysis` is a pluggable way to provide different output and calculation from the same system and interacts with plot and table reporters.
+
+### Components, Signals & Slots
+Component are able to be mounted into multiple Systems via `SLOTS.define( ComponentType )`. A Component's properties can be updated via `SIGNALS` in the Systems's solver in the `pre_execute` and/or the `post_execute` functions via `SIGNAL.define(target, source, mode)` where mode can be `pre`,`post` or `both` to update before the `System.execute()` method.
+
+Iterable Components may be defined on a System via `SLOT.define_iterable( <ComponentIter>, wide=True/False)` to choose how the system should iterate over the component, `wide` mode provides all the component `attributes` and `properties` in the same row whereas the `narrow` mode will iterate over each combination of component as though it was input into `system.run()`
+
+### Example Engineering Problems:
+These problems demonstrate functionality
+
+#### Air Filter
+run a throttle sweep with filter loss characteristic and fan afinity law based pressure based off of a design point.
+```python
+from engforge.analysis import Analysis
+from engforge.reporting import CSVReporter,DiskPlotReporter
+from engforge.properties import system_property
+from engforge import *
+import numpy as np
+import os,pathlib
+import attrs
+
+@forge
+class Fan(Component):
+
+    n_frac:float = field(default=1)
+    dp_design:float= field(default=100)
+    w_design:float = field(default=2)
+
+
+    @system_property
+    def dP_fan(self) -> float:
+        return self.dp_design*(self.n_frac*self.w_design)**2.0
+
+@forge
+class Filter(Component):
+
+    w:float = field(default=0)
+    k_loss:float = field(default=50)
+
+    @system_property
+    def dP_filter(self) -> float:
+        return self.k_loss*self.w
+
+@forge
+class Airfilter(System):
+
+    throttle:float = field(default=1)
+    w:float = field(default=1)
+    k_parasitic:float = field(default=0.1)
+
+    fan: Fan = Slot.define(Fan)
+    filt: Filter = Slot.define(Filter)
+
+    set_fan_n = Signal.define('fan.n_frac','throttle',mode='both')
+    set_filter_w = Signal.define('filt.w','w',mode='both')
+
+    flow_var = Solver.declare_var('w',combos='flow')
+    flow_var.add_var_constraint(0,'min',combos='flow')
+    
+    pr_eq = Solver.constraint_equality('sum_dP',0,combos='flow')
+    
+
+    flow_curve = Plot.define(
+        "throttle", "w", kind="lineplot", title="Flow Curve"
+    )    
+
+    @system_property
+    def dP_parasitic(self) -> float:
+        return self.k_parasitic * self.w**2.0
+
+    @system_property
+    def sum_dP(self) -> float:
+        return self.fan.dP_fan - self.dP_parasitic - self.filt.dP_filter
+
+
+#Run the system
+from matplotlib.pylab import *
+
+
+
+fan = Fan()
+filt = Filter()
+af = Airfilter(fan=fan,filt=filt)
+
+change_all_log_levels(af,20) #info
+
+af.run(throttle=list(np.arange(0.1,1.1,0.1)),combos='*')
+
+df = af.dataframe
+
+fig,(ax,ax2) = subplots(2,1)
+ax.plot(df.throttle*100,df.w,'k--',label='flow')
+ax2.plot(df.throttle*100,df.filt_dp_filter,label='filter')
+ax2.plot(df.throttle*100,df.dp_parasitic,label='parasitic')
+ax2.plot(df.throttle*100,df.fan_dp_fan,label='fan')
+ax.legend(loc='upper right')
+ax.set_title('flow')
+ax.grid()
+ax2.legend()
+ax2.grid()
+ax2.set_title(f'pressure')
+ax2.set_xlabel(f'throttle%')
+```
+
+##### Results
+![air_filter_calc.png](media/air_filter_calc.png)
+
+
+#### Spring Mass Damper
+##### Overview
+Test case results in accurate resonance frequency calculation
+```python
+
+@forge
+class SpringMass(System):
+    
+    k: float = attrs.field(default=50)
+    m: float = attrs.field(default=1)
+    g: float = attrs.field(default=9.81)
+    u: float = attrs.field(default=0.3)
+
+    a: float = attrs.field(default=0)
+    x: float = attrs.field(default=0.0)
+    v: float = attrs.field(default=0.0)
+
+    wo_f: float = attrs.field(default=1.0)
+    Fa: float = attrs.field(default=10.0)
+
+    x_neutral: float = attrs.field(default=0.5)
+
+    res =Solver.constraint_equality("sumF")
+    var_a = Solver.declare_var("a",combos='a',active=False)
+    var_b = Solver.declare_var("u",combos='u',active=False)
+    var_b.add_var_constraint(0.0,kind="min")
+    var_b.add_var_constraint(1.0,kind="max")
+
+    vtx = Time.integrate("v", "accl")
+    xtx = Time.integrate("x", "v")
+    xtx.add_var_constraint(0,kind="min")
+
+    #FIXME: implement trace testing
+    #pos = Trace.define(y="x", y2=["v", "a"])
+
+    @system_property
+    def dx(self) -> float:
+        return self.x_neutral - self.x
+
+    @system_property
+    def Fspring(self) -> float:
+        return self.k * self.dx
+
+    @system_property
+    def Fgrav(self) -> float:
+        return self.g * self.m
+
+    @system_property
+    def Faccel(self) -> float:
+        return self.a * self.m
+
+    @system_property
+    def Ffric(self) -> float:
+        return self.u * self.v
+
+    @system_property
+    def sumF(self) -> float:
+        return self.Fspring - self.Fgrav - self.Faccel - self.Ffric + self.Fext
+    
+    @system_property
+    def Fext(self) -> float:
+        return self.Fa * np.cos( self.time * self.wo_f )
+
+    @system_property
+    def accl(self) -> float:
+        return self.sumF / self.m
+    
+
+#Run The System, Compare damping `u`=0 & 0.1
+sm = SpringMass(x=0.0)
+sm.sim(dt=0.01,endtime=10,u=[0.0,0.1],combos='*',slv_vars='*')
+
+df = sm.dataframe
+df.groupby('run_id').plot('time','x')
+```
+
+##### Results Damping Off
+![olib_spring_mass_clac.png](media/olib_spring_mass_clac.png)
+
+##### Results - Damping On
+<img src="media/olib_spring_mass_clac_damp 1.png" />
+
+
+## Reporting & Analysis
+`Analysis` is capable of tabulation as a `Component` or `System` and wraps a top level `System` and will save data for each system interval. `Analysis` stores several reporters for tables and plots that may be used to store results in multiple locations.
+
+Reporting is supported for tables via dataframes in CSV,Excel and Gsheets (WIP).
+
+For plots reporting is supported in disk storage.
+
+```python
+
+from engforge.analysis import Analysis
+from engforge.reporting import CSVReporter,DiskPlotReporter
+from engforge.properties import system_property
+import numpy as np
+import os,pathlib
+
+this_dir = str(pathlib.Path(__file__).parent)
+this_dir = os.path.join(this_dir,'airfilter_report')
+if not os.path.exists(this_dir):
+    os.path.mkdir(this_dir)
+
+csv = CSVReporter(path=this_dir,report_mode='daily')
+csv_latest = CSVReporter(path=this_dir,report_mode='single')
+
+plots = DiskPlotReporter(path=this_dir,report_mode='monthly')
+plots_latest = DiskPlotReporter(path=this_dir,report_mode='single')
+
+
+@forge
+class AirfilterAnalysis(Analysis):
+    """Does post processing on a system"""
+    
+    efficiency = attrs.field(defualt=0.95)
+
+    @system_property
+    def clean_air_delivery_rate(self) -> float:
+        return self.system.w*self.efficiency
+
+    def post_process(self,*run_args,**run_kwargs):
+        pass
+        #TODO: something custom!
+
+#Air Filter as before
+fan = Fan()
+filt = Filter()
+af = Airfilter(fan=fan,filt=filt)
+
+#Make The Analysis
+sa = AirfilterAnalysis(
+                    system = af,
+                    table_reporters = [csv,csv_latest],
+                    plot_reporters = [plots,plots_latest]
+                   )
+
+#Run the analysis! Input passed to system
+sa.run(throttle=list(np.arange(0.1,1.1,0.1)),combos='*')
+
+
+#CSV's & Plots available in ./airfilter_report!
+```
+
+
+
+
+## Documentation:
+https://ottermatics.github.io/engforge/
+
+### DataStores
+Datastores are a work in progress feature to provide a zero configuration library for storage of tabulated data and report generated artifacts. No garuntee is provided as to their stability yet.
+Requirements for datasources are attempted upon access of `engforge.datastores` and entering of a `CONFIRM` prompt.
+
+### Environmental Variables
+To allow a write-once implement anywhere interface `EnvVariable` is provided for both open (the default) and secret variables. Allowance for type conversion, and defaults are provided.
+
+The current variable slots in memory are listed by `EnvVariable.print_env_vars()`
+```bash
+FORGE_DB_HOST                            |SECRETS[FORGE_DB_HOST]                    = localhost
+FORGE_DB_NAME                            |SECRETS[FORGE_DB_NAME]                    = 
+FORGE_DB_PASS                            |SECRETS[FORGE_DB_PASS]                    = postgres
+FORGE_DB_PORT                            |SECRETS[FORGE_DB_PORT]                    = 5432
+FORGE_DB_USER                            |SECRETS[FORGE_DB_USER]                    = postgres
+FORGE_HOSTNAME                           |SECRETS[FORGE_HOSTNAME]                   = <your-machine>
+FORGE_REPORT_PATH                        |SECRETS[FORGE_REPORT_PATH]                = 
+FORGE_SLACK_LOG_WEBHOOK                  |SECRETS[FORGE_SLACK_LOG_WEBHOOK]          = 
+SEABORN_CONTEXT                         |SECRETS[SEABORN_CONTEXT]                 = paper
+SEABORN_PALETTE                         |SECRETS[SEABORN_PALETTE]                 = deep
+SEABORN_THEME                           |SECRETS[SEABORN_THEME]                   = darkgrid
+```
+