### Define GeoStudio Launcher Path in Python

Source: https://pygeostudio.readthedocs.io/en/stable/install.html

Configure PyGeoStudio to locate your GeoStudio installation by providing the path to the GeoStudio executable. This is a one-time setup action.

```python
import PyGeoStudio as pgs
pgs.defineGeoStudioLauncher("C:\\Program Files\\Seequent\\GeoStudio 2023.1")
exit()

```

--------------------------------

### Install PyGeoStudio using pip

Source: https://pygeostudio.readthedocs.io/en/stable/install.html

Use this command to install the PyGeoStudio package via the pip package manager.

```bash
pip install PyGeoStudio

```

--------------------------------

### Setup and File Copy

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/rapid_drawdown_basic.html

Initializes PyGeoStudio, loads a GeoStudio file, and saves a copy for modification during the calibration process.

```python
import PyGeoStudio as pgs
import numpy as np

src_file = "../GeoStudio_files/Rapid drawdown.gsz"
copy_file = "Rapid drawdown_tmp.gsz"
geofile_src = pgs.GeoStudioFile(src_file)
geofile_src.saveAs(copy_file)

```

--------------------------------

### Initialize GeoStudio File and Copy

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Loads a GeoStudio file and saves a copy for modification. This is the initial setup step before performing any analysis or parameter fitting.

```python
import PyGeoStudio as pgs
import numpy as np

src_file = "../GeoStudio_files/1D_unsaturated_column.gsz"
copy_file = '.'.join(src_file.split('.')[:-1]) + "_tmp.gsz"
geofile_src = pgs.GeoStudioFile(src_file)
geofile_src.saveAs(copy_file)
```

--------------------------------

### Import PyGeoStudio and Load Study

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/61d57954e8763b186c6de2878893d05b/rapid_drawdown_Ksat.ipynb

Imports the PyGeoStudio library, opens a GeoStudio study file, and retrieves the hydraulic permeability function of the 'Dam fill' material. This is the initial setup for the parametric study.

```python
import PyGeoStudio as pgs

src_file = "../GeoStudio_files/Rapid drawdown.gsz"
geofile = pgs.GeoStudioFile(src_file)
mat = geofile.getMaterialByName("Dam fill")
Kfunction = mat["Hydraulic"]["KFn"]
```

--------------------------------

### Show and Get Function by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/function.html

Demonstrates how to display all defined functions in a GeoStudio study and retrieve a specific function by its name.

```python
geofile.showFunctions()
krel = geofile.getFunctionByName("Silty clay K function")
```

--------------------------------

### Plot Pore Water Pressure Over Time

Source: https://pygeostudio.readthedocs.io/en/stable/classes/results.html

Example demonstrating how to plot Pore Water Pressure against time at specified locations using the getVariablesVsTime method. It includes setting up labels, legends, and axis titles for clarity.

```python
results1.getOutputVariables() #show available output variables
locations = [[25,2],[23,1]] #get PWP at x=25,y=2 and x=23,y=1
T,PWP = results1.getVariablesVsTime("PoreWaterPressure", locations=locations)
fig,ax = plt.subplots()
ax.plot(
  T, PWP,
  label=["x=25,y=2","x=23,y=1"]
)
ax.grid()
ax.legend()
ax.set_ylabel("PoreWaterPressure")
ax.set_xlabel("Time (s)")
plt.tight_layout()
plt.show()
```

--------------------------------

### Accessing and Modifying Material Properties

Source: https://pygeostudio.readthedocs.io/en/stable/classes/material.html

Demonstrates how to get a Material instance by name and access/modify its properties using dictionary-like syntax.

```APIDOC
## Accessing and Modifying Material Properties

### Description
This section explains how to obtain a Material object and interact with its properties using the `[]` operator for both reading and writing values.

### Usage

1. **Get a Material instance:**
   ```python
   # Assuming 'geofile' is an instance of GeoStudioFile
   mat = geofile.getMaterialByName("Material Name")
   ```

2. **Access and modify properties:**
   Properties can be accessed and modified using their names as keys.
   ```python
   # Get the SeepModel property
   seep_model = mat["SeepModel"]
   
   # Set the SeepModel property
   mat["SeepModel"] = "SatUnsat"
   ```

### Available Properties for Material Class:

- **ID** (int): ID of the material in GeoStudio file. (Use with caution)
- **Name** (str): Name of the material in GeoStudio study.
- **Color** (PyGeoStudio.Color): RGB color (0 to 255) of the material.
- **SeepModel** (str): Hydraulic model ('SatOnly' or 'SatUnsat').
- **SlopeModel** (str): Geomechanical model in SLOPE (e.g., 'MohrCoulomb').
- **StressModel** (str): Geomechanical model in SIGMA (e.g., 'LinearElastric').
- **Hydraulic** (MaterialHydraulicFunction object): Hydraulic properties of the material.
- **StressStrain** (MaterialStressStrain object): Geotechnical properties of the material.
- **Thermal** (MaterialThermalFunction object): Thermal properties of the material.
```

--------------------------------

### Get Material by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves a material object using its name.

```python
geofile.getMaterialByName(_name_)
```

--------------------------------

### Get Available Output Times

Source: https://pygeostudio.readthedocs.io/en/stable/classes/results.html

Retrieves a list of all time steps for which results are saved in a transient analysis.

```python
results1.getOutputTimes()
```

--------------------------------

### Load Model and Extract Data

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/rapid_drawdown_basic.html

Opens the copied GeoStudio file, retrieves a specific material and its hydraulic conductivity function, and gets an analysis object.

```python
geofile = pgs.GeoStudioFile(copy_file)
mat = geofile.getMaterialByName("Dam fill")
Kfunction = mat["Hydraulic"]["KFn"]
instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown")

```

--------------------------------

### Get Reinforcement by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves a reinforcement object using its name.

```python
geofile.getReinforcementByName(_name_)
```

--------------------------------

### Load GeoStudio File and Get Analysis

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/884a5c164a41bca930d4015cfad9f61a/plot_results.ipynb

