The s3d_model object

note

For modelling functions, see model.

Throughout the rest of the documentation, the SkyCiv Structural 3D model may be referred to as the s3d_model object. The s3d_model object is a JSON object that describes the structural model. This data contains all the necessary information to model and analyze the structure. We also have a S3D Model Schema in JSON format to help you map the input.

A convenient way to examine what an existing model looks like as JSON, is to open the file in SkyCiv Structural 3D and click:

File → Export → SkyCiv File (JSON for API)

This will download the JSON object of the current model, and may help as a guide to building the s3d_model object. Similarly, a JSON file can be tested directly through the UI by clicking:

File → Import → SkyCiv File (JSON for API)

tip

By exporting from the S3D platform, the sections object may look complicated. If you would like to keep the s3d_model more compact, it can be substituted to use the load_section property as seen in sections. You can get all available sections by inspecting the Section Builder Platform or via the S3D.SB.getLibraryTree function.

Try s3d_model

`s3d_model`#

The s3d_model property is comprised of the following properties:

settings
nodes
members
plates
meshed_plates
sections
materials
supports
settlements
point_loads
moments
distributed_loads
pressures
area_loads
self_weight
load_combinations

`settings`#

Key	Type	Accepts	Description	Default
`units`	`string` or `object`	`imperial`, `metric`, `{...}`	Provide `imperial` or `metric` for default units. See Units to set specific units.	Varies per design standard.
`precision`	`string`	`fixed`, `exponential`	Number format style.	`fixed`
`precision_values`	`integer`	Between `1` and `15`	Number of precision.
`evaluation_points`	`integer`	Between `3` and `50`	number of evaluation points for each member. Higher evaluation points will (slightly) increase the accuracy but will increase the time taken to solve.
`vertical_axis`	`string`	`Y`, `Z`	The axis which defines the vertical direction of the model.	`Y`
`solver_timeout`	`integer`	Any number. in seconds	How long until the solver timeouts and returns "Solve Failed" if the model is not solving for an unknown reason.
`accurate_buckling_shape`	`boolean`	`true`, `false`	If enabled when a buckling analysis is performed then the accuracy of the displayed buckled shape will be improved however it will take longer to solve. The buckling factors and values should be very similar to when this option is not enabled.
`buckling_johnson`	`boolean`	`true`, `false`	Use the parabolic or J.B. Johnson formula which is a more conservative approach for buckling of intermediate-length columns. The Johnson formula will be applied for critical stresses above half the yield strength.
`non_linear_tolerance`	`string`	E.g. `1` = 1%	Non-Linear Analysis will continue to solve until this tolerance (relative error percentage) is met. A smaller number takes longer for convergence.
`non_linear_theory`	`string`	`small`, `finite`		`small`
`auto_stabilize_model`	`boolean`	`true`, `false`	Enable this if your model has stability issues, especially if the non-linear analysis will not converge. The solver will attempt to automatically stabilize nodes that are not restrained. It's is recommended to leave this disabled unless you are having issues with stability.
`member_offsets_axis`	`string`	`global`, `local`	Specifies if member offsets should be relative to the local or global axis system.	`local`
`dynamic_modes`	`integer`	Any positive integer	The maximum number of modes that the dynamic frequency analysis will return.	5
`dynamic_frequency_area_reduction_factor`	`float`	Any positive number	This factor reduces the area of these members to reduce their axial stiffness since they'll usually be used for bracing.	1

`units`#

Key	Type	Accepts	Description
`length`	`string`	`ft` `in` `mm` `m`	Length for defining elements.
`section_length`	`string`	`in`, `mm`	Length for defining section properties.
`material_strength`	`string`	`ksi`, `psi`, `mpa`
`density`	`string`	`lb/ft3`, `kg/m3`
`force`	`string`	`kip`, `lb`, `kn`, `n`, `kg`
`moment`	`string`	`kip-ft`, `lb-ft`, `lb-in`, `kn-m`, `n-m`, `kg-m`
`pressure`	`string`	`ksi`, `ksf`, `psi`, `psf`, `kpa`, `mpa`, `pa`
`mass`	`string`	`kip`, `lb`, `kg`
`translation`	`string`	`mm`, `in`
`stress`	`string`	`ksi`, `psi`, `mpa`, `kpa`

important

Unit systems can not be mixed between Imperial/Metric.

Sample code for the `settings` object#

Option 1 - Partially specify
Option 2 - Entirely specified

simple-settings.json

{
    "settings": {
        "units": "imperial", // Will load default imperial units
        "vertical_axis": "Z" // Only change one setting
    }
}

Default units#

Using a value of imperial or metric for the units property will set the units to the following.

Imperial
Metric

default-imperial-units.json

{
    "settings": {
        "units": {
            "length": "ft",
            "section_length": "in",
            "material_strength": "ksi",
            "density": "lb/ft3",
            "force": "kip",
            "moment": "kip-ft",
            "pressure": "ksf",
            "mass": "kip",
            "translation": "in",
            "stress": "ksi"
        }
    }
}

`nodes`#

Each node is defined by an object. The node key is the ID of that node in the structure.

The x, y, and z properties represent the coordinates in the global axes, respectively.

Key	Type	Description
`x`	`float`	The x coordinate of the node
`y`	`float`	The y coordinate of the node
`z`	`float`	The z coordinate of the node

note

The coordinates must be entered in the units defined by the length property of the units object.

Sample code for the `nodes` object#

The following JSON snippet describes 2 nodes, with IDs 1 & 2.

Node 1 lies at the origin, Node 2 lies a distance of 1 (in the relevant units) from the origin, along the x-axis.

