Metadata-Version: 2.4
Name: pyemsol
Version: 2026.9.1+cm
Summary: A Python wrapper of EMSolution
Home-page: https://github.com/EMSolution-SSIL/pyemsol
Author: Science Solutions International Laboratory, Inc.
License: Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: ~=3.11
Description-Content-Type: text/markdown
License-File: EULA.txt
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# **pyemsol** : Python dynamic module of EMSolution
```note
note:  
pyemsol.pyd works in Python 3.11 environments.
```

# Overview
**pyemsol** is a Python module that provides a dynamic link library for EMSolution, allowing users to interact with the EMSolution software directly from Python scripts. This module is designed to facilitate the integration of EMSolution functionalities into Python applications, enabling users to perform complex simulations and analyses with ease.

# Features
- **Dynamic Linking**: The module is built as a dynamic link library, allowing for efficient memory usage and faster execution.
- **Cross-Platform Compatibility**: The module is available for both Windows and Linux platforms, ensuring broad usability.
- **Easy Integration**: Users can easily integrate EMSolution functionalities into their Python applications without needing extensive knowledge of the underlying C++ code.
- **Comprehensive Documentation**: The module comes with detailed documentation, making it easy for users to understand how to use the various functions and features.

# Installation and Usage Guide for pyemsol
This guide provides instructions on how to install and use the **pyemsol** module, a Python dynamic link library for EMSolution.

## Requirements
- **Python 3.11**
- **pip** for package installation
- **Conda** for managing additional dependencies

## Installation
To install this package, you can use `pip`:

```sh
pip install pyemsol-2025.05.1-cp311-cp311-win_amd64.whl # Install the wheel file using pip on Windows
```
```sh
pip install pyemsol-2025.05.1-cp311-cp311-manylinux1_x86_64.whl # Install the wheel file using pip on Linux (RedHat family)
```

### Additional Dependencies
Please note that this package requires additional dependencies that are available via Conda. After installing the package, make sure to install the following Conda packages:

```sh
conda install -c conda-forge pybind11 pybind11-abi
conda install -c conda-forge mkl mkl-include
```

## How to use after installation
The **pyemsol** module can be imported in any Python script as follows:

```python
import pyemsol
pyemsol.version()  # This will print the version of the pyemsol module
```
To check what functions can be used:
```python
import pyemsol
print(dir(pyemsol))
```
The functions are written in `__init__.py` in the installed folder with `pyemsol.pyd`.

The output of the print function should look like this:

['__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', 'finalize', 'initialize', 'pyemsol', 'run', 'set_message_callback', 'solve', 'update_Time_Function', 'update_properties_in_design_domain', 'update_properties_to_elements', 'version', 'terminate']

## How to set up after installation on Linux

`pyemsol.so` is a dynamic link library, so you need to set the library path related to `pyemsol`.
The related libraries are stored in the installed directory by `pip install`.

If you need `LD_LIBRARY_PATH` to be set automatically whenever you open a terminal:
Add the export command to your ~/.bashrc or ~/.profile (depending on your shell and preferences):

```bash
echo 'export LD_LIBRARY_PATH=/path/to/pyemsol/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
```

```note
note:  
On Windows, this setup is not needed.
```

# Example Usage
Here is a simple example of how to use the **pyemsol** module in a Python script:

## 1. Running as in the General Method

You can execute simulations in the same way as before by using `pyemsol.run`.

The `pyemsol.run` function is almost equivalent to running the batch version EMSolBatch.exe on Windows, and can be used as follows:

```python
import pyemsol
import os
import json

# Directory containing input.json
current_directory = os.getcwd()
# or specify directly:
# Name of the input JSON file
input_json = "input.json"
with open(input_json, 'r') as file:
    json_data = json.load(file)

# Execute. The return value is output.json
output = pyemsol.run(json_data, current_directory)
```

## 2. Parameter Survey

### Updating Time Functions
Updating time functions can be used, for example, in motor analysis when calculating current-torque characteristics. Time functions are specified in ``18_Time_Function(18)``.

Here, an example using ``AC(18.3)`` is shown.

Assume that the time function ``18_Time_Function(18)`` shown below is connected to the electric circuit ``NETWORK(17.9)``.

```json
{
    "18_Time_Function": [
        {
            "TIME_ID": 1,
            "OPTION": 2,
            "AMPLITUDE": 1.0,
            "TCYCLE": 0.02,
            "PHASE": 0.0
        },
        {
            "TIME_ID": 2,
            "OPTION": 2,
            "AMPLITUDE": 1.0,
            "TCYCLE": 0.02,
            "PHASE": -120.0
        },
        {
            "TIME_ID": 3,
            "OPTION": 2,
            "AMPLITUDE": 1.0,
            "TCYCLE": 0.02,
            "PHASE": -240.0
        }
    ]
}
```

If you want to change the current amplitude, you can use `pyemsol.update_Time_Function` to update the amplitude of the time function as follows:

```python
import pyemsol

# Directory containing input.json
current_directory = os.getcwd()
# or specify directly:
# Name of the input JSON file
input_json = "parameter_servey.json"
with open(input_json, 'r') as file:
    json_data = json.load(file)

# Initialize EMSolution
pyemsol.initialize()

# Define the parameter range (e.g., current values from 1 to 10)
current_values = [i for i in range(1, 11)]
results = []

# Update time functions
# Assume three-phase AC is defined as TIME_ID=1,2,3.
for current in current_values:
    # Change the amplitude of the AC time function
    time_function = json_data["18_Time_Function"]
    for function in time_function:
        if function["TIME_ID"] == 1 or function["TIME_ID"] == 2 or function["TIME_ID"] == 3:
            function["AMPLITUDE"] = current

    # Update calculation conditions
    pyemsol.update_Time_Function(json_data)
    # Execute calculation and obtain results
    output = pyemsol.solve()
    # Process calculation results

# End calculation
pyemsol.finalize()
```

```note
note:   
For the argument of pyemsol.update_Time_Function, specify the data from input.json. The JSON data must contain the 18_Time_Function key.

To update the current phase, change the PHASE value.
```

Other examples are described in the 
 [EMSolutionDocs](https://emsolution-ssil.github.io/EMSolutionDocs/index.html).