Loads a GeoStudio file and retrieves a specific analysis by name. Ensure the file path is correct.

```python
import PyGeoStudio as pgs
src_file = "../GeoStudio_files/Rapid drawdown.gsz"
geofile = pgs.GeoStudioFile(src_file)
instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown")
```

--------------------------------

### Get Model Variables Over Time

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Retrieves specific model variables (e.g., PoreWaterPressure) at given locations over time. Used to get the latest model results.

```python
T,PWP = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[[25,2]])
```

--------------------------------

### Get Available Output Variables

Source: https://pygeostudio.readthedocs.io/en/stable/classes/results.html

Retrieves a list of all output variables available in the analysis results.

```python
results1.getOutputVariables()
```

--------------------------------

### Get Dataset by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves a dataset object using its name.

```python
geofile.getDatasetByName(_name_)
```

--------------------------------

### Show and Get a Specific Dataset

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/9775712cff32d710b996fb962b0eed3b/update_dataset.ipynb

Display all available datasets in the GeoStudio file and retrieve a specific dataset by its name. This helps in identifying and accessing the data you need.

```python
geofile.showDatasets()
dataset = geofile.getDatasetByName("Daily Precipitation")
print("\n", dataset)
```

--------------------------------

### Accessing Analysis Results

Source: https://pygeostudio.readthedocs.io/en/stable/classes/results.html

Demonstrates how to get an instance of the Results class from a GeoStudioFile object. This is the initial step to access analysis results.

```python
#geofile is a GeoStudioFile instance
geofile.showAnalysisTree()
analysis1 = geofile.getAnalysisByID(1)
results1 = analysis1["Results"]
```

--------------------------------

### Access and Modify Saturated Hydraulic Conductivity

Source: https://pygeostudio.readthedocs.io/en/stable/classes/material.html

Demonstrates how to get and set the saturated hydraulic conductivity ('KSat') for a material's hydraulic properties.

```python
KSat = hydraulic_props["KSat"] #get
geotech_props["KSat"] = 1e-6   #set
```

--------------------------------

### Get Reinforcement by ID

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves a reinforcement object using its unique ID.

```python
geofile.getReinforcementByID(_ID_)
```

--------------------------------

### Get Material by ID

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves a material object using its unique ID.

```python
geofile.getMaterialByID(_ID_)
```

--------------------------------

### Plotting Analysis Problem

Source: https://pygeostudio.readthedocs.io/en/stable/classes/analysis.html

Visualizes the conceptual problem of the analysis, including the material distribution. This method is useful for verifying the analysis setup.

```python
analysis1.showProblem()
```

--------------------------------

### Plot Pore Water Pressure vs. Time

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/884a5c164a41bca930d4015cfad9f61a/plot_results.ipynb

Plots the Pore Water Pressure for specified locations against time using Matplotlib. This snippet requires the 'matplotlib' library to be installed. It sets labels, adds a legend, and displays the plot.

```python
import matplotlib.pyplot as plt
T,PWP = results.getVariablesVsTime("PoreWaterPressure", locations=[[25,2],[23,1]])
fig,ax = plt.subplots()
ax.plot(
  T, PWP,
  label=["x=25,y=2","x=23,y=1"]
)
ax.grid()
ax.legend()
ax.set_ylabel("PoreWaterPressure")
ax.set_xlabel("Time (s)")
plt.tight_layout()
plt.show()
```

--------------------------------

### Adjust Relative Hydraulic Conductivity Function

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/4c1873de17db7f89eb91da84cb3ad8d5/change_saturated_perm.ipynb

Retrieves and modifies the relative hydraulic conductivity function for a 'SatUnsat' material. The example scales the hydraulic conductivity by an order of magnitude.

```python
mat2 = geofile.getMaterialByName("Dam fill") #get material nammed "Dam fill"
Krel = mat2["Hydraulic"]["KFn"]
print("Water suction:", Krel.getXData())
print("Hydraulic conductivity:", Krel.getYData())
new_Krel = Krel.getYData() * 10. # scale hydraulic conductivity by an order of magnitude
Krel.setYData(new_Krel)
```

--------------------------------

### Import Libraries and Open GeoStudio File

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/9775712cff32d710b996fb962b0eed3b/update_dataset.ipynb

Import necessary libraries and open a GeoStudio file to begin working with datasets. This is the initial step for most dataset operations.

```python
import PyGeoStudio as pgs
import numpy as np

src_file = "../GeoStudio_files/Soil Cover Modeling - Hydraulic Response.gsz"
geofile = pgs.GeoStudioFile(src_file)
```

--------------------------------

### Context Class Initialization

Source: https://pygeostudio.readthedocs.io/en/stable/classes/context.html

Initializes the Context class. Parameters like AnalysisID, GeometryUsesMaterials, and HydraulicBCDistribution can be provided. AnalysisID is handled automatically by PyGeoStudio.

```python
class PyGeoStudio.Context(_prop=None_)
    Parameters:
        AnalysisID (int) – ID of the analysis to apply this context. Handle automatically by PyGeoStudio. Do not change until you know what you are doing.
        GeometryUsesMaterials (dict) – Material distribution as a dictionnary such as {"region_name_1" : mat_id_1, "region_name_2" : mat_id_2, ...}
        HydraulicBCDistribution (dict) – Distribution of the hydraulic boundary condition as a dictionnary such as {}
```

--------------------------------

### Set Up Hydraulic Functions

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/1D_unsaturated_column_VG_parameter.html

Resizes and sets the X-data (suction) for the Water Content and Hydraulic Conductivity functions. This prepares the functions for fitting.

```python
N = 100 # number of data point
psi = np.logspace(-1,4,N) #suction from 0.1 to 1000 KPa
WCfunction.resizeXYData(N)
WCfunction.setXData(psi)
Kfunction.resizeXYData(N)
Kfunction.setXData(psi)
```

--------------------------------

### Get Analysis by ID

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves an analysis object from the analysis tree using its unique ID.

```python
geofile.getAnalysisByID(_ID_)
```

--------------------------------

### Open a GeoStudio Study