nodes-sample.json

{
    "nodes": {
        "1": {
            "x": 0,
            "y": 0,
            "z": 0
        },
        "2": {
            "x": 1,
            "y": 0,
            "z": 0
        }
    }
}

`members`#

Similar to nodes, each member is defined by an object, and the object key is the ID of that member.

Members are defined by two nodes, the section, rotation angle, and fixity of the member at each node. Other optional properties may be specified.

Key	Type	Accepts	Description	Default
`type`	`string` (optional)	`normal`, `normal_continuous`, `cable`	If `cable` is specified: `rotation_angle` defaults to `0` `fixity_A` and `fixity_B` default to `FFFRRR` All offset properties default to `0`.	`normal`
`cable_length`	`float` (optional)	Any non-negative number	Relevant only if `type` = `cable`, and even in this case, this is optional. A cable length can be specified to account for sagging or pre-tension. Do not set this property if you do not need to account for sagging or pre-tension.
`node_A`	`integer`	Any non-negative number	The start node, identified by the node ID
`node_B`	`integer`	Any non-negative number	The end node, identified by the node ID
`section_id`	`integer`	Any non-negative number	The ID of the section to be applied to the member. Must be positive. `sections` are defined in their own object.
`rotation_angle`	`float` optional	Number between -180 and 180	Rotation of the member about its own axis, in degrees. This is measured from S3D's default local axes position based on node_A and node_B. If local_axis_y or local_axis_z is provided then it will be measured from these local axes rather than S3D's default local axes. This value is ignored for type = cable.
`fixity_A`	`string`		How the member is connected about node A, represented by a restraint code. If "type" property = "cable", this value is ignored.
`fixity_B`	`string`		How the member is connected about node B, represented by a restraint code. If "type" property = "cable", this value is ignored.
`stiffness_A_Ry`	`string`	Number > 0 or a percentage between 0% and 100%.	Spring Stiffness for rotation about the member's local y-axis at node A. Enter the actual stiffness or a percentage like 80%.
`stiffness_A_Rz`	`string`	Number > 0 or a percentage between 0% and 100%.	Spring Stiffness for rotation about the member's local z-axis at node A. Enter the actual stiffness or a percentage like 80%.
`stiffness_B_Ry`	`string`	Number > 0 or a percentage between 0% and 100%.	Spring Stiffness for rotation about the member's local y-axis at node B. Enter the actual stiffness or a percentage like 80%.
`stiffness_B_Rz`	`string`	Number > 0 or a percentage between 0% and 100%.	Spring Stiffness for rotation about the member's local z-axis at node B. Enter the actual stiffness or a percentage like 80%.
`offset_Ax`	`float`	Any number.	The local x distance that the member is offset from its centroid at node A. If "type" property = "cable", this value is ignored.	`0`
`offset_Ay`	`float`	Any number.	The local y distance that the member is offset from its centroid at node A. If "type" property = "cable", this value is ignored.	`0`
`offset_Az`	`float`	Any number.	The local z distance that the member is offset from its centroid at node A. If "type" property = "cable", this value is ignored.	`0`
`offset_Bx`	`float`	Any number.	The local x distance that the member is offset from its centroid at node B. If "type" property = "cable", this value is ignored.	`0`
`offset_By`	`float`	Any number.	The local y distance that the member is offset from its centroid at node B. If "type" property = "cable", this value is ignored.	`0`
`offset_Bz`	`float`	Any number.	The local z distance that the member is offset from its centroid at node B. If "type" property = "cable", this value is ignored.	`0`
`local_axis_y`	`[float]` optional	-	Specify a global axis vector [X, Y, Z] for the direction of the local y-axis of the member (typically the minor axis). If this is provided, there is no need to provide local_axis_z. If this vector is not orthogonal to the local x-axis then it will be used along with the local x-axis to calculate the local z-axis. If rotation_angle property is non-zero then it will be added to this. This value is ignored for type = cable.
`local_axis_z`	`[float]` optional	-	Specify a global axis vector [X, Y, Z] for the direction of the local z-axis of the member (typically the major axis). If this is provided, there is no need to provide local_axis_y. If this vector is not orthogonal to the local x-axis then it will be used along with the local x-axis to calculate the local y-axis. If rotation_angle property is non-zero then it will be added to this. This value is ignored for type = cable.

note

The offsets must be entered in the units defined by the section_length property of the units object.

Sample code for the `members` object#

The following JSON snippet describes 2 members.

The first member spans from node 1 to node 4, is not rotated about its own axis, is fully fixed, and is offset in the local x-direction by the same amount at both ends. It uses the first section in the list of sections.

The second member is a cable, spanning from node 2 to 5, and uses the second section in the list of sections.

members-sample.json

{
    "members": {
        "1": {
            "node_A": 1,
            "node_B": 4,
            "section_id": 1,
            "rotation_angle": 0,
            "fixity_A": "FFFFFF",
            "fixity_B": "FFFFFF",
            "offset_Ax": "101.6",
            "offset_Ay": "0",
            "offset_Az": "0",
            "offset_Bx": "101.6",
            "offset_By": "0",
            "offset_Bz": "0"
        },
        "2": {
            "type": "cable",
            "node_A": 2,
            "node_B": 5,
            "section_id": 2
        }
    }
}

`plates`#

Plates are 2D structural elements. Each plate is defined by an object which is contained within the plates object. Each plate inside the plates object should be identified by a unique positive integer.

