Create README.md

README.md

@@ -0,0 +1,89 @@
+# Bio2Py
+Bio2Py (BioWin to Python) is a Python package that runs BioWin simulations using Python. 
+This API is based on the usage of PyAutoGUI Python package to automate loading influent data, running steady-state and dynamic simulations, and saving simulation results without manual intervention. 
+
+Instalation:
+---------------
+Bio2Py can be locally instaled with 'pip'. 
+
+In the root directory containing the file 'Bio2Py-1.0.0.tar.gz', type the command:
+
+    pip install Bio2Py-1.0.0.tar.gz
+
+The file 'Bio2Py-Env.txt' contains the information to create an environment to use Bio2Py. 
+
+Functions:
+---------------
+- setting_the_environment 
+- steady_state_simulations
+- dynamic_simulations
+
+Usage:
+---------------
+Bio2Py automates the process of loading influent data, running simulations and saving simulation results in BioWin. It is necessary to set the system configuration layout, project options, unit system, report options,etc before using Bio2Py. 
+
+In order to use Bio2Py, BioWin simulation window must be fully visible, placing BioWin window on the left side of the screen is recomended. 
+
+**Before using Bio2Py:**
+- Open BioWin simulation file.
+- Set zoom 100% on BioWin window.
+- Choose locations: 
+    - For saving BioWin generated reports with simulation results (File-Report to Excel (TM)- choose directory).
+    - From where variable influen data will be loaded (Influent icon - open file - choose directory)(***). Only necessary if running simulations with variable influent. Choose the same filepath arg when running 'steady_state_simulations'/'dynamic_simulations'.
+- Place BioWin simulation window on the left side of the screen. 
+- Make sure the 'influent' icon is visible. 
+
+**Getting ready:**
+- Import Bio2Py using:
+
+      import Bio2Py
+- Define the variables:
+
+      simulation_window,influen_window=Bio2Py.setting_the_environment()
+
+**Steady state simulations:**
+
+The 'steady_state_simulations' function allows the user to run multiple steady state simulations for constant or variable influent. It has the option of running a flow balance before running the steady state simulation, a good practice when working with complex systems. 
+
+Args:
+- influent_type: Specify whether the influent is constant ('constant') or variable ('variable') over time.
+- influent:
+  - If the influent type is constant (DataFrame):
+    - Each row corresponds to different scenarios to be tested. Columns represent influent characteristics in the same order as in BioWin (flow, N, P...).
+  - If the influent type is variable (Diccionary):
+    Each diccionary key corresponds to a different scenario.
+    - Each diccionary key column corresponds to the influent's parameters in the same order of appearance in BioWin: column_names = ['Flow', 'COD (mg-COD/L)', 'TKN (mg-N/L)', 'TP (mg-P/L)', 'TS (mg-S/L)', 'Nitrate (mg-N/L)', 'pH', 'Alkalinity (mmol/L)', 'ISS total (mg-ISS/L)', 'Metal soluble - Ca (mg/L)', 'Metal soluble - Mg (mg/L)', 'Gas - Dissolved O2 (mg/L)']".
+    - Each diccionary key row corresponds to the influent's parameters at the time specified in the time grid (minutes, days, hours).
+    - Dictionary entries should be ordered from the one with the least number of rows to the one with the most.
+- seed_mass: sets seed values for flow mass balance. Choose between the program options: 'seed' (seed), 'current' (current values), 'last' (last steady state), 'complex' (complex seed). 'None' for not running flow balance.
+- seed_SS: sets seed values for the steady state simulation. Choose between the program options: 'seed' (seed), 'current' (current values), 'last' (last steady state), 'complex' (complex seed).
+- max_simulation_time: sets the maximum time (in seconds) for finding the steady-state solution of each scenario. If the time for finding the solution exceeds the maximum time, the simulation will stop.
+- result_type: 'table' (csv file with album results), 'report' (excel report generated by BioWin) , 'complete' (csv file and excel report) ,'none' (does not save simulation results). 
+    - filepath: specifies where the generated files are saved. For simulations with constant influent, and result type 'table' filepath for saving csv file. For simulations with variable influent, a .txt file is generated by the function to ease influent data loading in BioWin, filepath specifies where to save the .txt file. Must be the same location chosen in (***).
+
+Returns:
+
+Excel report generated by the program or a CSV file with results specified on the first page of the album.
+
+**Dynamic simulations:** 
+
+The 'dynamic_simulations' function allows the user to run multiple dynamic simulations for a constant or variable influent. 
+
+Args:
+- influent_type: Specify whether the influent is constant ('constant') or variable ('variable') over time.
+- influent:
+  - If the influent type is constant (DataFrame):
+    - Each row corresponds to different scenarios to be tested. Columns represent influent characteristics in the same order as in BioWin (flow, N, P...).
+  - If the influent type is variable (Diccionary):
+    Each diccionary key corresponds to a different scenario.
+    - Each diccionary key column corresponds to the influent's parameters in the same order of appearance in BioWin: column_names = ['Flow', 'COD (mg-COD/L)', 'TKN (mg-N/L)', 'TP (mg-P/L)', 'TS (mg-S/L)', 'Nitrate (mg-N/L)', 'pH', 'Alkalinity (mmol/L)', 'ISS total (mg-ISS/L)', 'Metal soluble - Ca (mg/L)', 'Metal soluble - Mg (mg/L)', 'Gas - Dissolved O2 (mg/L)']".
+    - Each diccionary key row corresponds to the influent's parameters at the time specified in the time grid (minutes, days, hours).
+    - Dictionary entries should be ordered from the one with the least number of rows to the one with the most.
+- start_conditions: sets start conditions for the dynamic simulation. Choose between current values ('current') or last steady state values ('last').
+- days: specifies the length of the dynamic simulation in days.
+- max_simulation_time: sets the maximum time for running the dynamic simulation. If the time for finding the solution is exceeds the maximum time, the simulation will stop.
+- filepath (optional): only if influent_type='variable'. When working with variable influen data .txt files are generated for loading influent data to BioWin. Filepath specifies where the .txt files are saved.
+
+Returns:
+
+Excel report generated by BioWin.