Source: https://pygeostudio.readthedocs.io/en/stable/user_guide.html

Initialize the GeoStudioFile class with the path to your GeoStudio study file (.gsz). This loads the study into memory for Python access. Changes made through this object do not affect the original file.

```python
import PyGeoStudio as pgs
src_file = "Reinforcement with Anchors.gsz"
geofile = pgs.GeoStudioFile(src_file)
```

--------------------------------

### Show Functions

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table listing all functions defined within the GeoStudio file.

```python
geofile.showFunctions()
```

--------------------------------

### Show Materials (Minimal Detail)

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table listing minimal properties of the materials defined in the GeoStudio file.

```python
geofile.showMaterials(_detail =0_)
```

--------------------------------

### Color Class Usage

Source: https://pygeostudio.readthedocs.io/en/stable/classes/color.html

Demonstrates how to instantiate the Color class using RGB values or Matplotlib CSS4 color names and how to assign a color to a material.

```APIDOC
## Color Class

### Description
A helper class to handle color from GeoStudio file and Matplotlib colors. Color objects can be constructed either by specifying the name of a matplotlib color, or a list with RGB intensity from 0 to 255.

### Usage Examples
```python
from PyGeoStudio import Color

# Create a Color object using RGB values (0-255)
rgb_color = Color([156, 35, 76])

# Create a Color object using a Matplotlib CSS4 color name
darkblue_color = Color("darkblue")

# Assign a color to a material named 'mat'
mat["Color"] = darkblue_color
```

### Methods
#### `setMPLColor(_color_)`

Set color as defined in Matplotlib CSS4 colors.

##### Parameters
* **color** (_str_) - Required - The color as defined in Matplotlib CSS4 colors.
```

--------------------------------

### Get Analysis by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Retrieves an analysis object from the analysis tree using its name. Raises ValueError if no analysis is found.

```python
geofile.getAnalysisByName(_name_)
```

--------------------------------

### Show Reinforcements (Minimal Detail)

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table listing minimal properties of the reinforcements defined in the GeoStudio file.

```python
geofile.showReinforcements(_detail =0_)
```

--------------------------------

### Select Material by Name

Source: https://pygeostudio.readthedocs.io/en/stable/classes/material.html

Demonstrates how to select a specific material by its name from a GeoStudioFile instance.

```python
#geofile is a GeoStudioFile instance
geofile.showMaterials()
mat = geofile.getMaterialByName("Toe drain") #get material nammed "Toe drain" as a Material instance
```

--------------------------------

### Function Class Initialization

Source: https://pygeostudio.readthedocs.io/en/stable/classes/function.html

Shows the basic structure for initializing a Function object, including its parameters like ID, Name, and Points.

```python
class _PyGeoStudio.Function(_prop =None_)
```

--------------------------------

### Adding Lines to Geometry

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geometry.html

Adds lines to an existing Geometry object. Lines are defined by the start and end indices of points.

```python
addLines(_lines_)
```

--------------------------------

### Show Datasets

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table listing all datasets defined within the GeoStudio file.

```python
geofile.showDatasets()
```

--------------------------------

### Define Model and Run Function

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Sets up the suction (psi) data points and defines a function `run_model` that updates the hydraulic functions with new parameters, runs the simulation, and returns the simulated Pore Water Pressure.

```python
N = 100 # number of data point
psi = np.logspace(-1,4,N) #suction from 0.1 to 1000 KPa
WCfunction.resizeXYData(N)
WCfunction.setXData(psi)
Kfunction.resizeXYData(N)
Kfunction.setXData(psi)
def run_model(xdata, new_log_Ksat, tets, a_log, n, tetr, m):
  new_Ksat = 10.**new_log_Ksat
  a = 10**a_log
  # set the new hydraulic conductivity function
  theta = pgs.builtin_functions.VanGenuchtenWC(psi,tets, a, n, tetr)
  WCfunction.setYData(theta)
  Krel = pgs.builtin_functions.VanGenuchtenMualemK(theta, m)
  Kfunction.setYData(new_Ksat * Krel)
  # run the analysis
  geofile.save()
  pgs.run(geofile, analyses_to_solve=[instant_drawdown])
  # return fitted data
  T,PWP = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[location])
  return PWP
```

--------------------------------

### Open GeoStudio File with PyGeoStudio

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/8e4e1f4b9953e0fa89823a933fd5f702/change_anchors_properties.ipynb

Opens a GeoStudio file using PyGeoStudio. Ensure the file path is correct.

```python
import PyGeoStudio as pgs
src_file = "../GeoStudio_files/Reinforcement with Anchors.gsz"
geofile = pgs.GeoStudioFile(src_file) #open it with PyGeoStudio
```

--------------------------------

### Generate Experimental Data

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/rapid_drawdown_basic.html

Creates synthetic experimental data for pore water pressure by adding random noise to the actual model results. This simulates real-world measurements.

```python
target_Ksat = Kfunction.getYData()[0]
Tdata, PWPdata = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[[25,2]])
PWPdata += np.random.normal(0.,1.5,len(PWPdata)) #add some noise to measurement with std dev of 1.5 KPa

```

--------------------------------

### Perform Calibration and Print Results

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/rapid_drawdown_basic.html

Uses `scipy.optimize.curve_fit` to calibrate the model by finding the optimal base-10 logarithm of saturated hydraulic conductivity. It then prints the optimized Ksat, target Ksat, and optimization status.

```python
from scipy.optimize import curve_fit
initial_guess_log = -7
initial_PWP = run_model(None,initial_guess_log) #Run model to get non-calibrated results
popt, pcov, info_dict, mesg, ier = curve_fit(
  run_model, Tdata, PWPdata, p0=initial_guess_log, full_output=True
)
print("\n\n\nOptimisation results")
print("Optimal Ksat: ", 10.**popt[0], ", Target Ksat was:", target_Ksat)
print("Optimisation information: ", info_dict)
print("Optimisation status: ", ier, " - ", mesg)

```

--------------------------------

### Parametric Study Loop: Simulate and Collect Data

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/parametric/rapid_drawdown_Ksat.html