Key	Type	Accepts	Description	Default
`nodes`	`[integer]`	An array of normal integers.	The nodes which make up the plate. A minimum of 3 nodes are required to specify a plate.
`thickness`	`float`	A normal number	The thickness of the plate. The units of thickness are defined by the `section_length` property of the `units` object
`material_id`	`integer`	A normal number	The material of the plate. Identified by the material ID defined in the `materials` object.
`rotZ`	`float`		Rotation of the plate about its local Z (normal) axis in degrees.	`0.0`
`type`	`string`	`auto`	This will consider shear deformation when the plate thickness is sufficient.	`auto`
`offset`	`float`		Offset of the plate along its local z-axis
`diaphragm`	`string`	`no`, `rigid`	If the plate is a diaphragm.	`no`
`membrane_thickness`	`float`	`≥0`	The membrane thickness to be used. Takes the value of `thickness` if `null`.	`thickness`
`shear_thickness`	`float`	`≥0`	The shear thickness to be used. Takes the value of `thickness` if `null`.	`thickness`
`bending_thickness`	`float`	`≥0`	The bending thickness to be used. Takes the value of `thickness` if `null`.	`thickness`
`state`	`string`	`stress`, `strain`	Denotes whether the plate is in a state of plane stress or plane strain.	`stress`
`holes`	`[integer]`	An array of node IDs	Used to define holes in the plate.	`null`
`isMeshed`	`boolean`	`true`, `false`	Indicates whether the plate is already meshed. If the plate is meshed, then the elements making up the mesh must be specified in the `meshed_plates` object, and have their `parent_plate` property set to the ID of this plate.	`false`

note

Each plate defined is also known as a parent_plate as it can mesh into smaller plate elements.

Sample code for the `plates` object#

plates-sample.json

{
    "plates": {
        "1": {
            "nodes": [1, 2, 4, 3],
            "thickness": 50,
            "material_id": 1,
            "rotZ": 0,
            "type": "auto",
            "offset": 65.6,
            "diaphragm": "no",
            "membrane_thickness": 48,
            "shear_thickness": 45,
            "bending_thickness": 45,
            "state": "stress",
            "isMeshed": true
        },
        "2": {
            "nodes": [3, 4, 6, 6],
            "thickness": 50,
            "material_id": 1,
            "rotZ": 0,
            "type": "auto",
            "offset": 65.6,
            "state": "stress",
            "isMeshed": true
        }
    }
}

`meshed_plates`#

Meshed Plates are the 2D elements (triangular or quadrilateral) that make up a plate. Every meshed plate has a parent_plate property defining where it originated. Individual plates are defined by an object in the meshed_plates object. The object key is the plate ID, and must be a unique positive integer value.

Key	Type	Description	Default
`node_A`	`integer`	The first node of the meshed plate.
`node_B`	`integer`	The second node of the meshed plate.
`node_C`	`integer`	The third node of the meshed plate.
`node_D`	`integer`	The fourth node of the meshed plate. Set this to `null` (`None` for a Python dictionary) if the meshed plate is triangular.
`parent_plate`	`integer`	The ID of the plate which this meshed plate originated from. Must refer to a plate in the `plates` object.
`rotZ`	`float`	Rotation of this plate about the plate's local z-axis, in degrees.	`0.0`

Sample code for the `meshed_plates` object#

The following JSON snippet shows a triangular plate that originates from plate 1 as defined by the parent_plate property:

meshed_plates-sample.json

{
    "meshed_plates": {
        "1": {
            "node_A": 39,
            "node_B": 51,
            "node_C": 65,
            "node_D": null,
            "parent_plate": 1,
            "rotZ": 166.43391070308
        }
    }
}

`sections`#

Individual sections are stored in the sections object. Each section is defined by an object. The object key is the ID of the section, and should be a unique positive integer.

Sections can be specified in the following ways:

By providing the load_section property which contains the path to the section as seen in the SkyCiv Section Builder.
By providing the load_custom property which contains the name of a custom shape defined in SkyCiv Section Builder.
Using the output from the SkyCiv Section Builder, which includes geometric coordinates of the cross-section shape. Sections specified using this format support design, stress calculation, and can be rendered in S3D.
As custom input: The geometric coordinates of the cross-section shape are not considered, and only the essential section properties (Iz, Iy, J etc.) must be specified. Sections specified using this format do not support design, stress calculation, or rendering in S3D, making them appropriate for analysis, but not design.

note

The section builder format contains all the properties of the custom input format plus the version & aux properties.

load_section
load_custom
SB JSON format
Custom JSON format
Template Section

Using the load_section property.

Key	Type	Description
`load_section`	`[string]`	Provided as an array of 4 strings (see example below). It is the path of the section in the section library, obtained by inspection from within SkyCiv Section Builder or by attaining the library tree via S3D.SB.getLibraryTree
`material_id`	`integer`	The ID of the material that is assigned to the shape of the section. `materials` are defined in their own object.

Sample code for the sections object using the load_section property

sections-sample.json

{
    "sections": {
        "1": {
            "load_section": ["American", "AISC", "W shapes", "W14x22"],
            "material_id": 1
        }
    }
}

Using the load_custom property

Key	Type	Description
`load_custom`	`string` or `[string]`	The name of a shape defined in MySections of SkyCiv Section Builder. Use an array to specify the folders of your storage.
`material_id`	`integer` (optional)	The ID of the material that will be assigned to all shapes in the section. This is optional and if it's not provided then the materials that were saved with the section will be used. `materials` are defined in their own object.

Sample code for the sections object using the load_custom property

sections-sample.json

{
    "sections": {
        "1": {
            "load_custom": ["Folder1", "Folder2", "reinforced-channel"]
        }
    }
}

Section Builder JSON format

