Using the command-line interface

The Ashes command-line interface (ashes-cli) allows you to run batch simulations from the command-line or from a Python script. This section will explain how to run a simple batch and then an example where ashes-cli is used in an optimization loop is shown. Further, options for adding/removing blades is explained.


1 Running a batch

To run a batch, two files are needed: (1) An Ashes project file (.ash) containing your model, and (2) a batch CSV file defining your batch. The project file can be created by saving your model in Ashes to file, and the CSV file can be exported from the batch manager, see CSV file. 

The command to run the batch is
1
ashes-cli -runbatch -projectfile *pathtoprojectfile* -batchcsvfile *pathtocsvfile*

The ashes-cli is located in the Program Files folder (unless you installed it somewhere else). To run ashes-cli, you have to go to the installation folder first. Here is an example:

1
2
cd C:\Program Files\Ashes 3.20
ashes-cli -runbatch -projectfile "C:\Users\Per Ivar\Documents\Ashes 3.20\Onshore.ash" -batchcsvfile "C:\Users\Per Ivar\Documents\Ashes 3.20\Batch.csv"

The results from this batch will be saved in the folder C:\Users\Per Ivar\Documents\Ashes 3.20\Batch runs\Batch (replace with your own username).


Note: the cli works by taking the base model and modifying its parameters according to the value of each parameter specified in the csv file. If a value in the base model is the same as the csv file, it will not be modified.
  
This poses the following issue: imagine you create and save your base model with an textfile based tubular tower, named Tower.txt, and you add the tubular tower input file parameter to the csv file. When you run the cli, it will take the base model, see that the file that was used to create the base model is the same as the one in the csv file and therefore not update the model. If you then modify the text file without changing its name, the cli, will still not update the tubular tower since the input file parameter is the same.
If you want the tower to change when the cli is run, you need to change the name of the text file (and update the csv file accordingly).



2  Running ashes-cli from a Python script

The ashes-cli can easily be run from a Python script, using the subprocess module. Here is a Python script example for running a batch:
1
2
3
4
5
6
7
8
9
import subprocess

# Change these paths to use your own username 
ashesExePath = "C:/Program Files/Ashes 3.20/ashes-cli.exe"
projectFilePath = "C:/Users/Per Ivar/Documents/Ashes 3.20/onshore.ash"
csvFilePath = "C:/Users/Per Ivar/Documents/Ashes 3.20/Batch.csv"

result = subprocess.run([ashesExePath, "-runbatch", "-projectfile", projectFilePath, "-batchcsvfile", csvFilePath])
print ("Return code: {}".format(result.returncode))


3  Examples

This section explains how to add/modify any parameter from the Ashes model and run a simulation from the cli with the modified parameter (note that this is a suggestion on how to proceed, but other options are possible). The following subsections are examples of cli scripts that can be used.

In order to modify a parameter of an Ashes model and run a simulation with the cli
  1. Save the default model (also called 'base model') to file (you will then have a .ash file). You can either use a model you have created yourself or open a default template.
    This is the Ashes project file that will have to be called from the cli.

  2. Open the batch manager





  3. In the batch manager, create a new default batch



    You will have to enter a name for your batch.
    If you have an existing batch that has been save to csv, you can also use that by selecting Import a batch

  4. In the newly created batch, click Parameters to open the display parameter window




  5. Locate and add the parameter to your batch. In the example below, the parameter Mean sea level is added



    When you close the Display parameter window, the new parameter will have been added to the batch.
    Note that the value of the parameter in the batch once it is added will correspond to the value of the parameter of the model that was open when creating the batch. This can be changed once the parameter is added to the batch

  6. Export the batch to a CSV file. This is the batch CSV file that will have to be called from the cli.



    Note that this file also defines what kind of simulation will be run (for example, a time simulation, an eigenfrequency analysis or a Cp curve) and the duration of the time simulation, if applicable.


  7. That file can now be modified from the script that will run the simulation. The following snippet is an example of how to modify the csv file:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    import pandas as pd

csvFilePath = 'Batch.csv'
newCsvFilePath = 'NewBatch.csv'
NewMSL = 5

df = pd.read_csv(csvFilePath, sep=';', dtype="string", header=None)
df.iat[4,8] = str(NewMSL)
df.to_csv(newCsvFilePath, sep=';', index=None, header=None)



  8. Once the CSV file has been modified by the script, the simulation can be run in the script as well, as illustrated in the snippet below:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    Here goes thimport pandas as pd
import subprocess

ashesExePath = 'C:/Program Files/Ashes 3.21/ashes-cli.exe'
projectFilePath = 'MyModel.ash'

csvFilePath = 'Batch.csv'
newCsvFilePath = 'NewBatch.csv'
NewMSL = 5

df = pd.read_csv(csvFilePath, sep=';', dtype="string", header=None)
df.iat[4,8] = str(NewMSL)
df.to_csv(newCsvFilePath, sep=';', index=None, header=None)