Iterates through each defined Ksat value, scales the hydraulic conductivity function accordingly, runs the GeoStudio simulation for the 'Instantaneous drawdown' analysis, and extracts pore water pressure results over time at a specific location. The results are stored for later plotting.

```python
for new_Ksat in Ksats:
  # scale hydraulic conductivity
  # note relative permeability is defined through the function,
  # not by the KSat attribute which is for saturated only model
  actual_relK = Kfunction.getYData()
  actual_Ksat = Kfunction.getYData()[0]
  Kfunction.setYData(new_Ksat/actual_Ksat * actual_relK)
  # run GeoStudio
  geofile.save()
  instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown")
  pgs.run(geofile, analyses_to_solve=[instant_drawdown])
  # get results
  T,PWP = instant_drawdown["Results"].getVariablesVsTime(
    "PoreWaterPressure",
    locations=[[25,2]]
  )
  # store it for future plotting
  Ts.append(T)
  PWPs.append(PWP)

```

--------------------------------

### Open GeoStudio Study

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/bfa8c7fba2b97e0ea85889059129510f/create_region.ipynb

Opens a GeoStudio study file using PyGeoStudio. Ensure the file path is correct.

```python
import PyGeoStudio as pgs
src_file = "../GeoStudio_files/test.gsz"
geofile = pgs.GeoStudioFile(src_file)
```

--------------------------------

### Get Mesh Bounding Box

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Retrieve the coordinates of the two diagonal points that define the mesh's bounding box. This helps in understanding the spatial extent of the mesh.

```python
bbox_points = mesh_study.getMeshBoundingBox()
```

--------------------------------

### Accessing GeoStudio File Properties

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Demonstrates how to call methods to retrieve specific information from an opened GeoStudio file.

```python
geofile.showMaterials() #show a list of materials
geofile.getMaterialByID(3) #return material with ID 3
```

--------------------------------

### Modify Dataset Data

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/9775712cff32d710b996fb962b0eed3b/update_dataset.ipynb

Access and modify the data within a dataset. The data is stored as a NumPy array in the 'Data' attribute. This example changes a specific value in the dataset.

```python
dataset["Data"][2,1] = 1e-9 # m/d
print("\nDataset after changing first row: ", dataset)
```

--------------------------------

### Create New Dataset from Array

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/9775712cff32d710b996fb962b0eed3b/update_dataset.ipynb

Create a new dataset from scratch by providing a name, column headers, and a NumPy array containing the data. This is useful for generating custom datasets.

```python
new_dataset = geofile.createNewDataset("MyNewDataset",["Time","WaterFlux"])
arr = np.arange(0,46).reshape(23,2).astype(float) #create a example array
new_dataset.loadDataFromArray(arr)
print("\nNew dataset: ", new_dataset)
```

--------------------------------

### Get Point Index by Location

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Find the index of the mesh point closest to a given 3D location. The location should be provided as an iterable (e.g., a list or tuple) of X, Y, and Z coordinates.

```python
point_index = mesh_study.getPointIndexInMesh([1.0, 2.0, 3.0])
```

--------------------------------

### showMaterials

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints information about the materials defined in the GeoStudio file. Users can choose to see minimal properties or exhaustive details.

```APIDOC
## showMaterials

### Description
Print the material defined within the GeoStudio file.

### Parameters
* **detail** (int (0 or 1)) – Show a table listing minimal properties of the materials (0) or print exhaustive information (1)
```

--------------------------------

### showFunctions

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table of all functions defined in the GeoStudio file. This helps in understanding the functional definitions within the study.

```APIDOC
## showFunctions

### Description
Print a table showing the functions defined within the GeoStudio file.
```

--------------------------------

### Show Materials (Exhaustive Detail)

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints exhaustive information about the materials defined in the GeoStudio file.

```python
geofile.showMaterials(_detail =1_)
```

--------------------------------

### Calibrate Van Genuchten Parameters

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/1D_unsaturated_column_VG_parameter.html

Uses `scipy.optimize.curve_fit` to calibrate the Van Genuchten parameters by minimizing the difference between the simulated and experimental pore water pressure data. Initial guesses for the parameters are provided.

```python
from scipy.optimize import curve_fit
initial_guess = [np.log10(4e-7), 0.3, np.log10(1), 2, 0.04, 2]
popt, pcov, info_dict, mesg, ier = curve_fit(
  run_model, Tdata, PWPdata, p0=initial_guess, full_output=True
)
```

--------------------------------

### Open a GeoStudio File

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Opens a GeoStudio file in read mode. This is the initial step to access study properties.

```python
import PyGeoStudio as pgs
src_file = "Reinforcement with Anchors.gsz"
geofile = pgs.GeoStudioFile(src_file,mode='r')
```

--------------------------------

### Create New Dataset from CSV and Save

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/9775712cff32d710b996fb962b0eed3b/update_dataset.ipynb

Create a new dataset by loading data from a CSV file and then save the modified GeoStudio file. Ensure the CSV file path is correct and the column headers match.

```python
csv_dataset = geofile.createNewDataset("MyNewCSVDataset",["Time","WaterFlux"])
csv_dataset.loadDataFromCSV("./adataset.csv")
print("\nCSV dataset: ", csv_dataset)
geofile.saveAs("modified_datasets.gsz")
```

--------------------------------

### Open GeoStudio File and Select Analysis

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/3ed86b7ea47bd4e47da0a27fb0a2172c/export_results.ipynb

Opens a GeoStudio analysis file and selects a specific analysis by name. Ensure the file path is correct.

```python
import PyGeoStudio as pgs
src_file = "../GeoStudio_files/Rapid drawdown.gsz" #specify the geostudio analyses file
geofile = pgs.GeoStudioFile(src_file) #open it with PyGeoStudio
```

--------------------------------

### Display Calibration Results

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/1D_unsaturated_column_VG_parameter.html

Prints the optimization information, status, and a formatted table comparing the calibrated Van Genuchten parameter values against their target values.