Key	Type	Description
`version`	`float`	The version of SkyCiv Section Builder that was used to construct this object.
`name`	`string`	The name of your section. If nothing is entered, the name will default to the (rounded) height x width dimensions.
`area`	`float`	Cross-sectional area.
`Iy`	`float`	Area moment of inertia about the section y-axis.
`Iz`	`float`	Area moment of inertia about the section z-axis.
`material_id`	`integer`	The ID of the material that is assigned to the section. `materials` are defined in their own object.
`shear_area_z`	`float` (optional)	Shear Area in the section z-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. This should not be confused with the property of the same name within the `aux` object.
`shear_area_y`	`float` (optional)	Shear Area in the section y-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value. This should not be confused with the property of the same name within the `aux` object.
`aux`	`object`	The `aux` property is an object containing various section property values. It contains the geometric coordinates of the cross-section, among other properties, that are calculated via the Section Builder Platform. For brevity, these individual properties are not detailed here. To understand how to create a section via the Section Builder Platform and implement it into the API, please contact us at [email protected]

Sample code for the sections object using the Section Builder format

sections-sample.json

{
    "sections": {
        "1": {
            "version": 1,
            "name": "203 x 203",
            "area": 5894.42893,
            "Iy": 15391924.9909,
            "Iz": 45719276.66583,
            "J": 224234,
            "material_id": 1,
            "shear_area_z": 500,
            "shear_area_y": 800,
            "aux": {
                "composite": false,
                "Qz": 249151.30616,
                "Qy": 115057.81814,
                "centroid_point": [101.6, 101.6],
                "centroid_length": [101.6, 101.6],
                "depth": 203.2,
                "width": 203.2,
                "alpha": 0,
                "shear_area_z": 1380.153833546,
                "shear_area_y": 3889.4548957763,
                "torsion_radius": 16.5124
            }
        }
    }
}

Custom Input JSON format

Key	Type	Description
`name`	`string`	The name of your section. If nothing is entered, the name will default to the (rounded) height x width dimensions.
`material_id`	`integer`	The ID of the material that is assigned to the section. `materials` are defined in their own object.
`shear_area_z`	`float` (optional)	Shear Area in the section z-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value.
`shear_area_y`	`float` (optional)	Shear Area in the section y-axis. To model Euler-Bernoulli beams (i.e. to ignore shear deformation - recommended), leave this value as Empty or Zero. To model Timoshenko Beams (i.e. to include the effect of shear deformation), specify a value.
`area`	`float`	Cross-sectional area.
`Iy`	`float`	Area moment of inertia about the section y-axis.
`Iz`	`float`	Area moment of inertia about the section z-axis.
`J`	`float`	Torsion constant.

Sample code for the sections object using the Custom Input option The following JSON snippet shows both methods of specifying the section data:

sections-sample.json

{
    "sections": {
        "1": {
            "name": "CustomInputSection",
            "area": 6500,
            "Iy": 16000000,
            "Iz": 50000000,
            "J": 250000,
            "material_id": 3,
            "shear_area_z": 500,
            "shear_area_y": 800
        }
    }
}

Load a template shape.

Key	Type	Description
`info`	`object`	The shape information, see samples below.
`material_id`	`integer`	The ID of the material that is assigned to the section. `materials` are defined in their own object.

Sample code for the sections object using template shapes.

sections-sample.json

{
    "sections": {
        "1": {
            "material_id": 3,
            "info": {
                "shape": "lipped channel box",
                "dimensions": {
                    "h": 150,
                    "b": 100,
                    "b2": 90,
                    "t": 4,
                    "d": 40,
                    "r": 6
                }
            }
        }
    }
}

info-objects.json

{
    "shape": "rectangle",
    "dimensions": {
        "h": , // depth
        "b": , // width
    }
}

{
    "shape": "hollow rectangle",
    "dimensions": {
        "h": , // depth
        "b": , // width
        "t": , // thickness
        "r": , // radius
    }
}

{
    "shape": "circle",
    "dimensions": {
        "D": , // depth
    }
}

{
    "shape": "hollow circle",
    "dimensions": {
        "D": , // depth
        "t": , // thickness
    }
}

{
    "shape": "ibeam" "ishape" "i",
    "dimensions": {
        "TFw" //Top Width
        "TFt" //Top Thickness
        "BFw" //Bottom Width
        "BFt" //Bottom Thickness
        "h" //Total Height
        "Wt" //Web Thickness
        "r" //Radius
    }
}

{
    "shape": "tbeam" "teeshape" "tshape" "tee" "t",
    "dimensions": {
        "TFw" //Top Width
        "TFt" //Top Thickness
        "h" //Total Height
        "Wt" //Web Thickness
        "r" //Radius
    }
}

{
    "shape": "lbeam" "angle" "l",
    "dimensions": {
        "BFw" //Bottom Width
        "BFt" //Bottom Thickness
        "h" //Total Height
        "LFt" //Left Thickness
        "r" //Radius
    }
}

{
    "shape": "channel" "c",
    "dimensions": {
        "h" //Total height
        "TFw" //Top width full
        "TFt" //Top thickness
        "BFw" //Bottom Width full
        "BFt" //Bottom Thickness
        "Wt" //Web thickness
        "r" //Radius
    }
}

{
    "shape": "lipped channel",
    "dimensions": {
        "h" //Total height
        "TFw" //Top width full
        "TFt"  //Top thickness
        "BFw" //Bottom Width full
        "BFt" //Bottom Thickness
        "Wt" //Web thickness
        "d" //Lip depth
        "r" //Radius
    }
}

