Loads

The following sections identify load settings and discuss load limitation guidelines.

Load Settings

All functionality on the Setting dialog box Load Cases and Load Combinations tabs can be accessed by the API.

The following properties are available from the corresponding LoadCase BuiltInParameter:

Table 60 Load Case Properties and Parameters

Property	BuiltInParameter
Case Number	LOAD_CASE _NUMBER
Nature	LOAD_CASE_NATURE
Category	LOAD_CASE_CATEGORY

The LOAD_CASE_CATEGORY parameter returns an ElementId. The following table identifies the mapping between Category and ElementId Value.

Table 61: Load Case Category

Load Case Category	BuiltInCategory
Dead Loads	OST_LoadCasesDead
Live Loads	OST_LoadCasesLive
Wind Loads	OST_LoadCasesWind
Snow Loads	OST_LoadCasesSnow
Roof Live Loads	OST_LoadCasesRoofLive
Accidental Loads	OST_LoadCasesAccidental
Temperature Loads	OST_LoadCasesTemperature
Seismic Loads	OST_LoadCasesSeismic

Creating loads and load combinations

The following classes have one or more static Create() methods to create corresponding classes:

LoadUsage
LoadNature
LoadCase
LoadCombination.
PointLoad
LineLoad
AreaLoad

Because they are all Element subclasses, they can be deleted using Document.Delete().

Load Combinations are created via the static method LoadCombination.Create() which has two overloads. The first takes only a reference to the document in which you want to create the load combination and the string for the name of the new combination. The second takes these arguments plus the LoadCombinationType and LoadCombinationState. The LoadCombinationType can be either Combination, for a straight load combination, or Envelope, for an envelope of the effects of several load cases or combinations.

The LoadCombinationState can be either Serviceability or Ultimate. Use Serviceability if the load combination represents a service load level on the structure. This is typically used in design or checking of member deflections or other serviceability criteria such as Allowable Stress Design methodologies. Use Ultimate if the load combination represents an ultimate load state or a factored load state on the structure typically used in Load Resistance Factor Design methodologies.

After a LoadCombination is created, you will need to fill it with LoadComponents which comprise the load combination and their factors. LoadComponents are added to the LoadCombination by calling LoadCombination.SetComponents() with a list of the components as shown in this code snippet below.

Note: Make sure that the list of components does not refer to itself.

The following example demonstrates how to create a Load Combination and how to find or create Load Cases and Load Natures to use to set the components of the Load Combination.

Code Region: Creating a new LoadCombination

LoadCombination CreateLoadCombinationLoadCaseLoadUsageLoadNatureAndLoadComponent(Document document)
{
    // Create a new load combination
    LoadCombination loadCombination = LoadCombination.Create(document, "DL1 + RAIN1", LoadCombinationType.Combination, LoadCombinationState.Ultimate);
    if (loadCombination == null)
        throw new Exception("Create new load combination failed.");

    // Get all existing LoadCase
    FilteredElementCollector collector = new FilteredElementCollector(document);
    ICollection<Element> collection = collector.OfClass(typeof(LoadCase)).ToElements();

    // Find LoadCase "DL1"
    LoadCase case1 = null;
    foreach (Element e in collection)
    {
        LoadCase loadCase = e as LoadCase;
        if (loadCase.Name == "DL1")
        {
            case1 = loadCase;
            break;
        }
    }

    // Get all existing LoadNature
    collector = new FilteredElementCollector(document);
    collection = collector.OfClass(typeof(LoadNature)).ToElements();

    // Find LoadNature "Dead"
    LoadNature nature1 = null;
    foreach (Element e in collection)
    {
        LoadNature loadNature = e as LoadNature;
        if (loadNature.Name == "Dead")
        {
            nature1 = loadNature;
            break;
        }
    }

    // Create LoadNature "Dead" if not exist
    if (nature1 == null)
        nature1 = LoadNature.Create(document, "Dead");

    // Create LoadCase "DL1" if not exist
    if (case1 == null)
        case1 = LoadCase.Create(document, "DL1", nature1.Id, LoadCaseCategory.Dead);

    // Create LoadNature "Rain"
    LoadNature nature2 = LoadNature.Create(document, "Rain");
    if (nature2 == null)
        throw new Exception("Create new load nature failed.");

    // Create LoadCase "RAIN1"
    LoadCase case2 = LoadCase.Create(document, "RAIN1", nature2.Id, LoadCaseCategory.Snow);
    if (case1 == null || case2 == null)
        throw new Exception("Create new load case failed.");

    // Create LoadComponents - they consist of LoadCases or nested LoadCombination and Factors
    List<LoadComponent> components = new List<LoadComponent>();
    components.Add(new LoadComponent(case1.Id, 2.0));
    components.Add(new LoadComponent(case2.Id, 1.5));

    // Add components to combination
    loadCombination.SetComponents(components);

    // Create LoadUsages
    LoadUsage usage1 = LoadUsage.Create(document, "Frequent");
    LoadUsage usage2 = LoadUsage.Create(document, "Rare");

    if (usage1 == null || usage2 == null)
        throw new Exception("Create new load usage failed.");

    // Add load usages to combination
    loadCombination.SetUsageIds(new List<ElementId>() {usage1.Id, usage2.Id});

    // Give the user some information
    TaskDialog.Show("Revit", string.Format("Load Combination ID='{0}' created successfully.", loadCombination.Id.IntegerValue));

    return loadCombination;
}