```python
from prettytable import PrettyTable
print("\n\n\nOptimisation results")
print("Optimisation information: ", info_dict)
print("Optimisation status: ", ier, " - ", mesg)
res = PrettyTable()
res.field_names = ["Parameter","Calibrated value","Target value"]
res.add_row(["Ksat", 10.**popt[0], 1e-6])
res.add_row(["Saturated Water Content", popt[1], 0.453])
res.add_row(["Air Entry Value", 10.**popt[2], 13])
res.add_row(["VG n", popt[3], 2.3])
res.add_row(["Resisual Water Content", popt[4], 1.5e-4])
res.add_row(["K relative m", popt[5], "User-defined"])
print(res)
```

--------------------------------

### Import Libraries and Open GeoStudio File

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/01b70245eafc703a36d2785acd90a43c/change_timestepping.ipynb

Imports necessary libraries and opens a specified GeoStudio analysis file for manipulation.

```python
import numpy as np
import PyGeoStudio as pgs
src_file = "../GeoStudio_files/Rapid drawdown.gsz" #specify the geostudio analyses file
geofile = pgs.GeoStudioFile(src_file) #open it with PyGeoStudio
```

--------------------------------

### Show Geometries

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints the geometries defined within the GeoStudio file.

```python
geofile.showGeometries()
```

--------------------------------

### GeoStudioFile Constructor

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Initializes the GeoStudioFile object to read a GeoStudio .gsz file. This is the primary way to load a study into PyGeoStudio.

```APIDOC
## GeoStudioFile Constructor

### Description
Initializes the GeoStudioFile object to read a GeoStudio .gsz file. This is the primary way to load a study into PyGeoStudio.

### Parameters
* **geostudio_file** (str) – Path to the GeoStudio file
```

--------------------------------

### Plot Experimental Data and Calibrated Model

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Visualizes the noisy experimental data, the initial model guess, and the final calibrated model results. Requires matplotlib.

```python
import matplotlib.pyplot as plt
fig,ax = plt.subplots()
ax.scatter(Tdata, PWPdata, color="k", label=f"Noisy experimental data")
ax.plot(Tdata, initial_PWP, color='b', label="Initial guess (K=1e-7 m/s)")
ax.plot(Tdata, PWP, color="r", label=f"Calibrated model")
ax.grid()
ax.legend()
ax.set_ylabel("PoreWaterPressure")
ax.set_xlabel("Time (s)")
plt.tight_layout()
plt.show()
```

--------------------------------

### Create New Dataset

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Creates a new dataset within the GeoStudio file, requiring a name and a list of parameters.

```python
geofile.createNewDataset(_name_ , _parameters_)
```

--------------------------------

### Load File and Extract Data

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Opens a copied GeoStudio file, retrieves a specific material's hydraulic properties, and accesses a defined analysis for result extraction.

```python
geofile = pgs.GeoStudioFile(copy_file)
mat = geofile.getMaterialByName("Dam fill")
Kfunction = mat["Hydraulic"]["KFn"]
instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown")
```

--------------------------------

### Calibrate Model with Curve Fit

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Calibrates the model using scipy.optimize.curve_fit. Requires initial guess and experimental data.

```python
from scipy.optimize import curve_fit
initial_guess_log = -7
initial_PWP = run_model(None,initial_guess_log) #Run model to get non-calibrated results
popt, pcov, info_dict, mesg, ier = curve_fit(
  run_model, Tdata, PWPdata, p0=initial_guess_log, full_output=True
)
print("\n\n\nOptimisation results")
print("Optimal Ksat: ", 10.**popt[0], ", Target Ksat was:", target_Ksat)
print("Optimisation information: ", info_dict)
print("Optimisation status: ", ier, " - ", mesg)
```

--------------------------------

### setContext Method

Source: https://pygeostudio.readthedocs.io/en/stable/classes/analysis.html

Sets a new material distribution and boundary conditions to the analysis.

```APIDOC
## Method: setContext

### Description
Sets a new material distribution and boundary conditions to the analysis.

### Parameters
- **context** (Context object) – The new material distribution and boundary condition of the analysis
```

--------------------------------

### Show Reinforcements (Exhaustive Detail)

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints exhaustive information about the reinforcements defined in the GeoStudio file.

```python
geofile.showReinforcements(_detail =1_)
```

--------------------------------

### Calibrate Parameters and Display Results

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Uses `scipy.optimize.curve_fit` to calibrate the Van Genuchten parameters by minimizing the difference between simulated and noisy experimental data. Results are then displayed in a formatted table.

```python
from scipy.optimize import curve_fit
initial_guess = [np.log10(4e-7), 0.3, np.log10(1), 2, 0.04, 2]
popt, pcov, info_dict, mesg, ier = curve_fit(
  run_model, Tdata, PWPdata, p0=initial_guess, full_output=True
)

from prettytable import PrettyTable
print("\n\n\nOptimisation results")
print("Optimisation information: ", info_dict)
print("Optimisation status: ", ier, " - ", mesg)
res = PrettyTable()
res.field_names = ["Parameter","Calibrated value","Target value"]
res.add_row(["Ksat", 10.**popt[0], 1e-6])
res.add_row(["Saturated Water Content", popt[1], 0.453])
res.add_row(["Air Entry Value", 10.**popt[2], 13])
res.add_row(["VG n", popt[3], 2.3])
res.add_row(["Resisual Water Content", popt[4], 1.5e-4])
res.add_row(["K relative m", popt[5], "User-defined"])
print(res)
```

--------------------------------

### Show Analysis Tree

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints the analysis tree, displaying analysis ID, name, and parent ID.

```python
geofile.showAnalysisTree()
```

--------------------------------

### Setting Analysis Context

Source: https://pygeostudio.readthedocs.io/en/stable/classes/analysis.html

Updates the material distribution and boundary conditions for an analysis. This method requires a Context object as input.

```python
analysis1.setContext(context)
```

--------------------------------

### Parametric Study Loop for Ksat Analysis

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/61d57954e8763b186c6de2878893d05b/rapid_drawdown_Ksat.ipynb