subprocess.run([ashesExePath, "-runbatch", "-projectfile", projectFilePath, "-batchcsvfile", newCsvFilePath])e code






3.1 Optimization loop in a Python script

In this example we will modify the tower thickness in the input CSV file, and gradually increase it until the maximum normal stress is lower than the yield stress of steel.

This example uses two files: Onshore.ash, the project file; and Batch.csv, the batch file. Both of these files are found in the Examples/Ashes-cli examples folder, which you can open by going to Help | Open examples folder. You also find the Python script itself there, called ashesCliOptimizationLoopExample.py.

This example uses the pandas module. You might have to install it by running pip install pandas in a command line.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
import os
import subprocess
import shutil
import pandas as pd

# Change these paths 
ashesExePath = "C:/Program Files/Ashes 3.19/ashes-cli.exe"
projectFilePath = "C:/Users/Per Ivar/Documents/Ashes 3.20/onshore.ash"
originalCsvFilePath = "C:/Users/Per Ivar/Documents/Ashes 3.20/Batch.csv"
batchResultsDir = "C:/Users/Per Ivar/Documents/Ashes 3.20/Batch runs"

initialThickness = 0.001 # 1 millimeter as initial tower thickness
thickness = initialThickness
deltaThickness = 0.0005     # Step 0.5 millimeter every iteration
yieldStrength = 355.0/1.25  # Yield strength of steel in MPa divided by safety factor
i = 1

while True:
    # Make a copy of the csv file that we will modify
    outDir = os.path.dirname(originalCsvFilePath)
    batchName = "Optimization batch, t={}".format(thickness)
    modifiedCsvFilePath = outDir + "/" + batchName + ".csv"
    shutil.copyfile(originalCsvFilePath, modifiedCsvFilePath)
    # Read csv using pandas
    csv = pd.read_csv(modifiedCsvFilePath, sep=';', dtype="string", header=None)
    csv = csv.fillna("")
    # Modify the tower thickness value and save file
    csv.iat[4,10] = str(thickness)
    csv.to_csv(modifiedCsvFilePath, sep=';', index=None, header=None)
    # Run ashes-cli
    result = subprocess.run([ashesExePath, "-runbatch", "-projectfile", projectFilePath, "-batchcsvfile", modifiedCsvFilePath])
    if result.returncode != 0:
        print("Return code was {}, check console output for more information.".format(result.returncode))
        break   # Something went wrong, check console output.
    
    sensorFilePath = batchResultsDir + "/" + batchName + "/Load case set 1/Load case 1/Time simulation/Sensor Beam element [Element 1 Tubular tower].txt"
    sensorData = pd.read_table(sensorFilePath, skiprows=11)
    # Get last value of the normal stress column
    maxNormalStress = float(sensorData.iloc[-1]["Max normal stress [M Pa]"])
    if maxNormalStress <= yieldStrength:
        print("Final thickness of {} m was found, giving max normal stress of {} MPa.".format(thickness,maxNormalStress))
        break
    else:
        print("Thickness of {} was not sufficient, giving max normal stress of {}. Continuing.".format(thickness,maxNormalStress))
    
    thickness = initialThickness + i*deltaThickness
    i += 1


3.2 Power curve generation for random turbulent wind speeds

This example can be found in \Documents\Ashes X.yy\Ashes-cli examples\ashesCliWindSpeedCurve.p y.
It can be run with the default onshore model which has to be called onshore.ash and located in the Ashes X.yy folder.
It uses the csv file WindSpeed_curve.csv , located in the same folder.

The script contains several absolute paths. Make sure the pats are changed before running the script.

See the comments in the script for a detailed explanation of how the script works.

3.3  Adding and removing blades

3.3.1 Adding a blade

Blades can be added to the database using the -addblade argument. Additionally, you must specify the following arguments:
ArgumentDescription
bladenameThe name of the blade that is to be added to the database. It is recommended to not use whitespaces in the name.
bladeshapefileThe path to the Blade shape file.
bladestructurefileThe path to the Blade structure file.

Here is an example:

1
ashes-cli -addblade -bladeshapefile="C:\Users\User\Documents\Ashes 3.21\NREL 5-MW blade shape.txt" -bladestructurefile="C:\Users\User\Documents\Ashes 3.21\NREL 5-MW blade structure.txt" -bladename=myblade


If the command is successful, the blade has been added to the Ashes database. If you want to verify that the blade is correct, you can start Ashes and open the Blade database .

3.3.2  Removing a blade

Removing a blade from the database is done with the -removeblade argument. In addition, you must specify the blade name with the -bladename argument.

1
ashes-cli -removeblade -bladename=myblade


3.4 Run an eigenfrequency analysis

Currently, running an eigenfrequency analysis in the cli has to be done by adding the parameter Solve eigenmodes (In Analysis->Misc) and setting it to True.


Note: this will solve the eigenmodes in addition to running the time simulation. IF the results from the time simulations are not relevant, you can set the simulation time to an arbitrarily small number and/or remove the sensors from the model