Tutorial 1 - Using the materials library

This tutorial demonstrates how to manage material properties for power cable modeling using the package LineCableModels.jl. Accurate knowledge of electromagnetic properties is essential for reliable cable design and analysis.

Beyond showcasing the API, this guide serves as a practical reference by providing standard property values from recognized industry sources like CIGRE TB-531 [8] and IEC 60287 [9] that can be stored and consistently applied across multiple design iterations and simulation studies.

Tutorial outline

• Getting started
• Adding new materials
• Removing materials
• Saving the materials library to JSON
• Retrieving materials for use
• Conclusion

Getting started

Load the package:

using LineCableModels

The MaterialsLibrary is a container for storing electromagnetic properties of different materials used in power cables. By default, it initializes with several common materials with their standard properties.

Initialize a MaterialsLibrary with default values:

materials_db = MaterialsLibrary()

MaterialsLibrary with 9 materials:
├─ pe
├─ polyacrylate
├─ semicon1
├─ copper
└─ xlpe
└─ ... and 4 more

Inspect the contents of the materials library:

df_initial = list_materialslibrary(materials_db)

The function list_materialslibrary returns a DataFrame with all materials and their properties, namely: electrical resistivity, relative permittivity, relative permeability, reference temperature, and temperature coefficient.

Adding new materials

It might be useful to add other conductor materials with corrected properties based on recognized standards [8] [9].

copper_corrected = Material(1.835e-8, 1.0, 0.999994, 20.0, 0.00393) # Copper with corrected resistivity from IEC 60287-3-2
store_materialslibrary!(materials_db, "copper_corrected", copper_corrected)
aluminum_corrected = Material(3.03e-8, 1.0, 0.999994, 20.0, 0.00403) # Aluminum with corrected resistivity from IEC 60287-3-2
store_materialslibrary!(materials_db, "aluminum_corrected", aluminum_corrected)
lead = Material(21.4e-8, 1.0, 1.0, 20.0, 0.00400) # Lead or lead alloy
store_materialslibrary!(materials_db, "lead", lead)
steel = Material(13.8e-8, 1.0, 300.0, 20.0, 0.00450) # Steel
store_materialslibrary!(materials_db, "steel", steel)
bronze = Material(3.5e-8, 1.0, 1.0, 20.0, 0.00300) # Bronze
store_materialslibrary!(materials_db, "bronze", bronze)
stainless_steel = Material(70.0e-8, 1.0, 500.0, 20.0, 0.0) # Stainless steel
store_materialslibrary!(materials_db, "stainless_steel", stainless_steel)

MaterialsLibrary with 15 materials:
├─ pe
├─ aluminum_corrected
├─ bronze
├─ copper
└─ pec
└─ ... and 10 more

When modeling cables for EMT analysis, one might be concerned with the impact of insulators and semiconductive layers on cable constants. Common insulation materials and semicons with different dielectric properties are reported in Table 6 of [8]. Let us include some of these materials in the MaterialsLibrary to help our future selves.

epr = Material(1e15, 3.0, 1.0, 20.0, 0.005) # EPR (ethylene propylene rubber)
store_materialslibrary!(materials_db, "epr", epr)
pvc = Material(1e15, 8.0, 1.0, 20.0, 0.1) # PVC (polyvinyl chloride)
store_materialslibrary!(materials_db, "pvc", pvc)
laminated_paper = Material(1e15, 2.8, 1.0, 20.0, 0.0) # Laminated paper propylene
store_materialslibrary!(materials_db, "laminated_paper", laminated_paper)
carbon_pe = Material(0.06, 1e3, 1.0, 20.0, 0.0) # Carbon-polyethylene compound (semicon)
store_materialslibrary!(materials_db, "carbon_pe", carbon_pe)
conductive_paper = Material(18.5, 8.6, 1.0, 20.0, 0.0) # Conductive paper layer (semicon)
store_materialslibrary!(materials_db, "conductive_paper", conductive_paper)

MaterialsLibrary with 20 materials:
├─ pe
├─ aluminum_corrected
├─ bronze
├─ copper
└─ pec
└─ ... and 15 more

Removing materials

Add a duplicate material by accident:

store_materialslibrary!(materials_db, "epr_dupe", epr)

MaterialsLibrary with 21 materials:
├─ pe
├─ aluminum_corrected
├─ bronze
├─ copper
└─ pec
└─ ... and 16 more

And now remove it using the remove_materialslibrary! function:

remove_materialslibrary!(materials_db, "epr_dupe")

MaterialsLibrary with 20 materials:
├─ pe
├─ aluminum_corrected
├─ bronze
├─ copper
└─ pec
└─ ... and 15 more

Examine the updated library after removing the duplicate:

println("Material properties compiled from CIGRE TB-531 and IEC 60287:")
df_final = list_materialslibrary(materials_db)

Saving the materials library to JSON

output_file = joinpath(@__DIR__, "materials_library.json")
save_materialslibrary(
	materials_db,
	file_name = output_file,
);

Materials library saved to: materials_library.json

Retrieving materials for use

Initialize a new MaterialsLibrary and load from the JSON file:

materials_from_json = MaterialsLibrary()
load_materialslibrary!(
	materials_from_json,
	file_name = output_file,
)

MaterialsLibrary with 20 materials:
├─ pe
├─ aluminum_corrected
├─ bronze
├─ copper
└─ pec
└─ ... and 15 more

Retrieve a material and display the object:

copper = get_material(materials_from_json, "copper_corrected")

Material with properties: [rho=1.835e-8, eps_r=1.0, mu_r=1.0, T0=20.0, alpha=0.00393]

Access the material properties:

println("\nRetrieved copper_corrected material properties:")
println("Resistivity: $(copper.rho) Ω·m")
println("Relative permittivity: $(copper.eps_r)")
println("Relative permeability: $(copper.mu_r)")
println("Reference temperature: $(copper.T0) °C")
println("Temperature coefficient: $(copper.alpha) 1/°C")

Retrieved copper_corrected material properties:
Resistivity: 1.835e-8 Ω·m
Relative permittivity: 1
Relative permeability: 0.999994
Reference temperature: 20 °C
Temperature coefficient: 0.00393 1/°C

Conclusion

This tutorial has demonstrated how to:

1. Initialize a MaterialsLibrary with default Material objects.
2. Add new materials with specific properties.
3. Remove duplicate materials.
4. Save the library to a file for future use.
5. Retrieve materials for use in cable modeling.

The MaterialsLibrary provides a flexible and traceable framework to manage material properties for accurate power cable modeling. Custom Material objects can be defined and used to match specific manufacturer data or standards requirements.

🏠 Back to Tutorials