Iterates through different Ksat values, scales the hydraulic conductivity function, runs the instantaneous drawdown analysis in GeoStudio, and retrieves pore water pressure results over time. The saturated hydraulic conductivity is adjusted by scaling the entire conductivity function.

```python
for new_Ksat in Ksats:
  # scale hydraulic conductivity
  # note relative permeability is defined through the function,
  # not by the KSat attribute which is for saturated only model
  actual_relK = Kfunction.getYData()
  actual_Ksat = Kfunction.getYData()[0]
  Kfunction.setYData(new_Ksat/actual_Ksat * actual_relK)
  # run GeoStudio
  geofile.save()
  instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown")
  pgs.run(geofile, analyses_to_solve=[instant_drawdown])
  # get results
  T,PWP = instant_drawdown["Results"].getVariablesVsTime(
    "PoreWaterPressure",
    locations=[[25,2]]
  )
  # store it for future plotting
  Ts.append(T)
  PWPs.append(PWP)
```

--------------------------------

### showProblem Method

Source: https://pygeostudio.readthedocs.io/en/stable/classes/analysis.html

Plots the conceptual problem defined in the analysis, including the material distribution.

```APIDOC
## Method: showProblem

### Description
Plots the conceptual problem defined in the analysis (with material distribution)
```

--------------------------------

### showDatasets

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints a table summarizing all datasets defined within the GeoStudio file. This is useful for quickly inspecting available datasets.

```APIDOC
## showDatasets

### Description
Print a table showing the dataset defined within the GeoStudio file.
```

--------------------------------

### Load Analysis and Extract Hydraulic Functions

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Opens the copied GeoStudio file and retrieves the material's hydraulic properties (Volumetric Water Content and Hydraulic Conductivity functions) and a specific analysis (Instant Drawdown).

```python
geofile = pgs.GeoStudioFile(copy_file)
mat = geofile.getMaterialByName("Material")
WCfunction = mat["Hydraulic"]["VolWCFn"]
Kfunction = mat["Hydraulic"]["KFn"]
instant_drawdown = geofile.getAnalysisByID(1)
```

--------------------------------

### Define Saturated Permeability Values and Initialize Lists

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/61d57954e8763b186c6de2878893d05b/rapid_drawdown_Ksat.ipynb

Defines a list of saturated hydraulic conductivity (Ksat) values to be tested and initializes empty lists to store simulation results (time and pore water pressure).

```python
Ksats = [1e-7, 1e-6, 1e-5, 1e-4]
Ts = []
PWPs = []
```

--------------------------------

### List Materials in the Study

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/4c1873de17db7f89eb91da84cb3ad8d5/change_saturated_perm.ipynb

Displays a list of all materials defined in the GeoStudio study, showing their IDs, names, and types. This is useful for identifying materials before selection.

```python
geofile.showMaterials()
```

--------------------------------

### Print Reinforcement Properties

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/8e4e1f4b9953e0fa89823a933fd5f702/change_anchors_properties.ipynb

Retrieves all reinforcements from the GeoStudio file and prints the detailed properties of each one. This helps in understanding the available attributes for each reinforcement.

```python
reinfs = geofile["Reinforcements"] #get reinforcements defined in the study
for reinf in reinfs: #print the reinforcement properties
  print(reinf)
  print("----------------------")
```

--------------------------------

### Select Reinforcement by ID

Source: https://pygeostudio.readthedocs.io/en/stable/classes/reinforcement.html

Demonstrates how to select a specific reinforcement from a GeoStudio study using its ID. Assumes 'geofile' is an initialized GeoStudioFile instance.

```python
#geofile is a GeoStudioFile instance
geofile.showReinforcements()
reinf = geofile.getReinforcementsByID(1)
```

--------------------------------

### Creating a Region with New Geometry

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geometry.html

Creates new points, lines, and a region based on provided point coordinates. The points must form a convex, non-intersecting polygon when connected sequentially.

```python
createRegion(_pts_)
```

--------------------------------

### Access Function from Material Object

Source: https://pygeostudio.readthedocs.io/en/stable/classes/function.html

Illustrates how to access a function directly from a material object within a GeoStudio study.

```python
mat = geofile.getMaterialByName("Dam fill")
krel = mat["KFn"]
```

--------------------------------

### Generate Noisy Experimental Data

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Extracts the target saturated hydraulic conductivity (Ksat) and pore water pressure (PWP) data over time from the analysis results. Artificial noise is added to the PWP data to simulate experimental measurements.

```python
target_Ksat = Kfunction.getYData()[0]
Tdata, PWPdata = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[[25,2]])
PWPdata += np.random.normal(0.,1.5,len(PWPdata)) #add some noise to measurement with std dev of 1.5 KPa
```

--------------------------------

### write()

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Extracts and saves the mesh data in the GeoStudio native `.ply` format.

```APIDOC
## write(_path_)

Extract and save the mesh in GeoStudio native format with extention `.ply`

Parameters:
* **path** (_str_) – Path to the output mesh file
```

--------------------------------

### showAnalysisTree

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints the analysis tree of the GeoStudio file, displaying analysis IDs, names, and parent IDs. This provides an overview of the study's analysis structure.

```APIDOC
## showAnalysisTree

### Description
Print the analysis tree in the GeoStudio file with analysis ID, name and parent ID if defined.
```

--------------------------------

### Generate Artificial Noisy Data

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Creates synthetic experimental data for Pore Water Pressure over time by adding random noise to actual simulation results. This is used for calibrating the model.

```python
location = [0.05,0.8]
Tdata, PWPdata = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[location])
PWPdata += np.random.normal(0.,0.2,len(PWPdata)) #add some noise to measurement with std dev of 0.5 KPa
```

--------------------------------

### Plotting Calibration Results

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/rapid_drawdown_basic.html

Visualizes the noisy experimental data, the initial guess model results, and the final calibrated model results using Matplotlib. This helps in assessing the quality of the calibration.

