engforge 0.3.0
The Engineer's Framework
Requires Python: >=3.9

[![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
```