{
    "shape": "zshape" "z" "zsection",
    "dimensions": {
        "h" //Total height
        "TFw" //Top width full
        "BFw" //Bottom Width full
        "t" //Web thickness
        "r" //Radius
    }
}

{
    "shape": "lipped zshape" "lipped z" "zsectionLipped",
    "dimensions": {
        "h" //Total height
        "TFw" //Top width full
        "BFw" //Bottom Width full
        "t" //Web thickness
        "gamma" // Lip Bend Angle
        "d" // Lip Length
        "r" //Radius
    }
}

{
    "shape": "lipped angle",
    "dimensions": {
        "h" //Total height
        "BFw" //Bottom Width full
        "t" //Thickness
        "d" //Lip depth
        "r" //Radius
    }
}

{
    "shape": "lipped channel box",
    "dimensions": {
        "h", // Height/depth
        "b2", //Width 2
        "b", // Width,
        "t", // Thickness
        "d", // Lip depth
        "r", // Radius
    }
}

`materials`#

Individual materials are stored in the materials object. Each material is defined by an object. The object key is the ID of the material, and should be a unique positive integer.

Key	Type	Accepts	Description
`name`	`string`	Any string	The name of the material
`density`	`float`	A normal number	The density of the material.
`elasticity_modulus`	`float`	A normal number	The Modulus of Elasticity (or Young's Modulus) of the material.
`poissons_ratio`	`float`	A normal number	The Poisson's Ratio for the material.
`yield_strength`	`float`	A normal number	The Yield strength of the material.
`ultimate_strength`	`float`	A normal number	The Ultimate strength the material.
`class`	`string`	`steel`, `aluminium`, `masonry`, `concrete`, `wood`, `other`	The type of material.

Sample code for the `materials` object#

The following JSON snippet adds several materials, to the model using the metric system.

materials-sample.json

{
    "materials": {
        "1": {
            "name": "Structural Steel",
            "density": 7850,
            "elasticity_modulus": 200000,
            "poissons_ratio": 0.27,
            "yield_strength": 260,
            "ultimate_strength": 410,
            "class": "steel"
        },
        "2": {
            "name": "Aluminium",
            "density": 2700,
            "elasticity_modulus": 69000,
            "poissons_ratio": 0.32,
            "yield_strength": 100,
            "ultimate_strength": 150,
            "class": "aluminium"
        },
        "3": {
            "name": "Carbon Fibre Reinforced Plastic",
            "density": 3500,
            "elasticity_modulus": 150000,
            "poissons_ratio": 0.2,
            "yield_strength": null,
            "ultimate_strength": 2705,
            "class": "other"
        },
        "4": {
            "name": "Concrete",
            "density": 2500,
            "elasticity_modulus": 17000,
            "poissons_ratio": 0.2,
            "yield_strength": null,
            "ultimate_strength": 3.5,
            "class": "concrete"
        },
        "5": {
            "name": "Concrete High Strength",
            "density": 2500,
            "elasticity_modulus": 30000,
            "poissons_ratio": 0.2,
            "yield_strength": null,
            "ultimate_strength": 5,
            "class": "concrete"
        },
        "6": {
            "name": "Oakwood",
            "density": 900,
            "elasticity_modulus": 11000,
            "poissons_ratio": 0.3,
            "yield_strength": 4.5,
            "ultimate_strength": 5,
            "class": "wood"
        },
        "7": {
            "name": "Glass",
            "density": 2500,
            "elasticity_modulus": 70000,
            "poissons_ratio": 0.24,
            "yield_strength": null,
            "ultimate_strength": 33,
            "class": "other"
        }
    }
}

`supports`#

Individual supports are stored in the supports object. Each support is defined by an object. The object key is the ID of the support, and should be a unique positive integer.

Key	Type	Description
`node`	`integer`	The ID of the node at which the support is located.
`restraint_code`	`string`	A 6 character restraint code.
`tx`	`float`	Spring stiffness for translation in the x-axis. Applies only if the restraint code character for translation in x = `S`.
`ty`	`float`	Spring stiffness for translation in the y-axis. Applies only if the restraint code character for translation in y = `S`.
`tz`	`float`	Spring stiffness for translation in the z-axis. Applies only if the restraint code character for translation in z= `S`.
`rx`	`float`	Spring stiffness for rotation about the x-axis. Applies only if the restraint code character for rotation about x = `S`.
`ry`	`float`	Spring stiffness for rotation about the y-axis. Applies only if the restraint code character for rotation about y = `S`.
`rz`	`float`	Spring stiffness for rotation about the z-axis. Applies only if the restraint code character for rotation about z = `S`.

Sample code for the `supports` object#

The following JSON snippet creates two supports: the first is fully fixed, the second is released in all rotational degrees of freedom, and has a spring in the translational y-direction.

supports-sample.json

{
    "supports": {
        "1": {
            // Add a fully fixed support
            "node": 1,
            "restraint_code": "FFFFFF",
            "tx": 0,
            "ty": 0,
            "tz": 0,
            "rx": 0,
            "ry": 0,
            "rz": 0
        },
        "2": {
            // Add a support with a spring for translation in y, and released rotationally
            "node": 2,
            "restraint_code": "FSFRRR",
            "tx": 0,
            "ty": 0.1,
            "tz": 0,
            "rx": 0,
            "ry": 0,
            "rz": 0
        }
    }
}

`settlements`#

Settlement loads may be applied using the settlements object. Each settlement is defined by an object with properties within the settlements object. Individual settlements should be identified by a unique positive integer.

Key	Type	Description
`node`	`integer`	The node ID of the node to which the settlement is applied.
`tx`	`float`	Settlement displacement in the global x-axis.
`ty`	`float`	Settlement displacement in the global y-axis.
`tz`	`float`	Settlement displacement in the global z-axis.
`rx`	`float`	Settlement rotation about the global x-axis.
`ry`	`float`	Settlement rotation about the global y-axis.
`rz`	`float`	Settlement rotation about the global z-axis.

Sample code for the `settlements` object#

The following JSON snippet shows a settlement load applied to node 1, in the global translational x & y-directions, and about the global y-axis:

settlements-sample.json

{
    "settlements": {
        "1": {
            "node": 1,
            "tx": 5,
            "ty": -0.1,
            "tz": 0,
            "rx": 0,
            "ry": -0.174533,
            "rz": 0
        }
    }
}

`point_loads`#

Individual point loads are stored in the point_loads object. Each point load is defined by an object. The object key is the ID of the point load and should be a unique positive integer. Point loads may be applied to nodes, or at a position along a member, determined by the type property.

Key	Type	Accepts	Description
`type`	`string`	`n`, `m`	The type of object to which the load is applied. node, member
`node`	`integer`	A normal number	Include the property `node` only when applying the point load to a node. The value should be the node ID.
`member`	`integer`	A normal number	Include the property `member` only when applying the point load to a member. The value should be the member ID.
`position`	`float`	`0`-`100`	Include the property `position` only when applying the point load to a member. The value is the position of the point load along the member, from the start node of the member. It is defined as a percentage and therefore has an acceptable value of 0 to 100.
`x_mag`	`float`	Any number.	The magnitude of the point load along the x-axis.
`y_mag`	`float`	Any number.	The magnitude of the point load along the y-axis.
`z_mag`	`float`	Any number.	The magnitude of the point load along the z-axis.
`load_group`	`string`	A string.	The load group to which the point load will be grouped.

Sample code for the `point_loads` object#

The following JSON snippet will add two point loads to the S3D model, a nodal point load, and a member point load midway along the member:

point_loads-sample.json

{
    "point_loads": {
        "1": {
            "type": "n",
            "node": 2,
            "x_mag": 0,
            "y_mag": -1,
            "z_mag": 0,
            "load_group": "DL"
        },
        "2": {
            "type": "m",
            "member": 1,
            "position": 50,
            "x_mag": 0,
            "y_mag": -2,
            "z_mag": 0,
            "load_group": "LL"
        }
    }
}

`moments`#

Individual moments (moment loads) are stored in the moments object. Each moment is defined by an object. The object key is the ID of the moment and should be a unique positive integer. Moments may be applied to nodes, or at a position along a member, determined by the property type.

Key	Type	Accepts	Description
`type`	`string`	`n`, `m`	The type of object to which the load is applied. node, member
`node`	`integer`	A normal number	Include the property `node` only when applying the moment to a node. The value should be the node ID.
`member`	`integer`	A normal number	Include the property `member` only when applying the moment to a member. The value should be the member ID.
`position`	`float`	`0`-`100`	Include the property `position` only when applying the moment to a member. The value is the position of the moment along the member, from the start node of the member. It is defined as a percentage and therefore has an acceptable value of 0 to 100.
`x_mag`	`float`	Any number.	The magnitude of the moment about the x-axis. Positive = counter-clockwise, negative = clockwise.
`y_mag`	`float`	Any number.	The magnitude of the moment about the y-axis. Positive = counter-clockwise, negative = clockwise.
`z_mag`	`float`	Any number.	The magnitude of the moment about the z-axis. Positive = counter-clockwise, negative = clockwise.
`load_group`	`string`	A string.	The load group to which the moment will be grouped.

Sample code for the `moments` object#

The following JSON snippet will add two moments to the S3D model, a nodal moment, and a point moment midway along a member:

moments-sample.json

{
    "moments": {
        "1": {
            "type": "n",
            "node": 2,
            "x_mag": 0,
            "y_mag": -1,
            "z_mag": 0,
            "load_group": "DL"
        },
        "2": {
            "type": "m",
            "member": 1,
            "position": 50,
            "x_mag": 0,
            "y_mag": -2,
            "z_mag": 0,
            "load_group": "LL"
        }
    }
}

`distributed_loads`#

Individual distributed loads are stored in the distributed_loads object. Each distributed load is defined by an object. The object key is the ID of the distributed load, and should be a unique positive integer.

Key	Type	Accepts	Description
`member`	`integer`	A normal number	The member to which the distributed load will be applied. Identified by the member ID.
`x_mag_A`	`float`	Any number.	Magnitude of load in the x-direction at the starting position A.
`y_mag_A`	`float`	Any number.	Magnitude of load in the y-direction at the starting position A.
`z_mag_A`	`float`	Any number.	Magnitude of load in the z-direction at the starting position A.
`x_mag_B`	`float`	Any number.	Magnitude of load in the x-direction at the finish position B.
`y_mag_B`	`float`	Any number.	Magnitude of load in the y-direction at the finish position B.
`z_mag_B`	`float`	Any number.	Magnitude of load in the z-direction at the finish position B.
`position_A`	`float`	A normal number.	Position along member where the distributed load starts. Expressed as a percentage.
`position_B`	`float`	A normal number.	Position along member where the distributed load ends. Expressed as a percentage.
`load_group`	`string`	A string.	The load group to which the load belongs.
`axes`	`string`	`global`, `global_projected`, `local`	The axes in which the distributed load will be applied.

Sample code for the `distributed_loads` object#

The following JSON snippet shows a trapezoidal load in the global y-axis, applied to the middle 80% of member 9:

distributed_loads-sample.json

{
    "distributed_loads": {
        "1": {
            "member": 9,
            "x_mag_A": 0,
            "y_mag_A": -5,
            "z_mag_A": 0,
            "x_mag_B": 0,
            "y_mag_B": -30,
            "z_mag_B": 0,
            "position_A": 10,
            "position_B": 90,
            "load_group": "DL",
            "axes": "global"
        }
    }
}

`pressures`#

Pressures are uniform loads applied to plates. Each pressure is an object contained within the pressures object, and should be identified by a unique positive integer.

Key	Type	Accepts	Description
`plate_id`	`integer`	A normal number	The plate to which the pressure is applied. Identified by the plate ID.
`axes`	`string`	`global`, `global_projected`, `local`	The axes in which the pressure load will be applied.
`x_mag`	`float`	Any number.	The magnitude of the pressure in the x-direction of the specified axes, in the units of the `pressure` property of the `units` object.
`y_mag`	`float`	Any number.	The magnitude of the pressure in the y-direction of the specified axes, in the units of the `pressure` property of the `units` object.
`z_mag`	`float`	Any number.	The magnitude of the pressure in the z-direction of the specified axes, in the units of the `pressure` property of the `units` object.
`load_group`	`string`	A string.	The group to which this load belongs.

Sample code for the `pressures` object#

The following JSON snippet shows a pressure in the global y-axis, applied to plate 1:

pressures-sample.json

{
    "pressures": {
        "1": {
            "plate_id": 1,
            "axes": "global",
            "x_mag": 0,
            "y_mag": -20,
            "z_mag": 0,
            "load_group": "LL"
        }
    }
}

`area_loads`#

Area Loads are uniform loads applied to an area, that are distributed to the members surrounding that area. Each Area Load is an object contained with the area_loads object, and should be identified by a unique positive integer.

Key	Type	Accepts	Description
`type`	`string`	`one_way`, `two_way`, `column_wind_load`, `open_structure`, `non_rectangular`	How the area load should distribute the load.
`nodes`	`[integer]`	An array of integers.	The IDs of the nodes which define the area for loading. Specify 3 or 4 values, in sequential order (clockwise or counterclockwise direction).
`members`	`[integer]`	An array of integers.	The IDs of the members which create a closed space for `non_rectangular` type only..
`mag`	`float`	Any number.	The magnitude of the load, in the units of pressure.
`direction`	`string`	`X`, `X_projected`, `Y`, `Y_projected`, `Z`, `Z_projected`	The direction of the load in the global or local axes.
`elevations`	`string`	A comma separated string of values.	Relevant only if `"type": "column_wind_load"`. The elevations between which the corresponding pressure magnitudes (see next row in this table) should be applied. This property should have 1 more value than the corresponding pressure magnitudes property.
`mags`	`string`	A comma separated string of values.	Relevant only if `"type": "column_wind_load"`. The magnitudes of pressures which should be applied between the corresponding elevations (see above row in this table). This property should have 1 less value than the corresponding elevations property.
`column_direction`	`string`	A comma separated string of 2 integers.	Relevant only if `"type": "one_way"` or `"type": "column_wind_load"`. The span direction of the applied area load. The values must be the IDs of 2 nodes which are in the `nodes` property.
`loaded_members_axis`	`string`	`all`, `major`	Relevant only if `"type": "open_structure"`. Whether to apply the open structure load to all members attaching to the nodes (indicated by `all`), or to only those members which lie along the global XYZ axes (indicated by `major`).
`LG`	`string`	Any string.	The load group to which this area load belongs.

Sample code for the `area_loads` object#

The following JSON snippet shows each type of Area Load, applied to the same nodes, 1, 2, 3 & 4:

area_loads-sample.json

{
    "area_loads": {
        "1": {
            "type": "one_way",
            "nodes": [1, 2, 3, 4],
            "members": null,
            "mag": 10,
            "direction": "X",
            "elevations": null,
            "mags": null,
            // Loads will span parallel to the direction from node 1 to node 2
            "column_direction": "1,2",
            "loaded_members_axis": null,
            "LG": "LG"
        },
        "2": {
            "type": "two_way",
            "nodes": [1, 2, 3, 4],
            "members": null,
            "mag": 10,
            "direction": "X",
            "elevations": null,
            "mags": null,
            "column_direction": null,
            "loaded_members_axis": null,
            "LG": "LG"
        },
        "3": {
            "type": "column_wind_load",
            "nodes": [1, 2, 3, 4],
            "members": null,
            "mag": null,
            "direction": null,
            // Pressure 1 (5 kPa) will apply from 0 to 1.5 m, Pressure 2 (10 kPa) will apply from 1.5 to 3 m
            "elevations": "0,1.5,3",
            "mags": "5,10",
            // Loads will span parallel to the direction from node 1 to node 2
            "column_direction": "1,2",
            "loaded_members_axis": null,
            "LG": "LG"
        },
        "4": {
            "type": "open_structure",
            "nodes": [1, 2, 3, 4],
            "members": null,
            "mag": 10,
            "direction": "Y",
            "elevations": null,
            "mags": null,
            "column_direction": null,
            "loaded_members_axis": "all",
            "LG": "LG"
        },
        "5": {
                "type": "non_rectangular",
                "members": "3,7,8,9,16,17,18,19,20", //closed space of members
                "mag": -1,
                "direction": "Y",
                "LG": "LG"
        },
    }
}

`self_weight`#

The self-weight for the whole model in S3D can be toggled on or off using the self_weight object.

It is also possible to apply a gravity multiplier in the global x, y or z axes.

Key	Type	Accepts	Description
`enabled`	`boolean`	`true`, `false`	If the self-weight is applied to the model or not.
`x`	`float`	Any number.	Acceleration due to gravity in the x-axis, defined as a multiplier of the gravitational constant g.
`y`	`float`	Any number.	Acceleration due to gravity in the y-axis, defined as a multiplier of the gravitational constant g.
`z`	`float`	Any number.	Acceleration due to gravity in the z-axis, defined as a multiplier of the gravitational constant g.

Sample code for the `self_weight` object#

The following JSON snippet enables the self-weight, and indicates that gravity should act in the negative y-axis, with g = 1 × g:

self_weight-sample.json

  "self_weight": {
    "enabled": true,
    "x": 0,
    "y": -1,
    "z": 0
  }

`load_combinations`#

Each object in the load_combinations array represents an individual combination. For a single combination, a property for each load group is included. This property comprises the load group name and the load factor for that load group. The load factor is the multiplier applied to all forces and moments within the load group.

Key	Type	Description
`name`	`string`	Load Combination Name
`criteria`	`string`	Optional criteria that are used in design modules. Options are `strength`, `serviceability` or `other`
`SW`	`float`	Load factor for the Self Weight (SW) load group.
`LG1`	`float`	Load factor for (e.g.) the LG1 load group.
`LG2`	`float`	Load factor for (e.g.) the LG2 load group.

Sample code for the `load_combinations` object#

The following JSON snippet shows the creation of two load combinations. The first load combination contains 3 load groups, all with a factor of 1. The second load combination contains 2 load groups, the self-weight has a load factor of 1, and LG1 has a load factor of 1.5.

load_combinations-sample.json

    "load_combinations": {
        "1": {
          "name": "ULS: 1. 1.4D",
          "criteria": "strength",
          "Dead (Panel load)": 1.4,
          "Snow": 0,
          "SW1": 1.4,
          "Wind downforce": 0,
          "Wind uplift": 0
        },
        "2": {
          "name": "ULS: 2. 1.2D + 1.6L + 0.5(S or Lr or R)",
          "criteria": "strength",
          "Dead (Panel load)": 1.2,
          "Snow": 0.5,
          "SW1": 1.2,
          "Wind downforce": 0,
          "Wind uplift": 0
        },

`groups`#

Specify similar elements (members, plates, supports) in groups to neatly organise your structure, using the groups object:

Key	Type	Accepts	Description
`name`	`string`	Any String	Give your group a name.
`ids`	`array`	Array of element IDs	Array of integers (element IDs) to include in this group
`type`	`string`	`elements`, `nodes`, `supports`, `plates`, `groups`	What is the group comprised of?

Sample code for the `group` object#

group-sample.json

    "groups": {
        "1": {
            "name": "Some Group of Members",
            "ids": [
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                9
            ],
            "type": "elements"
        },
        "2": {
            "name": "Some Group of Plates",
            "ids": [
                5,
                8,
                9
            ],
            "type": "plates"
        }
    }

Restraint code#

The restraint code is a string made of 6 characters that describes how the member is connected to a node. The first three characters represent translational degrees of freedom in the local X, Y, and Z axes. The last 3 characters represent rotational degrees of freedom about the local X, Y, and Z axes.

F = Fixed, R = Released and S = Spring.

Example: "fixity_A": "FFFFFR" denotes a connection that has fixed translation, fixed rotation about the local X and Y axes, and rotationally released about the z-axis.

How can I test my Structural JSON file?#

There are a few simple and quick ways to test the file you have built:

Import - JSON from the SkyCiv Structural 3D Interface
Via the API - run S3D.file.save and visit the URL in the response. After that, you can simply re-run the API then refresh web browser to update your model

Other Sample files:#

Simple Beam (Imperial): skyciv-sample-1

AISC 3D Frame (exported from S3D): skyciv-sample-2

2,000 Member Structure: skyciv-sample-3

450 Member Structure with 32 Load Combos: skyciv-sample-4

Try s3d_model

note

tip

s3d_model#

settings#

units#

important

Sample code for the settings object#

Default units#

nodes#

note

Sample code for the nodes object#

members#

note

Sample code for the members object#

plates#

note

Sample code for the plates object#

meshed_plates#

Sample code for the meshed_plates object#

sections#

note

materials#

Sample code for the materials object#

supports#

Sample code for the supports object#

settlements#

Sample code for the settlements object#

point_loads#

Sample code for the point_loads object#

moments#

Sample code for the moments object#

distributed_loads#

Sample code for the distributed_loads object#

pressures#

Sample code for the pressures object#

area_loads#

Sample code for the area_loads object#

self_weight#

Sample code for the self_weight object#

load_combinations#

Sample code for the load_combinations object#

groups#

Sample code for the group object#

Restraint code#

How can I test my Structural JSON file?#

Other Sample files:#

`s3d_model`#

`settings`#

`units`#

Sample code for the `settings` object#

`nodes`#

Sample code for the `nodes` object#

`members`#

Sample code for the `members` object#

`plates`#

Sample code for the `plates` object#

`meshed_plates`#

Sample code for the `meshed_plates` object#

`sections`#

`materials`#

Sample code for the `materials` object#

`supports`#

Sample code for the `supports` object#

`settlements`#

Sample code for the `settlements` object#

`point_loads`#

Sample code for the `point_loads` object#

`moments`#

Sample code for the `moments` object#

`distributed_loads`#

Sample code for the `distributed_loads` object#

`pressures`#

Sample code for the `pressures` object#

`area_loads`#

Sample code for the `area_loads` object#

`self_weight`#

Sample code for the `self_weight` object#

`load_combinations`#

Sample code for the `load_combinations` object#

`groups`#

Sample code for the `group` object#