```python
import matplotlib.pyplot as plt
fig,ax = plt.subplots()
ax.scatter(Tdata, PWPdata, color="k", label=f"Noisy experimental data")
ax.plot(Tdata, initial_PWP, color='b', label="Initial guess (K=1e-7 m/s)")
ax.plot(Tdata, PWP, color="r", label=f"Calibrated model")
ax.grid()
ax.legend()
ax.set_ylabel("PoreWaterPressure")
ax.set_xlabel("Time (s)")
plt.tight_layout()
plt.show()

```

--------------------------------

### showReinforcements

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints information about the reinforcements defined in the GeoStudio file. Similar to showMaterials, it allows for viewing minimal or exhaustive details.

```APIDOC
## showReinforcements

### Description
Print the reinforcements defined within the GeoStudio file.

### Parameters
* **detail** (int (0 or 1)) – Show a table listing minimal properties of the reinforcements (0) or print exhaustive information (1)
```

--------------------------------

### Define Model Run Function for Calibration

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/calibrations/1D_unsaturated_column_VG_parameter.html

This function takes Van Genuchten parameters, updates the hydraulic functions in the GeoStudio model, runs the analysis, and returns the simulated pore water pressure. It's designed to be used with `scipy.optimize.curve_fit`.

```python
def run_model(xdata, new_log_Ksat, tets, a_log, n, tetr, m):
  new_Ksat = 10.**new_log_Ksat
  a = 10**a_log
  # set the new hydraulic conductivity function
  theta = pgs.builtin_functions.VanGenuchtenWC(psi,tets, a, n, tetr)
  WCfunction.setYData(theta)
  Krel = pgs.builtin_functions.VanGenuchtenMualemK(theta, m)
  Kfunction.setYData(new_Ksat * Krel)
  # run the analysis
  geofile.save()
  pgs.run(geofile, analyses_to_solve=[instant_drawdown])
  # return fitted data
  T,PWP = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[location])
  return PWP
```

--------------------------------

### Access and Modify Seep Model

Source: https://pygeostudio.readthedocs.io/en/stable/classes/material.html

Shows how to retrieve and update the 'SeepModel' property of a material. The 'SeepModel' can be set to 'SatOnly' or 'SatUnsat'.

```python
seepmodel = mat["SeepModel"] #store seep model (SatOnly or SatUnsat) in a variable
mat["SeepModel"] = "SatUnsat" #change seep model to SatUnsat
```

--------------------------------

### Retrieve Modelled Pore Water Pressure

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

After the calibration, this snippet retrieves the final modelled Pore Water Pressure values from the analysis results.

```python
T,PWP = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[location])
```

--------------------------------

### export()

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Exports the current mesh along with optional point data in various formats using the MeshIO library.

```APIDOC
## export(_path_, _point_data =None_)

Export the current mesh with point data provided in another format. Export are carried with MeshIO.

Parameters:
* **path** (_str_) – Path to the output mesh file
* **point_data** (_dict_) – Point data to write with the mesh (default = No data). Supplied as a dictionary with point dataset name as the key and value a iterable whose size match the number of point in the mesh.
```

--------------------------------

### Plotting Calibrated Model vs. Experimental Data

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/149dcccb413145d86a4f5f7bf69922c2/1D_unsaturated_column_VG_parameter.ipynb

Use this snippet to visualize the agreement between a calibrated model and noisy experimental data. It requires matplotlib for plotting and assumes Tdata, PWPdata, and PWP are defined.

```python
import matplotlib.pyplot as plt
fig,ax = plt.subplots()
ax.scatter(Tdata, PWPdata, color="k", label=f"Noisy experimental data")
ax.plot(Tdata, PWP, color="r", label=f"Calibrated model")
ax.grid()
ax.legend()
ax.set_ylabel("PoreWaterPressure")
ax.set_xlabel("Time (s)")
plt.tight_layout()
plt.show()
```

--------------------------------

### Display Current Timesteps

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/basics/change_timestepping.html

Prints the details of the current timesteps configured for the analysis.

```python
timestepping.showTimeSteps()
```

--------------------------------

### Function Class

Source: https://pygeostudio.readthedocs.io/en/stable/classes/function.html

Details of the Function class, including its constructor parameters and attributes.

```APIDOC
## Class _PyGeoStudio.Function

### Description
Represents a custom function within a GeoStudio study, used for various purposes such as defining water retention curves, hydraulic functions, custom boundary conditions, or reinforcements.

### Parameters

- **ID** (int) - ID of the function (must not be changed).
- **Name** (str) - Name of the function.
- **Points** (numpy array) - XY points that define the function for interpolation.
- **Function** - (No description provided in source)
- **Estimate** - (No description provided in source)
- **Types** (list of str) - Type of function. For example, for a function defining a water retention curve of a material, function type is `["Material", "Hydraulic", "VolWCFun"]`.
```

--------------------------------

### Accessing Analysis by ID

Source: https://pygeostudio.readthedocs.io/en/stable/classes/analysis.html

Demonstrates how to retrieve an Analysis object from a GeoStudioFile using its ID. This is the primary method for obtaining an analysis instance for further manipulation.

```python
geofile.showAnalysisTree()
analysis1 = geofile.getAnalysisByID(1)
```

--------------------------------

### Adding Regions to Geometry

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geometry.html

Creates a region in the geometry using existing points. Requires a list of point indices.

```python
addRegions(_pt_ids_)
```

--------------------------------

### Export Steady-State Results to VTU

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/3ed86b7ea47bd4e47da0a27fb0a2172c/export_results.ipynb

Exports all results from a selected steady-state analysis to a single VTU file. This is useful for static post-processing.

```python
steady_state = geofile.getAnalysisByName("1 - Initial steady-state") #select analysis 1
steady_state["Results"].exportAllResultsVTU("steady_state_res.vtu")
```

--------------------------------

### Save Mesh in GeoStudio Format

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Extract and save the current mesh in GeoStudio's native `.ply` format. Provide a valid file path for the output.

```python
mesh_study.write(path='/path/to/save/mesh.ply')
```

--------------------------------

### Mesh Class Initialization and Access

Source: https://pygeostudio.readthedocs.io/en/stable/classes/mesh.html