You may also modify the cases, components, natures, etc by using LoadCombination.GetComponents(), making modifications and then calling LoadCombination.SetComponents() again. LoadUsages for the LoadCombination can be modified by calling LoadCombination.GetUsageIds() to get the list of LoadUsage Ids, modifying the list, and calling SetUsageIds() again. The following code sample demonstrates how to modify an existing LoadCombination.

Code Region: Modify a load combination

void ModifyLoadCombinationLoadCaseLoadUsageLoadNatureAndLoadComponent(Document document, LoadCombination loadCombination)
{
    // Change name of LoadCombination
    loadCombination.Name = "DL2 + RAIN1";

    // Get any LoadCase from combination
    // Combination can have assigned LoadCase or other (nested) LoadCombination so we need to filter out any LoadCombination
    LoadCase case1 = null;
    IList<ElementId> caseAndCombinationIds = loadCombination.GetCaseAndCombinationIds();
    foreach (ElementId id in caseAndCombinationIds)
    {
        Element element = document.GetElement(id);
        if (element is LoadCase)
        {
            case1 = (LoadCase)element;
            break;
        }
        else if (element is LoadCombination)
        {
            continue;
        }
    }

    if (case1 == null)
        throw new Exception("Can't get LoadCase.");

    // Change case name and number
    case1.Name = "DL2";
    if (LoadCase.IsNumberUnique(document, 3))
    {
        case1.Number = 3;
    }

    // Create load nature
    LoadNature liveNature = LoadNature.Create(document, "Dead nature");
    if (liveNature == null)
        throw new Exception("Create new load nature failed.");

    // Change nature category and ID for case
    case1.SubcategoryId = new ElementId(BuiltInCategory.OST_LoadCasesDead);
    case1.NatureId = liveNature.Id;

    //Change factor for case1
    IList<LoadComponent> components = loadCombination.GetComponents();
    foreach (LoadComponent loadComponent in components)
    {
        if (loadComponent.LoadCaseOrCombinationId == case1.Id)
        {
            loadComponent.Factor = 3.0;
        }
    }

    loadCombination.SetComponents(components);

    // Remove one usage from combination
    IList<ElementId> usages = loadCombination.GetUsageIds();
    usages.RemoveAt(0);
    loadCombination.SetUsageIds(usages);

    // Give the user some information
    TaskDialog.Show("Revit", string.Format("Load Combination ID='{0}' modified successfully.", loadCombination.Id.IntegerValue));
}

There is no Duplicate() method in the LoadCase and LoadNature classes. To implement this functionality, you must first create a new LoadCase (or LoadNature) object, and then copy the corresponding properties and parameters from an existing LoadCase (or LoadNature).

The following is a minimum sample code to demonstrate the creation of a point load in VB.NET:

Code Region: New PointLoad


'Define the location at which the PointLoad is applied. 
Dim point As New XYZ(0, 0, 4)
'Define the 3d force. 
Dim force As New XYZ(0, 0, -1)
'Define the 3d moment. 
Dim moment As New XYZ(0, 0, 0)

Dim pointLoad As PointLoad = pointLoad.Create(document, point, force, moment, Nothing, Nothing)