Meshes are accessed through the Geometry object of a GeoStudio analysis. The Mesh class constructor takes a mesh ID and source mesh information.

```APIDOC
## Mesh Class

Meshes are accessed through the Geometry object:
```python
analysis = geofile.getAnalysisByID(1)
geom = analysis1["Geometry"]
mesh = geom["Mesh"]
```

### Class Definition

`_PyGeoStudio.Mesh(_mesh_id_, _src_mesh_)`

Parameters:
* **MeshId** (_int_) – Index of the mesh
* **Vertices** (_numpy array_) – XY coordinates of mesh vertices
* **Elements** (_list_) – list of mesh vertices defining the mesh elements
```

--------------------------------

### Print Detailed Material Properties

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/4c1873de17db7f89eb91da84cb3ad8d5/change_saturated_perm.ipynb

Retrieves all material objects from the analysis and prints the name and properties of each material. This provides a comprehensive view of material definitions.

```python
mats = geofile["Materials"] #get material defined in the analysis
for mat in mats: #print the material name properties
  print(mat)
  print("----------------------")
```

--------------------------------

### Instantiate Color Objects

Source: https://pygeostudio.readthedocs.io/en/stable/classes/color.html

Create Color objects using either RGB values (0-255) or Matplotlib CSS4 color names. This is useful for defining custom colors or using standard named colors.

```python
from PyGeoStudio import Color
rgb_color = Color([156,35,76]) #RGB color
darkblue_color = Color("darkblue") #matplotlib CSS4 color
```

--------------------------------

### Export Transient Analysis Results to VTU

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/3ed86b7ea47bd4e47da0a27fb0a2172c/export_results.ipynb

Exports results from a transient analysis to multiple VTU files, one for each saved timestep. This allows for time-dependent analysis.

```python
instant_drawdown = geofile.getAnalysisByName("2 - Instantaneous drawdown") #select analysis 2
instant_drawdown["Results"].exportAllResultsVTU("transient_res.vtu")
```

--------------------------------

### Accessing Geometry Object

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geometry.html

Demonstrates how to access the Geometry object associated with a specific analysis from a GeoStudioFile object.

```python
geofile.showAnalysisTree()
analysis1 = geofile.getAnalysisByID(1)
geom = analysis1["Geometry"]
```

--------------------------------

### Set X Data for Function Points

Source: https://pygeostudio.readthedocs.io/en/stable/classes/function.html

Helper method to set the X data of the 'Points' attribute. The size of the input must match the actual X data size.

```python
setXData(_values_)
```

--------------------------------

### Show and Select Geometry

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/bfa8c7fba2b97e0ea85889059129510f/create_region.ipynb

Displays all geometries in the study and retrieves a specific geometry by its ID. The selected geometry is then drawn.

```python
geofile.showGeometries()
geometry = geofile.getGeometryByID(1)
geometry.draw()
```

--------------------------------

### showGeometries

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Prints the geometries defined within the GeoStudio file. This method allows users to visualize or inspect the geometric components of the study.

```APIDOC
## showGeometries

### Description
Print the geometries definied within the GeoStudio file
```

--------------------------------

### Save GeoStudio File As New File

Source: https://pygeostudio.readthedocs.io/en/stable/classes/geostudiofile.html

Saves the modified study to a new file with specified compression level. Results are not copied.

```python
geofile.saveAs(_f_out_ , _compresslevel =5_)
```

--------------------------------

### Define Model Function for Optimization

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Defines a function that takes a new logarithm of saturated hydraulic conductivity (log_Ksat) as input, updates the GeoStudio model with this value, runs the simulation, and returns the calculated pore water pressure. This function is designed to be compatible with SciPy's curve_fit.

```python
def run_model(xdata,new_log_Ksat):
  # set the new hydraulic conductivity function
  new_Ksat = 10.**new_log_Ksat
  actual_relK = Kfunction.getYData()
  actual_Ksat = Kfunction.getYData()[0]
  Kfunction.setYData(new_Ksat/actual_Ksat * actual_relK)
  # run the analysis
  geofile.save()
  pgs.run(geofile, analyses_to_solve=[instant_drawdown])
  # return fitted data
  T,PWP = instant_drawdown["Results"].getVariablesVsTime("PoreWaterPressure", locations=[[25,2]])
  return PWP
```

--------------------------------

### Save GeoStudio File Copy

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/a2f6ff994a76d693515501f4bb528742/rapid_drawdown_basic.ipynb

Saves a copy of the original GeoStudio file to allow for modifications during the calibration process. This ensures the original file remains unchanged.

```python
import PyGeoStudio as pgs
import numpy as np

src_file = "../GeoStudio_files/Rapid drawdown.gsz"
copy_file = "Rapid drawdown_tmp.gsz"
geofile_src = pgs.GeoStudioFile(src_file)
geofile_src.saveAs(copy_file)
```

--------------------------------

### List Available Reinforcements

Source: https://pygeostudio.readthedocs.io/en/stable/_downloads/8e4e1f4b9953e0fa89823a933fd5f702/change_anchors_properties.ipynb

Displays a list of all reinforcements defined in the GeoStudio study, including their ID, name, and type. This is useful for identifying which reinforcements are available for manipulation.

```python
geofile.showReinforcements()
```

--------------------------------

### Retrieve Analysis and Timestepping Information

Source: https://pygeostudio.readthedocs.io/en/stable/gallery_examples/basics/change_timestepping.html

Retrieves a specific analysis by its ID and accesses its timestepping configuration.

```python
geofile.showAnalysisTree()
analysis = geofile.getAnalysisByID(4)
timestepping = analysis["TimeIncrements"]
```

--------------------------------

### Access and Modify Reinforcement Properties

Source: https://pygeostudio.readthedocs.io/en/stable/classes/reinforcement.html

Shows how to retrieve and update specific properties of a Reinforcement object. Properties are accessed using dictionary-like syntax with the property name.

```python
f = reinf["PulloutResistance"] #store the pullout resistance in a variable
reinf["PulloutResistance"] = 350 #change pullout resistance in-place
```